简介:本文介绍轻量级开源代码模型私有化部署的完整流程,涵盖显存规划、权重校验、推理服务启动、API连通与性能压测,并给出长上下文配置、输出漂移排查与运维要点。读者可据此搭建稳定可验收的推理服务。
在企业内网或私有云中运行代码模型,通常有三个要求:代码不出域、响应足够快、服务能长期稳定运行。本文以单机单卡或单机多卡推理为主线,说明从资源估算到上线验收的每一步。命令和参数以 vLLM 为例,它是常见的开源推理框架,提供 OpenAI 兼容接口。其他框架的思路相同,但参数名需要按对应文档调整。
文中的性能数字只是参考。实际表现取决于模型结构、GPU 型号、量化方式和并发数,应以你自己的压测结果为准。
显存主要由两部分占用:模型权重和 KV Cache。KV Cache 随上下文长度和并发数增长。在长上下文场景中,它往往比权重更占空间。
每个 token 的 KV Cache 字节数可按下式估算:
每 token KV Cache(字节)= 2 × 层数 × KV 头数 × 头维度 × 每元素字节数
以 bf16 为例,每元素 2 字节。假设模型为 32 层、8 个 KV 头、头维度 128,则每个 token 约占 128 KB。
下表按上述结构估算,具体数值以模型配置文件中的层数和头数为准。
| 模型规模 | 精度 | 权重占用(约) | 上下文长度 | 并发数 | 建议单卡显存 |
|---|---|---|---|---|---|
| 7B | bf16 | 14 GB | 8K | 4 | 24 GB |
| 7B | bf16 | 14 GB | 32K | 1 | 24 GB |
| 7B | bf16 | 14 GB | 32K | 8 | 48 GB 及以上 |
30B 以上的模型通常权重就超过单卡显存,需要多卡张量并行。文中提到的 40 GB 只是某一种配置下的示例,不是通用门槛。选型时应按模型、精度、上下文和并发分别计算。留出约 10% 的显存余量,用于激活值和框架自身开销。
先确认驱动和 CUDA 版本可用:
nvidia-smi
在独立的虚拟环境中安装推理框架,版本号填写你在测试环境中验证过的版本:
python3 -m venv /opt/llm-infer/venvsource /opt/llm-infer/venv/bin/activatepip install "vllm==<经过测试的版本号>"pip freeze > /opt/llm-infer/requirements.lock
确认 PyTorch 能识别 GPU:
python -c "import torch; print(torch.__version__, torch.version.cuda, torch.cuda.is_available())"
最后一项应为 True。版本锁定文件应随部署包一起保存,方便以后重现环境。
将权重放到固定目录,并核对发布方提供的校验文件:
mkdir -p /data/models/<模型目录>cd /data/models/<模型目录>sha256sum -c SHA256SUMS
如果发布方没有提供 SHA256SUMS,下载时自行计算哈希并记录,之后每次重启服务前都重新比对。
设置权限,只允许服务用户读取:
chown -R llm:llm /data/models/<模型目录>chmod -R u=rX,g=rX,o= /data/models/<模型目录>
使用专用的 llm 用户运行服务,不要用 root。这样即使服务被攻破,影响范围也较小。
vllm serve /data/models/<模型目录> \--served-model-name code-model \--dtype bfloat16 \--max-model-len 32768 \--gpu-memory-utilization 0.90 \--max-num-seqs 8 \--tensor-parallel-size 1 \--host 127.0.0.1 \--port 8000 \--api-key "${API_KEY}"
各参数的含义如下:
--max-model-len:服务允许的最大 token 数,包括输入和输出。超过此长度的请求会被拒绝并返回错误,框架不会自动截断。--gpu-memory-utilization:框架可使用的显存比例。设为 0.90 可留出余量。--max-num-seqs:同时处理的最大序列数,直接决定 KV Cache 的占用量。--tensor-parallel-size:多卡时设为 GPU 数量。--host:只绑定内网地址。关于生成参数,需要明确两点。第一,length_penalty 只在束搜索(beam search)中影响候选排序,它不会缩短输入上下文,也不能替代 max-model-len 的设计。第二,输入超长时,应在网关或业务侧制定明确的截断策略,例如保留题面首段和最近的若干轮对话,并记录每次截断事件。不要依赖生成参数处理超长输入。
评测时应固定 temperature 和 top_p,并把取值写入测试报告。可以从 temperature=0.2、top_p=0.95 开始调整。
将启动命令写入 /opt/llm-infer/run.sh,再用 systemd 托管:
[Unit]Description=LLM inference serviceAfter=network-online.target[Service]User=llmEnvironmentFile=/etc/llm-infer/envExecStart=/opt/llm-infer/run.shRestart=on-failureRestartSec=5[Install]WantedBy=multi-user.target
/etc/llm-infer/env 中保存 API_KEY,文件权限设为 600。密钥不要写进代码、脚本正文或日志。
curl http://127.0.0.1:8000/v1/chat/completions \-H "Content-Type: application/json" \-H "Authorization: Bearer ${API_KEY}" \-d '{"model": "code-model","messages": [{"role": "user", "content": "用一句话说明二分查找的时间复杂度。"}],"max_tokens": 64,"temperature": 0}'
返回结果中需要关注以下字段:
choices[0].message.content:模型输出的文本。usage.prompt_tokens 和 usage.completion_tokens:输入和输出的 token 数。choices[0].finish_reason:为 stop 表示正常结束,为 length 表示达到 max_tokens 被截断。性能验收:用固定的请求集压测。输入长度分别取 1K、8K、32K,输出长度固定为 256 token。记录以下指标:
测试报告必须写明模型版本、GPU 型号和数量、精度、量化方式、框架版本、并发数,以及输入输出长度。验收阈值由团队根据业务确定。例如,在 8K 输入、4 并发下,TTFT 的 P95 不超过 2 秒,错误率低于 0.5%。这些只是示例。
代码能力验证:准备独立的多语言测试集,覆盖 Python、Java、C++ 等语言。应说明测试题与模型训练数据的关系,无法确认时需注明。评估两个指标:
另外统计“臆造条件”的比例。只要输出假设了题面中没有给出的约束、输入格式或函数,就记为一次臆造。
长上下文稳定性:构造接近 max_model_len 的输入,并为输出预留空间。检查以下内容:请求是否成功,显存峰值是否超过 90%,以及题面末尾的约束是否被正确使用。可以在长文本中间埋入一条具体指令,检验回答是否引用了它。
--max-num-seqs 或 --max-model-len,也可以增加卡数。启动报错时,先用 nvidia-smi 检查是否有其他进程占用显存。--max-num-seqs 是否过小,导致 GPU 空闲。在启动日志中确认 attention 后端是否为 FlashAttention 等高性能实现。检查网关是否有缓冲或限流,检查分词和预处理是否占用过多 CPU。部署轻量级代码大模型,关键在于三件事:按实际的上下文长度和并发数估算显存,把推理参数与截断策略设计清楚,并用可复现的压测和多语言评测确认服务是否达标。文中的数字和阈值都需要在自己的环境中重新验证。完成上线后,持续监控和定期评测,才能让服务长期稳定地支撑代码补全、算法评测和自动化测试等场景。