GraphRAG

使用 GraphRAG SDK (图检索增强生成软件开发工具包) 大规模构建快速且准确的 GenAI (生成式人工智能) 应用

使用 GraphRAG-SDK 简化您的下一代 GenAI 应用开发，这是一个用于构建图检索增强生成 (Graph Retrieval-Augmented Generation, GraphRAG) 系统的专用工具包。它集成了知识图谱 (Knowledge Graph)、本体 (Ontology) 管理和最先进的 LLM (大语言模型)，以提供准确、高效且可定制的 RAG (检索增强生成) 工作流。

GraphRAG 设置

数据库设置

或者使用 Docker 进行本地部署 (On-premise)：

docker run -p 6379:6379 -p 3000:3000 -it --rm  -v ./data:/data falkordb/falkordb:latest

依赖项：

pip install graphrag_sdk

配置凭证。参见 .env 获取示例。

• LiteLLM: 一个支持大语言模型推理的框架，允许在部署和用例方面具有灵活性。
  要选择供应商，请使用前缀 "specific_vendor/your_model"，例如 "openai/gpt-4.1"。
• OpenAI 推荐模型：gpt-4.1
• Google 推荐模型：gemini-2.0-flash
• Azure-OpenAI 推荐模型：gpt-4.1
• Ollama 仅适用于问答 (Q&A) 步骤。推荐模型：llama3。Ollama 模型仅适用于问答步骤（在知识图谱 (KG) 创建之后）。

如何使用

环境配置

在使用 SDK 之前，配置您的环境变量：

# FalkorDB Connection (defaults are for on-premises)
export FALKORDB_HOST="localhost" 
export FALKORDB_PORT=6379 
export FALKORDB_USERNAME="your-username"  # optional for on-premises
export FALKORDB_PASSWORD="your-password"  # optional for on-premises

# LLM Provider (choose one)
export OPENAI_API_KEY="your-key"  # or GOOGLE_API_KEY, GROQ_API_KEY, etc.

使用现有知识图谱快速入门

如果您已经在 FalkorDB 中拥有知识图谱，可以通过从现有图谱中提取本体 (Ontology) 来快速设置 GraphRAG：

import os
from falkordb import FalkorDB
from graphrag_sdk import KnowledgeGraph
from graphrag_sdk.ontology import Ontology
from graphrag_sdk.models.litellm import LiteModel
from graphrag_sdk.model_config import KnowledgeGraphModelConfig

graph_name = "my_existing_graph"

# Connect to FalkorDB using environment variables
db = FalkorDB(
    host=os.getenv("FALKORDB_HOST", "localhost"),
    port=int(os.getenv("FALKORDB_PORT", 6379)),
    username=os.getenv("FALKORDB_USERNAME"),  # optional for on-premises
    password=os.getenv("FALKORDB_PASSWORD")   # optional for on-premises
)

# Select graph
graph = db.select_graph(graph_name)

# Extract ontology from existing knowledge graph
ontology = Ontology.from_kg_graph(graph)

# Configure model and create GraphRAG instance
model = LiteModel()  # Default is OpenAI GPT-4.1, can specify different model
model_config = KnowledgeGraphModelConfig.with_model(model)

# Create KnowledgeGraph instance
kg = KnowledgeGraph(
    name=graph_name,
    model_config=model_config,
    ontology=ontology,
    host=os.getenv("FALKORDB_HOST", "localhost"),
    port=int(os.getenv("FALKORDB_PORT", 6379)),
    username=os.getenv("FALKORDB_USERNAME"),
    password=os.getenv("FALKORDB_PASSWORD")
)

# Start chat session
chat = kg.chat_session()

# Ask questions
response = chat.send_message("What products are available?")
print(response["response"])

# Ask follow-up questions
response = chat.send_message("Tell me which one of them is the most expensive")
print(response["response"])

从头创建知识图谱

步骤 1：创建本体

从不结构化数据自动化创建本体 (Ontology) 或手动定义 - 参见 示例

