LightRAG 离线部署完全指南分层依赖、Tiktoken 缓存与完整无网安装工作流【免费下载链接】LightRAG[EMNLP2025] LightRAG: Simple and Fast Retrieval-Augmented Generation项目地址: https://gitcode.com/GitHub_Trending/li/LightRAGLightRAG 依赖pipmaster动态安装可选组件并会在首次使用时从网络下载 tiktoken BPE 编码模型这些“运行时取网”行为在无网环境中必然失败。本篇基于官方文档 docs/OfflineDeployment.md系统讲解如何用分层 extras 依赖组、lightrag-download-cache命令行工具和pip download本地包目录在完全断网的服务器上完成 LightRAG 的可复现安装并覆盖 spaCy 智能标题模型的离线准备与常见故障排查。读完本文你可以独立完成“在线环境备料 → 介质传输 → 离线安装 → 验证”的全链路部署。前提说明如果使用 Docker 部署 LightRAG则无需参考本文——LightRAG 的 Docker 镜像已为离线运行做了预配置详见 Docker 部署指南。本文面向非 Docker 的 pip 部署场景。1. 为什么离线部署需要特殊处理动态安装机制LightRAG 对可选功能采用动态包安装基于pipmaster根据文件类型和配置在运行时按需pip install对应依赖。在离线环境中这些动态安装会失败。因此离线部署的核心思路是提前把所有依赖装进本地包目录并预先下载所有需要联网获取的缓存文件。从源码结构看动态安装的入口分散在各后端实现中。例如 Neo4j 后端在 lightrag/kg/neo4j_impl.py 中执行pm.install(neo4j)LLM 绑定模块如 lightrag/llm/anthropic.py 也通过import pipmaster as pm触发按需安装。API 服务入口 lightrag/api/lightrag_server.py 同样引用了pipmaster。1.1 哪些组件会被动态安装类别涉及包存储后端redis、neo4j、pymilvus、pymongo、asyncpg、qdrant-clientLLM 提供商openai、anthropic、ollama、zhipuai、aioboto3、voyageai、llama-index、lmdeploy、transformers、torchTiktoken 模型从 OpenAI CDN 下载的 BPE 编码模型需要注意两个边界事实与 pyproject.toml 中 extras 定义一致文档解析依赖pypdf、python-docx、python-pptx、openpyxl现已随apiextras 组预装不再需要动态安装依赖transformers、torch或cuda的包不纳入离线依赖组。因此 Docling 等文档抽取工具以及 Hugging Face、LMDeploy 等本地 LLM 模型不在离线安装支持范围之内。这类高算力服务不应直接集成进 LightRAGDocling 将以独立服务的方式解耦部署。2. 分层依赖组按用途裁剪安装面LightRAG 在 pyproject.toml 中定义了灵活的分层依赖组对应仓库根目录下的 requirements-offline.txt、requirements-offline-storage.txt、requirements-offline-llm.txt 与 requirements-offline-smart-heading.txtGroup说明适用场景apiAPI 服务 文档解析带 PDF、DOCX、PPTX、XLSX 支持的 FastAPI 服务offline-storage存储后端Redis、Neo4j、MongoDB、PostgreSQL 等offline-llmLLM 提供商OpenAI、Anthropic、Ollama 等offline完整离线包API 存储 LLM全部功能从 pyproject.toml 可以看到offline组的实际定义是lightrag-hku[api,offline-storage,offline-llm]即它是其余三组的超集组合。说明文档解析PDF、DOCX、PPTX、XLSX包含在apiextras 组中此前的offline-docs组已并入api以获得更好的集成度。2.1 安装示例extras 方式# 安装 API 及文档解析能力 pip install lightrag-hku[api] # 安装 API 和存储后端 pip install lightrag-hku[api,offline-storage] # 安装全部离线依赖离线部署推荐 pip install lightrag-hku[offline]2.2 使用单独的 requirements 文件如果不用 extras也可以直接用仓库随附的 requirements 文件版本约束与pyproject.toml保持一致# 仅存储后端faiss-cpu、redis、neo4j、pymilvus、pymongo、asyncpg、pgvector、qdrant-client、opensearch-py pip install -r requirements-offline-storage.txt # 仅 LLM 提供商openai、anthropic、ollama、zhipuai、aioboto3、voyageai、llama-index 等 pip install -r requirements-offline-llm.txt # 全部离线依赖API 存储 LLM pip install -r requirements-offline.txt3. 快速上手两种离线部署路径3.1 路径一使用 pip 的离线 extras# 在线环境安装全部离线依赖 pip install lightrag-hku[offline] # 下载 tiktoken 缓存 lightrag-download-cache # 创建离线包 pip download lightrag-hku[offline] -d ./offline-packages tar -czf lightrag-offline.tar.gz ./offline-packages ~/.tiktoken_cache # 传输到离线服务器 scp lightrag-offline.tar.gz useroffline-server:/path/to/ # 离线环境安装 tar -xzf lightrag-offline.tar.gz pip install --no-index --find-links./offline-packages lightrag-hku[offline] export TIKTOKEN_CACHE_DIR~/.tiktoken_cache3.2 路径二使用 Requirements 文件# 在线环境下载包 pip download -r requirements-offline.txt -d ./packages # 传输到离线服务器 tar -czf packages.tar.gz ./packages scp packages.tar.gz useroffline-server:/path/to/ # 离线环境安装 tar -xzf packages.tar.gz pip install --no-index --find-links./packages -r requirements-offline.txt4. Tiktoken 缓存管理token 计数的离线命门LightRAG 使用 lightrag/utils.py 中的TiktokenTokenizer作为默认分词器默认模型为gpt-4o-mini而 tiktoken 会在首次使用时下载 BPE 编码模型。离线环境下必须提前下载这些模型。4.1 使用内置 CLI 命令lightrag-download-cache是 pyproject.toml 中注册的命令行入口实现位于 lightrag/tools/download_cache.py。安装 LightRAG 后可直接使用# 下载到默认位置输出中会打印确切路径 lightrag-download-cache # 下载到指定目录 lightrag-download-cache --cache-dir ./tiktoken_cache # 只下载指定模型 lightrag-download-cache --models gpt-4o-mini gpt-4该命令还支持--tiktoken、--spacy、--spacy-dir、--spacy-install等参数单独指定--cache-dir或--models即会选中 tiktoken 下载--spacy分支独立于 tiktoken 运行不会触碰 tiktoken 缓存见 download_cache.py 的参数定义。4.2 默认下载的模型gpt-4o-miniLightRAG 默认gpt-4ogpt-4gpt-3.5-turbotext-embedding-ada-002text-embedding-3-smalltext-embedding-3-large另外从 download_cache.py 的源码可以确认默认列表还额外包含cl100k_base编码LightRAG 的默认编码之一共 8 项。工具对“模型名”与“编码名”做了区分属于cl100k_base、p50k_base、r50k_base、o200k_base的走tiktoken.get_encoding()其余走tiktoken.encoding_for_model()download_cache.py、download_cache.py。4.3 在离线环境设置缓存位置# 方式 1环境变量临时 export TIKTOKEN_CACHE_DIR/path/to/tiktoken_cache # 方式 2写入 ~/.bashrc 或 ~/.zshrc持久化 echo export TIKTOKEN_CACHE_DIR~/.tiktoken_cache ~/.bashrc source ~/.bashrc # 方式 3复制到默认位置 cp -r /path/to/tiktoken_cache ~/.tiktoken_cache/一个容易踩坑的细节tiktoken 在导入时读取TIKTOKEN_CACHE_DIR环境变量。download_cache.py 因此特意在import tiktoken之前设置该变量并在注释中明确说明这一点——如果你在离线脚本里自行操作 tiktoken也要注意设置时序。5. spaCy 模型原生 docxsmart_heading的可选离线准备原生 docx 解析器的可选smart_heading引擎参数使用 spaCy 做句子切分 / NER 启发式判断。该依赖是惰性加载的只在文档以smart_headingtrue解析时才加载若未启用smart_heading完全不需要本节内容。缺失模型时会在解析点抛出硬错误绝不静默降级。若通过DOCX_SMART_HEADINGtrue全局开启或配置了带native(smart_headingtrue)的LIGHTRAG_PARSER规则检查会提前到服务启动阶段——服务器会在启动时校验模型并快速失败同时给出安装指引。Docker 部署不需要本节主 LightRAG 镜像已打包 spaCy 运行时和两个固定版本模型lite 镜像只含运行时在其上启用smart_heading仍需自行安装模型。以下步骤适用于非 Docker 的 pip 部署。5.1 为什么模型版本被严格钉死两个语言模型被固定到精确版本zh_core_web_sm/en_core_web_sm3.8.0因为smart_heading承诺确定性的重解析结果——模型版本漂移会静默改变 NER 与句子切分判断。zh 模型的 tokenizer 后端spacy-pkuseg固定为 1.0.1随模型 wheel 一并分发原因相同。这些 pin 在 download_cache.py 的SPACY_MODEL_WHEELS与 requirements-offline-smart-heading.txt 中保持同步spaCy 运行时则由apiextras 中的spacy3.8,3.8.14提供见 pyproject.toml。5.2 在线环境准备# spaCy 运行时api extra 已包含 pip install lightrag-hku[api] # 或pip install -r requirements-offline-smart-heading.txt运行时 模型 # 为离线传输准备下载运行时 模型 wheels 到 ./packages pip download -r requirements-offline-smart-heading.txt -d ./packages # 或只下载固定版本的模型 wheels默认到 ./spacy_models # --spacy 独立于 tiktoken 缓存下载不会触碰 tiktoken lightrag-download-cache --spacy-dir ./spacy_models # 或直接在当前环境中安装 lightrag-download-cache --spacy-install5.3 离线环境安装# 从传输来的 wheel 目录按名称安装。注意不要在这里使用 # -r requirements-offline-smart-heading.txt其中的模型 pin 是 # GitHub 直链即使加了 --no-indexpip 仍会走网络拉取直链依赖。 pip install --no-index --find-links./packages spacy zh_core_web_sm en_core_web_sm # 或者只安装 lightrag-download-cache --spacy 下载的模型 wheels pip install --no-index --find-links./spacy_models zh_core_web_sm en_core_web_sm这一点在 requirements-offline-smart-heading.txt 的文件头注释中也有明确警告是离线安装中非常隐蔽的一个坑。6. 完整离线部署工作流四步法Step 1在线环境准备# 1. 安装带离线依赖的 LightRAG pip install lightrag-hku[offline] # 2. 下载 tiktoken 缓存 lightrag-download-cache --cache-dir ./offline_cache/tiktoken # 3. 下载全部 Python 包 pip download lightrag-hku[offline] -d ./offline_cache/packages # 4. 创建传输归档 tar -czf lightrag-offline-complete.tar.gz ./offline_cache # 5. 校验内容 tar -tzf lightrag-offline-complete.tar.gz | head -20Step 2传输到离线环境# 使用 scp scp lightrag-offline-complete.tar.gz useroffline-server:/tmp/ # 或使用 U 盘/物理介质 # 将 lightrag-offline-complete.tar.gz 拷入 U 盘Step 3离线环境安装# 1. 解压归档 cd /tmp tar -xzf lightrag-offline-complete.tar.gz # 2. 安装 Python 包 pip install --no-index \ --find-links/tmp/offline_cache/packages \ lightrag-hku[offline] # 3. 配置 tiktoken 缓存 mkdir -p ~/.tiktoken_cache cp -r /tmp/offline_cache/tiktoken/* ~/.tiktoken_cache/ export TIKTOKEN_CACHE_DIR~/.tiktoken_cache # 4. 写入 shell profile 持久化 echo export TIKTOKEN_CACHE_DIR~/.tiktoken_cache ~/.bashrcStep 4验证安装# 测试 Python 导入 python -c from lightrag import LightRAG; print(✓ LightRAG imported) # 测试 tiktoken python -c from lightrag.utils import TiktokenTokenizer; t TiktokenTokenizer(); print(✓ Tiktoken working) # 测试可选依赖如已安装 python -c import redis; print(✓ Redis available)其中第二条验证命令正是直接实例化TiktokenTokenizerlightrag/utils.py它会触发 tiktoken 从TIKTOKEN_CACHE_DIR指向的缓存读取gpt-4o-mini的 BPE 模型——如果缓存文件缺失或环境变量未设置这一步会立即暴露问题是验证离线部署是否完备的最直接探针。7. 故障排查问题 1Tiktoken 报网络错误现象Unable to load tokenizer for model gpt-4o-mini解决# 确认 TIKTOKEN_CACHE_DIR 已设置 echo $TIKTOKEN_CACHE_DIR # 验证缓存文件存在 ls -la ~/.tiktoken_cache/ # 若为空需要先在在线环境下载缓存问题 2动态包安装失败现象Error installing package xxx解决预装你实际需要的组件见 pyproject.toml 中的分组定义# API 与文档解析 pip install lightrag-hku[api] # 存储后端 pip install lightrag-hku[offline-storage] # LLM 提供商 pip install lightrag-hku[offline-llm]问题 3运行时缺少依赖现象ModuleNotFoundError: No module named xxx解决# 查看已安装包 pip list | grep -i xxx # 安装缺失组件 pip install lightrag-hku[offline] # 安装全部离线依赖问题 4tiktoken 缓存权限不足现象PermissionError: [Errno 13] Permission denied解决# 确保缓存目录权限正确 chmod 755 ~/.tiktoken_cache chmod 644 ~/.tiktoken_cache/* # 或改用用户可写目录 export TIKTOKEN_CACHE_DIR~/my_tiktoken_cache mkdir -p ~/my_tiktoken_cache8. 最佳实践先在线验证去离线之前务必先在联网环境完整测试一遍部署流程。保持缓存更新每当有新模型发布时定期更新离线缓存。记录你的部署记下你实际用到了哪些可选依赖便于后续维护。版本固定生产环境建议固定版本pip freeze requirements-production.txt最小化安装只装需要的部分例如只需要 API 文档解析时pip install lightrag-hku[api] # 再按需手动添加特定 LLMpip install openai9. 延伸阅读Docker 部署指南镜像已预置离线运行所需的依赖API 服务文档离线安装完成后的服务启动与配置lightrag/tools/download_cache.pylightrag-download-cache命令的完整实现tiktoken 与 spaCy 两条下载分支、退出码语义pyproject.toml各 extras 依赖组的权威版本约束来源。【免费下载链接】LightRAG[EMNLP2025] LightRAG: Simple and Fast Retrieval-Augmented Generation项目地址: https://gitcode.com/GitHub_Trending/li/LightRAG创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考