如何在本地运行 GLM 5.1 以支持 Agentic 编码

GLM 5.1 是当下您可以本地运行的最强开源模型之一，Artificial Analysis 目前在其 Intelligence Index 上将其描述为领先的开放权重模型。Z.ai 也将其定位为面向编码、推理与 Agentic 工作流的旗舰版本。

来源：AI Model & API Providers Analysis | Artificial Analysis

在本地运行可让您对完整工作流拥有更多掌控。您的数据保留在自身环境中，您可以测试提示词、构建集成，并在编码项目中使用它，同时更注重隐私，减少外部数据泄露的担忧。

在本教程中，您将设置一个 H100 RunPod 环境，在本地运行 GLM 5.1，用 API 调用进行测试，将其连接到 OpenAI Python SDK，通过 WebUI 访问，并与 Claude Code 集成。 

步骤 1：租用并配置 H100 GPU Pod

首先前往 RunPod 的Pods 标签页，选择一台H100 SXM 机器。模板请选择最新的 PyTorch 选项，以便拥有一套可直接运行模型负载的环境。

部署前，请更新 Pod 的存储设置。将容器磁盘设置为100GB，卷磁盘设置为300GB，以确保有足够空间用于模型文件、依赖项和下载缓存。 

我们将在已挂载的 /workspace 目录中完成所有工作，使一切集中在同一位置。您还应开放8910 端口，我们将同时将其用于本地模型服务器和llama.cpp 的 WebUI。

接下来，将您的 Hugging Face 令牌以环境变量 HF_TOKEN 的形式添加。 

完成设置后，查看 Pod 概要并点击按需部署（Deploy On-Demand）。Pod 启动后，打开其附带的JupyterLab 实例。

在 JupyterLab 中，启动一个新终端，并运行以下命令安装所需的系统软件包：

apt-get update
apt-get install -y pciutils build-essential cmake curl git tmux libcurl4-openssl-dev

步骤 2：构建支持 CUDA 的 llama.cpp

现在 Pod 已就绪，下一步是构建带有 CUDA 支持的 llama.cpp，以便使用 H100 GPU 进行本地推理。

首先，从 GitHub 克隆 llama.cpp 仓库：

git clone https://github.com/ggml-org/llama.cpp

接着，配置构建，将生成的构建文件放在单独的 build 文件夹中：

cmake llama.cpp -B llama.cpp/build \
-DBUILD_SHARED_LIBS=OFF \
-DGGML_CUDA=ON

然后，以优化的 Release 模式编译我们需要的主二进制文件：

cmake --build llama.cpp/build --config Release -j --clean-first \
--target llama-cli llama-mtmd-cli llama-server llama-gguf-split

最后，将编译好的二进制文件复制到主 llama.cpp 文件夹，便于后续运行：

cp llama.cpp/build/bin/llama-* llama.cpp

完成此步骤后，您将获得主要的 llama.cpp 工具，包括稍后用于本地运行 GLM 5.1 的 llama-server。

步骤 3：下载 GLM 5.1 GGUF 模型

在下载模型之前，先了解一下为什么我们在此设置中使用2-bit 版本会更合适。

完整的GLM 5.1 模型有7440 亿参数，其中活跃参数为 400 亿，具有20 万上下文窗口，并大约需要1.65TB 磁盘空间。对于本地实践而言，这显然过大。 

而Unsloth Dynamic 2-bit GGUF 版本可将大小缩减至约220–236GB，将存储需求降低约80%，同时保留关键层的高精度以获得更好的性能。

这使得 2-bit 模型非常适合我们的硬件条件。配备80GB VRAM 和 125GB RAM 的情况下，该量化版本仍然吃资源，但在本地运行更为现实，同时在编码和 Agentic 工作流中仍能提供强劲表现。

现在，让我们安装高效下载模型文件所需的工具。

首先，安装带有 hf_xet 支持的 Hugging Face Hub 包，以及 hf-xet 辅助工具：

pip -q install -U "huggingface_hub[hf_xet]" hf-xet

接着，安装 hf_transfer 以加速大型模型的下载：

pip -q install -U hf_transfer

随后，启用高性能传输以加快下载速度：

export HF_XET_HIGH_PERFORMANCE=1

最后，将 GLM 5.1 模型文件下载到本地文件夹：

hf download unsloth/GLM-5.1-GGUF \
--local-dir models/GLM-5.1-GGUF \
--include "*UD-IQ2_M*"

即便是这个更小的版本，下载体量仍然很大。在我的环境中，2-bit 模型耗时大约 17 分钟完成，因此耗时稍长也属正常。

