跳到主要内容
极客日志极客日志面向AI+效率的开发者社区
首页博客GitHub 精选镜像工具UI配色美学隐私政策关于联系
搜索内容 / 工具 / 仓库 / 镜像...⌘K搜索
注册
博客列表
C++AI算法

WSL2 Ubuntu 部署 llama.cpp 指南

在 WSL2 Ubuntu 环境下编译部署 llama.cpp 的方法,涵盖 CPU 与 GPU(CUDA)后端配置步骤。内容包括克隆仓库、安装依赖、环境变量设置及模型下载流程,支持从 Hugging Face 或 ModelScope 获取 GGUF 格式模型,旨在帮助用户在本地高效运行大语言模型。

星云发布于 2026/4/5更新于 2026/5/2341 浏览
WSL2 Ubuntu 部署 llama.cpp 指南

WSL2 Ubuntu 部署 llama.cpp

llama.cpp 是一个完全由 C 与 C++ 编写的轻量级推理框架,支持在 CPU 或 GPU 上高效运行 Meta 的 LLaMA 等大语言模型(LLM),设计上尽可能减少外部依赖,能够轻松在多种后端与平台上运行。

安装 llama.cpp

采用本地编译的方法在设备上安装 llama.cpp。

克隆 llama.cpp 仓库

在 WSL 中打开终端:

git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp
编译项目

编译项目前,先安装所需依赖项:

sudo apt update
sudo apt install -y build-essential cmake git
# llama.cpp 的某些功能依赖 libcurl,如 llama-download 的自动下载模型
sudo apt install -y libcurl4-openssl-dev
# 如果要使用 python 接口,还需要
sudo apt install -y python3 python3-pip
pip3 install numpy
CPU Backend

默认使用 CPU 版本编译:

cmake -B build
cmake --build build --config Release
# cmake --build build --config Release -j 8
# -j 8 可加速编译过程,视你的 CPU 核心数而定
GPU Backend

如果你想使用 GPU(推荐支持 CUDA 的 NVIDIA 显卡),需要先安装 CUDA Toolkit。由于 WSL2 默认不会自动识别 Windows 主机上的 CUDA Toolkit,因此需要特殊处理。

  • 驱动版本 ≥ 465
  • 从 NVIDIA 官网 下载并安装最新版 CUDA Toolkit(但只需要驱动)。

重新编译带 CUDA 的 llama.cpp。

设置 CUDA 环境变量:

export PATH=/usr/local/cuda/bin:$PATH
export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH
export CUDACXX=/usr/local/cuda/bin/nvcc
source ~/.bashrc

安装 CUDA Toolkit 的 stub(轻量化开发头文件)。虽然你已经有了 CUDA runtime(用于运行模型),但 llama.cpp 编译阶段还需要 C++ 头文件和 nvcc 编译器 —— 你需要在 WSL2 里补装开发包:

sudo apt update
# 这里直接安装了 CUDA12 的整个工具包
 apt install -y cuda

sudo
# 验证 nvcc --version

在子系统中验证 GPU 是否可用。在 WSL2 中运行:

nvidia-smi

如果成功看到你的 GPU 显示状态(如 RTX 3060、显存使用情况等),说明 CUDA 运行库已经桥接成功,可以继续。

在 Windows 主机上确认:1)安装了支持 WSL 的 NVIDIA 驱动(必须是 DCH 驱动);2)安装好 WSL CUDA Toolkit(可以只装驱动和运行库,不需要开发工具)。

如何安装 WSL CUDA Toolkit:

i. 下载 NVIDIA GeForce Game Ready(根据自己的 GPU 版本进行选择),下载网址:https://www.nvidia.com/Download/index.aspx ii. 移走原先的 GPG key

sudo apt-key del 7fa2af80

iii. 下载 CUDA Toolkit

wget https://developer.download.nvidia.com/compute/cuda/repos/wsl-ubuntu/x86_64/cuda-wsl-ubuntu.pin
sudo mv cuda-wsl-ubuntu.pin /etc/apt/preferences.d/cuda-repository-pin-600
wget https://developer.download.nvidia.com/compute/cuda/12.9.1/local_installers/cuda-repo-wsl-ubuntu-12-9-local_12.9.1-1_amd64.deb
sudo dpkg -i cuda-repo-wsl-ubuntu-12-9-local_12.9.1-1_amd64.deb
sudo cp /var/cuda-repo-wsl-ubuntu-12-9-local/cuda-*-keyring.gpg /usr/share/keyrings/
sudo apt-get update
sudo apt-get -y install cuda-toolkit-12-9

如果你用 CPU 生成过编译文件,执行新的 make 指令时可能会报错。先使用 rm -rf build 把之前的清空:

rm -rf build
cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release -j 8
# -j 8 可加速编译过程,视你的 CPU 核心数而定
# 其实重启电脑也可以达到一样的效果

从 Hugging Face 下载模型

选择合适的模型

进入网站查看 llama.cpp 支持的所有模型列表。