from dotenv import load_dotenv
import json
from graphrag_sdk.source import URL
from graphrag_sdk import KnowledgeGraph, Ontology
from graphrag_sdk.models.litellm import LiteModel
from graphrag_sdk.model_config import KnowledgeGraphModelConfig
load_dotenv()

# Import Data
urls = ["https://www.rottentomatoes.com/m/side_by_side_2012",
"https://www.rottentomatoes.com/m/matrix",
"https://www.rottentomatoes.com/m/matrix_revolutions",
"https://www.rottentomatoes.com/m/matrix_reloaded",
"https://www.rottentomatoes.com/m/speed_1994",
"https://www.rottentomatoes.com/m/john_wick_chapter_4"]

sources = [URL(url) for url in urls]

# Model - vendor: openai, model: gpt-4.1 -> openai/gpt-4.1
model = LiteModel(model_name="openai/gpt-4.1")

# Ontology Auto-Detection
ontology = Ontology.from_sources(
    sources=sources,
    model=model,
)
# Save the ontology to the disk as a json file.
with open("ontology.json", "w", encoding="utf-8") as file:
    file.write(json.dumps(ontology.to_json(), indent=2))

步骤 2：创建知识图谱代理 (Agent)

构建、查询和管理针对检索和增强任务优化的知识图谱 (Knowledge Graph)。 利用 FalkorDB 实现高性能图谱查询和多租户支持。

# After approving the ontology, load it from disk.
ontology_file = "ontology.json"
with open(ontology_file, "r", encoding="utf-8") as file:
    ontology = Ontology.from_json(json.loads(file.read()))

kg = KnowledgeGraph(
    name="kg_name",
    model_config=KnowledgeGraphModelConfig.with_model(model),
    ontology=ontology,
    host="127.0.0.1",
    port=6379,
    # username=falkor_username, # optional
    # password=falkor_password  # optional
)

kg.process_sources(sources)

步骤 3：查询您的 Graph RAG

此时，您已经拥有一个可以使用此软件开发工具包（SDK）进行查询的知识图谱（Knowledge Graph）。使用 chat_session 方法来开始对话。

# Conversation
chat = kg.chat_session()
response = chat.send_message("Who is the director of the movie The Matrix?")
print(response)
response = chat.send_message("How this director connected to Keanu Reeves?")
print(response)

下一步

完成这 3 个步骤后，您就可以与您的知识图谱进行交互和查询了。以下是一些用例建议：

需要针对您的用例寻求帮助？让我们 谈谈

使用 Ollama

Ollama 模型仅适用于问答（Q&A）步骤（即在知识图谱创建之后）。

设置

from graphrag_sdk.models.ollama import OllamaGenerativeModel

# Local Ollama (default: http://localhost:11434)
qa_model = OllamaGenerativeModel(model_name="llama3:8b")

# Remote Ollama
qa_model = OllamaGenerativeModel(
    model_name="llama3:8b",
    api_base="http://remote-host:11434"
)

使用 GraphRAG 的 AI 智能体（Agents）

编排器（Orchestrator）

GraphRAG-SDK 支持基于知识图谱的智能体。每个智能体都是其领域的专家，而编排器负责协调这些智能体。

查看示例：

智能体（Agents）

请参阅 步骤 1 部分，了解如何基于预定义的本体（Ontology）为智能体创建知识图谱对象。

# Define the model
model = LiteModel(model_name="openai/gpt-4.1")

# Create the Knowledge Graph from the predefined ontology.
# In this example, we will use the restaurants agent and the attractions agent.
restaurants_kg = KnowledgeGraph(
    name="restaurants",
    ontology=restaurants_ontology,
    model_config=KnowledgeGraphModelConfig.with_model(model),
    host="127.0.0.1",
    port=6379,
    # username=falkor_username, # optional
    # password=falkor_password  # optional
)
attractions_kg = KnowledgeGraph(
    name="attractions",
    ontology=attractions_ontology,
    model_config=KnowledgeGraphModelConfig.with_model(model),
    host="127.0.0.1",
    port=6379,
    # username=falkor_username, # optional
    # password=falkor_password  # optional
)


