提示：自 8 月 30 日起，已在主线上对 Atlas 进行 DFlash2 测试。:) https://github.com/Avarok-Cybersecurity/atlas-recipes/pull/173 …
https://github.com/Avarok-Cybersecurity/atlas/pull/817 …

Avarok-Cybersecurity/atlas-recipes

来源：https://github.com/Avarok-Cybersecurity/atlas-recipes

Atlas 配方与 atlasctl

Atlas 的配方（Recipes）适用于 NVIDIA DGX Spark (GB10) 的纯 Rust LLM 推理服务器（https://github.com/Avarok-Cybersecurity/atlas），以及运行它们的启动器 atlasctl。

配方描述了一次模型部署——包括检查点、容器镜像及其经过验证的服务设置。atlasctl 读取配方并运行其隐含的 docker run 命令。

安装

Linux 和 macOS：

curl -fsSL https://atlasinference.io/install.sh | sh

Windows（PowerShell 中）：

irm https://atlasinference.io/install.ps1 | iex

或者，如果您已有工具链：

cargo install atlasctl  # 来自 crates.io
uvx pyatlasctl list     # 来自 PyPI，无需安装步骤

安装程序会下载预构建二进制文件，根据发布版本验证其 SHA-256 值，并将其放入 ~/.local/bin（Windows 上为 %LOCALAPPDATA%\Programs\atlasctl）。它不需要 Python 或 Rust 工具链。在已有 atlasctl 的机器上再次运行它会进行升级，或者——当版本已是最新的——则可以启动一个已安装但停止的代理。

sh scripts/install.sh --uninstall 可将其卸载；在 Windows 上，atlasctl agent uninstall 会移除任务，然后可以从上述安装目录中删除二进制文件。

后台代理在 Linux 上是 systemd --user 服务，在 macOS 上是 launchd LaunchAgent，在 Windows 上是登录时运行的计划任务——之所以是任务而非服务，是因为服务运行在会话 0，无法访问 Docker Desktop 的按用户命名的管道。

使用

atlasctl list                 # 查看可用内容
atlasctl show qwen3.6-35b-a3b-fp8-mtp  # 查看配方详情
atlasctl run qwen3.6-35b-a3b-fp8-mtp   # 启动服务
atlasctl run --print           # 打印命令而不执行
atlasctl logs --follow         # 跟随日志
atlasctl stop                  # 停止服务
atlasctl status                # 查看状态
atlasctl doctor                # 检查本机是否有问题（如有问题则退出码为1）

--print 值得了解：它显示 run 将执行的精确 docker run 命令，因此您可以在信任它之前先阅读它，或者自己运行它。添加 --portable 可保留 $(id -u) 和 $HOME 的符号表示，以便粘贴到其他地方。

多节点配方需要在每个节点上分别调用：

# 在头节点上
atlasctl run --rank 0 --world-size 2 --master-addr 10.10.10.1
# 在工作节点上
atlasctl run --rank 1 --world-size 2 --master-addr 10.10.10.1

多节点配方会拒绝在单节点上启动，而不是静默地运行小于配方描述的内容。

在其他机器上运行认证门控

被授予 bench 权限的配对节点（在该节点上使用 atlasctl peer grant-bench）将构建其 Atlas 检出的某个提交，并为您运行一个认证门控，流式传输进度并将签名的记录返回：

atlasctl bench nodes 10.10.10.2,dgx3.local          # 查看每个节点可以运行什么
atlasctl bench run 10.10.10.2 --sha <40-hex> --gate decode-floor --out-dir ./records
atlasctl bench attach 10.10.10.2                    # 重新跟随一个正在运行的任务

省略端口表示使用 34334；.local 名称无需 nss-mdns 即可工作。每个子命令都接受 --json，并且每个故障类别都有不同的退出码——Atlas 仓库中的 spark bench certify --with-nodes 就是以这种方式驱动的。有关节点的 bench.yaml、事件架构和退出码，请参阅 docs/BENCH.md；有关授权允许的内容，请参阅 SECURITY.md。

当模型无法启动时

启动是分离运行的，并且带有 --rm，因此启动时失败的容器会被移除并带走其日志。atlasctl run 会注意到这一点并显示提示，而不是报告一个已经消失的容器已启动——但那时原因已无法恢复。重新运行时保留容器，日志就会保留：

