基于 llama.cpp 的本地大模型部署教程

方式一：命令行交互模式

cd ~/llama.cpp/src/build/bin
./llama-cli -m ~/llama.cpp/models/qwen2.5-3b-instruct-q4_k_m.gguf \
  -c 4096 \
  --no-display-prompt

参数说明：

• -m 模型路径
• -c 上下文长度（默认 512，建议 4096）
• -ngl GPU 层数（纯 CPU 可不加）

方式二：启动 API 服务

cd ~/llama.cpp/src/build/bin
./llama-server \
  -m ~/llama.cpp/models/qwen2.5-3b-instruct-q4_k_m.gguf \
  --host 0.0.0.0 \
  --port 8080 \
  -c 4096

服务启动后访问：http://localhost:8080

五、API 调用方法

API 信息

端点列表

调用示例

curl

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{ "model": "qwen2.5-3b", "messages": [ {"role": "system", "content": "你是一个有帮助的助手。"}, {"role": "user", "content": "你好，介绍一下你自己"} ], "temperature": 0.7, "max_tokens": 512 }'

Python（OpenAI SDK）

from openai import OpenAI
client = OpenAI(
    base_url="http://localhost:8080/v1",
    api_key="not-needed"
)
response = client.chat.completions.create(
    model="qwen2.5-3b",
    messages=[{"role":"system","content":"你是一个有帮助的助手。"},{"role":"user","content":"你好"}],
    temperature=0.7,
    max_tokens=512
)
print(response.choices[0].message.content)

Node.js

const response = await fetch('http://localhost:8080/v1/chat/completions', {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({model:'qwen2.5-3b',messages:[{role:'user',content:'你好'}]})
});
const data = await response.json();
console.log(data.choices[0].message.content);

六、常用参数说明

服务端参数（llama-server）

API 请求参数

七、常见问题

Q1: 报错 'CUDA out of memory'

减少 -ngl 数值，让部分层用 CPU 计算：

./llama-server -m model.gguf -ngl 20 # 只放 20 层到 GPU

Q2: 中文乱码

PowerShell 执行：

chcp 65001

Q3: 如何后台运行服务？

nohup ./llama-server -m model.gguf --host 0.0.0.0 --port 8080 > server.log 2>&1 &

Q4: 如何设置 API Key 认证？

./llama-server -m model.gguf --api-key "your-secret-key"

调用时需要带上：

curl -H "Authorization: Bearer your-secret-key"...

Q5: 从其他设备访问

1. 查看 WSL IP：hostname -I
2. 使用该 IP 访问，如 http://172.x.x.x:8080

八、推荐模型

下载地址： https://hf-mirror.com（国内镜像）

九、文件结构

~/llama.cpp/
├── src/          # llama.cpp 源码
│   └── build/
│       └── bin/
│           ├── llama-cli   # 命令行工具
│           └── llama-server# API 服务
└── models/       # 模型存放目录
    └── qwen2.5-3b-instruct-q4_k_m.gguf

十、快速启动脚本

创建 start-server.sh：

#!/bin/bash
cd ~/llama.cpp/src/build/bin
./llama-server \
  -m ~/llama.cpp/models/qwen2.5-3b-instruct-q4_k_m.gguf \
  --host 0.0.0.0 \
  --port 8080 \
  -c 4096 \
  -np 4

赋予执行权限：

chmod +x start-server.sh
./start-server.sh