ghcr.io/getainode/ainode:0.5.17

AINode

将任意 NVIDIA GPU 转变为本地 AI 平台。 在浏览器内完成推理与微调。单命令即可完成安装。新增节点后，节点间可自动相互发现。

ainode.dev · 文档 · 快速上手 · 界面截图 · 已测试模型 · 功能兼容状态

---

AINode 产品定义

AINode 是面向 NVIDIA GB10（DGX Spark、华硕 GX10）及所有搭载 NVIDIA GPU 的设备的自托管 AI 一体机。仅需一条命令即可在每台主机上完成编排器容器与 systemd 单元的安装，该编排器可为您提供以下能力：

• 现代化 Web 界面（内置对话、集群拓扑、服务控制台、下载、训练模块）
• 兼容 OpenAI 规范的 API（接口路径为 /v1/chat/completions、/v1/completions、/v1/embeddings）与 Anthropic Messages API（接口路径为 /v1/messages），两类接口均可通过模型 ID 在整个集群内实现路由分发
• 决策接口（/v1/decide）：输入带类型约束的问题，直接输出经过校准的概率结果，单次请求即可完成全部计算
• 自动为您启动 vLLM 引擎：每个已加载模型对应独立容器，引擎镜像与运行参数均已通过对应模型的兼容性验证
• 基于 RoCE 的跨节点张量并行：通过主机物理网络接口自动配置 NCCL，仅需在浏览器中选中目标节点即可一键启动分布式任务
• UDP 节点发现机制：支持自动组建集群
• NFS 共享模型存储：仅需一次下载，所有节点均可直接调用
• 基于本机 GPU 的脚本化微调：支持 LoRA、QLoRA、全量微调模式

编排器镜像基于 python:3.12-slim 构建，打包后总大小约 364 MB。镜像内未预置 vLLM 和 CUDA 组件：引擎以独立容器运行，因此模型对应的引擎版本由模型本身定义，与 AINode 安装版本无关。无需配置主机 Python 虚拟环境，无需从源码编译 vLLM，不存在脆弱的运行时链路依赖。

curl -fsSL https://ainode.dev/install | bash

---

界面截图

集群视图：4 节点，聚合显存达 487 GB

名为 "MASTER" 的头节点负责运行 API 服务与集群编排。其余从属节点以无头引擎容器模式运行，执行头节点分配的计算秩任务。实例卡片标识 DISTRIBUTED · TP=2，表示当前模型已跨两张 GPU 完成分片加载。

对话页

功能完整的对话界面，支持流式 Token 输出、提示词历史记录、代码高亮、单请求指标统计（首 Token 延迟 TTFT、每秒生成 Token 数、总 Token 数），可对接集群内任意已加载的模型，支持单卡运行或跨卡分片模式。

服务页：API 控制台（LM Studio 风格）

实时开发者控制台：可查看各节点上已加载的模型列表、所有兼容 OpenAI/LM Studio/Anthropic 规范的接口端点、附带状态码与延迟信息的单请求日志，提供模型卸载按钮和可直接复制的 cURL 代码片段。

下载页：实时 HuggingFace 目录

浏览热门 HuggingFace 模型，系统会根据集群聚合显存自动计算并展示 AVAILABLE（已可用）/ FITS GPU（显存适配）标签。支持将下载任务加入队列，文件存入 NFS 共享缓存后所有节点均可直接加载。

训练页：总览

提供三种快速启动路径：LoRA（轻量方案，适合绝大多数用户）、QLoRA（4 比特基础模式，适配超大模型）、全量微调（需单节点大显存支持）。所有训练任务均在节点本机 GPU 上执行，可跟踪活跃与已完成任务数、GPU 运行时长，还可直接跳转至数据集管理页面。

训练页：模板

内置指令微调（Alpaca）、对话微调（ShareGPT）、分类头训练的开箱即用方案，每个模板均附带验证通过的数据集规范，数分钟内即可启动训练任务。

