大模型部署中环境变量配置失败排查过程
在大模型部署实践中，环境变量配置问题是最常见但又容易被忽视的故障点。本文记录一次典型的环境变量配置失败排查过程。
问题现象
在Kubernetes环境中部署大模型服务时，发现容器启动后无法正常加载模型权重文件，日志显示FileNotFoundError: [Errno 2] No such file or directory。初步怀疑是模型路径配置错误，但经过多次检查确认路径无误。
排查过程
第一步：验证环境变量设置
# 检查容器内环境变量
kubectl exec -it <pod-name> -- env | grep MODEL
# 输出：MODEL_PATH=/models/llama-7b
第二步：检查变量引用方式
# 错误示例
model_path = os.environ['MODEL_PATH'] # 可能被替换为字符串'None'
# 正确做法
model_path = os.environ.get('MODEL_PATH', '/default/path')
if not model_path or model_path == 'None':
raise ValueError('MODEL_PATH is not set properly')
第三步：排查变量传递方式 在helm chart中检查values.yaml配置：
# values.yaml
env:
- name: MODEL_PATH
value: /models/llama-7b
同时验证了deployment.yaml中的环境变量注入：
# deployment.yaml
env:
- name: MODEL_PATH
valueFrom:
configMapKeyRef:
name: model-config
key: model-path
根本原因
最终定位到问题出在CI/CD流程中的变量替换逻辑，使用了错误的shell变量替换语法导致环境变量被替换为字符串'None'。修复后通过以下方式验证：
# 重新部署并验证
kubectl rollout restart deployment/<deployment-name>
kubectl get pods -l app=model-service
kubectl logs <pod-name> | grep "Model loaded successfully"
最佳实践建议
- 在代码中添加环境变量有效性校验
- 使用
os.environ.get()替代直接访问 - 部署前在测试环境中验证变量传递
- 建立环境变量配置文档并定期更新
讨论