解决智能体等部署cl100k_base.tiktoken报错问题

【离线部署踩坑指南】彻底解决大模型应用 tiktoken 首次运行联网下载超时问题 (Connection timed out)

📌 背景与问题现象

在企业级内网或无外网环境（完全离线环境）下部署大模型应用（如 RAGFlow、LangChain 项目、本地知识库等）时，我们经常会遇到系统启动失败或在文本处理阶段卡死的情况。

查看日志，通常会看到类似下面这样的长串报错信息：

text 复制代码

urllib3.exceptions.ConnectTimeoutError: (<HTTPSConnection(host='openaipublic.blob.core.windows.net', port=443) at 0x75c688869940>, 'Connection to openaipublic.blob.core.windows.net timed out. (connect timeout=None)')

requests.exceptions.ConnectTimeout: HTTPSConnectionPool(host='openaipublic.blob.core.windows.net', port=443): Max retries exceeded with url: /encodings/cl100k_base.tiktoken

🔍 为什么会报错？（核心原因）

这个报错是离线部署中最典型的**"断网后遗症"**。

报错的罪魁祸首是 Python 中广泛使用的分词库：tiktoken（OpenAI 官方的分词器）。

当代码中执行到类似 encoder = tiktoken.get_encoding("cl100k_base") 这一行时，如果本地没有缓存，tiktoken 库在第一次运行时会强制尝试通过网络去下载对应的分词编码文件。

该文件托管在微软云上（openaipublic.blob.core.windows.net）。因为你的服务器位于纯离线环境，无法访问外网，下载请求被一直挂起，最终导致连接超时（Timeout）并引发服务崩溃。

🛠️ 解决方案：手动完成"离线缓存注入"

既然程序想联网下载，我们的解决思路就是：找台有网的电脑把文件下载好，手动塞进服务器，并告诉程序直接去本地读。

具体操作分为以下两步：

第一步：外网下载缺失的词表文件

找一台能够正常访问外网的电脑，下载这个缺失的 .tiktoken 文件。

对于绝大多数大模型应用（使用 cl100k_base 编码），请下载以下文件：

下载地址 ：https://openaipublic.blob.core.windows.net/encodings/cl100k_base.tiktoken

(提示：如果浏览器直接点击打开了乱码页面，请右键选择"另存为"，或者使用迅雷、wget 等下载工具)

第二步：将文件注入离线服务器

将下载好的 cl100k_base.tiktoken 文件上传到你的 Linux 离线服务器。

⚠️ 关键知识点（踩坑高发区）：
tiktoken 在本地查找缓存时，并不是 按照原始文件名 cl100k_base.tiktoken 去找的，而是寻找该文件内容的 SHA1 哈希值 。对于 cl100k_base.tiktoken，它固定的哈希名是 9b5ad71b2ce5302211f9c61530b329a4922fc6a4。

针对不同的部署方式，这里提供两种解决方案：

方案 A：Docker Compose 部署环境（最推荐，永久生效）

如果你的项目是通过 Docker 运行的（例如 RAGFlow 等开源项目），最优雅的做法是通过挂载和环境变量来实现纯离线化：

1. 配置环境变量

在你的 .env 文件或 docker-compose.yml 的 environment 节点中，新增一行，指定本地缓存目录：

bash 复制代码

# 告诉 tiktoken 去这个目录下找缓存
TIKTOKEN_CACHE_DIR=/app/tiktoken_cache/

(注：/app/tiktoken_cache/ 是容器内的虚拟路径，你可以根据实际情况自定义)

2. 配置路径挂载 (Volumes)

打开 docker-compose.yml，在对应服务（如 API 服务、Worker 服务）的 volumes 挂载清单中，把下载好的文件映射进去，并强制重命名为哈希值：

yaml 复制代码

services:
  your-ai-service:
    ...
    volumes:
      # 格式为：宿主机文件路径:容器内文件路径
      # 注意：冒号后面的文件名必须是这串哈希值！
      - ./cl100k_base.tiktoken:/app/tiktoken_cache/9b5ad71b2ce5302211f9c61530b329a4922fc6a4

修改完成后，重启容器：docker compose up -d 即可彻底解决。

方案 B：原生 Python 环境或临时修复

如果你是直接在宿主机跑 Python 脚本，或者想先进容器里临时修复一下，可以使用以下命令：

1. 声明环境变量

bash 复制代码

export TIKTOKEN_CACHE_DIR=/tmp/tiktoken_cache

2. 创建目录并复制文件 (注意重命名)

bash 复制代码

mkdir -p $TIKTOKEN_CACHE_DIR

# 将你上传的词表文件，复制到缓存目录，并重命名为哈希值
cp /你的存放路径/cl100k_base.tiktoken $TIKTOKEN_CACHE_DIR/9b5ad71b2ce5302211f9c61530b329a4922fc6a4

操作完成后，再次启动你的 Python 服务或 AI 应用，你会发现系统直接秒启动，不再出现令人头疼的 Timeout 报错了。

💡 总结与建议

在各种开源大模型框架（如 LangChain、RAGFlow、Dify 等）的落地中，tiktoken 的离线下载问题堪称"新手第一坑"。

强烈建议在进行内网私有化部署 架构设计时，统一将此类依赖外部网络的缓存文件提取出来，通过环境变量 + 文件挂载的方式进行管理。这才是真正的"纯离线化"规范部署，不仅方便后期运维，也能有效避免容器重启后缓存丢失的问题。

如果这篇文章帮助你解决了问题，欢迎点赞收藏！在离线部署大模型过程中遇到其他坑，也欢迎在评论区交流讨论。