我们推荐首先尝试较为主流的 LLaMA 2、LLaMA 3、Mistral、Qwen、ChatGLM 等系列模型。常见的 LLM 模型大小有 1B、7B、13B 等,一般来说,模型规模越大,生成的质量越好,但是运行时内存(推理时所需内存)也会随之增长。为避免频繁出现 OOM (Out of the memory) 的现象,我们推荐从较小的 LLM 开始调试。

注册 Hugging Face 账号后,可以添加自己的硬件设备信息,如下:

用户主页

之后 Hugging Face 会对你的硬件能力做出评估:

用户硬件性能评估

此时再选择相应的模型,右侧 Hardware Compatibility 面板用于帮助用户根据自己设备的性能,选择合适的量化模型文件(GGUF 格式)。

以第一行为例,Q4_K_M 是模型的量化精度,数字越大精度越高,越接近原始模型,但也更占内存;2.5GB 下载后模型文件所占空间,也是运行所需的最低内存估算:

模型量化精度推荐

下载方法
1. 使用 Hugging Face 下载

这里使用手动从 Hugging Face 官网下载的方法,打开你想下载的模型主页,如: https://huggingface.co/Qwen/Qwen3-0.6B-GGUF

然后在 Files and versions 中找到对应的 .gguf 文件下载并保存到你希望的目录即可。

2. 使用 ModelScope 下载

ModelScope 是阿里云提供的 AI 模型平台,也支持中文大模型。如果你无法访问 Hugging Face 或下载速度慢,推荐使用 ModelScope 下载。

首先安装 ModelScope 所需库(推荐使用虚拟环境):

pip install modelscope

然后运行以下 Python 脚本:

from modelscope import snapshot_download
model_dir = snapshot_download(
    'Qwen/Qwen3-0.6B-GGUF', # 替换为你想要下载的模型名称,推荐下载 .gguf 格式的量化模型,适用于 llama.cpp
    cache_dir='./models/qwen-0.6b-gguf', # 设置本地保存路径
    revision='master' # 可指定具体版本
)
print(f"Model saved at {model_dir}")

最后耐心等待即可。

目录

  1. WSL2 Ubuntu 部署 llama.cpp
  2. 安装 llama.cpp
  3. 克隆 llama.cpp 仓库
  4. 编译项目
  5. llama.cpp 的某些功能依赖 libcurl,如 llama-download 的自动下载模型
  6. 如果要使用 python 接口,还需要
  7. CPU Backend
  8. cmake --build build --config Release -j 8
  9. -j 8 可加速编译过程,视你的 CPU 核心数而定
  10. GPU Backend
  11. 这里直接安装了 CUDA12 的整个工具包
  12. 验证 nvcc --version
  13. -j 8 可加速编译过程,视你的 CPU 核心数而定
  14. 其实重启电脑也可以达到一样的效果
  15. 从 Hugging Face 下载模型
  16. 选择合适的模型
  17. 下载方法
  18. 1. 使用 Hugging Face 下载
  19. 2. 使用 ModelScope 下载
  • 💰 8折买阿里云服务器限时8折了解详情
  • Magick API 一键接入全球大模型注册送1000万token查看
  • 🤖 一键搭建Deepseek满血版了解详情
  • 一键打造专属AI 智能体了解详情
极客日志微信公众号二维码

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

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

更多推荐文章

查看全部
  • OpenClaw 本地部署指南:快速搭建自托管 AI 助手
  • C++ 函数模板
  • WebStorm 2025 版详细下载安装教程
  • LangChain Agent 基础入门:LLM 外部工具调用
  • FunASR 离线文件转写服务开发指南
  • GitHub Copilot 接入 Figma MCP 还原设计稿生成前端代码
  • Stable Diffusion WebUI 本地部署指南:CUDA、cuDNN 及 PyTorch GPU 环境配置
  • 使用 Java Flight Recorder 分析微信 API 服务的 GC 行为与内存泄漏
  • Boost C++ 库实战:构建高性能即时通讯服务器
  • 188+26 家国产大模型清单及特点分析
  • Whisper V3-Turbo 技术解析:效率与精度的平衡之道
  • 前端缓存策略最佳实践
  • C++ STL 详解:list 容器底层实现分析
  • Java 安全开发实战:从代码防护到架构安全
  • 从敏捷到生成式:AIGC 重塑软件测试全流程
  • Windows 本地部署 Ollama 与 OpenClaw 构建 AI 生产力系统
  • Git 核心原理与基础操作详解 (上)
  • DeepSeek-R1 大模型基于 MS-Swift 框架部署、推理与微调实践
  • 机器人具身智能核心解析:定义、指标与标准体系
  • Tomcat 安装、环境变量配置及 IDEA/Eclipse 集成指南

相关免费在线工具

  • 加密/解密文本

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

  • RSA密钥对生成器

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

  • Mermaid 预览与可视化编辑

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

  • 随机西班牙地址生成器

    随机生成西班牙地址(支持马德里、加泰罗尼亚、安达卢西亚、瓦伦西亚筛选),支持数量快捷选择、显示全部与下载。 在线工具,随机西班牙地址生成器在线工具,online

  • Gemini 图片去水印

    基于开源反向 Alpha 混合算法去除 Gemini/Nano Banana 图片水印,支持批量处理与下载。 在线工具,Gemini 图片去水印在线工具,online

  • Base64 字符串编码/解码

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