LightRAG 离线部署完全指南：分层依赖、Tiktoken 缓存与完整无网安装工作流

LightRAG 依赖 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-client
LLM 提供商	openai、anthropic、ollama、zhipuai、aioboto3、voyageai、llama-index、lmdeploy、transformers、torch
Tiktoken 模型	从 OpenAI CDN 下载的 BPE 编码模型

需要注意两个边界事实（与 pyproject.toml 中 extras 定义一致）：

• 文档解析依赖（pypdf、python-docx、python-pptx、openpyxl）现已随 api extras 组预装，不再需要动态安装；
• 依赖 transformers、torch 或 cuda 的包不纳入离线依赖组。因此 Docling 等文档抽取工具，以及 Hugging Face、LMDeploy 等本地 LLM 模型不在离线安装支持范围之内。这类高算力服务不应直接集成进 LightRAG，Docling 将以独立服务的方式解耦部署。

2. 分层依赖组：按用途裁剪安装面

LightRAG 在 pyproject.toml 中定义了灵活的分层依赖组，对应仓库根目录下的 requirements-offline.txt、requirements-offline-storage.txt、requirements-offline-llm.txt 与 requirements-offline-smart-heading.txt：

Group	说明	适用场景
api	API 服务 + 文档解析	带 PDF、DOCX、PPTX、XLSX 支持的 FastAPI 服务
offline-storage	存储后端	Redis、Neo4j、MongoDB、PostgreSQL 等
offline-llm	LLM 提供商	OpenAI、Anthropic、Ollama 等
offline	完整离线包	API + 存储 + LLM（全部功能）

从 pyproject.toml 可以看到，offline 组的实际定义是 lightrag-hku[api,offline-storage,offline-llm]，即它是其余三组的超集组合。

说明：文档解析（PDF、DOCX、PPTX、XLSX）包含在 api extras 组中，此前的 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.txt

3. 快速上手：两种离线部署路径

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 user@offline-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_cache

3.2 路径二：使用 Requirements 文件

# 在线环境：下载包
pip download -r requirements-offline.txt -d ./packages

# 传输到离线服务器
tar -czf packages.tar.gz ./packages
scp packages.tar.gz user@offline-server:/path/to/

# 离线环境：安装
tar -xzf packages.tar.gz
pip install --no-index --find-links=./packages -r requirements-offline.txt

4. 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-mini（LightRAG 默认）
• gpt-4o
• gpt-4
• gpt-3.5-turbo
• text-embedding-ada-002
• text-embedding-3-small
• text-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 模型：原生 docx smart_heading 的可选离线准备

原生 docx 解析器的可选 smart_heading 引擎参数使用 spaCy 做句子切分 / NER 启发式判断。该依赖是惰性加载的：只在文档以 smart_heading=true 解析时才加载；若未启用 smart_heading，完全不需要本节内容。缺失模型时会在解析点抛出硬错误（绝不静默降级）。若通过 DOCX_SMART_HEADING=true 全局开启，或配置了带 native(smart_heading=true) 的 LIGHTRAG_PARSER 规则，检查会提前到服务启动阶段——服务器会在启动时校验模型并快速失败，同时给出安装指引。

Docker 部署不需要本节：主 LightRAG 镜像已打包 spaCy 运行时和两个固定版本模型（lite 镜像只含运行时，在其上启用 smart_heading 仍需自行安装模型）。以下步骤适用于非 Docker 的 pip 部署。

5.1 为什么模型版本被严格钉死

两个语言模型被固定到精确版本（zh_core_web_sm / en_core_web_sm 3.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 运行时则由 api extras 中的 spacy>=3.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-install

5.3 离线环境安装

# 从传输来的 wheel 目录按名称安装。注意：不要在这里使用
# `-r requirements-offline-smart-heading.txt`：其中的模型 pin 是
# GitHub 直链，即使加了 --no-index，pip 仍会走网络拉取直链依赖。
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 -20

Step 2：传输到离线环境

# 使用 scp
scp lightrag-offline-complete.tar.gz user@offline-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' >> ~/.bashrc

Step 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')"

其中第二条验证命令正是直接实例化 TiktokenTokenizer（lightrag/utils.py），它会触发 tiktoken 从 TIKTOKEN_CACHE_DIR 指向的缓存读取 gpt-4o-mini 的 BPE 模型——如果缓存文件缺失或环境变量未设置，这一步会立即暴露问题，是验证离线部署是否完备的最直接探针。

7. 故障排查

问题 1：Tiktoken 报网络错误

现象：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]  # 安装全部离线依赖

问题 4：tiktoken 缓存权限不足

现象：PermissionError: [Errno 13] Permission denied

解决：

# 确保缓存目录权限正确
chmod 755 ~/.tiktoken_cache
chmod 644 ~/.tiktoken_cache/*

# 或改用用户可写目录
export TIKTOKEN_CACHE_DIR=~/my_tiktoken_cache
mkdir -p ~/my_tiktoken_cache

8. 最佳实践

1. 先在线验证：去离线之前，务必先在联网环境完整测试一遍部署流程。

2. 保持缓存更新：每当有新模型发布时，定期更新离线缓存。

3. 记录你的部署：记下你实际用到了哪些可选依赖，便于后续维护。

4. 版本固定：生产环境建议固定版本：

   pip freeze > requirements-production.txt
   

5. 最小化安装：只装需要的部分，例如只需要 API + 文档解析时：

   pip install lightrag-hku[api]
   # 再按需手动添加特定 LLM：pip install openai
   

9. 延伸阅读

• Docker 部署指南：镜像已预置离线运行所需的依赖；
• API 服务文档：离线安装完成后的服务启动与配置；
• lightrag/tools/download_cache.py：lightrag-download-cache 命令的完整实现（tiktoken 与 spaCy 两条下载分支、退出码语义）；
• pyproject.toml：各 extras 依赖组的权威版本约束来源。