配置页：集群

可自定义节点角色（auto / master / worker），设置共享 cluster_id 确保仅匹配标识的节点可相互发现，还可查看实时成员列表，包含每个节点的角色、地址与最后活跃时间。

---

分步快速上手

单节点（单机模式）

1. 在 Linux 主机上 安装 Docker 与 NVIDIA 容器工具包。
2. 拉取镜像并配置 systemd 单元：

curl -fsSL https://ainode.dev/install | bash

该单行安装脚本会执行以下操作：

# 解析 GHCR 上最高版本的数字标签（永远不会使用浮动的 :latest 标签）
docker pull ghcr.io/getainode/ainode:
# 将镜像标识固化到 ~/.ainode/image.env，同时安装可动态替换的 systemd 单元
systemctl enable --now ainode.service

该 systemd 单元会从 ~/.ainode/image.env 读取固化后的镜像路径（通过 EnvironmentFile 配置，Restart=always 自动重启），因此服务可在主机断电重启后自动恢复，并自动加载之前已启动的单机模式模型与堆叠模型。分布式头节点不会自动重启：该模式需要对等节点参与，您可通过浏览器手动重新拉起。 安装器还会提前拉取后续运行所需的 vLLM 引擎镜像（下载体积约 8.5 GB，磁盘占用约 22 GB），避免首次启动时等待下载。设置环境变量 AINODE_NVIDIA_IMAGE=skip 即可跳过该预拉取步骤。 3. 打开浏览器访问 http://<你的节点IP>:3000 进入 Web UI，从目录中选择一个模型。点击模型卡片后选择 Launch，即可开始对话。系统无引导向导：安装器会自动写入配置项 onboarded: true 并将默认启动模型置为空，因此节点启动后不会自动加载任何模型，等待用户手动选择。 4. 新增节点：在当前节点执行 ainode cluster token 生成加入令牌，将输出的 ainode join 命令在新主机上执行即可。该命令会自动写入集群 ID、共享密钥与主节点地址，无需手动编辑 config.json 完成集群配置。

升级操作可执行 ainode update，脚本会自动解析并拉取最新版本，随后重启系统服务。指定版本号即可固化升级到特定版本，例如 ainode update 0.5.24。请以安装 AINode 的原用户身份执行升级操作，并在执行前阅读 AINode 升级指南，不建议直接使用 sudo 运行命令。

希望手动拉取镜像？ AINode 仅官方发布到 GHCR 镜像仓库：

docker pull ghcr.io/getainode/ainode:latest # 拉取最新正式版本
# 或者固化特定版本，安装器默认采用该方式拉取镜像。所有版本标签可在
# https://github.com/getainode/ainode/releases 页面查看
docker pull ghcr.io/getainode/ainode:X.Y.Z

AINode 未在 Docker Hub 搭建官方镜像。Docker Hub 上存在的 argentaios/ainode 仓库版本停留在 2026 年 4 月的 0.4.7 版本，该版本不包含当前版本的引擎后端、模型目录、堆叠加载、基准测试与 embedding 能力，请勿拉取使用。

双节点（分布式模式）

适用于单张显存无法容纳的大模型场景，例如前沿 MoE 模型跨两台 DGX Spark 完成分片加载。浏览器可视化配置路径为官方支持的标准操作流程：

1. 在两个节点之间搭建干净的高速链路：可使用直连 QSFP 线缆并独占独立的 /24 子网，或接入专用交换机端口。详见网络要求：该配置至关重要。
2. 先安装主控节点，配置对等节点列表以让安装程序自动将你的 SSH 公钥分发到各对等节点：

AINODE_PEERS="10.0.0.2" curl -fsSL https://ainode.dev/install | bash -s -- --job master

--job master 参数为必填项。若缺少该参数，对等节点列表仅用于执行 ssh-copy-id 操作，节点将以独立单机模式安装。 3. 将对等节点加入集群：在主控节点上生成接入令牌，在对等节点上执行一键安装并加入集群命令：

