LangGraph-Agentic-Graph-RAG

# LangGraph-Agent-Graph RAG <div align="center"> <img src="https://img.shields.io/badge/python-3.10%2B-blue.svg" alt="Python"> <img src="https://img.shields.io/badge/Framework-LangGraph-orange.svg" alt="LangGraph"> <img src="https://img.shields.io/badge/Inference-SGLang-green.svg" alt="SGLang"> <img src="https://img.shields.io/badge/DB-Neo4j-blue.svg" alt="Neo4j"> <img src="https://img.shields.io/badge/DB-Weaviate-green.svg" alt="Weaviate"> <br> [](https://opensource.org/licenses/MIT) [](https://opensource.org/licenses/Apache-2.0) English | [한국어](README/README_KO.md) | 中文 </div> 传统的单一向量 RAG 系统在处理复杂的多步查询时面临固有的局限性，往往仅限于被动的 信息检索。为了克服这一局限性，我最初设计了 Agentic Graph RAG，由 LangGraph 和 SGLang 提供支持，具备自适应的 3 路检索路由系统，以最大限度地提高推理准确性并最小化不必要的数据库流量。 然而，在架构设计阶段，我意识到仅在这一稳健的检索基础上添加基于意图的工具路由层和模型上下文协议（MCP），就完全有可能构建一个完全自主的 Agentic AI 系统。 考虑到这一高可扩展性，架构被扩展。生成的框架动态地对用户意图进行分类，以便在深入的知识检索和计算任务（计算器、SQL、API）之间无缝切换。结合智能回溯和质量门验证，该项目为 AI 系统奠定了高度可扩展的基础，不仅可以检索信息，还可以主动思考和执行工具。 LangGraph-Agent-Graph RAG 是一个完全自主的 Agentic AI 和向量-图混合 RAG 平台，由 LangGraph + SGLang 提供支持。摄入管道将原始文档通过 LangGraph 状态机转换为 Markdown 片段和图元数据，并具有检查点持久性。在查询时，基于意图的工具路由器动态地将计算任务委派给外部工具（通过 MCP），而知识查询则通过基于跳的路由器路由，选择三个检索路径中的一个——向量、Weaviate GraphRAG 或 Neo4j GraphDB——以生成精确的答案。 该系统具有以下特点： - **双模式查询处理**：根据 LLM 驱动的意图分类，在基于知识的 RAG 检索和工具执行之间自动路由 - **高级文档摄入**：通过 LangGraph 状态机将原始文档（PDF/图像/音频）转换为 Markdown 片段和结构化的图元数据，并具有检查点持久性 - **智能检索路由**：基于跳的路由器与质量门回溯动态选择三个检索路径（向量、Weaviate Cross-Reference GraphRAG 或 Neo4j Deep Graph Traversal），根据查询复杂度 - **工具调用框架**：MCP（模型上下文协议）服务器集成，支持计算器、API 调用、代码执行和数据库查询，具有本地备用 - **思维图推理**：复杂分析查询的多分支探索，支持快照回溯 <div align="center"> <img src="https://github.com/user-attachments/assets/504ea0fa-ed9a-4664-9095-042e01debc65" width="512" height="768" ></img><br/> </div> --- ## 核心能力 - **LangGraph 状态机**：所有工作流（摄入、查询推理、工具执行、总结、思维图生成）都在 LangGraph `StateGraph` 上运行，并使用 `MemorySaver` 检查点进行完整的 状态持久性和恢复。 - **智能查询路由**：LLM 驱动的意图分类自动确定查询是需要知识检索还是计算工具执行： - **知识查询** → RAG 管道，具有 3 路检索路由 - **计算查询** → 计算器工具，具有基于 AST 的安全评估，支持高级数学（sqrt、log、trig、sigma） - **数据库查询** → SQL 执行器（计划中） - **API 调用** → HTTP API 调用器，具有可配置的端点 - **代码执行** → Python 沙盒，具有受限的内置函数 - **检查点和智能回溯**：每个节点转换都被检查点记录；质量门评估检索结果并触发智能路径选择，当质量不足时： - **质量评估**：观察者 LLM 根据 `QUALITY_GATE_THRESHOLD` 对每个路径结果进行评分（0.0-1.0） - **智能路径选择**：`PathSelector` 根据查询关键词、跳数和路径特征分析剩余未尝试的路径，以选择最合适的替代方案 - **回溯限制**：可通过 `MAX_BACKTRACK_COUNT` 配置以防止无限循环 - **状态跟踪**：`tried_paths` 字段防止重试失败的策略 - **3 路检索路由**：查询复杂度（跳数）决定了最佳检索策略： - **路径 1 – 向量 RAG（≤ 2 跳）**：对延迟分段的 TextDocument Corpus 进行快速语义相似性搜索。适用于直接事实问题。 - **路径 2 – Weaviate Cross-Reference GraphRAG（3-5 跳）**：BM25 种子实体搜索后，在 Weaviate 中进行多跳交叉引用遍历（源/目标/事件引用）。通过关系行走，揭示查询相关的实体和事件。 - **路径 3 – Neo4j Deep Graph Traversal（≥ 6 跳）**：基于 Cypher 的深度图探索，用于模式密集的关系推理。处理需要广泛图遍历的复杂多实体查询。 - **跳分类**：混合 LLM + 启发式方法估计查询复杂度，LLM 主要分类，基于关键词的备用 - **思维图扩展**：复杂分析查询的多分支推理，具有基于快照的回溯： - **分支探索**：每个步骤扩展 `GOT_BRANCH_FACTOR` 个候选查询并行 - **质量评分**：观察者 LLM 评估每个分支（0.0-1.0）的相关性、覆盖度和新颖性 - **智能合并**：高于 `GOT_THOUGHT_SCORE_THRESHOLD` 的分支通过可配置的策略（`top_k`/`weighted_union`/`vote`）合并 - **边缘修剪**：通过关键词重叠评分删除低质量连接（`GOT_EDGE_PRUNE_THRESHOLD`） - **故障恢复**：连续所有分支故障触发快照回滚到最后的成功合并点 - **SGLang 推理生态系统**：所有 LLM 操作（生成、嵌入、重新排名、跳分类、质量评估）在 SGLang 服务器上运行，具有智能生命周期管理： - **延迟加载架构**：服务器在第一个请求时自动启动，消除了初始化期间的冷启动开销 - **空闲超时**：GPU 内存在 `SGLANG_IDLE_TIMEOUT`（默认 60 秒）后自动释放 - **GPU 分配**：每个服务器（生成器、嵌入、重新排名器、精炼器）可配置设备分配和内存分数 - **保持活动机制**：后台线程在长时间运行的操作期间维护服务器健康 - **块重试逻辑**：LLM 元数据提取在失败时自动重试带有服务器重启的块（可通过 `GRAPH_EXTRACTOR_RETRY_ON_FAILURE` 配置） - **工具调用框架**：MCP（模型上下文协议）服务器集成，具有本地备用： - **MCP-first 架构**：在可用时通过 MCP 服务器进行主要执行（`MCP_SERVER_ENABLED=true`） - **本地备用**：当 MCP 服务器不可用时自动备用到本地实现 - **计算器**：基于 AST 的安全表达式评估，支持高级数学函数（sqrt、cbrt、log、exp、sin、cos、tan、sigma） - **自然语言解析**：将韩语/英语数学表达式（"144의 제곱근", "루트 144"）转换为可执行代码 - **API 调用者**：HTTP 请求执行，具有可配置的端点和方法 - **代码运行器**：Python 沙盒，具有受限的内置函数和令牌过滤以确保安全 - **SQL 执行器**：未来数据库查询支持的占位符 - **自动图构建**：从原始文档到可查询的知识图的端到端管道： - **OCR 处理**：SGLang 驱动的 OCRFlux 将文档转换为 Markdown - **LLM 提取**：从 Markdown 块中提取实体/事件/关系，具有可配置的块大小和超时 - **双存储**：同时插入 Weaviate（交叉引用图）和 Neo4j（深度图），具有确定性的 UUID - **模式管理**：自动创建 Weaviate 集合及其交叉引用定义 - **异步作业监控**：通过 REST API 跟踪整个任务生命周期： - **上传进度**：文件上传和处理阶段的实时状态 - **OCR 进度**：每页 OCR 完成跟踪 - **嵌入进度**：块级索引状态 - **任务取消**：长时间运行的操作的正常终止 --- ## 架构 ``` ┌──────────────┐ ┌─────────────────────────────┐ │ 输入层 │ → │ LangGraph 上传管道 │ → Markdown + *.graph.json │ （PDF/图像/...） │ │ （MemorySaver 检查点） │ └──────────────┘ └─────────────────────────────┘ │ ┌──────────────┐ ┌─────────────────────────────┐ │ 用户查询 │ → │ LangGraph RAG 工作流 │ └──────────────┘ │ （MemorySaver 检查点） │ └─────────────────────────────┘ │ ┌─────────────┴──────────────┐ │ 工具路由器（LLM 意图） │ │ （ToolExecutor.classify） │ └─────────────┬──────────────┘ │ ┌─────────────┴──────────────┐ │ │ 知识查询 计算任务 │ │ ┌───────────┴──────────────┐ ┌───────┴────────┐ │ RAG 路由器（推理器） │ │ 工具执行器 │ │ 跳跃分类器+路径选择 │ │ （MCP/本地） │ └───────────┬──────────────┘ └────────────────┘ │ ┌──────────────┼──────────────┐ │ │ │ 路径 1 路径 2 路径 3 向量 交叉引用 图数据库 搜索 Weaviate 引用 Neo4j Cypher （≤ 2 跳） （3-5 跳） （≥ 6 跳） │ ▼ ┌───────────────────────────────────────┐ │ 质量门（QualityEvaluator） │ │ 观察者 LLM（QUALITY_GATE_THRESHOLD） │ └────────────────┬──────────────────────┘ │ ┌─────────▼──────────────┐ │ 思维图扩展 │ │ 分支合并 + 修剪 │ └─────────┬──────────────┘ │ ┌──────▼──────┐ │ LLM 答案 │ └─────────────┘ ``` ### 核心组件 **推理模块** (`backend/notebooklm/reasoner/`): - `HopClassifier`：查询复杂度估计（LLM + 启发式备用） - `PathSelector`：回溯时的最佳检索路径选择 - `QualityEvaluator`：基于观察者 LLM 的结果质量评估 - `VectorRetriever`、`CrossRefRetriever`、`GraphDBRetriever`：模块化检索实现 ### 工作流图（查询） ``` planner → tool_router ┬→ rag_router →┬→ vector_retriever ──→┐ │ ├→ crossref_retriever ─→├→ quality_gate →┬→ thought_expander → aggregator → END │ └→ graphdb_retriever ──→┘ └→ rag_router (backtrack) │ └→ tool_executor ────────────────────────────────────────→ aggregator → END ``` **工具路由器**：LLM 驱动的意图分类决定查询路由策略： - **分类端点**：可通过 `TOOL_INTENT_CLASSIFIER_ENDPOINT` 配置（默认为 SGLang 生成器） - **意图类别**：`knowledge`、`calculation`、`database`、`api_call`、`code_exec` - **路由逻辑**： - `knowledge` → RAG 管道（3 路检索路由） - 其他意图 → 工具执行器（MCP/本地备用） - **备用机制**：当 LLM 分类失败时，使用启发式关键词匹配 **工具执行器** (`backend/notebooklm/tools/tool_executor.py`): - **MCP 集成**：在 `MCP_SERVER_ENABLED=true` 时，通过 MCP 服务器 REST API 进行主要执行 - **本地备用**：当 MCP 服务器不可用时，自动备用到本地实现 - **意图分类**：LLM 驱动的，具有启发式备用以确保可靠性 - **支持的工具**： - **计算器**（完全实现）： - 基于 AST 的安全表达式评估（无 `eval()` 安全风险） - 高级数学函数：`sqrt`、`cbrt`、`abs`、`log`、`ln`、`log10`、`exp`、`sin`、`cos`、`tan`、`sigma` - 自然语言解析："144의 제곱근" → `sqrt(144)`，"2的 3次方" → `2 ** 3` - 操作符支持：`+`、`-`、`*`、`/`、`**`、`%` - **API 调用者**（轻量级实现）： - HTTP GET/POST 请求执行 - 从自然语言提示中提取 URL - 可配置的超时和错误处理 - **代码运行器**（沙盒实现）： - 受限的 Python 执行环境 - 过滤的内置函数（无 `eval`、`exec`、`__import__`） - 基于令牌的安全过滤 - **SQL 执行器**（占位符）： - 返回 `not_implemented` 状态 - 为未来的数据库集成保留 --- ## 输入 / 预处理 由 `LangGraphUploadPipeline` (`langgraph_upload_pipeline.py`) 使用 `MemorySaver` 检查点处理： 1. **转换和布局**：`run_file_processor.py` 处理 PDF/Office/图像/音频输入 → `Results/1.Converted_images` + `Results/2.LayoutDetection`。 2. **OCR 和 Markdown**：`run_ocr_processing()` 使用 SGLang 驱动的 OCRFlux 生成每页 Markdown → `Results/4.OCR_results`。 3. **LLM 元数据提取**：`LLMMetadataExtractor` 从 Markdown 中提取实体/事件/关系 → `Results/8.graph_metadata/*.graph.json`。 - **块大小**：可通过 `GRAPH_EXTRACTOR_CHUNK_SIZE` 配置 - **超时**：可通过 `GRAPH_EXTRACTOR_API_TIMEOUT` 配置 - **重试逻辑**：超时时，SGLang 生成器服务器重启并重试相同的块一次 - **保持活动**：后台线程每 `SGLANG_KEEPALIVE_INTERVAL` 秒触摸一次服务器以保持活动 4. **图插入**： - `GraphSchemaManager` 确保 Weaviate GraphEntity/GraphEvent/GraphRelation 集合存在，具有交叉引用（源/目标/事件） - `LegacyGraphIngestor` / `Neo4jManager` 将节点/关系合并到 Neo4j，具有确定性的 UUID 5. **延迟分段和嵌入**：`embedding_text.py` 将 Markdown 分割成块，并通过 `SharedEmbeddingModel` 上传到 Weaviate TextDocument 集合（模型可通过 `EMBEDDING_MODEL` 配置）。 ## 模块映射 ``` backend/ ├── main.py # [Excluded] FastAPI 服务器入口点 ├── config.py # [Excluded] 服务器级配置 ├── logging_config.py # [Excluded] 日志配置 │ ├── api/ # API 层 │ ├── routes.py # [Excluded] 主要上传/文件/会话路由 │ ├── chat.py # [Excluded] POST /v1/chat 端点 │ ├── ocr_routes.py # [Excluded] OCR 处理端点 │ └── pause_api.py # [Excluded] 任务暂停/恢复 API │ ├── notebooklm/ # RAG 核心模块 │ ├── config.py # 模型/路径/图配置 │ ├── rag_pipeline.py # LangGraph RAG 工作流编排器 │ ├── graph_reasoner.py # LangGraph 工作流编排 │ ├── graph_schema.py # Weaviate 实体/事件/关系模式 │ ├── hop_classifier.py # 查询复杂度估计器 │ ├── reasoner/ # 重构的 GraphReasoner 模块 │ │ ├── state.py # GraphReasonerState 定义 │ │ ├── routing.py # 路径选择器，跳跃分类器 │ │ ├── quality.py # 质量评估器 │ │ ├── retrievers.py # 向量检索器，交叉引用检索器，图数据库检索器 │ │ └── __init__.py │ ├── legacy_graph_client.py # Neo4j Cypher 遍历客户端 │ ├── legacy_graph_ingestor.py # Neo4j 插入助手 │ ├── embedding_text.py # 延迟分块 + Weaviate 文本索引 │ ├── embedding_image.py # 图像嵌入 + Weaviate 图像索引 │ ├── image_processor.py # 图像处理实用程序 │ ├── shared_embedding.py # SGLang 嵌入/重新排序客户端（单例） │ ├── sglang_server_manager.py # SGLang 服务器生命周期管理器 │ ├── generator.py # LLM 答案生成 │ ├── refiner.py # 答案精炼 │ ├── evaluator.py # 答案质量评估 │ ├── router.py # 查询类型路由 │ ├── query_rewriter.py # 查询重写 │ ├── parallel_search.py # 并行文本 + 图像搜索 │ ├── weaviate_utils.py # Weaviate 客户端实用程序 │ ├── clean_weaviate.py # [Excluded] Weaviate + Neo4j 数据清理脚本 │ ├── tools/ # 工具调用 & MCP 集成 │ │ ├── mcp_client.py # MCP 服务器 REST 客户端 │ │ ├── tool_executor.py # 工具执行（MCP/本地备用） │ │ └── __init__.py │ ├── rag_text/ # 文本搜索 + 重新排序 │ └── rag_image/ # 图像搜索 + 重新排序 │ ├── mcp_server/ # MCP（模型上下文协议）工具服务器 │ └── main.py # 工具执行的 FastAPI 服务器 │ ├── data_pipeline/ # 数据处理管道 │ └── pipe/ │ ├── langgraph_upload_pipeline.py # LangGraph 上传工作流（带检查点） │ ├── llm_metadata_extractor.py # 实体/事件/关系提取 │ ├── neo4j_manager.py # Neo4j 插入管理器 │ ├── run_file_processor.py # 转换/布局/OCR 编排器 │ ├── pipeline_image.py # 图像管道 │ ├── pipeline_sound.py # 音频管道 │ └── main_pipe/ │ ├── ocr_pipe/ # 基于 SGLang 的 OCRFlux 引擎 │ ├── udp_pdftopng_300dpi.py # PDF → PNG 转换 │ └── udp_layoutdetection.py # 布局检测 │ ├── services/ # 业务逻辑服务 │ ├── model_manager.py # [Excluded] LazyModelManager（GPU 生命周期） │ ├── ocr_vision_manager.py # [Excluded] OCR 引擎管理 │ └── rag_service.py # [Excluded] RAG 服务编排 │ └── utils/ ├── task_queue.py # [Excluded] GPU 任务队列（异步作业管理） ├── helpers.py # [Excluded] 共享实用函数 ├── path_helpers.py # [Excluded] 路径计算助手 └── file_utils.py # [Excluded] 文件操作实用程序 ``` --- ## 数据管道 1. **文件上传** (`POST /upload/files`) - `api/routes.py` 将文件存储在每个会话的文件夹中，并通过 `task_queue.py` 排队 `run_processing_pipeline`。 2. **GPU 任务队列** - `task_queue.py` 管理顺序的 GPU 绑定任务（转换 → 布局 → OCR），并跟踪进度。 3. **文本索引** (`run_text_indexing` / `run_text_indexing_v2`) - 初始化 `SharedEmbeddingModel` → 运行 `process_markdown_files` 进行 Weaviate 延迟分块索引。 4. **图提取和摄入** - `LLMMetadataExtractor` 生成 `*.graph.json` → `GraphSchemaManager` 插入到 Weaviate → `Neo4jManager` / `LegacyGraphIngestor` 插入到 Neo4j。 5. **存储状态** - Weaviate：TextDocument + GraphEntity/Event/Relation 集合。 - Neo4j：具有确定性 UUID 和自动创建约束的实体/事件节点 + 关系边。 --- ## 查询处理流程 1. **请求启动**: `POST /v1/chat` → `RAGPipeline.process_query()` 调用 `GraphReasoner.retrieve()` 2. **LangGraph 工作流执行** (`graph_reasoner.py`) : * **步骤 1：规划器** (`planner` 节点) - 分析用户查询并提取关键概念 - 记录高级别搜索计划和推理步骤 - 初始化查询历史以进行多轮对话 - **输出**: `plan`, `query_analysis` * **步骤 2：工具路由器** (`tool_router` 节点) - LLM 通过 `ToolExecutor.classify_intent()` 分类查询意图： - `knowledge` → 路由到 **分支 A**（RAG 路由器） - `calculation`, `database`, `api_call`, `code_exec` → 路由到 **分支 B**（工具执行器） - **输出**: `intent`, 路由决策 **[分支 A：知识查询路径]** * **步骤 3a：RAG 路由器** (`rag_router` 节点，用于知识查询) - 执行跳跃分类（LLM + 启发式混合） - 设置 `max_hops` = `min(llm_estimate, heuristic_estimate, GRAPH_MAX_HOPS)` - 选择初始检索路径： - hop ≤ 2 → `vector_retriever`（路径 1） - hop 3–5 → `crossref_retriever`（路径 2） - hop ≥ 6 → `graphdb_retriever`（路径 3） - **输出**: `max_hops`, `retrieval_path`, `tried_paths` * **步骤 4a：检索执行**（路径 1/2/3） - **路径 1**: 对 TextDocument 进行语义搜索 + 重新排序 - **路径 2**: BM25 种子搜索 + Weaviate 交叉引用多跳遍历 - **路径 3**: Neo4j Cypher 深度图遍历 - **输出**: `context_snippets`, `entities`, `events`, `relations` * **步骤 5a：质量门** (`quality_gate` 节点) - 观察 LLM 评分检索结果（0.0–1.0） - **如果质量 ≥ `QUALITY_GATE_THRESHOLD`**：继续到聚合器或思维扩展器 - **如果质量 < 阈值**：触发智能回溯（`PathSelector` 分析剩余路径，选择替代路径并返回步骤 4a） - **终止**：在 `MAX_BACKTRACK_COUNT` 次重试或所有路径耗尽后 - **输出**: `retrieval_quality`, `backtrack_count`, `tried_paths` * **步骤 6a：思维扩展器** (`thought_expander` 节点，如果 `GOT_MODE_ENABLED=true`) - 并行扩展 `GOT_BRANCH_FACTOR` 个候查询分支 - 观察 LLM 评分每个分支（0.0–1.0） - 合并高于 `GOT_THOUGHT_SCORE_THRESHOLD` 的分支并修剪低质量边 - 基于快照的连续失败回溯 - **输出**: `thought_steps`, 扩展上下文 **[分支 B：工具执行路径]** * **步骤 3b：工具执行器** (`tool_executor` 节点，用于计算任务) - 将意图映射到特定工具 (`calculation`, `api_call`, `code_exec`, `database`) - 准备工具输入（例如，将自然语言 "144的平方根" 转换为 `sqrt(144)`） - 执行工具（MCP-first 架构，带有本地备用） - **输出**: 带有状态 (`ok`/`error`)、结果值、元数据的 `tool_result` **[合并节点]** * **步骤 7：聚合器** (`aggregator` 节点) - **对于 RAG 查询**：从实体/事件/关系/思维构建上下文片段 - **对于工具查询**：将工具结果格式化为自然语言（`"expression = result"` 等） - 收集元数据 (`context_snippets`, `thought_steps`, `backtrack_count`, `tried_paths`, `tool_result`) - **输出**: 聚合上下文或格式化的工具结果 3. **答案生成**： - **对于 RAG 查询**：`generator.py` 从原始查询 + 上下文片段合成答案 - **对于工具查询**：直接返回格式化的工具结果（无需 LLM 生成） - **可选后处理**：`refiner.py` 精炼答案，`evaluator.py` 记录质量备注 4. **响应构造** (`RAGPipeline._build_response()` 或 `_build_tool_only_response()`)： - **对于 RAG 查询**：包含答案、上下文、片段、搜索结果的完整响应 - **对于工具查询**：包含工具结果作为答案的精简响应 - **包含元数据**：`plan`, `max_hops`, `retrieval_quality`, `backtrack_count`, `tried_paths`, `thought_steps`, `tool_result` - **调试支持**：为可追溯性暴露所有工作流状态 5. **返回给客户端**：带有答案、元数据和调试信息的 JSON 响应 --- ## 关键设置 (`notebooklm/config.py`) - **图 RAG 开关**: `GRAPH_RAG_ENABLED`, `LANGGRAPH_ENABLED`, `GOT_MODE_ENABLED`, `GRAPH_MAX_HOPS`。 - **GoT 调整**: `GOT_BRANCH_FACTOR`, `GOT_MERGE_STRATEGY` (`top_k`/`weighted_union`/`vote`), `GOT_MERGE_TOP_K`, `GOT_THOUGHT_SCORE_THRESHOLD`, `GOT_EDGE_PRUNE_THRESHOLD`, `GOT_MAX_STEPS`, `GOT_MAX_CONSECUTIVE_FAILURES`, `GOT_OBSERVER_ENDPOINT`/`GOT_OBSERVER_MODEL`。 - **Neo4j**: `NEO4J_URI`, `NEO4J_USER`, `NEO4J_PASSWORD`, `GRAPH_MAX_HOPS`。 - **Weaviate**: `WEAVIATE_HOST/PORT`, `WEAVIATE_TEXT_CLASS` (TextDocument), `WEAVIATE_VECTORIZER` (text2vec-model2vec)。 - **SGLang 模型**: `LLM_MODEL`, `EMBEDDING_MODEL`, `RERANKER_MODEL`, `REFINER_MODEL`, `QUERY_REWRITER_MODEL`。 - **SGLang 服务器**: `SGLANG_GENERATOR_ENDPOINT`, `SGLANG_EMBEDDING_ENDPOINT`, `SGLANG_RERANKER_ENDPOINT`, `SGLANG_REFINER_ENDPOINT`, `SGLANG_QUERY_REWRITER_ENDPOINT`。 - **SGLang 生命周期**: `SGLANG_IDLE_TIMEOUT` (60s), `SGLANG_KEEPALIVE_INTERVAL` (20s)。 - **图提取器**: `GRAPH_EXTRACTOR_API_TIMEOUT` (60s), `GRAPH_EXTRACTOR_CHUNK_SIZE` (800), `GRAPH_EXTRACTOR_RETRY_ON_FAILURE` (true)。 - **会话目录**: `DATA_ROOT/Results`, `sessions/<id>` 布局。 --- ## MCP 工具服务器 MCP（模型上下文协议）服务器是一个独立的 FastAPI 服务，负责为 LangGraph RAG 系统执行计算工具。它提供了一个用于执行计算工具（如计算器、SQL 查询、API 调用和代码执行）的 REST API。 ### 功能 - **计算器**: 基于 AST 的安全数学表达式求值 - **SQL 执行器**: SQL 查询执行（可扩展） - **API 调用者**: 外部 API 调用（可扩展） - **代码运行器**: 代码执行沙箱（可扩展） --- ### 添加新工具 1. 在 `main.py` 中实现执行器函数 2. 在 `TOOL_REGISTRY` 中注册 3. 重启服务器 ```python def execute_my_tool(inputs: Dict[str, Any]) -> ToolExecuteResponse: # 实现 return ToolExecuteResponse(status="ok", result=...) TOOL_REGISTRY["my_tool"] = { "executor": execute_my_tool, "info": ToolInfo( name="my_tool", description="Description of my tool", parameters={...} ) } ``` --- ## API 亮点 | 端点 | 描述 | |---|---| | `POST /upload/files` | 触发 LangGraph 上传管道 | | `POST /v1/chat` | 运行带有检查点/回溯的三方 RAG | | `GET /api/v1/tasks/{task_id}` | 监视排队的上传/OCR 任务 | | `GET /files` | 列出会话工件 | | `POST /pause` | 暂停/恢复后台任务 | --- ## 日志和运维 - `sglang_embedding_server.log`, `sglang_reranker_server.log` – SGLang 模型服务器健康状况。 - `Results/8.graph_metadata/*.graph.json` – LLM 提取结果存档。 - `LegacyGraphIngestor` 在首次运行时自动创建约束；无需手动设置。 - `SGLangServerManager` 在空闲 60 秒后释放 GPU 内存（可通过 `SGLANG_IDLE_TIMEOUT` 配置）。 - 所有 LangGraph 工作流都记录检查点 ID 和回溯计数以便追溯。 - **SGLang 冷启动**：延迟加载意味着第一个 `/v1/chat`（或跳跃分类器）请求必须预热每个 SGLang 服务器，这可能需要 20–60 秒的 VRAM 加载时间；发出预热请求或保持活动 cron 以避免客户端超时。 - **分块重试机制**：如果 LLM 元数据提取超时（默认 60 秒），则自动重启生成器服务器并重试相同的分块一次。这可以防止在有问题的分块上挂起，同时保持提取质量。 - **易失性检查点**：`MemorySaver` 在进程中存储图快照，因此任何 FastAPI 重启都会在计划迁移到 `SqliteSaver`/`PostgresSaver` 之前丢弃飞行中的状态。 - **Weaviate v4 API**: 使用 `weaviate.connect_to_custom()`，带有 gRPC 支持（端口 50051）。 --- ## 路线图 1. ~~**GoT（思维图）**~~ - `thought_expander` 现在使用图状探索：每个步骤扩展 `GOT_BRANCH_FACTOR` 分支，一个观察者 LLM 评估每个分支，并通过 `GOT_MERGE_STRATEGY` 合并最佳结果。修剪低质量边，连续失败触发基于快照的回溯。 2. **高级跳跃分类器** - 结合查询元数据（令牌长度，实体计数）进行混合路由器。 3. **多图检索优化** - 改进 3-5 跳跃 Weaviate 遍历的上下文过滤/重复数据删除，并为 ≥ 6 跳跃 Neo4j 探索添加 Cypher 模板。 4. **LangGraph 工作流可观察性** - 发出每个节点的延迟/错误指标，并在 `GraphReasoner` 和 `LegacyGraphClient` 中集成重试策略。 5. **持久检查点** - 从 `MemorySaver` 迁移到 `SqliteSaver` / `PostgresSaver` 以进行跨会话状态恢复。 --- ## 贡献与联系 欢迎提出问题和拉取请求。如有疑问或顾虑，请在 GitHub 上提出问题或发送电子邮件至 **koto144@gmail.com**。 --- ## 许可证 该项目双重许可： - **MIT 许可证** - 参见 [LICENSE](LICENSE) 文件了解详情 - **Apache License 2.0** - 参见 [LICENSE-APACHE](LICENSE-APACHE) 文件了解详情 您可以选择其中一个许可证来管理对该软件的使用。 --- ## 引用 如果您在研究中使用此项目，请引用以下内容： ### SGLang ```bibtex @misc{zheng2023sglang, title={SGLang: Efficient Execution of Structured Language Model Programs}, author={Lianmin Zheng and Liangsheng Yin and Zhiqiang Xie and Jeff Huang and Chuyue Sun and Cody Hao Yu and Shiyi Cao and Christos Kozyrakis and Ion Stoica and Joseph E. Gonzalez and Clark Barrett and Ying Sheng}, year={2023}, url={https://github.com/sgl-project/sglang} } ``` ### LangGraph ```bibtex @software{langgraph2024, title={LangGraph: A Framework for Building Stateful Multi-Actor Applications}, author={LangChain AI}, year={2024}, url={https://github.com/langchain-ai/langgraph} } ``` ### Weaviate ```bibtex @software{weaviate2024, title={Weaviate: An Open-Source Vector Database}, author={Weaviate B.V.}, year={2024}, url={https://github.com/weaviate/weaviate} } ``` ### Neo4j ```bibtex @software{neo4j2024, title={Neo4j: The Graph Database Platform}, author={Neo4j, Inc.}, year={2024}, url={https://github.com/neo4j/neo4j} } ``` ### OCRFlux ```bibtex @software{ocrflux2024, title={OCRFlux: Vision-Language Model for OCR}, author={ChatDOC}, year={2024}, url={https://huggingface.co/ChatDOC/OCRFlux-3B} } ```