从零开始：在 Windows 上用 llama.cpp 跑本地大模型

一篇给普通人的手把手教程。不需要懂 AI、不需要懂编程，跟着做就能在自己电脑上跑大模型。

你会得到什么

一台不联网也能聊天的本地 AI
一个 OpenAI 兼容的 API 服务，可以接各种工具
开机自动启动，随时可用
所有数据留在本地，隐私零泄漏

你需要什么

条件	最低要求
显卡	NVIDIA 独显，4GB 显存以上
系统	Windows 10/11，64 位
硬盘	约 8GB 空闲空间
网络	下载模型时需要，之后可断网

速度预期（4GB 显卡）

操作	速度
读取你的问题	~94 字/秒
生成回答	~46 字/秒

日常聊天完全够用，比打字快得多。

第一步：装工具链

本地跑模型需要三个编译工具，就像做菜之前先得有锅碗瓢盆。

1.1 装 VS Build Tools（C++ 编译器）

这是微软的官方编译器，llama.cpp 需要它来编译。

powershell 复制代码

# 下载安装器
curl.exe -L -o "$env:TEMP\vs_buildtools.exe" "https://aka.ms/vs/17/release/vs_buildtools.exe" --max-time 60

# 静默安装（需要管理员权限，会弹出 UAC 确认）
Start-Process -FilePath "$env:TEMP\vs_buildtools.exe" -ArgumentList '--quiet','--wait','--norestart','--add','Microsoft.VisualStudio.Workload.VCTools','--add','Microsoft.VisualStudio.Component.VC.Tools.x86.x64','--add','Microsoft.VisualStudio.Component.Windows11SDK.22621' -Verb RunAs -Wait

💡 这一步会下载约 2-3GB，耐心等。安装完后不会弹出任何提示，这是正常的。

1.2 装 CMake（构建工具）

CMake 负责把源代码组织成可以编译的项目。

powershell 复制代码

# 下载 CMake 便携版（免安装，解压即用）
curl.exe -L -o "$env:TEMP\cmake-portable.zip" "https://github.com/Kitware/CMake/releases/download/v3.31.6/cmake-3.31.6-windows-x86_64.zip" --max-time 300

# 解压到 D 盘
Expand-Archive -Path "$env:TEMP\cmake-portable.zip" -DestinationPath "D:\" -Force

# 验证
& "D:\cmake-3.31.6-windows-x86_64\bin\cmake.exe" --version
# 应该输出: cmake version 3.31.6

⚠️ 如果 GitHub 下载慢或失败，看文末「常见问题 - 网络不通」。

1.3 装 CUDA Toolkit（GPU 加速）

这是 NVIDIA 的 GPU 计算工具，没有它模型只能用 CPU 跑，慢 10 倍以上。

powershell 复制代码

# 下载 CUDA 12.4.1 安装包（约 3GB）
curl.exe -L -o "$env:TEMP\cuda_installer.exe" "https://developer.download.nvidia.com/compute/cuda/12.4.1/local_installers/cuda_12.4.1_551.78_windows.exe" --max-time 600

然后右键以管理员身份运行以下命令（弹出 UAC 点"是"）：

powershell 复制代码

# 静默安装 CUDA（只装编译需要的组件，省空间）
Start-Process -FilePath "$env:TEMP\cuda_installer.exe" -ArgumentList '-s','nvcc_12.4','cublas_12.4','cublas_dev_12.4','cudart_12.4','cufft_12.4','curand_12.4','cusolver_12.4','cusparse_12.4','npp_12.4','nvrtc_12.4','nvml_dev_12.4','visual_studio_integration_12.4' -Verb RunAs -Wait

⚠️ visual_studio_integration_12.4 这个组件必须装，不然后面编译会报 "No CUDA toolset found"。

验证安装：

powershell 复制代码

& "C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.4\bin\nvcc.exe" --version
# 应该输出: release 12.4

1.4 装 Ninja（并行编译器）

powershell 复制代码

pip install ninja

第二步：下载并编译 llama.cpp

llama.cpp 是目前最流行的本地大模型运行引擎，开源免费。

2.1 下载源码

powershell 复制代码

# 用国内镜像下载（GitHub 直连国内可能很慢）
git clone https://ghfast.top/https://github.com/ggerganov/llama.cpp D:\llama.cpp --depth 1

2.2 编译（带 CUDA 加速）

powershell 复制代码

