用途
本技能用于在 Cypher 查询内部直接调用 Neo4j GenAI 插件的 ai.text.* 函数与过程，从而无需借助外部 Python 即可完成嵌入生成、文本补全、结构化输出、对话、分词与批处理等操作。适合希望把向量化与 LLM 调用直接嵌入数据导入、查询或 GraphRAG 流程中的场景。
主要能力
- 嵌入：使用 ai.text.embed() 生成单个向量，返回 VECTOR，可直接存储并用于向量索引；使用 CALL ai.text.embedBatch(resource, provider, config) YIELD index, resource, vector 批量嵌入节点或分块；使用 CALL ai.text.embed.providers() 列出已配置的嵌入提供方。
- 文本补全：ai.text.completion() 返回 STRING；ai.text.aggregateCompletion() 可对分组行进行汇总式补全。
- 结构化输出：ai.text.structuredCompletion() 返回 MAP，可直接写入节点属性或继续在 Cypher 中使用；ai.text.aggregateStructuredCompletion() 可跨多行进行结构化抽取。
- 对话：ai.text.chat() 支持带状态的会话，返回 MAP { message: STRING, chatId: STRING }，保存 chatId 即可继续同一会话；仅支持 openai 与 azure-openai。
- 分词与切分：ai.text.tokenCount() 返回 INTEGER；ai.text.chunkByTokenLimit(input, limit, model = 'gpt-4', overlap = 0) 返回 LIST<STRING>，按换行、空格、token 数依次切分。
- 纯 Cypher GraphRAG 模式：可在一条查询内完成“嵌入问题 → 向量检索 → 图遍历 → LLM 补全”。
使用方式
前置条件是所有 ai.* 函数要求 CYPHER 25，可通过查询前缀 CYPHER 25 或数据库级默认 ALTER DATABASE neo4j SET DEFAULT LANGUAGE CYPHER 25 启用。安装方面，Aura 默认启用 GenAI 插件；自管理环境需将插件 JAR 复制到 plugins/ 目录；Docker 使用 --env NEO4J_PLUGINS='["genai"]'。
所有 ai.text.* 函数将配置 MAP 作为最后一个参数。不同提供方所需键不同，例如 'openai' 需要 token、model；'azure-openai' 需要 token、resource、model；'vertexai' 需要 model、project、region、token 或 apiKey；'bedrock-titan' 需要 model、region、accessKeyId、secretAccessKey（仅嵌入）；'bedrock-nova' 同上但仅补全。所有提供方均可选传 vendorOptions MAP。API 密钥必须通过 driver 参数以 $param 传入，不可硬编码字面量。
批量写入前应先用 MATCH (c:Chunk) WHERE c.embedding IS NULL RETURN count(c) 统计节点数，用单个测试节点验证配置，批量超过 1000 个节点时使用 CALL { ... } IN TRANSACTIONS OF 500 ROWS，并在执行前取得明确确认。
适用场景
在数据摄取阶段批量向量化节点或分块；在 Cypher 中直接调用 LLM 完成补全或 GraphRAG；从 LLM 抽取结构化 JSON 映射；对分组行聚合生成摘要；构建带状态的对话会话；统计 token 数或按 token 上限切分文本。
限制
- 仅使用 CYPHER 25；Neo4j 版本低于 5.20 或未加载插件会报错。
- 不适合 Python 版 GraphRAG 流程（VectorCypherRetriever、HybridCypherRetriever），应改用 neo4j-graphrag-skill；向量索引创建、kNN 检索与 SEARCH 子句应改用 neo4j-vector-index-skill；GDS 嵌入（FastRP、Node2Vec）应改用 neo4j-gds-skill；全文/关键词检索应改用 neo4j-cypher-skill。
- chat 仅支持 openai 与 azure-openai，在 VertexAI 上会失败。
- 提供方字符串区分大小写且为小写，如 'openai' 而非 'OpenAI'。
- 已弃用函数：genai.vector.encode() 应替换为 ai.text.embed()；genai.vector.encodeBatch() 应替换为 CALL ai.text.embedBatch()；genai.vector.listEncodingProviders() 应替换为 CALL ai.text.embed.providers()。
- 结构化输出 schema 建议使用 additionalProperties: false 以防止产生幻觉键。
- embedBatch 支持 maxBatchSize 配置键限制单次 API 请求数据量，'openai' 与 'azure-openai' 默认为 8192，'vertexai' 无默认值。
- 部分版本特性（如 ai.text.structuredCompletion、aggregateCompletion 等）标注了引入版本号（2025.11、2025.12、2026.02、2026.03、2026.04），需对应版本支持。
- tokenCount 对 'openai' 使用本地分词器（无 API 调用），对 'Bedrock' 与 'VertexAI' 为免费 API 调用；chunkByTokenLimit 使用本地 OpenAI 分词器，无需提供方调用与 token。
其他未在资料中说明的细节暂未提供。