先看现象。系统盘只剩 8GB,把 HF_HOME 设成 /data/hf 后重新下载 Qwen2.5-7B,df 显示系统盘又少了 14GB,~/.cache/huggingface 里出现了完整权重,env 里确实有 HF_HOME=/data/hf。

排查方向其实有限,先把可能性排一排。下载动作发生在设置环境变量之前,缓存已经写进默认路径。还有一种是systemd 或 supervisor 启动时没有继承登录 shell 的环境变量。

少数情况下是transformers 版本较老,只认 TRANSFORMERS_CACHE。

不容易想到的是,容器里挂载了 HOME 但没挂 HF_HOME 指向的目录。

动手时先看进程实际拿到的环境变量

tr '\0' '\n' < /proc/$(pgrep -f api_server | head -1)/environ | grep -i -E 'HF_|HUGGING'

接着确认缓存实际落在哪

du -sh ~/.cache/huggingface /data/hf 2>/dev/null

随后启动时显式传入而不是依赖继承

HF_HOME=/data/hf python -m vllm.entrypoints.openai.api_server --model /data/models/Qwen2.5-7B-Instruct

老版本补上兼容变量

export TRANSFORMERS_CACHE=/data/hf/hub; python -c "import os;print(os.environ['TRANSFORMERS_CACHE'])"

改完先别撤,确认这几项。下载过程中系统盘空间不再减少,权重完整落在数据盘,重启服务后能直接从缓存加载不重下。

这里还有个坑。环境变量要在进程启动前就位,写进 shell 的 export 对守护进程无效,最稳妥的是在启动命令里显式带上。同一份配置在测试环境跑通,不代表线上没事,两边的默认值经常不一样。

作者 9823189