naim-node：面向生产环境的分布式LLM推理与训练平台

本文深入介绍naim-node项目，这是一个企业级的LLM推理与训练节点管理平台，提供从模型库管理、多节点GPU调度到OpenAI兼容API的完整解决方案，支持llama.cpp和llama_rpc的分布式部署。

在大语言模型（LLM）从实验室走向生产的过程中，一个核心挑战是如何高效地管理和调度分布在多节点上的GPU资源。naim-node项目正是为解决这一问题而设计的综合性平台，它将控制平面（naim）与节点代理（naim-node）分离，构建了一个可扩展、安全的分布式AI基础设施。

该平台的核心价值在于提供"即插即用"的GPU计算能力：管理员只需在裸机或虚拟机上部署naim-node代理，节点就会自动注册到控制中心，并根据硬件配置被分配存储或计算角色。这种设计大大降低了大规模LLM部署的运维复杂度。

naim-controller是整个平台的"大脑"，基于SQLite构建轻量级但功能完整的控制平面。它负责：

• 期望状态管理：通过desired-state.v2.json定义平面的目标配置
• 节点注册与发现：维护已连接节点的清单、角色分配和参与平面情况
• 模型库管理：提供模型下载、量化、分发和版本控制的全生命周期管理
• 认证与授权：支持用户名/密码、SSH密钥和WebAuthn的多因素认证
• 交互端点代理：为所有LLM平面提供统一的OpenAI兼容API入口

部署在每个计算节点上的naim-hostd负责将控制器的指令转化为本地操作：

• 库存扫描：定期扫描节点的CPU、内存、GPU、磁盘和网络配置
• 角色自适应：根据硬件规格自动被分配为Storage（存储）或Worker（计算）角色
• 安全出站连接：即使节点位于NAT或防火墙后，也能通过出站连接与控制器通信
• 运行时实现：管理Docker Compose制品、磁盘生命周期和本地配置

naim-node支持多种LLM部署拓扑，核心基于llama.cpp和llama_rpc：

部署模式	适用场景	架构特点
单副本平面	开发测试、小规模部署	单一推理实例
副本并行平面	高吞吐生产环境	聚合器头节点 + 多叶推理副本
纯后端平面	外部客户端接入	无应用层，直接提供推理API
应用附加平面	业务系统集成	LLM服务与应用容器共部署
GPU工作节点	训练工作负载	仅提供GPU计算，无推理服务

naim-node的模型库是一个企业级的模型资产管理中心：

发现与获取：

• 自动发现已缓存的模型
• 支持直接下载和多部分并行下载
• 基于节点容量的智能放置决策

量化与优化：

• 支持在Worker节点上进行模型量化
• 量化目标选择与节点硬件匹配
• 量化后的模型自动分发到计算节点

任务持久化：

• 下载和量化任务在控制器重启后自动恢复
• 支持暂停、恢复、隐藏和删除操作
• 实时进度报告和UI可视化

平台为所有LLM平面提供统一的OpenAI兼容API，使现有应用可以无缝迁移：

GET  /api/v1/planes/{plane_id}/interaction/status
GET  /api/v1/planes/{plane_id}/interaction/models
POST /api/v1/planes/{plane_id}/interaction/chat/completions
POST /api/v1/planes/{plane_id}/interaction/chat/completions/stream

这种设计的关键优势在于：

• 稳定性：客户端始终通过控制器访问，即使底层推理节点发生变化
• 负载均衡：控制器可以透明地在多个副本间分配请求
• 策略控制：在控制器层实施思考隐藏、语言偏好、完成限制等策略

naim-node采用基于规则的节点分类系统：

Storage角色：

• 无GPU要求
• 磁盘容量 > 100GB
• 负责模型存储和分发

Worker角色：

• 至少一块GPU
• 内存 >= 32GB
• 磁盘容量 > 100GB
• 负责推理计算和模型量化

值得注意的是，存储能力与派生角色是独立跟踪的。一个满足存储容量要求的Worker可以同时承担两种角色，实现存储和计算的协同优化。