ainode cluster token # 在主控节点上执行，将输出下一行所需的令牌内容
   AINODE_JOIN="10.0.0.1:3000: <生成的令牌内容>" curl -fsSL https://ainode.dev/install | bash

该操作会在对等节点中写入主控节点的 cluster_id、cluster_secret、服务发现端口和主控节点地址，将其配置为 distributed_mode: "member" 模式，且不会修改其他配置项。若两个节点完全独立安装，会各自生成独有的 cluster_secret，彼此之间无法发现。因此要么使用上述加入流程，要么在安装对等节点时设置 AINODE_CLUSTER_SECRET 为主控节点的对应值。仅指定 --job worker 但未执行加入操作的对等节点不属于任何集群。 4. 验证免密 SSH 连通性：确认主控节点的安装用户可免密登录所有对等节点。主控节点通过 SSH 启动对等节点上的引擎容器，若出现密码输入提示将导致启动失败。 5. 打开主控节点 UI：界面中应显示两个节点的信息及聚合后的总内存（例如 "2 nodes · 244 GB · 2 GPUs"）。每个节点会自动检测并上报自身的 GPU 数量，多 GPU 服务器的所有显卡都会纳入总计数中。 6. 启动分布式实例：在启动实例面板中选择目标模型，勾选需跨节点调度的设备后提交启动。系统会发送一条 POST /api/sharding/launch 请求，携带所选节点 ID；当前运行操作的节点始终作为主控节点，其余节点作为对等节点，全部通过专属高速网络的 IP 地址进行通信。若对等节点未配置已知的高速网络 IP，启动请求会被直接拒绝，不会尝试通过管理局域网发起部署。实例状态将显示为 DISTRIBUTED · TP=2。

多节点启动流程会在每个节点上运行一个引擎容器：主控节点上启动 rank 0 实例，各对等节点上以 --headless 模式启动对应 rank 的实例，全部通过 vLLM 原生的多节点执行器，基于 --master-addr 和 --master-port 完成集群组网。官方模型库中的所有多节点模型均固定采用该组网架构，所有经过验证的生产启动也都使用该方案，因为除了 vLLM 本身之外无需引擎镜像预装任何额外依赖。另一种手动接入方式是在 config.json 中设置 distributed_mode: "head" 并显式指定 peer_ips，随后重启服务，无人值守的节点推荐使用该配置方式。

当前仅支持张量并行。启动请求的请求体中即使带有 strategy 字段，只要节点数量大于 1，系统就会默认使用张量并行策略，不存在流水线并行能力。

---

模型量化（AWQ / NVFP4）

AINode 可在浏览器内、利用你本地的 GPU 将全精度模型压缩为 4 位精度，全程无需调用任何外部服务。进入 Training → Quantize a Model 页面即可开始操作：

1. Base model（基础模型）：可填写 Hugging Face 仓库 ID（例如 Qwen/Qwen3.5-4B），也可选择已安装在本地的模型。
2. Scheme（量化方案）：可选 AWQ（W4A16 精度，已通过 GB10 架构的 awq_marlin 后端验证）或 NVFP4（适配 Blackwell 架构的原生 4 位浮点格式）。
3. Calibration samples（校准样本数）：默认值为 256，样本取自 HuggingFaceH4/ultrachat_200k 数据集。
4. （可选）Push result to Hugging Face（将量化结果推送至 Hugging Face）：该操作需要拥有写入权限的 Hugging Face Token，量化后的模型将以私有仓库的形式推送到你的个人命名空间下。

量化目标节点必须处于空闲状态：量化操作需要占用全部统一内存，因此 AINode 会在已有模型加载时拒绝启动量化任务（你可先卸载运行中的模型，或设置 force=true 参数强制启动）。量化完成后的模型将出现在 Installed（已安装模型） 列表中，命名格式为 <原始模型名>-<量化方案名>，可直接投入服务使用。

