From 6bed37542c64f6e36ae785683b4982442510f6b1 Mon Sep 17 00:00:00 2001 From: kdletters Date: Tue, 21 Jul 2026 17:06:28 +0800 Subject: [PATCH] =?UTF-8?q?=E8=B0=83=E6=95=B4=20VectorEngine=20=E5=9B=BE?= =?UTF-8?q?=E7=89=87=E6=A8=A1=E5=9E=8B=E5=85=9C=E5=BA=95=E9=A1=BA=E5=BA=8F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 统一 gpt-image-2 首发并在符合条件的失败后切换 gpt-image-2-c 保留总尝试预算、worker deadline 与首选失败审计 补齐响应图片校验、脚本兜底和回归测试 同步后端架构、开发运维和项目共享记忆文档 --- .codex/skills/gpt-image-2-apimart/SKILL.md | 8 +- .../generate-anthro-cat-illustrations.mjs | 149 +++- .../scripts/generate-template-samples.mjs | 149 +++- .../shared-memory/decision-log.md | 7 + docs/project-memory/shared-memory/pitfalls.md | 2 +- ...】server-rs与SpacetimeDB数据契约-2026-05-15.md | 4 +- ...发运维】本地开发验证与生产运维-2026-05-15.md | 6 +- .../api-server/src/openai_image_generation.rs | 26 +- server-rs/crates/platform-image/src/lib.rs | 2 +- .../platform-image/src/vector_engine/audit.rs | 5 +- .../src/vector_engine/budget.rs | 4 + .../src/vector_engine/client.rs | 729 ++++++++++++++---- .../src/vector_engine/constants.rs | 1 + .../src/vector_engine/curl_transport.rs | 3 + .../platform-image/src/vector_engine/error.rs | 39 + .../src/vector_engine/image_source.rs | 18 +- .../platform-image/src/vector_engine/mod.rs | 4 +- .../src/vector_engine/request.rs | 11 +- .../src/vector_engine/response.rs | 39 + .../platform-image/src/vector_engine/types.rs | 3 + .../platform-image/src/vector_engine/util.rs | 7 + .../platform-image/tests/vector_engine.rs | 381 ++++++++- 22 files changed, 1372 insertions(+), 225 deletions(-) diff --git a/.codex/skills/gpt-image-2-apimart/SKILL.md b/.codex/skills/gpt-image-2-apimart/SKILL.md index 99caa76b4..f350d98a5 100644 --- a/.codex/skills/gpt-image-2-apimart/SKILL.md +++ b/.codex/skills/gpt-image-2-apimart/SKILL.md @@ -1,11 +1,11 @@ --- name: gpt-image-2-apimart -description: Generate or inspect project image assets through this repository's VectorEngine gpt-image-2 workflow. Use when Codex needs to create puzzle template sample images, reproduce the server-rs gpt-image-2 request body, dry-run image prompts, batch-generate local project thumbnails, or debug VECTOR_ENGINE_BASE_URL / VECTOR_ENGINE_API_KEY image-generation configuration without exposing secrets. The directory name is historical. +description: Generate or inspect project image assets through this repository's VectorEngine gpt-image-2 workflow with gpt-image-2-c fallback. Use when Codex needs to create puzzle template sample images, reproduce the server-rs image request body, dry-run image prompts, batch-generate local project thumbnails, or debug VECTOR_ENGINE_BASE_URL / VECTOR_ENGINE_API_KEY image-generation configuration without exposing secrets. The directory name is historical. --- # gpt-image-2 VectorEngine -Use this skill for project-local image asset generation that must match the repository's `server-rs` VectorEngine `gpt-image-2` path. The folder still contains `apimart` in its name for compatibility with existing local plugin references. +Use this skill for project-local image asset generation that must match the repository's `server-rs` VectorEngine image path. Keep the product/price model identifier and primary provider request as `gpt-image-2`, then fall back once to `gpt-image-2-c` for eligible provider failures. The folder still contains `apimart` in its name for compatibility with existing local plugin references. ## Workflow @@ -65,9 +65,9 @@ size=1024x1024 image=@reference.png ``` -In this repository, calls with no reference images use `POST /v1/images/generations`; calls with any reference image use `POST /v1/images/edits` and pass references as one or more `image` form parts. Match3D container UI generation embeds `public/match3d-background-references/pot-fused-reference.png` into the edit request as an `image` part. +In this repository, calls with no reference images use `POST /v1/images/generations`; calls with any reference image use `POST /v1/images/edits` and pass references as one or more `image` form parts. Both paths prefer `gpt-image-2`; on an eligible upstream/model failure they retry with `gpt-image-2-c`. Do not fall back for authentication, local validation, request-budget exhaustion, uncertain send/connection failure, content-safety rejection, or a generated image URL download failure. Match3D container UI generation embeds `public/match3d-background-references/pot-fused-reference.png` into the edit request as an `image` part. -Accept image output from `data[].url`, `data[].b64_json`, or direct nested `url` fields. VectorEngine GPT-image-2 currently returns synchronously; do not poll APIMart task endpoints. +Accept image output from `data[].url`, `data[].b64_json`, or direct nested `url` fields. VectorEngine image generation currently returns synchronously; do not poll APIMart task endpoints. ## Environment diff --git a/.codex/skills/gpt-image-2-apimart/scripts/generate-anthro-cat-illustrations.mjs b/.codex/skills/gpt-image-2-apimart/scripts/generate-anthro-cat-illustrations.mjs index e3b1f99d7..071301778 100644 --- a/.codex/skills/gpt-image-2-apimart/scripts/generate-anthro-cat-illustrations.mjs +++ b/.codex/skills/gpt-image-2-apimart/scripts/generate-anthro-cat-illustrations.mjs @@ -9,6 +9,8 @@ const skillRoot = path.resolve(__dirname, '..'); const repoRoot = path.resolve(skillRoot, '..', '..', '..'); const defaultOutDir = path.join(repoRoot, 'public', 'anthro-cat-illustrations'); const defaultTimeoutMs = 1000000; +const preferredImageModel = 'gpt-image-2'; +const fallbackImageModel = 'gpt-image-2-c'; const prompts = [ { @@ -165,6 +167,25 @@ function extractBase64Images(payload) { return values; } +function decodeStrictBase64Image(raw) { + const normalized = String(raw || '').trim(); + if ( + !normalized || + normalized.length % 4 !== 0 || + !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u.test( + normalized, + ) + ) { + return null; + } + const bytes = Buffer.from(normalized, 'base64'); + return bytes.length > 0 && + bytes.toString('base64') === normalized && + inferExtensionFromBytes(bytes) + ? bytes + : null; +} + function inferExtensionFromContentType(contentType) { const normalized = contentType.split(';')[0]?.trim().toLowerCase(); if (normalized === 'image/png') { @@ -192,7 +213,13 @@ function inferExtensionFromBytes(bytes) { ) { return 'webp'; } - return 'png'; + if ( + bytes.subarray(0, 6).toString('ascii') === 'GIF87a' || + bytes.subarray(0, 6).toString('ascii') === 'GIF89a' + ) { + return 'gif'; + } + return null; } async function fetchJson(url, options, timeoutMs) { @@ -205,9 +232,20 @@ async function fetchJson(url, options, timeoutMs) { }); const text = await response.text(); if (!response.ok) { - throw new Error(`VectorEngine ${response.status}: ${text.slice(0, 600)}`); + const error = new Error( + `VectorEngine ${response.status}: ${text.slice(0, 600)}`, + ); + error.vectorEngineStatus = response.status; + error.vectorEngineBody = text; + throw error; + } + try { + return JSON.parse(text); + } catch (error) { + error.vectorEngineResponseParse = true; + error.vectorEngineBody = text; + throw error; } - return JSON.parse(text); } catch (error) { if (error?.name === 'AbortError') { throw new Error(`VectorEngine request timed out after ${timeoutMs}ms`); @@ -218,6 +256,83 @@ async function fetchJson(url, options, timeoutMs) { } } +function shouldFallbackImageModel(error) { + const raw = `${error?.message || ''}\n${error?.vectorEngineBody || ''}`.toLowerCase(); + if (error?.vectorEngineResponseParse) { + return !containsContentRejection(raw); + } + const status = Number(error?.vectorEngineStatus || 0); + if (status === 408 || status >= 500) { + return true; + } + if (status === 429) { + return !containsContentRejection(raw); + } + const mentionsImageModel = + raw.includes('model') || + raw.includes('模型') || + raw.includes(preferredImageModel) || + raw.includes(fallbackImageModel); + return ( + [400, 404, 422].includes(status) && + mentionsImageModel && + /(not found|not supported|unsupported|unavailable|does not exist|invalid model|unknown model|不存在|不支持|不可用|未开通)/u.test( + raw, + ) + ); +} + +function containsContentRejection(raw) { + return /(invalid_prompt|safety|content[_ ]policy|moderation|prompt rejected|content rejected|prompt refusal|content refusal|rejected by safety|rejected by moderation|敏感|违规|安全策略|内容审核|提示词拒绝|内容拒绝)/u.test( + raw, + ); +} + +async function requestImagePayload(env, entry) { + for (const model of [preferredImageModel, fallbackImageModel]) { + const requestBody = { + model, + prompt: buildPrompt(entry), + n: 1, + size: '1024x1024', + }; + try { + const payload = await fetchJson( + buildVectorEngineImagesGenerationUrl(env.baseUrl), + { + method: 'POST', + headers: { + Authorization: `Bearer ${env.apiKey}`, + Accept: 'application/json', + 'Content-Type': 'application/json', + }, + body: JSON.stringify(requestBody), + }, + env.timeoutMs, + ); + const base64Image = decodeStrictBase64Image(extractBase64Images(payload)[0]); + if ( + extractImageUrls(payload)[0] || + base64Image + ) { + return payload; + } + const error = new Error(`VectorEngine returned no image for ${entry.id}`); + error.vectorEngineResponseParse = true; + error.vectorEngineBody = JSON.stringify(payload).slice(0, 600); + throw error; + } catch (error) { + if (model !== preferredImageModel || !shouldFallbackImageModel(error)) { + throw error; + } + console.warn( + `VectorEngine ${preferredImageModel} failed, retrying with ${fallbackImageModel}: ${error.message}`, + ); + } + } + throw new Error(`VectorEngine returned no image for ${entry.id}`); +} + async function downloadUrl(url, timeoutMs) { const abortController = new AbortController(); const timer = setTimeout(() => abortController.abort(), timeoutMs); @@ -244,25 +359,7 @@ async function downloadUrl(url, timeoutMs) { } async function generateOne(env, entry, outDir) { - const requestBody = { - model: 'gpt-image-2', - prompt: buildPrompt(entry), - n: 1, - size: '1024x1024', - }; - const payload = await fetchJson( - buildVectorEngineImagesGenerationUrl(env.baseUrl), - { - method: 'POST', - headers: { - Authorization: `Bearer ${env.apiKey}`, - Accept: 'application/json', - 'Content-Type': 'application/json', - }, - body: JSON.stringify(requestBody), - }, - env.timeoutMs, - ); + const payload = await requestImagePayload(env, entry); const urls = extractImageUrls(payload); const b64Images = extractBase64Images(payload); @@ -271,7 +368,10 @@ async function generateOne(env, entry, outDir) { if (urls[0]) { image = await downloadUrl(urls[0], env.timeoutMs); } else if (b64Images[0]) { - const bytes = Buffer.from(b64Images[0], 'base64'); + const bytes = decodeStrictBase64Image(b64Images[0]); + if (!bytes) { + throw new Error(`VectorEngine returned invalid base64 image for ${entry.id}`); + } image = { bytes, extension: inferExtensionFromBytes(bytes), @@ -304,8 +404,9 @@ if (dryRun) { requests: selectedPrompts.map((entry) => ({ id: entry.id, title: entry.title, + fallbackModel: fallbackImageModel, body: { - model: 'gpt-image-2', + model: preferredImageModel, prompt: buildPrompt(entry), n: 1, size: '1024x1024', diff --git a/.codex/skills/gpt-image-2-apimart/scripts/generate-template-samples.mjs b/.codex/skills/gpt-image-2-apimart/scripts/generate-template-samples.mjs index 165dac017..4f1c37e42 100644 --- a/.codex/skills/gpt-image-2-apimart/scripts/generate-template-samples.mjs +++ b/.codex/skills/gpt-image-2-apimart/scripts/generate-template-samples.mjs @@ -14,6 +14,8 @@ const promptsPath = path.join( ); const defaultOutDir = path.join(repoRoot, 'public', 'puzzle-creation-templates'); const defaultTimeoutMs = 1000000; +const preferredImageModel = 'gpt-image-2'; +const fallbackImageModel = 'gpt-image-2-c'; const args = new Map(); for (let index = 2; index < process.argv.length; index += 1) { @@ -131,6 +133,25 @@ function extractBase64Images(payload) { return values; } +function decodeStrictBase64Image(raw) { + const normalized = String(raw || '').trim(); + if ( + !normalized || + normalized.length % 4 !== 0 || + !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u.test( + normalized, + ) + ) { + return null; + } + const bytes = Buffer.from(normalized, 'base64'); + return bytes.length > 0 && + bytes.toString('base64') === normalized && + inferExtensionFromBytes(bytes) + ? bytes + : null; +} + function inferExtensionFromContentType(contentType) { const normalized = contentType.split(';')[0]?.trim().toLowerCase(); if (normalized === 'image/png') { @@ -158,7 +179,13 @@ function inferExtensionFromBytes(bytes) { ) { return 'webp'; } - return 'png'; + if ( + bytes.subarray(0, 6).toString('ascii') === 'GIF87a' || + bytes.subarray(0, 6).toString('ascii') === 'GIF89a' + ) { + return 'gif'; + } + return null; } async function fetchJson(url, options, timeoutMs) { @@ -171,9 +198,20 @@ async function fetchJson(url, options, timeoutMs) { }); const text = await response.text(); if (!response.ok) { - throw new Error(`VectorEngine ${response.status}: ${text.slice(0, 600)}`); + const error = new Error( + `VectorEngine ${response.status}: ${text.slice(0, 600)}`, + ); + error.vectorEngineStatus = response.status; + error.vectorEngineBody = text; + throw error; + } + try { + return JSON.parse(text); + } catch (error) { + error.vectorEngineResponseParse = true; + error.vectorEngineBody = text; + throw error; } - return JSON.parse(text); } catch (error) { if (error?.name === 'AbortError') { throw new Error(`VectorEngine request timed out after ${timeoutMs}ms`); @@ -184,6 +222,83 @@ async function fetchJson(url, options, timeoutMs) { } } +function shouldFallbackImageModel(error) { + const raw = `${error?.message || ''}\n${error?.vectorEngineBody || ''}`.toLowerCase(); + if (error?.vectorEngineResponseParse) { + return !containsContentRejection(raw); + } + const status = Number(error?.vectorEngineStatus || 0); + if (status === 408 || status >= 500) { + return true; + } + if (status === 429) { + return !containsContentRejection(raw); + } + const mentionsImageModel = + raw.includes('model') || + raw.includes('模型') || + raw.includes(preferredImageModel) || + raw.includes(fallbackImageModel); + return ( + [400, 404, 422].includes(status) && + mentionsImageModel && + /(not found|not supported|unsupported|unavailable|does not exist|invalid model|unknown model|不存在|不支持|不可用|未开通)/u.test( + raw, + ) + ); +} + +function containsContentRejection(raw) { + return /(invalid_prompt|safety|content[_ ]policy|moderation|prompt rejected|content rejected|prompt refusal|content refusal|rejected by safety|rejected by moderation|敏感|违规|安全策略|内容审核|提示词拒绝|内容拒绝)/u.test( + raw, + ); +} + +async function requestImagePayload(env, template) { + for (const model of [preferredImageModel, fallbackImageModel]) { + const requestBody = { + model, + prompt: buildPrompt(template), + n: 1, + size: '1024x1024', + }; + try { + const payload = await fetchJson( + buildVectorEngineImagesGenerationUrl(env.baseUrl), + { + method: 'POST', + headers: { + Authorization: `Bearer ${env.apiKey}`, + Accept: 'application/json', + 'Content-Type': 'application/json', + }, + body: JSON.stringify(requestBody), + }, + env.timeoutMs, + ); + const base64Image = decodeStrictBase64Image(extractBase64Images(payload)[0]); + if ( + extractImageUrls(payload)[0] || + base64Image + ) { + return payload; + } + const error = new Error(`VectorEngine returned no image for ${template.id}`); + error.vectorEngineResponseParse = true; + error.vectorEngineBody = JSON.stringify(payload).slice(0, 600); + throw error; + } catch (error) { + if (model !== preferredImageModel || !shouldFallbackImageModel(error)) { + throw error; + } + console.warn( + `VectorEngine ${preferredImageModel} failed, retrying with ${fallbackImageModel}: ${error.message}`, + ); + } + } + throw new Error(`VectorEngine returned no image for ${template.id}`); +} + async function downloadUrl(url, timeoutMs) { const abortController = new AbortController(); const timer = setTimeout(() => abortController.abort(), timeoutMs); @@ -210,25 +325,7 @@ async function downloadUrl(url, timeoutMs) { } async function generateOne(env, template, outDir) { - const requestBody = { - model: 'gpt-image-2', - prompt: buildPrompt(template), - n: 1, - size: '1024x1024', - }; - const payload = await fetchJson( - buildVectorEngineImagesGenerationUrl(env.baseUrl), - { - method: 'POST', - headers: { - Authorization: `Bearer ${env.apiKey}`, - Accept: 'application/json', - 'Content-Type': 'application/json', - }, - body: JSON.stringify(requestBody), - }, - env.timeoutMs, - ); + const payload = await requestImagePayload(env, template); const urls = extractImageUrls(payload); const b64Images = extractBase64Images(payload); @@ -237,7 +334,10 @@ async function generateOne(env, template, outDir) { if (urls[0]) { image = await downloadUrl(urls[0], env.timeoutMs); } else if (b64Images[0]) { - const bytes = Buffer.from(b64Images[0], 'base64'); + const bytes = decodeStrictBase64Image(b64Images[0]); + if (!bytes) { + throw new Error(`VectorEngine returned invalid base64 image for ${template.id}`); + } image = { bytes, extension: inferExtensionFromBytes(bytes), @@ -274,8 +374,9 @@ if (dryRun) { requests: selectedTemplates.map((template) => ({ id: template.id, title: template.title, + fallbackModel: fallbackImageModel, body: { - model: 'gpt-image-2', + model: preferredImageModel, prompt: buildPrompt(template), n: 1, size: '1024x1024', diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md index bf492c40e..9d3707cb2 100644 --- a/docs/project-memory/shared-memory/decision-log.md +++ b/docs/project-memory/shared-memory/decision-log.md @@ -4366,3 +4366,10 @@ ## 2026-07-20 VectorEngine 图片任务预算收口到 worker deadline - 决策：`editor_image_generation`、`editor_image_edit`、`editor_icon_spritesheet_generation` 和 `editor_ui_design_asset_extraction` 使用默认 `1800s` long job 预算。worker 从同一起点计算绝对 job deadline，并向 provider 提前保留 `min(60s, job 预算 / 2)` 作为审计、OSS 和终态写回窗口。deadline 只经进程内 `RequestContext` 传递；VectorEngine 单 attempt 取配置 timeout 与剩余预算的较小值，退避加下一次 attempt 无法落在同一 deadline 内时停止重试，参考图和响应图片下载也受同一 deadline 限制。普通 HTTP / `inline` 保持无 deadline 行为；`VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS` 默认仍为 `1000000`，配置加载层允许显式值更低。lease 续租 / fencing、迟到写回仲裁、attempt 耗尽和原子退款语义不变。 + +## 2026-07-21 VectorEngine 图片首选 gpt-image-2 并以 gpt-image-2-c 兜底 + +- 决策：前端、DTO、计费配置、持久化和 `platform-image` 的 `/v1/images/generations` / `/v1/images/edits` provider 首选请求统一使用 `gpt-image-2`；符合条件时才回退到兜底模型 `gpt-image-2-c`。不在业务 handler、前端或价格表中新增平行模型。 +- 回退边界：明确模型不存在 / 不支持、408、非内容拒绝类 429、5xx、响应解析失败或非拒绝类缺图可以切模型；401 / 403、普通参数 / 内容安全拒绝、本地配置与参考图错误、发送 / 连接错误、request budget 耗尽和已生成图片下载失败不切模型。一次业务请求总发送上限仍为 5 次，两个模型共享同一 worker provider deadline 和 attempt 预算。 +- 观测边界：审计 `image_model` 记录实际 provider attempt；首选 `gpt-image-2` 失败但兜底 `gpt-image-2-c` 恢复成功时，首选失败仍写入 `external_api_call_failure`，最终成功运行摘要记录 `recoveredFailureCount`。日志用 `fallback_from_model` / `fallback_to_model` 标识切换，不改变业务模型、扣费、素材 metadata 或终态语义。 +- 脚本边界：仓库 `gpt-image-2-apimart` skill 的现役生成脚本采用同一首选 / 回退顺序；认证、请求发送不确定错误和下载失败不重新生图，避免重复上游成本。 diff --git a/docs/project-memory/shared-memory/pitfalls.md b/docs/project-memory/shared-memory/pitfalls.md index 151270cee..cf3d0996f 100644 --- a/docs/project-memory/shared-memory/pitfalls.md +++ b/docs/project-memory/shared-memory/pitfalls.md @@ -1510,7 +1510,7 @@ - 现象：配置了 `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`。 +- 处理：为图片生成配置 `VECTOR_ENGINE_BASE_URL=https://api.vectorengine.ai`、`VECTOR_ENGINE_API_KEY`、`VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS`；排查请求体时确认无参考图路径为 `/v1/images/generations`、有参考图路径为 `/v1/images/edits`，业务 / 计费与 provider 首发模型均为 `gpt-image-2`，仅在符合条件的 provider 失败后切到兜底模型 `gpt-image-2-c`。 - 验证：运行 `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`。 diff --git a/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md b/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md index 3ef5cad36..c631b90c2 100644 --- a/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md +++ b/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md @@ -158,7 +158,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 协议不再放在玩法模块里实现。VectorEngine `gpt-image-2` 创建 / 编辑协议、URL / base64 图片解析、远端图片下载、请求超时 / 上游状态 / 响应解析 / 缺图 / 下载失败的结构化日志统一在 `server-rs/crates/platform-image/src/vector_engine/`；其中 `client.rs` 只保留 provider 调用编排，`transport.rs` 负责 HTTP client 与 reqwest 错误归一，`request.rs` 负责请求体和路径，`payload.rs` 负责响应 JSON 字段提取，`response.rs` 负责响应状态分流和图片结果归一。`api-server` 只负责配置校验、玩法 prompt 编排、OSS / asset object / binding 持久化、计费和外部 API 失败审计落库。 +5. 图片 provider 协议不再放在玩法模块里实现。产品、计费、DTO、持久化和 VectorEngine 创建 / 编辑首选请求统一使用 `gpt-image-2`；只有符合回退条件时，provider 边界才切到兜底模型 `gpt-image-2-c`。URL / base64 图片解析、远端图片下载、请求超时 / 上游状态 / 响应解析 / 缺图 / 下载失败的结构化日志统一在 `server-rs/crates/platform-image/src/vector_engine/`；其中 `client.rs` 只保留 provider 调用编排，`transport.rs` 负责 HTTP client 与 reqwest 错误归一，`request.rs` 负责请求体和路径，`payload.rs` 负责响应 JSON 字段提取，`response.rs` 负责响应状态分流和图片结果归一。`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 读取。 @@ -240,7 +240,7 @@ npm run check:server-rs-ddd ## 外部服务与资产 - LLM：通用 LLM 门面继续使用 `GENARRATIVE_LLM_*`；创意 Agent `gpt-5.4-mini` Chat Completions 文本链路已于 2026-06 从 APIMart 迁移到 VectorEngine，使用 `VECTOR_ENGINE_BASE_URL` / `VECTOR_ENGINE_API_KEY` 构造 OpenAI-compatible client，`api-server` 会把未带 `/v1` 的 VectorEngine base URL 规范化到 `/v1` 后请求 `/chat/completions`。通用 `/api/llm/chat/completions` 代理使用 `GENARRATIVE_LLM_PROVIDER=openai-compatible`、`GENARRATIVE_LLM_BASE_URL=https://api.vectorengine.cn/v1`、`GENARRATIVE_LLM_MODEL=gpt-5.4-mini`；未单独配置 `GENARRATIVE_LLM_API_KEY` 时可复用 `VECTOR_ENGINE_API_KEY`。`APIMART_BASE_URL` / `APIMART_API_KEY` 只作为历史残留，不再作为创意 Agent gpt-5.4-mini 客户端来源；后续排障时优先确认 VectorEngine `/v1/models`、`/v1/chat/completions` 和 `/v1/responses` 可用性。 -- 图片生成：VectorEngine `gpt-image-2` 图片 provider 归属 `platform-image`，密钥只在后端环境变量中；`api-server` 内的 `openai_image_generation.rs` 只是兼容调用面和外部失败审计桥接，不再承载 provider 协议实现。实际外部生成运行记录统一落 `tracking_event`，`event_key = external_generation_run`，metadata 记录开始 / 结束时间、耗时、状态、成功标记、失败原因、provider task id 和结果摘要，不再写回过时的 `ai_task`。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 与 provider 首选模型均固定为 `gpt-image-2`，只在明确模型不可用、408 / 非拒绝类 429 / 5xx、响应解析失败或非拒绝类缺图时切换兜底模型 `gpt-image-2-c`。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 数量；首选模型失败但兜底模型成功时，首选失败仍落 `external_api_call_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`、`fallback_from_model`、`fallback_to_model`、`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 → 阿里云 → 本地降级顺序。 diff --git a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md index 635934ce3..24cd48b95 100644 --- a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md +++ b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md @@ -153,9 +153,9 @@ spacetime sql "SELECT * FROM runtime_setting LIMIT 1" --server http:/ 本地 `spacetime` CLI / standalone 版本必须和 `server-rs/Cargo.toml` 里锁定的 `spacetimedb` 版本一致；当前统一版本为 `2.6.1`。若版本错配，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 && spacetime version use `，或在目标就是最新版本时执行 `spacetime version upgrade`，升级后重启 `npm run dev:spacetime` 再重试。当前 `scripts/dev.mjs` 会在启动和复用本地 SpacetimeDB 前写入并校验 `dev-spacetime-tool-version`。2.6.1 修复了 procedure context 中调用者 `Identity` / `ConnectionId` 始终为空的回归，依赖 `ctx.sender` 鉴权时必须同时确认宿主已升级。 -本地 `.env`、`.env.local` 或 `.env.secrets.local` 修改后必须重启 `api-server` 才会生效；若已经通过 `npm run dev` 启动完整联调，可在该终端输入 `rs api-server`。排查图片编辑器 VectorEngine 生成链路时，确认 `VECTOR_ENGINE_BASE_URL`、`VECTOR_ENGINE_API_KEY` 和 `VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS` 只在本地或服务器密钥文件中配置，不能写入 Git。`VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS` 是单次 attempt 的配置上限，默认 `1000000`；配置加载层允许显式值低于该默认值，不再在读取环境变量时强制抬高。VectorEngine `gpt-image-2` 图片协议、URL / base64 响应解析、远端图片下载和 provider 侧结构化日志在 `server-rs/crates/platform-image`；`api-server` 只做编辑器请求编排、OSS / asset 持久化、计费和失败审计落库。`platform-image` 会在 JSON 生成和 multipart 编辑请求发送前归一显式像素尺寸；若请求发送失败，先按同一 `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`。排查图片编辑器 VectorEngine 生成链路时，确认 `VECTOR_ENGINE_BASE_URL`、`VECTOR_ENGINE_API_KEY` 和 `VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS` 只在本地或服务器密钥文件中配置，不能写入 Git。`VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS` 是单次 attempt 的配置上限，默认 `1000000`；配置加载层允许显式值低于该默认值，不再在读取环境变量时强制抬高。业务模型和 VectorEngine provider 首选请求都使用 `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-2 family 规则归一显式像素尺寸；若请求发送失败，先按同一 `request_id` 查看 provider 日志与 `external_api_call_failure.metadata_json.errorSource`，当前 multipart `/v1/images/edits` 单独强制 HTTP/1.1。 -VectorEngine 图片生成 / 编辑在 `request_send` 阶段出现 `timeout`、`connect`、libcurl 35 SSL connect reset、libcurl 56 receive error / `unexpected eof while reading`、recv failure 等临时传输错误，或在 `upstream_status` 阶段收到 408 / 429 / 5xx（例如 Nginx HTML `502 Bad Gateway`）时，`platform-image` 会对同一请求最多发送 5 次；multipart 图片编辑每次重试都会重新构造 form，避免复用已消费的 body。worker 从 job 开始的同一时钟起点计算绝对 deadline，常规保留最后 `60` 秒给审计、OSS 和终态写回；job 预算小于 `120` 秒时保留一半。VectorEngine 单次 attempt timeout 取配置值和剩余 provider 预算的较小值；退避后已没有下一次 attempt 的预算时立即停止重试。该 deadline 覆盖参考图、provider 请求 / 响应和响应图片下载的整次 provider future，但只在 worker 进程内通过 `RequestContext` 传递；普通 HTTP / `inline` 没有该 deadline，继续保持原有 timeout 和重试行为。日志中 `VectorEngine 图片请求发送失败，准备重试` 或 `VectorEngine 图片上游状态可重试，准备重试` 表示本次失败确有预算进入下一次尝试；预算耗尽或最终仍失败时才会写入 `external_api_call_failure` 并返回 504 / 502。排查生产失败时应同时统计 retry 前的尝试日志和最终 audit，避免把一次用户请求内的多次发送误判成多个用户请求。这项收口不修改 lease 续租 / fencing、迟到写回仲裁、attempt 耗尽与原子退款语义。 +VectorEngine 图片生成 / 编辑在 `request_send` 阶段出现 `timeout`、`connect`、libcurl 35 SSL connect reset、libcurl 56 receive error / `unexpected eof while reading`、recv failure 等临时传输错误，或在 `upstream_status` 阶段收到 408 / 429 / 5xx（例如 Nginx HTML `502 Bad Gateway`）时，`platform-image` 会在一次业务请求总上限 5 次内处理；multipart 图片编辑每次重试都会重新构造 form，避免复用已消费的 body。首个 provider attempt 使用 `gpt-image-2`；明确模型不可用、408 / 非拒绝类 429 / 5xx、响应解析失败或非拒绝类缺图时，下一 attempt 直接切兜底模型 `gpt-image-2-c`，之后只在剩余次数内重试兜底模型。发送 / 连接错误无法确认上游是否已受理，只重试同一首选模型，不切模型；认证、普通参数、安全拒绝、图片下载和 budget 错误同样不切。worker 从 job 开始的同一时钟起点计算绝对 deadline，常规保留最后 `60` 秒给审计、OSS 和终态写回；job 预算小于 `120` 秒时保留一半。VectorEngine 单次 attempt timeout 取配置值和剩余 provider 预算的较小值；退避或模型切换后已没有下一次 attempt 的预算时立即停止。该 deadline 覆盖参考图、provider 请求 / 响应和响应图片下载的整次 provider future，但只在 worker 进程内通过 `RequestContext` 传递；普通 HTTP / `inline` 没有该 deadline，继续保持原有 timeout 和重试行为。日志中 `VectorEngine 首选图片模型失败，切换兼容模型` 会携带 `fallback_from_model` / `fallback_to_model`；即使回退成功，首选模型错误仍写入 `external_api_call_failure`，成功运行摘要的 `recoveredFailureCount` 同时递增。排查生产失败时应同时统计 fallback / retry 日志和最终 audit，避免把一次用户请求内的多次发送误判成多个用户请求。这项收口不修改 lease 续租 / fencing、迟到写回仲裁、attempt 耗尽与原子退款语义。 图片编辑器生成属于持久队列长任务：提交接口返回 job 后，前端通过 `/api/runtime/external-generation/jobs/{jobId}` 与编辑器项目资源状态收敛。生产排查小程序或 WebView `Failed to fetch` 时，若 Nginx access log 为 `499`、`upstream_status=-`，先按提交请求的 `request_id`、job id、worker 日志和 `external_api_call_failure` 对齐真实任务，不把客户端断开直接判定为 provider 失败。 @@ -603,7 +603,7 @@ OpenTelemetry 现阶段默认开启 OTLP traces / metrics / logs，但本地日 - debug exporter / Rider 转发都会同时接收 traces、metrics 和 logs。 - api-server 会随 metrics 发送进程级指标：`process.memory.usage`、`process.memory.virtual`、`process.cpu.time`、`genarrative.process.cpu.usage_percent`、`process.thread.count`、`genarrative.process.memory.private`；Windows 额外发送 `process.windows.handle.count`，Linux 额外发送 `process.unix.file_descriptor.count`。这些指标只描述当前进程，不携带请求、用户或作品 label。 - HTTP 运行态补充发送 `genarrative.http.server.response_bodies.in_flight` 与 `genarrative.http.server.request_permits.available`，后者带低基数 `pool=default|gallery|detail|admin` label，用于区分业务 handler / 背压 permit 是否仍被占用；拼图广场热点缓存补充发送 `genarrative.puzzle_gallery.cache.*` 指标，记录 fresh hit、stale hit、未命中、后台刷新开始 / 失败、重建耗时和预序列化 data JSON 字节数。 -- 外部 API 失败统一发送 OTLP 并落库。当前 VectorEngine `gpt-image-2` 图片生成 / 编辑失败由 `platform-image` provider 输出结构化日志字段，字段包括 provider、endpoint、failure_stage、status、source、source_chain、source_chain_depth、timeout、retryable、latency_ms、prompt_chars、reference_image_count、image_model、request_params 和 raw_excerpt；图片编辑请求参数日志还会带 reference_image_bytes_total，并在 request_params.referenceImages 中记录每个 multipart `image` part 的 fileName、mimeType 和 bytes，不记录 API key 或原始图片 bytes；`api-server` 再记录指标 `genarrative.external_api.failures{provider,failure_stage,status_class,retryable}`，并写入 `tracking_event`，`event_key = external_api_call_failure`、`module_key = external-api`、`scope_kind = module`、`scope_id = provider`。调用方能拿到身份上下文时，失败事件还会在行级 `user_id` / `owner_user_id` / `profile_id` 和 `metadata_json.userId` / `metadata_json.profileId` / `metadata_json.requestId` / `metadata_json.errorSource` 中记录触发者、草稿 / 作品作用域、请求标识和传输错误链。排障时先按 provider / failureStage 聚合，再下钻 userId / profileId，最后结合 request 日志、errorSource 和上游响应 excerpt 判断是限流、超时、解析失败还是未返回图片。 +- 外部 API 失败统一发送 OTLP 并落库。当前 VectorEngine 图片生成 / 编辑失败由 `platform-image` provider 输出结构化日志字段，字段包括 provider、endpoint、failure_stage、status、source、source_chain、source_chain_depth、timeout、retryable、latency_ms、prompt_chars、reference_image_count、实际 provider `image_model`、request_params 和 raw_excerpt；发生模型回退时另带 `fallback_from_model` / `fallback_to_model`。图片编辑请求参数日志还会带 reference_image_bytes_total，并在 request_params.referenceImages 中记录每个 multipart `image` part 的 fileName、mimeType 和 bytes，不记录 API key 或原始图片 bytes；`api-server` 再记录指标 `genarrative.external_api.failures{provider,failure_stage,status_class,retryable}`，并写入 `tracking_event`，`event_key = external_api_call_failure`、`module_key = external-api`、`scope_kind = module`、`scope_id = provider`。调用方能拿到身份上下文时，失败事件还会在行级 `user_id` / `owner_user_id` / `profile_id` 和 `metadata_json.userId` / `metadata_json.profileId` / `metadata_json.requestId` / `metadata_json.errorSource` 中记录触发者、草稿 / 作品作用域、请求标识和传输错误链。排障时先按 provider / failureStage / imageModel 聚合，再下钻 userId / profileId，最后结合 request 日志、errorSource 和上游响应 excerpt 判断是模型不可用、限流、超时、解析失败还是未返回图片。 - OSS 平台适配器也输出结构化日志，覆盖 `sign_post_object`、`sign_get_object_url`、`head_object` 和 `put_object`。排查资产签名、上传或确认失败时，先按 `provider=aliyun-oss` 与 `operation` 过滤，再看 `object_key` / `key_prefix`、`status`、`status_class`、`error_kind`、`content_length`、`content_type` 和 `elapsed_ms`；角色动画逐帧额外按 `frame_index`、`operation=source_put|final_put|final_head`、`attempt/max_attempts`、`will_retry`、`oss_code` 和 `oss_request_id` 对齐同一对象的请求尝试。`请求 OSS 失败` 时，`timeout/connect/transport=true` 表示传输类失败，OSS PutObject 的 `status=400, oss_code=RequestTimeout, timeout=true`、`status=429` 或 `500–599` 表示暂时性失败，PUT 的 `status=400`、`oss_code` 为空且 `timeout=true` 或 `transport=true`（message 含「错误响应体读取失败」，即 400 错误体读取超时/断流）也会重试；除这两类例外外，其他 400、401/403/404、配置、URL 和签名错误是确定性失败，不会重试。最终帧 HEAD 失败只会重试 HEAD，不会重复 PUT。日志不得包含 AccessKey、policy、signature、Authorization header、完整 signed URL 或 OSS 错误响应体；`oss_request_id` 只用于关联 OSS 服务端排障。排查 generated 图片重复下载时，先确认前端输入是否为 `/generated-*` legacy path 或可归一化的 `https://*.oss-*.aliyuncs.com/generated-*`；正确链路应先调 `/api/assets/read-url`，再由浏览器请求 signed URL，且同一路径、同一 `refreshKey` 版本和未临近过期的 signed URL 应复用。新上传 generated 私有对象应带 `Cache-Control: public, max-age=31536000, immutable`；旧对象若只有 `ETag` / `Last-Modified`，浏览器会走 304 协商缓存而不是长期强缓存，可通过刷新 OSS 元数据或 CDN 配置补齐。 - SpacetimeDB 观测分为两类：procedure / reducer 调用继续用 `genarrative.spacetime.procedure.*`，订阅本地 cache 读使用 `genarrative.spacetime.read.*`。`read=list_puzzle_gallery` 表示拼图广场当前从 `puzzle_gallery_card_view` 本地 cache 读取，不再每个 HTTP 请求调用 `list_puzzle_gallery` procedure。 - 本地 Windows 直连压测的内存高水位要结合 K6 VU / 连接数解释。250 RPS 下过高 `PREALLOCATED_VUS` 可能让 300 个本地 Established 连接把 `api-server` private memory 瞬时推到 GB 级，且 `/healthz` 小响应也能复现；若压测结束后回落、`response_bodies.in_flight` 和背压 permit 未显示业务积压，应优先按连接 / 发送链路高水位处理，而不是判断为 SpacetimeDB 或 JSON 缓存泄漏。 diff --git a/server-rs/crates/api-server/src/openai_image_generation.rs b/server-rs/crates/api-server/src/openai_image_generation.rs index 55ee30c46..e3e381eb5 100644 --- a/server-rs/crates/api-server/src/openai_image_generation.rs +++ b/server-rs/crates/api-server/src/openai_image_generation.rs @@ -434,6 +434,9 @@ async fn map_platform_image_result( ) -> Result { match result { Ok(value) => { + for audit in &value.recovered_failure_audits { + record_openai_image_failure_audit_if_configured(settings, audit).await; + } if let Some(state) = settings.external_api_audit_state.as_ref() { record_external_generation_run_after_success( state, @@ -448,6 +451,7 @@ async fn map_platform_image_result( Some(json!({ "imageCount": value.images.len(), "actualPromptChars": value.actual_prompt.as_ref().map(|prompt| prompt.chars().count()), + "recoveredFailureCount": value.recovered_failure_audits.len(), })), ) .await; @@ -455,6 +459,9 @@ async fn map_platform_image_result( Ok(value) } Err(error) => { + for audit in error.recovered_failure_audits() { + record_openai_image_failure_audit_if_configured(settings, audit).await; + } if let Some(state) = settings.external_api_audit_state.as_ref() { record_external_generation_run_after_success( state, @@ -478,14 +485,21 @@ async fn map_platform_image_result( pub(crate) async fn record_openai_image_failure_if_configured( settings: &OpenAiImageSettings, error: &PlatformImageError, +) { + let Some(audit) = error.audit() else { + return; + }; + record_openai_image_failure_audit_if_configured(settings, audit).await; +} + +async fn record_openai_image_failure_audit_if_configured( + settings: &OpenAiImageSettings, + audit: &platform_image::PlatformImageFailureAudit, ) { let Some(state) = settings.external_api_audit_state.as_ref() else { return; }; - let Some(draft) = build_openai_image_failure_audit_draft(error) else { - return; - }; - let draft = draft + let draft = build_external_api_failure_draft_from_platform_image_audit(audit) .with_user_id(settings.external_api_audit_user_id.clone()) .with_profile_id(settings.external_api_audit_profile_id.clone()) .with_request_id(settings.external_api_audit_request_id.clone()); @@ -501,6 +515,7 @@ pub(crate) fn build_openai_image_failure_audit_draft( } pub(crate) fn map_platform_image_error(error: PlatformImageError) -> AppError { + let error = error.into_final_error(); let status = match error.status_hint() { PlatformImageStatusHint::BadRequest => StatusCode::BAD_REQUEST, PlatformImageStatusHint::ServiceUnavailable => StatusCode::SERVICE_UNAVAILABLE, @@ -545,6 +560,9 @@ pub(crate) fn map_platform_image_error(error: PlatformImageError) -> AppError { details["rawExcerpt"] = json!(raw_excerpt); } PlatformImageError::MissingImage { .. } => {} + PlatformImageError::FallbackFailed { .. } => { + unreachable!("fallback wrapper should be removed before HTTP error mapping") + } } if let Some(audit) = error.audit() { diff --git a/server-rs/crates/platform-image/src/lib.rs b/server-rs/crates/platform-image/src/lib.rs index 4e7aaa896..95495b218 100644 --- a/server-rs/crates/platform-image/src/lib.rs +++ b/server-rs/crates/platform-image/src/lib.rs @@ -3,7 +3,7 @@ pub mod generated_assets; pub mod vector_engine; pub use vector_engine::{ - DownloadedImage, GPT_IMAGE_2_MODEL, GeneratedImages, PlatformImageError, + DownloadedImage, GPT_IMAGE_2_C_MODEL, GPT_IMAGE_2_MODEL, GeneratedImages, PlatformImageError, PlatformImageFailureAudit, PlatformImageStatusHint, ReferenceImage, VECTOR_ENGINE_GPT_IMAGE_2_MODEL, VECTOR_ENGINE_PROVIDER, VectorEngineImageSettings, build_vector_engine_image_http_client, build_vector_engine_image_request_body, diff --git a/server-rs/crates/platform-image/src/vector_engine/audit.rs b/server-rs/crates/platform-image/src/vector_engine/audit.rs index c28381d57..41bef9a6d 100644 --- a/server-rs/crates/platform-image/src/vector_engine/audit.rs +++ b/server-rs/crates/platform-image/src/vector_engine/audit.rs @@ -1,4 +1,4 @@ -use super::constants::{VECTOR_ENGINE_GPT_IMAGE_2_MODEL, VECTOR_ENGINE_PROVIDER}; +use super::constants::VECTOR_ENGINE_PROVIDER; #[derive(Clone, Debug)] pub struct PlatformImageFailureAudit { @@ -33,6 +33,7 @@ pub(crate) fn build_failure_audit( latency_ms: Option, prompt_chars: Option, reference_image_count: Option, + image_model: Option<&'static str>, ) -> PlatformImageFailureAudit { PlatformImageFailureAudit { provider: VECTOR_ENGINE_PROVIDER, @@ -49,7 +50,7 @@ pub(crate) fn build_failure_audit( latency_ms, prompt_chars, reference_image_count, - image_model: Some(VECTOR_ENGINE_GPT_IMAGE_2_MODEL), + image_model, } } diff --git a/server-rs/crates/platform-image/src/vector_engine/budget.rs b/server-rs/crates/platform-image/src/vector_engine/budget.rs index a7c82ec46..02f099344 100644 --- a/server-rs/crates/platform-image/src/vector_engine/budget.rs +++ b/server-rs/crates/platform-image/src/vector_engine/budget.rs @@ -53,6 +53,7 @@ fn retry_delay_fits_request_deadline_at( pub(crate) fn request_budget_exhausted_error( request_url: &str, operation: &str, + image_model: Option<&'static str>, latency_ms: Option, prompt_chars: Option, reference_image_count: Option, @@ -73,6 +74,7 @@ pub(crate) fn request_budget_exhausted_error( latency_ms, prompt_chars, reference_image_count, + image_model, ); tracing::warn!( provider = VECTOR_ENGINE_PROVIDER, @@ -82,6 +84,7 @@ pub(crate) fn request_budget_exhausted_error( elapsed_ms = latency_ms, prompt_chars, reference_image_count, + image_model, operation, "VectorEngine 图片请求执行预算已耗尽" ); @@ -162,6 +165,7 @@ mod tests { let error = request_budget_exhausted_error( "https://vector.example/v1/images/generations", "生成图片失败", + None, Some(900), Some(12), Some(1), diff --git a/server-rs/crates/platform-image/src/vector_engine/client.rs b/server-rs/crates/platform-image/src/vector_engine/client.rs index 54647031f..c71b2c8ab 100644 --- a/server-rs/crates/platform-image/src/vector_engine/client.rs +++ b/server-rs/crates/platform-image/src/vector_engine/client.rs @@ -9,7 +9,7 @@ use super::{ effective_request_timeout_ms, request_budget_exhausted_error, retry_delay_fits_request_deadline, }, - constants::{GPT_IMAGE_2_MODEL, VECTOR_ENGINE_PROVIDER}, + constants::{GPT_IMAGE_2_C_MODEL, GPT_IMAGE_2_MODEL, VECTOR_ENGINE_PROVIDER}, curl_transport::{ map_curl_error, send_vector_engine_json_request_with_curl, send_vector_engine_multipart_edit_request_with_curl, @@ -19,7 +19,7 @@ use super::{ request::{ build_vector_engine_image_edit_request_log_params, build_vector_engine_image_request_body_with_model, - build_vector_engine_nanobanana_generate_content_request_body, + build_vector_engine_nanobanana_generate_content_request_body, is_gpt_image_2_family_model, normalize_image_size_for_model, normalize_vector_engine_image_model, vector_engine_images_edit_url, vector_engine_images_generation_url, vector_engine_nanobanana_generate_content_url, @@ -65,7 +65,7 @@ pub async fn create_vector_engine_image_generation_with_model( reference_images: &[String], failure_context: &str, ) -> Result { - let model = normalize_vector_engine_image_model(model); + let requested_model = normalize_vector_engine_image_model(model); if !reference_images.is_empty() { let resolved_references = resolve_reference_images( http_client, @@ -77,7 +77,7 @@ pub async fn create_vector_engine_image_generation_with_model( return create_vector_engine_image_edit_with_references_and_model( http_client, settings, - model, + requested_model, prompt, negative_prompt, size, @@ -89,30 +89,36 @@ pub async fn create_vector_engine_image_generation_with_model( } let request_url = vector_engine_images_generation_url(settings); - let normalized_size = normalize_image_size_for_model(model, size); - let request_body = build_vector_engine_image_request_body_with_model( - model, - prompt, - negative_prompt, - normalized_size.as_str(), - candidate_count, - reference_images, - ); + let normalized_size = normalize_image_size_for_model(requested_model, size); let started_at = std::time::Instant::now(); + let mut upstream_model = preferred_vector_engine_upstream_model(requested_model); + let mut recovered_failure_audits = Vec::new(); let mut attempt = 1; - let response = loop { + loop { + let request_body = build_vector_engine_image_request_body_with_model( + upstream_model, + prompt, + negative_prompt, + normalized_size.as_str(), + candidate_count, + reference_images, + ); let Some(attempt_timeout_ms) = effective_request_timeout_ms(settings.request_timeout_ms, settings.request_deadline) else { - return Err(request_budget_exhausted_error( - request_url.as_str(), - failure_context, - Some(started_at.elapsed().as_millis() as u64), - Some(prompt.chars().count()), - Some(reference_images.len()), + return Err(finish_vector_engine_model_fallback_error( + request_budget_exhausted_error( + request_url.as_str(), + failure_context, + auditable_vector_engine_image_model(upstream_model), + Some(started_at.elapsed().as_millis() as u64), + Some(prompt.chars().count()), + Some(reference_images.len()), + ), + &mut recovered_failure_audits, )); }; - match send_vector_engine_json_request_with_curl( + let response = match send_vector_engine_json_request_with_curl( request_url.as_str(), settings.api_key.as_str(), &request_body, @@ -121,7 +127,56 @@ pub async fn create_vector_engine_image_generation_with_model( .await { Ok(response) => { - if should_retry_vector_engine_upstream_status(response.status, attempt) { + if should_retry_vector_engine_upstream_response( + response.status, + response.body.as_str(), + attempt, + ) { + let primary_error = if upstream_model == GPT_IMAGE_2_MODEL { + handle_vector_engine_response( + http_client, + request_url.as_str(), + response.status, + response.body.as_str(), + auditable_vector_engine_image_model(upstream_model), + failure_context, + started_at.elapsed().as_millis() as u64, + Some(prompt.chars().count()), + Some(reference_images.len()), + candidate_count, + "vector-engine", + settings.request_deadline, + ) + .await + .err() + } else { + None + }; + if primary_error.as_ref().is_some_and(|error| { + should_fallback_to_gpt_image_2_c( + requested_model, + upstream_model, + attempt, + error, + settings, + ) + }) { + let error = primary_error.expect("primary error checked above"); + record_vector_engine_model_fallback( + "generation", + request_url.as_str(), + upstream_model, + GPT_IMAGE_2_C_MODEL, + attempt, + &error, + ); + if let Some(audit) = error.audit().cloned() { + recovered_failure_audits.push(audit); + } + upstream_model = GPT_IMAGE_2_C_MODEL; + attempt += 1; + continue; + } if retry_vector_engine_upstream_status_after_delay( "generation", request_url.as_str(), @@ -140,7 +195,7 @@ pub async fn create_vector_engine_image_generation_with_model( continue; } } - break response; + response } Err(error) => { if should_retry_vector_engine_curl_send_error(&error, attempt) { @@ -166,48 +221,91 @@ pub async fn create_vector_engine_image_generation_with_model( continue; } } - return Err(map_curl_error( - format!("{failure_context}：创建图片生成任务失败").as_str(), + return Err(finish_vector_engine_model_fallback_error( + map_curl_error( + format!("{failure_context}：创建图片生成任务失败").as_str(), + request_url.as_str(), + "request_send", + auditable_vector_engine_image_model(upstream_model), + error, + started_at.elapsed().as_millis() as u64, + Some(prompt.chars().count()), + Some(reference_images.len()), + Some(&request_body), + ), + &mut recovered_failure_audits, + )); + } + }; + let response_status = response.status; + tracing::info!( + provider = VECTOR_ENGINE_PROVIDER, + endpoint = %request_url, + status = response_status, + image_model = upstream_model, + requested_image_model = requested_model, + prompt_chars = prompt.chars().count(), + size = %normalized_size, + reference_image_count = reference_images.len(), + attempt, + elapsed_ms = started_at.elapsed().as_millis() as u64, + failure_context, + "VectorEngine 图片生成 HTTP 返回" + ); + let response_text = response.body; + match handle_vector_engine_response( + http_client, + request_url.as_str(), + response_status, + response_text.as_str(), + auditable_vector_engine_image_model(upstream_model), + failure_context, + started_at.elapsed().as_millis() as u64, + Some(prompt.chars().count()), + Some(reference_images.len()), + candidate_count, + "vector-engine", + settings.request_deadline, + ) + .await + { + Ok(mut generated) => { + generated + .recovered_failure_audits + .append(&mut recovered_failure_audits); + return Ok(generated); + } + Err(error) + if should_fallback_to_gpt_image_2_c( + requested_model, + upstream_model, + attempt, + &error, + settings, + ) => + { + record_vector_engine_model_fallback( + "generation", request_url.as_str(), - "request_send", + upstream_model, + GPT_IMAGE_2_C_MODEL, + attempt, + &error, + ); + if let Some(audit) = error.audit().cloned() { + recovered_failure_audits.push(audit); + } + upstream_model = GPT_IMAGE_2_C_MODEL; + attempt += 1; + } + Err(error) => { + return Err(finish_vector_engine_model_fallback_error( error, - started_at.elapsed().as_millis() as u64, - Some(prompt.chars().count()), - Some(reference_images.len()), - Some(&request_body), + &mut recovered_failure_audits, )); } } - }; - let response_status = response.status; - tracing::info!( - provider = VECTOR_ENGINE_PROVIDER, - endpoint = %request_url, - status = response_status, - image_model = model, - prompt_chars = prompt.chars().count(), - size = %normalized_size, - reference_image_count = reference_images.len(), - attempt, - elapsed_ms = started_at.elapsed().as_millis() as u64, - failure_context, - "VectorEngine 图片生成 HTTP 返回" - ); - let response_text = response.body; - handle_vector_engine_response( - http_client, - request_url.as_str(), - response_status, - response_text.as_str(), - failure_context, - started_at.elapsed().as_millis() as u64, - Some(prompt.chars().count()), - Some(reference_images.len()), - candidate_count, - "vector-engine", - settings.request_deadline, - ) - .await + } } #[allow(clippy::too_many_arguments)] @@ -260,6 +358,7 @@ pub async fn create_vector_engine_nanobanana_generate_content( return Err(request_budget_exhausted_error( request_url.as_str(), failure_context, + None, Some(started_at.elapsed().as_millis() as u64), Some(prompt.chars().count()), Some(reference_image_count), @@ -274,7 +373,11 @@ pub async fn create_vector_engine_nanobanana_generate_content( .await { Ok(response) => { - if should_retry_vector_engine_upstream_status(response.status, attempt) { + if should_retry_vector_engine_upstream_response( + response.status, + response.body.as_str(), + attempt, + ) { if retry_vector_engine_upstream_status_after_delay( "nanobanana_generate_content", request_url.as_str(), @@ -323,6 +426,7 @@ pub async fn create_vector_engine_nanobanana_generate_content( format!("{failure_context}：创建 nanobanana2 图片生成任务失败").as_str(), request_url.as_str(), "request_send", + None, error, started_at.elapsed().as_millis() as u64, Some(prompt.chars().count()), @@ -355,6 +459,7 @@ pub async fn create_vector_engine_nanobanana_generate_content( request_url.as_str(), response_status, response_text.as_str(), + None, failure_context, started_at.elapsed().as_millis() as u64, Some(prompt.chars().count()), @@ -424,7 +529,7 @@ pub async fn create_vector_engine_image_edit_with_references_and_model( reference_images: &[ReferenceImage], failure_context: &str, ) -> Result { - let model = normalize_vector_engine_image_model(model); + let requested_model = normalize_vector_engine_image_model(model); if reference_images.is_empty() { return Err(PlatformImageError::InvalidRequest { provider: VECTOR_ENGINE_PROVIDER, @@ -433,15 +538,7 @@ pub async fn create_vector_engine_image_edit_with_references_and_model( } let request_url = vector_engine_images_edit_url(settings); - let normalized_size = normalize_image_size_for_model(model, size); - let request_params = build_vector_engine_image_edit_request_log_params( - model, - prompt, - negative_prompt, - normalized_size.as_str(), - candidate_count, - reference_images, - ); + let normalized_size = normalize_image_size_for_model(requested_model, size); let reference_image_count = reference_images.iter().take(5).count(); let reference_image_bytes_total: usize = reference_images @@ -450,43 +547,59 @@ pub async fn create_vector_engine_image_edit_with_references_and_model( .map(|image| image.bytes.len()) .sum(); let started_at = std::time::Instant::now(); - tracing::info!( - provider = VECTOR_ENGINE_PROVIDER, - endpoint = %request_url, - image_model = model, - size = %normalized_size, - candidate_count = candidate_count.clamp(1, 4), - requested_candidate_count = candidate_count, - prompt_chars = prompt.trim().chars().count(), - negative_prompt_chars = negative_prompt - .map(str::trim) - .filter(|value| !value.is_empty()) - .map(str::chars) - .map(Iterator::count) - .unwrap_or_default(), - reference_image_count, - reference_image_bytes_total, - request_params = %request_params, - failure_context, - "VectorEngine 图片编辑请求参数" - ); + let mut upstream_model = preferred_vector_engine_upstream_model(requested_model); + let mut recovered_failure_audits = Vec::new(); let mut attempt = 1; - let response = loop { + loop { + let request_params = build_vector_engine_image_edit_request_log_params( + upstream_model, + prompt, + negative_prompt, + normalized_size.as_str(), + candidate_count, + reference_images, + ); + tracing::info!( + provider = VECTOR_ENGINE_PROVIDER, + endpoint = %request_url, + image_model = upstream_model, + requested_image_model = requested_model, + size = %normalized_size, + candidate_count = candidate_count.clamp(1, 4), + requested_candidate_count = candidate_count, + prompt_chars = prompt.trim().chars().count(), + negative_prompt_chars = negative_prompt + .map(str::trim) + .filter(|value| !value.is_empty()) + .map(str::chars) + .map(Iterator::count) + .unwrap_or_default(), + reference_image_count, + reference_image_bytes_total, + request_params = %request_params, + attempt, + failure_context, + "VectorEngine 图片编辑请求参数" + ); let Some(attempt_timeout_ms) = effective_request_timeout_ms(settings.request_timeout_ms, settings.request_deadline) else { - return Err(request_budget_exhausted_error( - request_url.as_str(), - failure_context, - Some(started_at.elapsed().as_millis() as u64), - Some(prompt.chars().count()), - Some(reference_image_count), + return Err(finish_vector_engine_model_fallback_error( + request_budget_exhausted_error( + request_url.as_str(), + failure_context, + auditable_vector_engine_image_model(upstream_model), + Some(started_at.elapsed().as_millis() as u64), + Some(prompt.chars().count()), + Some(reference_image_count), + ), + &mut recovered_failure_audits, )); }; - match send_vector_engine_multipart_edit_request_with_curl( + let response = match send_vector_engine_multipart_edit_request_with_curl( request_url.as_str(), settings.api_key.as_str(), - model, + upstream_model, prompt, negative_prompt, normalized_size.as_str(), @@ -497,7 +610,56 @@ pub async fn create_vector_engine_image_edit_with_references_and_model( .await { Ok(response) => { - if should_retry_vector_engine_upstream_status(response.status, attempt) { + if should_retry_vector_engine_upstream_response( + response.status, + response.body.as_str(), + attempt, + ) { + let primary_error = if upstream_model == GPT_IMAGE_2_MODEL { + handle_vector_engine_response( + http_client, + request_url.as_str(), + response.status, + response.body.as_str(), + auditable_vector_engine_image_model(upstream_model), + failure_context, + started_at.elapsed().as_millis() as u64, + Some(prompt.chars().count()), + Some(reference_image_count), + candidate_count, + "vector-engine-edit", + settings.request_deadline, + ) + .await + .err() + } else { + None + }; + if primary_error.as_ref().is_some_and(|error| { + should_fallback_to_gpt_image_2_c( + requested_model, + upstream_model, + attempt, + error, + settings, + ) + }) { + let error = primary_error.expect("primary error checked above"); + record_vector_engine_model_fallback( + "edit", + request_url.as_str(), + upstream_model, + GPT_IMAGE_2_C_MODEL, + attempt, + &error, + ); + if let Some(audit) = error.audit().cloned() { + recovered_failure_audits.push(audit); + } + upstream_model = GPT_IMAGE_2_C_MODEL; + attempt += 1; + continue; + } if retry_vector_engine_upstream_status_after_delay( "edit", request_url.as_str(), @@ -516,7 +678,7 @@ pub async fn create_vector_engine_image_edit_with_references_and_model( continue; } } - break response; + response } Err(error) => { if should_retry_vector_engine_curl_send_error(&error, attempt) { @@ -542,49 +704,238 @@ pub async fn create_vector_engine_image_edit_with_references_and_model( continue; } } - return Err(map_curl_error( - format!("{failure_context}：创建图片编辑任务失败").as_str(), + return Err(finish_vector_engine_model_fallback_error( + map_curl_error( + format!("{failure_context}：创建图片编辑任务失败").as_str(), + request_url.as_str(), + "request_send", + auditable_vector_engine_image_model(upstream_model), + error, + started_at.elapsed().as_millis() as u64, + Some(prompt.chars().count()), + Some(reference_image_count), + Some(&request_params), + ), + &mut recovered_failure_audits, + )); + } + }; + let response_status = response.status; + tracing::info!( + provider = VECTOR_ENGINE_PROVIDER, + endpoint = %request_url, + status = response_status, + image_model = upstream_model, + requested_image_model = requested_model, + prompt_chars = prompt.chars().count(), + size = %normalized_size, + reference_image_count, + reference_image_bytes_total, + request_params = %request_params, + attempt, + elapsed_ms = started_at.elapsed().as_millis() as u64, + failure_context, + "VectorEngine 图片编辑 HTTP 返回" + ); + let response_text = response.body; + match handle_vector_engine_response( + http_client, + request_url.as_str(), + response_status, + response_text.as_str(), + auditable_vector_engine_image_model(upstream_model), + failure_context, + started_at.elapsed().as_millis() as u64, + Some(prompt.chars().count()), + Some(reference_image_count), + candidate_count, + "vector-engine-edit", + settings.request_deadline, + ) + .await + { + Ok(mut generated) => { + generated + .recovered_failure_audits + .append(&mut recovered_failure_audits); + return Ok(generated); + } + Err(error) + if should_fallback_to_gpt_image_2_c( + requested_model, + upstream_model, + attempt, + &error, + settings, + ) => + { + record_vector_engine_model_fallback( + "edit", request_url.as_str(), - "request_send", + upstream_model, + GPT_IMAGE_2_C_MODEL, + attempt, + &error, + ); + if let Some(audit) = error.audit().cloned() { + recovered_failure_audits.push(audit); + } + upstream_model = GPT_IMAGE_2_C_MODEL; + attempt += 1; + } + Err(error) => { + return Err(finish_vector_engine_model_fallback_error( error, - started_at.elapsed().as_millis() as u64, - Some(prompt.chars().count()), - Some(reference_image_count), - Some(&request_params), + &mut recovered_failure_audits, )); } } - }; - let response_status = response.status; - tracing::info!( + } +} + +fn preferred_vector_engine_upstream_model(requested_model: &str) -> &str { + if is_gpt_image_2_family_model(requested_model) { + GPT_IMAGE_2_MODEL + } else { + requested_model + } +} + +fn finish_vector_engine_model_fallback_error( + error: PlatformImageError, + recovered_failure_audits: &mut Vec, +) -> PlatformImageError { + error.with_recovered_failure_audits(std::mem::take(recovered_failure_audits)) +} + +fn auditable_vector_engine_image_model(model: &str) -> Option<&'static str> { + match model { + GPT_IMAGE_2_C_MODEL => Some(GPT_IMAGE_2_C_MODEL), + GPT_IMAGE_2_MODEL => Some(GPT_IMAGE_2_MODEL), + _ => None, + } +} + +fn should_fallback_to_gpt_image_2_c( + requested_model: &str, + upstream_model: &str, + attempt: u32, + error: &PlatformImageError, + settings: &VectorEngineImageSettings, +) -> bool { + if !is_gpt_image_2_family_model(requested_model) + || upstream_model != GPT_IMAGE_2_MODEL + || attempt >= VECTOR_ENGINE_SEND_MAX_ATTEMPTS + || effective_request_timeout_ms(settings.request_timeout_ms, settings.request_deadline) + .is_none() + { + return false; + } + + match error { + PlatformImageError::Upstream { + upstream_status, + message, + raw_excerpt, + .. + } => match *upstream_status { + 408 => true, + 429 => !contains_vector_engine_content_rejection(message, raw_excerpt), + status if status >= 500 => true, + 400 | 404 | 422 => contains_vector_engine_model_unavailable(message, raw_excerpt), + _ => false, + }, + PlatformImageError::ResponseParse { + message, + raw_excerpt, + .. + } => !contains_vector_engine_content_rejection(message, raw_excerpt), + PlatformImageError::MissingImage { message, audit, .. } => { + let raw_excerpt = audit + .as_ref() + .and_then(|audit| audit.raw_excerpt.as_deref()) + .unwrap_or_default(); + !contains_vector_engine_content_rejection(message, raw_excerpt) + } + PlatformImageError::InvalidConfig { .. } + | PlatformImageError::InvalidRequest { .. } + | PlatformImageError::Request { .. } + | PlatformImageError::FallbackFailed { .. } => false, + } +} + +fn contains_vector_engine_model_unavailable(message: &str, raw_excerpt: &str) -> bool { + let haystack = format!("{message}\n{raw_excerpt}").to_ascii_lowercase(); + let mentions_model = haystack.contains("model") + || haystack.contains("模型") + || haystack.contains(GPT_IMAGE_2_MODEL) + || haystack.contains(GPT_IMAGE_2_C_MODEL); + let unavailable = [ + "not found", + "not supported", + "unsupported", + "unavailable", + "does not exist", + "invalid model", + "unknown model", + "不存在", + "不支持", + "不可用", + "未开通", + ] + .iter() + .any(|marker| haystack.contains(marker)); + mentions_model && unavailable +} + +fn contains_vector_engine_content_rejection(message: &str, raw_excerpt: &str) -> bool { + let haystack = format!("{message}\n{raw_excerpt}").to_ascii_lowercase(); + [ + "invalid_prompt", + "safety", + "content policy", + "content_policy", + "moderation", + "prompt rejected", + "content rejected", + "prompt refusal", + "content refusal", + "rejected by safety", + "rejected by moderation", + "敏感", + "违规", + "安全策略", + "内容审核", + "提示词拒绝", + "内容拒绝", + ] + .iter() + .any(|marker| haystack.contains(marker)) +} + +fn record_vector_engine_model_fallback( + request_kind: &'static str, + request_url: &str, + from_model: &str, + to_model: &str, + attempt: u32, + error: &PlatformImageError, +) { + let audit = error.audit(); + tracing::warn!( provider = VECTOR_ENGINE_PROVIDER, endpoint = %request_url, - status = response_status, - prompt_chars = prompt.chars().count(), - size = %normalized_size, - reference_image_count, - reference_image_bytes_total, - request_params = %request_params, + request_kind, + fallback_from_model = from_model, + fallback_to_model = to_model, attempt, - elapsed_ms = started_at.elapsed().as_millis() as u64, - failure_context, - "VectorEngine 图片编辑 HTTP 返回" + next_attempt = attempt + 1, + max_attempts = VECTOR_ENGINE_SEND_MAX_ATTEMPTS, + failure_stage = audit.map(|audit| audit.failure_stage).unwrap_or("unknown"), + status = audit.and_then(|audit| audit.status_code).unwrap_or_default(), + error = %error.message(), + "VectorEngine 首选图片模型失败，切换兼容模型" ); - let response_text = response.body; - handle_vector_engine_response( - http_client, - request_url.as_str(), - response_status, - response_text.as_str(), - failure_context, - started_at.elapsed().as_millis() as u64, - Some(prompt.chars().count()), - Some(reference_image_count), - candidate_count, - "vector-engine-edit", - settings.request_deadline, - ) - .await } fn should_retry_vector_engine_curl_send_error( @@ -595,8 +946,11 @@ fn should_retry_vector_engine_curl_send_error( && (error.is_timeout() || error.is_connect() || error.is_transient_transport()) } -fn should_retry_vector_engine_upstream_status(status: u16, attempt: u32) -> bool { - attempt < VECTOR_ENGINE_SEND_MAX_ATTEMPTS && (status == 408 || status == 429 || status >= 500) +fn should_retry_vector_engine_upstream_response(status: u16, raw_body: &str, attempt: u32) -> bool { + attempt < VECTOR_ENGINE_SEND_MAX_ATTEMPTS + && (status == 408 + || status >= 500 + || (status == 429 && !contains_vector_engine_content_rejection("", raw_body))) } async fn retry_vector_engine_send_after_delay( @@ -795,11 +1149,100 @@ mod tests { #[test] fn vector_engine_send_retry_policy_treats_upstream_502_as_retryable() { - assert!(should_retry_vector_engine_upstream_status(502, 1)); - assert!(should_retry_vector_engine_upstream_status(429, 1)); - assert!(should_retry_vector_engine_upstream_status(408, 1)); - assert!(!should_retry_vector_engine_upstream_status(400, 1)); - assert!(!should_retry_vector_engine_upstream_status(502, 5)); + assert!(should_retry_vector_engine_upstream_response(502, "", 1)); + assert!(should_retry_vector_engine_upstream_response(429, "", 1)); + assert!(should_retry_vector_engine_upstream_response( + 429, + "request rejected due to rate limit", + 1, + )); + assert!(should_retry_vector_engine_upstream_response(408, "", 1)); + assert!(!should_retry_vector_engine_upstream_response( + 429, + "内容审核拒绝", + 1, + )); + assert!(!should_retry_vector_engine_upstream_response(400, "", 1)); + assert!(!should_retry_vector_engine_upstream_response(502, "", 5)); + } + + #[test] + fn model_fallback_only_accepts_eligible_provider_failures() { + let settings = VectorEngineImageSettings { + base_url: "https://vector.example/v1".to_string(), + api_key: "test-key".to_string(), + request_timeout_ms: 1_000, + request_deadline: None, + }; + let unsupported_model = PlatformImageError::Upstream { + provider: VECTOR_ENGINE_PROVIDER, + message: "model gpt-image-2 is not supported".to_string(), + upstream_status: 400, + raw_excerpt: "unknown model".to_string(), + audit: None, + }; + let content_rejection = PlatformImageError::Upstream { + provider: VECTOR_ENGINE_PROVIDER, + message: "moderation blocked".to_string(), + upstream_status: 429, + raw_excerpt: "invalid_prompt".to_string(), + audit: None, + }; + let uncertain_send_failure = PlatformImageError::Request { + provider: VECTOR_ENGINE_PROVIDER, + message: "send failed".to_string(), + endpoint: None, + timeout: true, + connect: false, + request: true, + body: false, + status_code: None, + source: None, + audit: None, + }; + + assert!(should_fallback_to_gpt_image_2_c( + GPT_IMAGE_2_MODEL, + GPT_IMAGE_2_MODEL, + 1, + &unsupported_model, + &settings, + )); + assert!(!should_fallback_to_gpt_image_2_c( + GPT_IMAGE_2_MODEL, + GPT_IMAGE_2_MODEL, + 1, + &content_rejection, + &settings, + )); + let rate_limit_rejection = PlatformImageError::Upstream { + provider: VECTOR_ENGINE_PROVIDER, + message: "request rejected due to rate limit".to_string(), + upstream_status: 429, + raw_excerpt: "rate_limit_exceeded".to_string(), + audit: None, + }; + assert!(should_fallback_to_gpt_image_2_c( + GPT_IMAGE_2_MODEL, + GPT_IMAGE_2_MODEL, + 1, + &rate_limit_rejection, + &settings, + )); + assert!(!should_fallback_to_gpt_image_2_c( + GPT_IMAGE_2_MODEL, + GPT_IMAGE_2_MODEL, + 1, + &uncertain_send_failure, + &settings, + )); + assert!(!should_fallback_to_gpt_image_2_c( + GPT_IMAGE_2_MODEL, + GPT_IMAGE_2_MODEL, + VECTOR_ENGINE_SEND_MAX_ATTEMPTS, + &unsupported_model, + &settings, + )); } #[test] diff --git a/server-rs/crates/platform-image/src/vector_engine/constants.rs b/server-rs/crates/platform-image/src/vector_engine/constants.rs index 4cfa0432b..afbe17d03 100644 --- a/server-rs/crates/platform-image/src/vector_engine/constants.rs +++ b/server-rs/crates/platform-image/src/vector_engine/constants.rs @@ -1,3 +1,4 @@ pub const GPT_IMAGE_2_MODEL: &str = "gpt-image-2"; +pub const GPT_IMAGE_2_C_MODEL: &str = "gpt-image-2-c"; pub const VECTOR_ENGINE_GPT_IMAGE_2_MODEL: &str = GPT_IMAGE_2_MODEL; pub const VECTOR_ENGINE_PROVIDER: &str = "vector-engine"; diff --git a/server-rs/crates/platform-image/src/vector_engine/curl_transport.rs b/server-rs/crates/platform-image/src/vector_engine/curl_transport.rs index ce7dd389c..2098718a3 100644 --- a/server-rs/crates/platform-image/src/vector_engine/curl_transport.rs +++ b/server-rs/crates/platform-image/src/vector_engine/curl_transport.rs @@ -148,6 +148,7 @@ pub(crate) fn map_curl_error( context: &str, request_url: &str, failure_stage: &'static str, + image_model: Option<&'static str>, error: VectorEngineCurlError, latency_ms: u64, prompt_chars: Option, @@ -172,6 +173,7 @@ pub(crate) fn map_curl_error( Some(latency_ms), prompt_chars, reference_image_count, + image_model, ); tracing::warn!( provider = VECTOR_ENGINE_PROVIDER, @@ -189,6 +191,7 @@ pub(crate) fn map_curl_error( elapsed_ms = latency_ms, prompt_chars, reference_image_count, + image_model, request_params = %request_params .map(|value| value.to_string()) .unwrap_or_default(), diff --git a/server-rs/crates/platform-image/src/vector_engine/error.rs b/server-rs/crates/platform-image/src/vector_engine/error.rs index c98edf2dc..cb820e08a 100644 --- a/server-rs/crates/platform-image/src/vector_engine/error.rs +++ b/server-rs/crates/platform-image/src/vector_engine/error.rs @@ -42,6 +42,10 @@ pub enum PlatformImageError { message: String, audit: Option, }, + FallbackFailed { + final_error: Box, + recovered_failure_audits: Vec, + }, } impl PlatformImageError { @@ -53,6 +57,7 @@ impl PlatformImageError { | Self::Upstream { provider, .. } | Self::ResponseParse { provider, .. } | Self::MissingImage { provider, .. } => provider, + Self::FallbackFailed { final_error, .. } => final_error.provider(), } } @@ -64,6 +69,7 @@ impl PlatformImageError { | Self::Upstream { message, .. } | Self::ResponseParse { message, .. } | Self::MissingImage { message, .. } => message, + Self::FallbackFailed { final_error, .. } => final_error.message(), } } @@ -73,10 +79,42 @@ impl PlatformImageError { | Self::Upstream { audit, .. } | Self::ResponseParse { audit, .. } | Self::MissingImage { audit, .. } => audit.as_ref(), + Self::FallbackFailed { final_error, .. } => final_error.audit(), Self::InvalidConfig { .. } | Self::InvalidRequest { .. } => None, } } + pub fn recovered_failure_audits(&self) -> &[PlatformImageFailureAudit] { + match self { + Self::FallbackFailed { + recovered_failure_audits, + .. + } => recovered_failure_audits.as_slice(), + _ => &[], + } + } + + pub(crate) fn with_recovered_failure_audits( + self, + recovered_failure_audits: Vec, + ) -> Self { + if recovered_failure_audits.is_empty() { + self + } else { + Self::FallbackFailed { + final_error: Box::new(self), + recovered_failure_audits, + } + } + } + + pub fn into_final_error(self) -> Self { + match self { + Self::FallbackFailed { final_error, .. } => final_error.into_final_error(), + error => error, + } + } + pub fn status_hint(&self) -> PlatformImageStatusHint { match self { Self::InvalidConfig { .. } => PlatformImageStatusHint::ServiceUnavailable, @@ -93,6 +131,7 @@ impl PlatformImageError { | Self::Upstream { .. } | Self::ResponseParse { .. } | Self::MissingImage { .. } => PlatformImageStatusHint::BadGateway, + Self::FallbackFailed { final_error, .. } => final_error.status_hint(), } } } diff --git a/server-rs/crates/platform-image/src/vector_engine/image_source.rs b/server-rs/crates/platform-image/src/vector_engine/image_source.rs index e2a59706c..b9c65e853 100644 --- a/server-rs/crates/platform-image/src/vector_engine/image_source.rs +++ b/server-rs/crates/platform-image/src/vector_engine/image_source.rs @@ -69,6 +69,7 @@ async fn download_remote_image_with_deadline( return Err(request_budget_exhausted_error( image_url, operation, + None, Some(0), None, None, @@ -83,6 +84,7 @@ async fn download_remote_image_with_deadline( request_budget_exhausted_error( image_url, operation, + None, Some(started_at.elapsed().as_millis() as u64), None, None, @@ -117,6 +119,7 @@ pub(crate) async fn download_images_from_urls( task_id, actual_prompt: None, images, + recovered_failure_audits: Vec::new(), }) } @@ -222,12 +225,13 @@ pub(crate) fn images_from_base64( task_id, actual_prompt: None, images, + recovered_failure_audits: Vec::new(), } } pub(crate) fn decode_generated_image_base64(raw: &str) -> Option { let bytes = BASE64_STANDARD.decode(raw.trim()).ok()?; - let mime_type = infer_image_mime_type(bytes.as_slice()); + let mime_type = infer_image_mime_type(bytes.as_slice())?; Some(DownloadedImage { extension: mime_to_extension(mime_type.as_str()).to_string(), mime_type, @@ -258,20 +262,20 @@ pub(crate) fn mime_to_extension(mime_type: &str) -> &str { } } -pub(crate) fn infer_image_mime_type(bytes: &[u8]) -> String { +pub(crate) fn infer_image_mime_type(bytes: &[u8]) -> Option { if bytes.starts_with(b"\x89PNG\r\n\x1A\n") { - return "image/png".to_string(); + return Some("image/png".to_string()); } if bytes.starts_with(b"\xFF\xD8\xFF") { - return "image/jpeg".to_string(); + return Some("image/jpeg".to_string()); } if bytes.starts_with(b"RIFF") && bytes.get(8..12) == Some(b"WEBP") { - return "image/webp".to_string(); + return Some("image/webp".to_string()); } if bytes.starts_with(b"GIF87a") || bytes.starts_with(b"GIF89a") { - return "image/gif".to_string(); + return Some("image/gif".to_string()); } - "image/png".to_string() + None } fn map_simple_request_error(message: String, endpoint: Option) -> PlatformImageError { diff --git a/server-rs/crates/platform-image/src/vector_engine/mod.rs b/server-rs/crates/platform-image/src/vector_engine/mod.rs index 8f771c54a..99511b9ac 100644 --- a/server-rs/crates/platform-image/src/vector_engine/mod.rs +++ b/server-rs/crates/platform-image/src/vector_engine/mod.rs @@ -19,7 +19,9 @@ pub use client::{ create_vector_engine_image_generation, create_vector_engine_image_generation_with_model, create_vector_engine_nanobanana_generate_content, }; -pub use constants::{GPT_IMAGE_2_MODEL, VECTOR_ENGINE_GPT_IMAGE_2_MODEL, VECTOR_ENGINE_PROVIDER}; +pub use constants::{ + GPT_IMAGE_2_C_MODEL, GPT_IMAGE_2_MODEL, VECTOR_ENGINE_GPT_IMAGE_2_MODEL, VECTOR_ENGINE_PROVIDER, +}; pub use error::{PlatformImageError, PlatformImageStatusHint}; pub use image_source::download_remote_image; pub use request::{ diff --git a/server-rs/crates/platform-image/src/vector_engine/request.rs b/server-rs/crates/platform-image/src/vector_engine/request.rs index 91d6075c4..a0daa53c4 100644 --- a/server-rs/crates/platform-image/src/vector_engine/request.rs +++ b/server-rs/crates/platform-image/src/vector_engine/request.rs @@ -1,7 +1,7 @@ use serde_json::{Map, Value, json}; use super::{ - constants::GPT_IMAGE_2_MODEL, + constants::{GPT_IMAGE_2_C_MODEL, GPT_IMAGE_2_MODEL}, types::{ReferenceImage, VectorEngineImageSettings}, }; @@ -90,6 +90,13 @@ pub fn normalize_vector_engine_image_model(model: &str) -> &str { } } +pub(crate) fn is_gpt_image_2_family_model(model: &str) -> bool { + matches!( + normalize_vector_engine_image_model(model), + GPT_IMAGE_2_MODEL | GPT_IMAGE_2_C_MODEL + ) +} + pub fn normalize_image_size_for_model(model: &str, size: &str) -> String { let size = size.trim(); let normalized_size = match size { @@ -102,7 +109,7 @@ pub fn normalize_image_size_for_model(model: &str, size: &str) -> String { _ => "1024x1024".to_string(), }; - if normalize_vector_engine_image_model(model) == GPT_IMAGE_2_MODEL { + if is_gpt_image_2_family_model(model) { clamp_gpt_image_2_pixel_size(normalized_size.as_str()) } else { normalized_size diff --git a/server-rs/crates/platform-image/src/vector_engine/response.rs b/server-rs/crates/platform-image/src/vector_engine/response.rs index 112889930..438b5b3a6 100644 --- a/server-rs/crates/platform-image/src/vector_engine/response.rs +++ b/server-rs/crates/platform-image/src/vector_engine/response.rs @@ -17,6 +17,7 @@ pub(crate) async fn handle_vector_engine_response( request_url: &str, response_status: u16, response_text: &str, + image_model: Option<&'static str>, failure_context: &str, latency_ms: u64, prompt_chars: Option, @@ -42,6 +43,7 @@ pub(crate) async fn handle_vector_engine_response( Some(latency_ms), prompt_chars, reference_image_count, + image_model, ); tracing::warn!( provider = VECTOR_ENGINE_PROVIDER, @@ -79,6 +81,7 @@ pub(crate) async fn handle_vector_engine_response( Some(latency_ms), prompt_chars, reference_image_count, + image_model, ); tracing::warn!( provider = VECTOR_ENGINE_PROVIDER, @@ -136,6 +139,7 @@ pub(crate) async fn handle_vector_engine_response( Some(download_started_at.elapsed().as_millis() as u64), prompt_chars, reference_image_count, + image_model, ); return Err(error.with_audit(audit)); } @@ -154,6 +158,40 @@ pub(crate) async fn handle_vector_engine_response( let b64_images = extract_b64_images(&response_json.payload); if !b64_images.is_empty() { let mut generated = images_from_base64(task_id, b64_images, candidate_count); + if generated.images.is_empty() { + let message = format!("{failure_context}：VectorEngine 返回的 base64 图片无法解码"); + let raw_excerpt = truncate_raw(response_text); + let audit = build_failure_audit( + request_url, + failure_context, + "response_parse", + Some(response_status), + None, + false, + false, + message.as_str(), + None, + Some(raw_excerpt.clone()), + Some(latency_ms), + prompt_chars, + reference_image_count, + image_model, + ); + tracing::warn!( + provider = VECTOR_ENGINE_PROVIDER, + endpoint = %request_url, + status = response_status, + image_model, + raw_excerpt = %raw_excerpt, + "VectorEngine 图片 base64 解码失败" + ); + return Err(PlatformImageError::ResponseParse { + provider: VECTOR_ENGINE_PROVIDER, + message, + raw_excerpt, + audit: Some(audit), + }); + } generated.actual_prompt = actual_prompt; tracing::info!( provider = VECTOR_ENGINE_PROVIDER, @@ -180,6 +218,7 @@ pub(crate) async fn handle_vector_engine_response( Some(latency_ms), prompt_chars, reference_image_count, + image_model, ); tracing::warn!( provider = VECTOR_ENGINE_PROVIDER, diff --git a/server-rs/crates/platform-image/src/vector_engine/types.rs b/server-rs/crates/platform-image/src/vector_engine/types.rs index 328173567..77fbd19f9 100644 --- a/server-rs/crates/platform-image/src/vector_engine/types.rs +++ b/server-rs/crates/platform-image/src/vector_engine/types.rs @@ -1,3 +1,5 @@ +use super::audit::PlatformImageFailureAudit; + #[derive(Clone, Debug)] pub struct VectorEngineImageSettings { pub base_url: String, @@ -11,6 +13,7 @@ pub struct GeneratedImages { pub task_id: String, pub actual_prompt: Option, pub images: Vec, + pub recovered_failure_audits: Vec, } #[derive(Clone, Debug)] diff --git a/server-rs/crates/platform-image/src/vector_engine/util.rs b/server-rs/crates/platform-image/src/vector_engine/util.rs index ed6c487ab..621d57c6a 100644 --- a/server-rs/crates/platform-image/src/vector_engine/util.rs +++ b/server-rs/crates/platform-image/src/vector_engine/util.rs @@ -79,6 +79,13 @@ impl PlatformImageError { message, audit: Some(audit), }, + Self::FallbackFailed { + final_error, + recovered_failure_audits, + } => Self::FallbackFailed { + final_error: Box::new(final_error.with_audit(audit)), + recovered_failure_audits, + }, Self::InvalidConfig { .. } | Self::InvalidRequest { .. } => self, } } diff --git a/server-rs/crates/platform-image/tests/vector_engine.rs b/server-rs/crates/platform-image/tests/vector_engine.rs index 6485e8d6c..c4b1801db 100644 --- a/server-rs/crates/platform-image/tests/vector_engine.rs +++ b/server-rs/crates/platform-image/tests/vector_engine.rs @@ -1,6 +1,6 @@ use platform_image::vector_engine::{ - GPT_IMAGE_2_MODEL, PlatformImageError, ReferenceImage, VECTOR_ENGINE_PROVIDER, - VectorEngineImageSettings, build_vector_engine_image_http_client, + GPT_IMAGE_2_C_MODEL, GPT_IMAGE_2_MODEL, PlatformImageError, ReferenceImage, + VECTOR_ENGINE_PROVIDER, VectorEngineImageSettings, build_vector_engine_image_http_client, build_vector_engine_image_request_body, build_vector_engine_image_request_body_with_model, build_vector_engine_nanobanana_generate_content_request_body, create_vector_engine_image_edit, create_vector_engine_image_generation, create_vector_engine_nanobanana_generate_content, @@ -17,6 +17,7 @@ use std::{ use tokio::{ io::{AsyncReadExt, AsyncWriteExt}, net::TcpListener, + sync::Mutex, }; #[test] @@ -32,6 +33,7 @@ fn vector_engine_module_exposes_provider_protocol_helpers() { build_vector_engine_image_request_body("雾海神殿", Some("文字，水印"), "16:9", 9, &[]); assert_eq!(GPT_IMAGE_2_MODEL, "gpt-image-2"); + assert_eq!(GPT_IMAGE_2_C_MODEL, "gpt-image-2-c"); assert_eq!(VECTOR_ENGINE_PROVIDER, "vector-engine"); assert_eq!(body["model"], GPT_IMAGE_2_MODEL); assert_eq!(body["size"], "1536x1024"); @@ -109,8 +111,17 @@ fn vector_engine_only_enforces_the_gpt_image_2_pixel_budget_for_that_model() { 1, &[], ); + let fallback_gpt_body = build_vector_engine_image_request_body_with_model( + GPT_IMAGE_2_C_MODEL, + "小尺寸图", + None, + "640x640", + 1, + &[], + ); assert_eq!(gpt_body["size"], "816x816"); + assert_eq!(fallback_gpt_body["size"], "816x816"); assert_eq!(nanobanana_body["size"], "640x640"); assert_eq!(oversized_gpt_body["size"], "2880x2880"); } @@ -207,6 +218,8 @@ async fn vector_engine_image_edit_retries_send_timeout_once_and_succeeds() { .expect("mock server address should be readable"); let request_count = Arc::new(AtomicUsize::new(0)); let request_count_for_server = Arc::clone(&request_count); + let requests = Arc::new(Mutex::new(Vec::new())); + let requests_for_server = Arc::clone(&requests); let server = tokio::spawn(async move { loop { @@ -214,9 +227,13 @@ async fn vector_engine_image_edit_retries_send_timeout_once_and_succeeds() { break; }; let request_index = request_count_for_server.fetch_add(1, Ordering::SeqCst); + let requests_for_connection = Arc::clone(&requests_for_server); tokio::spawn(async move { - let mut buffer = [0_u8; 4096]; - let _ = stream.read(&mut buffer).await; + let request = read_http_request(&mut stream).await; + requests_for_connection + .lock() + .await + .push(String::from_utf8_lossy(request.as_slice()).into_owned()); if request_index == 0 { tokio::time::sleep(Duration::from_millis(120)).await; return; @@ -261,10 +278,55 @@ async fn vector_engine_image_edit_retries_send_timeout_once_and_succeeds() { assert_eq!(generated.images.len(), 1); assert_eq!(generated.images[0].mime_type, "image/png"); + assert!(generated.recovered_failure_audits.is_empty()); assert_eq!(request_count.load(Ordering::SeqCst), 2); + let requests = requests.lock().await; + assert!( + requests + .iter() + .all(|request| request.contains("\r\n\r\ngpt-image-2\r\n")) + ); server.abort(); } +async fn read_http_request(stream: &mut tokio::net::TcpStream) -> Vec { + let mut request = Vec::new(); + let mut buffer = [0_u8; 4096]; + loop { + let Ok(read) = stream.read(&mut buffer).await else { + return request; + }; + if read == 0 { + return request; + } + request.extend_from_slice(&buffer[..read]); + let Some(header_start) = request.windows(4).position(|window| window == b"\r\n\r\n") else { + continue; + }; + let header_end = header_start + 4; + let headers = String::from_utf8_lossy(&request[..header_end]); + let content_length = headers + .lines() + .find_map(|line| { + line.strip_prefix("Content-Length:") + .or_else(|| line.strip_prefix("content-length:")) + }) + .and_then(|value| value.trim().parse::().ok()) + .unwrap_or_default(); + let expected_len = header_end + content_length; + while request.len() < expected_len { + let Ok(read) = stream.read(&mut buffer).await else { + return request; + }; + if read == 0 { + return request; + } + request.extend_from_slice(&buffer[..read]); + } + return request; + } +} + #[tokio::test] async fn vector_engine_deadline_clips_stalled_attempt_and_prevents_retry() { let listener = TcpListener::bind("127.0.0.1:0") @@ -393,7 +455,7 @@ async fn nanobanana_generate_content_posts_native_body_and_reads_inline_data() { } #[tokio::test] -async fn vector_engine_image_generation_retries_upstream_502_once_and_succeeds() { +async fn vector_engine_image_generation_falls_back_after_upstream_502_and_succeeds() { let listener = TcpListener::bind("127.0.0.1:0") .await .expect("mock server should bind"); @@ -402,6 +464,8 @@ async fn vector_engine_image_generation_retries_upstream_502_once_and_succeeds() .expect("mock server address should be readable"); let request_count = Arc::new(AtomicUsize::new(0)); let request_count_for_server = Arc::clone(&request_count); + let requests = Arc::new(Mutex::new(Vec::new())); + let requests_for_server = Arc::clone(&requests); let server = tokio::spawn(async move { loop { @@ -409,9 +473,13 @@ async fn vector_engine_image_generation_retries_upstream_502_once_and_succeeds() break; }; let request_index = request_count_for_server.fetch_add(1, Ordering::SeqCst); + let requests_for_connection = Arc::clone(&requests_for_server); tokio::spawn(async move { - let mut buffer = [0_u8; 4096]; - let _ = stream.read(&mut buffer).await; + let request = read_http_request(&mut stream).await; + requests_for_connection + .lock() + .await + .push(String::from_utf8_lossy(request.as_slice()).into_owned()); if request_index == 0 { let body = "502 Bad Gateway

