修订生成带参考图的模型路由与计价文档
- ADR 改为「带参考图的生成与编辑都按编辑 concrete model 执行、审计与计价」，并补定价档位跟随 concrete model 的后果 - 里程碑文档路由表拆分 flare-c（仅无参考图生成）与 sunburst-c（编辑 + 带参考图的生成），必须成立的行为补第 7 条 - decision-log 修正 2026-09-18 条目，并新增本次「生成带参考图统一按编辑 concrete model 执行与计价」决策记录 - pitfalls、后端架构与开发运维文档同步 provider 具体模型与计价档位口径
This commit is contained in:
@@ -2,7 +2,7 @@
|
||||
|
||||
状态：accepted
|
||||
|
||||
新任务使用业务模型值 `gpt-image-2.5`，api-server 按任务显式选择具体 model：生成使用 `gpt-image-2.5-flare-c`，编辑使用 `gpt-image-2.5-sunburst-c`。这两个 GPT Image 2.5 model 必须通过启动时构造的 Tiantoken client 发送；Tiantoken client 只读取显式配置的 `TIANTOKEN_BASE_URL`（部署值由环境设置为 `https://api.tiantoken.com`）和独立 `TIANTOKEN_API_KEY`，缺失即阻止 api-server 启动，不得回退到 VectorEngine 或其 API key。
|
||||
新任务使用业务模型值 `gpt-image-2.5`，api-server 按任务显式选择具体 model：无参考图的生成使用 `gpt-image-2.5-flare-c`，编辑以及带参考图的生成使用 `gpt-image-2.5-sunburst-c`（参考图会让执行端必须走 edits multipart，因此执行与计价都按编辑 concrete model）。这两个 GPT Image 2.5 model 必须通过启动时构造的 Tiantoken client 发送；Tiantoken client 只读取显式配置的 `TIANTOKEN_BASE_URL`（部署值由环境设置为 `https://api.tiantoken.com`）和独立 `TIANTOKEN_API_KEY`，缺失即阻止 api-server 启动，不得回退到 VectorEngine 或其 API key。
|
||||
|
||||
图片协议执行逻辑保持 provider-neutral：请求 body、multipart、尺寸约束、重试、响应解码和审计由共享 image executor 承担；VectorEngine 与 Tiantoken client 只提供相同协议所需的 base URL、API key 和 provider identity。platform-image 根据 concrete model 做严格白名单路由：`gpt-image-2.5-flare-c` 与 `gpt-image-2.5-sunburst-c` 走 Tiantoken，`gemini-3.1-flash-image-preview`（nanobanana）走 VectorEngine；未知 model 直接拒绝。已持久化的 `gpt-image-2` 只在新任务提交边界按兼容规则解析为当前 GPT Image 2.5 任务，不改写历史资源，也不进入旧 VectorEngine 图片路由。
|
||||
|
||||
@@ -10,13 +10,14 @@ provider 白名单同时拒绝非 provider model：业务模型名 `gpt-image-2.
|
||||
|
||||
`gpt-image-2-c` 已整体删除：它自兜底移除后只剩历史审计字符串，从未进入业务模型、持久化模型字段或前端契约，因此不再保留任何常量、解析分支、尺寸语义或 provider 路由。数据库里既有的审计字符串保持原样，不参与新任务。
|
||||
|
||||
普通主站前端只接触业务模型和新生成展示名 `GPT Image 2.5`，admin Web/API 可以查看和编辑两个具体定价 key；普通生成即使因参考图使用 edits multipart，仍按生成 concrete model。新代码不再跨模型或跨 provider fallback，已退役的 `gpt-image-2-c` 审计记录原样保留在数据库，代码不再引用该值。
|
||||
普通主站前端只接触业务模型和新生成展示名 `GPT Image 2.5`，admin Web/API 可以查看和编辑两个具体定价 key；生成类任务带参考图时后端必须走 edits multipart，因此 dispatch、审计与计价统一按编辑 concrete model `gpt-image-2.5-sunburst-c`（包含图标素材图集的固定参考图与 UI 素材提取的来源图），不存在「生成档计价 + 编辑档执行」的分裂。新代码不再跨模型或跨 provider fallback，已退役的 `gpt-image-2-c` 审计记录原样保留在数据库，代码不再引用该值。
|
||||
|
||||
主站前端只把原本明确使用 GPT Image 2 的专用新任务改为业务模型值 `gpt-image-2.5`；普通图片、角色、场景、图标等原有 nanobanana 默认行为保持不变。画布参数或编辑布局读到 `gpt-image-2` 时，在使用端解析为 `gpt-image-2.5` 并触发参数迁移警告，原始资源、审计、metadata 和历史 fixture 不回写。AGC 现有资源生成界面与请求默认保持不变，不因本决策新增模型字段、选择器或尺寸行为。
|
||||
|
||||
## Consequences
|
||||
|
||||
- 定价配置的活动 key 是两个具体 provider model；旧单 key 配置只允许受控 backfill，并留下兼容 TODO。
|
||||
- 定价档位跟随任务最终 concrete model：带参考图的生成任务与编辑任务同价，admin 单独调整 `gpt-image-2.5-sunburst-c` 时生成带参考图的任务必须同步生效。
|
||||
- 新任务的同模型重试固定使用 api-server dispatch 的具体 model，不切换到另一个 model。
|
||||
- 两套 provider client 在 api-server 启动阶段同时构造；任一 required provider 配置缺失，启动失败而不是延迟到首次图片请求。
|
||||
- 两套 provider client 的缺失配置报错点名对应环境变量（`VECTOR_ENGINE_BASE_URL` / `VECTOR_ENGINE_API_KEY`、`TIANTOKEN_BASE_URL` / `TIANTOKEN_API_KEY`），构造成功后用启动日志记录已启用的 provider。
|
||||
|
||||
@@ -21,8 +21,8 @@
|
||||
|
||||
| Concrete model | Provider client | 业务用途 |
|
||||
| --- | --- | --- |
|
||||
| `gpt-image-2.5-flare-c` | Tiantoken | Generate，包括带参考图的普通生成 |
|
||||
| `gpt-image-2.5-sunburst-c` | Tiantoken | Edit，包括快速编辑、原位修改、raw edit |
|
||||
| `gpt-image-2.5-flare-c` | Tiantoken | Generate，仅限不带参考图的生成任务 |
|
||||
| `gpt-image-2.5-sunburst-c` | Tiantoken | Edit，包括快速编辑、原位修改、raw edit，以及带参考图的生成任务（图标素材图集的固定参考图、UI 素材提取的来源图同在内） |
|
||||
| `gemini-3.1-flash-image-preview` | VectorEngine | nanobanana 生成/编辑能力 |
|
||||
|
||||
`gpt-image-2` 与 `gpt-image-2-c` 只保留为历史持久化/审计字符串；新任务不得 dispatch 到旧 GPT Image 2 路由。未知 model 直接拒绝。
|
||||
@@ -35,6 +35,7 @@
|
||||
4. 同 concrete model 可以 retry，但永不跨 concrete model 或跨 provider fallback。
|
||||
5. 历史值读取不改写；新任务提交边界将旧值兼容为 GPT Image 2.5 业务任务。
|
||||
6. 普通前端不接收 concrete provider model；admin 定价界面可查看和编辑两个具体 pricing key。
|
||||
7. 生成任务的 concrete model 由参考图决定：同一判据同时用于 dispatch、审计与计价，带参考图的生成任务按编辑档计价。
|
||||
|
||||
## 非目标
|
||||
|
||||
|
||||
@@ -1,5 +1,15 @@
|
||||
# 决策记录
|
||||
|
||||
## 2026-09-21 生成带参考图统一按编辑 concrete model 执行与计价
|
||||
|
||||
- 背景：GPT Image 2.5 迁移后，生成端在带参考图时会改走 `/v1/images/edits` 并提交 `gpt-image-2.5-sunburst-c`，但计价仍按 `gpt-image-2.5-flare-c` 生成档，dispatch 判断也分散在三个入口各自的 `if 带参考图` 表达式里；结果是「生成档扣费 + 编辑档执行/审计」分裂，admin 单独调价任一档位都会错价，ADR 里「普通生成即使因参考图使用 edits multipart，仍按生成 concrete model」与代码事实不符。
|
||||
- 决策：保留「按是否带参考图决定 concrete model」这一现有行为，把三处文档改到与代码一致；同时新增 `editor_image_generation_concrete_model(model, has_reference_images)` 作为生成类任务选择 concrete model 的唯一入口，dispatch 与计价共用同一判据。`image_generation_mud_points` 增加 `has_reference_images`，命中编辑 concrete model 时改走编辑档 `image_edit_model_mud_points`；图标素材图集（固定参考图）、UI 素材提取（来源图）、图标规范带 `referenceId`、Agent 生成类工具带 `referenceImageIds` 全部同规则。`EditImageTool` 计价从生成档改为编辑档，与直连快速编辑、raw edit 对齐。
|
||||
- 边界：nanobanana 生成与编辑共用一个 concrete model，参考图不改变档位；不引入跨模型 fallback；历史持久化值与审计字符串不改写。
|
||||
- 同批修复：`raw_image_edit` 发送前复用共享 `ensure_provider_matches_model` 白名单校验；`platform-image` 兜底 task id 前缀改为跟随实际 provider（`tiantoken-edit` / `tiantoken-nanobanana` 不再带 `vector-engine` 前缀）；`resolve_image_provider` 增加 `gpt-image-2 → Tiantoken` 断言把历史值意图钉死；删除 `openai_image_generation.rs` 中仅测试使用的 `create_openai_image_edit` / `create_openai_image_edit_with_references`（测试改用 `..._and_model` 变体，保留空参考图本地校验覆盖）；`normalize_editor_generation_options` 的具体 provider key 改用常量；External v1 OpenAPI 的 `model` 描述改为与实现一致（`kind=ui-design` / `publication-material` 固定 `gpt-image-2.5`，UI 素材提取未传默认 nanobanana）。
|
||||
- 影响范围：`api-server`（`editor_generation_config`、`editor_project`、`editor_project_icon`、`character_visual_assets`、`editor_agent/tool`、`openai_image_generation`）、`platform-image`（`raw_image_edit`、`runtime/executor`、集成测试）、ADR、里程碑文档、External v1 OpenAPI 描述、`.codex/skills/gpt-image-2-apimart` 脚本与 SKILL.md（改用 `TIANTOKEN_*` 凭据 + concrete model）。
|
||||
- 验证：`cargo test -p api-server editor_generation_config`、`cargo test -p api-server editor_agent::tool`、`cargo test -p api-server`（1123 passed / 1 failed，失败项为 mock LLM 连接超时，单测隔离重跑通过）。
|
||||
- 关联文档：[`docs/adr/【ADR】GPT Image 2.5模型路由与历史值兼容-2026-09-18.md`](../../adr/【ADR】GPT%20Image%202.5模型路由与历史值兼容-2026-09-18.md)、[`docs/project-memory/plans/【里程碑】GPT Image 2.5 provider边界重构-2026-09-18.md`](../plans/【里程碑】GPT%20Image%202.5%20provider边界重构-2026-09-18.md)。
|
||||
|
||||
## 2026-09-21 图片 provider 白名单收紧，并整体删除 gpt-image-2-c
|
||||
|
||||
- 背景：GPT Image 2.5 迁移后，`resolve_image_provider` 仍把业务模型名 `gpt-image-2.5` 与 `gpt-image-2-c` 一起判为 Tiantoken，等于把「非 provider model」留在 provider 边界白名单里。`gpt-image-2-c` 自 2026-07-21 起只是首选模型失败时的兜底 provider model（兜底移除后仅剩历史审计字符串），从未进入业务模型、持久化 `model` 字段或前端契约——api-server 持久化的模型一律取自 `generation_options.model`（业务值），前端在 2.5 迁移前只写 `gpt-image-2`。
|
||||
@@ -9161,7 +9171,7 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
|
||||
|
||||
## 2026-09-18 GPT Image 2.5 业务模型与具体 provider 定价路由
|
||||
|
||||
- **决策**：新任务使用业务模型值 `gpt-image-2.5`；api-server 按任务显式 dispatch 具体模型 `gpt-image-2.5-flare-c`（生成）或 `gpt-image-2.5-sunburst-c`（编辑），并把同一具体 key 交给 `platform-image` 与后台定价解析。普通生成即使因参考图使用 edits multipart，仍按生成 route；同模型重试不跨模型 fallback。
|
||||
- **决策**：新任务使用业务模型值 `gpt-image-2.5`；api-server 按任务显式 dispatch 具体模型 `gpt-image-2.5-flare-c`（无参考图的生成）或 `gpt-image-2.5-sunburst-c`（编辑，以及带参考图的生成），并把同一具体 key 交给 `platform-image` 与后台定价解析。带参考图的生成任务因为必须走 edits multipart，dispatch、审计与计价统一按编辑 concrete model；同模型重试不跨模型 fallback。
|
||||
- **历史兼容**：已持久化 `gpt-image-2` 读回原值不改写；基于旧资源发起新任务时，在提交边界解析为 `gpt-image-2.5`，新任务/新产物按新业务值和当前 task price 处理。旧 `gpt-image-2-c` 仅保留历史审计，不再作为 fallback 或业务模型。
|
||||
- **可见性**：普通主站前端和公开定价 API 不接收具体 provider key；新生成 UI label 为 `GPT Image 2.5`，历史资源/旧编辑上下文不扩散该 label。admin Web/API 是明确例外，可查看和编辑两个具体定价 key。旧单 key 定价配置允许受控 backfill，并加 compatibility TODO。
|
||||
- **关联 ADR**：[`docs/adr/【ADR】GPT Image 2.5模型路由与历史值兼容-2026-09-18.md`](../../adr/【ADR】GPT%20Image%202.5模型路由与历史值兼容-2026-09-18.md)。
|
||||
|
||||
@@ -2503,7 +2503,7 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
|
||||
|
||||
- 现象：配置了 `APIMART_BASE_URL` / `APIMART_API_KEY` 后，RPG、拼图或方洞的 GPT-image-2 生图仍返回缺配置，或请求体里还出现 `official_fallback` / `image_urls`。
|
||||
- 原因：2026-05-21 后 GPT-image-2 图片生成按 VectorEngine 创建/编辑接口分流；2026-07-05 后创意 Agent 文本链路也改为 VectorEngine Chat Completions `gpt-5.4-mini`，APIMart 不再作为当前创意 Agent 来源。
|
||||
- 处理：为图片生成配置 `VECTOR_ENGINE_BASE_URL=https://api.vectorengine.ai`、`VECTOR_ENGINE_API_KEY`、`VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS`；排查请求体时确认无参考图路径为 `/v1/images/generations`、有参考图路径为 `/v1/images/edits`，新任务业务模型为 `gpt-image-2.5`，provider 具体模型为 `gpt-image-2.5-flare-c`（生成）/ `gpt-image-2.5-sunburst-c`（编辑），只在同一具体模型内重试。历史兜底模型 `gpt-image-2-c` 已从代码整体删除，不再存在任何 fallback 路径，请求体里出现该值即视为异常。
|
||||
- 处理：为图片生成配置 `VECTOR_ENGINE_BASE_URL=https://api.vectorengine.ai`、`VECTOR_ENGINE_API_KEY`、`VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS`；排查请求体时确认无参考图路径为 `/v1/images/generations`、有参考图路径为 `/v1/images/edits`，新任务业务模型为 `gpt-image-2.5`，provider 具体模型为 `gpt-image-2.5-flare-c`（不带参考图的生成）/ `gpt-image-2.5-sunburst-c`（编辑与带参考图的生成），带参考图的生成按编辑档计价，只在同一具体模型内重试。历史兜底模型 `gpt-image-2-c` 已从代码整体删除，不再存在任何 fallback 路径，请求体里出现该值即视为异常。
|
||||
- 验证：运行 `cargo test -p api-server openai_image --manifest-path server-rs/Cargo.toml` 和相关玩法图片生成测试；真实联调只在本地私密环境放置 VectorEngine key。
|
||||
- 关联：`docs/technical/VECTOR_ENGINE_GPT_IMAGE_2_GENERATION_2026-05-09.md`、`server-rs/crates/api-server/src/openai_image_generation.rs`。
|
||||
|
||||
|
||||
@@ -184,7 +184,7 @@ npm run check:server-rs-ddd
|
||||
2. Adapter 输入应显式包含 provider、prompt、reference images、OSS prefix/path/file name、asset kind、entity kind/id、slot、owner/profile/source job、metadata 和可选透明背景后处理。
|
||||
3. Adapter 输出应保留 legacy public path、object key、asset object id、MIME、extension、task id 和实际 prompt。
|
||||
4. Adapter 不负责扣费、退款或钱包读取；计费仍由调用方显式包裹。
|
||||
5. 图片 provider 协议不再放在玩法模块里实现。产品、计费、DTO、持久化和 GPT Image 2.5 创建 / 编辑请求统一使用业务模型 `gpt-image-2.5`，api-server 在提交边界分派 `gpt-image-2.5-flare-c` / `gpt-image-2.5-sunburst-c`；已持久化的 `gpt-image-2` 只按兼容规则读取，不改写历史值；已退役的 `gpt-image-2-c` 已从代码整体删除，传入即按不支持的值处理。URL / base64 图片解析、远端图片下载、请求超时 / 上游状态 / 响应解析 / 缺图 / 下载失败的结构化日志统一在 `server-rs/crates/platform-image/src/image_provider/`；其中 `runtime/executor.rs` 负责共享 provider-neutral 执行编排，`transport/` 负责 HTTP client 与 curl 传输，`protocol/` 负责请求体、路径和响应 JSON 字段。raw image edit 的 multipart 与严格尺寸校验位于独立的 `server-rs/crates/platform-image/src/raw_image_edit/`。`api-server` 只负责配置校验、玩法 prompt 编排、OSS / asset object / binding 持久化、计费和外部 API 失败审计落库。
|
||||
5. 图片 provider 协议不再放在玩法模块里实现。产品、计费、DTO、持久化和 GPT Image 2.5 创建 / 编辑请求统一使用业务模型 `gpt-image-2.5`，api-server 在提交边界按是否带参考图分派 `gpt-image-2.5-flare-c`（无参考图的生成）/ `gpt-image-2.5-sunburst-c`（编辑与带参考图的生成），dispatch、审计与计价共用同一 concrete model；已持久化的 `gpt-image-2` 只按兼容规则读取，不改写历史值；已退役的 `gpt-image-2-c` 已从代码整体删除，传入即按不支持的值处理。URL / base64 图片解析、远端图片下载、请求超时 / 上游状态 / 响应解析 / 缺图 / 下载失败的结构化日志统一在 `server-rs/crates/platform-image/src/image_provider/`；其中 `runtime/executor.rs` 负责共享 provider-neutral 执行编排，`transport/` 负责 HTTP client 与 curl 传输，`protocol/` 负责请求体、路径和响应 JSON 字段。raw image edit 的 multipart 与严格尺寸校验位于独立的 `server-rs/crates/platform-image/src/raw_image_edit/`，发送前复用共享 `ensure_provider_matches_model` 白名单校验，避免把 Tiantoken 的模型发到 VectorEngine 端点。`api-server` 只负责配置校验、玩法 prompt 编排、OSS / asset object / binding 持久化、计费和外部 API 失败审计落库。
|
||||
6. OSS 平台适配日志统一在 `server-rs/crates/platform-oss` 输出，覆盖 `sign_post_object`、`sign_get_object_url`、`head_object` 和 `put_object`。日志字段固定使用 `provider`、`operation`、`bucket`、`endpoint`、`object_key` / `key_prefix`、`access`、`content_type`、`content_length`、`status`、`status_class`、`error_kind` 和 `elapsed_ms`，只记录对象定位和排障信息；不得输出 AccessKey、policy、signature、Authorization header 或完整 signed URL。generated 私有对象上传时必须由 OSS 对象头承载浏览器 / CDN 缓存策略，默认写入 `Cache-Control: public, max-age=31536000, immutable`，不得改成 api-server 本地磁盘静态资源兜底。
|
||||
7. Puzzle、Match3D、音频、GLB、视频等复杂媒体可以复用 OSS + asset object + binding 的底层持久化能力，但玩法专属处理规则留在各自编排层，不塞进公共接口。
|
||||
8. 拼图入口页与结果页新增关卡的本地参考图不走浏览器直传 OSS，前端读取为 Data URL 后随创作 action 提交，并在读取前限制 6MB、显示“图片≤6MB”。`api-server` 必须对 Data URL 实际字节数再次校验；历史图片才提交 `referenceImageAssetObjectId(s)`，后端校验 `asset_object` 的 bucket、kind、图片 MIME、大小和 owner 后签发只读 URL 给 VectorEngine 读取。
|
||||
@@ -318,7 +318,7 @@ Responses 的终态载荷既是工具调用的恢复源，也是正文的恢复
|
||||
|
||||
错误边界固定如下：`StreamUnavailable` 只表示流式响应已给出 `tool_use` / `tool_calls` 完成原因但没有聚合出任何工具 slot，供调用方回退非流式，它不承担截断语义；`EmptyResponse` 表示最终文本和工具调用都为空，纯工具响应合法；`Deserialize` 覆盖 JSON / SSE / UTF-8 解析失败、缺少 `choices[0]`、流式工具身份缺失、流式工具槽位身份冲突、流式参数不完整，以及上述工具流未收尾截断。Anthropic 仍不支持 `web_search`、图片内容和纯 system 消息，必须至少有一条非 system 文本消息。
|
||||
|
||||
- 图片生成：VectorEngine 图片 provider 归属 `platform-image`，密钥只在后端环境变量中；逻辑 SKU 固定为业务模型 `gpt-image-2.5`，provider 具体模型固定为 `gpt-image-2.5-flare-c`（生成）/ `gpt-image-2.5-sunburst-c`（编辑）；历史兜底模型 `gpt-image-2-c` 已从代码整体删除，只在同一具体模型内重试，不做跨模型 fallback。401 / 403、普通参数或安全拒绝、本地配置 / 参考图错误、无法确认上游是否已受理的发送错误、request budget 耗尽和生成成功后的图片下载失败不得切模型。一次业务请求总发送上限仍为 5 次；切换兜底模型会消耗后续 attempt，不允许两个模型各重试 5 次。`api-server` 内的 `openai_image_generation.rs` 只是兼容调用面和外部失败审计桥接，不再承载 provider 协议实现。实际外部生成运行记录统一落 `tracking_event`，`event_key = external_generation_run`，metadata 记录开始 / 结束时间、耗时、状态、成功标记、失败原因、provider task id、结果摘要和 recovered failure 数量；失败 attempt 仍落 `external_api_call_failure`，后续 attempt 成功时在运行摘要里计入 recovered failure。DashScope 只按仍在使用的历史能力单独处理，不作为 GPT-image-2 兜底。VectorEngine `/v1/images/generations` 和 `/v1/images/edits` 上游 POST 使用 `libcurl` 发送；`reqwest` 只保留给参考图 URL 下载和响应中图片 URL 下载。`/v1/images/edits` 的 multipart 参考图必须作为 libcurl 文件上传 part 发送，字段名为 `image`，实现上使用 `Form::buffer(file_name, bytes)` 并设置 `Content-Type`；不能只用 `contents(...).filename(...)`，否则上游会把请求转码为缺少图片并返回 `image is required`。`request_send` 阶段的 curl timeout / connect error 按可重试传输错误处理，最多尝试 5 次，并使用指数退避加短抖动；排障时优先看 `attempt`、`max_attempts`、`retry_delay_ms`、`reference_image_bytes_total` 和 `request_params`，不要把 `SendRequest` 当成上游业务错误。
|
||||
- 图片生成：VectorEngine 图片 provider 归属 `platform-image`，密钥只在后端环境变量中；逻辑 SKU 固定为业务模型 `gpt-image-2.5`，provider 具体模型为 `gpt-image-2.5-flare-c`（无参考图的生成）/ `gpt-image-2.5-sunburst-c`（编辑与带参考图的生成），计价档位与执行档位必须一致；历史兜底模型 `gpt-image-2-c` 已从代码整体删除，只在同一具体模型内重试，不做跨模型 fallback。401 / 403、普通参数或安全拒绝、本地配置 / 参考图错误、无法确认上游是否已受理的发送错误、request budget 耗尽和生成成功后的图片下载失败不得切模型。一次业务请求总发送上限仍为 5 次；切换兜底模型会消耗后续 attempt，不允许两个模型各重试 5 次。`api-server` 内的 `openai_image_generation.rs` 只是兼容调用面和外部失败审计桥接，不再承载 provider 协议实现。实际外部生成运行记录统一落 `tracking_event`，`event_key = external_generation_run`，metadata 记录开始 / 结束时间、耗时、状态、成功标记、失败原因、provider task id、结果摘要和 recovered failure 数量；失败 attempt 仍落 `external_api_call_failure`，后续 attempt 成功时在运行摘要里计入 recovered failure。DashScope 只按仍在使用的历史能力单独处理，不作为 GPT-image-2 兜底。VectorEngine `/v1/images/generations` 和 `/v1/images/edits` 上游 POST 使用 `libcurl` 发送；`reqwest` 只保留给参考图 URL 下载和响应中图片 URL 下载。`/v1/images/edits` 的 multipart 参考图必须作为 libcurl 文件上传 part 发送，字段名为 `image`，实现上使用 `Form::buffer(file_name, bytes)` 并设置 `Content-Type`；不能只用 `contents(...).filename(...)`，否则上游会把请求转码为缺少图片并返回 `image is required`。`request_send` 阶段的 curl timeout / connect error 按可重试传输错误处理，最多尝试 5 次，并使用指数退避加短抖动；排障时优先看 `attempt`、`max_attempts`、`retry_delay_ms`、`reference_image_bytes_total` 和 `request_params`，不要把 `SendRequest` 当成上游业务错误。
|
||||
- 抠图输入以私有 OSS 作为内存生命周期边界：生成原图和角色动作抽取帧上传时消费图片字节所有权，上传完成后不保留原图缓冲；手动去背景直接解析并校验已有 OSS object key，不下载原图。BgFilter 必须为 object key 签发 600 秒 GET URL 并通过 multipart `image_url` 提交，不用 `file` 重传；flat 链路进入阿里云 fallback 时由 `platform-matting` URL 接口单独下载并上传 `AuthorizeFileUpload` 临时对象，在推理前释放下载缓冲，继续 fallback 到本地键色时再单独下载一次原图，本地产出后释放本次原图下载缓冲。签名 URL 不得写入日志、审计或持久化。
|
||||
- 角色动作抠图输入像素边界：仅图片画布角色动作链路在 FFmpeg 抽帧后、源帧上传 OSS 前，把帧解码为 RGB8，并按最终 `frameWidth × frameHeight` 的 contain 比例使用 `Triangle` 只缩放到内容尺寸；该阶段不得创建最终目标尺寸画布、不得引入 Alpha 通道，也不得插入任何 padding。BgFilter、阿里云通用抠图和本地键色降级共享这个无补边源帧 object key。抠图返回后才统一转为 RGBA8，按相同比例居中放入最终目标尺寸画布，并用 `RGBA(0,0,0,0)` 补齐透明 padding。以 `560×752 → 323×480` 为例，抠图输入固定为无 Alpha、无补边的 `323×434 RGB8 PNG`，最终输出为上下各 `23px` 透明补边的 `323×480 RGBA8 PNG`。旧 `/api/assets/character-animation/*` 动作发布链路继续保留原有帧 finalizer，不适用该输入规则。抽帧解码后若携带 Alpha 通道，必须先把像素按白底合成为不透明再转 RGB8，禁止直接丢弃 Alpha——全透明像素下未定义的 RGB 值会以杂色进入抠图输入，重新引入杂色边缘；共享 FFmpeg 抽帧命令保持不固定 `-pix_fmt`，白底合成只属于该链路的 BgFilter 输入准备阶段。
|
||||
- 阿里云通用抠图的非上海地域输入不得使用 `viapiutils/GetOssStsToken`、固定 `viapi-customer-temp` 或 OSS V1 PUT。`platform-matting` 必须按官方新版 SDK Advance 协议调用 `AuthorizeFileUpload`，使用动态返回的单对象 Policy 执行 multipart POST，再把临时上海 OSS URL 交给 `SegmentCommonImage`；输入归一化、结果下载与原尺寸 Alpha 回贴继续留在同一适配器内。该协议仍上传图片字节，不等同于阿里云服务端直接抓取任意公网 URL，也不改变上层 BgFilter → 阿里云 → 本地降级顺序。
|
||||
|
||||
@@ -238,7 +238,7 @@ spacetime sql <database> "SELECT * FROM runtime_setting LIMIT 1" --server http:/
|
||||
|
||||
本地 `spacetime` CLI / standalone 版本必须和 `server-rs/Cargo.toml` 里锁定的 `spacetimedb` 版本一致；当前统一版本为 `2.8.3`，CLI / standalone commit 固定核对为 `8e410d2842147bd8e5a32a9589cc00c19f7478e2`。若版本或 commit 错配，procedure 返回值可能在宿主侧触发 `Failed to BSATN deserialize procedure return value`，api-server 最终表现为现役 settings、editor project 或 profile procedure 超时。排障时先运行 `spacetime --version`，再对照 `server-rs/Cargo.toml` 的 `spacetimedb = "..."`；其它版本可执行 `spacetime version install <version> && spacetime version use <version>`，升级后重启 `npm run dev:spacetime` 再重试。当前 `scripts/dev.mjs` 会把 tool version 和 commit 一起写入 `dev-spacetime-tool-version`，启动新 standalone 与复用已有本地进程时都要求 `2.8.3 + 8e410d28...` 同时匹配；旧版本或旧单行版本记录会拒绝复用并要求重启。2.6.1 修复了 procedure context 中调用者 `Identity` / `ConnectionId` 始终为空的回归，依赖 `ctx.sender` 鉴权时必须同时确认宿主已升级。
|
||||
|
||||
本地 `.env`、`.env.local` 或 `.env.secrets.local` 修改后必须重启 `api-server` 才会生效；若已经通过 `npm run dev` 启动完整联调，可在该终端输入 `rs api-server`。排查图片编辑器 Tiantoken 生成链路时，确认 `TIANTOKEN_BASE_URL`、`TIANTOKEN_API_KEY` 和 `TIANTOKEN_IMAGE_REQUEST_TIMEOUT_MS` 只在本地或服务器密钥文件中配置，不能写入 Git；同时确认 VectorEngine 的 `VECTOR_ENGINE_BASE_URL` / `VECTOR_ENGINE_API_KEY` 已配置，因为两个图片 client 都在 api-server 启动时构造，任一缺失都会阻止启动。VectorEngine 配置仍保留给 nanobanana 与 Suno 音乐任务。`TIANTOKEN_IMAGE_REQUEST_TIMEOUT_MS` 是单次 attempt 的配置上限，默认 `1000000`；配置加载层允许显式值低于该默认值，不再在读取环境变量时强制抬高。新生成任务使用业务模型 `gpt-image-2.5`，api-server 显式分派 `gpt-image-2.5-flare-c`（generate）或 `gpt-image-2.5-sunburst-c`（edit）；已持久化的 `gpt-image-2` 只在提交边界按兼容规则解析，不改写历史值，也不回退到旧 GPT Image 2 路由；已退役的 `gpt-image-2-c` 已从代码整体删除，传入即按不支持的值处理。图片协议、URL / base64 响应解析、远端图片下载和 provider 侧结构化日志在 `server-rs/crates/platform-image`，`api-server` 只做编辑器请求编排、OSS / asset 持久化、计费和失败审计落库。`platform-image` 会在 JSON 生成和 multipart 编辑请求发送前按同一 GPT-image family 规则归一显式像素尺寸；若请求发送失败，先按同一 `request_id` 查看 provider 日志与 `external_api_call_failure.metadata_json.errorSource`，当前 multipart `/v1/images/edits` 单独强制 HTTP/1.1。
|
||||
本地 `.env`、`.env.local` 或 `.env.secrets.local` 修改后必须重启 `api-server` 才会生效；若已经通过 `npm run dev` 启动完整联调，可在该终端输入 `rs api-server`。排查图片编辑器 Tiantoken 生成链路时，确认 `TIANTOKEN_BASE_URL`、`TIANTOKEN_API_KEY` 和 `TIANTOKEN_IMAGE_REQUEST_TIMEOUT_MS` 只在本地或服务器密钥文件中配置，不能写入 Git；同时确认 VectorEngine 的 `VECTOR_ENGINE_BASE_URL` / `VECTOR_ENGINE_API_KEY` 已配置，因为两个图片 client 都在 api-server 启动时构造，任一缺失都会阻止启动。VectorEngine 配置仍保留给 nanobanana 与 Suno 音乐任务。`TIANTOKEN_IMAGE_REQUEST_TIMEOUT_MS` 是单次 attempt 的配置上限，默认 `1000000`；配置加载层允许显式值低于该默认值，不再在读取环境变量时强制抬高。新生成任务使用业务模型 `gpt-image-2.5`，api-server 显式分派 `gpt-image-2.5-flare-c`（不带参考图的 generate）或 `gpt-image-2.5-sunburst-c`（edit 与带参考图的 generate，计价同步走编辑档）；已持久化的 `gpt-image-2` 只在提交边界按兼容规则解析，不改写历史值，也不回退到旧 GPT Image 2 路由；已退役的 `gpt-image-2-c` 已从代码整体删除，传入即按不支持的值处理。图片协议、URL / base64 响应解析、远端图片下载和 provider 侧结构化日志在 `server-rs/crates/platform-image`，`api-server` 只做编辑器请求编排、OSS / asset 持久化、计费和失败审计落库。`platform-image` 会在 JSON 生成和 multipart 编辑请求发送前按同一 GPT-image family 规则归一显式像素尺寸；若请求发送失败，先按同一 `request_id` 查看 provider 日志与 `external_api_call_failure.metadata_json.errorSource`，当前 multipart `/v1/images/edits` 单独强制 HTTP/1.1。
|
||||
|
||||
编辑器 ElevenLabs 音效生成只从服务端读取 `ELEVENLABS_BASE_URL`、`ELEVENLABS_API_KEY` 和 `ELEVENLABS_REQUEST_TIMEOUT_MS`，timeout 默认 `180000ms`；base URL 或 Key 缺失时失败关闭，不回退 Vidu。生产 API 与 external-generation worker 通过共享 API env 取得同一配置，模板见 `deploy/env/api-server.env.example`；Key 不得进入 Web/Vite 环境、命令参数、日志、fixture 或仓库。普通测试只使用 loopback mock，禁止把真实付费请求作为 T3 自动验收。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user