# 创建编译脚本
$buildScript = @"
call "C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Auxiliary\Build\vcvarsall.bat" x64
set PATH=D:\cmake-3.31.6-windows-x86_64\bin;C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.4\bin;%PATH%
cd /d D:\llama.cpp
cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DGGML_CUDA=ON -DCMAKE_C_COMPILER=cl -DCMAKE_CXX_COMPILER=cl
cmake --build build -j %NUMBER_OF_PROCESSORS%
"@
$buildScript | Out-File -FilePath "$env:TEMP\build_llama.bat" -Encoding ASCII

# 执行编译（约 5-10 分钟）
cmd.exe /c "$env:TEMP\build_llama.bat"

2.3 验证

powershell 复制代码

& "D:\llama.cpp\build\bin\llama-cli.exe" --version
# 应该输出版本号，没有报错就成功了

第三步：下载模型

我们用 Gemma 4 E2B --- Google 出的小模型，4GB 显卡刚好能跑。

模型	量化后大小	4GB 显卡	推荐度
Gemma 4 E2B Q4_K_M	~3.3GB	✅ 完全装下	⭐⭐⭐⭐⭐
Gemma 4 E4B Q4_K_M	~5.4GB	❌ 装不下	---

💡 "E2B" = 有效 2B 参数，"Q4_K_M" = 4-bit 量化，质量和速度的最佳平衡点。

3.1 用 HuggingFace 镜像下载

powershell 复制代码

# 设置国内镜像（HuggingFace 在国内被墙）
$env:HF_ENDPOINT = "https://hf-mirror.com"

# 用 Python 下载模型文件（约 3.3GB）
python -c "
import os
os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com'
from huggingface_hub import hf_hub_download
path = hf_hub_download(
    repo_id='bartowski/google_gemma-4-E2B-it-GGUF',
    filename='google_gemma-4-E2B-it-Q4_K_M.gguf',
    local_dir='D:/models'
)
print(f'Downloaded to: {path}')
"

下载完成后文件在 D:\models\google_gemma-4-E2B-it-Q4_K_M.gguf。

第四步：跑起来！

4.1 交互式聊天（试试看）

powershell 复制代码

D:\llama.cpp\build\bin\llama-cli.exe -m D:\models\google_gemma-4-E2B-it-Q4_K_M.gguf --chat-template gemma -c 2048 -ngl 99

参数	含义
`-m`	模型文件路径
`--chat-template gemma`	用 Gemma 的对话格式
`-c 2048`	上下文长度（越大越吃内存，2048 够日常用）
`-ngl 99`	把模型全部 99 层放到 GPU 上跑

输入问题回车即可聊天。输入 /exit 退出。

4.2 启动 API 服务（给其他工具用）

powershell 复制代码

D:\llama.cpp\build\bin\llama-server.exe -m D:\models\google_gemma-4-E2B-it-Q4_K_M.gguf --port 8080 -c 2048 -ngl 99

启动后，任何支持 OpenAI API 的工具都能连上来：

python 复制代码

# Python 示例
from openai import OpenAI
client = OpenAI(base_url="http://localhost:8080/v1", api_key="sk-no-key")
resp = client.chat.completions.create(
    model="gemma-4-e2b",
    messages=[{"role": "user", "content": "你好"}]
)
print(resp.choices[0].message.content)

javascript 复制代码

// Node.js 示例
import OpenAI from 'openai';
const client = new OpenAI({ baseURL: 'http://localhost:8080/v1', apiKey: 'sk-no-key' });
const resp = await client.chat.completions.create({
  model: 'gemma-4-e2b',
  messages: [{ role: 'user', content: '你好' }]
});
console.log(resp.choices[0].message.content);

甚至可以用 curl：

powershell 复制代码

curl http://localhost:8080/v1/chat/completations -H "Content-Type: application/json" -d '{\"model\":\"gemma4\",\"messages\":[{\"role\":\"user\",\"content\":\"Hello\"}]}'

4.3 确认 GPU 在工作

打开任务管理器 → 性能 → GPU，应该看到：

GPU 专用内存：约 2.1GB 被占用
GPU 利用率：聊天时有波动

如果 GPU 利用率为 0，说明模型在用 CPU 跑，看「常见问题」章节。

第五步：设置开机自启

让模型服务开机自动启动，不用每次手动开。

5.1 创建启动脚本

powershell 复制代码

