Python 的 GraphRAG¶
此软件包包含 Neo4j 官方的 Python GraphRAG 功能。
此软件包的目的是为开发者提供第一方（官方）包，Neo4j 能保证长期承诺和维护，并且能够快速发布新功能以及高性能的模式和方法。
⚠️ 此软件包是 neo4j-genai 更名后的延续。neo4j-genai 已被弃用，且不再维护。我们鼓励所有用户迁移到此新软件包以继续获取更新和支持。
支持的 Neo4j 版本
Neo4j >=5.18.1
Neo4j Aura >=5.18.0
支持的 Python 版本
Python 3.14
Python 3.13
Python 3.12
Python 3.11
Python 3.10
主题¶
使用方法¶
安装¶
此软件包需要 Python（>=3.10）。
要安装最新的稳定版本，使用
pip install neo4j-graphrag
注意
始终建议在虚拟环境中为用户空间安装 Python 包。
可选依赖¶
可以使用以下方式安装额外依赖
pip install "neo4j-graphrag[openai]"
额外依赖列表
- LLM 提供商（RAG 和 KG Builder 流程至少需要一种）
ollama: 来自 Ollama 的 LLM
openai: 来自 OpenAI 的 LLM（包括 AzureOpenAI）
google: 来自 Vertex AI 的 LLM
cohere: 来自 Cohere 的 LLM
anthropic: 来自 Anthropic 的 LLM
mistralai: 来自 MistralAI 的 LLM
sentence-transformers：用于使用 sentence-transformers Python 包中的嵌入
- 向量数据库（用于使用 外部检索器）
weaviate: 在 Weaviate 中存储向量
pinecone: 在 Pinecone 中存储向量
qdrant: 在 Qdrant 中存储向量
experimental: 实验性功能，主要来自知识图谱创建流水线。
nlp：安装 spaCy 用于 NLP 流程，供知识图谱创建流水线中的 SpaCySemanticMatchResolver 组件使用。
fuzzy-matching：安装 rapidfuzz 用于基于字符串相似度的模糊匹配，供知识图谱创建流水线中的 FuzzyMatchResolver 组件使用。
注意
由于上游 spaCy 导入时出现问题（见 spaCy #13895），`nlp` 额外依赖（spaCy）目前在 Python 3.14 上不受支持。在该问题解决之前，请使用 Python 3.13 或更早版本以使用基于 spaCy 的功能。
示例¶
创建向量索引¶
创建向量索引时，请确保索引的维度数与嵌入的维度数一致。
详见 API 文档。
from neo4j import GraphDatabase
from neo4j_graphrag.indexes import create_vector_index
URI = "neo4j://:7687"
AUTH = ("neo4j", "password")
INDEX_NAME = "vector-index-name"
# Connect to Neo4j database
driver = GraphDatabase.driver(URI, auth=AUTH)
# Creating the index
create_vector_index(
driver,
INDEX_NAME,
label="Document",
embedding_property="vectorProperty",
dimensions=1536,
similarity_fn="euclidean",
)
注意
假设 Neo4j 正在运行
填充 Neo4j 向量索引¶
请注意，以下示例并非向 Neo4j 数据库进行 upsert 的唯一方式。例如，您也可以使用 Neo4j Python 驱动。
from neo4j import GraphDatabase
from neo4j_graphrag.indexes import upsert_vectors
from neo4j_graphrag.types import EntityType
URI = "neo4j://:7687"
AUTH = ("neo4j", "password")
# Connect to Neo4j database
driver = GraphDatabase.driver(URI, auth=AUTH)
# Upsert the vector
vector = ...
upsert_vectors(
driver,
ids=["1234"],
embedding_property="vectorProperty",
embeddings=[vector],
entity_type=EntityType.NODE,
)
注意
假设 Neo4j 已运行且已定义向量索引
执行相似性搜索¶
虽然库中有比此处展示的更多检索器，以下示例足以帮助您入门。
from neo4j import GraphDatabase
from neo4j_graphrag.embeddings.openai import OpenAIEmbeddings
from neo4j_graphrag.retrievers import VectorRetriever
URI = "neo4j://:7687"
AUTH = ("neo4j", "password")
INDEX_NAME = "vector-index-name"
# Connect to Neo4j database
driver = GraphDatabase.driver(URI, auth=AUTH)
# Create Embedder object
# Note: An OPENAI_API_KEY environment variable is required here
embedder = OpenAIEmbeddings(model="text-embedding-3-large")
# Initialize the retriever
retriever = VectorRetriever(driver, INDEX_NAME, embedder)
# Run the similarity search
query_text = "How do I do similarity search in Neo4j?"
response = retriever.search(query_text=query_text, top_k=5)
注意
假设 Neo4j 正在运行且已填充向量索引。
限制¶
对向量索引的查询是一次近似最近邻搜索，可能不会得到精确结果。请参阅此文档了解更多细节。
开发¶
安装依赖¶
uv sync --all-extras
入门¶
问题¶
如果您有 bug 要报告或功能请求，请先 搜索是否已有相同问题。如果不存在相关问题，请使用相应的 问题表单创建新问题。
如果您是 Neo4j Enterprise 客户，也可以联系 客户支持。
如果您没有 bug 或功能请求，但需要库的帮助；社区支持可通过 Neo4j 在线社区 和/或 Discord 获得。
进行更改¶
Fork（派生）此仓库。
安装 Python 和 uv。
从 main 创建工作分支并开始您的更改！
拉取请求¶
完成更改后，创建一个拉取请求（PR）。
确保您已 签署 CLA。
确保 PR 的 base 设为 main。
若在解决问题，请不要忘记 将 PR 链接到相应问题。
勾选 允许维护者编辑 复选框，以便维护者对您的分支进行必要的调整并合并。
审阅者可能会要求在 PR 合并前进行更改，您可以使用 建议的更改或普通的 PR 评论。您可以直接通过 UI 应用建议的更改，其他更改则在您的 fork 中完成并提交到 PR 分支。
在更新 PR 并应用更改时，将每个对话标记为 已解决。
运行测试¶
使用 uv 运行测试。
uv run pytest
单元测试¶
安装依赖后，这应当可以直接运行。
uv run pytest tests/unit
端到端测试¶
要运行端到端测试，需要在本地运行一些服务
neo4j
weaviate
weaviate-text2vec-transformers
最简便的启动方式是使用 Docker Compose
docker compose -f tests/e2e/docker-compose.yml up
注意
如果怀疑数据库中有缓存，请运行 docker compose -f tests/e2e/docker-compose.yml down 将其彻底移除
服务启动后，执行以下命令运行端到端测试。
uv run pytest tests/e2e