节点接入与管理

imrouter 节点是独立的 Go 程序，负责下载和校验 ModelScope 模型快照、安装和托管私有CUDA Toolkit与vLLM运行环境、连接平台并转发推理任务

节点支持Linux amd64/arm64和NVIDIA GPU。机器必须安装可用的NVIDIA驱动并确保nvidia-smi可以正常执行，系统还需提供xz和可供nvcc调用的C/C++编译器；无需预装CUDA Toolkit、uv、Python、PyTorch或vLLM。没有可用驱动时，可先阅读NVIDIA 显卡驱动安装。ARM64私有CUDA安装仅支持SBSA服务器；Jetson/Tegra需要自行提供兼容的系统Toolkit

1. 检查基础环境并登录节点

先确认NVIDIA驱动和基础系统工具可用：

nvidia-smi
xz --version
cc --version

从服务商控制台选择 Linux 架构并下载节点程序，然后创建独立运行目录：

mkdir -p ~/imrouter-node
cd ~/imrouter-node
chmod +x ./imrouter
./imrouter login

登录成功后会在二进制同目录生成 proof.cert 和 .proof.key；两者必须同时保留，不能提交到代码仓库或复制给其他机器

2. 安装并验证CUDA Toolkit

节点可以将CUDA Toolkit安装到自身运行目录，不需要root权限：

./imrouter cuda install --version 12.9 --accept-license
./imrouter cuda list
./imrouter cuda verify --version 12.9

示例安装CUDA Toolkit 12.9。节点内置支持12.6、12.8和12.9，请安装不高于nvidia-smi所示驱动上限的最高内置版本，优先顺序为12.9、12.8、12.6；驱动上限低于12.6时应先升级驱动。安装时必须通过--accept-license明确接受NVIDIA CUDA Toolkit许可协议。

Toolkit保存在节点程序同级的runtime/cuda/，安装过程不会修改系统驱动、软件仓库、/usr/local/cuda或全局环境变量。安装会自动切换当前版本；没有节点托管的当前版本时，节点才会尝试使用系统PATH或/usr/local/cuda中的nvcc

如果机器还需要为其他程序提供全局nvcc、开发头文件或/usr/local/cuda，可使用CUDA Toolkit 安装中的系统级脚本；仅运行imrouter节点时优先使用上述私有安装方式

3. 查看平台模型

./imrouter list
./imrouter show Qwen3.5-0.8B

示例中的 Qwen3.5-0.8B 需要替换为模型仓库中的实际模型 ID

4. 安装并检查 vLLM

./imrouter engine install
./imrouter engine list
./imrouter check

无参数时安装最新兼容版本，也可以指定精确版本：

./imrouter engine install --version 0.25.1

节点优先使用当前托管的CUDA Toolkit，并根据操作系统、CPU架构、NVIDIA驱动、Toolkit和GPU型号安装平台提供的兼容uv、托管Python、PyTorch和vLLM清单。check会离线检查NVIDIA环境和全部已安装引擎，不读取登录凭证或检查模型

5. 下载并检查模型

./imrouter pull Qwen3.5-0.8B
./imrouter list --local

pull使用平台模型 ID 获取ModelScope不可变revision和权威文件清单，支持断点续传，并在全部文件SHA256校验通过后完成下载。在节点程序目录中执行时，默认模型父目录为同目录下的models

6. 启动节点

./imrouter serve --model Qwen3.5-0.8B

请将模型 ID 替换为实际值。serve会校验已安装的CUDA Toolkit、vLLM运行时和模型快照，启动受控子进程并连接平台。serve不会自动安装CUDA Toolkit或引擎依赖。默认不限制任务数，由vLLM自行排队；--max-inflight可设置节点保护性并发上限，--context-length仅在引擎无法报告实际上下文时作为后备

7. 常用命令

./imrouter cuda list
./imrouter cuda use --version 12.9
./imrouter cuda verify --version 12.9
./imrouter engine list
./imrouter engine verify --version 0.25.1
./imrouter list --local
./imrouter remove Qwen3.5-0.8B
./imrouter check
./imrouter upgrade
./imrouter version

安装CUDA Toolkit会自动切换当前版本。当前版本和正被engine install、engine verify或serve使用的版本不能删除；应先停止相关节点进程并切换到其他已安装版本。以下示例假设12.8已经安装，且当前版本已经切换为12.9：

./imrouter cuda remove --version 12.8

删除不再使用的运行时前先停止对应serve进程：

./imrouter engine remove --version 0.25.1

pull、list --local、remove和serve的--model-dir都表示模型父目录。在节点程序目录中执行这些命令时可以省略该参数并统一使用同目录下的models；在其他目录执行或需要自定义目录时，应为这些命令传入相同的父目录，例如--model-dir /var/lib/imrouter-node/models。删除正在使用的模型前应先停止节点服务

常见问题

安装失败

先检查NVIDIA驱动、xz、C/C++编译器、网络和磁盘空间，再根据节点显示的失败步骤处理。cuda install会拒绝安装超过驱动支持上限的版本；本机nvcc与目标运行时不匹配时，应安装并切换到提示的CUDA Toolkit版本。节点不会使用系统Python环境替代签名安装清单

节点连接后没有上线

检查模型是否启用、list --local是否显示已下载，以及本地vLLM运行时和模型抽样校验是否通过

节点在线但没有任务

检查健康度和最近错误。任务量由用户请求和平台调度决定，不保证持续分配；vLLM的running、waiting和KV指标用于监控，不直接改变调度分数