ghcr.io/getainode/ainode-base:0.5.13-c026c92

AINode

将任意 NVIDIA GPU 转化为本地 AI 平台。 直接在浏览器中完成推理与微调，仅需一条命令即可完成安装。接入节点后，各节点可自动相互发现。

ainode.dev · 文档 · 快速上手 · 截图展示 · 已测试模型 · 功能支持/不支持清单

---

AINode 是什么

AINode 是一款自托管 AI 设备，兼容 NVIDIA GB10（DGX Spark、ASUS GX10）以及所有搭载 NVIDIA GPU 的设备。只需一条命令即可在每台机器上安装编排器容器和 systemd 单元，该编排器将提供以下能力：

• 现代化 Web UI，集成聊天、集群拓扑、服务器控制台、下载、训练功能
• 兼容 OpenAI 的 API（/v1/chat/completions、/v1/completions、/v1/embeddings）与 Anthropic Messages API（/v1/messages），两类 API 均可通过模型 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 个节点，聚合 VRAM 达 487 GB

“MASTER” 节点（头节点）运行 API 并负责全局编排。其余从属的轨道节点（工作节点）运行无头引擎容器，执行头节点分配的对应 rank 任务。实例卡片标注 DISTRIBUTED · TP=2，代表该模型已被分片部署到 2 张 GPU 上。

聊天界面

功能完备的聊天交互，支持令牌流输出、提示词历史记录、代码高亮、单条消息指标展示（TTFT、令牌生成速率、总令牌数），可对接集群中任意已加载模型，无论该模型是单卡运行还是多卡分片运行。

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

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

下载页：实时 HuggingFace 目录

浏览热门 HuggingFace 模型，系统会根据集群聚合 VRAM 自动计算并展示 AVAILABLE（可直接加载） / FITS GPU（显存容量足够） 标识。可将下载任务加入共享 NFS 缓存队列，任意节点都可立即加载已下载的模型。

训练页：总览

提供三种快速启动路径：LoRA（轻量模式，适合绝大多数用户）、QLoRA（4 位基模型模式，适配超大型模型）、全量微调（需单节点配备大显存 GPU）。所有训练任务均在对应节点的本地 GPU 上执行。可查看运行中与已完成的任务、GPU 耗时，还可直接跳转至数据集管理界面。

训练页：模板

提供指令微调（Alpaca）、聊天微调（ShareGPT）、分类头训练的入门示例。每个模板均附带可直接使用的数据集 schema，数分钟内即可启动训练任务。

配置页：集群

可指定节点角色（auto / master / worker），设置共享 cluster_id，仅配置相同 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

该服务单元从 ~/.ainode/image.env 读取固定镜像版本（通过 EnvironmentFile 配置，Restart=always 生效），因此节点遭遇意外掉电重启后，会自动恢复此前已加载的独立模型和堆叠模型。分布式头节点状态不会自动恢复：分布式头节点需要等待其他对等节点接入，因此你需要在浏览器中手动重新启动它。

安装程序还会提前拉取运行时所需的 vLLM 引擎镜像（下载体积约 8.5 GB，磁盘占用约 22 GB），避免你首次启动模型时等待过长时间。设置环境变量 AINODE_NVIDIA_IMAGE=skip 可跳过该预拉取步骤。 3. 在浏览器中打开地址 http://<你的节点IP>:3000，从目录中选择任意模型。点击模型卡片后选择 Launch，即可开始聊天。系统没有配置引导向导：安装程序会自动写入 onboarded: true 配置并将 model 字段置空，因此节点启动后默认不加载任何模型，等待你的操作。 4. 如需新增节点，在当前主节点运行命令 ainode cluster token 生成令牌，然后在新设备上运行输出的 ainode join 命令即可。该命令会自动写入集群 ID、共享密钥和主节点地址，无需手动编辑 config.json。

升级操作执行 ainode update 即可，该命令会自动解析并拉取最新版本，随后重启服务。如需固定版本，可指定版本号执行 ainode update 0.5.24。请以当初安装 AINode 的用户身份运行该命令，在执行 sudo 操作前请先阅读升级 AINode 文档。

偏好手动拉取镜像？ GHCR 是 AINode 唯一官方发布镜像的仓库地址：

docker pull ghcr.io/getainode/ainode:latest # 拉取最新正式版本
# 也可像安装程序一样指定固定版本，所有版本标签可在以下地址查看
# https://github.com/getainode/ainode/releases
docker pull ghcr.io/getainode/ainode:X.Y.Z

本项目没有 Docker Hub 镜像。Docker Hub 上的 argentaios/ainode 仓库版本停留在 2026 年 4 月的 0.4.7 版，该版本远早于当前的引擎后端、模型目录、堆叠部署、基准测试和嵌入功能，请勿拉取使用。