# The following agent is specialized in finding restaurants.
restaurants_agent = KGAgent(
    agent_id="restaurants_agent",
    kg=restaurants_kg,
    introduction="I'm a restaurant agent, specialized in finding the best restaurants for you.",
)

# The following agent is specialized in finding tourist attractions.
attractions_agent = KGAgent(
    agent_id="attractions_agent",
    kg=attractions_kg,
    introduction="I'm an attractions agent, specialized in finding the best tourist attractions for you.",
)

编排器 - 多智能体系统（Multi-Agent System）

编排器管理智能体的使用并处理提问。

# Initialize the orchestrator while giving it the backstory.
orchestrator = Orchestrator(
    model,
    backstory="You are a trip planner, and you want to provide the best possible itinerary for your clients.",
)

# Register the agents that we created above.
orchestrator.register_agent(restaurants_agent)
orchestrator.register_agent(attractions_agent)

# Query the orchestrator.
runner = orchestrator.ask("Create a two-day itinerary for a trip to Rome. Please don't ask me any questions; just provide the best itinerary you can.")
print(runner.output)

社区

有问题或反馈？请通过以下方式联系：

• GitHub 问题
• 加入我们的 Discord

⭐️ 如果您觉得这个仓库有帮助，请考虑给它点个星！

额外增强：配置您的提示词（Prompts）

在创建您的知识图谱（KG）智能体时，您可以自定义提示词以调整其行为。

💡 此步骤是可选的，但可以增强功能。

这里有五种类型的提示词：

1. cypher_system_instruction

   • 用于 Cypher 生成步骤的系统指令。
   • 注意： 确保您的提示词包含 {ontology}。

2. qa_system_instruction

   • 用于问答（Q&A）步骤的系统指令。

3. cypher_gen_prompt

   • 在 Cypher 生成步骤期间使用的提示词。
   • 注意： 在您的提示词中包含 {question}。

4. cypher_gen_prompt_history

   • 当需要考虑历史记录时，用于 Cypher 生成的提示词。
   • 注意： 在您的提示词中包含 {question} 和 {last_answer}。

5. qa_prompt

   • 在问答（Q&A）步骤期间使用的提示词。
   • 注意： 在您的提示词中包含 {question}、{context} 和 {cypher}。

这是一个配置示例：

kg = KnowledgeGraph(
    name="kg_name",
    model_config=KnowledgeGraphModelConfig.with_model(model),
    ontology=ontology,
    cypher_system_instruction=cypher_system_instruction,
    qa_system_instruction=qa_system_instruction,
    cypher_gen_prompt=cypher_gen_prompt,
    cypher_gen_prompt_history=cypher_gen_prompt_history,
    qa_prompt=qa_prompt
    host="127.0.0.1",
    port=6379,
    # username=falkor_username, # optional
    # password=falkor_password  # optional
)

常见问题解答（FAQ）

支持哪些数据库？

GraphRAG-SDK 针对 FalkorDB 进行了优化。其他后端可能需要适配器。

SDK 的可扩展性如何？

GraphRAG-SDK 专为多租户和大规模应用设计。性能取决于 FalkorDB 的部署配置。

此 SDK 如何改进检索增强生成（Retrieval-Augmented Generation）？

通过利用知识图谱，GraphRAG-SDK 能够实现语义关系和本体驱动的查询，超越了标准的向量相似度。

SDK 支持哪些文件格式？

支持的格式包括 PDF、JSONL、CSV、HTML、TEXT 和 URL。

SDK 如何处理延迟？

SDK 通过 FalkorDB 针对低延迟操作进行了优化，使用了查询优化和内存处理等技术。

SDK 支持多图查询吗？

支持。多图查询受到支持，API 专为跨域和分层图谱探索设计。

许可证

本项目采用 MIT 许可证授权。详情请参见 LICENSE 文件。

关键词：RAG（检索增强生成）, graphrag, 检索增强生成（Retrieval-Augmented Generation）, NLP（自然语言处理）, AI（人工智能）, 信息检索（Information Retrieval）, 自然语言处理（Natural Language Processing）, LLM（大型语言模型）, 嵌入（Embeddings）, 语义搜索（Semantic Search）

GraphRAG-SDK 快速上手指南

