{"repo": "amd/playbooks", "files": {"auto-translations/zh-CN/supplemental/deepseek-v4-flash-ds4/README.md": {"2c91fd969a341f9f82591458a50acd1791738b33": {"t": 1785747257.252161, "n": 12125, "h": "1f42a56f6201fc00", "c": "<!--\nCopyright Advanced Micro Devices, Inc.\n\nSPDX-License-Identifier: MIT\n-->\n\n<!-- auto-translated-disclaimer v1 -->\n> [!WARNING]\n> **机器翻译。**本页面由英文自动翻译而成,尚未经过人工审核。其中可能存在错误,部分步骤、命令、下载内容或产品的可用性在您所在的语言或地区可能有所不同。如发现任何问题,请以英文原版 playbook 为准。\n<!-- auto-translated-disclaimer:end -->\n\n<!-- @github-only -->\n> [!IMPORTANT]\n> 本行动手册使用了 GitHub 无法渲染的特殊标签。请访问 [amd.com/playbooks](https://amd.com/playbooks) 以正确预览此内容。\n<!-- @github-only:end -->\n\n## 概述\n\n[DeepSeek V4 Flash](https://huggingface.co/deepseek-ai/DeepSeek-V4-Flash) 是 DeepSeek V4 系列中专注于效率的变体——一个拥有 2840 亿参数的混合专家（Mixture of Experts）模型，激活参数为 130 亿。根据[DeepSeek 的技术报告](https://huggingface.co/deepseek-ai/DeepSeek-V4-Flash)，该模型在 SWE-bench Verified 上得分 79%，在 LiveCodeBench 上得分 91.6%。\n\n[ds4 (Dwarf Star 4)](https://github.com/antirez/ds4) 是专门为该模型架构构建的专用推理引擎。与通用运行时不同，ds4 直接针对 DeepSeek V4 系列，为 AMD ROCm™ 软件提供架构特定的内核优化。目前，它是 Strix Halo 上性能最佳的 DeepSeek V4 Flash 实现之一。\n\n本教程展示了如何使用 `ds4-cockpit`（一款终端 UI）来设置 ds4、下载模型权重，并在 AMD Ryzen™ AI Halo 开发者平台上本地启动 DeepSeek V4 Flash 服务。\n\n## 您将学到什么\n\n- 如何安装并启动 `ds4-cockpit` 终端 UI\n- 如何创建 ds4 ROCm 工具箱容器\n- 为单个 Halo 节点下载推荐的量化版本\n- 启动 ds4 推理服务器并公开与 OpenAI 兼容的端点\n- 将 Web UI 或编码代理连接到本地服务器\n\n## 设置内存配置\n\n<!-- @require:memory-config -->\n\n## 安装软件先决条件\n\n> **本配置的系统要求（单节点 IQ2_XXS，126k 上下文）：**\n> - 一台**至少配备 128 GB 统一内存**的 Strix Halo 系统。\n> - **BIOS 专用 VRAM（UMA 帧缓冲区）设置为最低值**，以便共享内存池尽可能大。\n> - GPU **共享内存池至少设置为 110 GB**：运行 `amd-ttm --set 110`（参见上面的内存配置步骤）并重启。如果模型在 126k 上下文下加载时数值过低，可能会导致内存不足。如果您的系统可用内存较少，请改为在服务器模式中降低**上下文（Context）**值。\n>\n> **注意：** 尝试将**GPU 共享内存池**设置为 **110 GB** 作为起始值。如果遇到内存不足错误，请增加共享内存池或降低上下文大小。\n\nds4-cockpit 使用容器工具箱来运行 ds4 引擎。请安装 `podman`、`distrobox` 和 `pipx`：\n\n```bash\nsudo apt update\nsudo apt install -y podman distrobox pipx\n```\n\n<!-- @test:id=ds4-prereqs-linux timeout=60 hidden=True -->\n```bash\nset -euo pipefail\nexport PATH=\"$HOME/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:$PATH\"\npodman --version\ndistrobox version 2>/dev/null || distrobox --version\npipx --version\necho \"OK: podman, distrobox, and pipx are installed\"\n```\n<!-- @test:end -->\n\n## 可用的量化版本\n\nds4 的作者提供了多个采用 GGUF 格式的 DeepSeek V4 Flash 量化版本。以下所有模型都使用了重要性矩阵（imatrix）校准，该方法可为模型中对编码和推理任务最重要的部分保留更高的精度。\n\n| 量化版本 | 大小 | 说明 |\n|-------------|------|-------------|\n| [IQ2_XXS imatrix](https://huggingface.co/antirez/deepseek-v4-gguf) | ~80.8 GB | 推荐用于单个 128 GB 节点 |\n| [Hybrid Q2/Q4 imatrix](https://huggingface.co/antirez/deepseek-v4-gguf) | ~97 GB | 第 37–42 层保持 Q4 精度以获得更好的准确性。可容纳于 128 GB，但为上下文留出的空间较少 |\n| [Q4 imatrix](https://huggingface.co/antirez/deepseek-v4-gguf) | ~153 GB | 更高质量。需要通过多节点集群使用两个 Halo 节点 |\n| [MTP Speculative Decoding](https://huggingface.co/antirez/deepseek-v4-gguf) | ~3.6 GB | 用于推测解码的可选附加组件，以提升生成速度 |\n\n**IQ2_XXS imatrix** 模型是一个不错的起点。它可以轻松容纳在单个节点中，并为合理的上下文窗口留出了足够的内存。\n\n## 安装 ds4-cockpit\n\n[ds4-cockpit](https://github.com/kyuz0/strix-halo-ds4-toolbox) 是一款轻量级终端 UI，可让您轻松在 Strix Halo 上运行 ds4。它负责创建工具箱容器、下载模型权重以及启动服务器。使用 `pipx` 安装：\n\n```bash\npipx install \"git+https://github.com/kyuz0/strix-halo-ds4-toolbox.git#subdirectory=ds4-strix-halo-cockpit\"\n```\n\n启动 cockpit：\n```bash\nds4-cockpit\n```\n\n<!-- @test:id=ds4-cockpit-linux timeout=60 hidden=True -->\n```bash\nset -euo pipefail\nexport PATH=\"$HOME/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:$PATH\"\n# Verify the pipx-installed cockpit entry point is on PATH (do NOT launch the TUI).\ncommand -v ds4-cockpit\necho \"OK: ds4-cockpit is installed and on PATH\"\n```\n<!-- @test:end -->\n\n## 创建工具箱\n\n在**交互式工具箱（Interactive Toolboxes）**选项卡中，选择最新的可用/稳定工具箱（例如 `ds4-rocm-7.2.4`），然后点击**创建/更新（Create/Update）**。这将拉取容器镜像并创建工具箱环境。\n\n\n<p align=\"center\">\n  <img src=\"assets/ds4-cockpit-toolboxes.png\" alt=\"Selecting the ds4 toolbox in ds4-cockpit\" width=\"800\"/>\n</p>\n\n<!-- @test:id=ds4-toolbox-image-linux timeout=120 hidden=True -->\n```bash\nset -euo pipefail\nexport PATH=\"$HOME/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:$PATH\"\n\n# The toolbox version changes over time, so match the image family, not a fixed tag.\nif ! podman images --format '{{.Repository}}:{{.Tag}}' | grep -i 'strix-halo-ds4-toolbox'; then\n  echo \"No strix-halo-ds4-toolbox image found. Create the toolbox in ds4-cockpit (Interactive Toolboxes tab) first.\"\n  exit 1\nfi\necho \"OK: ds4 toolbox container image is present\"\n```\n<!-- @test:end -->\n\n## 下载模型\n\n前往**模型管理器（Model Manager）**选项卡。从下拉菜单中选择 **IQ2_XXS imatrix (~80.8 GB)**，然后点击**下载（Download）**。模型文件默认将保存到 `~/ds4`（您可以更改存储路径）。\n\n> **注意：** IQ2_XXS 模型大小约为 80 GB，因此根据您的网络连接情况，下载可能需要一段时间。下载完成后即可继续操作。\n\n<p align=\"center\">\n  <img src=\"assets/ds4-cockpit-model-manager.png\" alt=\"Selecting and downloading the IQ2_XXS model\" width=\"800\"/>\n</p>\n\n<!-- @test:id=ds4-model-downloaded-linux timeout=60 hidden=True -->\n```bash\nset -euo pipefail\n\n# ds4-cockpit saves model weights to ~/ds4 by default\nmodel_dir=\"$HOME/ds4\"\n\nif [ ! -d \"$model_dir\" ]; then\n  echo \"Model directory $model_dir does not exist. Download the model in ds4-cockpit (Model Manager tab) first.\"\n  exit 1\nfi\n\nif ! find \"$model_dir\" -maxdepth 2 -iname '*.gguf' | grep -q .; then\n  echo \"No .gguf model files found under $model_dir. Download the IQ2_XXS imatrix model in ds4-cockpit first.\"\n  exit 1\nfi\n\n# Prefer to confirm the recommended IQ2_XXS imatrix quantization is present.\nif find \"$model_dir\" -maxdepth 2 -iname '*IQ2*imatrix*.gguf' | grep -q .; then\n  echo \"OK: IQ2_XXS imatrix model is downloaded\"\nelse\n  echo \"OK: a GGUF model is present (recommended IQ2_XXS imatrix file not detected by name)\"\nfi\n```\n<!-- @test:end -->\n\n## 启动服务器\n\n前往**服务器模式（Server Mode）**选项卡。选择已下载的模型和工具箱，然后配置上下文大小、主机和端口。准备就绪后，点击**启动 ds4-server（Start ds4-server）**。\n\n> **提示** `126000` 的上下文大小是一个合理的起始值，应该能够容纳在单个节点中——如果您有多余的内存，可以将其设置得更高；如果遇到内存不足错误，则可以降低该值。本指南中的端口（`8000`）是随意选定的；您可以选择任何空闲端口。\n\n> **KV 磁盘缓存（可选）。** 开启 **KV Disk Cache** 会将 KV 缓存卸载到磁盘（位于**主机缓存目录（Host Cache Dir）**，默认为 `~/.cache/ds4-kv`），这样重复的系统提示词就可以从 SSD 中恢复，而无需重新计算。这是针对具有长而重复提示词的编码代理工作流的一项性能优化，**并非**运行服务器所必需的。\n\n<p align=\"center\">\n  <img src=\"assets/ds4-cockpit-server-mode.png\" alt=\"Configuring and starting the ds4 server\" width=\"800\"/>\n</p>\n\n服务器将启动并监听 8000 端口，在 `http://localhost:8000/v1` 公开一个与 OpenAI 兼容的 API 端点。\n\n**快速测试：**\n```bash\ncurl http://127.0.0.1:8000/v1/chat/completions \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"model\": \"deepseek-v4-flash\",\n    \"messages\": [{\"role\": \"user\", \"content\": \"Hello!\"}],\n    \"stream\": false\n  }'\n```\n\n<!-- @test:id=ds4-server-chat-linux timeout=1200 hidden=True -->\n```bash\nset -euo pipefail\n\n# This runner is shared with other playbooks, and ds4 at a 126k context consumes almost the entire GPU memory pool.\n# So rather than keeping ds4 resident, CI starts the server, verifies a chat completion, then stops it again.\n# This frees the memory for the next job.\n# ds4 has no separate \"unload\"; stopping the server process is what releases the ~80 GB model.\n\nCONTAINER=\"ds4-ci-server\"\nMODEL_DIR=\"$HOME/ds4\"\n\n# Locate the downloaded model (prefer the recommended IQ2_XXS imatrix file).\nmodel_file=\"$(find \"$MODEL_DIR\" -maxdepth 2 -iname '*IQ2*imatrix*.gguf' 2>/dev/null | head -1)\"\nif [ -z \"$model_file\" ]; then\n  model_file=\"$(find \"$MODEL_DIR\" -maxdepth 2 -iname '*.gguf' 2>/dev/null | head -1)\"\nfi\nif [ -z \"$model_file\" ]; then\n  echo \"No .gguf model found under $MODEL_DIR. Download it in ds4-cockpit first.\"\n  exit 1\nfi\nmodel_name=\"$(basename \"$model_file\")\"\n\n# Pick the toolbox image (version-agnostic).\nimage=\"$(podman images --format '{{.Repository}}:{{.Tag}}' | grep -i 'strix-halo-ds4-toolbox' | head -1)\"\nif [ -z \"$image\" ]; then\n  echo \"No strix-halo-ds4-toolbox image found. Create the toolbox in ds4-cockpit first.\"\n  exit 1\nfi\n\n# Always stop/remove the server on exit so it never holds GPU memory afterwards.\ncleanup() {\n  podman stop -t 10 \"$CONTAINER\" >/dev/null 2>&1 || true\n  podman rm -f \"$CONTAINER\" >/dev/null 2>&1 || true\n}\ntrap cleanup EXIT\n\n# Remove any stale instance, then start ds4-server detached (same flags ds4-cockpit uses, with -d instead of -it).\npodman rm -f \"$CONTAINER\" >/dev/null 2>&1 || true\npodman run -d --name \"$CONTAINER\" \\\n  --device /dev/dri --device /dev/kfd \\\n  --group-add keep-groups \\\n  --security-opt seccomp=unconfined \\\n  --ipc=host \\\n  --cap-add=SYS_PTRACE \\\n  --security-opt label=disable \\\n  --userns=keep-id \\\n  -p 127.0.0.1:8000:8000 \\\n  -v \"$MODEL_DIR\":/models:ro \\\n  \"$image\" \\\n  ds4-server -m \"/models/$model_name\" --ctx 126000 --host 0.0.0.0 --port 8000\n\n# Wait for readiness; the ~80 GB model can take a few minutes to load.\nup=false\nfor i in $(seq 1 240); do\n  code=\"$(curl -s -o /dev/null -w '%{http_code}' --max-time 3 http://127.0.0.1:8000/v1/models || true)\"\n  if [ -n \"$code\" ] && [ \"$code\" != \"000\" ]; then\n    up=true\n    break\n  fi\n  if ! podman inspect -f '{{.State.Running}}' \"$CONTAINER\" 2>/dev/null | grep -q true; then\n    echo \"ds4-server container exited during startup:\"\n    podman logs \"$CONTAINER\" 2>&1 | tail -40 || true\n    exit 1\n  fi\n  sleep 2\ndone\n\nif [ \"$up\" != \"true\" ]; then\n  echo \"ds4 server did not become ready on http://127.0.0.1:8000\"\n  podman logs \"$CONTAINER\" 2>&1 | tail -40 || true\n  exit 1\nfi\necho \"OK: ds4 server is responding on :8000\"\n\nbody='{\n  \"model\": \"deepseek-v4-flash\",\n  \"messages\": [{\"role\": \"user\", \"content\": \"Reply with exactly: OK\"}],\n  \"temperature\": 0,\n  \"max_tokens\": 32,\n  \"stream\": false\n}'\n\nout=\"$(curl -sS --fail-with-body --max-time 300 http://127.0.0.1:8000/v1/chat/completions \\\n  -H 'Content-Type: application/json' \\\n  -d \"$body\")\"\n\nif [ -z \"$out\" ]; then\n  echo \"Empty response from ds4 /v1/chat/completions\"\n  exit 1\nfi\n\nexport DS4_OUT=\"$out\"\npython3 - <<'PY'\nimport json, os, sys\n\ndata = json.loads(os.environ[\"DS4_OUT\"])\nchoices = data.get(\"choices\")\nif not choices:\n    print(\"Response has no 'choices':\")\n    print(json.dumps(data, indent=2)[:2000])\n    sys.exit(1)\n\nmessage = choices[0].get(\"message\", {}) or {}\ncontent = message.get(\"content\") or message.get(\"reasoning_content\")\nif not content:\n    print(\"Response choice has empty content:\")\n    print(json.dumps(data, indent=2)[:2000])\n    sys.exit(1)\n\nprint(\"OK: ds4 chat/completions returned content\")\nPY\n\necho \"OK: ds4 server test complete; server stopped and GPU memory released\"\n```\n<!-- @test:end -->\n\n## 连接 Web UI\n\n您可以连接任何支持 OpenAI API 格式的聊天界面。例如，使用 HuggingFace ChatUI：\n\n```bash\ndocker run -p 3000:3000 \\\n  --add-host=host.docker.internal:host-gateway \\\n  -e OPENAI_BASE_URL=http://host.docker.internal:8000/v1 \\\n  -e OPENAI_API_KEY=dummy \\\n  -v chat-ui-data:/data \\\n  ghcr.io/huggingface/chat-ui-db\n```\n\n在浏览器中打开 `http://localhost:3000` 即可开始聊天。\n## 连接编码代理\n\nds4 服务器同时暴露了兼容 OpenAI 和 Anthropic 的端点，因此大多数编码代理都可以直接连接到它。例如，要将其添加到 `pi` 编码代理中，请将以下代码块添加到 `~/.pi/agent/models.json`：\n\n```json\n\"ds4\": {\n  \"name\": \"ds4.c local\",\n  \"baseUrl\": \"http://localhost:8000/v1\",\n  \"api\": \"openai-completions\",\n  \"apiKey\": \"dsv4-local\",\n  \"compat\": {\n    \"supportsStore\": false,\n    \"supportsDeveloperRole\": false,\n    \"supportsReasoningEffort\": true,\n    \"supportsUsageInStreaming\": true,\n    \"maxTokensField\": \"max_tokens\",\n    \"supportsStrictMode\": false,\n    \"thinkingFormat\": \"deepseek\",\n    \"requiresReasoningContentOnAssistantMessages\": true\n  },\n  \"models\": [\n    {\n      \"id\": \"deepseek-v4-flash\",\n      \"name\": \"DeepSeek V4 Flash (ds4.c local)\",\n      \"reasoning\": true,\n      \"thinkingLevelMap\": {\n        \"off\": null,\n        \"minimal\": \"low\",\n        \"low\": \"low\",\n        \"medium\": \"medium\",\n        \"high\": \"high\",\n        \"xhigh\": \"xhigh\"\n      },\n      \"input\": [\"text\"],\n      \"contextWindow\": 131072,\n      \"maxTokens\": 65536,\n      \"cost\": { \"input\": 0, \"output\": 0, \"cacheRead\": 0, \"cacheWrite\": 0 }\n    }\n  ]\n}\n```\n\n> **提示**：如果您的编码代理或 Web UI 运行在与 Halo 平台不同的机器上，您需要通过 SSH 转发 8000 端口：\n> ```bash\n> ssh -L 0.0.0.0:8000:localhost:8000 <halo-host-ip>\n> ```\n\n## 后续步骤\n\n- **多节点集群**：如果您拥有两台 Halo 设备，ds4 支持通过流水线并行将 Q4 模型（约 153 GB）分布到两台机器上。有关设置说明，请参阅 [ds4-toolbox 文档](https://github.com/kyuz0/strix-halo-ds4-toolbox#distributed-inference-pipeline-parallelism)。\n- **推测解码（MTP）**：下载 MTP 权重（约 3.6 GB），并向服务器传递 `--mtp` 参数以获得更快的生成速度。\n- **KV 缓存磁盘卸载**：对于编码代理工作流，启用 `--kv-disk-dir`，这样重复的系统提示词可以从 SSD 中恢复，而无需每次都重新计算。\n\n更多信息，请参阅 [ds4 仓库](https://github.com/antirez/ds4) 和 [ds4-cockpit 工具箱](https://github.com/kyuz0/strix-halo-ds4-toolbox)。"}, "67e50b3269457cc2cd7f06e97fee2c834080e0b9": {"t": 1785771884.8442063, "n": 12125, "h": "1f42a56f6201fc00", "c": "<!--\nCopyright Advanced Micro Devices, Inc.\n\nSPDX-License-Identifier: MIT\n-->\n\n<!-- auto-translated-disclaimer v1 -->\n> [!WARNING]\n> **机器翻译。**本页面由英文自动翻译而成,尚未经过人工审核。其中可能存在错误,部分步骤、命令、下载内容或产品的可用性在您所在的语言或地区可能有所不同。如发现任何问题,请以英文原版 playbook 为准。\n<!-- auto-translated-disclaimer:end -->\n\n<!-- @github-only -->\n> [!IMPORTANT]\n> 本行动手册使用了 GitHub 无法渲染的特殊标签。请访问 [amd.com/playbooks](https://amd.com/playbooks) 以正确预览此内容。\n<!-- @github-only:end -->\n\n## 概述\n\n[DeepSeek V4 Flash](https://huggingface.co/deepseek-ai/DeepSeek-V4-Flash) 是 DeepSeek V4 系列中专注于效率的变体——一个拥有 2840 亿参数的混合专家（Mixture of Experts）模型，激活参数为 130 亿。根据[DeepSeek 的技术报告](https://huggingface.co/deepseek-ai/DeepSeek-V4-Flash)，该模型在 SWE-bench Verified 上得分 79%，在 LiveCodeBench 上得分 91.6%。\n\n[ds4 (Dwarf Star 4)](https://github.com/antirez/ds4) 是专门为该模型架构构建的专用推理引擎。与通用运行时不同，ds4 直接针对 DeepSeek V4 系列，为 AMD ROCm™ 软件提供架构特定的内核优化。目前，它是 Strix Halo 上性能最佳的 DeepSeek V4 Flash 实现之一。\n\n本教程展示了如何使用 `ds4-cockpit`（一款终端 UI）来设置 ds4、下载模型权重，并在 AMD Ryzen™ AI Halo 开发者平台上本地启动 DeepSeek V4 Flash 服务。\n\n## 您将学到什么\n\n- 如何安装并启动 `ds4-cockpit` 终端 UI\n- 如何创建 ds4 ROCm 工具箱容器\n- 为单个 Halo 节点下载推荐的量化版本\n- 启动 ds4 推理服务器并公开与 OpenAI 兼容的端点\n- 将 Web UI 或编码代理连接到本地服务器\n\n## 设置内存配置\n\n<!-- @require:memory-config -->\n\n## 安装软件先决条件\n\n> **本配置的系统要求（单节点 IQ2_XXS，126k 上下文）：**\n> - 一台**至少配备 128 GB 统一内存**的 Strix Halo 系统。\n> - **BIOS 专用 VRAM（UMA 帧缓冲区）设置为最低值**，以便共享内存池尽可能大。\n> - GPU **共享内存池至少设置为 110 GB**：运行 `amd-ttm --set 110`（参见上面的内存配置步骤）并重启。如果模型在 126k 上下文下加载时数值过低，可能会导致内存不足。如果您的系统可用内存较少，请改为在服务器模式中降低**上下文（Context）**值。\n>\n> **注意：** 尝试将**GPU 共享内存池**设置为 **110 GB** 作为起始值。如果遇到内存不足错误，请增加共享内存池或降低上下文大小。\n\nds4-cockpit 使用容器工具箱来运行 ds4 引擎。请安装 `podman`、`distrobox` 和 `pipx`：\n\n```bash\nsudo apt update\nsudo apt install -y podman distrobox pipx\n```\n\n<!-- @test:id=ds4-prereqs-linux timeout=60 hidden=True -->\n```bash\nset -euo pipefail\nexport PATH=\"$HOME/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:$PATH\"\npodman --version\ndistrobox version 2>/dev/null || distrobox --version\npipx --version\necho \"OK: podman, distrobox, and pipx are installed\"\n```\n<!-- @test:end -->\n\n## 可用的量化版本\n\nds4 的作者提供了多个采用 GGUF 格式的 DeepSeek V4 Flash 量化版本。以下所有模型都使用了重要性矩阵（imatrix）校准，该方法可为模型中对编码和推理任务最重要的部分保留更高的精度。\n\n| 量化版本 | 大小 | 说明 |\n|-------------|------|-------------|\n| [IQ2_XXS imatrix](https://huggingface.co/antirez/deepseek-v4-gguf) | ~80.8 GB | 推荐用于单个 128 GB 节点 |\n| [Hybrid Q2/Q4 imatrix](https://huggingface.co/antirez/deepseek-v4-gguf) | ~97 GB | 第 37–42 层保持 Q4 精度以获得更好的准确性。可容纳于 128 GB，但为上下文留出的空间较少 |\n| [Q4 imatrix](https://huggingface.co/antirez/deepseek-v4-gguf) | ~153 GB | 更高质量。需要通过多节点集群使用两个 Halo 节点 |\n| [MTP Speculative Decoding](https://huggingface.co/antirez/deepseek-v4-gguf) | ~3.6 GB | 用于推测解码的可选附加组件，以提升生成速度 |\n\n**IQ2_XXS imatrix** 模型是一个不错的起点。它可以轻松容纳在单个节点中，并为合理的上下文窗口留出了足够的内存。\n\n## 安装 ds4-cockpit\n\n[ds4-cockpit](https://github.com/kyuz0/strix-halo-ds4-toolbox) 是一款轻量级终端 UI，可让您轻松在 Strix Halo 上运行 ds4。它负责创建工具箱容器、下载模型权重以及启动服务器。使用 `pipx` 安装：\n\n```bash\npipx install \"git+https://github.com/kyuz0/strix-halo-ds4-toolbox.git#subdirectory=ds4-strix-halo-cockpit\"\n```\n\n启动 cockpit：\n```bash\nds4-cockpit\n```\n\n<!-- @test:id=ds4-cockpit-linux timeout=60 hidden=True -->\n```bash\nset -euo pipefail\nexport PATH=\"$HOME/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:$PATH\"\n# Verify the pipx-installed cockpit entry point is on PATH (do NOT launch the TUI).\ncommand -v ds4-cockpit\necho \"OK: ds4-cockpit is installed and on PATH\"\n```\n<!-- @test:end -->\n\n## 创建工具箱\n\n在**交互式工具箱（Interactive Toolboxes）**选项卡中，选择最新的可用/稳定工具箱（例如 `ds4-rocm-7.2.4`），然后点击**创建/更新（Create/Update）**。这将拉取容器镜像并创建工具箱环境。\n\n\n<p align=\"center\">\n  <img src=\"assets/ds4-cockpit-toolboxes.png\" alt=\"Selecting the ds4 toolbox in ds4-cockpit\" width=\"800\"/>\n</p>\n\n<!-- @test:id=ds4-toolbox-image-linux timeout=120 hidden=True -->\n```bash\nset -euo pipefail\nexport PATH=\"$HOME/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:$PATH\"\n\n# The toolbox version changes over time, so match the image family, not a fixed tag.\nif ! podman images --format '{{.Repository}}:{{.Tag}}' | grep -i 'strix-halo-ds4-toolbox'; then\n  echo \"No strix-halo-ds4-toolbox image found. Create the toolbox in ds4-cockpit (Interactive Toolboxes tab) first.\"\n  exit 1\nfi\necho \"OK: ds4 toolbox container image is present\"\n```\n<!-- @test:end -->\n\n## 下载模型\n\n前往**模型管理器（Model Manager）**选项卡。从下拉菜单中选择 **IQ2_XXS imatrix (~80.8 GB)**，然后点击**下载（Download）**。模型文件默认将保存到 `~/ds4`（您可以更改存储路径）。\n\n> **注意：** IQ2_XXS 模型大小约为 80 GB，因此根据您的网络连接情况，下载可能需要一段时间。下载完成后即可继续操作。\n\n<p align=\"center\">\n  <img src=\"assets/ds4-cockpit-model-manager.png\" alt=\"Selecting and downloading the IQ2_XXS model\" width=\"800\"/>\n</p>\n\n<!-- @test:id=ds4-model-downloaded-linux timeout=60 hidden=True -->\n```bash\nset -euo pipefail\n\n# ds4-cockpit saves model weights to ~/ds4 by default\nmodel_dir=\"$HOME/ds4\"\n\nif [ ! -d \"$model_dir\" ]; then\n  echo \"Model directory $model_dir does not exist. Download the model in ds4-cockpit (Model Manager tab) first.\"\n  exit 1\nfi\n\nif ! find \"$model_dir\" -maxdepth 2 -iname '*.gguf' | grep -q .; then\n  echo \"No .gguf model files found under $model_dir. Download the IQ2_XXS imatrix model in ds4-cockpit first.\"\n  exit 1\nfi\n\n# Prefer to confirm the recommended IQ2_XXS imatrix quantization is present.\nif find \"$model_dir\" -maxdepth 2 -iname '*IQ2*imatrix*.gguf' | grep -q .; then\n  echo \"OK: IQ2_XXS imatrix model is downloaded\"\nelse\n  echo \"OK: a GGUF model is present (recommended IQ2_XXS imatrix file not detected by name)\"\nfi\n```\n<!-- @test:end -->\n\n## 启动服务器\n\n前往**服务器模式（Server Mode）**选项卡。选择已下载的模型和工具箱，然后配置上下文大小、主机和端口。准备就绪后，点击**启动 ds4-server（Start ds4-server）**。\n\n> **提示** `126000` 的上下文大小是一个合理的起始值，应该能够容纳在单个节点中——如果您有多余的内存，可以将其设置得更高；如果遇到内存不足错误，则可以降低该值。本指南中的端口（`8000`）是随意选定的；您可以选择任何空闲端口。\n\n> **KV 磁盘缓存（可选）。** 开启 **KV Disk Cache** 会将 KV 缓存卸载到磁盘（位于**主机缓存目录（Host Cache Dir）**，默认为 `~/.cache/ds4-kv`），这样重复的系统提示词就可以从 SSD 中恢复，而无需重新计算。这是针对具有长而重复提示词的编码代理工作流的一项性能优化，**并非**运行服务器所必需的。\n\n<p align=\"center\">\n  <img src=\"assets/ds4-cockpit-server-mode.png\" alt=\"Configuring and starting the ds4 server\" width=\"800\"/>\n</p>\n\n服务器将启动并监听 8000 端口，在 `http://localhost:8000/v1` 公开一个与 OpenAI 兼容的 API 端点。\n\n**快速测试：**\n```bash\ncurl http://127.0.0.1:8000/v1/chat/completions \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"model\": \"deepseek-v4-flash\",\n    \"messages\": [{\"role\": \"user\", \"content\": \"Hello!\"}],\n    \"stream\": false\n  }'\n```\n\n<!-- @test:id=ds4-server-chat-linux timeout=1200 hidden=True -->\n```bash\nset -euo pipefail\n\n# This runner is shared with other playbooks, and ds4 at a 126k context consumes almost the entire GPU memory pool.\n# So rather than keeping ds4 resident, CI starts the server, verifies a chat completion, then stops it again.\n# This frees the memory for the next job.\n# ds4 has no separate \"unload\"; stopping the server process is what releases the ~80 GB model.\n\nCONTAINER=\"ds4-ci-server\"\nMODEL_DIR=\"$HOME/ds4\"\n\n# Locate the downloaded model (prefer the recommended IQ2_XXS imatrix file).\nmodel_file=\"$(find \"$MODEL_DIR\" -maxdepth 2 -iname '*IQ2*imatrix*.gguf' 2>/dev/null | head -1)\"\nif [ -z \"$model_file\" ]; then\n  model_file=\"$(find \"$MODEL_DIR\" -maxdepth 2 -iname '*.gguf' 2>/dev/null | head -1)\"\nfi\nif [ -z \"$model_file\" ]; then\n  echo \"No .gguf model found under $MODEL_DIR. Download it in ds4-cockpit first.\"\n  exit 1\nfi\nmodel_name=\"$(basename \"$model_file\")\"\n\n# Pick the toolbox image (version-agnostic).\nimage=\"$(podman images --format '{{.Repository}}:{{.Tag}}' | grep -i 'strix-halo-ds4-toolbox' | head -1)\"\nif [ -z \"$image\" ]; then\n  echo \"No strix-halo-ds4-toolbox image found. Create the toolbox in ds4-cockpit first.\"\n  exit 1\nfi\n\n# Always stop/remove the server on exit so it never holds GPU memory afterwards.\ncleanup() {\n  podman stop -t 10 \"$CONTAINER\" >/dev/null 2>&1 || true\n  podman rm -f \"$CONTAINER\" >/dev/null 2>&1 || true\n}\ntrap cleanup EXIT\n\n# Remove any stale instance, then start ds4-server detached (same flags ds4-cockpit uses, with -d instead of -it).\npodman rm -f \"$CONTAINER\" >/dev/null 2>&1 || true\npodman run -d --name \"$CONTAINER\" \\\n  --device /dev/dri --device /dev/kfd \\\n  --group-add keep-groups \\\n  --security-opt seccomp=unconfined \\\n  --ipc=host \\\n  --cap-add=SYS_PTRACE \\\n  --security-opt label=disable \\\n  --userns=keep-id \\\n  -p 127.0.0.1:8000:8000 \\\n  -v \"$MODEL_DIR\":/models:ro \\\n  \"$image\" \\\n  ds4-server -m \"/models/$model_name\" --ctx 126000 --host 0.0.0.0 --port 8000\n\n# Wait for readiness; the ~80 GB model can take a few minutes to load.\nup=false\nfor i in $(seq 1 240); do\n  code=\"$(curl -s -o /dev/null -w '%{http_code}' --max-time 3 http://127.0.0.1:8000/v1/models || true)\"\n  if [ -n \"$code\" ] && [ \"$code\" != \"000\" ]; then\n    up=true\n    break\n  fi\n  if ! podman inspect -f '{{.State.Running}}' \"$CONTAINER\" 2>/dev/null | grep -q true; then\n    echo \"ds4-server container exited during startup:\"\n    podman logs \"$CONTAINER\" 2>&1 | tail -40 || true\n    exit 1\n  fi\n  sleep 2\ndone\n\nif [ \"$up\" != \"true\" ]; then\n  echo \"ds4 server did not become ready on http://127.0.0.1:8000\"\n  podman logs \"$CONTAINER\" 2>&1 | tail -40 || true\n  exit 1\nfi\necho \"OK: ds4 server is responding on :8000\"\n\nbody='{\n  \"model\": \"deepseek-v4-flash\",\n  \"messages\": [{\"role\": \"user\", \"content\": \"Reply with exactly: OK\"}],\n  \"temperature\": 0,\n  \"max_tokens\": 32,\n  \"stream\": false\n}'\n\nout=\"$(curl -sS --fail-with-body --max-time 300 http://127.0.0.1:8000/v1/chat/completions \\\n  -H 'Content-Type: application/json' \\\n  -d \"$body\")\"\n\nif [ -z \"$out\" ]; then\n  echo \"Empty response from ds4 /v1/chat/completions\"\n  exit 1\nfi\n\nexport DS4_OUT=\"$out\"\npython3 - <<'PY'\nimport json, os, sys\n\ndata = json.loads(os.environ[\"DS4_OUT\"])\nchoices = data.get(\"choices\")\nif not choices:\n    print(\"Response has no 'choices':\")\n    print(json.dumps(data, indent=2)[:2000])\n    sys.exit(1)\n\nmessage = choices[0].get(\"message\", {}) or {}\ncontent = message.get(\"content\") or message.get(\"reasoning_content\")\nif not content:\n    print(\"Response choice has empty content:\")\n    print(json.dumps(data, indent=2)[:2000])\n    sys.exit(1)\n\nprint(\"OK: ds4 chat/completions returned content\")\nPY\n\necho \"OK: ds4 server test complete; server stopped and GPU memory released\"\n```\n<!-- @test:end -->\n\n## 连接 Web UI\n\n您可以连接任何支持 OpenAI API 格式的聊天界面。例如，使用 HuggingFace ChatUI：\n\n```bash\ndocker run -p 3000:3000 \\\n  --add-host=host.docker.internal:host-gateway \\\n  -e OPENAI_BASE_URL=http://host.docker.internal:8000/v1 \\\n  -e OPENAI_API_KEY=dummy \\\n  -v chat-ui-data:/data \\\n  ghcr.io/huggingface/chat-ui-db\n```\n\n在浏览器中打开 `http://localhost:3000` 即可开始聊天。\n## 连接编码代理\n\nds4 服务器同时暴露了兼容 OpenAI 和 Anthropic 的端点，因此大多数编码代理都可以直接连接到它。例如，要将其添加到 `pi` 编码代理中，请将以下代码块添加到 `~/.pi/agent/models.json`：\n\n```json\n\"ds4\": {\n  \"name\": \"ds4.c local\",\n  \"baseUrl\": \"http://localhost:8000/v1\",\n  \"api\": \"openai-completions\",\n  \"apiKey\": \"dsv4-local\",\n  \"compat\": {\n    \"supportsStore\": false,\n    \"supportsDeveloperRole\": false,\n    \"supportsReasoningEffort\": true,\n    \"supportsUsageInStreaming\": true,\n    \"maxTokensField\": \"max_tokens\",\n    \"supportsStrictMode\": false,\n    \"thinkingFormat\": \"deepseek\",\n    \"requiresReasoningContentOnAssistantMessages\": true\n  },\n  \"models\": [\n    {\n      \"id\": \"deepseek-v4-flash\",\n      \"name\": \"DeepSeek V4 Flash (ds4.c local)\",\n      \"reasoning\": true,\n      \"thinkingLevelMap\": {\n        \"off\": null,\n        \"minimal\": \"low\",\n        \"low\": \"low\",\n        \"medium\": \"medium\",\n        \"high\": \"high\",\n        \"xhigh\": \"xhigh\"\n      },\n      \"input\": [\"text\"],\n      \"contextWindow\": 131072,\n      \"maxTokens\": 65536,\n      \"cost\": { \"input\": 0, \"output\": 0, \"cacheRead\": 0, \"cacheWrite\": 0 }\n    }\n  ]\n}\n```\n\n> **提示**：如果您的编码代理或 Web UI 运行在与 Halo 平台不同的机器上，您需要通过 SSH 转发 8000 端口：\n> ```bash\n> ssh -L 0.0.0.0:8000:localhost:8000 <halo-host-ip>\n> ```\n\n## 后续步骤\n\n- **多节点集群**：如果您拥有两台 Halo 设备，ds4 支持通过流水线并行将 Q4 模型（约 153 GB）分布到两台机器上。有关设置说明，请参阅 [ds4-toolbox 文档](https://github.com/kyuz0/strix-halo-ds4-toolbox#distributed-inference-pipeline-parallelism)。\n- **推测解码（MTP）**：下载 MTP 权重（约 3.6 GB），并向服务器传递 `--mtp` 参数以获得更快的生成速度。\n- **KV 缓存磁盘卸载**：对于编码代理工作流，启用 `--kv-disk-dir`，这样重复的系统提示词可以从 SSD 中恢复，而无需每次都重新计算。\n\n更多信息，请参阅 [ds4 仓库](https://github.com/antirez/ds4) 和 [ds4-cockpit 工具箱](https://github.com/kyuz0/strix-halo-ds4-toolbox)。"}}}}