GPU 状态与模型契约

更新时间：2026年09月08日 13时20分03秒（UTC+8）

本次仅迁移文档，不改变接口行为。原有“候选”标识保留，表示发布状态尚需逐项核验，不代表本次已上线该能力。

GPU 调度器只读状态

登录后的浏览器通过 BFF 读取两条不计费、只读接口：

• GET /api/proxy/v1/scheduler/status：物理 GPU、Comfy 实例、显存、运行/等待数量和活动工作流；refresh=true 绕过短缓存。
• GET /api/proxy/v1/scheduler/capabilities：已知工作流 × 登记物理 GPU 的部署能力与有效路由矩阵；普通读取使用 30 秒短缓存，管理员请求 refresh=true 时才向中央调度器发起带冷却的全实例深度探测。

能力和路由是两个独立维度。每个 worker 均返回：

• status：实际部署能力，取 ok、incomplete、unreachable、unavailable 或 unknown。
• routed / route_order：当前是否为有效候选及其顺序；routed=false 时 route_order=null，但 status 仍保留该 GPU 的实际能力结果。工作流 ready 只统计同时满足 routed=true 且 status=ok 的物理 GPU。
• missing_nodes_count / missing_models_count：缺项数量；missing_nodes / missing_models 仅向管理员返回经过清洗的节点名和模型文件名，其他登录用户得到空数组但数量不变。
• observed_at / stale：该能力结果的探测时间和是否来自旧探测或未覆盖全部实例。

每个资源还返回 instances、reported_instances、节点与模型资产数量区间、ComfyUI / Python / PyTorch 版本集合、observed_at 和 stale。已知但中央调度器本次没有报告的工作流仍返回一行，并以 reported=false、ready=false 明示部署漂移。顶层 refresh_suppressed=true 表示深度刷新仍处于冷却期。

响应不得包含原始实例 ID、服务地址、URL、Token、任务内容或内部目录。能力探测与高频 GPU 遥测使用独立缓存和超时；能力读取失败时不影响 GPU 状态，最近成功的能力快照最多可在 300 秒窗口内以 status=degraded、stale=true 返回，并同时给出 fetched_at、attempted_at 与 last_success_at。浏览器也执行同样有界的 last-good 保留，超过窗口后恢复真实不可用状态。

Krea2 姿势 LoRA

登录客户端可通过 GET /api/proxy/v1/krea2/poses 读取姿势目录；画布使用与该接口同版本的内置目录，避免生成配置受临时网络故障影响。接口响应只返回稳定 ID、中文名称、提示词建议、推荐强度、强度范围和支持模型，不返回 GPU 上的 LoRA 文件路径。

文生图沿用 POST /api/proxy/v1/images/generations：

{
  "model": "krea2",
  "prompt": "场景与人物描述",
  "krea2_pose": "missionary",
  "krea2_pose_strength": 1.0
}

单参考图编辑沿用 POST /api/proxy/v1/images/edits multipart 表单，模型为 krea2-v21-edit，并提交同名的 krea2_pose 与 krea2_pose_strength 字段。姿势 ID 以 GET /api/proxy/v1/krea2/poses 返回的 28 项稳定目录为准；强度可省略并默认为 1.0，显式值必须是 0–2 的有限数字。只传强度、传文件路径、未知 ID 或把字段用于其他模型时返回 HTTP 400。

浏览器和公开接口始终只传稳定 ID；Proxy 与 Scheduler 在服务端白名单中解析实际 LoRA，并把最终工作流的模型资产需求交给 Scheduler 过滤 GPU 候选。

明星 GirlsLike Krea2 图像 API

GET /api/proxy/v1/models 返回当前可用模型；明星模型 ID 使用 krea2-girlslike-{alias}，并携带 name、alias、modes: ["generation", "edit"] 和服务端将自动注入的 trigger。GPU 上的 LoRA 文件路径和内部 source alias 不会出现在响应中。

文生图沿用 OpenAI 兼容入口 POST /api/proxy/v1/images/generations：

{
  "model": "krea2-girlslike-ym",
  "prompt": "电影感棚拍肖像，柔和轮廓光",
  "size": "1024x1536",
  "n": 1
}

单图编辑沿用 multipart 入口 POST /api/proxy/v1/images/edits，提交同一个 model、一份 image、prompt，以及可选的 seed 和 output_sizing=source_ratio|source_exact。同一明星模型没有参考图时执行文生图，有且仅有一张参考图时执行编辑；多图会在创建任务前返回 HTTP 400。

文生图 size 必须为 WIDTHxHEIGHT，每边 256–2048 且为 32 的倍数，省略时使用 1024x1536；固定工作流不接收 quality。单图编辑由 output_sizing 控制输出，quality、size、width、height 和 mask 均不适用，传入时返回 HTTP 400，避免参数被静默忽略。

Proxy 会幂等补齐人物标签和真实训练 trigger。以上 ym 请求最终提示词为 girlslikekrea2 for Yang Mi, 杨幂, 电影感棚拍肖像，柔和轮廓光；客户端已经写入该标签时不会重复。人物由模型 ID 的服务端白名单固定，客户端传 celebrity、LoRA 名称/路径、权重或 trigger 覆盖字段会返回 HTTP 400。

当前 50 个 alias：hangain、aimi、ayx、bl、bsn、cdl、chg、chyao、dlrb、fbb、glnz、gxt、gyj、gyy、hnkz、iu、jjy、jpy、jt、keb、khw、lhc、lq、lss、ly、lyer、lyf、lyt、mxt、mzy、sml、syn、syq、szer、szn、tly、ty、wcr、wys、xjq、ycy、ym、ysx、zjn、zjy、zs、zti、zxd、zye、zyx。