agentic_huge_data_base / wiki
页面 LightRAG · 4.5 Ollama API 兼容性·DeepWiki 中文全文译文
DeepWiki 中文译文 / LightRAG / 4.5

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

轻量图谱增强检索 · 本章是 LightRAG DeepWiki 中文译文的独立章节页，保留原始链接、源码锚点、模块标签和章节层级。

项目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 重组后的对应页面（来源：6-2.zh.md）
翻译时间：2026-05-27T12:17:56.000Z
翻译模型：deepseek-chat
项目：LightRAG (lightrag)

---

查询、图谱与 Ollama API 路由

相关源文件

以下文件为本维基页面的生成提供了上下文：

  • lightrag/api/routers/__init__.py
  • lightrag/api/routers/graph_routes.py
  • lightrag/api/routers/ollama_api.py
  • lightrag/api/routers/query_routes.py
  • lightrag/utils_graph.py
  • tests/test_aquery_data_endpoint.py
  • tests/test_description_api_validation.py
  • tests/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。

参数类型描述
querystr自然语言查询 lightrag/api/routers/query_routes.py:15-18。
modeLiterallocal、global、hybrid、naive、mix 或 bypass lightrag/api/routers/query_routes.py:20-23。
top_kint要检索的实体（本地模式）或关系（全局模式）数量 lightrag/api/routers/query_routes.py:41-45。
streambool为 /query/stream 端点启用流式传输 lightrag/api/routers/query_routes.py:106-109。
only_need_contextbool如果为 true，则仅返回检索到的上下文，不进行大语言模型（LLM）生成 lightrag/api/routers/query_routes.py:25-28。
路由定义
  1. POST /query：返回一个包含生成文本和可选引用的 QueryResponse lightrag/api/routers/query_routes.py:155-163。
  2. POST /query/stream：以 NDJSON 格式返回 StreamChunkResponse 对象的 StreamingResponse lightrag/api/routers/query_routes.py:176-189。
  3. 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/editEntityUpdateRequest更新实体属性或重命名节点 lightrag/api/routers/graph_routes.py:14-19。
POST /graph/entity/mergeEntityMergeRequest将重复或拼写错误的实体合并到目标实体 lightrag/api/routers/graph_routes.py:27-40。
POST /graph/relation/createRelationCreateRequest手动在现有实体之间建立链接 lightrag/api/routers/graph_routes.py:61-84。
数据流：实体删除

当通过 API 删除实体时，系统会触发跨所有存储层的级联清理。

图示：实体删除逻辑

graph TD
    subgraph "API 层"
        A["DELETE /documents/entity"] --> B["adelete_by_entity"]
    end

    subgraph "存储编排 (utils_graph.py)"
        B --> C["get_storage_keyed_lock"]
        C --> D["chunk_entity_relation_graph.delete_node"]
        C --> E["entities_vdb.delete_entity"]
        C --> F["relationships_vdb.delete_entity_relation"]
        C --> G["entity_chunks_storage.delete"]
    end

    subgraph "持久化"
        D & E & F & G --> H["_persist_graph_updates"]
        H --> I["index_done_callback()"]
    end

来源： 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 querySearchMode.local
/global querySearchMode.global_
/hybrid[prompt] querySearchMode.hybrid + 自定义用户提示
/context querySearchMode.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 请求转换

sequenceDiagram
    participant Client as "Open WebUI / Ollama 客户端"
    participant OAPI as "OllamaAPI (ollama_api.py)"
    participant RAG as "LightRAG (lightrag.py)"

    Client->>OAPI: POST /api/chat { "messages": [{"content": "/local who is... "}] }
    OAPI->>OAPI: parse_query_mode()
    Note over OAPI: 提取 mode="local", query="who is..."
    OAPI->>RAG: aquery(query, QueryParam(mode="local"))
    RAG-->>OAPI: 响应字符串
    OAPI->>OAPI: TiktokenTokenizer.encode()
    Note over OAPI: 计算 eval_count / duration
    OAPI-->>Client: OllamaChatResponse (JSON)

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