502 Bad Gateway

nginx
"; let response = format!( @@ -458,6 +526,305 @@ async fn vector_engine_image_generation_retries_upstream_502_once_and_succeeds() assert_eq!(generated.images.len(), 1); assert_eq!(generated.images[0].mime_type, "image/png"); + assert_eq!(generated.recovered_failure_audits.len(), 1); + assert_eq!( + generated.recovered_failure_audits[0].image_model, + Some(GPT_IMAGE_2_MODEL) + ); assert_eq!(request_count.load(Ordering::SeqCst), 2); + let requests = requests.lock().await; + assert!(requests[0].contains("\"model\":\"gpt-image-2\"")); + assert!(requests[1].contains("\"model\":\"gpt-image-2-c\"")); server.abort(); } + +#[tokio::test] +async fn vector_engine_image_generation_uses_gpt_image_2_without_fallback_on_success() { + let (base_url, server, requests) = start_http_response_sequence(vec![MockResponse { + status: "200 OK", + content_type: "application/json", + body: r#"{"data":[{"b64_json":"iVBORw0KGgpyZXN0"}]}"#, + }]) + .await; + let settings = test_vector_engine_settings(base_url); + let http_client = + build_vector_engine_image_http_client(&settings).expect("client should build"); + + let generated = create_vector_engine_image_generation( + &http_client, + &settings, + "测试提示词", + None, + "1024x1024", + 1, + &[], + "测试 VectorEngine 图片生成失败", + ) + .await + .expect("preferred model should generate image"); + + assert_eq!(generated.images.len(), 1); + assert!(generated.recovered_failure_audits.is_empty()); + let requests = requests.lock().await; + assert_eq!(requests.len(), 1); + assert!(requests[0].contains("\"model\":\"gpt-image-2\"")); + server.abort(); +} + +#[tokio::test] +async fn vector_engine_image_edit_falls_back_when_preferred_model_is_unsupported() { + let (base_url, server, requests) = start_http_response_sequence(vec![ + MockResponse { + status: "400 Bad Request", + content_type: "application/json", + body: r#"{"error":{"message":"model gpt-image-2 is not supported"}}"#, + }, + MockResponse { + status: "200 OK", + content_type: "application/json", + body: r#"{"data":[{"b64_json":"iVBORw0KGgpyZXN0"}]}"#, + }, + ]) + .await; + let settings = test_vector_engine_settings(base_url); + let http_client = + build_vector_engine_image_http_client(&settings).expect("client should build"); + let reference = ReferenceImage { + bytes: b"reference".to_vec(), + mime_type: "image/png".to_string(), + file_name: "reference.png".to_string(), + }; + + let generated = create_vector_engine_image_edit( + &http_client, + &settings, + "测试提示词", + None, + "1024x1024", + &reference, + "测试 VectorEngine 图片编辑失败", + ) + .await + .expect("fallback model should recover unsupported preferred model"); + + assert_eq!(generated.images.len(), 1); + assert_eq!(generated.recovered_failure_audits.len(), 1); + assert_eq!( + generated.recovered_failure_audits[0].image_model, + Some(GPT_IMAGE_2_MODEL) + ); + let requests = requests.lock().await; + assert_eq!(requests.len(), 2); + assert!(requests[0].contains("\r\n\r\ngpt-image-2\r\n")); + assert!(requests[1].contains("\r\n\r\ngpt-image-2-c\r\n")); + server.abort(); +} + +#[tokio::test] +async fn vector_engine_image_generation_does_not_fallback_on_auth_failure() { + let (base_url, server, requests) = start_http_response_sequence(vec![MockResponse { + status: "401 Unauthorized", + content_type: "application/json", + body: r#"{"error":{"message":"invalid api key"}}"#, + }]) + .await; + let settings = test_vector_engine_settings(base_url); + let http_client = + build_vector_engine_image_http_client(&settings).expect("client should build"); + + let error = create_vector_engine_image_generation( + &http_client, + &settings, + "测试提示词", + None, + "1024x1024", + 1, + &[], + "测试 VectorEngine 图片生成失败", + ) + .await + .expect_err("authentication failure should remain terminal"); + + assert!(matches!( + error, + PlatformImageError::Upstream { + upstream_status: 401, + .. + } + )); + let requests = requests.lock().await; + assert_eq!(requests.len(), 1); + server.abort(); +} + +#[tokio::test] +async fn vector_engine_image_generation_falls_back_after_non_image_base64_response() { + let (base_url, server, requests) = start_http_response_sequence(vec![ + MockResponse { + status: "200 OK", + content_type: "application/json", + body: r#"{"data":[{"b64_json":"bm90IGFuIGltYWdl"}]}"#, + }, + MockResponse { + status: "200 OK", + content_type: "application/json", + body: r#"{"data":[{"b64_json":"iVBORw0KGgpyZXN0"}]}"#, + }, + ]) + .await; + let settings = test_vector_engine_settings(base_url); + let http_client = + build_vector_engine_image_http_client(&settings).expect("client should build"); + + let generated = create_vector_engine_image_generation( + &http_client, + &settings, + "测试提示词", + None, + "1024x1024", + 1, + &[], + "测试 VectorEngine 图片生成失败", + ) + .await + .expect("fallback model should recover invalid preferred response"); + + assert_eq!(generated.images.len(), 1); + assert_eq!(generated.recovered_failure_audits.len(), 1); + assert_eq!( + generated.recovered_failure_audits[0].failure_stage, + "response_parse" + ); + let requests = requests.lock().await; + assert_eq!(requests.len(), 2); + assert!(requests[0].contains("\"model\":\"gpt-image-2\"")); + assert!(requests[1].contains("\"model\":\"gpt-image-2-c\"")); + server.abort(); +} + +#[tokio::test] +async fn vector_engine_image_generation_preserves_primary_audit_when_fallback_also_fails() { + let (base_url, server, requests) = start_http_response_sequence(vec![ + MockResponse { + status: "502 Bad Gateway", + content_type: "text/html", + body: "

