查询、图谱与 Ollama API 路由
查询、图谱与 Ollama API 路由
相关源文件
以下文件为本维基页面的生成提供了上下文：
lightrag/api/routers/__init__.pylightrag/api/routers/graph_routes.pylightrag/api/routers/ollama_api.pylightrag/api/routers/query_routes.pylightrag/utils_graph.pytests/test_aquery_data_endpoint.pytests/test_description_api_validation.pytests/test_lightrag_ollama_chat.py
LightRAG API 提供了一套全面的端点，用于与检索增强生成（RAG）引擎交互、管理底层知识图谱，以及模拟 Ollama API 以实现第三方集成。这些路由通过工厂函数动态生成，以确保工作空间隔离，并防止在多租户或测试环境中出现路由重复 lightrag/api/routers/__init__.py:4-10。
查询端点
查询系统支持三种主要的交互模式：标准 JSON 响应、用于实时输出的流式 NDJSON，以及用于调试和评估的富数据端点。所有查询路由均使用 QueryRequest Pydantic 模型 lightrag/api/routers/query_routes.py:14-110。
QueryRequest 模型
QueryRequest 模型作为所有检索操作的统一接口，将 API 参数桥接到内部的 QueryParam 类 lightrag/api/routers/query_routes.py:130-141。
| 参数 | 类型 | 描述 |
|---|---|---|
query | str | 自然语言查询 lightrag/api/routers/query_routes.py:15-18。 |
mode | Literal | local、global、hybrid、naive、mix 或 bypass lightrag/api/routers/query_routes.py:20-23。 |
top_k | int | 要检索的实体（本地模式）或关系（全局模式）数量 lightrag/api/routers/query_routes.py:41-45。 |
stream | bool | 为 /query/stream 端点启用流式传输 lightrag/api/routers/query_routes.py:106-109。 |
only_need_context | bool | 如果为 true，则仅返回检索到的上下文，不进行大语言模型（LLM）生成 lightrag/api/routers/query_routes.py:25-28。 |
路由定义
- POST
/query：返回一个包含生成文本和可选引用的QueryResponselightrag/api/routers/query_routes.py:155-163。 - POST
/query/stream：以 NDJSON 格式返回StreamChunkResponse对象的StreamingResponselightrag/api/routers/query_routes.py:176-189。 - POST
/query/data：返回一个QueryDataResponse，其中包含检索过程中使用的原始实体、关系和片段lightrag/api/routers/query_routes.py:165-174。
来源： lightrag/api/routers/query_routes.py:14-189，tests/test_aquery_data_endpoint.py:100-146
图谱管理路由
图谱路由允许手动检查和修改知识图谱。这些操作会与向量数据库同步，以保持一致性 lightrag/utils_graph.py:23-64。
子图检索
GET /graphs 端点允许用户检索以特定节点标签为中心的连通子图 lightrag/api/routers/graph_routes.py:163-182。
- 优先级：当超过
max_nodes限制时，节点会优先按与起始节点的路径跳数排序，然后按节点度数排序lightrag/api/routers/graph_routes.py:172-173。
图谱修改操作
LightRAG 对手动图谱编辑实施严格校验，特别是要求非空描述，以确保检索增强生成（RAG）质量 lightrag/utils_graph.py:14-20。
| 端点 | 请求模型 | 操作 |
|---|---|---|
POST /graph/entity/edit | EntityUpdateRequest | 更新实体属性或重命名节点 lightrag/api/routers/graph_routes.py:14-19。 |
POST /graph/entity/merge | EntityMergeRequest | 将重复或拼写错误的实体合并到目标实体 lightrag/api/routers/graph_routes.py:27-40。 |
POST /graph/relation/create | RelationCreateRequest | 手动在现有实体之间建立链接 lightrag/api/routers/graph_routes.py:61-84。 |
数据流：实体删除
当通过 API 删除实体时，系统会触发跨所有存储层的级联清理。
图示：实体删除逻辑
来源： lightrag/utils_graph.py:66-160，lightrag/api/routers/graph_routes.py:14-84
Ollama API 模拟
OllamaAPI 类提供了一个兼容层，允许 LightRAG 在 Open WebUI 等工具中作为 Ollama 的直接替代品使用 lightrag/api/routers/ollama_api.py:220-227。
查询模式解析
由于 Ollama API 本身不支持检索增强生成（RAG）的"模式"，LightRAG 在查询字符串中使用基于前缀的解析策略来确定检索策略 lightrag/api/routers/ollama_api.py:165-217。
| 前缀示例 | 解析后的模式 |
|---|---|
/local query | SearchMode.local |
/global query | SearchMode.global_ |
/hybrid[prompt] query | SearchMode.hybrid + 自定义用户提示 |
/context query | SearchMode.mix + only_need_context=True |
实现细节
- 端点模拟：实现了
/api/chat、/api/generate、/api/tags和/api/pslightrag/api/routers/ollama_api.py:233-280。 - Token 估算：使用
TiktokenTokenizer估算提示和响应的 Token 数，以生成 Ollama 兼容的元数据lightrag/api/routers/ollama_api.py:159-162。 - 流式传输：支持 Ollama 客户端期望的
application/x-ndjson流式响应lightrag/api/routers/ollama_api.py:317-320。
图示：Ollama 请求转换
来源： lightrag/api/routers/ollama_api.py:165-227，lightrag/api/routers/ollama_api.py:285-350，tests/test_lightrag_ollama_chat.py:4-10
实现技术总结
路由器工厂模式
为了避免 FastAPI 中出现"重复操作 ID"警告（尤其是在并行测试期间），路由器在工厂函数内部创建。这确保了每次初始化 LightRAG 实例时，它都会获得一组绑定到其特定存储上下文的新路由 lightrag/api/routers/graph_routes.py:87-92，lightrag/api/routers/__init__.py:4-10。
统一持久化
任何修改图谱的操作（创建、编辑、合并、删除）都会以调用 _persist_graph_updates 结束。该函数使用 asyncio.gather 在所有涉及的存储后端（图谱、向量和键值存储）上并行执行 index_done_callback()，以确保类似 ACID 的持久性 lightrag/utils_graph.py:23-64。
来源： lightrag/api/routers/graph_routes.py:87-92，lightrag/utils_graph.py:23-64