# 写一个 bat 脚本，内置 PATH 设置（避免重启后找不到 DLL）
$bat = "@echo off`r`nset PATH=D:\llama.cpp\build\bin;C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.4\bin;%PATH%`r`ntimeout /t 10 /nobreak >nul`r`nstart /b `"`" `"`"D:\llama.cpp\build\bin\llama-server.exe`"`" -m `"`"D:\models\google_gemma-4-E2B-it-Q4_K_M.gguf`"`" --port 8080 -c 2048 -ngl 99`r`n"
[System.IO.File]::WriteAllText("D:\start-llama-server.bat", $bat, [System.Text.Encoding]::ASCII)

5.2 注册开机自启任务

powershell 复制代码

$action = New-ScheduledTaskAction -Execute "cmd.exe" -Argument '/c D:\start-llama-server.bat' -WorkingDirectory "D:\"
$trigger = New-ScheduledTaskTrigger -AtLogon -User $env:USERNAME
$settings = New-ScheduledTaskSettingsSet -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries -StartWhenAvailable -ExecutionTimeLimit (New-TimeSpan -Days 365)
$principal = New-ScheduledTaskPrincipal -UserId $env:USERNAME -LogonType Interactive -RunLevel Limited
Register-ScheduledTask -TaskName "llama-server" -Action $action -Trigger $trigger -Settings $settings -Principal $principal -Description "Local LLM server" -Force

5.3 把 PATH 加到系统环境变量

这一步很关键！重启后 DLL 才能被找到：

powershell 复制代码

# 添加到用户 PATH（不需要管理员）
$userPath = [System.Environment]::GetEnvironmentVariable("Path", "User")
if ($userPath -notlike "*D:\llama.cpp\build\bin*") {
    $userPath += ";D:\llama.cpp\build\bin;C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.4\bin"
    [System.Environment]::SetEnvironmentVariable("Path", $userPath, "User")
}

5.4 管理命令

powershell 复制代码

# 手动启动
schtasks /run /tn "llama-server"

# 禁用自启
schtasks /change /tn "llama-server" /disable

# 重新启用
schtasks /change /tn "llama-server" /enable

# 删除任务
schtasks /delete /tn "llama-server" /f

第六步：添加 PowerShell 快捷命令

在终端里输入 llama-start 就能启动，比记一长串命令方便多了。

powershell 复制代码

# 把快捷函数写入 PowerShell 配置文件
$functions = @'

# === Local LLM Shortcuts ===
function llama-start {
    $env:Path = "D:\llama.cpp\build\bin;C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.4\bin;" + $env:Path
    Start-Process -FilePath "D:\llama.cpp\build\bin\llama-server.exe" -ArgumentList '-m', 'D:\models\google_gemma-4-E2B-it-Q4_K_M.gguf', '--port', '8080', '-c', '2048', '-ngl', '99' -WindowStyle Hidden
    Write-Host "llama-server starting on port 8080..." -ForegroundColor Green
}

function llama-stop {
    Stop-Process -Name "llama-server" -Force -ErrorAction SilentlyContinue
    Write-Host "llama-server stopped." -ForegroundColor Yellow
}

function llama-status {
    $proc = Get-Process -Name "llama-server" -ErrorAction SilentlyContinue
    if ($proc) {
        Write-Host "llama-server running, PID: $($proc.Id)" -ForegroundColor Green
        nvidia-smi --query-gpu=memory.used,memory.total --format=csv,noheader
    } else {
        Write-Host "llama-server not running" -ForegroundColor Red
    }
}
'@

Add-Content -Path $PROFILE -Value $functions

重新打开 PowerShell 后就能用了：

复制代码

PS> llama-start    # 后台启动服务
PS> llama-status   # 查看状态和显存
PS> llama-stop     # 停止服务

第七步（可选）：添加到 Windows Terminal 下拉菜单

如果你用 Windows Terminal，可以在下拉菜单里加三个快捷项，一键启动/停止/查看状态。

打开 Windows Terminal 的设置文件：

复制代码

C:\Users\<你的用户名>\AppData\Local\Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\LocalState\settings.json

在 profiles → list 数组里添加三个 Profile：

json 复制代码

