LightRAG 怎么把解析结果接入 Python SDKinitialize_storages 初始化与 check_initialization 诊断【免费下载链接】LightRAG[EMNLP2025] LightRAG: Simple and Fast Retrieval-Augmented Generation项目地址: https://gitcode.com/GitHub_Trending/li/LightRAG如果你的文档解析、抽取已经完成下一步是把得到的文本接入 LightRAG 的 Python SDK创建LightRAG实例、完成存储初始化、写入文本并查询同时在初始化环节出问题时能快速定位原因。LightRAG 官方文档 ProgramingWithCore.md 说明 Core SDK 面向嵌入式应用和研究评估场景官方推荐用 REST API 集成完整项目本文聚焦 SDK 路径。整条路径的关键约束只有一条创建实例后必须显式调用await rag.initialize_storages()否则后续操作会直接报错。初始化是否正确可以用仓库自带的诊断工具 lightrag/tools/check_initialization.py 核实。准备条件Python 版本满足3.10见 pyproject.toml 的requires-python。安装 SDKpip install lightrag-hkuREADME 中给出的安装方式在仓库内本地开发时用pip install -e .。官方示例程序使用 OpenAI 的openai_embed与gpt_4o_mini_complete文档要求运行前导出OPENAI_API_KEY环境变量。使用其他 LLM/Embedding 绑定时可换用文档中的其他注入方式但初始化流程不变。接入主路径创建、初始化、插入、查询、收尾ProgramingWithCore.md 给出的最小程序如下它覆盖了完整的初始化与数据流转import os import asyncio from lightrag import LightRAG, QueryParam from lightrag.llm.openai import gpt_4o_mini_complete, gpt_4o_complete, openai_embed from lightrag.utils import setup_logger setup_logger(lightrag, levelINFO) WORKING_DIR ./rag_storage if not os.path.exists(WORKING_DIR): os.mkdir(WORKING_DIR) async def initialize_rag(): rag LightRAG( working_dirWORKING_DIR, embedding_funcopenai_embed, llm_model_funcgpt_4o_mini_complete, ) # IMPORTANT: Both initialization calls are required! await rag.initialize_storages() # Initialize storage backends return rag async def main(): try: # Initialize RAG instance rag await initialize_rag() await rag.ainsert(Your text) # Perform hybrid search mode hybrid print( await rag.aquery( What are the top themes in this story?, paramQueryParam(modemode) ) ) except Exception as e: print(fAn error occurred: {e}) finally: if rag: await rag.finalize_storages() if __name__ __main__: asyncio.run(main())按文档要求替换两处内容即可运行ainsert的参数换成你解析得到的文本可传字符串或字符串列表aquery的问题换成你的实际问题。代码中三个动作的分工LightRAG(...)只创建配置对象。working_dir是所有数据的持久化目录默认./rag_storageembedding_func与llm_model_func在初始化时注入。仓库内 reproduce/Step_1.py 的写法与之一致其initialize_rag中同样先建实例再await rag.initialize_storages()注释写明该调用会 Auto-initializes pipeline_status——即管道状态随本次初始化一起建立。await rag.initialize_storages()真正初始化存储后端与管道状态。文档用Important标出LightRAG requires explicit initialization before use必须在创建实例后调用否则会遭遇错误。实例上还有对应的收尾调用await rag.finalize_storages()示例放在finally中它负责释放已初始化的存储。ainsert/aquery插入与混合检索。如果你的输入还是原始文档文件而非纯文本文档提供了用textract先提取再插入的分支支持 TXT、DOCX、PPTX、CSV、PDFimport textract file_path TEXT.pdf text_content textract.process(file_path) rag.insert(text_content.decode(utf-8))需要区分必做与可选initialize_storages()是必做步骤textract分支只在你需要把文件直接转成文本时使用QueryParam的其他参数检索模式、top_k 等在 ProgramingWithCore.md 的 QueryParam 一节有完整定义默认modemix。用 check_initialization 诊断初始化是否到位lightrag/tools/check_initialization.py 的模块说明写明它用于在initialize_storages()之后验证 LightRAG 实例是否处于可用状态核心入口是check_lightrag_setup(rag_instance, verboseFalse)。在你的代码里接在初始化之后from lightrag.tools.check_initialization import check_lightrag_setup rag LightRAG(...) await rag.initialize_storages() ok await check_lightrag_setup(rag, verboseTrue)返回值是布尔值初始化就绪返回True发现问题返回False。verboseTrue时逐项打印各存储组件 Ready 的状态False时打印问题清单并给出修复指引——重新执行await rag.initialize_storages()。它实际检查三组内容实例状态读取rag._storages_status必须是INITIALIZED。该状态取自 lightrag/base.py 的StoragesStatus枚举共四个取值not_created、created、initialized、finalized漏掉初始化时工具会报告类似Storages not initialized (status: created)的问题。十个存储组件full_docs、text_chunks、entities_vdb、relationships_vdb、chunks_vdb、doc_status、llm_response_cache、full_entities、full_relations、chunk_entity_relation_graph。组件缺失或存储锁未建立记为 issue组件为None只记为 warning工具注明 might be optional。管道状态通过get_namespace_data(pipeline_status, workspacerag_instance.workspace)确认管道状态已初始化未初始化时会提示 call rag.initialize_storages() first。也可以不进代码直接跑命令行演示python -m lightrag.tools.check_initialization --demo注意这条命令的副作用--demo会用默认 OpenAI 绑定创建一个working_dir./test_diagnostic的实例执行初始化和诊断结束时用shutil.rmtree(./test_diagnostic, ignore_errorsTrue)删除该目录。它适合验证环境本身能走通初始化但会实际创建并删除本地目录且依赖 OpenAI 凭据。不带--demo直接运行只会打印用法提示。README 的 Maintenance Tools 一节对这个工具的定位是SDK diagnostic, verifies that aLightRAGinstance is fully initialized, catching the common forgotawait rag.initialize_storages() mistake。初始化失败时的两个典型报错ProgramingWithCore.md 的 Troubleshooting 一节列出了与初始化直接相关的报错及处理报错文档给出的原因文档给出的解决方式AttributeError: __aenter__存储后端未初始化在创建实例后调用await rag.initialize_storages()KeyError: history_messages管道状态未初始化同上两个报错相继出现同上严格遵循rag LightRAG(...)→await rag.initialize_storages()的顺序也就是说无论写入还是查询阶段先撞上哪个报错修复动作都是同一个补上初始化调用。如果补上后仍异常用上一节的check_lightrag_setup(rag, verboseTrue)看具体是哪个组件或状态没有就绪。接入时容易踩的限制默认存储不适合生产四类存储KV、向量、图、文档状态的默认实现都是内存数据库持久化到working_dir下的本地文件容量受可用内存限制。文档明确默认后端只适合小规模测试、评估和调试生产环境推荐 PostgreSQL它可以单独承担全部四种存储类型。更换 embedding 模型必须清空数据目录切换 embedding 模型后已有向量与模型空间不匹配文档要求清空数据目录唯一可以考虑保留的文件是kv_store_llm_response_cache.jsonLLM 缓存。索引与查询使用的 embedding 模型必须一致。workspace 初始化后不可变workspace参数用于多个 LightRAG 实例间的数据隔离一旦初始化就不能再改。模型要求文档建议 LLM 至少 32B 参数、32KB 上下文推荐 64KB索引阶段避免使用推理型模型这些是官方给出的选型要求不是可选项。完成初始化和诊断后仓库中 examples/lightrag_openai_demo.py 提供了一个完整的可运行示例如果你的目标最终是服务端集成而不是进程内调用文档的原始建议是改用 LightRAG Server 提供的 REST APICore SDK 保留给嵌入式与研究场景。【免费下载链接】LightRAG[EMNLP2025] LightRAG: Simple and Fast Retrieval-Augmented Generation项目地址: https://gitcode.com/GitHub_Trending/li/LightRAG创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考