6 · LLM 与外部服务（LLM and External Services）

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

项目LightRAG 章节6 状态全文译文模块检索、召回与索引、模型调用与提供方适配、接口与服务契约、系统架构

项目要点页2.5 参考项目项目章节目录LightRAG DeepWiki 原始章节LLM and External Services 上一章5.6 下一章6.1

源码线索

examples/unofficial-sample/lightrag_embedding_prefixes.py
lightrag/llm/anthropic.py
lightrag/llm/azure_openai.py
lightrag/llm/bedrock.py
lightrag/llm/deprecated/siliconcloud.py
lightrag/llm/gemini.py
lightrag/llm/hf.py
lightrag/llm/jina.py
lightrag/llm/llama_index_impl.py
lightrag/llm/lmdeploy.py

模块标签

检索、召回与索引
模型调用与提供方适配
接口与服务契约
系统架构
测试、发布与运维

中文译文

REST API 服务端（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/HKUDS/LightRAG/6-rest-api-server

翻译时间：2026-05-27T08:45:11.684Z

翻译模型：deepseek-chat

原文字符数：5972

项目：LightRAG (lightrag)

---

REST 接口服务器

系统架构总览

该服务器作为 LightRAG 核心类的管理层，处理多租户工作空间隔离、认证和请求编排。

graph TD
    subgraph "客户端空间"
        ["WebUI/外部应用"] -- "HTTP/JSON" --> ["FastAPI 服务器"]
    end

    subgraph "代码实体空间：lightrag-server"
        ["FastAPI 服务器"] --> ["create_app 工厂"]
        ["create_app 工厂"] --> ["combined_auth 依赖"]
        ["create_app 工厂"] --> ["create_query_routes"]
        ["create_app 工厂"] --> ["create_document_routes"]
        ["create_app 工厂"] --> ["create_graph_routes"]
        ["create_app 工厂"] --> ["OllamaAPI 仿真"]
    end

    subgraph "核心引擎空间"
        ["路由"] --> ["LightRAG 实例"]
        ["LightRAG 实例"] --> ["存储后端"]
    end

    ["combined_auth 依赖"] -.-> ["auth_handler"]
    ["LightRAG 实例"] -.-> ["_GlobalArgsProxy"]

来源：lightrag/api/lightrag_server.py:1-56, lightrag/api/lightrag_server.py:1021-1050, lightrag/api/utils_api.py:91-127

关键组件

组件	代码实体	职责
应用工厂	`create_app`	初始化 FastAPI，挂载 WebUI 的静态文件，并附加路由器。 `lightrag/api/lightrag_server.py:1021-1050`
全局配置	`_GlobalArgsProxy`	一个延迟加载的代理，管理系统范围的参数以及大语言模型（LLM）/嵌入向量配置。 `lightrag/api/lightrag_server.py:284-333`
认证处理器	`auth_handler`	管理 JWT 生成、校验和 OAuth2 密码流程。 `lightrag/api/auth.py:25-50`
工作空间管理器	`LIGHTRAG-WORKSPACE`	基于请求头的隔离机制，允许单个服务器实例管理多个逻辑知识图谱。 `lightrag/api/lightrag_server.py:1052-1085`
Ollama 仿真	`OllamaAPI`	提供如 `/api/chat` 等端点，允许 Open WebUI 等工具将 LightRAG 用作后端。 `lightrag/api/routers/ollama_api.py:18-40`

---

服务器配置与启动

服务器通过环境变量（在 .env 中定义）和由 parse_args 解析的命令行参数组合进行配置。一个关键组件是 LLMConfigCache，它会智能地缓存特定于供应商的选项（OpenAI、Ollama、Gemini 等），以确保每个请求的 RAG 引擎快速初始化。

服务器支持通过 Gunicorn/Uvicorn 进行生产部署，并支持可配置的工作进程数量和超时时间。它还实现了一个 lifespan 上下文管理器，用于处理共享存储数据和锁的优雅初始化和终结。

详情请参见服务器配置与启动。

来源： lightrag/api/lightrag_server.py:131-230, lightrag/api/config.py:1-49, env.example:1-40

---

查询、图谱和 Ollama API 路由

API 被组织为功能路由器：

查询路由： 实现 /query、/query/stream 和 /query/data 端点。这些端点接受 QueryRequest 模型，并映射到核心引擎的 aquery 方法。
图谱路由： 提供对知识图谱的深度访问，包括子图检索、实体编辑和关系合并。
Ollama 仿真： 一个专门的路由器，模拟 Ollama API，实现与更广泛的大语言模型（LLM）工具生态系统的无缝集成。

详情请参见查询、图谱和 Ollama API 路由。

来源： lightrag/api/routers/query_routes.py:1-30, lightrag/api/routers/graph_routes.py:1-30, lightrag/api/routers/ollama_api.py:1-50

---

认证与安全

LightRAG 实现了多层安全模型：

基于 JWT 的认证： 支持 OAuth2 密码流程，并支持可配置的令牌过期时间（TOKEN_EXPIRE_HOURS）。
API 密钥访问： 请求可以通过 X-API-Key 请求头进行认证。
令牌自动续期： 一种滑动窗口机制（TOKEN_AUTO_RENEW），当用户在令牌即将过期时处于活跃状态，会发出一个 X-New-Token 请求头。
白名单支持： 允许特定路径（如 /health）绕过认证。

详情请参见认证与安全。

来源： lightrag/api/auth.py:1-60, lightrag/api/utils_api.py:120-175, lightrag/api/config.py:159-169

---

API 交互流程

下图展示了请求如何从网络流入核心代码实体。

sequenceDiagram
    participant C as 客户端 (WebUI/Curl)
    participant S as FastAPI (lightrag_server)
    participant A as combined_auth (utils_api)
    participant R as 路由器 (query_routes)
    participant E as 核心引擎 (lightrag.py)

    C->>S: POST /query (请求头：X-API-Key 或 Authorization)
    S->>A: 校验凭证
    alt 无效
        A-->>C: 401 未授权
    else 有效
        A->>S: 继续执行
        S->>R: handle_query(QueryRequest)
        R->>E: rag_instance.aquery(query, query_param)
        E-->>R: 响应文本/流
        R-->>C: JSON 响应
    end

来源：lightrag/api/lightrag_server.py:1021-1050, lightrag/api/utils_api.py:120-135, lightrag/api/routers/query_routes.py:80-110