入门
GPUWorks 文档
安装 GPUWorks、部署第一个模型,并查阅节点接入和运维指南。
本文目录
从哪里开始
- 第一次接触 GPUWorks从零启动并部署第一个模型,再看控制台页面导览
- 在 Mac 上本地试用在 Mac 上运行第一个本地模型
- 在 Windows WSL2 上本机试用在 Windows WSL2 上用 Docker 运行 GPUWorks
- 遇到问题排障指南
- 对接 APIOpenAI 兼容网关、REST API 全量路由
- 参与开发开发者文档总览
用户入口
教程(tutorials)
- 从零启动并部署第一个模型适用场景:首次安装 GPUWorks,接入一台 GPU 节点并部署对话模型。
- 一张 GPU 跑两个模型:dGPU 与 sleep/wake适用场景:在一张 NVIDIA GPU 上同时运行两个小型对话模型,分别设置 dGPU 显存上限,并让其中一个休眠、唤醒。
- 在 Mac 上运行第一个本地模型在一台 Apple silicon Mac 上安装 GPUWorks,把本机接入控制台,从推理模板选择模型并完成第一次本地对话。本文面向首次安装和本地试用,用完后可以停止模型以释放资源。
- 把一个模型服务从一副本扩到两副本适用场景:一个模型已经能在单张 GPU 上运行,希望增加一个独立副本分担请求,并在负载降低后缩回一副本。
- 部署 PD 服务并观测请求链路本教程使用两台 NVIDIA GPU 节点部署 Qwen/Qwen3-14B:Prefill(P)负责提示计算,Decode(D)负责逐 token 生成。完成后,你将能发起一次长文总结请求,并通过角色状态、请求详情和 KV 交接日志判断 PD 链路是否工作。
- 运行一次性能评测并读懂报告模型服务已经能回答问题后,可以用内置的 纯随机定长负载运行一次性能评测。本教程向你指定的服务发送并发 1、2、4 的请求,查看成功率、首字等待、单用户输出速度和整体吞吐,最后保存报告。
- 定位一次回答慢的请求模型能正常回答,但回答开始得慢,或整段输出耗时较长时,可以从请求历史查看时间花在哪个阶段。本教程从一次试验场调用出发,找到对应请求、读懂耗时,再用请求 ID 找回同一条记录。
操作指南(how-to)
安装与接入
- 安装和升级控制面本文说明如何安装、验证、升级和卸载 GPUWorks 控制面。
- 在 Windows WSL2 上用 Docker 运行 GPUWorks本文说明在 Windows 的 WSL2(Ubuntu)里运行控制面与本机 GPU 节点时,与普通 Linux 主机不同的地方:推理运行时必须是 Docker + NVIDIA Container Toolkit,以及让发行版常驻。部署模型与调用接口的步骤与 Linux 相同,见从零启动并部署第一个模型。
- 升级与版本兼容本文提供控制台、命令行和离线升级方式,并说明版本不一致时的限制与回退方法。
- 接入节点、升级与卸载 agent把 GPU 主机接入已运行的 server。接入完成后,应能在计算节点中看到节点在线,并核对加速卡和运行时。
- 租用云 GPU把阿里云、RunPod、优云智算 CompShare、AutoDL 或 Vast.ai 的 GPU 实例接入 GPUWorks,并在用完后停止或释放云资源。先在厂商控制台租机,再在本平台同步和安装 agent;支持的 REST API 创建方式也在本文列出。
- 接入 ZStack Cloud将已有 ZStack Cloud 环境添加到 GPUWorks,同步 KVM 物理机和 GPU 资源,再为需要纳管的物理机安装 Agent。
- 接入 Kubernetes 集群适用场景:已有带 GPU 的 Kubernetes 集群,希望把其中一批 GPU 节点交给 gpuworks 部署模型,而不逐台安装 agent。
- 接入公有云托管 Kubernetes(阿里云 ACK、DigitalOcean、Nebius)适用场景:在公有云上租一个带 GPU 节点的托管 Kubernetes 集群,交给 gpuworks 部署模型。本文按云厂商给出从建集群到能对话的完整步骤; 工作方式、各参数的含义与日常运维见 接入 Kubernetes 集群。
- 给控制台一个公网地址在 NAT 后的开发机、GPU 节点或内网服务器上,为已运行的控制台开启临时公网入口,并在使用后关闭。本文使用 cloudflare-quick,不用于长期入口或节点接入。
- 生产环境部署将已安装的 server 配置为团队或生产入口,完成 HTTPS、网关长连接和凭证备份检查。本文适用于原生 TLS 或前置反向代理,两种方式按部署环境选择。
- 配置节点网络为有多张网卡的节点指定存储同步、参数(多机推理与 PD 的 KV 传输)和服务流量使用的网络,再用内部测试检查节点间连通性与带宽。创建网络只声明已有网络的用途,不会配置交换机、网卡地址或布线。
模型与镜像
- 使用存储:本地目录、NFS 与 NFS 加本地缓存本文说明怎样添加模型存储、导入已有模型库,以及选择部署使用的存储和管理本地缓存。
- 下载、缓存和节点间同步模型本文说明怎样登记模型、下载到指定存储,或采用节点已有的文件,使模型可以用于部署。
- 在节点之间同步模型和镜像本文说明怎样复制已有的模型或推理镜像,并检查同步结果。
- 配置镜像与模型拉取:来源规则、代理、同步组与凭据本文说明怎样配置模型和镜像的获取地址、出站代理、节点复制范围及访问凭据,并在目标节点确认配置生效。
- 从 HTTP 文件服务器导入模型与镜像将 HTTP 文件服务器上的模型目录或 docker save 镜像归档登记到平台,再获取到节点用于部署。模型目录需提供 Apache、nginx、Caddy 等可解析的目录列表页;镜像使用归档文件的直接地址。
- 离线环境部署适用场景:集群不能访问公网:拉不到 Docker Hub 等镜像仓,也下载不了 Hugging Face / ModelScope 上的模型。
部署与推理
- 部署模型、选卡与解释调度结果本文说明怎样把模型部署成可调用的推理服务,检查放置结果,并在部署后调整节点范围。
- 在昆仑 P800 上部署模型P800 PCIe / KL3 使用 kunlunxin 厂商和 xre 框架,已验证的运行时为 Linux amd64 上的 Docker 和 nerdctl;runveil 尚未开放。该组合支持整卡 TP(Tensor Parallelism,张量并行)、PP(Pipeline Parallelism,流水线并行)和引擎 DP(Data P…
- 多机推理适用场景:模型单节点放不下,或希望把 TP / PP 拆到多台节点上,让一个部署的多个 rank 分布在多台机器。
- 用 MinerU 连接远程视觉模型GPUWorks 负责部署 MinerU 视觉模型、管理 GPU 资源并提供推理网关。MinerU 客户端负责读取 PDF、渲染页面、调用模型和生成 Markdown、JSON 与图片。 输入 PDF 和解析结果保存在运行 MinerU 的机器上。
- PD 分离部署适用场景:提示长(上千 token)、并发高,prefill 抢占 decode 导致输出不稳时,把推理拆成 prefill 与 decode 两组实例(可跨机)。
- 启用和排查 dGPU本文说明怎样确认 GPU 可用的 dGPU 能力、创建带显存上限的部署,以及调整已有部署的配额。
- 让实例 sleep / wake本文说明怎样休眠整个部署、部分副本或 PD 角色以释放显存,并在需要时唤醒、确认服务恢复。
- 使用调度分析:定时计划、出让策略、唤醒等位本文说明怎样让平台替你执行事先约定好的 sleep / wake 和副本数调整,以及怎样在调度看板上看清每张卡被谁占着、什么在等、接下来要发生什么。
- 节点失联重调度本文说明一台节点离线后,平台怎样把它上面的副本重调度到别的节点:单机副本、多机副本和 PD 副本分别怎么处理,怎样调整等待时间,以及怎样让增加的单机副本先放到指定节点。
- 运行批处理任务:Batch API 与控制台本文说明怎样把一大批推理请求交给平台异步执行:准备 JSONL 文件、上传、创建批处理任务、查看进度、下载结果、取消,以及怎样把它指向出让策略为随时出让的部署、只用空闲 GPU 跑。
运维与评测
- 排障指南本文用于排查节点连接、GPU、模型与镜像、实例启动和推理请求故障。先按现象找到对应小节, 用状态、事件或日志确认原因,处理后重复原操作检查是否恢复。
- 查看指标与检索日志适用场景:查看集群和部署的 GPU 指标、排查某个实例为什么起不来或报错、按关键字检索历史日志。
- 查看用量分析适用场景:对外提供推理服务时,按 API key 核对任意时间段用了多少 token、缓存命中多少;看各部署这个月的成功率与首 token 延迟;找长期闲置的卡;看每个部署占了多少卡时、每百万 token 用了多少卡时。
- 导出请求 trace 到 OpenTelemetry适用场景:把平台网关的逐请求数据接到自己的追踪系统(Jaeger、Grafana Tempo、Grafana Cloud、Datadog 等),让上游网关、平台网关和你自己的服务在同一条 trace 里,并在控制台与追踪系统之间按 trace id 来回跳。
- 为推理模板声明引擎指标适用场景:你写了一个推理模板(尤其是 engine: callable 的自研或第三方引擎),部署后部署抽屉、实例页和服务监控页的推理面板没有数据,或者想让引擎自己的 TTFT、KV 使用率、投机接受率进入平台面板。
- 把部署另存为推理模板适用场景:你在 GPUWorks 里把一个模型跑通了(服务在运行,API 能答),想把这套配置变成推理模板,留给自己或别的集群复用,或者贡献给官方目录,但不想手写 model.yaml。
- 运行评测并解读报告适用场景:量化托管部署或外部 OpenAI 兼容端点的吞吐、延迟和成功率,比较不同并发、到达率、输入 / 输出长度下的表现。
- 使用 AI 助手适用场景:实例启动失败时找根因和修法;判断一个模型在当前集群哪些卡上能跑、要几张卡;部署的副本为什么调度不上;节点和加速卡是否健康。
- 通过 MCP 接入在支持 MCP HTTP 传输的 AI 客户端中连接 GPUWorks,让客户端读取节点、部署和指标信息,回答集群问题。完成后可列出 GPUWorks 工具,并读取一次集群概况。
查表入口
参考(reference)
- 控制台页面导览Web 控制台是一个单页应用,随 server 二进制一起提供。本页按左侧菜单的分组列出全部页面:页面名使用界面上的中文文案,路径是浏览器地址栏里的路径(前端路由),「页内」描述的是同一路径下的标签页、抽屉和弹窗。路由定义在 ui/src/App.tsx,菜单定义在 ui/src/navigation.tsx,文案在 ui/src/i18n/l…
- REST API 全量路由本文列出管理 GPUWorks 资源的 HTTP 接口,包括节点、模型、部署与设置。管理接口以 /api/v1 为前缀; 鉴权与响应约定统一列在开头,接口按资源类型查阅。路径中的 {id}、{uuid} 等须替换为实际资源标识。
- OpenAI 兼容网关server 的 /v1/* 默认要求 API key 鉴权,规则见下文认证。请求体中的 model 指定对外提供推理服务的模型名称(served model);server 据此找到部署、实例和节点,通过 agent tunnel(agent 隧道)转发到本地端口。管理 API 使用 JWT,不能用管理 JWT 代替网关 key。
- CLI 与安装脚本GPUWorks 提供两个命令行程序:gpuworks 用于安装、运行、升级和维护控制面;gpuworks-agent 用于连接 GPU 节点、检查节点环境、排查容器问题和执行评测。
- 配置与环境变量server 的配置只有一个来源:安装目录下的 server.yaml(gpuworks install 写入,单元文件和 nohup 命令只有 gpuworks serve --config <dir>/server.yaml)。放在安装目录而不在数据目录, 是为了数据库恢复到另一台机器时不会带着旧机器的地址。
- 控制面安装布局(含节点上的 agent 配置文件)
- 网络监控指标本页是节点网络与 NIXL 传输指标的字典:名称、标签、口径与控制台展示位置。怎么配置网络见配置节点网络;通用的指标查询与日志检索见查看指标与检索日志。
- 推理指标词表平台的推理指标只在 internal/inferencemetrics 定义一次:短名、类型、单位,以及由其他指标派生出的指标。推理模板的 api.metrics 用短名指向这里的指标,导入时按本表校验;存储的序列名是 gpuworks_infer_<短名>,例如 ttft_seconds 存为 gpuworks_infer_ttft_seco…
- 请求时间线与阶段拆分网关为每个转发的 /v1 与 Playground 请求记一条记录(ADR 0042)。请求视图、请求详情、端到端延迟拆解、分布卡片和导出的 OTel span(OpenTelemetry 追踪片段,ADR 0046)都从这条记录算出。
- GPU、探测、部署与 dGPU 支持矩阵上表的 dGPU 能力状态由 server 的 partition capability(分区能力判定)推导:
- 昇腾 CANN 组合矩阵更新日期:2026-11-13。这里把三件容易混淆的东西分开写:
- 镜像目录与推理镜像家族GPUWorks 自己组装完整引擎命令,不依赖镜像默认 entrypoint。镜像页按「系列 → 版本 → 节点分布」管理运行镜像, 版本按来源分三类。这三类是同一种镜像版本记录上的来源标记,不是三种不同的对象:
- 部署启动参数来源本文说明推理容器最终的 entrypoint、argv、环境变量、挂载、docker 参数、/dev/shm、端口、网络与设备, 各自从哪一层来、谁覆盖谁、什么条件下生效。entrypoint 是启动入口,argv 是传给入口的参数列表。 术语以 CONTEXT.md 为准 ([解析后启动方案]、[容器覆盖]、[命令模式]、[实例期望状态])。
- 可执行推理目录包推理目录包用于分发模型的部署配置和配套的轻量文件。一个包可以包含多个模型,每个模型又可以提供多个 spec(档位),对应不同的部署配置。导入后,可以在推理模板页面查看并选择这些配置。
- 推理目录 model.yaml 语法参考本文是 models/<model-id>/model.yaml 的逐字段语法参考。一个模型可以有多个 spec(档位); 每个 spec 描述一套可部署配置,包括适用 GPU、镜像、权重来源和启动参数。权威定义在代码: 结构体与基础校验在 internal/server/inferencecatalog/flat.go,可执行契约 (asse…
- 安全默认值清单管理 API 使用持久化会话:浏览器保存 HttpOnly 不透明 Cookie,Bearer JWT 绑定同一会话。每次鉴权都会查询会话和当前用户权限,数据库只保存随机凭证的 SHA256。
- 用户术语表这是用户可见术语的精简表;完整定义和反例以根目录 CONTEXT.md 为准。
为什么这样设计
- 架构总览:server、agent 与 yamuxserver 是控制面、Web UI 和 OpenAI 兼容网关;agent 运行在每个 GPU 节点,负责探测、runtime、 容器生命周期和指标采集。二者都静态编译,server 把前端和各平台 agent 嵌入发布包。
- runveil 与 udocker:无 docker 节点的容器运行时一句话:runveil 是 GPUWorks 在没有 docker(或 docker 给不了容器 NVIDIA 卡)的节点上用的容器运行时。它沿用 udocker 的磁盘布局和 PRoot 执行方式,但镜像处理和启动容器都由 agent 自己完成,不需要 udocker CLI,也不需要 Python。界面上统一叫 runveil;udocke…
- 典型部署拓扑本文用图说明 GPUWorks 常见的七种部署形态:谁连谁、方向怎样、需要开放哪些端口。图只画关键链路, 配置步骤不在这里重复,每节末尾链到对应的操作指南。连接模型的背景见架构总览, 各特性怎么选见怎么选:dGPU、sleep/wake、多机、副本、PD。
- 怎么选:dGPU、sleep/wake、多机、副本、PD已经能跑通第一个模型(见从零启动并部署第一个模型)之后,下一个问题通常是: 一张卡要不要分给多个模型、模型放不下怎么办、流量大了加什么、要不要上 PD。这些特性名字相近、 解决的问题不同,也不能随意叠加。本文按"解决什么问题 / 代价与限制 / 什么时候不该用"逐个讲清楚, 操作步骤不在这里重复,统一链到对应的操作指南。
- 调度与显存估算部署请求先经过可行性 filters(节点在线、framework、镜像/模型就位、dGPU 能力、能否承担服务流量), 再由 GPU planner 生成候选卡集合,最后由 scorer 按拓扑连接质量、GPU 打包紧凑度(tp 越小越优)和 显存贴合度(卡容量越贴近需求分越高)排序。被保留和被淘汰的每个候选都会进入 schedule_exp…
- 出让策略:几个部署怎样共用一批 GPU本文解释出让策略是什么、平台按什么规则让一个部署为另一个让卡,以及这些规则背后的取舍。操作步骤见使用调度分析,决策记录见 ADR 0059。
- 请求优先级请求优先级让引擎按请求的优先级排队:高优先级的请求先被调度,显存(KV 缓存)不够时先抢占低优先级的请求。它依靠 vLLM 与 SGLang 自带的优先级调度,平台负责打开引擎的开关,并且只允许网关决定每个请求的优先级。
- 部署启动配置的语义部署页里能看到的每个参数、环境变量、挂载和命令,最后都落成一份启动配置,实例启动只读这一份。本文解释这份配置怎么来、“没填”和“清除”和“冲突”各是什么意思、命令模式有哪三档,以及存量部署如何解释这些配置。操作步骤见部署模型与解释调度结果。
- SGLang 日志注入的行为与边界SGLang 默认的日志格式只有时间戳和 rank 前缀,没有级别。引擎里的真实错误和普通请求日志因此看起来一样,平台「日志」页的级别过滤(level=warn)和直方图也就看不到它们。
- dGPU 的语义与边界dGPU(dynamic GPU)把显存预算和必要的运行库注入容器,使同一物理卡上的多个实例互相受到显存上限约束。 它不是虚拟出两张拥有独立故障域、固定带宽和固定算力的 PCIe 设备。
- 安全模型与信任边界服务端持久化会话保护管理 API:网页使用 HttpOnly Cookie,非浏览器客户端可使用绑定会话的 JWT。 鉴权检查会话有效性与当前用户权限;改密原子撤销全部管理会话,退出撤销当前凭证,空闲和绝对期限 由服务端强制执行。前端只报告真实交互并处理重新登录,不管理 refresh token;后台轮询不保活。
- 架构决策记录(ADR)本索引记录 GPUWorks 的架构决策、状态和取代关系。已移出的决策保留原编号。
发布说明
开发者入口
- 开发者文档总览GPUWorks 由两个 CGO_ENABLED=0 的静态 Go 二进制和一个 React 前端组成。控制面入口是 cmd/gpuworks,节点入口是 cmd/gpuworks-agent;前端位于 ui/,构建结果嵌入 server。
- 代码地图:逐包职责CLAUDE.md「架构总览」只保留高价值的协议约束和一份「看代码看不出来的约束」清单;每个包做什么的 逐包说明放在这里。想知道某个目录/包的职责,先看这一页;想知道为什么某处这样设计、什么是唯一产地、 哪里禁止什么,回 CLAUDE.md。
- 本地搭建通过 make run-server 启动的本地 server 默认监听 :8800、数据写入 ./data。并行开发实例依次使用 8800、8802、 8804、8806;手工测试密码使用 password,不要把测试密码用于生产。 make demo 使用独立的 127.0.0.1:8099 和临时目录,并为本次运行生成管理员密码; 脚本结…
- 测试指南与云端分层测试规约的唯一权威是 CLAUDE.md。本文说明如何选择和运行各层测试, 不重复定义质量门槛。
- AMD 接入结构与硬件验收详细实现设计见 AMD 支持设计。
- 评测信息与报告规范本规范约束性能压测(benchmark)的信息保留、统计口径、解释与报告导出,覆盖负载生成、 server/agent 发压、聚合、持久化、API、CLI 和 UI。术语以 CONTEXT.md 为准;用户操作见运行评测并解读报告。
- 逐请求引擎排队耗时的观测边界监控请求的 engine_queue_ms 只能使用同一个推理回复携带的逐请求耗时。 /metrics 的排队请求数是瞬时 gauge,服务级直方图是聚合样本,两者都没有逐请求关联, 不能给某个请求反推或回填排队时间。未上报及 JSON null 保留为未知;只有显式数字 0 才是已测得零。 只有 queue 而没有 prefill 时,时间条…
- 浏览器 E2E 测试规范在 GitHub 查看原文
- 发布与内嵌资产以下命令在仓库根目录执行。先构建 UI 等前置产物,再生成用于分发的压缩包:
- 贡献指南了解如何准备开发分支、验证代码改动并提交贡献。
- PR / MR 操作指南PR / MR 模板
这篇文档有帮助吗?