跳到主要内容
极客日志极客日志
首页博客AI提示词GitHub精选代理工具
|注册
博客列表

目录

  1. llama.cpp 本地大模型部署教程
  2. 一、环境准备
  3. 1. 硬件要求
  4. 2. 安装编译工具（WSL Ubuntu）
  5. 二、下载和编译 llama.cpp
  6. 1. 克隆源码
  7. 2. 编译
  8. 三、下载模型
  9. 1. 创建模型目录
  10. 2. 下载 GGUF 模型（使用国内镜像加速）
  11. 四、运行模型
  12. 方式一：命令行交互模式
  13. 方式二：启动 API 服务
  14. 五、API 调用方法
  15. API 信息
  16. 端点列表
  17. 调用示例
  18. curl
  19. Python（OpenAI SDK）
  20. Node.js
  21. 六、常用参数说明
  22. 服务端参数（llama-server）
  23. API 请求参数
  24. 七、常见问题
  25. Q1: 报错“CUDA out of memory”
  26. Q2: 中文乱码
  27. Q3: 如何后台运行服务？
  28. Q4: 如何设置 API Key 认证？
  29. Q5: 从其他设备访问
  30. 八、推荐模型
  31. 九、文件结构
  32. 十、快速启动脚本
C++Node.jsAI算法

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

在 Windows WSL2 环境下使用 llama.cpp 部署本地大模型的完整流程。内容包括环境准备（硬件要求、编译工具安装）、源码克隆与编译、GGUF 模型下载、命令行交互及 API 服务启动。提供了 curl、Python 和 Node.js 的 API 调用示例，并列举了常用参数说明、常见问题排查及推荐模型列表。适用于希望本地运行 Qwen 或 Mistral 等大语言模型的开发人员。

孤勇者发布于 2026/4/6更新于 2026/4/131 浏览
llama.cpp 本地大模型部署教程

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

本教程基于实际操作整理，适用于 Windows WSL2 环境

一、环境准备

1. 硬件要求
显卡推荐模型显存占用
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
2. 安装编译工具（WSL Ubuntu）
sudo apt update && sudo apt install -y cmake build-essential

二、下载和编译 llama.cpp

1. 克隆源码
mkdir -p ~/llama.cpp
cd ~/llama.cpp
git clone --depth 1 https://github.com/ggerganov/llama.cpp.git src
2. 编译
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/ 目录下。

三、下载模型

1. 创建模型目录
mkdir -p ~/llama.cpp/models
2. 下载 GGUF 模型（使用国内镜像加速）

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 可不加）
方式二：启动 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 信息
项目值
地址http://localhost:8080
API Key不需要（或随意填写）
兼容格式OpenAI API
端点列表
端点说明
POST /v1/chat/completions聊天补全
POST /v1/completions文本补全
GET /health健康检查
GET /Web 聊天界面
调用示例
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）
参数说明示例
-m模型路径-m model.gguf
--host监听地址--host 0.0.0.0
--port端口--port 8080
-c上下文长度-c 4096
-nglGPU 层数-ngl 99（全部放 GPU）
-np并行请求数-np 4
--api-key设置 API Key--api-key your-key
API 请求参数
参数说明默认值
temperature随机性（0-2）0.7
max_tokens最大生成长度模型上限
top_p核采样1.0
stream流式输出false
stop停止词[]

七、常见问题

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

八、推荐模型

模型大小适合场景
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

版本信息：llama.cpp b7917 + Qwen2.5-3B-Instruct

极客日志微信公众号二维码

微信扫一扫，关注极客日志

微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog

更多推荐文章

查看全部
  • 文心一言 4.5 开源模型技术解析与部署实践
  • Neo4j 与 RDF 数据互操作：neosemantics 插件配置与 JSON-LD 实战
  • 无人机植物病害目标检测数据集（1500 张已标注图片）
  • 三大扩散模型性能对比：Z-Image-Turbo、ComfyUI 与 Stable Diffusion
  • 图文内容社区数据指标体系构建方法与实践
  • C# WebApi 接口测试工具 WebApiTestClient 应用详解
  • AI 调参技巧：贝叶斯优化与 Optuna 实战
  • Jetson Orin NX 部署 Ollama 及 Llama 3.2 模型
  • WebGIS 项目实战经验与技术应用展望
  • Obsidian Copilot 集成本地模型：Ollama 与 LM Studio 配置指南
  • 深入理解 IDE 中 LLM 调用的 Session 机制
  • 基于 Next.js 构建支持 TokenP 钱包登录的 DApp 前端
  • 基于 Docker 部署 Appsmith 并配置内网穿透远程访问
  • 如何免费使用 AI 绘画模型 Nano Banana Pro
  • Stable Diffusion XL 本地环境快速部署与使用指南
  • AI 辅助前端设计工作流：独立完成产品从原型到代码的全流程
  • Linux 环境下 OpenClaw 安装、初始化与 Web UI 配置指南
  • 千笔 AI：辅助学术写作的智能工具
  • B 站 PC 端自动开启字幕用户脚本
  • WebRTC + Java 信令服务器 + Vue 实时视频聊天实现

相关免费在线工具

  • 加密/解密文本

    使用加密算法（如AES、TripleDES、Rabbit或RC4）加密和解密文本明文。 在线工具，加密/解密文本在线工具，online

  • RSA密钥对生成器

    生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online

  • Mermaid 预览与可视化编辑

    基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online

  • Base64 字符串编码/解码

    将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online

  • Base64 文件转换器

    将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online

  • Markdown 转 HTML

    将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML 转 Markdown 互为补充。 在线工具，Markdown 转 HTML在线工具，online