{
    "colorScheme": "One Half Dark",
    "commandline": "powershell.exe -NoExit -Command \"$env:Path='D:\\llama.cpp\\build\\bin;C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v12.4\\bin;'+$env:Path; llama-start; llama-status\"",
    "font": { "face": "Cascadia Mono", "size": 11 },
    "guid": "{aeacfd10-ffa2-45ee-9b2b-d93c43564a46}",
    "name": "🟢 LLM Start",
    "startingDirectory": "D:\\"
},
{
    "colorScheme": "One Half Dark",
    "commandline": "powershell.exe -NoExit -Command \"$env:Path='D:\\llama.cpp\\build\\bin;C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v12.4\\bin;'+$env:Path; llama-stop\"",
    "font": { "face": "Cascadia Mono", "size": 11 },
    "guid": "{b2f3a91c-7d4e-4f8b-9c5a-1e6d2f8b3c7a}",
    "name": "🔴 LLM Stop",
    "startingDirectory": "D:\\"
},
{
    "colorScheme": "One Half Dark",
    "commandline": "powershell.exe -NoExit -Command \"$env:Path='D:\\llama.cpp\\build\\bin;C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v12.4\\bin;'+$env:Path; llama-status\"",
    "font": { "face": "Cascadia Mono", "size": 11 },
    "guid": "{c3d4e52d-8f6a-4b9c-a7d2-3f4e5b6c8d9e}",
    "name": "📊 LLM Status",
    "startingDirectory": "D:\\"
}

保存后重新打开 Terminal，下拉菜单里就能看到了。

换个更大的模型

如果你的显卡显存更大，可以换更强的模型。只需要换模型文件，其他都不用改。

模型选择参考

显卡显存	推荐模型	Q4_K_M 大小	命令中的变化
4GB	Gemma 4 E2B	~3.3GB	本教程默认
8GB	Gemma 4 E4B	~5.4GB	换模型文件，`-ngl 99` 部分卸载
8GB	Qwen3-4B	~2.6GB	换模型文件
16GB	Gemma 4 12B	~7.8GB	换模型文件，`-c 4096`
24GB	Gemma 4 26B A4B	~14GB	换模型文件

下载其他模型

powershell 复制代码

$env:HF_ENDPOINT = "https://hf-mirror.com"
python -c "
import os
os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com'
from huggingface_hub import hf_hub_download
path = hf_hub_download(
    repo_id='bartowski/Qwen3-4B-GGUF',          # 换成你想下的模型
    filename='Qwen3-4B-Q4_K_M.gguf',              # 换成对应文件名
    local_dir='D:/models'
)
print(f'Downloaded to: {path}')
"

然后在启动命令里把 -m 后面的路径换成新模型就行。

常见问题

🔴 编译报 "No CUDA toolset found"

原因：CUDA 的 Visual Studio 集成组件没装。

解决：重新运行 CUDA 安装器，加上 visual_studio_integration_12.4：

powershell 复制代码

Start-Process -FilePath "$env:TEMP\cuda_installer.exe" -ArgumentList '-s','visual_studio_integration_12.4' -Verb RunAs -Wait

另外，必须用 Ninja 生成器编译，不要用 MSBuild（Visual Studio 生成器），后者对 CUDA 支持经常出问题。

🔴 编译报 "No CMAKE_ASM_COMPILER could be found"

原因：MASM 汇编器没被 CMake 检测到。

解决：显式指定汇编器路径：

powershell 复制代码

cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DGGML_CUDA=ON -DCMAKE_C_COMPILER=cl -DCMAKE_CXX_COMPILER=cl -DCMAKE_ASM_COMPILER="C:/Program Files (x86)/Microsoft Visual Studio/2022/BuildTools/VC/Tools/MSVC/14.44.35207/bin/Hostx64/x64/ml64.exe"

路径中的 14.44.35207 要换成你机器上实际的版本号。

🔴 重启后服务不自启 / 闪退

原因：ggml-cuda.dll 等依赖 CUDA 运行时 DLL，但系统 PATH 里找不到它们。

表现：退出码 -1073741515（十六进制 0xC0000135），意思是 "找不到 DLL"。

解决：确保做了两件事：

启动脚本里加了 set PATH=D:\llama.cpp\build\bin;C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.4\bin;%PATH%
把这两个路径加到了系统用户 PATH（见第五步 5.3）

🔴 模型用 CPU 跑，GPU 利用率为 0

原因：llama.cpp 编译时没带 CUDA，或者启动时没加 -ngl 参数。

排查：

检查启动日志有没有 warning: no usable GPU found --- 如果有，说明编译没带 CUDA
检查启动命令有没有 -ngl 99 --- 没有这个参数模型就全在 CPU 跑

解决：重新编译（带 -DGGML_CUDA=ON），启动时加 -ngl 99。

🔴 网络不通，GitHub / HuggingFace 下载失败

国内用户通用方案：

网站	问题	解决
GitHub	连接超时	用镜像 `https://ghfast.top/https://github.com/...`
HuggingFace	被墙	设置 `$env:HF_ENDPOINT = "https://hf-mirror.com"`
NVIDIA	通常可达	直接下载即可
CMake	GitHub 托管	同 GitHub 镜像方案

