1. [主页](/)
2. [查看所有手册](https://developer.nvidia.cn/build-spark)
3. 

在 DGX Spark 上使用 llama.cpp 运行模型

# 在 DGX Spark 上使用 llama.cpp 运行模型

基于 CUDA 编译构建 llama.cpp，并通过兼容 OpenAI 接口规范的 API 部署模型服务

概述

操作指令

故障排除

## 基本理念

[llama.cpp](https://github.com/ggml-org/llama.cpp) 是适用于大语言模型的轻量级 C/ C++ 推理堆栈。使用 CUDA 构建模型，以便充分利用 DGX Spark GB10 GPU，然后加载 GGUF 权重并公开聊天llama-server 兼容 OpenAI 的 HTTP API。  
  
本练习本使用支持 MTP 的 Qwen3.6-35B-A3B 作为实战示例，端到端介绍该堆栈。以下矩阵总结了所有受支持模型的检查点选择和路径；指令中包含命令。

## 您将完成的任务

您将使用 CUDA 为 GB10 构建 llama.cpp，下载 Qwen3.6-35B-A3B Checkpoint，然后运行 llama-server GPU 卸载。您将获得：

- 

通过 llama.cpp 进行本地推理 (无需单独的 Python 推理框架)

- 

兼容 OpenAI /v1/chat/completions 工具和应用端点

- 

具体验证了 Qwen3.6-35B-A3B 示例在支持 MTP 的 DGX Spark 上的此堆栈上运行。

## 开始之前需要了解的内容

- 

基本熟悉 Linux 命令行和终端命令

- 

了解 git 并使用 CMake 从源代码进行构建

- 

了解用于测试的 REST API 和 cURL 的基本知识

## 预备知识

硬件要求

- 

搭载 GB10 GPU 的 NVIDIA DGX Spark

- 

为所使用的模型和 KV-Cache 提供足够的统一内存 (示例中的模型约 30GB 可用 RAM)

- 

至少约 40GB 的可用磁盘可用于示例下载，以及构建构件 (如果您保留多个 GGUF，则会增加)

软件要求

- 

NVIDIA DGX 操作系统

- 

Git： git --version

- 

CMake ( 3.14+) ： cmake --version

- 

CUDA 工具包： nvcc --version

- 

对 GitHub 和 Hugging Face 的网络访问

## 模型支持矩阵

DGX Spark 通过 llama.cpp 支持任何 GGUF 格式模型检查点，前提是系统具有可用于托管和运行检查点的内存。

## 时间和风险

- 

**预估时间** ：约 30 分钟，并下载示例 GGUF (默认量化约为 35GB 数量级)

- 

**风险级别** ：低 – 构建是在本地克隆；执行以下步骤无需进行系统级安装

- 

**回滚** ：删除 llama.cpp 克隆和模型目录 ~/.cache/huggingface/hub/ 来回收磁盘空间

- 

**上次更新时间** ：2026 年 6 月 3 日

  - 

演示现在使用 Qwen3.6-35B-A3B 作为示例

## 第 1 步：安装依赖项

更新软件包并安装所需的依赖项：

    sudo apt update sudo apt install -y git clang cmake libcurl4-openssl-dev libssl-dev

## 第 2 步：克隆 llama.cpp 资源库

克隆 llama.cpp – 您正在构建的框架：

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

## 第 3 步：使用 CUDA 构建 llama.cpp

使用 CUDA 和 GB10 的 sm\_121 架构配置 CMake，使 GGML 的 CUDA 后端与您的 GPU 相匹配：

    cmake -B build -DGGML\_NATIVE=ON -DGGML\_CUDA=ON -DGGML\_CURL=ON -DGGML\_RPC=ON -DCMAKE\_CUDA\_ARCHITECTURES=121a-real cmake --build build --config Release --target llama-server -j

构建通常需要 5 到 10 分钟。完成后，llama-server 出现在 build/bin/。

## 第 4 步：使用模型启动 llama-server

llama.cpp 以 GGUF 格式加载模型。本手册使用 unsloth/Qwen3.6-35B-A3B-MTP-GGUF 在 DGX Spark 上实现质量和速度的良好平衡。  
  
从您的 llama.cpp/build 启动 GPU 卸载的 OpenAI 兼容服务器。如果之前未下载模型或模型有任何更新，它会首先从 HuggingFace 加载模型。  
  
所有模型均保存在默认 HuggingFace 缓存目录中:～/.cache/huggingface/hub 。例如，此模型将保存到～/.cache/huggingface/hub/models--unsloth--Qwen3.6-35B-A3B-MTP-GGUF  
  
它还会自动加载 mmproj 文件，以便在模型支持的情况下启用视觉功能。默认情况下，llama-server 将尝试适应完整的模型上下文，并可同时处理 4 个并发请求，必要时 会自动调整参数。

    ./bin/llama-server \ -hf unsloth/Qwen3.6-35B-A3B-MTP-GGUF:UD-Q4\_K\_XL \ --host 0.0.0.0 \ --port 30000

要使用 MTP 预测解码运行，请使用 以下示例中所示的其他参数。MTP 需要兼容的模型，例如此示例中使用的 unsloth/Qwen3.6-35B-A3B-MTP-GGUF 。以下示例还设置了“preserve\_thinking”标志，允许 Qwen 模型保留历史思考块，用于代理式工作流中的“交错思考” 。

    ./bin/llama-server \ -hf unsloth/Qwen3.6-35B-A3B-MTP-GGUF:UD-Q4\_K\_XL \ --host 0.0.0.0 \ --port 30000 \ --chat-template-kwargs '{"preserve\_thinking": true}' \ --spec-type draft-mtp \ --spec-draft-n-max 3

参数 (简称)：

- 

--host / --port ：HTTP API 的绑定地址和端口

- 

--chat-template-kwargs ：为 JSON 模板解析器设置其他参数，必须是有效的 JSON 对象字符串

- 

--spec-type ：要使用的预测解码类型的逗号分隔列表 (默认：无，大多数兼容 MTP 的模型将使用“draft-mtp”，但您需要先查看模型卡)

- 

--spec-draft-n-max ：用于预测解码的起草令牌数量 (默认值：3)

您应看到类似于以下内容的日志行：

    0.14.322.968 I srv load\_model: speculative decoding context initialized 0.14.322.970 I slot load\_model: id 0 | task -1 | new slot, n\_ctx = 262144 0.14.322.972 I slot load\_model: id 1 | task -1 | new slot, n\_ctx = 262144 0.14.322.972 I slot load\_model: id 2 | task -1 | new slot, n\_ctx = 262144 0.14.322.973 I slot load\_model: id 3 | task -1 | new slot, n\_ctx = 262144 0.14.323.063 I srv load\_model: prompt cache is enabled, size limit: 8192 MiB ... 0.14.342.935 I srv llama\_server: model loaded 0.14.342.939 I srv llama\_server: server is listening on http://0.0.0.0:30000 0.14.342.944 I srv update\_slots: all slots are idle

在测试时 **保持此终端的打开状态** 。大型 GGUF 的加载可能需要一分钟或更长时间，如果尚未下载模型，则初始模型的下载可能需要一段时间。下载模型时，您将看到一个进度条。  
  
只有在您看到 30000 端口后，服务器才准备好接受传入连接 server is listening 消息 (请参阅故障排除 curl 报告连接被拒绝) 。

## 第 5 步：测试 API

在发送请求前，请确认服务器已准备就绪 (大型模型可能需要几分钟才能加载)：

    timeout 900 bash -c 'until curl -sf http://127.0.0.1:30000/health \> /dev/null 2\>&1; do sleep 5; done' || exit 1

    curl -X POST http://127.0.0.1:30000/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "unsloth/Qwen3.6-35B-A3B-MTP-GGUF:UD-Q4\_K\_XL", "messages": [{"role": "user", "content": "New York is a great city because..."}], "max\_tokens": 100 }'

如果您看到 curl: (7) Failed to connect ，服务器仍在加载，进程已退出 (检查服务器日志是否存在 OOM 或路径错误)，或者您未发送到运行 llama-server 的主机。  
  
响应的示例形状 (字段因 llama.cpp 版本而异； message 可能包括额外的密钥)：

    { "choices": [{ "finish\_reason": "length", "index": 0, "message": { "role": "assistant", "content": "New York is a great city because it's a living, breathing collage of cultures, ideas, and possibilities—all stacked into one vibrant, never‑sleeping metropolis. Here are just a few reasons that many people (" } }], "created": 1765916539, "model": "$MODEL\_PATH", "object": "chat.completion", "usage": { "completion\_tokens": 100, "prompt\_tokens": 25, "total\_tokens": 125 }, "id": "chatcmpl-...", "timings": { ... } }

## 第 6 步：完成时间较长 (使用 Qwen3.6-35B-A3B)

尝试使用稍长的提示词确认使用 Qwen3.6-35B-A3B 是否稳定生成：

    curl -X POST http://127.0.0.1:30000/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "unsloth/Qwen3.6-35B-A3B-MTP-GGUF:UD-Q4\_K\_XL", "messages": [{"role": "user", "content": "Solve this step by step: If a train travels 120 miles in 2 hours, what is its average speed?"}], "max\_tokens": 500 }'

## 第 7 步：清理

要停止服务器，请在终端中按 Ctrl+C。  
  
要删除本教程的伪影，请执行以下操作：

    rm -rf ~/llama.cpp rm -rf ~/.cache/huggingface/hub/models--unsloth--Qwen3.6-35B-A3B-MTP-GGUF

## 第 8 步：后续步骤

- 

**上下文长度** ：默认情况下，llama.cpp 会尝试分配模型支持的最大上下文大小 (如果可能)，但您也可以使用 --ctx-size (或 -c) 根据需要进行调整。对于代理式或编码需求，您至少需要 32768 个令牌，最好是 100000 个或更多。

- 

**其他模型** ：您可以使用 --model 加载本地下载的任何兼容的 GGUF；llama.cpp 服务器 API 保持不变。使用 -hf 让 llama.cpp 自动管理下载/更新。请注意，如果您使用 --model 使用多模态模型时，您需要使用 --mmproj 参数。如果您使用 -hf 它会自动加载 mmproj 文件。

- 

**集成** ：指向 Open WebUI、Continue.dev 或自定义客户端 http://:30000/v1 使用 OpenAI 客户端模式。

服务器将实现您的 llama.cpp 构建启用的常见 OpenAI 式聊天功能 (包括流式传输和工具相关流 (如果支持))。

| 症状 | 原因 | 修复 |
| --- | --- | --- |
| cmake 失败并显示“未找到 CUDA” | CUDA 工具包不在 PATH 中 | 运行 export PATH=/usr/local/cuda/bin:$PATH 并从干净的构建目录重新运行 CMake |
| 构建错误，其中提及错误的 GPU arch | CMake CMAKE\_CUDA\_ARCHITECTURES 不匹配 GB10 | 使用 -DCMAKE\_CUDA\_ARCHITECTURES="121" 适用于 DGX Spark GB10 |
| GGUF 下载失败或停止 | 网络或 Hugging Face 可用性 | 重新运行 hf download；它会恢复部分文件 |
| 启动时“CUDA 显存不足” llama-server | 对于当前上下文或 VRAM 而言，模型过大 | 降低 --ctx-size (例如 4096) 或使用同一存储库中更小的量化 |
| 服务器运行，但延迟较高 | GPU 之外的层 | 确认 --n-gpu-layers 对模型来说足够高；检查 nvidia-smi 请求期间 |
| curl: (7) Failed to connect 端口数量：30000 | 尚未侦听、主机错误或崩溃 | 等待 server is listening ；运行 curl 在与主机相同的主机上 llama-server (或 Spark 的 IP) ；运行 ss -tln 并确认 :30000 ；读取服务器 stderr 以检测 OOM 或损坏 --model 路径 |
| 聊天 API 错误或空回复 | 错误 --model 路径或不兼容的 GGUF | 验证路径 .gguf 文件；如果 GGUF 需要更新的格式，请更新 llama.cpp |

**注意：**

DGX Spark 采用统一内存架构 (UMA)，可在 GPU 和 CPU 内存之间实现灵活共享。一些软件仍在追踪 UMA 的行为。如果意外遇到内存压力，您可以尝试刷新页面缓存 (在共享系统上谨慎使用)：

    sudo sh -c 'sync; echo 3 \> /proc/sys/vm/drop\_caches'

有关最新的平台问题，请参阅 [DGX Spark 已知问题](https://docs.nvidia.com/dgx/dgx-spark/known-issues.html)文档。