4.5 · Ollama API 兼容性（Ollama API Compatibility）

轻量图谱增强检索 · 聚焦本章的模块关系、源码依据与实现要点。

项目LightRAG 章节4.5 状态全文译文模块接口与服务契约、记忆与上下文、检索、召回与索引、配置治理

项目要点页2.5 参考项目项目章节目录LightRAG DeepWiki 原始章节Ollama API Compatibility 上一章4.4 下一章4.6

源码线索

lightrag/api/routers/ollama_api.py
lightrag/api/routers/query_routes.py
lightrag/evaluation/__init__.py
lightrag/evaluation/eval_rag_quality.py

模块标签

接口与服务契约
记忆与上下文
检索、召回与索引
配置治理
评测、反馈与人工复核

章节正文

Ollama API 兼容性

原始 DeepWiki 页面https://deepwiki.com/HKUDS/LightRAG/4.5-ollama-api-compatibility

此页面内容来自 DeepWiki 重组后的对应页面（来源：6-2.zh.md）

查询、图谱与 Ollama API 路由

查询端点

查询系统支持三种主要的交互模式：标准 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：返回一个包含生成文本和可选引用的 QueryResponse lightrag/api/routers/query_routes.py:155-163。
POST /query/stream：以 NDJSON 格式返回 StreamChunkResponse 对象的 StreamingResponse lightrag/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 · 数据流：实体删除 · 图 1

来源： 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/ps lightrag/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 · 实现细节 · 图 2

来源： 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