agentic_huge_data_base / wiki
页面 LightRAG · 7.3 生产部署与 Gunicorn·DeepWiki 中文全文译文
DeepWiki 中文译文 / LightRAG / 7.3

7.3 · 生产部署与 Gunicorn（Production Deployment with Gunicorn）

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

项目LightRAG 章节7.3 状态全文译文 模块测试、发布与运维、认证、权限与安全、系统架构、接口与服务契约
项目要点页2.5 参考项目 项目章节目录LightRAG DeepWiki 原始章节Production Deployment with Gunicorn 上一章7.2 下一章7.4
源码线索
  • lightrag/api/auth.py
  • lightrag/api/gunicorn_config.py
  • lightrag/api/passwords.py
  • lightrag/api/run_with_gunicorn.py
  • lightrag/tools/hash_password.py
  • tests/test_auth.py
模块标签
  • 测试、发布与运维
  • 认证、权限与安全
  • 系统架构
  • 接口与服务契约
  • 配置治理

章节正文

召回测试与设置 UI

原始 DeepWiki 页面https://deepwiki.com/HKUDS/LightRAG/7.3-retrieval-testing-and-settings-ui

检索测试与设置界面

相关源文件

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

  • lightrag_webui/src/components/AppSettings.tsx
  • lightrag_webui/src/components/graph/Legend.tsx
  • lightrag_webui/src/components/graph/Settings.tsx
  • lightrag_webui/src/components/retrieval/QuerySettings.tsx
  • lightrag_webui/src/components/ui/TabContent.tsx
  • lightrag_webui/src/contexts/TabVisibilityProvider.tsx
  • lightrag_webui/src/contexts/useTabVisibility.ts
  • lightrag_webui/src/features/ApiSite.tsx
  • lightrag_webui/src/features/RetrievalTesting.tsx
  • lightrag_webui/src/i18n.ts
  • lightrag_webui/src/locales/de.json
  • lightrag_webui/src/locales/ja.json
  • lightrag_webui/src/locales/ko.json
  • lightrag_webui/src/locales/ru.json
  • lightrag_webui/src/locales/uk.json
  • lightrag_webui/src/locales/vi.json
  • lightrag_webui/src/stores/settings.ts

检索测试与设置界面提供了一个与 LightRAG 核心引擎交互的全面界面。它允许用户在各种检索增强生成（RAG）模式下执行查询、可视化流式响应，并微调检索参数。该系统基于 Zustand 构建了持久化状态管理层，确保用户偏好、查询历史和本地化设置在会话之间得以保留。

检索测试组件

RetrievalTesting 组件是测试 RAG 引擎性能的主要界面。它管理一个支持复杂渲染的聊天式界面，包括 LaTeX 和思维链（COT）推理块。

核心实现细节
  • 消息渲染：UI 使用 ChatMessage 组件来渲染响应。它包含专门的逻辑来检测和解析 <think> 标签，用于 COT 可视化 lightrag_webui/src/features/RetrievalTesting.tsx:45-102。
  • LaTeX 支持：它具备强大的 LaTeX 完整性检测算法，确保即使在流式传输过程中也能正确渲染数学公式 lightrag_webui/src/features/RetrievalTesting.tsx:29-42。
  • 流式 NDJSON：该组件使用 queryTextStream 来处理来自后端的实时更新，处理增量片段以动态更新 UI lightrag_webui/src/features/RetrievalTesting.tsx:6。
  • 智能输入：输入字段会根据内容自动在单行 Input 和多行 Textarea 之间切换 lightrag_webui/src/features/RetrievalTesting.tsx:145-152。
数据流：查询执行

下图展示了从用户输入到渲染流式响应的完整流程。

查询执行与渲染流程

LightRAG · 数据流：查询执行 · 图 1
LightRAG · 数据流：查询执行 · 图 1

来源： lightrag_webui/src/features/RetrievalTesting.tsx:175-250、lightrag_webui/src/stores/settings.ts:124-137、lightrag_webui/src/api/lightrag.ts:1-50

查询设置组件

QuerySettings 组件 lightrag_webui/src/components/retrieval/QuerySettings.tsx:41 是一个专用的侧边栏面板，允许对检索引擎的行为进行精细控制。

可配置参数

该组件直接映射到后端使用的 QueryRequest 模型：

