明确BgFilter分割模型的对外边界
记录segModel仅限内部兼容使用，不作为用户或外部 OpenAPI 字段 补充BgFilter内存与并发约束的排障说明
This commit is contained in:
@@ -16,6 +16,14 @@
|
||||
|
||||
---
|
||||
|
||||
## 2026-07-10 BgFilter segModel 保留内部字段，不进入外部 OpenAPI
|
||||
|
||||
- 背景：`api-server` 的图片生成、图标 spritesheet 与 UI 素材提取请求仍可反序列化 `segModel`，并识别 `birefnet` / `anime-seg`，以兼容内部调用和既有任务；但 BgFilter 当前受服务进程内存与并发容量约束，不同分割模型的内存占用并非可由外部调用方自由选择的稳定契约。
|
||||
- 决策：`segModel` 是有效的**内部**字段，不是用户可配置字段。产品 UI 不提供抠图模型选择，应用内调用固定使用 `birefnet`；外部编辑器 OpenAPI 刻意不声明 `segModel`，并通过请求 schema 的 `additionalProperties: false` 拒绝该字段。外部调用方应省略它并使用服务端默认值；只有维护 BgFilter 容量与模型策略的后端代码可在经过内存 / 并发验证后调整内部固定值或兼容策略。
|
||||
- 影响范围：`server-rs/crates/api-server/src/editor_project.rs`、`src/services/image-editor/editorProjectClient.ts`、图片画布提交模型、`docs/openapi/genarrative-external-v1.openapi.json`。
|
||||
- 验证方式：确认外部 OpenAPI 三个生成请求 schema 均未公开 `segModel` 且保持 `additionalProperties: false`；运行 `npm run check:encoding` 和 `git diff --check`。
|
||||
- 关联文档：`docs/project-memory/shared-memory/pitfalls.md`（BgFilter 模型字段的对外暴露边界）。
|
||||
|
||||
## 2026-07-10 背景色决策统一走 gpt-5-mini 并挪到预扣泥点之后
|
||||
|
||||
- 背景：背景色决策此前无源图路径继承 `state.llm_client()`（Ark/豆包，选色能力弱、线上从未真正调用 VectorEngine）；且四条生成链路（角色生图 / 角色动作生视频 / 图标 spritesheet / UI 设计图提取）都在 `execute_billable_asset_operation_with_cost` 预扣泥点之前发起决策，导致用户余额不足或生成注定失败时仍白发一次 gpt-5-mini 决策、平台白付 token，也与定价文档「预扣失败不得继续调用上游」的原则相悖。
|
||||
@@ -76,7 +84,7 @@
|
||||
## 2026-07-03 图片画布生成纯色背景资产接入 BgFilter
|
||||
|
||||
- 背景：独立 BgFilter 服务已部署在 image host，并提供 `POST /bgfilter/remove-background`，支持显式 `screen_color` 和 `seg_model`。手动去背景已有独立 BiRefNet BFF，不能把两个服务的配置或语义混在一起。
|
||||
- 决策：角色形象生成、图标 spritesheet 生成和 UI 设计图素材提取在保存带纯色背景源图后，统一调用 BgFilter 生成透明 PNG；请求 multipart 字段为 `file`、`screen_color=<screenColor>` 和 `seg_model=<segModel>`，前端用户路径固定提交 `segModel=birefnet` 且不展示抠图模型选择；`anime-seg` 路径保留为后端可识别的内部能力但不对用户可见。BgFilter 使用独立配置 `GENARRATIVE_EDITOR_BGFILTER_BASE_URL`、`GENARRATIVE_EDITOR_BGFILTER_TOKEN`、`GENARRATIVE_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS`，默认 base URL 为 `http://58.87.105.82/bgfilter`，默认请求超时 `180000ms`，token 未配置时复用 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_TOKEN`。手动 `POST /api/editor/images/background-removals` 继续使用独立 BiRefNet 配置 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_BASE_URL`，不受 BgFilter 影响。BgFilter 参数里的 `seg_model=birefnet` 只表示 BgFilter 内部分割后端，不等于手动去背景的独立 BiRefNet 服务。若 BgFilter 失败，api-server 对这些标准纯色背景生成图使用本地 `editor_green_screen` 兜底；连续失败达到 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_FAILURE_THRESHOLD`（默认 `3`）后，`GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_COOLDOWN_SECONDS`（默认 `300`）内直接本地兜底。角色动作背景色和抠帧口径已由 2026-07-09 决策取代：角色动作同样使用多色自动决策，抽帧后优先阿里云通用抠图，失败再按选定背景色本地兜底。更正（截至 2026-07-10 实现）：BgFilter 失败与熔断期本条描述的「直接本地兜底」已过时——角色形象/图标/UI 三条静态生图链路同样先走阿里云通用抠图，仅阿里云也失败才本地 `editor_green_screen` 兜底。
|
||||
- 决策：角色形象生成、图标 spritesheet 生成和 UI 设计图素材提取在保存带纯色背景源图后，统一调用 BgFilter 生成透明 PNG；请求 multipart 字段为 `file`、`screen_color=<screenColor>` 和内部固定的 `seg_model=birefnet`。`segModel` 虽是后端可识别的内部兼容字段（另保留 `anime-seg`），但不向用户或外部 OpenAPI 暴露：当前 BgFilter 的内存与并发容量不适合由调用方自由切换模型。BgFilter 使用独立配置 `GENARRATIVE_EDITOR_BGFILTER_BASE_URL`、`GENARRATIVE_EDITOR_BGFILTER_TOKEN`、`GENARRATIVE_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS`，默认 base URL 为 `http://58.87.105.82/bgfilter`，默认请求超时 `180000ms`，token 未配置时复用 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_TOKEN`。手动 `POST /api/editor/images/background-removals` 继续使用独立 BiRefNet 配置 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_BASE_URL`，不受 BgFilter 影响。BgFilter 参数里的 `seg_model=birefnet` 只表示 BgFilter 内部分割后端，不等于手动去背景的独立 BiRefNet 服务。若 BgFilter 失败，api-server 对这些标准纯色背景生成图使用本地 `editor_green_screen` 兜底；连续失败达到 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_FAILURE_THRESHOLD`（默认 `3`）后，`GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_COOLDOWN_SECONDS`（默认 `300`）内直接本地兜底。角色动作背景色和抠帧口径已由 2026-07-09 决策取代：角色动作同样使用多色自动决策，抽帧后优先阿里云通用抠图，失败再按选定背景色本地兜底。更正（截至 2026-07-10 实现）：BgFilter 失败与熔断期本条描述的「直接本地兜底」已过时——角色形象/图标/UI 三条静态生图链路同样先走阿里云通用抠图，仅阿里云也失败才本地 `editor_green_screen` 兜底。
|
||||
- 影响范围：`server-rs/crates/api-server/src/config.rs`、`server-rs/crates/api-server/src/editor_project.rs`、图片画布 MVP 文档和角色形象生成设计文档。
|
||||
- 验证方式：运行 `cargo test -p api-server config::tests::from_env_reads_editor_bgfilter_settings_and_reuses_background_token editor_project::tests::editor_canvas_screen_background_generation_uses_bgfilter_postprocess --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:encoding` 和 `git diff --check`。
|
||||
- 关联文档：`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`、`docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md`。
|
||||
|
||||
@@ -2903,3 +2903,11 @@
|
||||
- 处理：**不要**给 `resolve_editor_screen_background_color` 的带图路径加图片归一化——那是阿里云抠图链路（`platform-matting`）专属需求，两者别混。真要加保护也应放在字节 / 像素远高于当前实测通过档（如 base64 >40MB 或长边 >6000px）才截断，避免无谓重编码开销与画质损失。
|
||||
- 验证：探针脚本 `Myscripts/probe_gpt5mini_image_limits.py`（本地不入库，逐级放大纯色 / 噪声图打 `/v1/responses`，记录 HTTP 状态与响应）。2026-07-10 实测：solid 512²~5000² 全 200；noise 900²(4.1MB)~2600²(34.4MB) 全 200，无拒绝阈值出现在实用范围内。
|
||||
- 关联：`server-rs/crates/api-server/src/character_animation_assets.rs`（`resolve_media_source_as_data_url`）、`server-rs/crates/api-server/src/editor_screen_background_decision.rs`、`server-rs/crates/platform-matting/src/lib.rs`（对照：阿里云输入归一化）。
|
||||
|
||||
## 不要把 BgFilter segModel 暴露为外部可选参数
|
||||
|
||||
- 现象：看到 `EditorImageGenerationRequest`、`EditorIconSpritesheetGenerationRequest` 和 `EditorUiDesignAssetExtractionRequest` 能反序列化 `segModel`，容易认为外部 OpenAPI 也应公开该字段，或让用户在 `birefnet` 与 `anime-seg` 间自行选择。
|
||||
- 原因：`segModel` 是 BgFilter 内部调用链的有效兼容字段，不等于稳定的外部产品契约。当前 BgFilter 服务受进程内存和并发容量约束，不同分割模型的资源消耗不能交给外部调用方控制；任意开放模型切换会让容量规划、超时和故障隔离失去确定性。
|
||||
- 处理：产品 UI 不提供模型选择，应用内调用固定 `birefnet`；外部编辑器 OpenAPI 不声明 `segModel`，并保持相关请求 schema 的 `additionalProperties: false`，使外部请求携带该字段时被契约拒绝。只有维护 BgFilter 模型与容量的后端代码可使用该内部字段；若未来需要开放，先完成各模型的内存、并发和超时压测，再明确版本化外部契约。
|
||||
- 验证：检查 `docs/openapi/genarrative-external-v1.openapi.json` 的图片生成、图标 spritesheet 和 UI 素材提取请求 schema 均未包含 `segModel`，且均保持 `additionalProperties: false`。
|
||||
- 关联：`server-rs/crates/api-server/src/editor_project.rs`、`src/services/image-editor/editorProjectClient.ts`、`docs/project-memory/shared-memory/decision-log.md`。
|
||||
|
||||
Reference in New Issue
Block a user