powershell 复制代码

# GitHub 镜像克隆
git clone https://ghfast.top/https://github.com/ggerganov/llama.cpp --depth 1

# HuggingFace 镜像下载模型
$env:HF_ENDPOINT = "https://hf-mirror.com"
python -c "
import os; os.environ['HF_ENDPOINT']='https://hf-mirror.com'
from huggingface_hub import hf_hub_download
hf_hub_download(repo_id='bartowski/google_gemma-4-E2B-it-GGUF', filename='google_gemma-4-E2B-it-Q4_K_M.gguf', local_dir='D:/models')
"

🔴 显存不够（模型装不下）

如果模型大于显存，可以用 -ngl 参数只卸载部分层到 GPU：

powershell 复制代码

# 只把前 20 层放 GPU，剩下的用 CPU 内存
llama-server -m model.gguf --port 8080 -c 2048 -ngl 20

GPU 层数越多越快，但显存占用也越大。可以从 ngl 99 往下减，直到显存不爆。

清理磁盘空间

安装完成后，下载的安装包和编译缓存可以安全删除，不影响已装好的程序运行。

powershell 复制代码

# 一键清理（约释放 3GB）
Remove-Item "$env:TEMP\cuda_installer.exe" -Force -EA SilentlyContinue   # CUDA 安装包 (~3GB)
Remove-Item "$env:TEMP\cmake-portable.zip" -Force -EA SilentlyContinue   # CMake 压缩包
Remove-Item "$env:TEMP\cmake-install.msi" -Force -EA SilentlyContinue    # CMake 安装包
Remove-Item "$env:TEMP\vs_buildtools.exe" -Force -EA SilentlyContinue    # VS 安装器
Remove-Item "D:\llama.cpp\.git" -Recurse -Force -EA SilentlyContinue     # git 历史
pip uninstall nvidia-cublas-cu12 nvidia-cuda-nvcc-cu12 nvidia-cuda-nvrtc-cu12 nvidia-cuda-runtime-cu12 -y 2>$null

绝对不能删的：

路径	为什么
`D:\models\*.gguf`	模型本体，删了就不能跑了
`D:\llama.cpp\build\`	编译结果，删了要重新编译
`C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\`	CUDA 运行时，删了 GPU 加速就没了

完整文件结构

安装完成后的文件分布：

复制代码

D:\
├── llama.cpp\                          # 源码和编译产物
│   └── build\bin\
│       ├── llama-cli.exe               # 命令行聊天
│       ├── llama-server.exe            # API 服务
│       ├── ggml-cuda.dll               # CUDA 后端
│       ├── ggml-cpu.dll                # CPU 后端
│       ├── llama.dll                   # 核心库
│       └── ...
├── models\
│   └── google_gemma-4-E2B-it-Q4_K_M.gguf  # 模型文件
├── cmake-3.31.6-windows-x86_64\        # CMake 工具
└── start-llama-server.bat              # 启动脚本

C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.4\  # CUDA 运行时
C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\  # VS 编译器

速查卡片

复制代码

# 启动服务
D:\llama.cpp\build\bin\llama-server.exe -m D:\models\google_gemma-4-E2B-it-Q4_K_M.gguf --port 8080 -c 2048 -ngl 99

# 命令行聊天
D:\llama.cpp\build\bin\llama-cli.exe -m D:\models\google_gemma-4-E2B-it-Q4_K_M.gguf --chat-template gemma -c 2048 -ngl 99

# 快捷命令（需先配置 $PROFILE）
llama-start      # 启动
llama-stop       # 停止
llama-status     # 状态

# 重新编译（源码更新后）
call "C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Auxiliary\Build\vcvarsall.bat" x64
set PATH=D:\cmake-3.31.6-windows-x86_64\bin;C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.4\bin;%PATH%
cd D:\llama.cpp
rd /s /q build
cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DGGML_CUDA=ON -DCMAKE_C_COMPILER=cl -DCMAKE_CXX_COMPILER=cl
cmake --build build -j %NUMBER_OF_PROCESSORS%

写在最后

本地大模型不是云端的替代品 --- 它更像是你口袋里的一把瑞士军刀：随时可用、不依赖网络、数据不外泄。

Gemma 4 E2B 虽然小，但日常问答、文本摘要、代码补全这些任务完全能胜任。等你想换更强的模型，只需要下载新模型文件、改一下路径，其他一切不变。

享受你的本地 AI 吧 🎉