简介:本文面向开发者和运维人员,按资源规划、模型校验、启动配置、访问验证、故障排查和日常运维的顺序,给出可直接执行的命令与配置模板。读完后,你可以在本机启动一个只监听回环地址的推理服务,用固定方法验证它是否正常,并在出现常见故障时快速定位原因。
本文描述的是在单台工作站或服务器上运行的本地推理服务。服务加载量化后的模型权重,在本机开启一个 HTTP 接口,供对话界面、脚本或本地应用调用。
部署完成后,应满足以下四点:
本地部署不适合多用户对外服务。那类需求需要独立的服务器、负载均衡、鉴权体系和容量冗余,应另行设计。
权重占用的近似计算方法如下:
权重占用(字节)≈ 参数量 × 每个参数的比特数 ÷ 8
以参数量约 270 亿、量化后平均约 3 比特为例:
27 × 10⁹ × 3 ÷ 8 ≈ 10.1 GB
这是权重本身的大小。运行时还需要计算缓存、程序自身的开销,以及未卸载到显存的部分。
KV 缓存保存上下文对应的中间状态,其近似计算方法如下:
KV 缓存(字节)≈ 2 × 层数 × KV 头数 × 每个头的维度 × 上下文长度 × 每个元素的字节数 × 并行槽位数
假设某模型有 60 层、8 个 KV 头、每个头维度 128,使用 FP16(每个元素 2 字节),上下文长度 32768,并行槽位数为 1:
2 × 60 × 8 × 128 × 32768 × 2 × 1 ≈ 8.05 GB
上下文长度或并行槽位数增加时,这部分会按比例增长。把并行槽位数改为 4,同样的上下文需要约 32 GB。因此,应先确定实际需要的上下文长度,再决定槽位数和 KV 缓存量化方式。
KV 缓存量化可以降低显存占用,但可能影响长文本的输出质量。是否采用,应使用同一组提示词做对比测试后确认。
软件环境应满足以下条件:
建议在专用目录下建立版本记录表,每次变更都更新一行:
| 项目 | 示例值 | 记录内容 |
|---|---|---|
| 操作系统 | Ubuntu 22.04 | 发行版与内核版本 |
| GPU 驱动 | 以 nvidia-smi 输出为准 |
驱动版本与支持的 CUDA 版本 |
| 推理程序 | llama.cpp 某发布版本 | 版本号、下载日期、哈希值 |
| 模型文件 | 某模型,3 比特量化 | 名称、量化级别、哈希值、许可证、下载日期 |
推理服务不需要管理员权限。请使用普通用户账户运行。以管理员身份长期运行服务,一旦服务或依赖存在漏洞,影响范围会明显扩大。
sha256sum ~/llm/models/model-q3.gguf
把参数集中写在脚本中,避免每次手动输入,也便于回滚。下面以 llama.cpp 的 llama-server 为例。其他推理程序的参数名称不同,请以所用版本的 --help 输出为准。
建立目录结构:
mkdir -p ~/llm/{bin,models,conf,logs}
启动脚本 ~/llm/conf/start.sh:
#!/usr/bin/env bashset -euo pipefailBASE="$HOME/llm"exec "$BASE/bin/llama-server" \-m "$BASE/models/model-q3.gguf" \--host 127.0.0.1 \--port 8080 \-c 8192 \-np 1 \-ngl 99 \-t 8 \-fa on \--cache-type-k q8_0 \--cache-type-v q8_0 \--log-file "$BASE/logs/server.log"
各参数的含义和取值建议如下:
| 参数 | 含义 | 取值建议 |
|---|---|---|
-m |
模型文件路径 | 指向已校验的文件 |
--host |
监听地址 | 固定为 127.0.0.1,不改为 0.0.0.0 |
--port |
监听端口 | 选择未被占用的端口 |
-c |
上下文长度 | 按实际需求设定,每增加一倍,KV 缓存也约增加一倍 |
-np |
并行槽位数 | 默认设为 1 |
-ngl |
卸载到 GPU 的层数 | 显存充足时设为较大值,超过模型层数时等同于全部卸载 |
-t |
CPU 线程数 | 设为物理核心数,超过物理核心数通常不会更快 |
-fa |
Flash Attention 开关 | 启用 V 缓存量化前需要开启,以所用版本的参数格式为准 |
--cache-type-k / --cache-type-v |
KV 缓存量化类型 | 需要显存时再启用,并做质量对比 |
--log-file |
日志文件路径 | 放在专用目录,便于轮转和脱敏 |
设置脚本权限:
chmod 700 ~/llm/conf/start.sh
~/llm/conf/start.sh
另开一个终端,检查日志中的关键信息:
tail -n 50 ~/llm/logs/server.log
日志中应出现模型加载完成、卸载层数(例如 “offloaded X/Y layers”)和服务监听的信息。如果卸载层数少于预期,说明显存不足,需要调整参数。
ss -ltnp | grep 8080
输出中的地址应为 127.0.0.1:8080。如果显示 0.0.0.0:8080 或 *:8080,应立即停止服务,检查 --host 参数。
确认防火墙没有放行该端口的入站连接。以 ufw 为例:
sudo ufw status
如果确需局域网访问,不要直接暴露推理进程。应在前面加反向代理,配置身份认证、IP 白名单和 TLS 加密。
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8080/health
期望输出为 200。返回的 JSON 中 status 字段应为 ok。模型仍在加载时,接口可能返回 503,应等待后重试。
curl -s http://127.0.0.1:8080/v1/chat/completions \-H "Content-Type: application/json" \-d '{"model": "local","messages": [{"role": "user", "content": "用一句话介绍你自己"}],"max_tokens": 64,"temperature": 0.2}'
判断标准如下:
choices[0].message.content 有非空文本。finish_reason 为 stop。如果为 length,说明 max_tokens 不足,属于正常截断,不是故障。error 字段。耗时的口径分为两项:
测量总耗时可以使用:
curl -s -o /dev/null -w "总耗时: %{time_total} 秒\n" \http://127.0.0.1:8080/v1/chat/completions \-H "Content-Type: application/json" \-d '{"model":"local","messages":[{"role":"user","content":"列出三条学习编程的建议"}],"max_tokens":256}'
首 token 延迟可以在请求中加入 "stream": true,记录第一个数据块到达的时间。
耗时没有统一的合格线,应在本机首次稳定运行后记录基线,并以后续变化相对基线判断。同一组提示词、同一参数下,耗时明显变长,就需要排查。
| 现象 | 常见原因 | 定位方法 | 处置 | |
|---|---|---|---|---|
| 启动后立即退出,日志出现加载失败 | 模型文件损坏或哈希不一致 | sha256sum 与发布页值比对 |
重新下载文件并校验 | |
| 日志出现 out of memory 或 CUDA 分配失败 | 显存不足 | nvidia-smi 查看显存占用 |
减小 -ngl、-c、-np,或启用 KV 缓存量化 |
|
| 启动报 CUDA 相关错误 | 驱动与运行库不匹配 | nvidia-smi 查看驱动版本,核对程序的发布说明 |
更新或回退驱动,或换用与驱动匹配的程序版本 | |
| 提示端口已被占用 | 其他进程占用端口 | `ss -ltnp \ | grep 8080` | 结束冲突进程,或更换 --port |
| 响应明显变慢 | 卸载层数不足、线程数不合理、并发堆积 | 日志中的卸载层数,top 查看 CPU 占用 |
提高 -ngl,将 -t 设为物理核心数,检查是否有并发请求 |
|
| 页面或脚本无法访问 | 监听地址错误,或请求地址不是本机 | ss -ltnp,核对客户端地址 |
确认监听为 127.0.0.1,客户端使用 http://127.0.0.1:端口 |
|
| 输出被截断 | max_tokens 过小,或上下文超限 |
检查 finish_reason 是否为 length |
增大 max_tokens,或提高 -c |
|
| 显存随时间持续增长 | 请求堆积,或缓存未释放 | 每隔数分钟记录 nvidia-smi 输出 |
限制并发,定期重启服务,并记录增长曲线交由后续排查 |
定位问题时,先看日志,再看端口和资源占用,最后看请求内容。每次