离线环境装 vLLM 报 tiktoken 编码文件下载失败

内网机器无外网，pip 离线装好 vLLM 0.6.3 后启动报 tiktoken_ext.openai_public 拉取 cl100k_base 失败，堆栈里是 ConnectionError: HTTPSConnectionPool，模型权重已经提前拷进本地目录，服务仍然卡在启动阶段。

一开始怀疑是「编码文件只拷到本机，容器里没有挂载」，查了一圈，方向不对。

真正麻烦的地方在于，几个原因的现象几乎一样。tiktoken 首次使用会联网下载编码文件，离线环境必然失败。也可能是TIKTOKEN_CACHE_DIR 没设，缓存路径在用户家目录且为空。

还有一种情况，启动用户与预置文件的属主不同，读取被拒后回退到下载。

动手时先确认失败点是不是编码下载

python -c "import tiktoken;print(tiktoken.get_encoding('cl100k_base'))" 2>&1 | tail -3

接着在有网机器上把编码文件落到指定目录

TIKTOKEN_CACHE_DIR=/opt/tiktoken python -c "import tiktoken;tiktoken.get_encoding('cl100k_base');print('cached')"

然后把目录拷到离线机并设置环境变量

export TIKTOKEN_CACHE_DIR=/opt/tiktoken; python -c "import tiktoken;print(len(tiktoken.get_encoding('cl100k_base').encode('离线测试')))"

剩下的就是容器里把缓存目录挂载进去再启动

docker run -v /opt/tiktoken:/opt/tiktoken -e TIKTOKEN_CACHE_DIR=/opt/tiktoken vllm:0.6.3 python -c "import tiktoken;print('ok')"

恢复的判定其实很直接。离线机上取编码不再联网，启动日志里没有下载请求，分词结果与联网环境逐 token 一致。

容易忽略的是，离线部署要连小文件一起打包，权重拷全了不代表能跑，凡是首次运行会联网的库都要在构建阶段预热一遍。监控比日志更早给出信号，事后回看经常能提前半小时发现异常。