跳转到正文

架构说明

本文目录

两个二进制

server 是控制面、Web UI 和 OpenAI 兼容网关;agent 运行在每个 GPU 节点,负责探测、runtime、 容器生命周期和指标采集。二者都静态编译,server 把前端和各平台 agent 嵌入发布包。

总览

本页的总览图与生命周期图以容器运行时路径为例;macOS 节点使用 host 运行时,以普通主机进程运行引擎,见 ADR 0044。

flowchart TB
  user["浏览器 / API 客户端"]
  app["推理调用方 (OpenAI SDK)"]
  subgraph server["server(控制面)"]
    direction LR
    api["REST API + Web UI"]
    gw["OpenAI 兼容网关"]
    ctl["controller:期望状态与对账"]
    sched["调度与显存估算"]
    db[("SQLite:配置、日志、指标")]
    api --> ctl
    gw --> ctl
    ctl --> sched
    ctl --> db
  end
  subgraph node["GPU 节点"]
    direction LR
    agent["agent"]
    rt["容器运行时:docker / runveil / nerdctl"]
    eng["vLLM / SGLang 实例"]
    agent --> rt --> eng
  end
  user -->|"HTTPS /api/v1(会话或 API Token)"| api
  app -->|"/v1(API key)"| gw
  agent ==>|"出站 WebSocket + yamux(ctrl 与 data 两条通道)"| ctl
  gw -.->|"经 data 通道隧道转发请求"| eng

默认由 agent 主动向 server 发起连接,节点无需开放入站端口。使用 server_dial 时,改由 server 连接 agent 的监听端口,该端口必须能从 server 访问。SSH 只用于安装、预检查和带外恢复。

所有调用方只与 server 交互:管理面接受管理会话(网页使用 HttpOnly Cookie,其他客户端可使用绑定会话的 JWT)及平台 API Token,/v1 数据面用 API key,请求由网关选出副本后经已建立的连接转发到节点上的实例。

连接与流

agent 主动连接 wss://server/api/v1/agent/connect,升级后通过 yamux 复用。默认使用两条独立的 WebSocket 加 yamux 通道:

通道承载特点
ctrl控制消息、终端延迟敏感,固定小窗口,不被大流量拖慢
data到实例的请求隧道、日志追踪、指标与日志上送、模型与镜像传输窗口自适应,适配高带宽高延迟链路

其中各类流为:

  • ctrl:双向 JSON Lines 控制消息,envelope 为 {"t":"...","id":...,"d":{...}};
  • telemetry:agent 在数据通道上打开,上送指标与日志批次,格式与 ctrl 消息相同;server 不支持(老版本)或 agent 不开数据通道(--data-lane=false)时这些批次仍走 ctrl;数据通道在握手后 30 秒内未连上时,该连接先走 ctrl,连上后切到数据通道,见 ADR 0064;
  • logtail、tunnel:实时日志追踪和数据面;
  • model.read/model.write、image.read/image.write:模型目录和 docker save/load 流;
  • terminal:host 或 container 的交互 pty。

数据通道是控制通道会话的附属资源:它掉线时 server 会等待它重连,超时后网关返回可重试的 503,而不会把大流量回退到控制通道, 见 ADR 0024。老版本 agent 和 --data-lane=false 使用单通道;server_dial 在 agent 开启数据通道时同样建立第二条通道。

断线后 agent 重连并重放状态;server 以 desired state + watch 驱动长生命周期,短动作走 RPC。 server_dial 是带 HMAC challenge 的例外,用于 server 主动拨入受控节点。

一次部署的生命周期

sequenceDiagram
  actor U as 用户
  participant S as server(API + controller)
  participant A as agent
  participant R as 容器运行时
  participant I as 推理实例
  U->>S: 提交部署(模型、节点、参数)
  S->>S: 评估显存并调度,保存期望状态
  S->>A: 下发期望状态(ctrl 通道)
  A->>R: 校验或拉取镜像(pulling)
  A->>R: 组装命令并启动容器(starting)
  R->>I: 加载模型
  A->>I: 探测 /health
  A-->>S: 上报状态(running)
  U->>S: 调用 /v1/chat/completions
  S->>I: 选出副本,经 data 通道隧道转发
  I-->>U: 流式响应

所有部署都以 unit 为单位对账(角色 → unit → rank),失败重试、整组重置和排空由同一套逻辑完成, 见 ADR 0029。实例状态和排查方法见排障指南。

为什么没有云厂商 SDK 和 NVML

provider 使用受忠实 fixture 约束的 HTTP/SSH 客户端;agent runtime 通过 docker、nerdctl CLI 以及内置的 runveil(udocker driver,直接调用内嵌 PRoot,两者关系见 runveil 与 udocker),GPU 探测通过 nvidia-smi、npu-smi、ppu-smi、hy-smi、sysfs 和 /proc。这样保持单二进制和 CGO_ENABLED=0,也让命令、超时和错误传播可测试。

runtime 与镜像

最终启动方案合并引擎配置、选定的推理模板 spec、放置结果和部署输入;镜像目录不提供可编辑的启动默认值(ADR 0031)。 运行时如何使用镜像 entrypoint 由命令模式决定:engine 使用生成的引擎命令,image-entry 保留镜像 entrypoint 并传入引擎参数,manual 使用镜像命令或显式覆盖的命令、不注入引擎参数。runveil 额外建立 canonical ROOT loopback,使 /proc/self/maps 暴露的库路径可在 guest 中重开。

模型和镜像内容采用 原子下载/load 与 manifest/presence 校验,避免 partial 目录被当成可用。

存储与事件

GORM entity 只存在 store 层,API DTO 独立映射。SQLite 迁移通过 schema_migrations 管理。写操作 收敛到 store 显式方法,事务提交后 publish bus 事件,不使用 ORM hooks。FTS5 保存日志,内嵌 TSDB 保存指标。

可扩展点

inferenceapi 提供稳定的 chat、embeddings、rerank、audio、image、video、realtime contract; scheduler 依次执行 filters、GPU planner、scorers 并产出 schedule_explain;accelerator 注册表是 新增 dGPU 后端的唯一入口。更多长期取舍见 ADR 索引;节点网络的设计见 ADR 0030。

这篇文档有帮助吗?