步骤 4：启动 GLM 5.1 本地服务器

现在是时候启动本地服务器，并将模型加载到内存中。

运行以下命令：

./llama.cpp/llama-server \
  --model ./models/GLM-5.1-GGUF/UD-IQ2_M/GLM-5.1-UD-IQ2_M-00001-of-00006.gguf \
  --alias "GLM-5.1" \
  --host 0.0.0.0 \
  --port 8910 \
  --jinja \
  --fit on \
  --threads 16 \
  --threads-batch 16 \
  --ctx-size 32768 \
  --batch-size 2048 \
  --ubatch-size 512 \
  --flash-attn on \
  --temp 0.7 \
  --top-p 0.95 \
  --cont-batching \
  --metrics \
  --perf

这里需要重点关注的参数是 --fit on。它指示服务器尽可能将更多模型权重放入 GPU，并将其余部分卸载到系统内存。这在我们的设置中尤为有用，因为它有助于在可用的80GB VRAM 和 125GB RAM 条件下，在无需手动控制层放置的情况下运行超大模型。

其他参数主要用于控制服务器名称、端口、性能设置、批处理以及推理的上下文长度。

模型加载完成后，您将看到一条消息，显示服务器正在监听：http://0.0.0.0:8910。

此时，GLM 5.1 已在本地运行，可以在下一步进行测试。

步骤 5：使用 cURL 测试本地 GLM-5.1 API

服务器运行后，下一步是确保模型可以通过其本地 API 正常响应。

在 JupyterLab 中打开一个新终端，以便原始终端继续运行服务器。然后使用 curl 发送一个简单的测试请求：

curl http://127.0.0.1:8910/v1/messages \
-H "Content-Type: application/json" \
-H "x-api-key: local-test" \
-d '{
"model": "GLM-5.1",
"max_tokens": 300,
"messages": [
{"role": "user", "content": "Write a Python hello world function."}
]
}'

此请求会将一个提示发送到您本地运行的 GLM 5.1 服务器，并要求其生成简短的回复。这里需要注意的主要点是本地服务器 URL、模型名称，以及请求体中使用的 messages 格式。

如果一切运行正常，终端将返回包含模型输出的 JSON 响应。

步骤 7：将本地 GLM 5.1 连接到 OpenAI Python SDK

现在本地 API 已可用，下一步是将其连接到OpenAI Python SDK。这很有用，因为许多现有应用和脚本已使用 OpenAI 客户端，将其指向您的本地 GLM 5.1 服务器，可大大简化集成。

首先，升级 pip 并安装 OpenAI 包：

python -m pip install --upgrade pip
pip install openai

然后运行一个简短的 Python 脚本，将 SDK 连接到您的本地服务器：

python - <<'PY'
from openai import OpenAI

client = OpenAI(
    api_key="local-key",
    base_url="http://127.0.0.1:8910/v1",
)

resp = client.completions.create(
    model="GLM-5.1",
    prompt="Answer briefly and in plain text only.\n\nQuestion: What is the capital city of Australia?\nAnswer:",
    temperature=0.2,
    max_tokens=12,
)

print(resp.choices[0].text.strip())
PY

这里的关键在于我们并未调用 OpenAI 云端 API，而是使用相同的 SDK，将 base_url 指向本地 GLM 5.1 服务器，即运行在 8910 端口的实例。

如果一切设置正确，输出应为：

Canberra

步骤 8：通过 llama.cpp WebUI 访问本地 GLM 5.1

最新的 llama.cpp 服务器包含内置 WebUI，这意味着您可以通过简洁的聊天界面与本地 GLM 5.1 模型交互，而不必只使用终端或 API 调用。

要打开它，请回到您的RunPod 控制台，打开该 Pod 的Connect 选项卡。由于8910 端口已暴露，点击该端口的HTTP Service 链接，即可在新浏览器标签页中打开 llama.cpp WebUI。

页面加载后，您可以直接开始与模型对话。输入您的第一个提示，几秒钟内就会出现响应。在我的环境中，模型生成速度约为每秒 8 个 token，对于如此规模的模型来说，这一速度相当不错。

作为快速测试，试着让它构建一个简单的Hello World 应用。它可以在多种主流编程语言中生成可运行的示例。

步骤 9：将 Claude Code 与本地 GLM 5.1 集成

既然 GLM 5.1 已在本地运行，下一步是将其连接到Claude Code。这是一个有价值的测试，因为 GLM 5.1 被定位为强大的编码模型，将其用于编码 Agent 工作流能更好地反映其在真实开发任务中的表现。

