学习路径
面向数据科学家的 AI 工程师助理
40 小时
GLM-5 是 Z.ai 最新的开放式推理模型，因其在编码、代理工作流和长上下文对话方面的强劲表现而迅速受到关注。
许多开发者已经在用它一键生成网站、构建小型应用，并尝试本地 AI 代理。
挑战在于 GLM-5 体量非常大，在消费级硬件上本地运行并不现实。即使是量化版本也需要数百 GB 的内存以及强大的 GPU 配置。
在本教程中，我们将演示一种务实的方法：在 NVIDIA H200 集群上使用 2-bit GGUF 量化在本地运行 GLM-5，通过 llama.cpp 提供服务，并将其连接到 Aider，这样您就能在自己的项目中把 GLM-5 当作真正的编码代理来使用。
另外，也推荐查看我们的指南：本地运行 GLM 4.7 Flash。
先决条件：运行 GLM-5 需要什么
在本地运行 GLM-5 之前，您需要合适的模型变体、足够的内存来加载它，以及一套可用的 GPU 软件栈。
硬件需求取决于量化规模：
- 2-bit（281GB）：适配约 300GB 统一内存系统，或使用 1×24GB GPU + 约 300GB RAM 并配合 MoE offloading 也能良好运行
- 1-bit：适配约 180GB RAM
- 8-bit：需要约 805GB RAM
为获得最佳性能，您的 VRAM 与系统内存的总和应尽量接近量化大小。否则，llama.cpp 可以将部分负载卸载到 SSD，但推理会更慢。在 llama.cpp 中使用 --fit 以最大化 GPU 使用率。
在我们的配置中，我们在 NVIDIA H200 上运行 GLM-5-UD-Q2_K_XL，并配备足够的 VRAM 与系统内存，以高效容纳模型。
软件先决条件：
- 已安装的 GPU 驱动
- CUDA Toolkit
- 可用的 Python 环境
如何在本地运行 GLM-5
下面是本地运行 GLM-5 的分步说明：
1. 设置本地环境
即使是 1-bit 版本的 GLM-5，也大到多数消费级笔记本无法承载。因此在本教程中，我将使用Runpod，并配备一块NVIDIA H200 GPU。
首先创建一个新的 pod，并选择最新的PyTorch 模板。
然后点击Edit 来调整 pod 设置：
- 将卷磁盘大小提升至 500GB，因为我们的 2-bit 模型约为 280GB，且需要额外空间进行构建和试验。
- 打开8080 端口，这样您可以直接在浏览器中访问 llama.cpp 的 Chat UI。
- 将您的Hugging Face 令牌添加为环境变量，以加速模型下载（您可以在 Hugging Face 账户中生成令牌）。
确认无误后，查看 pod 摘要并点击Deploy On-Demand。
当 pod 就绪后，打开JupyterLab，启动一个终端（Terminal）并从那里开始操作。使用 Jupyter 终端很方便，因为无需依赖 SSH 就能顺畅运行多个会话。
首先，确认 GPU 可用：
nvidia-smi 您应当能在输出中看到 H200。
接下来，安装克隆和构建 llama.cpp 所需的 Linux 软件包：
sudo apt update
sudo apt install -y git cmake build-essential curl jq2. 使用 CUDA 支持编译 llama.cpp
现在 Runpod 环境已就绪且 GPU 正常工作，下一步是安装并编译llama.cpp，启用 CUDA 加速，使 GLM-5 能在 H200 上高效运行。
首先，进入工作区目录并克隆官方 llama.cpp 仓库：
cd /workspace
git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp此时需要注意：最新的稳定版 llama.cpp 尚未完全即开即用地支持 GLM-5。您需要拉取包含近期兼容性更新的特定上游 PR。
获取并检出更新的分支：
git fetch origin pull/19460/head:MASTER && git checkout MASTER && cd ..接下来配置构建系统，使 llama.cpp 以启用 CUDA 的方式进行编译，从而让模型使用 GPU 加速，而不是完全在 CPU 上运行。
使用开启 CUDA 标志运行 CMake：
cmake llama.cpp -B llama.cpp/build \
-DBUILD_SHARED_LIBS=OFF -DGGML_CUDA=ON
这会创建一个独立的build/ 目录，并确保 llama.cpp 服务器二进制文件支持 NVIDIA GPU 执行。
配置完成后，构建llama-server 目标：
cmake --build llama.cpp/build --config Release -j --clean-first --target llama-server
这一步可能需要几分钟，取决于 pod 性能。完成后，您将获得一个启用 CUDA 的服务器二进制文件，可用于运行 GLM-5。
最后，将编译好的可执行文件复制到主文件夹，方便访问：
cp llama.cpp/build/bin/llama-* llama.cpp3. 从 Hugging Face 下载 GLM-5 模型
llama.cpp 编译就绪后，下一步是从 Hugging Face 下载GLM-5 GGUF 模型文件。
由于这些模型检查点极其庞大，启用最快的下载方式非常重要。
Hugging Face 提供了可选工具，如hf_xet 和hf_transfer，它们能显著提升下载速度，尤其是在像 Runpod 这样的云主机上。
先安装所需的 Hugging Face 下载工具：
pip -q install -U "huggingface_hub[hf_xet]" hf-xet
pip -q install -U hf_transfer这些软件包支持更快的并行下载，并在拉取数百 GB 的模型分片时提供更好的性能。
现在下载本教程中使用的特定量化模型变体。我们只需要UD-Q2_K_XL 文件，而不是整个上传集：
hf download unsloth/GLM-5-GGUF \
--local-dir models/GLM-5-GGUF \
--include "*UD-Q2_K_XL*"这会将模型直接保存到 models/GLM-5-GGUF 目录中。
在我们的环境中，下载速度可达1.2 GB/s，这是因为我们启用了hf_xet 并提前提供了 Hugging Face 令牌。匿名下载通常会慢很多，因此在处理此规模的模型时，设置认证与传输加速能带来巨大差异。
4. 在单块 GPU 上启动 GLM-5 模型
现在模型已下载且 llama.cpp 已启用 CUDA 支持，我们可以使用内置的llama-server 启动 GLM-5。
运行以下命令启动服务器：
./llama.cpp/llama-server \
--model models/GLM-5-GGUF/UD-Q2_K_XL/GLM-5-UD-Q2_K_XL-00001-of-00007.gguf \
--alias "GLM-5" \
--host 0.0.0.0 \
--port 8080 \
--jinja \
--fit on \
--threads 32 \
--ctx-size 16384 \
--batch-size 512 \
--ubatch-size 128 \
--flash-attn auto \
--temp 0.7 \
--top-p 0.95这里有几个重要参数需要理解：
--host 0.0.0.0将服务器暴露出来，便于从浏览器访问--port 8080与我们之前在 Runpod 中打开的端口一致--fit on确保在溢出到 RAM 前尽可能利用 GPU--ctx-size 16384设置推理的上下文窗口大小--flash-attn auto在支持时启用更快的注意力内核
启动服务器后，您会注意到 llama.cpp 几乎使用了所有可用的 GPU 内存，剩余的模型层会卸载到系统内存中。这是预期行为，并且在 H200 配置上效果良好。
模型应在一分钟内加载并开始提供服务。如果您的 pod 用时显著更长，实例可能存在问题。这种情况下，通常更快的做法是终止该 pod 并新建一个。
服务器运行后，通过查询 OpenAI 兼容端点来验证 GLM-5 是否可用：
curl -s http://127.0.0.1:8080/v1/models | jq您应在响应中看到 "GLM-5"，这表明模型已加载并可使用。
{
"models": [
{
"name": "GLM-5",
"model": "GLM-5",
"modified_at": "",
"size": "",
"digest": "",
"type": "model",
"description": "",
"tags": [
""
],
"capabilities": [
"completion"
],
"parameters": "",
"details": {
"parent_model": "",
"format": "gguf",
"family": "",
"families": [
""
],
"parameter_size": "",
"quantization_level": ""
}
}
],
"object": "list",
"data": [
{
"id": "GLM-5",
"object": "model",
"created": 1770900487,
"owned_by": "llamacpp",
"meta": {
"vocab_type": 2,
"n_vocab": 154880,
"n_ctx_train": 202752,
"n_embd": 6144,
"n_params": 753864139008,
"size": 281373251584
}
}
]
}5. 通过聊天界面测试 GLM-5 模型
服务器运行后，您可以直接通过内置的 llama.cpp Chat UI 测试 GLM-5。
通常，WebUI 可在本地访问：http://127.0.0.1:8080
不过，由于我们在云端的 Runpod 上运行，该 localhost 链接无法从您的本机访问。
请改为前往您的Runpod 控制台，点击 8080 端口对应的HTTP Service 链接。这是转发到您正在运行的 llama-server 的公共 URL。
打开该链接将进入 Chat UI，GLM-5 模型已加载就绪。
为确认一切正常，先发送一个简单消息，如 “Hey!!”。您应能看到模型立即响应。
在我们的情况下，推理速度约为每秒 8.7 个 token，考虑到 GLM-5 的体量和 281GB 的量化检查点，这个性能非常出色。
6. 安装并连接 Aider
Aider 是一个基于终端的 AI 结对编程工具，可直接在您的项目文件夹中工作。
您可以像与编码伙伴聊天一样与它交流，它能在整个代码仓中创建、编辑和重构文件，同时始终基于您的实际代码库与 git 工作流。
它还支持连接到任何兼容 OpenAI 的 API 端点，这使它非常适合与我们本地的 llama.cpp 服务器配合使用。
首先安装 Aider：
pip install -U aider-chat接着，将 Aider 指向您的本地 llama.cpp OpenAI 兼容服务器。我们设置了一个占位 key，因为 llama.cpp 并不需要真实的 OpenAI key：
export OPENAI_API_BASE=http://127.0.0.1:8080/v1
export OPENAI_API_KEY=local
export OPENAI_BASE_URL=$OPENAI_API_BASE现在创建一个全新的演示项目文件夹（让 Aider 有一个干净的仓库来工作）：
mkdir -p glm5-demo-app
cd glm5-demo-app最后，启动 Aider，并使用我们先前暴露的模型别名连接到 GLM-5：
aider --model openai/GLM-5 --no-show-model-warnings此时，您在 Aider 中的任何请求都会通过本地 GLM-5 服务器路由，Aider 会将更改直接应用到 glm5-demo-app 中的文件。
将 GLM-5 用作您的编码代理
一旦 Aider 连接到 GLM-5，您就可以在仓库内将其当作编码代理来使用。先用一个简单的问候语确认其响应迅速。
然后，给出一个清晰的任务提示，例如：
Create a simple Python FastAPI project with one /health endpoint, a README, and instructions to run it locally.
Aider 会先提出一个计划，然后请求允许应用修改。
接受修改后，它会自动生成文件。
在像GLM-5-UD-Q2_K_XL 这样的 2-bit 量化上，您可能会看到一些小错误，例如创建一个类似 pip install -r requirements.txt 这样的文件——这是错误的。完整模型更不容易犯此类错误，但 2-bit 模型在快速人工检查下仍非常好用。
Aider 完成项目写入后，进入该文件夹，安装依赖并运行服务器：
cd glm5-demo-app/pip install -r requirements.txt使用 Uvicorn 启动 FastAPI 应用：
uvicorn main:app --reload服务器将运行在 8000 端口。
测试健康检查端点：
curl -s http://127.0.0.1:8000/health您应当得到：
{"status":"ok"}结语
GLM-5 正迅速成为 AI 社区最受讨论的开源权重模型之一，尤其因为它将开源性能进一步逼近闭源模型，同时面向深度推理、代理式工作流与编码任务而设计。
尽管声势很大，在本地运行全尺寸模型对普通用户而言仍然是挑战。
即便经过量化，像 GLM-5 这样的模型仍需要数百 GB 的内存与高速 GPU，这并不是许多人在家用设备上所具备的。
这意味着大多数人要么依赖云端 GPU pod（如本教程中的 H200 配置），要么使用托管的 API 服务。
GLM-5 的开源权重特性非常有力，因为它让您可以自行托管与控制实例，而无需依赖专有 API 提供商；但这也凸显了为什么在 AI 领域，“开源”并不意味着人人都能“在笔记本上跑起来”。
在本教程中，我们展示了如何在Runpod 的 H200 GPU 上使用 2-bit 量化版 GLM-5 来克服这些硬件障碍。我们依次完成了环境搭建、编译启用 CUDA 的 llama.cpp、高效下载模型、启动推理服务器、通过浏览器 UI 测试，最后连接 Aider，将 GLM-5 用作实际开发任务的代理。