双节点模式（分布式运行）

适用于单张 GPU 无法容纳的大模型场景，例如将前沿 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. 打开主节点 Web UI：你将在界面中看到两个节点以及聚合后的系统资源总量，例如「2 个节点 · 244 GB 显存 · 2 张 GPU」。每个节点会自动检测自身挂载的 GPU 数量并上报给主节点，配备多 GPU 的主机所有 GPU 都会被计入全局聚合总量。 6. 启动分布式实例：在「启动实例」面板中选择目标模型，勾选需要跨节点调度的所有节点后点击启动。系统将携带所选节点 ID 发起一次 POST /api/sharding/launch API 请求；当前访问的节点默认为主节点，其余选中节点作为对等节点，全部通过之前配置的高速织物 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 位格式，全程无需调用任何外部服务。打开「训练 → 量化模型」页面后按以下步骤操作：

1. 基础模型：填写 Hugging Face 仓库 ID（例如 Qwen/Qwen3.5-4B），也可直接选择本地已安装的模型。
2. 量化方案：选择 AWQ（W4A16 格式，已在 GB10 架构显卡上通过 awq_marlin 充分验证）或 NVFP4（Blackwell 架构原生 4 位浮点格式）。
3. 校准样本数：默认值为 256，校准数据来自开源数据集 HuggingFaceH4/ultrachat_200k。
4. （可选）将量化结果推送至 Hugging Face：该操作需要你提供拥有写入权限的 Hugging Face 令牌，推送后的量化模型将作为私有仓库存储在你的个人命名空间下。

[!IMPORTANT] 执行量化操作的目标节点必须处于空闲状态。量化流程需要占用全部统一显存，若当前已有模型加载运行，AINode 将直接拒绝启动量化任务。你需要先卸载已加载的运行中模型，或主动传入 force=true 参数强制启动量化。量化完成后的结果将自动加入「已安装模型」列表，名称格式为「原始模型名 - 量化方案名」，可直接对外提供服务。

[!NOTE] 节点必须预先准备任务镜像。量化、训练以及适配器合并操作全部在独立的 GPU 容器中运行，该镜像大小约为 22 GB，系统不会自动拉取。节点将按以下优先级顺序解析镜像地址：首先读取显式配置的 AINODE_QUANT_IMAGE / AINODE_TRAIN_IMAGE 变量，随后尝试拉取 ghcr.io/getainode/ainode-train: 对应版本镜像，最后查找本地构建的 ainode-quant:0.17.0-t5 标签镜像。如果以上镜像全部不存在，量化任务会在提交时直接被拒绝，同时列出全部三个候选镜像地址，避免任务运行后在日志中抛出 docker exit 125 错误。关于任务镜像的构建和指向配置，可参阅训练部分的任务镜像章节了解发布方式。

在 GB10 架构显卡上优先使用 AWQ 方案。NVFP4 量化是较新的技术路线，针对多模态模型（例如 Qwen3.5 系列）的 NVFP4 量化目前处于实验阶段，尚未经过充分验证，因此当前版本下 Qwen3.5 系列模型推荐优先选择 AWQ 量化方案。

Hugging Face 令牌说明（读权限 vs 写权限）：AINode 的凭证信息存储在本地密钥库中（路径为 ~/.ainode/secrets.json，文件权限为 0600，静态存储状态下已做混淆处理），支持配置两个 Hugging Face 令牌：读权限令牌用于下载受访问限制的 gated 模型，写权限令牌用于将自定义模型推送至 Hugging Face Hub，仅拥有读权限的令牌在执行多 GB 级推送操作前就会被直接拒绝。你可以在「配置 → 密钥」页面设置这两个令牌（每个令牌旁配有「测试」按钮，可直接查看当前令牌的有效权限范围），也可以通过命令 ainode config --hf-token hf_xxx 直接设置读权限令牌。

---

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

打开「训练 → 新建运行」页面，选择基础模型和数据集后提交即可启动微调任务。任务将在独立的 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 状态的作业会被恢复为失败状态：对应的进程已随重启一同终止。
• 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 的运行机制已有所不同，此处将进行精确说明：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 脚本基于上述表格所用的基准记录自动生成，内容与实测数据完全一致。对于同一模型-框架组合，表格展示的是最新一次的运行结果，如果某次运行标记为"未实测"，表格中将直接显示该标注而非数值。

镜像名称：ghcr.io/getainode/ainode-base 参考标签：latest

[!NOTE] 本次提供的原始测试数据末尾内容已截断，仅保留上述完整有效基准测试记录。