[!IMPORTANT] 节点必须提前准备好作业镜像。量化、训练和适配器合并操作都会在独立的 GPU 容器中运行，该镜像大小约为 22 GB，系统不会自动隐式拉取。节点将按以下优先级顺序解析镜像路径：先读取显式配置的 AINODE_QUANT_IMAGE / AINODE_TRAIN_IMAGE，其次使用 ghcr.io/getainode/ainode-train:<版本号>，最后尝试本地构建的 ainode-quant:0.17.0-t5 镜像。若节点上不存在上述任意一种镜像，作业会在启动前直接被拒绝并同时列出三个候选镜像地址，避免出现运行时日志中才抛出 docker exit 125 错误的情况。关于如何构建或指定该镜像，可参考训练章节下的作业镜像说明。

AWQ 是 GB10 架构下经过充分验证的成熟量化方案。NVFP4 量化是较新的技术路线，多模态模型（例如 Qwen3.5）的 NVFP4 量化目前属于实验性功能，尚未完成完整验证，当前 Qwen3.5 系列模型优先推荐使用 AWQ 量化方案。

Hugging Face Token 说明（读权限 vs 写权限）：AINode 会将凭证存储在本地密钥库中（路径为 ~/.ainode/secrets.json，文件权限为 0600，静态存储时已做混淆处理），包含两个 Hugging Face 专属字段：读权限 Token（用于下载需要申请权限的受限模型）和 写权限 Token（用于将模型推送至 Hub，只读 Token 会在 GB 级大文件传输前直接被拦截拒绝）。你可以在 Config → Secrets 页面中配置这两个 Token（每个 Token 旁都配有 Test 按钮，可检测当前 Token 拥有的权限范围），也可通过 ainode config --hf-token hf_xxx 命令单独设置读权限 Token。

---

模型微调（LoRA / QLoRA / 全参数微调）

进入 Training → New Run 页面，选择基础模型和数据集后提交即可启动微调任务。所有微调任务都在独立的 GPU 容器中运行（编排器镜像本身未预装 torch 环境），每个节点同一时间仅运行一个作业，队列机制会在当前作业结束后自动拉起下一个排队任务。

作业镜像要求：微调、量化和适配器合并操作都需要训练专用镜像。节点将按以下优先级顺序解析镜像路径，若节点上不存在任意一种候选镜像，作业会在启动前直接被拒绝并列出全部三个地址（旧版本会在运行时抛出 docker exit 125 错误）：

1. 显式配置的环境变量 AINODE_TRAIN_IMAGE / AINODE_QUANT_IMAGE，用于覆盖默认镜像地址。
2. 官方发布镜像 ghcr.io/getainode/ainode-train:<版本号>。
3. 本地自行构建的镜像 ainode-quant:0.17.0-t5。

官方发布镜像由 .github/workflows/publish-train-image.yml 工作流自动构建，构建基于自托管 Spark 运行器上的 scripts/Dockerfile.quant 完成，镜像大小约为 22 GB。系统不会自动隐式拉取或构建该镜像，常规版本发布流程也不会重新构建该镜像。你可以通过推送格式为 train-v<版本号> 的 Git 标签触发构建（版本号必须与 pyproject.toml 中定义的版本号完全匹配，引擎会按该版本号查找对应镜像），也可以手动触发工作流：

gh workflow run publish-train-image.yml -f push=true -f version=0.5.27

同一次构建可以通过工作流的 alias_versions 参数关联多个版本号（为同一镜像摘要追加额外标签，无需重复上传文件），从而为多个发布版本提供服务。如果节点上已经存在对应镜像，可直接指定已有镜像地址：

sudo systemctl set-environment AINODE_TRAIN_IMAGE=ghcr.io/getainode/ainode-train:0.5.27

数据集格式：支持读取存放在 ~/.ainode/datasets/ 路径下的 .jsonl 文件，也支持直接加载 Hugging Face 公开数据集 ID。数据集中的行可采用以下任意一种格式：

