上个星期在客户现场部署 RAGFlow所有的服务容器都拉起来了唯独 ragflow-server 一直在重启。docker logs 拉出来一看满屏都是 tiktoken 下载词表的报错核心就是 cl100k_base.tiktoken 这个文件拉不下来。客户环境是隔离内网没有外网出口这个文件下载失败服务就卡在初始化整个知识库流程根本推不动。RAGFlow 做文档解析、文本切片的时候默认要用 tiktoken 对文本做 token 化这是 OpenAI 开源的一个分词库。cl100k_base 是它内置的编码词表对应 GPT-4、GPT-3.5 这些模型用的 token 规则。联网环境第一次运行会自动下载几秒钟解决但到了离线环境这个下载请求就变成了拦路虎。这篇文章就专门解决这个问题把我试过有效的方法连同 RAGFlow 离线部署时其他几个高频坑一起梳理出来照着做就能填平。1. 问题复盘一个 1.35MB 的词表文件为什么能卡死服务1.1 分词器在 RAGFlow 里的定位很多人第一次看到 cl100k_base.tiktoken 报错会懵因为这不是 RAGFlow 自己的组件而是 Python 库 tiktoken 运行时的下载动作。要理解这里面的逻辑得先知道 RAGFlow 处理一份 PDF 的流程上传文档之后DeepDoc 做版面解析和 OCR把 PDF 转成结构化的文本块然后再做文本切片。切片的时候RAGFlow 需要把文本转成 token 序列用 token 数量来控制每个 chunk 的长度这样向量化的结果才均匀、检索才准。tiktoken 就是干这个转 token 的活。它本身是纯 Python 库安装很快但是首次调用tiktoken.get_encoding(cl100k_base)时如果本地缓存没有这个词表就会尝试从 OpenAI 的对象存储下载。这个文件只有 1.35MB 左右在联网环境里是秒下但内网环境直接超时失败异常抛出来文档解析链路全部停摆。1.2 报错现场长什么样RAGFlow 的日志里会出现类似这样的信息Encountered error downloading https://openaipublic.blob.core.windows.net/encodings/cl100k_base.tiktoken或者这样Connection error, and we cannot find the requested files in the local cache还有一种情况是报 HTTP 403 或者 SSL 错误但根因都一样tiktoken 在尝试联网下载而网络不通。这个报错经常出现在 ragflow-server 容器刚启动、或者第一次创建知识库上传文档的时候所以很多人一开始会误以为是 RAGFlow 其他配置有问题折腾半天才发现只是 tokenizer 词表没就绪。1.3 tiktoken 的查找顺序要把这个问题彻底解决得先明白 tiktoken 找文件的顺序。它的逻辑不复杂查内存缓存进程内已经加载过就直接复用。查环境变量TIKTOKEN_CACHE_DIR指定的目录。查默认缓存路径~/.cache/tiktoken。都没命中就向远程 URL 发 HTTP 请求下载下载成功后把文件写入缓存目录文件名的规则是 URL 的 SHA1 哈希。也就是说英文资料里说的“下载 cl100k_base.tiktoken”其实下载完之后它并不叫这个名字而是以哈希命名的无扩展名文件存在缓存目录里。这个细节很重要因为我见过有人手动创建一个叫 cl100k_base.tiktoken 的文件塞进缓存目录结果根本不生效。后来搞清楚了查找规则整个解决方案就顺理成章了我们把缓存文件和目录结构准备好骗过它的查找逻辑让它在离线环境下命中本地缓存。2. 解决思路选型试过绕路最后还是回归缓存预置2.1 几个试了但没根治的方案先说踩过的弯路避免大家重复投入。第一种思路是把 tiktoken 整个包离线安装到内网也就是拿 whl 文件 pip install。这个做了之后import tiktoken没问题但那句报错依然存在。原因很简单pip 只是把包装进了 site-packages词表数据文件还是要运行时联网拉取。第二种思路是在容器里配 HTTP 代理或者改 DNS。离线内网的网络拓扑里很多环境压根没有外网出口改网关和 DNS 都没用代理服务器也不一定找得到。这条路对真正隔离的客户网络来说基本走不通。第三种思路是写代码绕过出错点比如 catch 异常然后 fake 一个 encoding 对象。这样做异常是不抛了但 RAGFlow 后续的切片逻辑会拿不到真实的 token 计数切出来的 chunk 大小偏差很大知识库的质量直接受影响。这个方案我调试到一半就放弃了太不优雅。2.2 三个真正靠谱的方案对比真正靠谱的方案其实都是围绕“让 tiktoken 在本地找到词表文件”这个核心思路展开的。方案实现方式优点缺点方案A预置缓存目录在联网机器上生成缓存拷贝到内网并挂载进容器不碰代码升级重建容器后依然有效可沉淀为部署资产需要提前准备第一次部署多花十分钟方案B改包源码修改 tiktoken 内部的加载逻辑把远程 URL 替换成本地路径完全不依赖缓存目录逻辑改完一劳永逸每次升级镜像或升级版本要重新改易维护性差方案C低层 API 加载用Encoding类手动读本地文件构造编码对象对业务代码可控性最强需要在代码层面嵌入RAGFlow 又不是自己写的根本没法改干净我最终选择的是方案A把缓存目录做成挂载卷。理由很简单RAGFlow 官方镜像更新频率高docker compose pull之后容器重建方案B和方案C说不定就丢了但挂载卷是独立于容器生命周期的文件一直在。而且这个缓存目录后续可以放进团队内部的知识库资产里新环境部署直接拷一份全网通用。2.3 为什么说“放缓存文件”不是临时补丁我看到有些帖子说这个是“治标不治本”这个说法我不太认同。tiktoken 本身就内置了缓存目录机制环境变量TIKTOKEN_CACHE_DIR就是官方留的口子。我们做的只是把“下载”这一步在联网机器上先执行完把“产物”放到内网环境这正是离线部署的标准做法和离线安装 Python 包、离线拉 Docker 镜像是一个道理。举个例子docker pull 在联网机器上拉镜像再 save 成 tar 包拷进内网 load这是所有内网部署的常规操作。tiktoken 缓存预置和这个完全同构属于正规的离线软件分发不是 hack。3. 动手实操三步解决 cl100k_base.tiktoken照着做就行3.1 在能联网的机器上生成缓存文件找一台能访问外网的 Linux 机器最好 Python 版本和 RAGFlow 容器内的版本接近。执行下面这段命令python3 - EOF import tiktoken enc tiktoken.get_encoding(cl100k_base) print(enc.encode(hello world)) EOF第一次执行会联网下载看到输出一串数字就代表成功了。然后看一下缓存目录ls -l ~/.cache/tiktoken/正常情况下会看到一个没有扩展名的文件文件名是一长串哈希大小约 1.35MB。这就是 cl100k_base 词表在缓存目录里的真实形态。这里有个细节提醒一下如果目录下已经有多个文件不用纠结哪个是哪个全部一起拷走就行。比如有些机器上还缓存过r50k_base或者p50k_base一并拷过去也没坏处后面可能会用到。3.2 拷贝到离线服务器并调整权限把~/.cache/tiktoken/目录整个拷贝到离线服务器的固定路径比如/data/ragflow/tiktoken-cachemkdir -p /data/ragflow/tiktoken-cache cp ~/.cache/tiktoken/* /data/ragflow/tiktoken-cache/ chmod -R ar /data/ragflow/tiktoken-cache/最后一步chmod很容易被忽略。RAGFlow 容器里的进程不一定以 root 运行如果文件权限是 600 或者更严格容器内用户读不了照样报错。我之前就遇到过这种情况缓存文件位置放对了权限不对日志里报 Permission denied排查了半小时才反应过来。3.3 修改 docker-compose.yml给 ragflow-server 挂载缓存进入 RAGFlow 部署目录编辑docker-compose.yml。找到ragflow-server这个服务在environment里加上TIKTOKEN_CACHE_DIR环境变量在volumes里把宿主机目录挂载进去ragflow-server: ... environment: - TIKTOKEN_CACHE_DIR/opt/tiktoken volumes: - /data/ragflow/tiktoken-cache:/opt/tiktoken保存后重启docker compose down docker compose up -d注意volumes的挂载路径和TIKTOKEN_CACHE_DIR必须一致否则容器内找到了环境变量但目录里没有文件还是会走下载逻辑。我用过/opt/tiktoken做容器内路径避免和容器已有的数据目录冲突。3.4 容器内验证缓存是否真正生效重启完别急着去界面操作先进容器做一次单测确认 tiktoken 不再尝试联网docker exec -it ragflow-server bash python3 -c import tiktoken; enc tiktoken.get_encoding(cl100k_base); print(enc.encode(hello world))正常输出类似[15339, 2437]这样的 token id 列表而不是抛异常。看到这个输出就说明 tiktoken 在离线状态下成功读到了本地缓存。如果这一步还是报错先检查两个地方第一挂载路径是否写对了进容器执行ls -l /opt/tiktoken看看文件在不在第二文件是否有可读权限容器内执行cat /opt/tiktoken/哈希文件 | head -c 100试试。3.5 回到 RAGFlow 界面做端到端验证单测过了还要把业务链路走一遍。登录 RAGFlow 管理界面新建一个知识库选择嵌入模型上传一个测试用的小 PDF观察解析状态。如果之前卡在 pending现在变成了 done说明文档解析链路里 tiktoken 相关的问题已经清零。我习惯用一个单页的 PDF 做验证解析快容易看出问题。如果上传后状态还是长时间 pending就去 docker logs 里看 ragflow-server 有没有别的报错重点是定位是不是还有第二个网络请求被卡住。4. 不只是 tokenizer离线部署的模型链路也要一起验证4.1 嵌入模型和重排模型的离线方案tiktoken 的问题解决后RAGFlow 还有一个大头嵌入模型和重排模型。创建知识库时RAGFlow 要用嵌入模型把文本块转成向量检索时要用重排模型对候选结果做二次排序。这两个模型在离线环境通常不会自动下载需要提前准备好。常见的做法是把模型文件放在一台能联网的机器上下载好按 Hugging Face 的目录结构整体拷进内网然后用 Ollama 或者 Xinference 加载。以 Xinference 为例启动时可以指定本地路径加载模型配置好之后把模型的 Base URL 填到 RAGFlow 的模型供应商里。RAGFlow 官方的模型列表里支持 Xinference填http://xinference服务IP:端口就行。这里提醒一个容易踩的坑RAGFlow 创建知识库时下拉框里的模型必须先在“模型供应商”页面注册成功否则选不到。很多人部署完发现模型列表是空的不是模型文件的问题而是注册步骤没完成。4.2 创建知识库的完整流程和默认模型设置RAGFlow 创建知识库的流程是这样的先配置好模型供应商再点“创建知识库”填写名称、选择嵌入模型和重排模型完成之后上传文档。这里有一个“默认模型”的概念如果你希望后续所有知识库默认使用某个本地模型可以在系统设置里把默认模型指过去这样每次新建知识库就不用反复选择。文档上传之后解析过程是异步的。我建议盯一眼解析日志确认嵌入模型的调用地址是内网 IP 而不是公网地址。有些配置模板里默认填的是外网模型地址离线环境里虽然 tokenizer 问题解决了但模型调用还是失败知识库照样起不来。4.3 其他同类工具的离线部署经验这套思路不光适用于 RAGFlow。如果你在用 AnythingLLM 或者其他 RAG 工具做本地化部署同样会遇到模型加载、嵌入模型配置这些问题。AnythingLLM 的离线部署主要卡在本地模型路径配置上处理方式和 RAGFlow 类似都是提前把模型文件下载好然后通过环境变量或者配置页面指定本地路径。区别在于AnythingLLM 默认对 tiktoken 的依赖没有 RAGFlow 那么深它的文本切片逻辑有自己的实现。但不管什么工具离线部署的核心思路是一致的把所有需要联网获取的组件在能联网的环境里准备好以文件形式放入内网再告诉软件“去哪读本地文件”。4.4 用 Helm 部署 RAGFlow 时的等效做法如果你用的是 Kubernetes 环境通过 Helm 部署 RAGFlow处理方式原理相同只是“挂载卷”变成了 PVC。具体来说先把 tiktoken 缓存文件放到共享存储里然后在 Helm values 里配置环境变量TIKTOKEN_CACHE_DIR和对应的 volumeMounts。如果临时没有共享存储也可以用 initContainer 在容器启动前把文件拷进去本质上和 docker 的挂载是一回事。另外一个在 Helm 环境里需要注意的点是tiktoken 缓存文件是二进制文件不适合放到 ConfigMap 里。ConfigMap 是用来存放配置文本的二进制文件要塞进去很容易出编码问题。正确做法是 PVC 挂载或者把文件打包进自定义镜像。5. 高频报错与排查经验5.1 tiktoken 相关报错速查表把我在部署过程中遇到过的几个典型报错以及对应的处理方式整理成了一张表方便你排查时直接对照报错信息原因解决办法Ran out of entries in remote openai/encode static files词表文件未下载或缓存不完整重新生成缓存目录并确保挂载路径正确Connection error, and we cannot find the requested files in the local cache网络不通本地也没有缓存按第3章步骤预置缓存文件Permission denied访问/opt/tiktoken时容器内用户无缓存文件读权限宿主机上执行chmod -R ar单测通过但知识库解析仍失败tiktoken之外的问题比如嵌入模型地址不可达检查模型供应商配置、模型进程状态容器重建后问题复现用了docker cp临时缓存没有持久化挂载改用 docker-compose volumes 挂载5.2 RAGFlow 启动成功后一直报连接不上 Redis这是另一个我在离线部署中经常被问到的问题。现象是 RAGFlow 的界面能打开但服务日志里不断报 Redis 连接失败。排查顺序很重要别一上来就改配置。第一步确认 Redis 容器是不是健康docker ps | grep redis docker logs redis容器名 --tail 50第二步进入 ragflow-server 容器测试能不能连上 Redis 服务名docker exec -it ragflow-server redis-cli -h redis ping如果能 PONG说明容器网络 OK问题大概率出在.env里的密码或端口配置上。RAGFlow 的.env文件里有REDIS_HOST、REDIS_PORT、REDIS_PASSWORD等字段离线部署时如果 Redis 密码没设置而.env里却配了密码就会出现反复重试连接的情况。把密码字段清空或者改成与 Redis 实际配置一致即可。5.3 创建知识库时模型列表为空这个问题的原因十有八九是模型没有注册成功。RAGFlow 里的模型不是“上传文件”就有了必须先在模型供应商页面里把本地嵌入模型的 API 地址和模型名称配好测试连通成功后才能在创建知识库时选到。还有一种情况是模型注册了但状态显示不可用这时候要看模型服务的日志。比如 Xinference 加载模型失败多半是模型文件路径不对或者显存不足。先把模型服务调通再回到 RAGFlow 界面刷新重试不要反着来。5.4 Windows 部署场景的路径注意点如果你是在 Windows 上用 Docker Desktop 跑 RAGFlow挂载路径的写法要特别注意。TIKTOKEN_CACHE_DIR是容器内路径保持 Linux 风格/opt/tiktoken宿主机挂载路径写成 Windows 格式比如D:\ragflow\tiktoken-cache:/opt/tiktoken。权限问题上Windows 挂载到 Linux 容器偶尔会带上奇怪的权限位遇到 Permission denied 时在容器里执行chmod -R ar /opt/tiktoken也能救急。还有一个 Windows 特有的坑Docker Desktop 的文件共享设置里默认只共享了部分盘符。如果你的缓存文件放在 D 盘但 Docker Desktop 没有把 D 盘加入共享目录挂载就会失败。遇到挂载不生效先去 Docker Desktop 的 Settings - Resources - File Sharing 里确认盘符已勾选。5.5 部署预检清单把离线问题在开机前解决踩过几次坑之后我给自己整理了一份 RAGFlow 离线部署预检清单每次上新环境都按这个过一遍能省掉大半烦恼tiktoken 缓存目录是否就绪权限是否为 ar。嵌入模型和重排模型的本地路径是否就位Xinference 或 Ollama 能否正常启动。.env文件中的 Redis、MySQL 配置是否与依赖容器一致。所有需要的内网 IP 和端口是否在防火墙上放通。如果是 K8s 环境PVC 是否创建成功initContainer 是否执行完成。这份清单不复杂但能解决的问题很实际。离线部署最怕的不是某一个技术点有多难而是环境默认联网、实际又不联网这种假设错位。预检清单的价值就是把所有“需要联网”的假设提前标出来逐个替换成本地方案。我个人的感觉是tiktoken 这个坑看似小但它暴露的是离线部署的一个通用规律部署前先盘一遍所有需要运行时下载的文件把它们变成部署资产的一部分。现在我在公司内部搭了一套离线部署制品库tiktoken 缓存、模型文件、离线 Docker 镜像全放一起新环境部署基本半小时搞定。这个小习惯算是这个坑给我留下的最大收获。