Start 先安装 Claude Code：

curl -fsSL https://claude.ai/install.sh | bash

接着，将 Claude Code 添加到您的 shell PATH，以便在终端使用 claude 命令：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

然后，配置 Claude Code 指向您的本地 GLM 5.1 服务器，而非托管的 Anthropic API：

cat >> ~/.bashrc <<'EOF'
export ANTHROPIC_BASE_URL="http://127.0.0.1:8910"
export ANTHROPIC_AUTH_TOKEN="local-dev-token"
export ANTHROPIC_MODEL="GLM-5.1"
export ANTHROPIC_DEFAULT_SONNET_MODEL="GLM-5.1"
export API_TIMEOUT_MS=1200000
EOF

随后重新加载 shell 配置，使这些环境变量生效：

source ~/.bashrc

现在，创建一个测试文件夹并在其中启动 Claude Code：

mkdir -p test-claude-local
cd test-claude-local
claude

Claude Code 首次启动时，可能会要求您完成一些设置步骤，例如选择主题或信任工作目录。完成后，您即可开始下达任务。

作为第一个简单测试，尝试以下提示：

Build the simple Hello World app in Python

这将帮助您检查 Claude Code 是否已成功向本地 GLM 5.1 服务器发送请求，并使用其进行代码生成。

就我的体验而言，该设置可行，但明显比先前测试更慢。 

在更长上下文和偏编码风格的提示下，生成速度会降至每秒约 2 个 token，且模型常常在给出简单答案前花费过多时间进行推理。 

这是我在该工作流中对 GLM 5.1 注意到的主要权衡之一：它很强大，但对于轻量级编码任务，速度可能偏慢且输出更为冗长。

GLM 5.1 常见问题与解决方法

本节涵盖在本地运行 GLM 5.1 时可能遇到的一些常见问题以及快速修复方法。

1. 模型无法加载或在启动时崩溃

通常意味着模型对可用的 GPU 与系统内存来说过大，请尝试更小的量化版本或降低上下文大小。llama.cpp 也支持 --fit on，可帮助自动在可用内存中进行适配。

2. 服务器已启动，但 WebUI 无法打开

请确保您打开的是 RunPod 中暴露的正确端口，而不是 JupyterLab 的 URL。llama.cpp 服务器内置了 WebUI，因此关键在于服务器端口，URL 应指向暴露的 HTTP 服务上的 0.0.0.0:8910。

3. API 在某个工具中可用，但在另一个工具中不可用

这通常是基础 URL 或端点不匹配导致的。llama.cpp 同时支持 OpenAI 兼容路由与 Anthropic Messages 兼容路由，请检查您的工具是否指向正确的路径，例如 /v1 或 /v1/messages。

4. Claude Code 可用，但感觉很慢

这可能是因为性能取决于客户端与后端模型行为的双重因素。Claude Code 可通过设置与环境变量进行配置，但较慢的响应通常是由于模型花更久时间进行推理或生成所致。

5. 在较长提示下，模型感觉过慢

更长的上下文窗口与更大的生成长度会增加内存压力并延长响应时间。减少上下文大小、提示长度或生成参数，有助于在本地环境中提升速度。

总结

总体而言，在本地设置 GLM 5.1 相当直接。下载模型、运行服务器并进行基础测试并不费劲。对于简单的本地实验，整个流程是相当可控的。

当您希望用于 Agentic 编码工作流时，挑战就开始显现。这需要更多 RAM 与 VRAM，且随着上下文窗口的填充，token 生成速度会明显下降。即使模型一开始感觉很快，“思考模式”会带来大量延迟，因此在本地使用时，如果速度重要，通常更适合关闭思考模式。

除了性能，还需考虑实际运维层面。本地运行模型意味着您需要自行管理模型服务器、处理 GPU 设置并应对基础设施问题。当 RunPod 或 Vast.ai 等 GPU 租赁平台供给有限时（随着需求增长，这种情况更常见），难度也会增加。

因此，在许多场景下，托管 API 可能是更佳选择。您可能会牺牲一些隐私与控制权，但能获得更好的速度、更少的维护，以及在处理更大或更复杂的编码任务时更顺畅的体验。如果成本只是每月几美元，与自行全权管理相比，这样的权衡往往是值得的。

所以，如果您的目标是实验、学习，或运行较轻量的本地任务，那么本地运行 GLM 5.1 是个不错的选择。但若目标是在规模化层面进行可靠的 Agentic 编码，那么托管服务往往更为务实。更多详细对比，建议参阅我们的 GLM-5 vs GPT-5.3-Codex 指南。