Shell / BashAI算法
llama.cpp 本地大模型部署与 API 服务搭建教程
在 Windows WSL2 环境下使用 llama.cpp 部署本地大模型的完整流程。内容包括环境准备（安装编译工具）、源码克隆与编译、GGUF 模型下载、命令行交互模式及 API 服务启动。提供了 curl、Python 和 Node.js 的 API 调用示例，以及常用参数说明和常见问题排查方法。支持 Qwen2.5 系列等主流模型，适合本地化运行大语言模型。
在 Windows WSL2 环境下使用 llama.cpp 部署本地大模型的完整流程。内容包括环境准备（安装编译工具）、源码克隆与编译、GGUF 模型下载、命令行交互模式及 API 服务启动。提供了 curl、Python 和 Node.js 的 API 调用示例，以及常用参数说明和常见问题排查方法。支持 Qwen2.5 系列等主流模型，适合本地化运行大语言模型。
本教程基于实际操作整理，适用于 Windows WSL2 环境
| 显卡 | 推荐模型 | 显存占用 |
|---|---|---|
| GTX 1050 Ti (4GB) | Qwen2.5-3B Q4 | ~2.5GB |
| RTX 4060 (8GB) | Qwen2.5-7B Q4 | ~5GB |
| RTX 4090 (24GB) | Qwen2.5-32B Q4 | ~20GB |
sudo apt update
sudo apt install -y cmake build-essential
mkdir -p ~/llama.cpp
cd ~/llama.cpp
git clone --depth 1 https://github.com/ggerganov/llama.cpp.git src
cd ~/llama.cpp/src
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j$(nproc) llama-cli llama-server
编译完成后，可执行文件在 ~/llama.cpp/src/build/bin/ 目录下。
mkdir -p ~/llama.cpp/models
Qwen2.5-3B（适合 4GB 显存）：
curl -L -o ~/llama.cpp/models/qwen2.5-3b-instruct-q4_k_m.gguf "https://hf-mirror.com/Qwen/Qwen2.5-3B-Instruct-GGUF/resolve/main/qwen2.5-3b-instruct-q4_k_m.gguf"
Qwen2.5-7B（适合 8GB 显存）：
curl -L -o ~/llama.cpp/models/qwen2.5-7b-instruct-q4_k_m.gguf "https://hf-mirror.com/Qwen/Qwen2.5-7B-Instruct-GGUF/resolve/main/qwen2.5-7b-instruct-q4_k_m.gguf"
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 可不加）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
| 项目 | 值 |
|---|---|
| 地址 | http://localhost:8080 |
| API Key | 不需要（或随意填写） |
| 兼容格式 | OpenAI API |
| 端点 | 说明 |
|---|---|
POST /v1/chat/completions | 聊天补全 |
POST /v1/completions | 文本补全 |
GET /health | 健康检查 |
GET / | Web 聊天界面 |
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 }'
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)
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);
| 参数 | 说明 | 示例 |
|---|---|---|
-m | 模型路径 | -m model.gguf |
--host | 监听地址 | --host 0.0.0.0 |
--port | 端口 | --port 8080 |
-c | 上下文长度 | -c 4096 |
-ngl | GPU 层数 | -ngl 99（全部放 GPU） |
-np | 并行请求数 | -np 4 |
--api-key | 设置 API Key | --api-key your-key |
| 参数 | 说明 | 默认值 |
|---|---|---|
temperature | 随机性（0-2） | 0.7 |
max_tokens | 最大生成长度 | 模型上限 |
top_p | 核采样 | 1.0 |
stream | 流式输出 | false |
stop | 停止词 | [] |
减少 -ngl 数值，让部分层用 CPU 计算：
./llama-server -m model.gguf -ngl 20 # 只放 20 层到 GPU
PowerShell 执行：
chcp 65001
nohup ./llama-server -m model.gguf --host 0.0.0.0 --port 8080 > server.log 2>&1 &
./llama-server -m model.gguf --api-key "your-secret-key"
调用时需要带上：
curl -H "Authorization: Bearer your-secret-key"...
hostname -Ihttp://172.x.x.x:8080| 模型 | 大小 | 适合场景 |
|---|---|---|
| Qwen2.5-3B-Instruct Q4 | ~2GB | 轻量对话、低配设备 |
| Qwen2.5-7B-Instruct Q4 | ~4.5GB | 通用对话、代码 |
| Qwen2.5-14B-Instruct Q4 | ~9GB | 复杂推理 |
| DeepSeek-R1-Distill-Qwen-7B Q4 | ~4.5GB | 数学、逻辑推理 |
| Mistral-7B-v0.3 Q5 | ~5GB | 英文、代码 |
下载地址： 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
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
使用加密算法（如AES、TripleDES、Rabbit或RC4）加密和解密文本明文。 在线工具，加密/解密文本在线工具，online
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML 转 Markdown 互为补充。 在线工具，Markdown 转 HTML在线工具，online