最后一种格式是 AutoData 所采用的写入格式，也是 sharegpt-chat 模板所声明支持的格式：role/content 对话轮次与 messages 字段的工作方式完全一致。系统会对整段渲染后的对话执行监督训练（暂未实现仅对助手回复部分进行掩码的功能，因此本特性不提供该保证），填充位永远不会被设为标签。

运行记录重启后依然保留。每次状态转换时，任务都会在自身的任务目录中写入一个 status.json 文件。服务启动时会从 ~/.ainode/training/jobs/ 重建注册表，因此重启前的任务对应的运行记录表、统计卡片、日志、产物下载、合并与恢复功能都可以正常使用。有两点值得注意的特性：

• AINode 停止时处于 RUNNING 状态的任务重启后会变为 failed：任务进程会随重启一同终止。
• AINode 0.5.26 或更早版本生成的任务目录不包含状态文件，系统会根据磁盘上的现存内容重建其状态：存在权重文件则标记为已完成，否则标记为失败。这类任务行将被标注为 restored，附带说明该情况的 note 字段，并且不会显示运行时长，因为该数据从未被记录。

恢复训练。POST /api/training/jobs/{id}/resume 接口（或任务页面上的对应按钮）会从最新检查点启动一个全新任务：新任务拥有独立的输出目录，源任务的目录会以只读方式挂载到容器内的 /src 路径，同时检查点路径也会同步重写以匹配挂载规则。恢复训练流程绝对不会向被恢复的原有运行记录写入任何数据。

---

功能特性

社区关联

AINode 基于 DGX Spark 生态中的优秀开源成果构建。https://github.com/eugr/spark-vllm-docker 及其打了补丁的 NCCL（dgxspark-3node-ring 分支）是 AINode 多节点能力的起点：0.4.x 版本直接运行了 eugr 的 launch-cluster.sh 脚本与对应基础镜像，项目中用到的各类标识与拓扑经验也全部来源于该仓库。

当前运行的版本已有诸多改进，此处有必要明确说明：AINode 0.5.x 会自行启动引擎，每个实例从模型配方指定的镜像单独拉起一个 vLLM 容器，多节点运行依赖 vLLM 原生多节点执行器实现，而非 Ray。从 eugr 的代码库构建而来的 ainode-base 镜像已不再作为正式发布产品的依赖组件。即便如此，我们对该项目的借鉴事实确凿，且 eugr 的项目仍是 Spark 硬件上原生部署 vLLM 集群的首选参考资源。

在此特别感谢 eugr 及所有让多节点 Spark 部署方案落地的贡献者。

AINode 实测模型

下表中每一项对应的模型，均已通过 AINode 在我方自有硬件上完成部署与性能实测。每一次运行的完整 JSON 记录保存在 bench/results/ 目录下，整个表格由 scripts/render-bench-table.py 脚本从这些记录自动生成，完全避免了人工编写的说明与实际数据出现偏差的问题。如果某个模型在该目录下没有对应记录，说明我们尚未对其完成实测，我们宁愿如实标注，也不会发布未经核验的性能数值。

编码测试框架运行记录

以下记录的是上述模型由专属编码代理驱动的实测结果。表格中每一项代表单个模型在对应测试框架（aider、dsh、claude 等）上的运行结果，由与上表完全相同的基准测试记录通过 scripts/render-bench-table.py 脚本自动生成，同样不会出现描述与实测数据不一致的问题。表中展示的是每一组「模型-测试框架」配对的最新运行结果，如果某次运行的标识标注了 not measured，表格中就会直接显示该字符串，而非填充无效数值。

基准测试镜像信息： 镜像名称：ghcr.io/getainode/ainode 参考标签：latest

以下是各模型与测试框架的基准测试明细：

[!NOTE] 原始输入文档末尾内容不完整，基准测试表格在最后一条“Spark-X2.5 4B”条目后被截断。