GraphRAG-SDK 是一个用于构建图检索增强生成（GraphRAG）系统的专用工具包。它集成了知识图谱、本体管理和先进的大语言模型（LLM），旨在简化 GenAI 应用的开发，提供准确、高效且可定制的 RAG 工作流。

环境准备

在开始之前，请确保满足以下系统要求：

• 操作系统：支持 Docker 的系统（Linux / macOS / Windows）
• Python 环境：Python 3.8+
• 数据库：FalkorDB（可通过 Docker 本地部署或使用 FalkorDB Cloud）
• 大模型凭证：需准备至少一个 LLM 提供商的 API Key（推荐 OpenAI、Google 或 Azure）

安装步骤

1. 部署 FalkorDB 数据库

使用 Docker 快速启动本地 FalkorDB 实例：

docker run -p 6379:6379 -p 3000:3000 -it --rm  -v ./data:/data falkordb/falkordb:latest

2. 安装 Python SDK

通过 pip 安装 GraphRAG-SDK：

pip install graphrag_sdk

3. 配置环境变量

在使用 SDK 前，需配置数据库连接和 LLM 凭证。建议在终端导出变量或创建 .env 文件：

# FalkorDB 连接配置 (本地默认)
export FALKORDB_HOST="localhost" 
export FALKORDB_PORT=6379 
export FALKORDB_USERNAME="your-username"  # 本地部署可选
export FALKORDB_PASSWORD="your-password"  # 本地部署可选

# LLM 提供商配置 (任选其一)
export OPENAI_API_KEY="your-key"  # 或 GOOGLE_API_KEY, GROQ_API_KEY 等

基本使用

以下示例展示如何从零开始创建知识图谱并进行问答。流程分为：定义数据源 -> 构建本体 -> 创建图谱 -> 对话查询。

1. 构建知识图谱

首先导入数据源并自动检测本体结构，然后初始化知识图谱代理。

import os
import json
from dotenv import load_dotenv
from graphrag_sdk.source import URL
from graphrag_sdk import KnowledgeGraph, Ontology
from graphrag_sdk.models.litellm import LiteModel
from graphrag_sdk.model_config import KnowledgeGraphModelConfig

load_dotenv()

# 1. 准备数据源 (示例为电影网页)
urls = [
    "https://www.rottentomatoes.com/m/matrix",
    "https://www.rottentomatoes.com/m/matrix_revolutions"
]
sources = [URL(url) for url in urls]

# 2. 配置模型 (默认使用 OpenAI GPT-4.1，可通过 openai/gpt-4.1 指定)
model = LiteModel(model_name="openai/gpt-4.1")

# 3. 自动检测本体结构
ontology = Ontology.from_sources(sources=sources, model=model)

# 4. 创建知识图谱实例
kg = KnowledgeGraph(
    name="movies_kg",
    model_config=KnowledgeGraphModelConfig.with_model(model),
    ontology=ontology,
    host=os.getenv("FALKORDB_HOST", "localhost"),
    port=int(os.getenv("FALKORDB_PORT", 6379)),
    username=os.getenv("FALKORDB_USERNAME"),
    password=os.getenv("FALKORDB_PASSWORD")
)

# 5. 处理数据源并构建图谱
kg.process_sources(sources)

2. 查询与对话

图谱构建完成后，即可开启会话进行自然语言查询。

# 开启聊天会话
chat = kg.chat_session()

# 发送问题
response = chat.send_message("Who is the director of the movie The Matrix?")
print(response)

# 多轮对话
response = chat.send_message("How this director connected to Keanu Reeves?")
print(response)

进阶提示

• 本地模型支持：问答步骤支持使用 Ollama 本地模型（如 llama3），需在初始化 KnowledgeGraph 后配置 OllamaGenerativeModel。
• 多智能体协作：SDK 支持基于知识图谱的多智能体系统（Orchestrator），可为不同领域（如餐厅、景点）创建独立 Agent 并由协调器统一管理。
• 提示词定制：创建 KnowledgeGraph 时可自定义 cypher_system_instruction、qa_prompt 等提示词以优化行为。