LightRAG 从 v1.4.16 升级到 v1.5.x 前需要检查哪些文件处理管线与配置变更【免费下载链接】LightRAG[EMNLP2025] LightRAG: Simple and Fast Retrieval-Augmented Generation项目地址: https://gitcode.com/GitHub_Trending/li/LightRAG如果你正在运行 LightRAG v1.4.16准备升级到 v1.5.x需要先确认几件事v1.5.x 引入了新的文件处理流水线、解析器路由LIGHTRAG_PARSER、多模态分析、基于角色的 LLM/VLM 配置、JSON 实体抽取以及若干 provider/storage 变更。升级前请先阅读 v1.5.0rc2 发布说明然后按本文对照.env与部署拓扑逐项检查。以下内容均出自项目文档 docs/LightRAG-API-Server.md 的 “Upgrading from v1.4.16 to v1.5.x” 及配套章节。一、文件处理管线的变化v1.5 引入了分阶段的文档管线文件先经过内容抽取引擎extraction engine可选的多模态分析文本分块最后做实体/关系抽取除非该文件禁用了知识图谱构建。文件如何进入这条管线由LIGHTRAG_PARSER控制规则按文件扩展名从左到右匹配例如LIGHTRAG_PARSERpdf:mineru-R,docx:native-ietP,*:legacy-R支持的引擎包括legacy原有抽取行为、native内置结构化解析器目前聚焦.docx与 LightRAG Document sidecar、mineru外部 MinerU 服务和docling外部 docling-serve 服务。升级前需要明确的两个判断是否沿用旧行为。如果只想升级服务器、保持 v1.4 的文件处理行为设置LIGHTRAG_PARSER*:legacy-F已有文档不会被重新路由。修改LIGHTRAG_PARSER或文件名 hint 只影响新上传的文件。若要把某份已有文档切换到另一个解析引擎必须先删除该文档再重新上传。二、配置项检查清单1. 移除ENTITY_TYPES会导致启动失败ENTITY_TYPES在 v1.5 中已不再支持取而代之的是 prompt profile改用ENTITY_TYPE_PROMPT_FILE指向一个只含文件名的 YAML profile文件从PROMPT_DIR/entity_type下加载不要传绝对路径。PROMPT_DIR默认是./prompts。仓库提供了参考模板 prompts/samples/entity_type_prompt.sample.yml其中包含entity_types_guidance、entity_extraction_examples和entity_extraction_json_examples三段内容。文档明确警告如果旧.env中仍保留ENTITY_TYPES服务器会直接启动失败fail fast。因此升级前先从.env删除该行再按需配置ENTITY_EXTRACTION_USE_JSONtrue ENTITY_TYPE_PROMPT_FILEentity_type_prompt.yml PROMPT_DIR/opt/lightrag/promptsENTITY_EXTRACTION_USE_JSON在 v1.5 中因可靠性被推荐开启但会增加延迟可按需取舍。2. Embedding 配置任何改变都意味着重索引更换 embedding 模型、embedding 维度、非对称 embedding 行为EMBEDDING_ASYMMETRIC或 query/document 前缀都会改变向量语义。文档给出的处理方式是清空受影响的 LightRAG workspace/向量数据并重新索引源文件。文档还提醒对 PostgreSQL 等存储向量维度在首次建表时就已固定这类变更的代价更高。如果升级时没有动这些配置则不需要重索引。3. OpenSearch 存储的版本门槛如果使用 OpenSearch 存储且集群版本低于 OpenSearch 3.3.0要先升级 OpenSearch再启用 v1.5 的存储路径并校验已有索引。新部署则直接使用 OpenSearch 3.3.0 或更高版本。4. Chunker 配置CHUNK_*与多模态选项修改CHUNK_SIZE、CHUNK_OVERLAP_SIZE等CHUNK_*配置只在服务器重启后新入队的文档上生效。这些值在启动时读取并在文档入队时作为 per-document 的chunk_options快照保存。若希望旧文档的chunk_options快照也采用新配置需要重新处理这些文档。启用多模态选项i/t/e需要文档已有解析 sidecar并设置VLM_PROCESS_ENABLEtrue。已有文档可以通过重新处理在可用 sidecar 上补跑 VLM 分析但切换抽取引擎仍然需要删除 重新上传。三、请求体上限客户端行为会变升级后MAX_REQUEST_BODY_BYTES会默认开启为 1 MiB此前默认关闭且只覆盖三条摄取路由对客户端有两点直接影响普通路由上超过 1 MiB 的请求体返回 413包括/query*、/api/chat、/api/generate等既非上传也非文本插入的路由。/documents/text与/documents/texts保留 50 MiB 上限/documents/upload的上限由MAX_UPLOAD_SIZE派生批量摄取不受影响。把MAX_REQUEST_BODY_BYTES设为任意正值可让它统一约束所有非上传路由设为0关闭全部上限。模型侧字段有固定上限且不可配置单个 query/prompt 64 KiB、单条消息 32 KiB、每请求模型侧文本合计 128 KiB、最多 128 条消息、top_k/chunk_top_k最大 1000、max_*_tokens最大 1,000,000。依赖无界top_k或数 MB 查询文本的客户端需要在升级前调整。四、管线调度的并发协议升级顺序的关键引入PIPELINE_SCHEDULING_PAGE_SIZE、MAX_PENDING_DOCUMENTS和MAX_UNACKED_MANUAL_RETRIES见 env.example的版本同时改变了各 writer 通过共享状态协调的并发协议。这是一次一次性、原地的升级不写任何 marker也不写协议版本号存储层无法替你识别残留的旧 writer。文档因此给出硬性运维要求在对同一存储、同一 workspace 启动新版本之前必须先停掉所有旧 writer。滚动重启时只要还留着一个旧 worker——或者一个共用同一 Redis/PostgreSQL workspace 的旧实例——就是故障场景而不只是升级变慢。旧 writer 无法遵守的三点行为是这条要求的原因manual retry 冻结/documents/reprocess_failed不再就地重置FAILED行而是发布 intent、冻结入口、等管线空闲后分页把FAILED改写为PENDING。旧 writer 不读冻结标志会继续往这个被重置逻辑视为独占的窗口里入队。调度排序键created_at现在以 UTC ISO-8601 时间戳写入作为不可变的(created_at, id)keyset 游标。旧 writer 用其他格式打上的时间戳会造成 keyset 分页跳过或重复文档。派生索引在 Redis 上status 集合与 source multimap 与文档主记录在同一事务中维护旧 writer 只更新主记录会让索引停留在陈旧状态strict 分页与 strict 活跃计数会静默漏掉该文档。推荐升级顺序停止接收新文档等待管线跑完。用已鉴权的/health确认没有任何在途工作时scheduling.drain_waiting_on_workers为false、scheduling.drain_pending_enqueues为0curl -H X-API-Key: key http://localhost:9621/health停掉共用该存储与 workspace 的全部worker 和实例Gunicorn 多 worker 部署要停掉整个进程组而不是逐个滚动替换。启动新版本。不需要数据迁移。启动后的第一轮 sweep 是一次 strict 全量 sweep旧 writer 留在半途的文档例如卡在PARSING/ANALYZING/PROCESSING且背后已没有 worker 的行会被自动捡起并重新处理。如果某次运行确实无法排空中途停止同样是安全的不安全的是事后把旧版本重新启动回来。五、升级后的验证检查启动日志中的 strict 能力告警。五个内置doc_status后端JSON、Redis、PostgreSQL、MongoDB、OpenSearch都具备全部能力第三方后端可能缺失且每一项缺失都是失败关闭而非静默降级admission 返回 503、source-conflict 端点返回 501、scan 会一直重复检查陈旧的FAILEDstub。启动日志会逐项列出缺失能力及代价已鉴权的/health在capabilities字段下报告同一份信息。若希望把这些缺口直接变成启动失败设置PIPELINE_REQUIRE_STRICT_STORAGE_READStrue。注意有界分页没有对应旋钮分页与 typed source 解析方法是抽象方法缺失相应能力的后端根本无法被构造。确认请求上限符合预期。对普通路由发送超过 1 MiB 的请求体应得到 413/documents/upload与/documents/text(s)的批量摄取应不受影响。确认文档处理路径符合预期。若按第一节的建议保留了LIGHTRAG_PARSER*:legacy-F新上传文件应与 v1.4 行为一致对切换到新解析引擎的文档按“删除 重新上传”操作后通过/documents/track_status/{track_id}查询处理状态pending/processing/processed/failed确认结果。边界与限制修改解析引擎或 chunker 配置都不回溯旧文档前者需删除并重新上传后者需重新处理升级后不要预期“重启即全量生效”。数据迁移方面本升级本身不需要迁移但若同时更换 embedding 或存储后端重索引仍是文档给出的通用路径。旧版本在升级完成后不应再被启动回同一存储与 workspace这一点在文档中是明确的不安全操作。更多管线细节路由语法、解析器缓存、并发规则可查阅 FileProcessingPipeline.md解析器路由与处理选项的完整说明见 docs/LightRAG-API-Server.md 的 “Document and Chunk Processing” 一节。【免费下载链接】LightRAG[EMNLP2025] LightRAG: Simple and Fast Retrieval-Augmented Generation项目地址: https://gitcode.com/GitHub_Trending/li/LightRAG创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
LightRAG 从 v1.4.16 升级到 v1.5.x 前需要检查哪些文件处理管线与配置变更【免费下载链接】LightRAG[EMNLP2025] LightRAG: Simple and Fast Retrieval-Augmented Generation项目地址: https://gitcode.com/GitHub_Trending/li/LightRAG如果你正在运行 LightRAG v1.4.16准备升级到 v1.5.x需要先确认几件事v1.5.x 引入了新的文件处理流水线、解析器路由LIGHTRAG_PARSER、多模态分析、基于角色的 LLM/VLM 配置、JSON 实体抽取以及若干 provider/storage 变更。升级前请先阅读 v1.5.0rc2 发布说明然后按本文对照.env与部署拓扑逐项检查。以下内容均出自项目文档 docs/LightRAG-API-Server.md 的 “Upgrading from v1.4.16 to v1.5.x” 及配套章节。一、文件处理管线的变化v1.5 引入了分阶段的文档管线文件先经过内容抽取引擎extraction engine可选的多模态分析文本分块最后做实体/关系抽取除非该文件禁用了知识图谱构建。文件如何进入这条管线由LIGHTRAG_PARSER控制规则按文件扩展名从左到右匹配例如LIGHTRAG_PARSERpdf:mineru-R,docx:native-ietP,*:legacy-R支持的引擎包括legacy原有抽取行为、native内置结构化解析器目前聚焦.docx与 LightRAG Document sidecar、mineru外部 MinerU 服务和docling外部 docling-serve 服务。升级前需要明确的两个判断是否沿用旧行为。如果只想升级服务器、保持 v1.4 的文件处理行为设置LIGHTRAG_PARSER*:legacy-F已有文档不会被重新路由。修改LIGHTRAG_PARSER或文件名 hint 只影响新上传的文件。若要把某份已有文档切换到另一个解析引擎必须先删除该文档再重新上传。二、配置项检查清单1. 移除ENTITY_TYPES会导致启动失败ENTITY_TYPES在 v1.5 中已不再支持取而代之的是 prompt profile改用ENTITY_TYPE_PROMPT_FILE指向一个只含文件名的 YAML profile文件从PROMPT_DIR/entity_type下加载不要传绝对路径。PROMPT_DIR默认是./prompts。仓库提供了参考模板 prompts/samples/entity_type_prompt.sample.yml其中包含entity_types_guidance、entity_extraction_examples和entity_extraction_json_examples三段内容。文档明确警告如果旧.env中仍保留ENTITY_TYPES服务器会直接启动失败fail fast。因此升级前先从.env删除该行再按需配置ENTITY_EXTRACTION_USE_JSONtrue ENTITY_TYPE_PROMPT_FILEentity_type_prompt.yml PROMPT_DIR/opt/lightrag/promptsENTITY_EXTRACTION_USE_JSON在 v1.5 中因可靠性被推荐开启但会增加延迟可按需取舍。2. Embedding 配置任何改变都意味着重索引更换 embedding 模型、embedding 维度、非对称 embedding 行为EMBEDDING_ASYMMETRIC或 query/document 前缀都会改变向量语义。文档给出的处理方式是清空受影响的 LightRAG workspace/向量数据并重新索引源文件。文档还提醒对 PostgreSQL 等存储向量维度在首次建表时就已固定这类变更的代价更高。如果升级时没有动这些配置则不需要重索引。3. OpenSearch 存储的版本门槛如果使用 OpenSearch 存储且集群版本低于 OpenSearch 3.3.0要先升级 OpenSearch再启用 v1.5 的存储路径并校验已有索引。新部署则直接使用 OpenSearch 3.3.0 或更高版本。4. Chunker 配置CHUNK_*与多模态选项修改CHUNK_SIZE、CHUNK_OVERLAP_SIZE等CHUNK_*配置只在服务器重启后新入队的文档上生效。这些值在启动时读取并在文档入队时作为 per-document 的chunk_options快照保存。若希望旧文档的chunk_options快照也采用新配置需要重新处理这些文档。启用多模态选项i/t/e需要文档已有解析 sidecar并设置VLM_PROCESS_ENABLEtrue。已有文档可以通过重新处理在可用 sidecar 上补跑 VLM 分析但切换抽取引擎仍然需要删除 重新上传。三、请求体上限客户端行为会变升级后MAX_REQUEST_BODY_BYTES会默认开启为 1 MiB此前默认关闭且只覆盖三条摄取路由对客户端有两点直接影响普通路由上超过 1 MiB 的请求体返回 413包括/query*、/api/chat、/api/generate等既非上传也非文本插入的路由。/documents/text与/documents/texts保留 50 MiB 上限/documents/upload的上限由MAX_UPLOAD_SIZE派生批量摄取不受影响。把MAX_REQUEST_BODY_BYTES设为任意正值可让它统一约束所有非上传路由设为0关闭全部上限。模型侧字段有固定上限且不可配置单个 query/prompt 64 KiB、单条消息 32 KiB、每请求模型侧文本合计 128 KiB、最多 128 条消息、top_k/chunk_top_k最大 1000、max_*_tokens最大 1,000,000。依赖无界top_k或数 MB 查询文本的客户端需要在升级前调整。四、管线调度的并发协议升级顺序的关键引入PIPELINE_SCHEDULING_PAGE_SIZE、MAX_PENDING_DOCUMENTS和MAX_UNACKED_MANUAL_RETRIES见 env.example的版本同时改变了各 writer 通过共享状态协调的并发协议。这是一次一次性、原地的升级不写任何 marker也不写协议版本号存储层无法替你识别残留的旧 writer。文档因此给出硬性运维要求在对同一存储、同一 workspace 启动新版本之前必须先停掉所有旧 writer。滚动重启时只要还留着一个旧 worker——或者一个共用同一 Redis/PostgreSQL workspace 的旧实例——就是故障场景而不只是升级变慢。旧 writer 无法遵守的三点行为是这条要求的原因manual retry 冻结/documents/reprocess_failed不再就地重置FAILED行而是发布 intent、冻结入口、等管线空闲后分页把FAILED改写为PENDING。旧 writer 不读冻结标志会继续往这个被重置逻辑视为独占的窗口里入队。调度排序键created_at现在以 UTC ISO-8601 时间戳写入作为不可变的(created_at, id)keyset 游标。旧 writer 用其他格式打上的时间戳会造成 keyset 分页跳过或重复文档。派生索引在 Redis 上status 集合与 source multimap 与文档主记录在同一事务中维护旧 writer 只更新主记录会让索引停留在陈旧状态strict 分页与 strict 活跃计数会静默漏掉该文档。推荐升级顺序停止接收新文档等待管线跑完。用已鉴权的/health确认没有任何在途工作时scheduling.drain_waiting_on_workers为false、scheduling.drain_pending_enqueues为0curl -H X-API-Key: key http://localhost:9621/health停掉共用该存储与 workspace 的全部worker 和实例Gunicorn 多 worker 部署要停掉整个进程组而不是逐个滚动替换。启动新版本。不需要数据迁移。启动后的第一轮 sweep 是一次 strict 全量 sweep旧 writer 留在半途的文档例如卡在PARSING/ANALYZING/PROCESSING且背后已没有 worker 的行会被自动捡起并重新处理。如果某次运行确实无法排空中途停止同样是安全的不安全的是事后把旧版本重新启动回来。五、升级后的验证检查启动日志中的 strict 能力告警。五个内置doc_status后端JSON、Redis、PostgreSQL、MongoDB、OpenSearch都具备全部能力第三方后端可能缺失且每一项缺失都是失败关闭而非静默降级admission 返回 503、source-conflict 端点返回 501、scan 会一直重复检查陈旧的FAILEDstub。启动日志会逐项列出缺失能力及代价已鉴权的/health在capabilities字段下报告同一份信息。若希望把这些缺口直接变成启动失败设置PIPELINE_REQUIRE_STRICT_STORAGE_READStrue。注意有界分页没有对应旋钮分页与 typed source 解析方法是抽象方法缺失相应能力的后端根本无法被构造。确认请求上限符合预期。对普通路由发送超过 1 MiB 的请求体应得到 413/documents/upload与/documents/text(s)的批量摄取应不受影响。确认文档处理路径符合预期。若按第一节的建议保留了LIGHTRAG_PARSER*:legacy-F新上传文件应与 v1.4 行为一致对切换到新解析引擎的文档按“删除 重新上传”操作后通过/documents/track_status/{track_id}查询处理状态pending/processing/processed/failed确认结果。边界与限制修改解析引擎或 chunker 配置都不回溯旧文档前者需删除并重新上传后者需重新处理升级后不要预期“重启即全量生效”。数据迁移方面本升级本身不需要迁移但若同时更换 embedding 或存储后端重索引仍是文档给出的通用路径。旧版本在升级完成后不应再被启动回同一存储与 workspace这一点在文档中是明确的不安全操作。更多管线细节路由语法、解析器缓存、并发规则可查阅 FileProcessingPipeline.md解析器路由与处理选项的完整说明见 docs/LightRAG-API-Server.md 的 “Document and Chunk Processing” 一节。【免费下载链接】LightRAG[EMNLP2025] LightRAG: Simple and Fast Retrieval-Augmented Generation项目地址: https://gitcode.com/GitHub_Trending/li/LightRAG创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