atlasctl run --no-rm
atlasctl logs

通常的原因，按值得排查的顺序：

atlasctl run --print 显示精确的 docker run 命令而不执行它，这值得在信任它之前阅读，也是粘贴到错误报告中的内容。

端口

两个端口，并且它们独立失败，因此值得区分。

34334 永远不会离开本机，因此防火墙中的任何规则都不适用于它。**34334 必须在机器之间可达。**如果它被阻塞，或者有其他东西占用它，所有本地功能仍然正常——网站仍然可以找到本机并仍然提供添加另一个节点的选项——而故障会出现在另一台机器上，表现为：

joining the fleet at 192.168.68.67:34334...
error: ... Connection refused

atlasctl doctor 会分别报告两者：

agent: ok (listening on 127.0.0.1:34333)
peers: ok (accepting on 34334)

peers: 行未监听意味着本机无法被加入，无论其他输出看起来多么健康。代理会重试该端口，因此通常的原因是另一个 atlasctl agent 已经在此处运行——而通常的修复方法是使用那个已运行的代理，而不是启动第二个。

配方的来源

**配方被编译到 atlasctl 中。**新安装不会执行任何网络访问来查找配方，因为没有需要获取的内容——二进制文件附带的语料库就是它构建时所基于的语料库。更新配方意味着更新 atlasctl。

您可以添加自己的注册表：

atlasctl registry add myteam https://github.com/myteam/recipes.git
atlasctl run @myteam/my-recipe

远程注册表只提供配方数据，其他什么也不提供。它无法导致命令在您的机器上执行：

• 在上一个启动器中执行代码的配方字段——pre_exec、post_exec、post_commands、mods、builder——无论出现在何处都会被拒绝，包括我们自己发布的配方中；
• 容器隔离来自 atlasctl 中经过审核的配置文件，而非来自配方，因此 executor_config 也会被拒绝；
• atlasctl 中根本没有“受信任注册表”的概念。该机制不存在，因此任何配置编辑都无法启用它。

带有被拒绝键的配方仍然会出现在 atlasctl list --all 中，并显示原因。消失的配方比自我解释的配方更难推理。

注册表名称在本地解析：atlas 是保留给内置语料库的，裸配方名称总是首先解析为内置配方，因此远程注册表无法通过选择其名称来屏蔽已发布的配方。

替代 sparkrun

atlasctl 替代了 sparkrun 启动器。如果您安装了 sparkrun，请运行 atlasctl doctor——并阅读 SECURITY.md，其中解释了为什么存在此工具以及需要检查什么。

在整个配方语料库中，服务命令与 sparkrun 的字节相同；有关比较和有意为之的差异，请参阅 docs/PARITY.md。

贡献配方

在 recipes/ 下添加一个 YAML 文件。文件名主体是配方名称。

recipe_version: "2"
model: org/Model-Name
runtime: atlas
container: avarok/atlas-gb10:latest
max_nodes: 1
metadata:
  description: |
    此部署是什么，以及其测量值是多少。
  maintainer: you
defaults:
  port: 8888
  max_model_len: 8192
  gpu_memory_utilization: 0.85

CI 会解析并渲染此仓库中的每个配方，因此格式错误的配方会导致拉取请求失败，而不是在某人的机器上失败。请在描述中说明这些设置是针对什么进行验证的——这些文件中的数字是信任它们的理由。

关于检查点的说明

配方按名称引用上游 HuggingFace 仓库，而上游可以就地重新量化仓库。这种情况发生在 2026-07-10：unsloth/Qwen3.6-{27B,35B-A3B}-NVFP4 以混合精度 NVFP4/FP8 布局重新上传，而任何 Atlas 版本都无法加载——每个新下载的用户都会遇到 Weight '...weight_global_scale' not found in store，而对于仍然缓存旧快照的人来说则继续工作。

