在纯 Cypher 中调用 LLM 与生成向量：Neo4j…

当需要在 Cypher 查询内直接做嵌入生成、文本补全、结构化抽取、聊天、分词与批量入库，而不借助外部 Python 时使用。

适用场景

解决思路

1. 所有 ai.* 函数都必须启用 CYPHER 25：可在每条查询前加 `CYPHER 25` 前缀（自管理、无需管理员权限），或用管理员执行 `ALTER DATABASE neo4j SET DEFAULT LANGUAGE CYPHER 25` 设为库级默认。
2. 安装插件：Aura 默认启用无需操作；自管理版把插件 JAR 复制到 `plugins/` 目录；Docker 用 `--env NEO4J_PLUGINS='["genai"]'`。
3. 所有 ai.text.* 函数最后一个参数都传 `configuration :: MAP`，按 provider 提供必需键：`'openai'` 需 `token`、`model`；`'azure-openai'` 需 `token`（OAuth2 bearer）、`resource`、`model`；`'vertexai'` 需 `model`、`project`、`region`、`token` 或 `apiKey`（`publisher` 默认 `'google'`）；`'bedrock-titan'` 需 `model`、`region`、`accessKeyId`、`secretAccessKey`（仅嵌入）；`'bedrock-nova'` 需 `model`、`region`、`accessKeyId`、`secretAccessKey`（仅补全）。
4. 可选键 `vendorOptions :: MAP` 传 provider 专属参数，例如 OpenAI 的 `{ dimensions: 1024 }`。
5. API key 一律通过驱动参数以 `$param` 传入，绝不硬编码字面量。
6. 单条嵌入：`SET c.embedding = ai.text.embed(c.text, 'openai', { token: $openaiKey, model: 'text-embedding-3-small' })`，返回 `VECTOR`，可直接存储并用于向量索引；批量时用 `CALL { ... } IN TRANSACTIONS OF 500 ROWS` 包裹。
7. 批量嵌入过程：`CALL ai.text.embedBatch(resource, provider, config) YIELD index, resource, vector`，用 `resource` 回匹配节点后 `SET c.embedding = vector`。
8. 列出已配置的嵌入 provider：`CALL ai.text.embed.providers() YIELD name, requiredConfigType, optionalConfigType, defaultConfig`。
9. 文本补全：`RETURN ai.text.completion('Summarize: ' + $text, 'openai', { token: $openaiKey, model: 'gpt-4o-mini' }) AS summary`，返回 `STRING`。
10. 跨行聚合补全：`ai.text.aggregateCompletion(c.text, 'Summarize the following article chunks in 3 sentences', 'openai', {...})`，`value` 参数为每行送入 LLM 的 STRING，非字符串值会用 `toString()` 转换。
11. 纯 Cypher GraphRAG 模式：先用 `ai.text.embed($question, ...)` 生成问题向量，再用 `SEARCH chunk IN (VECTOR INDEX chunk_embedding FOR qEmbedding LIMIT 10) SCORE AS score` 做向量检索，然后图遍历（如 `shortestPath((article)-[*..3]-(other:Article))` 以发现直接邻居看不到的关系），拼接上下文后调用 `ai.text.completion()` 返回答案。
12. 结构化输出：`ai.text.structuredCompletion(prompt, schema, provider, config)` 返回 `MAP`，schema 用 JSON Schema 描述（含 `type`、`properties`、`required`、`enum`），可直接 `SET` 到节点属性或继续在 Cypher 中 `UNWIND` 使用；务必设 `additionalProperties: false` 防止幻觉键。
13. 跨行聚合结构化抽取：`ai.text.aggregateStructuredCompletion(value, instruction, schema, provider, config)`，例如根据用户订单构建购物画像。
14. 聊天：`ai.text.chat(message, chatId, provider, config)` 返回 `MAP { message: STRING, chatId: STRING }`；`chatId` 传 `null` 开启新会话，把返回的 `chatId` 存下来用于后续续聊；仅支持 `openai` 和 `azure-openai`。
15. 分词与分块：`ai.text.tokenCount(input, provider, configuration = {}) :: INTEGER` 统计 token（`'openai'` 用本地分词器不发 API 调用，`'Bedrock'`/`'VertexAI'` 走免费 API 调用）；`ai.text.chunkByTokenLimit(input, limit, model = 'gpt-4', overlap = 0) :: LIST<STRING>` 按 token 上限分块（本地 OpenAI 分词器，无需 token，按换行→空格→token 数依次切分，`limit` 应低于 provider 上限以留出 prompt 开销）；可用 `CALL ai.text.tokenCount.providers()` 列出支持该功能的 provider。
16. `ai.text.embedBatch` 支持配置键 `maxBatchSize` 限制单次 API 请求数据量：`'openai'` 和 `'azure-openai'` 默认 8192，`'vertexai'` 无默认值（遇到 token 超限错误时手动设置）。
17. 批量写入前先计数目标节点（如 `MATCH (c:Chunk) WHERE c.embedding IS NULL RETURN count(c)`），先用一个测试节点验证配置，超过 1000 节点用 `CALL { ... } IN TRANSACTIONS OF 500 ROWS`，执行前需显式确认。
18. 用新函数替换已废弃函数：`genai.vector.encode()` → `ai.text.embed()`，`genai.vector.encodeBatch()` → `CALL ai.text.embedBatch()`，`genai.vector.listEncodingProviders()` → `CALL ai.text.embed.providers()`。
19. 排查常见错误：`Unknown function 'ai.text.embed'` 说明缺 `CYPHER 25` 前缀或插件未装；`Configuration key 'token' missing` 说明配置 map 不全；embed 返回 `null` 多为模型名错误或鉴权失败，可先用 `RETURN ai.text.embed('test', 'openai', {token:$k, model:'text-embedding-3-small'})` 单独测试；`Unsupported provider` 多为大小写问题，provider 字符串必须小写。
20. 执行前逐项核对：每条 ai.text.* 查询都有 `CYPHER 25` 前缀、插件已装、API key 用 `$param`、config 中显式写 `model`、provider 字符串小写、批量写入用 `IN TRANSACTIONS OF 500 ROWS` 且先计数、已替换废弃函数、聊天会话保存 `chatId`、结构化 schema 带 `additionalProperties: false`。

适用边界 · 注意事项

• 需要 Python 版 GraphRAG 流水线（VectorCypherRetriever、HybridCypherRetriever）时，改用 neo4j-graphrag-skill。
• 需要创建向量索引、kNN 检索或 SEARCH 子句语法时，改用 neo4j-vector-index-skill。
• 需要 GDS 嵌入（FastRP、Node2Vec）或全文/关键词检索时，分别改用 neo4j-gds-skill、neo4j-cypher-skill。