参数UI 控件描述
modeSelect选择 naive、local、global、hybrid、mix 或 bypass 模式 lightrag_webui/src/components/retrieval/QuerySettings.tsx:138-143。
top_kInput（数字）要检索的实体/关系数量 lightrag_webui/src/components/retrieval/QuerySettings.tsx:154-180。
chunk_top_kInput（数字）要检索的文本片段数量 lightrag_webui/src/components/retrieval/QuerySettings.tsx:182-208。
max_total_tokensInput（数字）总上下文的 Token 数量上限 lightrag_webui/src/components/retrieval/QuerySettings.tsx:266-292。
user_promptUserPromptInputWithHistory自定义系统提示覆盖，支持历史记录 lightrag_webui/src/components/retrieval/QuerySettings.tsx:98-108。
enable_rerankCheckbox切换是否使用已配置的重排序器 lightrag_webui/src/components/retrieval/QuerySettings.tsx:323-332。

来源： lightrag_webui/src/components/retrieval/QuerySettings.tsx:111-350、lightrag_webui/src/stores/settings.ts:124-137

持久化状态管理

LightRAG 使用带有 persist 中间件的 Zustand 来管理跨浏览器重载的应用程序状态。

useSettingsStore

useSettingsStore lightrag_webui/src/stores/settings.ts:87 负责处理：

  1. 检索历史：存储之前的消息以重建聊天会话 lightrag_webui/src/stores/settings.ts:59。
  2. 提示历史：保留最近 12 个唯一用户提示的列表 lightrag_webui/src/stores/settings.ts:205-227。
  3. 图谱偏好：控制可视化参数，如 graphMaxNodes、minEdgeSize 和标签可见性 lightrag_webui/src/stores/settings.ts:24-53。
  4. UI 状态：当前活动标签页、主题（浅色/深色/系统）和语言 lightrag_webui/src/stores/settings.ts:70-80。

状态持久化架构

LightRAG · useSettingsStore · 图 2
LightRAG · useSettingsStore · 图 2

来源： lightrag_webui/src/stores/settings.ts:87-137、lightrag_webui/src/stores/settings.ts:205-227

本地化（i18n）

该应用程序使用 i18next 支持多种语言。配置在 i18n.ts 中初始化，并与 useSettingsStore 同步。

支持的语言
  • 英语（EN）、中文（ZH/ZH_TW）、法语（FR）、阿拉伯语（AR）、日语（JA）、韩语（KO）、德语（DE）、俄语（RU）、乌克兰语（UK）、越南语（VI） lightrag_webui/src/i18n.ts:5-15。
实现机制
  1. 初始化：加载时，系统会尝试从 localStorage 中检索语言设置 lightrag_webui/src/i18n.ts:17-28。
  2. 订阅：i18n 实例会订阅 Zustand 存储中的变更。当 state.language 发生变化时，会自动调用 i18n.changeLanguage() lightrag_webui/src/i18n.ts:57-62。
  3. 组件：AppSettings 组件提供一个 Select 下拉菜单来触发这些更新 lightrag_webui/src/components/AppSettings.tsx:43-60。

来源： lightrag_webui/src/i18n.ts:30-64、lightrag_webui/src/components/AppSettings.tsx:14-80

图谱设置面板

虽然与检索设置不同，但图谱设置面板 lightrag_webui/src/components/graph/Settings.tsx:173 共享同一个 useSettingsStore，并提供对 KnowledgeGraph 可视化的控制。

关键特性
  • 节点/边控制：切换标签显示、启用/禁用拖拽以及设置边的大小范围 lightrag_webui/src/components/graph/Settings.tsx:176-184。
  • 搜索深度：graphQueryMaxDepth 控制展开节点时检索的跳数 lightrag_webui/src/components/graph/Settings.tsx:185。
  • 节点限制：graphMaxNodes 通过限制渲染的实体数量来防止浏览器性能下降 lightrag_webui/src/components/graph/Settings.tsx:186。
  • 图例集成：Legend 组件使用 useGraphStore 中的 typeColorMap 来显示本地化的节点类型标签 lightrag_webui/src/components/graph/Legend.tsx:11-41。

来源： lightrag_webui/src/components/graph/Settings.tsx:173-220、lightrag_webui/src/components/graph/Legend.tsx:1-41、lightrag_webui/src/stores/settings.ts:157-175