用 neo4j-graphrag 构建 Neo4j…

在 Neo4j 上用 neo4j-graphrag Python 包搭建或调试 GraphRAG 检索管道时使用，覆盖检索器选择、索引创建、Cypher 增强检索、LLM/Embedder 与外部向量库接入。

适用场景

解决思路

1. 按 LLM/Embedder/外部向量库安装对应 extra：`pip install neo4j-graphrag[openai]`、`[anthropic]`、`[google]`、`[bedrock]`、`[cohere]`、`[mistralai]`、`[ollama]`、`[weaviate]`、`[pinecone]`、`[qdrant]`；要求 Python >= 3.10、`neo4j >= 5.17.0`（driver 6.x 支持）。
2. 按需求选择 retriever：有 fulltext 索引用 Hybrid 变体（`HybridRetriever`/`HybridCypherRetriever`），否则用 Vector 变体（`VectorRetriever`/`VectorCypherRetriever`）；向量查找后需要图遍历用 Cypher 变体，否则用 plain；自然语言转 Cypher 用 `Text2CypherRetriever`（无需 embedder）；让 LLM 路由多个检索器用 `ToolsRetriever`；向量存外部 DB 用 `WeaviateNeo4jRetriever`/`PineconeNeo4jRetriever`/`QdrantNeo4jRetriever`。
3. 按 retriever 表选型：`VectorRetriever` 用于基线语义搜索；`HybridRetriever` 用于更好召回但无图扩展；`VectorCypherRetriever` 用于无 fulltext 的 GraphRAG；`HybridCypherRetriever` 用于生产 GraphRAG 默认选择；`Text2CypherRetriever` 用于 NL→Cypher 且无 embedder；`ToolsRetriever` 用于 LLM 路由多检索器；外部向量库 retriever 用于对应 Weaviate/Pinecone/Qdrant。
4. 创建向量索引：`CREATE VECTOR INDEX chunk_embedding IF NOT EXISTS FOR (c:Chunk) ON (c.embedding) OPTIONS { indexConfig: { 'vector.dimensions': 1536, 'vector.similarity_function': 'cosine' } };`；使用 Hybrid 时再创建 fulltext 索引：`CREATE FULLTEXT INDEX chunk_fulltext IF NOT EXISTS FOR (c:Chunk) ON EACH [c.text];`。
5. 确认索引 ONLINE：`SHOW INDEXES YIELD name, state WHERE name IN ['chunk_embedding', 'chunk_fulltext'] RETURN name, state;`，两者必须 `state = 'ONLINE'`；未 ONLINE 时等待并每 5 秒轮询，ONLINE 前不要开始导入。
6. 使用核心模式 `HybridCypherRetriever`：创建 `GraphDatabase.driver(NEO4J_URI, auth=(NEO4J_USERNAME, NEO4J_PASSWORD))`、`OpenAIEmbeddings(model='text-embedding-3-large')`、`retrieval_query`、`HybridCypherRetriever(driver=..., vector_index_name='chunk_embedding', fulltext_index_name='chunk_fulltext', retrieval_query=..., embedder=...)`、`OpenAILLM(model_name='gpt-4.1', model_params={'temperature': 0})`，用 `GraphRAG(retriever=retriever, llm=llm)` 组装；调用 `rag.search(query_text='Who does Alice work for?', retriever_config={'top_k': 5})` 后读取 `response.answer` 并 `driver.close()`。
7. 编写 `retrieval_query`：它是向量/fulltext 查找后执行的 Cypher 片段，自动注入变量 `node`（匹配节点）和 `score`（相似度浮点数）；必须包含 `RETURN` 子句，且 `score` 必须出现在 `RETURN` 中；不要重新声明 `score`。
8. 使用 `VectorCypherRetriever`：`VectorCypherRetriever(driver=driver, index_name='chunk_embedding', retrieval_query=retrieval_query, embedder=embedder)`；通过 `rag.search(query_text='What happened at Apple?', retriever_config={'top_k': 10})` 查询。
9. 使用 `Text2CypherRetriever`：传 `driver`、`llm`、`neo4j_schema=None`（None 表示自动从 DB 获取 schema，也可传裁剪后的字符串）、`examples`；v1.16.0+ 会先对 LLM 生成的 Cypher 执行 `EXPLAIN`，被归类为写/破坏性语句时抛 `Text2CypherRetrievalError` 而不执行，以防提示注入。
10. 使用 `ToolsRetriever`：`ToolsRetriever(llm=llm, retrievers=[vector_retriever, text2cypher_retriever])`，由 LLM 决定每个查询调用哪些检索器；可用 `vector_retriever.convert_to_tool()` 把任意 retriever 转成独立 Tool。
11. 使用 filters 在向量搜索前预过滤：`retriever.search(query_text='quarterly earnings', top_k=5, filters={'date': {'$gte': '2024-01-01'}, 'source': {'$eq': '10-K'}})`；支持 `$eq`、`$ne`、`$lt`、`$lte`、`$gt`、`$gte`、`$between`、`$in`、`$like`、`$ilike`。
12. 使用 `query_params` 参数化 `retrieval_query`：在 Cypher 中写 `$entity_name`；通过 `retriever.search(query_text='What happened at Apple?', top_k=10, query_params={'entity_name': 'Apple'})` 传入，或通过 `rag.search(query_text='What happened at Apple?', retriever_config={'top_k': 10, 'query_params': {'entity_name': 'Apple'}})` 传入。
13. 启用 Cypher 25 SEARCH 子句：在 v1.16.0、Neo4j 2026+ 上给 `VectorRetriever` 等设置 `use_search_clause=True`；v1.16+ 在 Neo4j 2026.01+ 上当过滤条件为 SEARCH 兼容的简单 AND 比较且所有过滤属性已在索引 `WITH [n.prop]` 列表中声明时，四个 vector/hybrid retriever 自动走 SEARCH...WHERE，否则自动回退到 `db.index.vector.queryNodes()` 过程路径并记录 warning；用 `create_vector_index()` 的 `filterable_properties=[...]` 声明可过滤属性。
14. 在 Cypher retrievers 上排序：`retriever.search(query_text='...', top_k=10, order_by='score DESC')`。
15. 自定义 prompt 模板：用 `RagTemplate(template='Answer using ONLY the context below.\nContext: {context}\nQuestion: {query_text}\nAnswer:', expected_inputs=['context', 'query_text'])`，再传 `GraphRAG(retriever=retriever, llm=llm, prompt_template=template)`。
16. 使用 `return_context` 与 `response_fallback`：`rag.search(query_text='...', retriever_config={'top_k': 5}, return_context=True, response_fallback='No relevant context.')`；`return_context=True` 时可通过 `response.retriever_result` 获取原始检索块，检索器无结果时跳过 LLM 调用。
17. 多轮消息历史：用 `InMemoryMessageHistory()` 创建 `history`，在 `rag.search(query_text='Who is Alice?', message_history=history)` 和 `rag.search(query_text='Where does she work?', message_history=history)` 中传入。
18. 接入外部 retriever：Weaviate 用 `weaviate.connect_to_local()` 和 `WeaviateNeo4jRetriever(driver=driver, client=weaviate_client, collection='Chunk', id_property_external='neo4j_id', id_property_neo4j='id', retrieval_query=retrieval_query, node_label_neo4j='Chunk')`；Pinecone 用 `Pinecone(api_key=os.environ['PINECONE_API_KEY'])` 和 `PineconeNeo4jRetriever(driver=driver, client=pc, index_name='my-index', id_property_neo4j='id', retrieval_query=retrieval_query)`；Qdrant 用 `QdrantClient(url='http://localhost:6333')` 和 `QdrantNeo4jRetriever(driver=driver, client=QdrantClient(url='http://localhost:6333'), collection_name='Chunk', id_property_external='neo4j_id', id_property_neo4j='id', id_property_getter=lambda hit: hit.payload['neo4j_id'], retrieval_query=retrieval_query)`。
19. 配置 LLM provider：所有实现 `LLMBase` 的类包括 `OpenAILLM`、`AzureOpenAILLM`、`AnthropicLLM`、`VertexAILLM`、`MistralAILLM`、`CohereLLM`、`OllamaLLM`、`BedrockLLM`，均支持同步/异步、工具调用和自动限流；按 provider 安装 extra 并实例化，如 `OpenAILLM(model_name='gpt-4.1', model_params={'temperature': 0})`、`AnthropicLLM(model_name='claude-3-5-sonnet-20241022')`、`VertexAILLM(model_name='gemini-2.0-flash')`、`OllamaLLM(model_name='llama3')`（无需 API key）、`BedrockLLM(model_id='anthropic.claude-3-5-sonnet-20241022-v2:0')`；v1.15.0+ 用 `response.usage` 查看 `LLMUsage(request_tokens=N, response_tokens=M, total_tokens=T)`；v1.16.0+ 用 `llm.close()` 或 `await llm.aclose()` 释放资源。
20. 配置 Embedder provider：所有 embedder 包括 `OpenAIEmbeddings`、`AzureOpenAIEmbeddings`、`VertexAIEmbeddings`、`MistralAIEmbeddings`、`CohereEmbeddings`、`OllamaEmbeddings`、`SentenceTransformerEmbeddings`、`BedrockEmbeddings`，自动限流并使用 tenacity 指数退避；按 provider 安装 extra 并实例化，如 `OpenAIEmbeddings(model='text-embedding-3-large')`（3072 dims）、`OpenAIEmbeddings(model='text-embedding-3-small')`（1536 dims）、`SentenceTransformerEmbeddings(model='all-MiniLM-L6-v2')`（384 dims，本地）、`BedrockEmbeddings(model_id='amazon.titan-embed-text-v2:0')`。
21. 用 Python API 建向量索引：`create_vector_index(driver, name='chunk_embedding', label='Chunk', embedding_property='embedding', dimensions=1536, similarity_fn='cosine')`，`similarity_fn` 也可用 `'euclidean'`；fulltext 索引用 Cypher 创建。
22. 检查 schema：`get_schema(driver, sample=1000)` 返回人类可读字符串，`get_structured_schema(driver, sample=1000)` 返回包含 labels/rels/props 的 dict；schema 很大时给 `Text2CypherRetriever` 传裁剪后的字符串以减少 LLM prompt 大小。
23. 按常见错误修复：包名旧用 `pip uninstall neo4j-genai && pip install neo4j-graphrag`；`retrieval_query` 返回 0 行检查 MATCH 或关系方向并用 `EXPLAIN` 和 `CALL db.schema.visualization()`；`KeyError: 'score'` 在 `retrieval_query` 的 `RETURN` 中加入 `score`；`score` 变量未找到时不要重新声明 `score`；`Text2CypherRetrievalError` 是 v1.16.0+ 的预期安全行为；异步报 `TypeError: coroutine` 用 `asyncio.run(pipeline.run_async(...))`；HybridRetriever 空结果检查 fulltext 索引是否 ONLINE；嵌入维度不匹配按正确 `dimensions=` 重建索引。
24. 按验证清单检查：安装 `neo4j-graphrag`（不是 `neo4j-genai`）且驱动 `neo4j >= 5.17.0`；向量索引在导入 embedding 或运行 retriever 前 ONLINE；使用 Hybrid 时 fulltext 索引 ONLINE；`create_vector_index` 的维度匹配 embedder 输出；`retrieval_query` 的 `RETURN` 返回 `node` 和 `score` 且不重复声明；`query_params` 通过 `rag.search()` 的 `retriever_config` 传入而不是在 retriever 构造函数传；API key 放在环境变量中不要硬编码；结束时调用 `llm.close()` 释放资源。

适用边界 · 注意事项

• 不适用于从文档构建知识图谱（KG construction），应使用 neo4j-document-import-skill。
• 不适用于纯向量/语义搜索、不带图遍历的混合搜索，或自定义 Cypher 混合搜索，应使用 neo4j-vector-index-skill。
• 不适用于 GDS 算法（PageRank、Louvain、节点嵌入）、agent 长期记忆或编写原始 Cypher 查询，应分别使用 neo4j-gds-skill、neo4j-agent-memory-skill、neo4j-cypher-skill。