Agentic RAG Knowledge Graph 实战基于 Pydantic AI 与 Graphiti 构建向量与图混合的智能问答系统【免费下载链接】ottomator-agentsAll the open source AI Agents hosted on the oTTomator Live Agent Studio platform!项目地址: https://gitcode.com/GitHub_Trending/ot/ottomator-agents本文以开源仓库中的agentic-rag-knowledge-graph子项目为核心完整讲解一套「Agentic RAG 时序知识图谱」系统的搭建与运行方法从 PostgreSQL(pgvector) 与 Neo4j(Graphiti) 双库准备、Markdown 文档的语义分块与入库流水线到 Pydantic AI Agent 的工具注册策略、FastAPI 流式接口与 CLI 交互。读完本文你可以独立部署这套系统理解「向量检索 图遍历」混合检索的实现链路并掌握 Agent 如何在运行时自主决定调用哪一类检索工具。一、系统概览为什么要把 RAG 和知识图谱组合起来该系统的定位是用传统 RAG向量检索解决找相似内容用知识图谱Graphiti 时序图解决找实体关系与时间演变再由一个 Pydantic AI Agent 决定何时用哪条路径面向的场景是分析大型科技公司及其 AI 举措仓库内置了 21 篇示例文档 big_tech_docs。技术栈如下均见于 READMEPydantic AIAgent 框架负责工具调用与多轮推理Graphiti时序知识图谱中间件负责实体/关系抽取与事实有效期管理PostgreSQL pgvector向量数据库存放文档块与 embeddingNeo4j图数据库引擎Graphiti 连接其后端FastAPIAgent API 服务提供流式SSE与非流式接口。系统由三个主要组件构成文档入库流水线Ingestion Pipeline对 Markdown 文档做语义分块同时构建向量嵌入与知识图谱关系写入 PostgreSQL 与 Neo4jAI Agent 接口基于 Pydantic AI 的会话式 Agent可跨向量库与知识图谱检索流式 APIFastAPI 后端实时流式响应 独立检索端点。项目目录结构仓库实际路径agentic-rag-knowledge-graph/ ├── agent/ # AI agent and API │ ├── agent.py # Main Pydantic AI agent │ ├── api.py # FastAPI application │ ├── db_utils.py # PostgreSQL 访问层 │ ├── graph_utils.py # Graphiti/Neo4j 封装 │ ├── providers.py # LLM provider abstraction │ ├── prompts.py # 系统提示词 │ ├── tools.py # 工具实现与输入模型 │ └── models.py # Data models ├── ingestion/ # Document processing │ ├── ingest.py # Main ingestion pipeline │ ├── chunker.py # Semantic chunking │ ├── embedder.py # Embedding generation │ └── graph_builder.py # Graphiti 入库 ├── sql/ # schema.sql 数据库脚本 ├── big_tech_docs/ # 21 篇示例文档 ├── cli.py # 交互式命令行 └── tests/ # Comprehensive test suite二、环境准备与安装2.1 前置条件Python 3.11 或更高版本PostgreSQL 数据库README 以 Neon 为例Neo4j 数据库知识图谱后端LLM Provider API KeyOpenAI、Ollama、Gemini 等。2.2 创建虚拟环境并安装依赖# Create and activate virtual environment python -m venv venv # python3 on Linux source venv/bin/activate # On Linux/macOS # or venv\Scripts\activate # On Windowspip install -r requirements.txt2.3 初始化 PostgreSQL 表结构执行 sql/schema.sql 中的 SQL创建全部表、索引与函数。关键注意脚本会先 DROP 所有表再重建属于破坏性操作请勿在有数据的生产库上直接执行。此外必须根据所用 embedding 模型修改向量维度——schema 中第 31、67、100 行的vector(1536)需要与你的模型一致OpenAI 的text-embedding-3-small是 1536 维Ollama 的nomic-embed-text是 768 维。从 schema 源码看这套表结构为混合检索做了完整铺垫4 张表documents原文 JSONB 元数据、chunks文本块 embedding向量列、sessions与messages会话与对话历史支撑 CLI 的多轮上下文混合检索索引chunks表上同时建了三类索引——ivfflat向量余弦距离索引vector_cosine_ops、内容列的GIN三元组索引pg_trgm扩展、以及document_id外键索引两个核心 SQL 函数match_chunks(query_embedding, match_count)按1 - (embedding query)余弦相似度排序返回文档块及来源标题hybrid_search(query_embedding, query_text, match_count, text_weight)将向量结果与ts_rank_cd全文结果FULL OUTER JOIN后加权合并合并分公式为vector_sim * (1 - text_weight) text_sim * text_weight默认text_weight 0.3与 Agent 侧工具默认值一致辅助设施get_document_chunks(doc_id)函数、update_updated_at_column()触发器、聚合视图document_summaries含每文档块数与 token 统计。2.4 初始化 Neo4jREADME 给出两种方案方案 A推荐local-ai-packaged 一体化部署克隆coleam00/local-ai-packaged仓库按其安装说明配置 Neo4j记录.env中设置的用户名和密码URI 为bolt://localhost:7687。方案 BNeo4j Desktop下载安装 Neo4j Desktop新建项目并添加本地 DBMS启动 DBMS 并设置密码记录连接信息URI、用户名、密码。2.5 配置环境变量在项目根目录创建.env文件。完整模板如下# Database Configuration (example Neon connection string) DATABASE_URLpostgresql://username:passwordep-example-12345.us-east-2.aws.neon.tech/neondb # Neo4j Configuration NEO4J_URIbolt://localhost:7687 NEO4J_USERneo4j NEO4J_PASSWORDyour_password # LLM Provider Configuration (choose one) LLM_PROVIDERopenai LLM_BASE_URLhttps://api.openai.com/v1 LLM_API_KEYsk-your-api-key LLM_CHOICEgpt-4.1-mini # Embedding Configuration EMBEDDING_PROVIDERopenai EMBEDDING_BASE_URLhttps://api.openai.com/v1 EMBEDDING_API_KEYsk-your-api-key EMBEDDING_MODELtext-embedding-3-small # Ingestion Configuration INGESTION_LLM_CHOICEgpt-4.1-nano # Faster model for processing # Application Configuration APP_ENVdevelopment LOG_LEVELINFO APP_PORT8058其他 LLM 提供商的替换配置# Ollama (Local) LLM_PROVIDERollama LLM_BASE_URLhttp://localhost:11434/v1 LLM_API_KEYollama LLM_CHOICEqwen2.5:14b-instruct # OpenRouter LLM_PROVIDERopenrouter LLM_BASE_URLhttps://openrouter.ai/api/v1 LLM_API_KEYyour-openrouter-key LLM_CHOICEanthropic/claude-3-5-sonnet # Gemini LLM_PROVIDERgemini LLM_BASE_URLhttps://generativelanguage.googleapis.com/v1beta LLM_API_KEYyour-gemini-key LLM_CHOICEgemini-2.5-flash从源码看这套任意 OpenAI 兼容提供商的能力来自 agent/providers.pyget_llm_model()把LLM_BASE_URLLLM_API_KEY交给 Pydantic AI 的OpenAIProvider因此只要端点遵循 OpenAI Chat API 协议即可接入。两个值得注意的实现细节get_ingestion_model()优先读取INGESTION_LLM_CHOICE未设置时回退到主模型——这正是 README 建议入库用更快更便宜的模型的底层支撑因为语义分块和实体抽取都会大量消耗 tokenGraphiti 侧agent/graph_utils.py复用同一套 LLM/embedding 环境变量并用VECTOR_DIMENSION默认 1536声明图侧向量维度——换 embedding 模型时除了改 schema这里也要同步。三、Quick Start文档准备与入库流水线3.1 准备文档把 Markdown 文档放入documents/目录mkdir -p documents # Add your markdown files about tech companies, AI research, etc. # Example: documents/google_ai_initiatives.md # documents/microsoft_openai_partnership.md示例数据可复制仓库内置的big_tech_docs21 篇关于大型科技公司 AI 举措的详细文档cp -r big_tech_docs/* documents/注意README 明确提示把这批文档全部处理进知识图谱会消耗可观时间可能 30 分钟以上因为实体抽取与关系构建的计算复杂度很高——这一提示在源码中也能得到印证入库流水线在构建图谱前会打印Building knowledge graph relationships (this may take several minutes)...ingestion/ingest.py。3.2 运行入库必须先入库Agent 才能给出有意义的回答# Basic ingestion with semantic chunking python -m ingestion.ingest # Clean existing data and re-ingest everything python -m ingestion.ingest --clean # Custom settings for faster processing (no knowledge graph) python -m ingestion.ingest --chunk-size 800 --no-semantic --verbose从 ingestion/ingest.py 的argparse定义看完整参数集如下参数短选项默认值作用--documents-ddocuments文档目录路径递归匹配*.md、*.markdown、*.txt--clean-c关入库前清空 PostgreSQL 四张表与整个知识图谱--chunk-size-1000目标块大小字符--chunk-overlap-200块间重叠--no-semantic-关禁用 LLM 语义分块走规则分块--no-entities-关跳过实体抽取--fast-f关快速模式跳过知识图谱构建只写向量库--verbose-v关日志级别升到 DEBUG单篇文档的处理链路_ingest_single_document为读取文件并提取标题优先取前 10 行中的#一级标题否则用文件名→ 分块 → 实体抽取可选→ 生成 embedding → 事务写入documents/chunksembedding 以[1.0,2.0,...]字符串格式写入vector列→ 若未开启--fast则调用 Graphitiadd_episode写入图。运行结束会打印汇总处理文档数、块数、实体数、图 episode 数、错误数、总耗时及每篇文档的逐项结果。3.3 语义分块的实现细节ingestion/chunker.py 中ChunkingConfig的完整参数dataclass class ChunkingConfig: chunk_size: int 1000 # 目标块大小 chunk_overlap: int 200 # 重叠量必须小于 chunk_size max_chunk_size: int 2000 # 块上限 min_chunk_size: int 100 # 块下限过小的块会被丢弃 use_semantic_splitting: bool True preserve_structure: bool TrueSemanticChunker的三级降级策略是这段实现最值得参考的设计结构切分优先先用正则按 Markdown 结构边界拆分标题、空行段落、无序/有序列表、代码块、表格再把相邻 section 聚合到不超过chunk_size的块LLM 语义切分兜底大段超过max_chunk_size的单段会交给INGESTION_LLM_CHOICE指定的模型要求其在自然语义边界处切分并以---CHUNK---分隔若 LLM 失败或结果不合法回退到句子边界切分纯规则切分整体语义分块失败时按chunk_size硬切并尝试落在.!?\n句子边界带chunk_overlap重叠。每个DocumentChunk都会记录index、原文起止偏移start_char/end_char、元数据含chunk_method: semantic|simple与total_chunkstoken 数按约 4 字符/token粗估——这解释了为什么chunks.token_count是估值而非精确计数。四、Agent 设计工具注册与检索策略4.1 Pydantic AI Agent 与七类工具agent/agent.py 用三行核心代码创建 Agentrag_agent Agent( get_llm_model(), deps_typeAgentDependencies, system_promptSYSTEM_PROMPT )随后通过rag_agent.tool注册了 7 个工具每个工具都是薄壳参数校验后委托给 agent/tools.py 中的实现函数后者再落到db_utils的 SQL 函数或graph_utils的 Graphiti 调用。工具的参数契约含取值范围如下工具关键参数说明vector_searchquery: strlimit: int 101-50向量语义相似检索返回带score/document_title的块列表graph_searchquery: str查 Graphiti 事实结果含fact、valid_at、invalid_at时间字段hybrid_searchquery、limit 101-50、text_weight: float 0.30.0-1.0向量 关键词ts_rank_cd加权混合对应 SQL 函数hybrid_searchget_documentdocument_id: strUUID取整篇文档全文及其全部块list_documentslimit 201-100、offset 0列出知识库文档及块数用于了解可用信息源get_entity_relationshipsentity_name: str、depth: int 21-5查询实体在图中的关系与关联实体get_entity_timelineentity_name、start_date/end_dateISO 日期可选实体事实时间线利用 Graphiti 的valid_at排序所有实现函数都做了容错检索失败时记录日志并返回空列表/空结构如 tools.py保证单个后端故障不会让整个 Agent 崩溃——这也是健康检查能区分 healthy/degraded/unhealthy 的前提。4.2 系统提示词如何约束工具选择README 建议在启动 API 前可通过修改 agent/prompts.py 中的SYSTEM_PROMPT定制 Agent 的工具使用策略。该提示词当前规定了回答前必须先检索并在适用时组合向量与图谱两类结果必须引用来源文档标题与具体事实关注时间维度——部分信息是时效性的核心策略Use the knowledge graph tool only when the user asks about two companies in the same question. Otherwise, use just the vector store tool.仅当用户在同一个问题中问到两家公司时才用图工具否则只用向量库。这条规则直接影响成本与延迟图检索Graphiti 内部走 LLM 语义检索比向量检索重得多用提示词层面的启发式限制调用频率是一种简单的检索路由手段。4.3 Graphiti 侧的时间感知实现agent/graph_utils.py 的GraphitiClient封装了全部图操作初始化时用NEO4J_*连接信息构造Graphiti实例注入 OpenAI 兼容的 LLM 客户端、Embedder 与 Reranker并执行build_indices_and_constraints()入库走add_episodesourceEpisodeType.textsearch()返回的每条事实都携带valid_at/invalid_at——这就是时序知识的来源get_entity_timeline()正是基于valid_at倒序排列事实列表。从源码结构看get_related_entities目前是复用graphiti.search(relationships involving {entity})的语义检索近似实现README 中graph traversal的表述更接近其设计意图而非精确的 Cypher 遍历理解这一点有助于正确预期该工具的输出形态。五、启动 API 服务与 CLI 交互5.1 启动 FastAPI 服务终端 1# Start the FastAPI server python -m agent.api # Server will be available at http://localhost:8058agent/api.py 在 lifespan 启动钩子里依次初始化 Postgres 连接池与 Graphiti、做连通性自检应用层启用了 CORS 全放开与 GZip 中间件。主要端点端点方法说明/healthGET健康检查返回healthy/degraded单库可用/unhealthy/chatPOST非流式问答返回message、session_id与本次使用的tools_used列表/chat/streamPOSTSSE 流式问答先发session事件逐段推text增量收尾推tools与end事件/search/vector、/search/graph、/search/hybridPOST绕过 Agent 直接调用三类检索返回结果数与query_time_ms/documentsGET文档列表limit/offset分页/sessions/{session_id}GET查询会话信息流式实现值得留意它使用 Pydantic AI 的agent.iter()节点级流式 API遍历运行节点在模型请求节点上监听PartStartEvent/PartDeltaEvent把文本增量转成 SSE同时把最近 6 条约 3 轮历史消息拼接进 prompt 作为上下文并把每轮 user/assistant 消息写入messages表——CLI 的会话管理能力即来源于此。5.2 使用 CLI终端 2CLI 提供交互式会话并展示每次回答实际调用了哪些工具# Start the CLI in a separate terminal from the API (connects to default API at http://localhost:8058) python cli.py # Connect to a different URL python cli.py --url http://localhost:8058 # Connect to a specific port python cli.py --port 8080CLI 能力见 cli.py实时流式响应边生成边展示 Agent 回答工具使用可视化列出vector_search语义相似检索、graph_search知识图谱查询、hybrid_search混合检索并附带关键参数query 截断展示、limit、entity会话管理维持多轮对话上下文彩色输出ANSI 颜色区分回答与工具信息。示例会话 Agentic RAG with Knowledge Graph CLI Connected to: http://localhost:8058 You: What are Microsofts AI initiatives? Assistant: Microsoft has several major AI initiatives including... Tools Used: 1. vector_search (queryMicrosoft AI initiatives, limit10) 2. graph_search (queryMicrosoft AI projects) ──────────────────────────────────────────────────────────── You: How is Microsoft connected to OpenAI? Assistant: Microsoft has a significant strategic partnership with OpenAI... Tools Used: 1. hybrid_search (queryMicrosoft OpenAI partnership, limit10) 2. get_entity_relationships (entityMicrosoft)CLI 内置命令help查看命令、health检查 API 连接、clear清空当前会话、exit/quit退出。5.3 接口自测#### Health Check curl http://localhost:8058/health #### Chat with the Agent (Non-streaming) curl -X POST http://localhost:8058/chat \ -H Content-Type: application/json \ -d { message: What are Google\s main AI initiatives? } #### Streaming Chat curl -X POST http://localhost:8058/chat/stream \ -H Content-Type: application/json \ -d { message: Compare Microsoft and Google\s AI strategies, }服务启动后还可访问http://localhost:8058/docs获取交互式 API 文档FastAPI 自带。六、工作原理混合 RAG 知识图谱的互补机制向量库PostgreSQL pgvector跨文档块做语义相似度检索快速召回上下文相关内容适合找相似主题的资料。知识图谱Neo4j Graphiti维护公司、人物、技术之间的时序关系图遍历用于发现关联适合理解合作、收购与随时间演变的格局。智能 Agent自动选择检索策略、合并双库结果、给出带来源引用的上下文感知回答。README 给出的四类典型查询与对应策略语义类问题What AI research is Google working on? → 向量检索召回相关文档块关系类问题How are Microsoft and OpenAI connected? → 知识图谱遍历关系与合作时间类问题Show me the timeline of Metas AI announcements → 借助 Graphiti 的时序能力跟踪事实变化复杂分析Compare the AI strategies of FAANG companies → 向量检索策略文档 图遍历做竞争分析。该架构的优势README 归纳均可在源码中找到对应实现互补强项向量检索找相似内容图谱揭示隐藏关联时间智能Graphiti 跟踪事实随时间的变化契合快速演变的 AI 领域灵活的 LLM 支持可在 OpenAI、Ollama、OpenRouter、Gemini 间切换依赖 OpenAI 兼容协议见 providers.py生产化要素完整测试套件、结构化日志与错误处理。对应地README 列出的关键特性为混合检索、时序知识、SSE 流式响应、多提供商支持、LLM 语义分块、生产级日志/测试/错误处理。七、测试与排错7.1 运行测试# Run all tests pytest # Run with coverage pytest --covagent --covingestion --cov-reporthtml # Run specific test categories pytest tests/agent/ pytest tests/ingestion/测试分为 tests/agentAgent 层与 tests/ingestion入库层配套conftest.py做共享 fixture。7.2 常见问题排查数据库连接确认DATABASE_URL正确且可达psql -d $DATABASE_URL -c SELECT 1;Neo4j 连接确认实例在运行、凭据正确# Check if Neo4j is accessible (adjust URL as needed) curl -u neo4j:password http://localhost:7474/db/data/Agent 没有结果确认已经跑过入库流水线最常见原因python -m ingestion.ingest --verboseLLM API 问题检查.env中的 API Key 与提供商配置LLM_API_KEY、LLM_BASE_URL、LLM_CHOICE注意 Graphiti 侧同样依赖这几个变量缺NEO4J_PASSWORD、LLM_API_KEY或EMBEDDING_API_KEY时GraphitiClient初始化会直接抛出ValueError。八、小结这套系统的工程价值在于把三件事做成了可复用的模板双库存储pgvector 向量 Graphiti 时序图schema 层用 SQL 函数把混合打分封装到数据库内、分级入库--fast/--no-semantic/--no-entities三档开关对应不同时间与算力预算INGESTION_LLM_CHOICE让入库用便宜模型、可观测的 Agenttools_used随每次回答返回并在 CLI 高亮展示使Agent 到底调了哪个工具变成可验证的事实。若你需要把该模式迁移到自己的文档域最需要先想清楚的两个参数是embedding 维度贯穿 schema 与 Graphiti 配置和系统提示词中的工具路由策略决定图检索的触发频率与成本。【免费下载链接】ottomator-agentsAll the open source AI Agents hosted on the oTTomator Live Agent Studio platform!项目地址: https://gitcode.com/GitHub_Trending/ot/ottomator-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Agentic RAG + Knowledge Graph 实战：基于 Pydantic AI 与 Graphiti 构建向量与图混合的智能问答系统
Agentic RAG Knowledge Graph 实战基于 Pydantic AI 与 Graphiti 构建向量与图混合的智能问答系统【免费下载链接】ottomator-agentsAll the open source AI Agents hosted on the oTTomator Live Agent Studio platform!项目地址: https://gitcode.com/GitHub_Trending/ot/ottomator-agents本文以开源仓库中的agentic-rag-knowledge-graph子项目为核心完整讲解一套「Agentic RAG 时序知识图谱」系统的搭建与运行方法从 PostgreSQL(pgvector) 与 Neo4j(Graphiti) 双库准备、Markdown 文档的语义分块与入库流水线到 Pydantic AI Agent 的工具注册策略、FastAPI 流式接口与 CLI 交互。读完本文你可以独立部署这套系统理解「向量检索 图遍历」混合检索的实现链路并掌握 Agent 如何在运行时自主决定调用哪一类检索工具。一、系统概览为什么要把 RAG 和知识图谱组合起来该系统的定位是用传统 RAG向量检索解决找相似内容用知识图谱Graphiti 时序图解决找实体关系与时间演变再由一个 Pydantic AI Agent 决定何时用哪条路径面向的场景是分析大型科技公司及其 AI 举措仓库内置了 21 篇示例文档 big_tech_docs。技术栈如下均见于 READMEPydantic AIAgent 框架负责工具调用与多轮推理Graphiti时序知识图谱中间件负责实体/关系抽取与事实有效期管理PostgreSQL pgvector向量数据库存放文档块与 embeddingNeo4j图数据库引擎Graphiti 连接其后端FastAPIAgent API 服务提供流式SSE与非流式接口。系统由三个主要组件构成文档入库流水线Ingestion Pipeline对 Markdown 文档做语义分块同时构建向量嵌入与知识图谱关系写入 PostgreSQL 与 Neo4jAI Agent 接口基于 Pydantic AI 的会话式 Agent可跨向量库与知识图谱检索流式 APIFastAPI 后端实时流式响应 独立检索端点。项目目录结构仓库实际路径agentic-rag-knowledge-graph/ ├── agent/ # AI agent and API │ ├── agent.py # Main Pydantic AI agent │ ├── api.py # FastAPI application │ ├── db_utils.py # PostgreSQL 访问层 │ ├── graph_utils.py # Graphiti/Neo4j 封装 │ ├── providers.py # LLM provider abstraction │ ├── prompts.py # 系统提示词 │ ├── tools.py # 工具实现与输入模型 │ └── models.py # Data models ├── ingestion/ # Document processing │ ├── ingest.py # Main ingestion pipeline │ ├── chunker.py # Semantic chunking │ ├── embedder.py # Embedding generation │ └── graph_builder.py # Graphiti 入库 ├── sql/ # schema.sql 数据库脚本 ├── big_tech_docs/ # 21 篇示例文档 ├── cli.py # 交互式命令行 └── tests/ # Comprehensive test suite二、环境准备与安装2.1 前置条件Python 3.11 或更高版本PostgreSQL 数据库README 以 Neon 为例Neo4j 数据库知识图谱后端LLM Provider API KeyOpenAI、Ollama、Gemini 等。2.2 创建虚拟环境并安装依赖# Create and activate virtual environment python -m venv venv # python3 on Linux source venv/bin/activate # On Linux/macOS # or venv\Scripts\activate # On Windowspip install -r requirements.txt2.3 初始化 PostgreSQL 表结构执行 sql/schema.sql 中的 SQL创建全部表、索引与函数。关键注意脚本会先 DROP 所有表再重建属于破坏性操作请勿在有数据的生产库上直接执行。此外必须根据所用 embedding 模型修改向量维度——schema 中第 31、67、100 行的vector(1536)需要与你的模型一致OpenAI 的text-embedding-3-small是 1536 维Ollama 的nomic-embed-text是 768 维。从 schema 源码看这套表结构为混合检索做了完整铺垫4 张表documents原文 JSONB 元数据、chunks文本块 embedding向量列、sessions与messages会话与对话历史支撑 CLI 的多轮上下文混合检索索引chunks表上同时建了三类索引——ivfflat向量余弦距离索引vector_cosine_ops、内容列的GIN三元组索引pg_trgm扩展、以及document_id外键索引两个核心 SQL 函数match_chunks(query_embedding, match_count)按1 - (embedding query)余弦相似度排序返回文档块及来源标题hybrid_search(query_embedding, query_text, match_count, text_weight)将向量结果与ts_rank_cd全文结果FULL OUTER JOIN后加权合并合并分公式为vector_sim * (1 - text_weight) text_sim * text_weight默认text_weight 0.3与 Agent 侧工具默认值一致辅助设施get_document_chunks(doc_id)函数、update_updated_at_column()触发器、聚合视图document_summaries含每文档块数与 token 统计。2.4 初始化 Neo4jREADME 给出两种方案方案 A推荐local-ai-packaged 一体化部署克隆coleam00/local-ai-packaged仓库按其安装说明配置 Neo4j记录.env中设置的用户名和密码URI 为bolt://localhost:7687。方案 BNeo4j Desktop下载安装 Neo4j Desktop新建项目并添加本地 DBMS启动 DBMS 并设置密码记录连接信息URI、用户名、密码。2.5 配置环境变量在项目根目录创建.env文件。完整模板如下# Database Configuration (example Neon connection string) DATABASE_URLpostgresql://username:passwordep-example-12345.us-east-2.aws.neon.tech/neondb # Neo4j Configuration NEO4J_URIbolt://localhost:7687 NEO4J_USERneo4j NEO4J_PASSWORDyour_password # LLM Provider Configuration (choose one) LLM_PROVIDERopenai LLM_BASE_URLhttps://api.openai.com/v1 LLM_API_KEYsk-your-api-key LLM_CHOICEgpt-4.1-mini # Embedding Configuration EMBEDDING_PROVIDERopenai EMBEDDING_BASE_URLhttps://api.openai.com/v1 EMBEDDING_API_KEYsk-your-api-key EMBEDDING_MODELtext-embedding-3-small # Ingestion Configuration INGESTION_LLM_CHOICEgpt-4.1-nano # Faster model for processing # Application Configuration APP_ENVdevelopment LOG_LEVELINFO APP_PORT8058其他 LLM 提供商的替换配置# Ollama (Local) LLM_PROVIDERollama LLM_BASE_URLhttp://localhost:11434/v1 LLM_API_KEYollama LLM_CHOICEqwen2.5:14b-instruct # OpenRouter LLM_PROVIDERopenrouter LLM_BASE_URLhttps://openrouter.ai/api/v1 LLM_API_KEYyour-openrouter-key LLM_CHOICEanthropic/claude-3-5-sonnet # Gemini LLM_PROVIDERgemini LLM_BASE_URLhttps://generativelanguage.googleapis.com/v1beta LLM_API_KEYyour-gemini-key LLM_CHOICEgemini-2.5-flash从源码看这套任意 OpenAI 兼容提供商的能力来自 agent/providers.pyget_llm_model()把LLM_BASE_URLLLM_API_KEY交给 Pydantic AI 的OpenAIProvider因此只要端点遵循 OpenAI Chat API 协议即可接入。两个值得注意的实现细节get_ingestion_model()优先读取INGESTION_LLM_CHOICE未设置时回退到主模型——这正是 README 建议入库用更快更便宜的模型的底层支撑因为语义分块和实体抽取都会大量消耗 tokenGraphiti 侧agent/graph_utils.py复用同一套 LLM/embedding 环境变量并用VECTOR_DIMENSION默认 1536声明图侧向量维度——换 embedding 模型时除了改 schema这里也要同步。三、Quick Start文档准备与入库流水线3.1 准备文档把 Markdown 文档放入documents/目录mkdir -p documents # Add your markdown files about tech companies, AI research, etc. # Example: documents/google_ai_initiatives.md # documents/microsoft_openai_partnership.md示例数据可复制仓库内置的big_tech_docs21 篇关于大型科技公司 AI 举措的详细文档cp -r big_tech_docs/* documents/注意README 明确提示把这批文档全部处理进知识图谱会消耗可观时间可能 30 分钟以上因为实体抽取与关系构建的计算复杂度很高——这一提示在源码中也能得到印证入库流水线在构建图谱前会打印Building knowledge graph relationships (this may take several minutes)...ingestion/ingest.py。3.2 运行入库必须先入库Agent 才能给出有意义的回答# Basic ingestion with semantic chunking python -m ingestion.ingest # Clean existing data and re-ingest everything python -m ingestion.ingest --clean # Custom settings for faster processing (no knowledge graph) python -m ingestion.ingest --chunk-size 800 --no-semantic --verbose从 ingestion/ingest.py 的argparse定义看完整参数集如下参数短选项默认值作用--documents-ddocuments文档目录路径递归匹配*.md、*.markdown、*.txt--clean-c关入库前清空 PostgreSQL 四张表与整个知识图谱--chunk-size-1000目标块大小字符--chunk-overlap-200块间重叠--no-semantic-关禁用 LLM 语义分块走规则分块--no-entities-关跳过实体抽取--fast-f关快速模式跳过知识图谱构建只写向量库--verbose-v关日志级别升到 DEBUG单篇文档的处理链路_ingest_single_document为读取文件并提取标题优先取前 10 行中的#一级标题否则用文件名→ 分块 → 实体抽取可选→ 生成 embedding → 事务写入documents/chunksembedding 以[1.0,2.0,...]字符串格式写入vector列→ 若未开启--fast则调用 Graphitiadd_episode写入图。运行结束会打印汇总处理文档数、块数、实体数、图 episode 数、错误数、总耗时及每篇文档的逐项结果。3.3 语义分块的实现细节ingestion/chunker.py 中ChunkingConfig的完整参数dataclass class ChunkingConfig: chunk_size: int 1000 # 目标块大小 chunk_overlap: int 200 # 重叠量必须小于 chunk_size max_chunk_size: int 2000 # 块上限 min_chunk_size: int 100 # 块下限过小的块会被丢弃 use_semantic_splitting: bool True preserve_structure: bool TrueSemanticChunker的三级降级策略是这段实现最值得参考的设计结构切分优先先用正则按 Markdown 结构边界拆分标题、空行段落、无序/有序列表、代码块、表格再把相邻 section 聚合到不超过chunk_size的块LLM 语义切分兜底大段超过max_chunk_size的单段会交给INGESTION_LLM_CHOICE指定的模型要求其在自然语义边界处切分并以---CHUNK---分隔若 LLM 失败或结果不合法回退到句子边界切分纯规则切分整体语义分块失败时按chunk_size硬切并尝试落在.!?\n句子边界带chunk_overlap重叠。每个DocumentChunk都会记录index、原文起止偏移start_char/end_char、元数据含chunk_method: semantic|simple与total_chunkstoken 数按约 4 字符/token粗估——这解释了为什么chunks.token_count是估值而非精确计数。四、Agent 设计工具注册与检索策略4.1 Pydantic AI Agent 与七类工具agent/agent.py 用三行核心代码创建 Agentrag_agent Agent( get_llm_model(), deps_typeAgentDependencies, system_promptSYSTEM_PROMPT )随后通过rag_agent.tool注册了 7 个工具每个工具都是薄壳参数校验后委托给 agent/tools.py 中的实现函数后者再落到db_utils的 SQL 函数或graph_utils的 Graphiti 调用。工具的参数契约含取值范围如下工具关键参数说明vector_searchquery: strlimit: int 101-50向量语义相似检索返回带score/document_title的块列表graph_searchquery: str查 Graphiti 事实结果含fact、valid_at、invalid_at时间字段hybrid_searchquery、limit 101-50、text_weight: float 0.30.0-1.0向量 关键词ts_rank_cd加权混合对应 SQL 函数hybrid_searchget_documentdocument_id: strUUID取整篇文档全文及其全部块list_documentslimit 201-100、offset 0列出知识库文档及块数用于了解可用信息源get_entity_relationshipsentity_name: str、depth: int 21-5查询实体在图中的关系与关联实体get_entity_timelineentity_name、start_date/end_dateISO 日期可选实体事实时间线利用 Graphiti 的valid_at排序所有实现函数都做了容错检索失败时记录日志并返回空列表/空结构如 tools.py保证单个后端故障不会让整个 Agent 崩溃——这也是健康检查能区分 healthy/degraded/unhealthy 的前提。4.2 系统提示词如何约束工具选择README 建议在启动 API 前可通过修改 agent/prompts.py 中的SYSTEM_PROMPT定制 Agent 的工具使用策略。该提示词当前规定了回答前必须先检索并在适用时组合向量与图谱两类结果必须引用来源文档标题与具体事实关注时间维度——部分信息是时效性的核心策略Use the knowledge graph tool only when the user asks about two companies in the same question. Otherwise, use just the vector store tool.仅当用户在同一个问题中问到两家公司时才用图工具否则只用向量库。这条规则直接影响成本与延迟图检索Graphiti 内部走 LLM 语义检索比向量检索重得多用提示词层面的启发式限制调用频率是一种简单的检索路由手段。4.3 Graphiti 侧的时间感知实现agent/graph_utils.py 的GraphitiClient封装了全部图操作初始化时用NEO4J_*连接信息构造Graphiti实例注入 OpenAI 兼容的 LLM 客户端、Embedder 与 Reranker并执行build_indices_and_constraints()入库走add_episodesourceEpisodeType.textsearch()返回的每条事实都携带valid_at/invalid_at——这就是时序知识的来源get_entity_timeline()正是基于valid_at倒序排列事实列表。从源码结构看get_related_entities目前是复用graphiti.search(relationships involving {entity})的语义检索近似实现README 中graph traversal的表述更接近其设计意图而非精确的 Cypher 遍历理解这一点有助于正确预期该工具的输出形态。五、启动 API 服务与 CLI 交互5.1 启动 FastAPI 服务终端 1# Start the FastAPI server python -m agent.api # Server will be available at http://localhost:8058agent/api.py 在 lifespan 启动钩子里依次初始化 Postgres 连接池与 Graphiti、做连通性自检应用层启用了 CORS 全放开与 GZip 中间件。主要端点端点方法说明/healthGET健康检查返回healthy/degraded单库可用/unhealthy/chatPOST非流式问答返回message、session_id与本次使用的tools_used列表/chat/streamPOSTSSE 流式问答先发session事件逐段推text增量收尾推tools与end事件/search/vector、/search/graph、/search/hybridPOST绕过 Agent 直接调用三类检索返回结果数与query_time_ms/documentsGET文档列表limit/offset分页/sessions/{session_id}GET查询会话信息流式实现值得留意它使用 Pydantic AI 的agent.iter()节点级流式 API遍历运行节点在模型请求节点上监听PartStartEvent/PartDeltaEvent把文本增量转成 SSE同时把最近 6 条约 3 轮历史消息拼接进 prompt 作为上下文并把每轮 user/assistant 消息写入messages表——CLI 的会话管理能力即来源于此。5.2 使用 CLI终端 2CLI 提供交互式会话并展示每次回答实际调用了哪些工具# Start the CLI in a separate terminal from the API (connects to default API at http://localhost:8058) python cli.py # Connect to a different URL python cli.py --url http://localhost:8058 # Connect to a specific port python cli.py --port 8080CLI 能力见 cli.py实时流式响应边生成边展示 Agent 回答工具使用可视化列出vector_search语义相似检索、graph_search知识图谱查询、hybrid_search混合检索并附带关键参数query 截断展示、limit、entity会话管理维持多轮对话上下文彩色输出ANSI 颜色区分回答与工具信息。示例会话 Agentic RAG with Knowledge Graph CLI Connected to: http://localhost:8058 You: What are Microsofts AI initiatives? Assistant: Microsoft has several major AI initiatives including... Tools Used: 1. vector_search (queryMicrosoft AI initiatives, limit10) 2. graph_search (queryMicrosoft AI projects) ──────────────────────────────────────────────────────────── You: How is Microsoft connected to OpenAI? Assistant: Microsoft has a significant strategic partnership with OpenAI... Tools Used: 1. hybrid_search (queryMicrosoft OpenAI partnership, limit10) 2. get_entity_relationships (entityMicrosoft)CLI 内置命令help查看命令、health检查 API 连接、clear清空当前会话、exit/quit退出。5.3 接口自测#### Health Check curl http://localhost:8058/health #### Chat with the Agent (Non-streaming) curl -X POST http://localhost:8058/chat \ -H Content-Type: application/json \ -d { message: What are Google\s main AI initiatives? } #### Streaming Chat curl -X POST http://localhost:8058/chat/stream \ -H Content-Type: application/json \ -d { message: Compare Microsoft and Google\s AI strategies, }服务启动后还可访问http://localhost:8058/docs获取交互式 API 文档FastAPI 自带。六、工作原理混合 RAG 知识图谱的互补机制向量库PostgreSQL pgvector跨文档块做语义相似度检索快速召回上下文相关内容适合找相似主题的资料。知识图谱Neo4j Graphiti维护公司、人物、技术之间的时序关系图遍历用于发现关联适合理解合作、收购与随时间演变的格局。智能 Agent自动选择检索策略、合并双库结果、给出带来源引用的上下文感知回答。README 给出的四类典型查询与对应策略语义类问题What AI research is Google working on? → 向量检索召回相关文档块关系类问题How are Microsoft and OpenAI connected? → 知识图谱遍历关系与合作时间类问题Show me the timeline of Metas AI announcements → 借助 Graphiti 的时序能力跟踪事实变化复杂分析Compare the AI strategies of FAANG companies → 向量检索策略文档 图遍历做竞争分析。该架构的优势README 归纳均可在源码中找到对应实现互补强项向量检索找相似内容图谱揭示隐藏关联时间智能Graphiti 跟踪事实随时间的变化契合快速演变的 AI 领域灵活的 LLM 支持可在 OpenAI、Ollama、OpenRouter、Gemini 间切换依赖 OpenAI 兼容协议见 providers.py生产化要素完整测试套件、结构化日志与错误处理。对应地README 列出的关键特性为混合检索、时序知识、SSE 流式响应、多提供商支持、LLM 语义分块、生产级日志/测试/错误处理。七、测试与排错7.1 运行测试# Run all tests pytest # Run with coverage pytest --covagent --covingestion --cov-reporthtml # Run specific test categories pytest tests/agent/ pytest tests/ingestion/测试分为 tests/agentAgent 层与 tests/ingestion入库层配套conftest.py做共享 fixture。7.2 常见问题排查数据库连接确认DATABASE_URL正确且可达psql -d $DATABASE_URL -c SELECT 1;Neo4j 连接确认实例在运行、凭据正确# Check if Neo4j is accessible (adjust URL as needed) curl -u neo4j:password http://localhost:7474/db/data/Agent 没有结果确认已经跑过入库流水线最常见原因python -m ingestion.ingest --verboseLLM API 问题检查.env中的 API Key 与提供商配置LLM_API_KEY、LLM_BASE_URL、LLM_CHOICE注意 Graphiti 侧同样依赖这几个变量缺NEO4J_PASSWORD、LLM_API_KEY或EMBEDDING_API_KEY时GraphitiClient初始化会直接抛出ValueError。八、小结这套系统的工程价值在于把三件事做成了可复用的模板双库存储pgvector 向量 Graphiti 时序图schema 层用 SQL 函数把混合打分封装到数据库内、分级入库--fast/--no-semantic/--no-entities三档开关对应不同时间与算力预算INGESTION_LLM_CHOICE让入库用便宜模型、可观测的 Agenttools_used随每次回答返回并在 CLI 高亮展示使Agent 到底调了哪个工具变成可验证的事实。若你需要把该模式迁移到自己的文档域最需要先想清楚的两个参数是embedding 维度贯穿 schema 与 Graphiti 配置和系统提示词中的工具路由策略决定图检索的触发频率与成本。【免费下载链接】ottomator-agentsAll the open source AI Agents hosted on the oTTomator Live Agent Studio platform!项目地址: https://gitcode.com/GitHub_Trending/ot/ottomator-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考