llama.cpp 是一种轻量模型运行环境,支持量化 GGUF 权重及内置服务器。需要明确控制模型文件、CPU 线程和上下文长度时,它是实用的选择。本指南通过 SSH 访问需要认证的 API,并使用您自行选择和验证的模型文件。
目标环境: Ubuntu Server 24.04 LTS、x86-64、SSH 和 sudo 账户。文档审核日期:2026 年 11 月 15 日。命令尚未在 Ubuntu 上完成端到端测试。
开始之前
对于 0.5–1.5B 的小型量化文本模型,可先预留约 2–4 个 vCPU、4 GB 内存和 10 GB 可用磁盘,再进行实测。更大的权重和上下文需要更多资源。您需要兼容的指令微调 GGUF 文件及发布者的校验值和许可证;任意重命名的模型文件不一定兼容。
这些资源数值仅为小规模评估的规划估算,不是性能保证或套餐规格。VPS/VDS 不代表包含 GPU。下单前请检查可用内存、存储和其他资源。
全新 Ubuntu 可使用以下软件包。如果 Docker 已从其他仓库安装,请保留并先检查兼容性,不要混用 Docker CE 和 docker.io 软件包。使用 Compose v2;缺少软件包时,请检查是否启用 Ubuntu Universe。
sudo apt update
sudo apt install -y docker.io docker-compose-v2 curl openssl
sudo systemctl enable --now docker
sudo docker compose version
所有示例仅将端口发布到服务器的 127.0.0.1。请从本机通过 SSH 隧道访问,无需域名。不要将这些端口开放到互联网。容器内部监听 0.0.0.0 不会改变宿主机端口仅绑定回环地址的事实。
以下项目均为全新安装。不要对现有部署重新执行密钥生成步骤。
1. 准备经过验证的模型文件
创建项目。在本机按示例将所选 GGUF 复制到 VPS,并替换每个占位值。启动前,在 VPS 上将 sha256sum models/model.gguf 与可信发布者提供的值核对。加载 GGUF 不需要执行远程模型仓库中的代码。
umask 077
mkdir -p ~/ai-llama/models
cd ~/ai-llama
openssl rand -hex 32 > api-key.txt
scp /PATH/TO/SELECTED.gguf YOUR_USER@YOUR_SERVER_IP:~/ai-llama/models/model.gguf
2. 配置资源受限的 CPU 服务器
保存 compose.yaml。模型和 API 密钥文件在容器内只读。--alias 提供稳定的客户端模型名称;两个线程和一个并行槽位是保守评估配置,并非适合所有套餐的调优建议。
services:
llama:
image: ghcr.io/ggml-org/llama.cpp:server
restart: unless-stopped
ports:
- "127.0.0.1:8080:8080"
volumes:
- ./models:/models:ro
- ./api-key.txt:/run/llama-api-key:ro
command: ["-m", "/models/model.gguf", "--alias", "local-gguf", "--host", "0.0.0.0", "--port", "8080", "--ctx-size", "2048", "--threads", "2", "--parallel", "1", "--api-key-file", "/run/llama-api-key"]
3. 验证加载、认证与响应
核对校验值后在 VPS 上运行。/health 可以公开,并在加载期间返回 503;该端点不是认证测试。不带密钥请求 /v1/models 应返回 401。最初请使用简短提示词;如果不支持模型的聊天模板,请查看日志。
sha256sum models/model.gguf
sudo docker compose up -d
curl -i http://127.0.0.1:8080/health
curl -s -o /dev/null -w '%{http_code}
' http://127.0.0.1:8080/v1/models
LLAMA_KEY=$(cat api-key.txt)
curl --fail-with-body --max-time 180 http://127.0.0.1:8080/v1/chat/completions -H "Authorization: Bearer $LLAMA_KEY" -H 'Content-Type: application/json' -d '{"model":"local-gguf","messages":[{"role":"user","content":"Explain SSH in one sentence."}],"max_tokens":80}'
unset LLAMA_KEY
4. 连接并保持可重复部署
从本机建立隧道,使用 http://127.0.0.1:8080/v1、相同的 API 密钥和模型别名。记录模型来源、校验值、量化方式、许可证及容器摘要。模型即使能放入内存,共享 CPU 上仍可能很慢;增加并发前请比较实测延迟。保留准确的权重文件或可验证的重新获取方法,并备份密钥和配置。
ssh -N -L 127.0.0.1:8080:127.0.0.1:8080 YOUR_USER@YOUR_SERVER_IP
更新与恢复
升级前停止应用以制作一致性备份,将数据和密钥保留在 VPS 之外,并在独立实例测试恢复。示例中的浮动镜像标签用于初期评估;长期使用前请固定已审核的版本或摘要。可通过 sudo docker image inspect IMAGE_NAME --format '{{json .RepoDigests}}' 记录当前摘要。不要在未检查兼容性时无人值守升级,也不要用 down -v 删除持久卷。
启动失败时,请检查 sudo docker compose ps、近期日志、剩余磁盘和内存。不要分享包含密钥、提示词或个人数据的日志。目录权限出错时,应核对预期 UID/GID 与所有权,不要授予 777。共享访问前请配置 HTTPS、认证和请求限制。