agentic_huge_data_base / wiki
页面 LightRAG · 5.1 前端架构·DeepWiki 中文全文译文
DeepWiki 中文译文 / LightRAG / 5.1

5.1 · 前端架构（Frontend Architecture）

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

项目LightRAG 章节5.1 状态全文译文 模块系统架构、界面与交互、配置治理、认证、权限与安全
项目要点页2.5 参考项目 项目章节目录LightRAG DeepWiki 原始章节Frontend Architecture 上一章5 下一章5.2
源码线索
  • lightrag_webui/src/App.tsx
  • lightrag_webui/src/AppRouter.tsx
  • lightrag_webui/src/features/LoginPage.tsx
  • lightrag_webui/src/features/SiteHeader.tsx
  • lightrag_webui/src/index.css
  • lightrag_webui/src/lib/extensions.ts
  • lightrag_webui/src/main.tsx
  • lightrag_webui/src/services/navigation.ts
  • lightrag_webui/src/stores/state.ts
  • lightrag_webui/src/types/katex.d.ts
模块标签
  • 系统架构
  • 界面与交互
  • 配置治理
  • 认证、权限与安全
  • 图谱与关系

章节正文

文档路由与管线编排

原始 DeepWiki 页面https://deepwiki.com/HKUDS/LightRAG/5.1-document-routes-and-pipeline-orchestration

文档路由与管线编排

相关源文件

本章引用的主要源码文件：

  • docs/LightRAG-API-Server-zh.md
  • docs/LightRAG-API-Server.md
  • lightrag/api/gunicorn_config.py
  • lightrag/api/routers/document_routes.py
  • lightrag/api/run_with_gunicorn.py
  • lightrag/kg/shared_storage.py
  • lightrag/parser_routing.py
  • lightrag/pipeline.py
  • lightrag/utils_pipeline.py
  • tests/test_api_config_bedrock.py
  • tests/test_document_routes_docx_archive.py
  • tests/test_pipeline_release_closure.py

本文详细介绍了基于 FastAPI 的文档管理路由以及底层多阶段入库管线。系统采用级联工作队列架构来管理文档从原始上传到知识图谱（KG）集成的状态转换。

API 端点与文档管理

document_routes.py 模块定义了文档操作的 RESTful 接口。这些路由与 LightRAG 实例及其 DocStatusStorage 交互，以跟踪每个文件的生命周期。

关键路由
端点方法函数描述
/documents/uploadPOSTupload_documents接收多部分文件上传，对文件名进行消毒处理，并将其移动到工作区输入目录。
/documents/scanPOSTscan_documents触发对输入目录的后台扫描，以检测新增、修改或删除的文件。
/documents/insert_textPOSTinsert_text直接将原始文本内容插入管线，无需物理文件。
/documents/deleteDELETEdelete_documents从存储中移除文档，并触发对关联的知识图谱实体和向量的清理。
/documents/statusGETget_document_status返回文档的当前处理状态和元数据。

来源：lightrag/api/routers/document_routes.py:17-47、lightrag/api/routers/document_routes.py:465-485、lightrag/api/routers/document_routes.py:734-754

文件名消毒与提示

为防止路径遍历攻击，服务器会通过移除分隔符和控制字符来对文件名进行消毒 lightrag/api/routers/document_routes.py:107-150。LightRAG 支持在文件名中嵌入"解析器提示"（例如 doc.[native-iet].pdf），允许用户在上传时指定解析器引擎和处理选项（如 i 表示图片，t 表示表格）lightrag/parser_routing.py:47-51、lightrag/parser_routing.py:155-162。

管线编排

编排逻辑实现在 _PipelineMixin 中，该混入类被主 LightRAG 类继承。它通过多个异步队列来管理文档的流转。

级联工作队列

管线使用一系列 asyncio.Queue 对象将文档传递给专门的处理器。这种架构允许不同阶段并行处理（例如，在解析一个文档的同时从另一个文档中提取实体）。

数据流图：文档入库管线

LightRAG · 级联工作队列 · 图 1
LightRAG · 级联工作队列 · 图 1

来源：lightrag/pipeline.py:173-191、lightrag/pipeline.py:350-410、lightrag/pipeline.py:535-590

处理器阶段
  1. 解析：根据所选解析器引擎，文档被路由到 q_native、q_mineru 或 q_docling。处理器将文件转换为通用的中间格式（Sidecar）lightrag/pipeline.py:640-670。
  2. 分析：_pipeline_analyze_worker 处理多模态内容（图片、表格），如果启用，会使用视觉语言模型（VLM）lightrag/pipeline.py:730-760。
  3. 提取：_pipeline_process_worker 执行文本片段切分以及由大语言模型（LLM）驱动的实体/关系提取 lightrag/pipeline.py:810-850。

锁定策略与并发

为确保跨多个进程（尤其是在使用 Gunicorn 运行时）的数据一致性，LightRAG 通过 shared_storage.py 采用了一套复杂的锁定策略。

管线状态标志

系统在共享内存中维护一个 pipeline_status 字典，包含几个关键标志：

  • busy：表示管线当前正在处理文档 lightrag/api/routers/document_routes.py:157-159。
  • scanning：在目录扫描进行中时设置，以防止并发扫描 lightrag/api/routers/document_routes.py:1360-1370。
  • destructive_busy：在修改模式或删除大型数据集等操作期间设置，会阻止所有其他管线活动 lightrag/api/routers/document_routes.py:1410-1420。
锁定原语

LightRAG 使用 KeyedUnifiedLock 来提供进程级（multiprocessing.Lock）和协程级（asyncio.Lock）的同步。

代码实体映射：锁定与状态

LightRAG · 锁定原语 · 图 2
LightRAG · 锁定原语 · 图 2

来源：lightrag/kg/shared_storage.py:137-179、lightrag/kg/shared_storage.py:430-460、lightrag/pipeline.py:43-44

数据一致性与恢复

管线设计为可恢复的。如果服务器崩溃或处理器失败，文档会在 DocStatusStorage 中保持 FAILED 或 PENDING 状态。

  1. 状态跟踪：每次文档状态转换都会被记录。状态包括 PARSING、ANALYZING、PROCESSING、PROCESSED 和 FAILED lightrag/base.py:32-41。
  2. 扫描恢复：当触发 run_scanning_process 时，它会将输入目录中的物理文件与 DocStatusStorage 进行比对。它会自动重新入队处于 FAILED 状态或知识图谱中缺失的文档 lightrag/api/routers/document_routes.py:1380-1450。
  3. 内容哈希：文档通过其内容的哈希值（compute_text_content_hash）进行标识。这可以防止同一文件以不同名称上传时被重复处理 lightrag/pipeline.py:71-74。

来源：lightrag/pipeline.py:94-100、lightrag/utils_pipeline.py:142-155、lightrag/api/routers/document_routes.py:1500-1550