502 Bad Gateway

", + }, + MockResponse { + status: "401 Unauthorized", + content_type: "application/json", + body: r#"{"error":{"message":"invalid api key"}}"#, + }, + ]) + .await; + let settings = test_vector_engine_settings(base_url); + let http_client = + build_vector_engine_image_http_client(&settings).expect("client should build"); + + let error = create_vector_engine_image_generation( + &http_client, + &settings, + "测试提示词", + None, + "1024x1024", + 1, + &[], + "测试 VectorEngine 图片生成失败", + ) + .await + .expect_err("fallback authentication failure should remain terminal"); + + assert_eq!(error.recovered_failure_audits().len(), 1); + assert_eq!( + error.recovered_failure_audits()[0].image_model, + Some(GPT_IMAGE_2_MODEL) + ); + assert_eq!( + error.audit().and_then(|audit| audit.image_model), + Some(GPT_IMAGE_2_C_MODEL) + ); + let requests = requests.lock().await; + assert_eq!(requests.len(), 2); + server.abort(); +} + +#[tokio::test] +async fn vector_engine_image_generation_does_not_fallback_on_safety_parse_failure() { + let (base_url, server, requests) = start_http_response_sequence(vec![MockResponse { + status: "200 OK", + content_type: "application/json", + body: "safety refusal: 内容审核拒绝", + }]) + .await; + let settings = test_vector_engine_settings(base_url); + let http_client = + build_vector_engine_image_http_client(&settings).expect("client should build"); + + let error = create_vector_engine_image_generation( + &http_client, + &settings, + "测试提示词", + None, + "1024x1024", + 1, + &[], + "测试 VectorEngine 图片生成失败", + ) + .await + .expect_err("content rejection should not switch models"); + + assert!(matches!(error, PlatformImageError::ResponseParse { .. })); + let requests = requests.lock().await; + assert_eq!(requests.len(), 1); + server.abort(); +} + +#[derive(Clone, Copy)] +struct MockResponse { + status: &'static str, + content_type: &'static str, + body: &'static str, +} + +async fn start_http_response_sequence( + responses: Vec, +) -> (String, tokio::task::JoinHandle<()>, Arc>>) { + let listener = TcpListener::bind("127.0.0.1:0") + .await + .expect("mock server should bind"); + let server_addr = listener + .local_addr() + .expect("mock server address should be readable"); + let requests = Arc::new(Mutex::new(Vec::new())); + let requests_for_server = Arc::clone(&requests); + let server = tokio::spawn(async move { + for response_spec in responses { + let Ok((mut stream, _)) = listener.accept().await else { + return; + }; + let request = read_http_request(&mut stream).await; + requests_for_server + .lock() + .await + .push(String::from_utf8_lossy(request.as_slice()).into_owned()); + let response = format!( + "HTTP/1.1 {}\r\nContent-Type: {}\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{}", + response_spec.status, + response_spec.content_type, + response_spec.body.len(), + response_spec.body, + ); + let _ = stream.write_all(response.as_bytes()).await; + } + }); + (format!("http://{server_addr}/v1"), server, requests) +} + +fn test_vector_engine_settings(base_url: String) -> VectorEngineImageSettings { + VectorEngineImageSettings { + base_url, + api_key: "test-key".to_string(), + request_timeout_ms: 1_000, + request_deadline: None, + } +}