# V17 聚合模型网关标准(GATEWAY-SPEC v1) > 状态:**规范**。V17 不内置模型能力,只认一个聚合网关;本文件定义这个网关 > 必须长什么样、agent 启动 V17 前怎么验收、没有网关时怎么实现。 > 能力请求/响应格式见 `CAP-SPEC v3`(`docs/CAPABILITIES.md`);本文件只定义 > **总接口、发现、验收、部署边界**。 > > 机读入口:`GET /api/gateway`(清单)、`GET /api/gateway/check`(实测)。 > 启动前检查:`v17.exe -check-gateway -ws `(通过退出 0,否则 2)。 --- ## 1. 唯一入口 - V17 只读取 `workspace/.env` 的 `TLA_AGG_URL`,值是**网关根地址**,例如 `http://gateway.example:8080`,不带任何能力前缀。 - 不再读取 `TLA_ASR_URL` / `TLA_VL_URL` / `TLA_OCR_URL` / `TLA_FACE_URL` / `TLA_RMBG_URL` / `TLA_CLIP_URL` / `TLA_DINOV2_URL` / `TLA_MDX_URL` 等单服务地址。 - V17 的配置里**不得出现 8081/8082/8083/8084/8085/8086 等直连端口**。网关后面 怎么拆服务是网关自己的事,客户端只认 8080(或部署方指定的单一入口端口)。 - 一个部署只有一个网关;不做“主网关 + 备用单服务”的降级。 ## 2. 总接口(发现入口) ### 2.1 `GET {base}/healthz` 必须返回 HTTP 200 和 JSON;`ok:true` 表示**网关自身可用**,不代表所有可选能力都在跑。 最小响应: ```json { "ok": true, "service": "model_service-gateway", "version": "1.0.0", "services": [ {"id":"asr","ok":true,"optional":false,"target":"http://127.0.0.1:8082"}, {"id":"vision","ok":true,"optional":false,"target":"http://127.0.0.1:8084"}, {"id":"rmbg","ok":false,"optional":true,"target":"http://127.0.0.1:8083"}, {"id":"ocr","ok":true,"optional":true,"remote":true,"target":"http://service-node:8085"}, {"id":"lfm","ok":true,"optional":true,"remote":true,"target":"http://service-node:8081"} ], "routes": {"/asr":"http://127.0.0.1:8082","/ocr":"http://service-node:8085"} } ``` 规范要求: | 字段 | 要求 | |---|---| | `ok` | 必有,布尔;网关进程本身可用时为 `true` | | `service` | 必有,字符串 | | `services[]` | 必有;每项至少有 `id`、`ok`、`optional`;`target`/`remote` 建议给 | | `routes` | 建议给;键是能力前缀,值是上游根地址 | | `spec` | 建议新增 `"gateway-spec-v1"`,便于 agent 识别版本 | **兼容规则**:V17 的预检同时接受当前 `model_service` 的字段(`ok`/`optional`/`target`); 新实现应带 `spec`,旧实现缺 `spec` 不视为失败。 ### 2.2 单能力健康入口 每个能力前缀都必须有统一健康别名: ```text GET {base}/asr/healthz GET {base}/ocr/healthz GET {base}/lfm/healthz GET {base}/clip/healthz GET {base}/dinov2/healthz GET {base}/face/healthz GET {base}/mdxsep/healthz GET {base}/rmbg/healthz ``` - 200 = 该能力可用;502/503 = 服务未启动/上游不可用;404 = 网关没实现该前缀; - 健康入口**不能**要求鉴权,不能返回 HTML; - 不允许把 `/asr/healthz` 原样转给只认 `/healthz` 的上游(这是历史 404 根因); 网关必须自己提供别名,再转发到上游真实健康路径。 ### 2.3 可选局域网发现(UDP 39080) 发现是**可选能力**,不替代 `TLA_AGG_URL`,也不自动改配置。网关不实现它仍然合格; 客户端只能在用户要求或“没有配置”时探测,探测结果必须经 `/healthz` 复核后交给用户确认。 请求(客户端 → 网关,UDP 39080): ```json {"v17":"discover","spec":"gateway-spec-v1","nonce":"<随机串>"} ``` 应答(网关 → 客户端单播): ```json { "v17": "gateway", "spec": "gateway-spec-v1", "base": "http://:8080", "service": "model_service-gateway", "version": "1.0.0", "nonce": "<原样回填>", "httpPort": 8080, "bases": ["http://:8080"], "healthz": "http://:8080/healthz", "time": "2026-11-15 19:51:09" } ``` 约束: - 只接受 JSON 对象且 `v17=="discover"`、`spec=="gateway-spec-v1"` 的请求;垃圾包/空包/超长包不回; - `base` 必须是客户端能访问的地址;多网卡时按请求来源同子网选择,配 `publicBase` 时优先用它; - 客户端必须校验 `v17=="gateway"`、`spec`、`nonce`,再 `GET {base}/healthz` 校验 `200` / `ok:true` / `service`; - **多网卡**:客户端枚举所有 up 的 IPv4 网卡,**每块网卡绑定自己的源地址**,分别发该网段的定向广播和 `255.255.255.255`;不能只按默认路由选一块网卡,否则会漏掉网关所在网段; - 本机回环单独用 `127.0.0.1:39080` 和 `http://127.0.0.1:8080/healthz` 探测; - 建议 800 ms 超时、重试 2 次;发现结果只作为候选,用户确认后才写 `TLA_AGG_URL`; - 跨三层网段、交换机隔离广播、防火墙未放行 UDP 39080 时发现不到,回退到显式配置或候选地址。 V17 侧命令(只输出候选,不写配置): ```powershell server\bin\v17.exe -discover-gateway -ws workspace ``` 输出包含 `interfaces[]`(实际探测的网卡/广播地址)、`found[]`(通过 `/healthz` 的候选)、 `duration_ms` 和 `advice`;找到退出 0,没找到退出 2。可用 `TLA_GATEWAY_CANDIDATES=host:port,host2:port` 增加手工候选。 ## 3. 能力清单与等级 | id | 等级 | 网关路径 | 健康 | 说明 | |---|---|---|---|---| | `asr` | **required** | `/asr` | `/asr/healthz` | V17 启动的最低要求 | | `lfm` | standard | `/lfm/v1/chat/completions` | `/lfm/healthz` | OpenAI 视觉消息体 | | `ocr` | standard | `/ocr` | `/ocr/healthz` | 逐字取字 | | `clip` | standard | `/clip/image` | `/clip/healthz` | 512 维,已 L2 | | `dinov2` | standard | `/dinov2/image` | `/dinov2/healthz` | 384 维,未归一化 | | `face` | standard | `/face/detect` `/face/embed` | `/face/healthz` | 检测/512 维 | | `mdx` | standard | `/mdxsep` | `/mdxsep/healthz` | 人声/伴奏 | | `rmbg` | optional | `/rmbg` | `/rmbg/healthz` | 可手动停止 | | `subremove` | optional | `/subremove` | `/subremove/healthz` | 未实现返回 501 | | `tts` | optional | `/tts` | `/tts/healthz` | 未实现返回 501 | 等级含义: - **required**:没有它,V17 的 ASR 索引不可用;启动前必须通过; - **standard**:完整剪辑/检索/看图能力;缺失时 V17 仍可打开,但 `/api/gateway/check` 会报 `standard_ok:false`; - **optional**:可以人工启停或暂不实现;缺失不影响 `ok`,但必须在健康/清单中如实标记。 > **“都要实现成这样”的硬含义**:只要网关对外宣称提供某能力,路径、请求体、响应体、 > 错误码必须按 CAP-SPEC v3 来;不能换路径、不能把多个能力塞进一个私有接口、 > 不能要求 V17 去连单服务端口。没有实现的能力必须显式返回 501 > `{"ok":false,"error":"not implemented","capability":"subremove"}`,并在健康中标记不可用; > 不允许静默 404 或偷偷降级到 CPU/单服务。 ## 4. 通用请求规则 - 请求/响应 UTF-8;二进制接口用 `application/octet-stream` 或 multipart; - 时间单位秒(浮点),图像坐标是提交图像的像素; - 单次请求失败返回 4xx/5xx + JSON `{"ok":false,"error":"..."}`; - 并发上限常见 4;超限必须 `429 + Retry-After`,调用方按头退避; - 网关对 `application/x-www-form-urlencoded` 和缺失 `Content-Type` 的二进制请求, 必须改写成 `application/octet-stream` 再转发(历史 8 KB 表单上限 413 的根因); - 网关可以压缩/限制图片尺寸,但**不得改变坐标语义**;返回的 box 必须相对提交图。 ## 5. agent 安装/部署/启动 V17 的强制顺序 agent 在“下载 → 安装 → 启动 GUI”之间必须执行以下步骤。**任何一步失败都先诊断,不得 “看到连不上就自己新建一个网关”**——很大概率是已有网关没启动、端口/防火墙/地址不对。 ### 5.1 先探,不先写 1. **找配置**:读取 `workspace/.env` 的 `TLA_AGG_URL`。没有配置不等于没有网关。 2. **可选发现**:没有配置、或 `unreachable`/`not_configured` 时,先跑 `server\bin\v17.exe -discover-gateway -ws workspace`。它会枚举**所有** IPv4 网卡, 每块网卡绑定源地址后发定向广播 + `255.255.255.255`,再对候选做 `/healthz` 校验; 只输出候选,**不写 `TLA_AGG_URL`**。 3. **探总接口**:`GET {base}/healthz`,要求 200 且 `ok:true`;记录 `service`/`version`/`services`。 4. **跑预检**:`server\bin\v17.exe -check-gateway -ws workspace`;看 `state/error/missing/advice`。 5. **按 `state` 分流,禁止盲目实现**: - `ok`:网关存在且最低验收通过,继续第 5.4 步; - `capability_missing` / `partial`:**总接口已存在**,只是 ASR/标准服务没启动或上游错。 先启动/修复对应服务,或补齐该前缀;**不要重建整个网关**; - `unreachable`:先判断“已有但没启动”还是“根本没有”; - `not_configured`:先问用户有没有现成网关,不要默认新建。 ### 5.2 `unreachable` 的判定(按顺序做,不要跳) 1. 在**网关所在机器**确认进程/端口:`Get-NetTCPConnection -LocalPort 8080`、 查看网关进程/服务、`logs` 目录; 2. 在本机确认网络:`Test-NetConnection -Port 8080`;区分 **连接被拒绝**(进程没起/端口错)、**超时**(防火墙/地址错)、**502/503**(http.sys/urlacl/上游); 3. 检查是否只是监听地址、防火墙、urlacl、双进程等部署问题; 4. 若网关已存在→启动/修复它,重跑预检;**不要新建**; 5. 若确认不存在(机器上没有进程、没有安装、用户也不知道有)→进入 5.3。 ### 5.3 确认没有网关后:先让用户选实现方式 把下面选项连同证据(`health_url/error`、进程/端口探测结果)一次性告诉用户, **用户明确选择后才开始实现**: | 选项 | 适用 | 说明 | |---|---|---| | A. 使用已有网关 | 本机/局域网/云上已有服务 | 只改 `TLA_AGG_URL`;不新建任何东西 | | B. 本机最小实现(推荐先做) | 只要 ASR/字幕检索 | 本机起一个网关 + ASR;只实现 `/healthz`、`/asr`、`/asr/healthz`;资源占用最小 | | C. 本机完整实现 | 需要 OCR/VL/视觉/抠图全套 | 按第 3 节接满 standard;显存/磁盘/维护成本更高 | | D. 云服务 API 聚合 | 本机没有 GPU 或不想常驻模型 | 网关仍在本机/内网,上游换成云 API;说明延迟、费用、素材出网/隐私边界 | | E. 完全不接模型能力 | 只做剪辑/时间线/渲染,不做 ASR/OCR | 明确告知 ASR/OCR/VL 全部不可用;只能用 `scripts\start_all.cmd -NoGateway` 显式降级启动 | > 选择 B/C/D 时,才按第 6 章写网关;选择 E 时不要写模型代码,只登记“无模型能力” > 并让用户确认降级启动。任何情况下都不允许把 V17 改成直连单服务工作。 ### 5.4 启动与复核 5. **启动 V17**:`scripts\start_all.cmd`(内部再跑一次预检;没有网关会中止并打印原因)。 只有用户选择 E 时才可用 `scripts\start_all.cmd -NoGateway`(显式降级,ASR/OCR/VL 不可用)。 6. **运行中复核**:`GET http://127.0.0.1:8617/api/gateway/check`; 应看到 `ok:true`、`required_ok:true`、`standard_ok:true`(`extended_ok` 可因 rmbg 等为 false)。 7. **登记**:把网关地址、`/healthz` 结果、用户选择(A/B/C/D/E)、缺失能力写入 `workspace/docs/ENVIRONMENT.md`(R11)。 > 预检与 `/api/gateway/check` 只探健康,不跑推理。 > 真正的推理验收由 agent 用 `POST /asr` 等最小样例完成(见第 8 章)。 > 记忆口诀:**先看 `state`,再判“没启动/没实现”,最后才问用户选哪种实现。** ## 6. 确认没有网关后:实现清单 只有用户选定 B/C/D 后才执行。实现一个**网关层**(不是把 V17 改成直连): 1. 选一个固定根地址和端口(默认 `8080`),只暴露这一个端口给 V17; 2. 实现 `GET /healthz`,返回第 2.1 节结构;`ok` 反映网关自身,`services[]` 反映后端; 3. 实现 `GET /asr/healthz` 和 `POST /asr?lang=zh&itn=1`: - 请求体是音频字节; - 响应 `{"text":"...","segments":[{"start":0.0,"end":1.2,"text":"..."}]}`; 4. 有 ASR 后端就反向代理;没有就安装一个符合 CAP-SPEC 的 ASR 服务, 绝不把 8082 写进 V17 配置; 5. 其他能力按第 3 节逐项接:每个前缀一个健康别名,一个真实上游; 未实现的能力统一 501,健康标记不可用; 6. 对二进制请求统一 `application/octet-stream`,对 429 透传 `Retry-After`; 7. 启动时探测每个上游,`/healthz` 的 `ok` 不能把“手动停止的可选服务”算成整体失败; 8. 用 `v17 -check-gateway` 和 `GET /api/gateway/check` 自测,直到 `required_ok:true`、`standard_ok:true`。 最小实现(B)只做 1–4 和 8 即可;不要为了“看起来完整”把没接的服务写成假 200。 完全不对接(E)不建网关:显式 `-NoGateway` 降级启动,并在环境台账写明不可用能力。 参考拓扑: ```text V17 ── TLA_AGG_URL ──> 网关 :8080 ├─ /asr -> ASR 服务(本机或局域网) ├─ /lfm -> LFM/llama-server ├─ /ocr -> OCR 服务 ├─ /clip /dinov2 /face /mdxsep -> 视觉多模型 └─ /rmbg -> 抠图(可手动停止) ``` 网关实现可以是任何语言;只要总接口与 CAP-SPEC 对齐,V17 不关心它后面是 C#、 Go、Python 还是反向代理。 ## 7. 验收命令 ```powershell # 静态清单(不探测) Invoke-RestMethod http://127.0.0.1:8617/api/gateway # 实测(等价于 v17 -check-gateway) Invoke-RestMethod http://127.0.0.1:8617/api/gateway/check # 启动前(不需要 V17 已启动) server\bin\v17.exe -check-gateway -ws workspace # 同一套判断的独立脚本(没有 V17 安装时也能跑;--strict 要求标准能力全通) py -3 scripts\gateway_conformance.py --base http://gateway.example:8080 --strict # 判断“已有但没启动”还是“根本没有”(在网关所在机器/本机各跑一次) Get-NetTCPConnection -LocalPort 8080 -ErrorAction SilentlyContinue Test-NetConnection -Port 8080 ``` 判定: | 字段 | 含义 | |---|---| | `state` | `ok` / `not_configured` / `unreachable` / `capability_missing` / `partial`;先看它再决定动作 | | `ok` | 总接口 200 + `ok:true` + ASR 健康 200 | | `required_ok` | ASR 可用 | | `standard_ok` | asr/lfm/ocr/clip/dinov2/face/mdx 全部可用 | | `extended_ok` | rmbg/subremove/tts 全部可用(可为 false) | | `missing` | 缺失能力 id 列表 | | `advice` | 给人/agent 的下一步(含“不要盲目新建网关”的判定指引) | ## 8. 版本 - 本文件版本:`gateway-spec-v1`; - 能力请求格式版本:`CAP-SPEC v3`; - 只要路径、等级、预检语义发生变化,`gateway-spec` 版本递增;V17 的 `/api/gateway` 会在 `spec` 字段里返回当前版本,agent 不要缓存旧版本。