项目定位与目标

LightRAG 是由香港大学数据智能系统实验室 (HKUDS) 开源的检索增强生成 (Retrieval-Augmented Generation, RAG) 框架，旨在通过结合知识图谱与向量检索，解决传统 RAG 在多跳推理、全局上下文关联以及领域术语覆盖方面的不足。框架同时提供 Python Core 库、LightRAG Server (REST API + WebUI) 以及与 Ollama 兼容的聊天接口，方便不同场景下的集成与部署 README.md:1-80。

最新发布版本 v1.5.0 已将 RAG-Anything 的多模态处理能力合并进 LightRAG 主仓库，PDF、Office 文档、图像、表格与公式均可被解析并纳入检索管线，社区建议使用 MinerU 先将文档转为 Markdown 以获得更稳定的识别效果 README.md:1-30。

核心架构与查询模式

LightRAG Server 在前端通过 QueryRequest 类型描述查询参数，支持 naive、local、global、hybrid、mix、bypass 六种检索模式，并提供 top_k、chunk_top_k、max_entity_tokens、max_relation_tokens 与 max_total_tokens 等细粒度控制项 lightrag_webui/src/api/lightrag.ts:1-100。下表对各模式进行概要说明：

⚠️ 社区反馈 v1.5.0 中曾出现 /query 返回 [no-context] 且日志显示 embedding worker 超时的问题，提示在升级后应检查嵌入服务的并发与超时配置 (issue #3195)。

多模态与可插拔解析器

v1.5.0 之后，多模态文档处理成为内置能力，外部解析后端 (如 MinerU、Docling、PaddleOCR、DeepSeek-OCR、GLM-OCR) 通过统一协议接入 README.md:1-40。社区正在推动 BaseExternalParser 协议以替代每接入一种引擎就重复四件套 (client.py / ir_builder.py / cache.py / manifest.py) 的现状，从而在 lightrag/parser/external/<engine>/ 之外提供统一抽象 (RFC #3197、#3198)。

WebUI 前端使用 React 19 + Vite + TypeScript 构建，依赖 sigma、graphology、graphology-layout-forceatlas2 等库渲染力导向知识图谱；节点类型与配色规则集中在 lightrag_webui/src/utils/graphColor.ts 中维护，支持中英文实体类别标签 (如 organization / 组织 / 公司) 的双向映射 lightrag_webui/package.json:1-60、lightrag_webui/src/utils/graphColor.ts:1-60。

部署、生态与社区热点

部署方式上，官方推荐使用 uv tool install "lightrag-hku[api]" 或 make dev 完成 Python 端安装，并使用 Bun 构建前端 (bun install --frozen-lockfile && bun run build)；Docker Compose 与 env.example 配置脚本可一键启动完整栈 README.md:1-120、lightrag_webui/README.md:1-40。路径前缀处理在 normalizeApiPrefix / normalizeWebuiPrefix 中实现，会把空值、/ 与带尾斜杠的输入归一化，避免拼接出 //x 这类协议相对 URL lightrag_webui/src/lib/pathPrefix.test.ts:1-30。

评估方面，lightrag/evaluation/sample_documents/ 提供 5 篇与 sample_dataset.json 题目对齐的示例文档，配合 eval_rag_quality.py 可达到约 91-100% 的 RAGAS 分数，建议在自有数据上自定义 lightrag/prompt.py 以获得更优的实体抽取效果 lightrag/evaluation/sample_documents/README.md:1-15。

社区关注度较高的议题包括：

• N8N 集成 (issue #328)：讨论将 LightRAG 关键能力移植为 N8N 节点；
• PathRAG 对比 (issue #1038)：新用户对 LightRAG 与 PathRAG 选型的疑问；
• 自定义元数据列 (issue #1985)：在多模态场景下扩展文档管理字段；
• 来源文件回溯 (issue #323)：希望查询结果中能携带源 PDF 文件名而不仅是文档 ID；
• 生产部署经验 (issue #422)：规模化运行时的稳定性与可观测性讨论。

相关生态项目包括多模态版 RAG-Anything 与视频版 VideoRAG，前者核心特性已合入主仓库 README.md:1-80。

See Also

• 快速开始 (Quickstart)
• 核心 API 参考 (Core API Reference)
• 多模态文档处理 (Multimodal Processing)
• 存储后端 (Storage Backends)

一、定位与整体目标

LightRAG 是一个面向"图增强检索（Graph-Augmented RAG）"的开源框架，其核心思路是把文档切分、知识图谱抽取、向量检索与上下文拼装统一在一条流水线中，使得查询既能利用文本片段，也能利用实体-关系结构。根据 README.md 的项目说明，LightRAG 同时提供"Core（嵌入式库）"和"Server（带 WebUI 的 REST 服务）"两种交付形态；Server 还附带一个与 Ollama 兼容的聊天接口，可被 Open WebUI 等前端直接调用。

整体目标可以归纳为三点：

1. 低门槛：通过 uv tool install "lightrag-hku[api]" 或 docker compose up 即可启动一套完整的多模态 RAG 服务（参见 README.md）。
2. 可扩展：存储后端覆盖向量库、图数据库、KV 存储和文档库，并支持自定义 LLM/Embedding Provider（README.md）。
3. 可生产：内置 Rerank、角色级 LLM 配置（EXTRACT/QUERY/KEYWORDS/VLM）、RAGAS 评估与 Langfuse 链路追踪（README.md 的更新日志条目）。

二、分层架构

LightRAG 的代码组织清晰地分为四层，每层都可以独立替换：

WebUI 端使用 TypeScript 与 Vite + Bun 工具链构建，依赖 react-markdown、sigma、graphology、katex、mermaid 等库（lightrag_webui/package.json），负责知识图谱可视化、文档上传与对话交互。WebUI 的"支持文件类型"与 MIME 映射定义在 lightrag_webui/src/lib/constants.ts 中，覆盖 Markdown、TXT、PDF、DOCX、PPTX、XLSX 以及多种源代码文件。

三、查询流水线与五种模式

查询请求首先被 /query 端点接收，参数 mode 决定走哪条分支；前端 QueryMode 枚举（lightrag_webui/src/api/lightrag.ts）定义如下：

• naive：仅向量检索。
• local：以实体为中心，结合实体描述与邻居关系。
• global：以关系为中心做图遍历。
• hybrid（默认）：本地 + 全局 + 文本块拼接，并通过 Rerank 提升混合查询质量。
• mix：与 hybrid 类似，但更强调多源融合。
• bypass：跳过检索直接调用 LLM。

flowchart LR
  A[用户查询] --> B[查询编码]
  B --> C{QueryMode}
  C -- local --> D[实体向量检索]
  C -- global --> E[关系向量检索]
  C -- hybrid/mix --> F[实体+关系+文本块]
  D --> G[图遍历/邻居扩展]
  E --> G
  F --> H[Reranker 精排]
  G --> H
  H --> I[统一 Token 控制<br/>max_entity_tokens / max_relation_tokens / max_total_tokens]
  I --> J[LLM 生成]
  J --> K[流式响应]

统一的 Token 预算由 max_entity_tokens、max_relation_tokens、max_total_tokens 三个字段联合约束（lightrag_webui/src/api/lightrag.ts），可以避免在 hybrid 模式下把上下文撑爆。enable_rerank 默认为 true；若未配置 Rerank 模型，则会发出告警并降级。

四、存储后端与多模态扩展

LightRAG 把数据拆成四类并允许独立选择后端，这一抽象也体现在 2025–2026 期间的多次发布说明中：

• 2026.05：支持 EXTRACT/QUERY/KEYWORDS/VLM 四种角色的独立 LLM 配置（README.md）。
• 2026.03：OpenSearch 作为统一存储后端，可同时承载四类 LightRAG 存储（README.md）。
• v1.5.0 / v1.5.0rc3：把 RAG-Anything 的多模态能力合并进主仓库，PDF/Office 中的图像、表格、公式可被检索与回答使用（v1.5.0 release）。
• 2025.11：集成 RAGAS 评估与 Langfuse 追踪，/query 返回时附带 retrieved contexts 以便计算 context precision（README.md）。

社区也提出了一些与存储/检索紧密相关的痛点：在 Milvus 作为向量库时，_merge_nodes 阶段会把所有出现过的描述拼接进 dynamic 字段，超过 65KB 限制后导致摄取失败（Issue #3204）；纯向量检索对领域术语和缩写召回不足，社区建议引入 BM25 + 图遍历混合召回（Issue #3198）；还有用户希望在 v1.5.0 中加入对自定义 OCR/VLM 引擎的协议化抽象（Issue #3197），以替代每个引擎单独复制 client.py / ir_builder.py / cache.py / manifest.py 的重复劳动。

针对图后端的可替换性，文档提供了基于 KubeBlocks 的快速部署模板 k8s-deploy/databases/README.md，用于在 K8s 集群上一键拉起 Neo4j、PostgreSQL 等依赖。评估方面，仓库自带 lightrag/evaluation/sample_documents/ 与 eval_rag_quality.py 脚本，按 lightrag/evaluation/sample_documents/README.md 的说明，目标是在 RAGAS 指标上达到 ~91–100% 的命中率。

五、常见故障与排错要点

• 返回 [no-context] 但文档确实存在：通常发生在 v1.5.0 Docker 部署中 Embedding Worker 超时，需检查 EMBEDDING_TIMEOUT 与并发数（Issue #3195）。
• 实体合并阶段 OOM / 字段超限：观察 Milvus 动态字段或 Neo4j 节点属性大小，并对 _merge_nodes 前的描述做截断或分片（Issue #3204）。
• 多模态/OCR 集成：在 v1.5.0 之前需要外部 MinerU/Docling 服务；之后将走统一的 BaseExternalParser 协议，社区正在讨论（Issue #3197）。

See Also

• 核心 API 与 QueryParam 参考
• 存储后端与可替换性
• 多模态文档处理流水线
• 评估与 RAGAS 接入

1. 概述与设计目标

LightRAG 的"核心 RAG 流水线"是介于文档摄入 (Insert) 与查询检索 (Query) 之间的中台逻辑层，负责把非结构化文本转换为"知识图谱 + 向量索引 + 文本块"三元组形式存储，并在查询时按 naive / local / global / hybrid / mix / bypass 六种模式统一调度实体、关系与文本块三种上下文来源 资料来源：[lightrag/operate.py:1-15] 资料来源：[lightrag_webui/src/api/lightrag.ts:1-20](https://github.com/HKUDS/LightRAG/blob/3fa73ecb9e19f19e184ab6e6c5608472d9b5371b/lightrag_webui/src/api/lightrag.ts)。

流水线以"双层检索 + 增量更新"为核心思想：第一层通过 LLM 抽取实体与关系构建图结构，第二层把图节点/边/原始文本块全部嵌入到向量库，使查询能够同时利用关键词、语义与图遍历三种信号 README.md。从工程角度看，流水线既要适配多种存储后端（PostgreSQL、Milvus、MongoDB、OpenSearch 等），也要支持可插拔的 LLM/Embedding 提供方，因此在 operate.py 中大量使用 functools.partial 和工作池 (apool) 进行异步编排 资料来源：[lightrag/operate.py:20-60]。

社区关注点：在 v1.5.0 中，流水线把 RAG-Anything 的多模态能力合并进来，PDF/Office 中的图片、表格、公式会经过 OCR/VLM 解析后进入同一管线 v1.5.0 Release Notes。

2. 流水线阶段分解

核心流水线在源码中可被划分为以下五个有序阶段（部分以函数边界出现）：

1. 文档分块 (Chunking)：根据 chunk_token_size、chunk_overlap_token_size 等常量把长文本切片为带重叠区的文本块 资料来源：[lightrag/constants.py:1-30]。
2. 实体/关系抽取 (Extraction)：调用 LLM，根据 PROMPTS["entity_extraction"] 模板产出 (entity_name, entity_type, description, source_id) 与 (source_entity, target_entity, description, keywords, weight) 两类结构化结果 资料来源：[lightrag/prompt.py:1-40]。
3. 图合并 (Graph Merge)：基于实体名去重，把新描述追加到既有节点上，并将"指向同一实体的边"做去重合并。社区报告 #3204 显示，Milvus 动态字段默认上限为 65 KB，描述不断追加时可能阻塞摄入 Issue #3204。
4. 向量化与写入 (Embedding & Persist)：实体、关系、文本块分别走不同函数（embedding_func）入库到 KV/向量/图三类存储。lightrag.types 中以 TypedDict 形式约束了字段命名，确保跨后端兼容 资料来源：[lightrag/types.py:1-40]。
5. 查询上下文组装 (Retrieval Context)：依据 QueryParam.mode 选择召回路径，混合模式下还会调用 Rerank 模型对文本块重排 资料来源：[lightrag/operate.py:60-120] Reranker 特性说明 (2025.08)。

3. 关键数据流图

flowchart LR
    A[原始文档] --> B[Chunking]
    B --> C[LLM 抽取<br/>Entity & Relation]
    C --> D[Graph Merge<br/>去重 + 描述累加]
    D --> E[Embedding]
    E --> F1[(KV 存储<br/>chunks/llm_cache)]
    E --> F2[(向量库<br/>entities/relations/chunks)]
    E --> F3[(图存储<br/>nodes/edges)]
    G[用户 Query] --> H{QueryParam.mode}
    H -->|local| I1[实体向量召回 + 邻居展开]
    H -->|global| I2[关系向量召回 + 路径]
    H -->|hybrid/mix| I3[实体+关系+chunk 合并 + Rerank]
    I1 --> J[LLM 生成答案]
    I2 --> J
    I3 --> J

该图对应 operate.py 中 extract_entities、merge_nodes_and_edges、query 三大入口函数的调用顺序；当 mode=mix 时，I3 会按 max_entity_tokens / max_relation_tokens / max_total_tokens 的统一 token 配额做截断 资料来源：[lightrag_webui/src/api/lightrag.ts:10-40]。

4. 失败模式与社区实践

实用建议：开启 Langfuse 追踪可定位具体超时发生在 Embedding 还是 LLM 阶段 Advanced Features 文档；启用 Reranker 后，混合查询的 chunk_top_k 建议先放大 2–3 倍再做重排截断 资料来源：[lightrag_webui/src/api/lightrag.ts:20-45]。

5. 与其他模块的关系

• 存储层：operate.py 仅定义抽象 KV/向量/图接口，落地由 lightrag/kg/ 与 lightrag/base.py 中具体实现（MilvusStorage、PostgresGraphStorage 等）承担，便于在不修改管线的前提下替换后端 Question #2709。
• 提示词层：所有 LLM 调用集中读取 lightrag/prompt.py，用户可通过修改 entity_extraction / summarize_entity_descriptions 等模板来适配垂直领域 资料来源：[lightrag/prompt.py:1-30]。
• API/Server 层：lightrag_server 暴露 /query、/documents、/graph 等端点，但内部仍把请求转交给 LightRAG 类的 aquery / ainsert 方法，与核心流水线共用同一条代码路径 资料来源：[lightrag/lightrag.py:1-40]。

概述

知识图谱操作是 LightRAG 的核心抽象层，负责在文档索引阶段抽取实体与关系，在查询阶段对图谱进行检索与推理，并在运行期支持对实体/关系的合并、改名与删除等维护动作。整套图谱操作既可作为 Python 库直接调用，也可通过 LightRAG Server 提供的 REST/WebUI 入口远程访问 README.md:installation-section。图谱操作在 LightRAG 中位于「文档切分 → 抽取 → 嵌入存储 → 图谱查询」流水线的中心，向上承载查询模式（naive/local/global/hybrid/mix/bypass），向下适配多种图存储后端（NetworkX、Neo4j、PostgreSQL、Milvus 等）README.md:architecture-section。

图谱构建：实体与关系抽取

LightRAG 在索引阶段会调用 lightrag/operate.py 中的抽取函数，由 LLM 依据预置 prompt 从文本块中解析出实体（entity）与关系（relationship），并把三元组写入对应的存储后端 lightrag/operate.py:extraction-region。抽取质量对后续检索影响极大，因此官方建议：

• LLM 参数量 ≥ 32B，context 长度 ≥ 32KB（推荐 64KB），索引阶段不推荐使用推理模型 README.md:model-recommendations。
• 嵌入模型需在索引前固定，切换模型后必须删除旧的向量表并重新构建 README.md:embedding-model-note。

WebUI 在渲染图谱时，会按实体类型为节点着色。graphColor.ts 中将抽取出的实体类型归一化到 organization / event / person / creature / location / naturalobject / data / content / artifact / method 等类别，对应不同的视觉通道 lightrag_webui/src/utils/graphColor.ts:category-mapping。

图谱查询模式

QueryRequest 中通过 mode 字段选择查询策略，类型定义见前端 API 模块 lightrag_webui/src/api/lightrag.ts:QueryRequest：

统一 token 控制系统（max_entity_tokens、max_relation_tokens、max_total_tokens）在 hybrid / mix 模式下生效，用于在实体上下文、关系上下文与文本块上下文之间做预算分配 lightrag_webui/src/api/lightrag.ts:QueryRequest-tokens。

实体更新与维护：合并、改名、删除

LightRAG 1.5 起支持带 KG 重建的文档删除，并提供实体级更新 API。对应响应结构在 EntityUpdateResponse.operation_summary 中显式返回了合并结果与改名结果，便于前端做精细化提示 lightrag_webui/src/api/lightrag.ts:EntityUpdateResponse：

{
  "operation_summary": {
    "merged": true,
    "merge_status": "success",
    "target_entity": "北京市文物局",
    "renamed": true
  }
}

服务器侧的实现位于 lightrag/api/routers/graph_routes.py，封装了图谱相关的 CRUD 与批量合并接口 lightrag/api/routers/graph_routes.py:routing-region。在底层，lightrag/kg/networkx_impl.py 等适配器负责把图操作翻译成具体后端的原生调用 lightrag/kg/networkx_impl.py:adapter-region。

常见失败模式

社区中报告过几类与图谱操作直接相关的故障，使用时需要留意：

• Milvus 65K 字节上限：在 merge 阶段，实体描述持续累加可能撑爆 Milvus dynamic field 的字节上限，导致文档摄取被阻塞（Issue #3204）。
• 合并过程中连接被关闭：长任务在合并实体时偶发 connection was closed in the middle of operation，需要结合后端超时与重试策略调参（Issue #2746）。
• 新图数据库接入：若希望替换默认 NetworkX 实现，可参考存储抽象层的接口约定，并参考（Issue #2709）中的讨论。
• 检索词召不回实体：纯向量召回对领域术语覆盖不足，社区已提出「BM25 + 向量 + 图遍历」混合方案的 RFC（Issue #3198）。
• Embedding worker 超时导致 [no-context]：1.5.0 中出现过日志显示 embedding 超时但 /query 仍返回空上下文的情况（Issue #3195）。

可视化与运维工具

lightrag/tools/lightrag_visualizer 提供了一个基于 imgui_bundle + ModernGL + NetworkX 的 3D 图谱浏览器，支持多种布局算法（spring / circular / shell / random）、社区检测、WASD 漫游与节点交互 lightrag/tools/lightrag_visualizer/README.md:features。WebUI 一侧则使用 graphology + sigma 渲染力导向布局，支持多语言、KaTeX 公式与 Mermaid 图表 lightrag_webui/package.json:graphology-deps，可通过 bun run build 产物部署到 lightrag/api/webui 目录 lightrag_webui/README.md:build-steps。

flowchart LR
  A[文档输入] --> B[分块与抽取<br/>operate.py]
  B --> C[实体 / 关系]
  C --> D[(图存储后端<br/>NetworkX / Neo4j / PG / Milvus)]
  D --> E{查询模式}
  E -- local --> F[实体向量召回 + 一跳扩展]
  E -- global --> G[关系向量召回]
  E -- hybrid/mix --> H[统一 token 预算]
  H --> I[LLM 生成答案]
  D --> J[合并 / 改名 / 删除<br/>graph_routes.py]

最佳实践小结

1. 模型先行：先确定 LLM、Embedding、Reranker 三件套，再开始批量灌库，避免事后改嵌入模型清空表。
2. 统一 token 预算：混合查询务必显式设置 max_total_tokens，否则实体 + 关系 + 文本块极易超出 LLM 上下文。
3. 慎用推理模型做索引：抽取阶段对结构化输出敏感，推理模型的链式思考会显著拖慢索引速度。
4. 监控合并路径：在长任务中为 merge 步骤加监控与断点续跑，规避 Milvus 字节上限与连接中断。
5. 图谱可观测：在生产环境同时启用 WebUI 图谱浏览器与 3D 可视化，便于运维定位异常实体增长。

See Also

• README.md — 项目总览与模型建议
• AdvancedFeatures.md — 重排序、引用追踪等进阶能力
• OfflineDeployment.md — 离线/气隙环境部署
• Reproduce.md — 论文结果复现指南
• Multimodal Processing (RAG-Anything) — 1.5.0 之后已并入主仓的多模态能力
• VideoRAG — 视频检索增强生成

Pitfall Log / 踩坑日志

项目：HKUDS/LightRAG

摘要：发现 36 个潜在踩坑项，其中 8 个为 high/blocking；最高优先级：安装坑 - 来源证据：Guidance on Adding Multimodal Support to LightRAG: Wrap with RAG‑Anything or Extend (modify) LightRAGs lightrag‑server?。

1. 安装坑 · 来源证据：Guidance on Adding Multimodal Support to LightRAG: Wrap with RAG‑Anything or Extend (modify) LightRAGs lightrag‑server?

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Guidance on Adding Multimodal Support to LightRAG: Wrap with RAG‑Anything or Extend (modify) LightRAGs lightrag‑server?
• 对用户的影响：可能影响升级、迁移或版本选择。
• 证据：community_evidence:github | https://github.com/HKUDS/LightRAG/issues/2642 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

2. 安装坑 · 来源证据：[Bug]:connection was closed in the middle of operation

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]:connection was closed in the middle of operation
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/HKUDS/LightRAG/issues/2746 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

3. 安装坑 · 来源证据：[v1.5.0] /query still returns [no-context] due to embedding worker timeout even though embeddings API is reachable and…

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[v1.5.0] /query still returns [no-context] due to embedding worker timeout even though embeddings API is reachable and documents exist
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/HKUDS/LightRAG/issues/3195 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

4. 配置坑 · 来源证据：[Bug]:RagAnything with Ollma(qwen3-vl) image process, Getting error

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug]:RagAnything with Ollma(qwen3-vl) image process, Getting error
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/HKUDS/LightRAG/issues/2502 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

5. 配置坑 · 来源证据：[Question]: Other graph database implementation

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Question]: Other graph database implementation
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/HKUDS/LightRAG/issues/2709 | 来源类型 github_issue 暴露的待验证使用条件。

6. 能力坑 · 来源证据：关于富文本内容识别

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：关于富文本内容识别
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/HKUDS/LightRAG/issues/2761 | 来源类型 github_issue 暴露的待验证使用条件。

7. 运行坑 · 来源证据：[Question]:一个chunk平均6分钟正常吗？

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：[Question]:一个chunk平均6分钟正常吗？
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/HKUDS/LightRAG/issues/2768 | 来源类型 github_issue 暴露的待验证使用条件。

8. 运行坑 · 来源证据：悬空代词（或者图结构）引发的LightRAG翻车现场

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：悬空代词（或者图结构）引发的LightRAG翻车现场
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/HKUDS/LightRAG/issues/3234 | 来源类型 github_issue 暴露的待验证使用条件。

9. 安装坑 · 失败模式：installation: [v1.5.0] /query still returns [no-context] due to embedding worker timeout even though embedd...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: [v1.5.0] /query still returns [no-context] due to embedding worker timeout even though embeddings API is reachable and documents exist
• 对用户的影响：Developers may fail before the first successful local run: [v1.5.0] /query still returns [no-context] due to embedding worker timeout even though embeddings API is reachable and documents exist
• 证据：failure_mode_cluster:github_issue | https://github.com/HKUDS/LightRAG/issues/3195 | [v1.5.0] /query still returns [no-context] due to embedding worker timeout even though embeddings API is reachable and documents exist

10. 安装坑 · 失败模式：installation: v1.4.10

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v1.4.10
• 对用户的影响：Upgrade or migration may change expected behavior: v1.4.10
• 证据：failure_mode_cluster:github_release | https://github.com/HKUDS/LightRAG/releases/tag/v1.4.10 | v1.4.10

11. 安装坑 · 来源证据：RFC: introduce a BaseExternalParser protocol for pluggable OCR/VLM backends

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：RFC: introduce a BaseExternalParser protocol for pluggable OCR/VLM backends
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/HKUDS/LightRAG/issues/3197 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

12. 配置坑 · 失败模式：configuration: RFC: hybrid BM25 + vector retrieval with graph traversal seeding for jargon-heavy domains

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: RFC: hybrid BM25 + vector retrieval with graph traversal seeding for jargon-heavy domains
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: RFC: hybrid BM25 + vector retrieval with graph traversal seeding for jargon-heavy domains
• 证据：failure_mode_cluster:github_issue | https://github.com/HKUDS/LightRAG/issues/3198 | RFC: hybrid BM25 + vector retrieval with graph traversal seeding for jargon-heavy domains

13. 配置坑 · 失败模式：configuration: [Bug] Entity description accumulated in Milvus dynamic field exceeds 65K byte limit on merge,...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: [Bug] Entity description accumulated in Milvus dynamic field exceeds 65K byte limit on merge, blocking document ingestion
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: [Bug] Entity description accumulated in Milvus dynamic field exceeds 65K byte limit on merge, blocking document ingestion
• 证据：failure_mode_cluster:github_issue | https://github.com/HKUDS/LightRAG/issues/3204 | [Bug] Entity description accumulated in Milvus dynamic field exceeds 65K byte limit on merge, blocking document ingestion

14. 配置坑 · 失败模式：configuration: [Bug]:RagAnything with Ollma(qwen3-vl) image process, Getting error

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: [Bug]:RagAnything with Ollma(qwen3-vl) image process, Getting error
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: [Bug]:RagAnything with Ollma(qwen3-vl) image process, Getting error
• 证据：failure_mode_cluster:github_issue | https://github.com/HKUDS/LightRAG/issues/2502 | [Bug]:RagAnything with Ollma(qwen3-vl) image process, Getting error

15. 配置坑 · 失败模式：configuration: [Bug]:connection was closed in the middle of operation

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: [Bug]:connection was closed in the middle of operation
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: [Bug]:connection was closed in the middle of operation
• 证据：failure_mode_cluster:github_issue | https://github.com/HKUDS/LightRAG/issues/2746 | [Bug]:connection was closed in the middle of operation

16. 配置坑 · 失败模式：configuration: [Question]: Using Smoldocling VLM for OCR

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: [Question]: Using Smoldocling VLM for OCR
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: [Question]: Using Smoldocling VLM for OCR
• 证据：failure_mode_cluster:github_issue | https://github.com/HKUDS/LightRAG/issues/1434 | [Question]: Using Smoldocling VLM for OCR

17. 配置坑 · 失败模式：configuration: v1.4.11

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: v1.4.11
• 对用户的影响：Upgrade or migration may change expected behavior: v1.4.11
• 证据：failure_mode_cluster:github_release | https://github.com/HKUDS/LightRAG/releases/tag/v1.4.11 | v1.4.11

18. 配置坑 · 失败模式：configuration: v1.4.11rc2

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: v1.4.11rc2
• 对用户的影响：Upgrade or migration may change expected behavior: v1.4.11rc2
• 证据：failure_mode_cluster:github_release | https://github.com/HKUDS/LightRAG/releases/tag/v1.4.11rc2 | v1.4.11rc2

19. 配置坑 · 失败模式：configuration: v1.4.12

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: v1.4.12
• 对用户的影响：Upgrade or migration may change expected behavior: v1.4.12
• 证据：failure_mode_cluster:github_release | https://github.com/HKUDS/LightRAG/releases/tag/v1.4.12 | v1.4.12

20. 配置坑 · 失败模式：configuration: v1.4.13

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: v1.4.13
• 对用户的影响：Upgrade or migration may change expected behavior: v1.4.13
• 证据：failure_mode_cluster:github_release | https://github.com/HKUDS/LightRAG/releases/tag/v1.4.13 | v1.4.13

21. 配置坑 · 失败模式：configuration: v1.4.14

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: v1.4.14
• 对用户的影响：Upgrade or migration may change expected behavior: v1.4.14
• 证据：failure_mode_cluster:github_release | https://github.com/HKUDS/LightRAG/releases/tag/v1.4.14 | v1.4.14

22. 配置坑 · 失败模式：configuration: v1.5.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: v1.5.0
• 对用户的影响：Upgrade or migration may change expected behavior: v1.5.0
• 证据：failure_mode_cluster:github_release | https://github.com/HKUDS/LightRAG/releases/tag/v1.5.0 | v1.5.0

23. 配置坑 · 失败模式：configuration: v1.5.0rc3

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: v1.5.0rc3
• 对用户的影响：Upgrade or migration may change expected behavior: v1.5.0rc3
• 证据：failure_mode_cluster:github_release | https://github.com/HKUDS/LightRAG/releases/tag/v1.5.0rc3 | v1.5.0rc3

24. 配置坑 · 来源证据：[Question]: Using Smoldocling VLM for OCR

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Question]: Using Smoldocling VLM for OCR
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/HKUDS/LightRAG/issues/1434 | 来源类型 github_issue 暴露的待验证使用条件。

25. 配置坑 · 来源证据：[Question]:上传文件embedding失败，几十kb或者2M的都失败，报错：expected 10 vectors but got 5 vectors (from embedding result)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Question]:上传文件embedding失败，几十kb或者2M的都失败，报错：expected 10 vectors but got 5 vectors (from embedding result)
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/HKUDS/LightRAG/issues/3232 | 来源类型 github_issue 暴露的待验证使用条件。

26. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | github_repo:866513204 | https://github.com/HKUDS/LightRAG | README/documentation is current enough for a first validation pass.

27. 运行坑 · 来源证据：[Feature Request]:can you add workspace。support some type konwledge by one people

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：[Feature Request]:can you add workspace。support some type konwledge by one people
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/HKUDS/LightRAG/issues/3236 | 来源类型 github_issue 暴露的待验证使用条件。

28. 维护坑 · 失败模式：migration: Guidance on Adding Multimodal Support to LightRAG: Wrap with RAG‑Anything or Extend (modify)...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this migration risk before relying on the project: Guidance on Adding Multimodal Support to LightRAG: Wrap with RAG‑Anything or Extend (modify) LightRAGs lightrag‑server?
• 对用户的影响：Developers may hit a documented source-backed failure mode: Guidance on Adding Multimodal Support to LightRAG: Wrap with RAG‑Anything or Extend (modify) LightRAGs lightrag‑server?
• 证据：failure_mode_cluster:github_issue | https://github.com/HKUDS/LightRAG/issues/2642 | Guidance on Adding Multimodal Support to LightRAG: Wrap with RAG‑Anything or Extend (modify) LightRAGs lightrag‑server?

29. 维护坑 · 失败模式：migration: v1.4.16

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this migration risk before relying on the project: v1.4.16
• 对用户的影响：Upgrade or migration may change expected behavior: v1.4.16
• 证据：failure_mode_cluster:github_release | https://github.com/HKUDS/LightRAG/releases/tag/v1.4.16 | v1.4.16

30. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | github_repo:866513204 | https://github.com/HKUDS/LightRAG | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | github_repo:866513204 | https://github.com/HKUDS/LightRAG | no_demo; severity=medium

32. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | github_repo:866513204 | https://github.com/HKUDS/LightRAG | no_demo; severity=medium

33. 安全/权限坑 · 来源证据：RFC: hybrid BM25 + vector retrieval with graph traversal seeding for jargon-heavy domains

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：RFC: hybrid BM25 + vector retrieval with graph traversal seeding for jargon-heavy domains
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/HKUDS/LightRAG/issues/3198 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

34. 安全/权限坑 · 来源证据：[Bug] Entity description accumulated in Milvus dynamic field exceeds 65K byte limit on merge, blocking document ingesti…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug] Entity description accumulated in Milvus dynamic field exceeds 65K byte limit on merge, blocking document ingestion
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/HKUDS/LightRAG/issues/3204 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

35. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | github_repo:866513204 | https://github.com/HKUDS/LightRAG | issue_or_pr_quality=unknown

36. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | github_repo:866513204 | https://github.com/HKUDS/LightRAG | release_recency=unknown