因此，默认的 27B/35B NVFP4 配方现在跟踪 nvidia/* 检查点，其磁盘格式自 2026-05-29 以来一直稳定。这些是在 GB10 上经过端到端验证的，也是您应该使用的。-unsloth 配方现在也存在，但只在某个门控实际进行过测量的地方才有——它们故意不是默认选项。

加载混合精度布局需要两个修复：atlas#300（层权重）和 atlas#301（FP8 lm_head，以及传递给 128×128 块缩放内核的逐行权重缩放——在范围内，因此没有崩溃，只是日志its错误）。两者都在 main 分支上，并在 GB10 上验证过：

目前发布的两个是 qwen3.6-27b-nvfp4-unsloth（BFCL 门控配置）和 qwen3.8-27b-nvfp4-unsloth（智能体门控配置）。两者都固定了一个可以加载该布局的镜像；在任何更旧的版本上，它们会因 weight_global_scale not found 而失败。

如果模型突然因缺少 weight_global_scale 或 weight_scale 数据类型错误而无法构建，您几乎可以肯定使用的是比 Atlas 镜像更新的检查点——请拉取更新的 avarok/atlas-gb10:dev。

目录

布局

recipes/
├── qwen3.5/
│   ├── qwen3.5-27b-dense-nvfp4.yaml
│   ├── qwen3.5-35b-a3b-nvfp4.yaml
│   ├── qwen3.5-122b-a10b-nvfp4-single.yaml
│   └── qwen3.5-122b-a10b-nvfp4-ep2.yaml
├── qwen3-next/
│   └── qwen3-next-80b-a3b-nvfp4.yaml
├── qwen3-vl/
│   └── qwen3-vl-30b-a3b-nvfp4.yaml
├── qwen3-coder-next/
│   └── qwen3-coder-next-fp8.yaml
├── gemma4/
│   ├── gemma-4-26b-a4b-nvfp4.yaml
│   └── gemma-4-31b-nvfp4.yaml
├── nemotron-3-nano/
│   └── nemotron-3-nano-30b-a3b-nvfp4.yaml
├── nemotron-3-super/
│   └── nemotron-3-super-120b-a12b-nvfp4.yaml
├── mistral-small-4/
│   └── mistral-small-4-119b-nvfp4.yaml
└── minimax-m2.7/
    └── minimax-m2.7-nvfp4-ep2.yaml

atlasctl 的配方查找在 recipes 子树中是递归的，因此族级分组纯粹是装饰性的。配方通过其文件主体访问，无论嵌套如何。

配方中捕获的硬件约束

每个配方都携带了生产验证的 KV/序列/MoE 设置，这些设置来自 Atlas 的 QUICKSTART.md、scripts/sweep_all_models.sh 基线以及生产启动脚本 start-minimax-ep2.sh/start-ep2.sh。值得注意的是：

• Mistral Small 4 强制使用 kv_cache_dtype: bf16 — FP8/NVFP4 KV 会破坏 MLA 压缩潜在表示（Atlas alpha-2.8 发布公告）。
• Qwen3-Coder-Next-FP8 需要 ssm_cache_slots: 0、oom_guard_mb: 1024 和 kv_cache_dtype: bf16。
• 122B EP=2 和 MiniMax M2.7 EP=2 在两个等级上都携带匹配的 --speculative / --mtp-quantization 标志（不匹配的标志会使 MTP 验证落在工作节点的 SSM 层，而没有分配缓冲区）。
• MiniMax M2.7 EP=2 限制为 max_model_len: 12288，以在公共 avarok/atlas-gb10:latest 镜像的 gpu_memory_utilization: 0.90 下适应头部的 KV 预算（2026-05-08 现场验证）。

相关链接

• 运行时：atlasctl 中的 atlas 运行时（https://github.com/spark-arena/atlasctl）（PR #169）
• 引擎：https://github.com/Avarok-Cybersecurity/atlas
• Docker 镜像：avarok/atlas-gb10（https://hub.docker.com/r/avarok/atlas-gb10）
• Discord：Atlas-Inference（https://atlasinference.io）

许可证

AGPL-3.0 — 请参阅 LICENSE。与上游 Atlas（https://github.com/Avarok-Cybersecurity/atlas）许可证匹配。

Azeez (@AtlasInference)： Dflash2 对 Atlas 推理的支持 ⚡️

单行服务仅需 24 秒 ⏰ https://t.co/f8eyXrEJc0 sparkrun run @atlas/qwen3.8-27b-nvfp4-dflash2

超前草拟 8 个 token，并行验证，获得约 23.5 tok/s 的速度，无精度损失（87.9% BFCL）💯

不能用脑子换速度 🧠