neo4j-genai-plugin-skill
Use Neo4j GenAI Plugin ai.text.* functions and procedures for in-Cypher
neo4j-contrib · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add neo4j-contrib/neo4j-skills --skill neo4j-genai-plugin-skill技能说明
name: neo4j-genai-plugin-skill description: Use Neo4j GenAI Plugin ai.text.* functions and procedures for in-Cypher embedding generation, text completion, structured output, chat, tokenization, and batch ingestion. Covers ai.text.embed(), ai.text.embedBatch(), ai.text.completion(), ai.text.structuredCompletion(), ai.text.aggregateCompletion(), ai.text.chat(), ai.text.tokenCount(), ai.text.chunkByTokenLimit(), and provider configuration for OpenAI, Azure OpenAI, VertexAI, and Amazon Bedrock. Requires CYPHER 25. Replaces deprecated genai.vector.encode(). Use when writing pure-Cypher GraphRAG, embedding nodes in-graph, generating structured maps from prompts, or calling LLMs inside Cypher queries. Does NOT handle neo4j-graphrag Python library pipelines — use neo4j-graphrag-skill. Does NOT handle vector index creation/search — use neo4j-vector-index-skill. version: 1.0.7 status: active allowed-tools: Bash WebFetch
When to Use
- Generating embeddings inside Cypher without external Python (
ai.text.embed()) - Batch-embedding nodes/chunks during ingestion (
ai.text.embedBatch()) - Calling LLMs directly in Cypher for completions or GraphRAG (
ai.text.completion()) - Extracting structured JSON maps from LLM inside Cypher (
ai.text.structuredCompletion()) - Aggregating LLM summaries over grouped rows (
ai.text.aggregateCompletion()) - Stateful chat sessions in Cypher (
ai.text.chat()) - Counting tokens or chunking text by token limit (
ai.text.tokenCount(),ai.text.chunkByTokenLimit())
When NOT to Use
- Python-based GraphRAG pipelines (VectorCypherRetriever, HybridCypherRetriever) →
neo4j-graphrag-skill - Vector index CREATE / kNN search / SEARCH clause →
neo4j-vector-index-skill - GDS embeddings (FastRP, Node2Vec) →
neo4j-gds-skill - Fulltext / keyword search →
neo4j-cypher-skill
Prerequisites
CYPHER 25 required for all ai.* functions. Two ways to enable:
// Per-query prefix (self-managed, no admin rights needed):
CYPHER 25 MATCH (n:Chunk) ...
// Per-database default (admin; applies to all sessions):
ALTER DATABASE neo4j SET DEFAULT LANGUAGE CYPHER 25
Installation:
- Aura: GenAI plugin enabled by default — no action needed
- Self-managed JAR: copy plugin JAR to
plugins/directory - Docker:
--env NEO4J_PLUGINS='["genai"]'
Provider Config Quick Reference
All ai.text.* functions accept a configuration :: MAP as last argument.
| Provider string | Required keys | Notes |
|---|---|---|
'openai' | token, model | token = OpenAI API key |
'azure-openai' | token, resource, model | token = OAuth2 bearer; resource = Azure resource name |
'vertexai' | model, project, region, token or apiKey | publisher defaults to 'google' |
'bedrock-titan' | model, region, accessKeyId, secretAccessKey | Embedding only |
'bedrock-nova' | model, region, accessKeyId, secretAccessKey | Completion only |
Optional for all: vendorOptions :: MAP passes provider-specific extras (e.g. { dimensions: 1024 } for OpenAI).
❌ Never hardcode API key literals. ✅ Always use $param passed via driver parameters dict.
Full provider config table → references/providers.md
Embedding
Single embed [2025.11]
CYPHER 25
MATCH (c:Chunk)
WHERE c.embedding IS NULL
WITH c
CALL {
WITH c
SET c.embedding = ai.text.embed(c.text, 'openai', {
token: $openaiKey,
model: 'text-embedding-3-small'
})
} IN TRANSACTIONS OF 500 ROWS
ai.text.embed() returns VECTOR — directly storable and queryable in a vector index.
Batch embed procedure [2025.11]
CYPHER 25
MATCH (c:Chunk) WHERE c.embedding IS NULL
WITH collect(c) AS chunks
UNWIND chunks AS c
WITH c.text AS text, c AS node
CALL ai.text.embedBatch(text, 'openai', { token: $openaiKey, model: 'text-embedding-3-small' })
YIELD index, resource, vector
MATCH (c:Chunk {text: resource})
SET c.embedding = vector
Procedure signature: CALL ai.text.embedBatch(resource, provider, config) YIELD index, resource, vector
List configured embed providers
CYPHER 25
CALL ai.text.embed.providers()
YIELD name, requiredConfigType, optionalConfigType, defaultConfig
RETURN name, requiredConfigType
Text Completion [2025.11]
CYPHER 25
RETURN ai.text.completion(
'Summarize: ' + $text,
'openai',
{ token: $openaiKey, model: 'gpt-4o-mini' }
) AS summary
Returns STRING.
Aggregate completion — summarize across rows [2026.03]
CYPHER 25
MATCH (c:Chunk)-[:PART_OF]->(a:Article {id: $articleId})
RETURN ai.text.aggregateCompletion(
c.text,
'Summarize the following article chunks in 3 sentences',
'openai',
{ token: $openaiKey, model: 'gpt-4o-mini' }
) AS summary
value parameter = each row's STRING fed to the LLM. Uses toString() for non-string values.
Pure-Cypher GraphRAG Pattern
Embed question → vector search → graph traverse → LLM completion — all in one Cypher query:
CYPHER 25
WITH ai.text.embed($question, 'openai', { token: $openaiKey, model: 'text-embedding-3-small' }) AS qEmbedding
MATCH (chunk:Chunk)
SEARCH chunk IN (VECTOR INDEX chunk_embedding FOR qEmbedding LIMIT 10) SCORE AS score
// SEARCH preferred on 2026.x; db.index.vector.queryNodes() deprecated 2026.04 — SEARCH syntax → neo4j-vector-index-skill
MATCH (chunk)<-[:HAS_CHUNK]-(article:Article)
OPTIONAL MATCH path = shortestPath((article)-[*..3]-(other:Article))
WITH chunk, article, collect(DISTINCT other.title) AS related, score
ORDER BY score DESC LIMIT 5
WITH collect(chunk.text + '\n[Source: ' + article.title + ']') AS context, $question AS question
RETURN ai.text.completion(
'Answer based on context:\n' + reduce(s='', c IN context | s + c + '\n') + '\nQuestion: ' + question,
'openai',
{ token: $openaiKey, model: 'gpt-4o-mini' }
) AS answer
Key insight (Bergman): shortest path
阅读完整来源 ↗