From cc538e827fd758d52ffe62f9fdcbe25a61191b26 Mon Sep 17 00:00:00 2001 From: Lixi20 Date: Mon, 21 Sep 2026 15:52:41 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20gpt-image-2=20=E5=8F=96=E8=AF=81?= =?UTF-8?q?=E9=A1=B5=E9=94=99=E8=AF=AF=E6=98=A0=E5=B0=84=E4=B8=80=E8=8A=82?= =?UTF-8?q?=E6=8C=89=E5=AE=98=E6=96=B9=20Error=20codes=20=E9=A1=B5?= =?UTF-8?q?=E9=87=8D=E5=86=99?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 新增三部分：此前猜的五个码名与官方对照（六错五，作为教训留档）、官方表 13 条的 分类一览（全是基础设施与计费，**没有任何内容审核/侵权码**）、逐条抄自文档的映射表。 两处标注清楚的判断：400 的两义用 error.param 的有无区分（推断，附三条依据与取错 代价的不对称分析）；Retry-After 暂不接（附可算的理由——Java 侧退避基线已长于服务商 通常给的值）。 另记一条厂商改判：视频过载已从 429 改判为 503，我们两者都归可重试故不受影响， 并说明测试在哪里钉住这个「无影响」。 mkdocs build --strict 通过。 --- .../development/providers/openai-gpt-image.md | 119 ++++++++++++++---- 1 file changed, 93 insertions(+), 26 deletions(-) diff --git a/docs/development/providers/openai-gpt-image.md b/docs/development/providers/openai-gpt-image.md index 1d62ebc..5d6e580 100644 --- a/docs/development/providers/openai-gpt-image.md +++ b/docs/development/providers/openai-gpt-image.md @@ -1,7 +1,7 @@ # OpenAI gpt-image-2 图片生成：接口事实与映射 -> 取证日期：2026-09-21　来源：用户提供的两份官方文档（`doc_temp/gpt生图.md`、 -> `doc_temp/gpt图像编辑.md`） +> 取证日期：2026-09-21　来源：用户提供的三份官方文档（`doc_temp/gpt生图.md`、 +> `doc_temp/gpt图像编辑.md`、`doc_temp/gpt错误码.md`） > 实现位置：`patbond-ai` 的 `app/providers/openai/`（`client.py` 传输 / `errors.py` 错误映射 / > `models.py` 厂商 DTO / `image.py` 图片业务 / `capabilities.py` 参数限制 / > `tasks.py` 同步→异步桥） @@ -145,41 +145,108 @@ edge limits」——**没给具体数值**，故这一条无法在本地校验 可退避重试）。服务商说成功却没给图，那不是成功——把它当成功会让上层拿到一个没有 产物的 SUCCEEDED 去空指针。 -## 6. 错误映射 ⚠️ 未经文档证实 +## 6. 错误映射 -> **两份文档都没有错误码一节。** 这与火山那边给了完整错误码表的情况不同。 +> 取证补充（2026-09-21）：收到官方 Error codes 页（`doc_temp/gpt错误码.md`）。 +> 本节此前是按 HTTP 状态码推断的版本，现已按文档实际码名重写。 -因此 `errors.py` 的映射建立在 OpenAI 通用错误约定之上（错误体形如 -`{"error": {message, type, code, param}}`），并**以 HTTP 状态码为主、 -`type`/`code` 为辅**。选这个策略是因为状态码语义由 HTTP 规范保证，而 `type`/`code` -的取值集没有文档支撑——凭记忆列一张表只会得到一张看起来权威、实则可能错漏的映射。 +### 先记一笔教训：此前猜的五个码名，一个都不存在 + +| 我猜的 | 官方文档里 | +| --- | --- | +| `rate_limit_exceeded` | ❌ 不存在。真实的是 type `rate_limit_error` + code `slow_down` | +| `moderation_blocked` | ❌ 不存在 | +| `content_policy_violation` | ❌ 不存在 | +| `invalid_api_key` | ❌ 不存在（401 只给人类可读消息，无 code） | +| `image_generation_user_error` | ❌ 不存在 | +| `insufficient_quota` | ✅ 存在，但它是**宽 `type`** 而非 `code` | + +六个里错五个。这就是「凭记忆列错误码表」的实际命中率——那张表当时看起来是权威的。 +故当时的 ⚠️ 标注不是客套：**没有文档就要明写没有文档**。 + +### ⚠️ 官方错误码表里没有任何业务层失败 + +13 条全是**基础设施与计费**： + +| 类别 | 条目 | +| --- | --- | +| 鉴权（401） | 无效认证 / 密钥不正确 / 不属于任何组织 / IP 不在白名单 | +| 地域（403） | 国家、地区或领地不受支持 | +| 参数（400） | `service_tier` 不被项目允许 | +| 限流（429） | 请求过快 / `slow_down`（涨得太快） | +| 钱（429） | 余额耗尽 / 组织消费限额 / 项目消费限额 / 组织用量限额 | +| 服务端（500 / 503） | 内部错误 / 模型过载 | + +**没有内容审核、没有版权/侵权、没有「这个提示词不能生成」。** 但图片接口明确有 +`moderation` 参数（`low`/`auto`），说明审核确实存在——只是它的错误形态未被文档化。 + +### 映射表（键全部抄自文档） | 依据 | `retry` | 用户可见 | | --- | --- | --- | -| `code`/`type` = `insufficient_quota` | `QUOTA` | 配额耗尽 | -| `code`/`type` = `rate_limit_exceeded` | `BACKOFF` | 限流 | -| `code` = `moderation_blocked` / `content_policy_violation` | `NEVER` | 内容被拒 | -| `code` = `invalid_api_key` | `NEVER` | 服务端错误 | -| 网络层失败（连不上、超时） | `BACKOFF` | 上游不可用 | -| HTTP 429（且拿不到 type/code） | `BACKOFF` | **按限流处理** | +| `credit_balance_exhausted` | `QUOTA` | 配额耗尽 | +| `organization_spend_limit_exceeded` | `QUOTA` | 配额耗尽 | +| `project_spend_limit_exceeded` | `QUOTA` | 配额耗尽 | +| `organization_usage_limit_exceeded` | `QUOTA` | 配额耗尽 | +| `insufficient_quota`（宽 type） | `QUOTA` | 配额耗尽 | +| `slow_down` / `rate_limit_error` | `BACKOFF` | 限流 | +| `server_is_overloaded` / `service_unavailable_error` | `BACKOFF` | 上游不可用 | +| HTTP 429（无 code 且 type 不认识） | `BACKOFF` | 限流 | +| HTTP 400 **带** `error.param` | `NEVER` | 服务端错误 | +| HTTP 400 **不带** `error.param` | `NEVER` | **内容被拒**（推断，见下） | | HTTP 401 / 403 | `NEVER` | 服务端错误 | -| HTTP 400 | `NEVER` | **服务端错误**，不猜成「内容被拒」 | | 其余 4xx | `NEVER` | 服务端错误 | +| 网络层失败（连不上、超时） | `BACKOFF` | 上游不可用 | | 5xx 及一切未知 | `BACKOFF` | 上游不可用 | -两处取舍值得记下来： +`Retry.QUOTA` 这一档的存在理由正是文档那句原话：**「Retrying billing, spend, or +quota errors won't restore API access」**——重试不会恢复访问，要人去充值或改限额。 +Worker 不该把重试预算花在这上面，应直接终态失败并让用户看到出口。 -- **429 拿不到 type/code 时按限流而非配额耗尽。** 429 在 OpenAI 上两义兼有；猜成 - 配额耗尽会把一次本可重试的限流判死，代价更大。 -- **400 归「服务端错误」而不是「内容被拒」。** OpenAI 用 400 同时表示参数问题与 - 内容被拒；拿不到 type/code 时无法区分，而错报「内容被拒」会让用户去改一个其实 - 没问题的提示词。 +**两个字段查同一张表。** 文档把某个标识列在哪个字段下，不保证实际响应里它一定出现 +在那个字段（`insufficient_quota` 被描述为「broader `error.type`」，但很容易出现在 +`code` 里）。查错字段的代价是把配额耗尽降级成限流、白烧一轮重试预算；而两边都查 +不引入任何**新**词汇。 -未知情形一律偏向**可退避重试**：把一次可恢复的抖动判成用户可见的失败是更糟的 -错误，而重试预算本身有上限（`max_attempts`）。 +### 唯一的推断：400 的两义如何区分 -**待补**：拿到官方错误码文档、或在真实调用中观察到实际取值后，校正 `errors.py` -并回改本节。在那之前，`errors.py` 顶部那段 ⚠️ 说明不要删。 +因为没有内容审核码，**一次侵权或违规拒绝很可能以一个普通 400 到达**，只带一句 +人类可读的消息。若把这种 400 一律归为「服务端错误」，用户会看到「服务出错了」 +然后反复重试同一个注定被拒的提示词。 + +用 `error.param` 的有无做结构化区分，三条依据： + +1. 文档在 `service_tier` 那条明确写了「as an `invalid_request_error` with + `error.param` set to `service_tier`」——**参数类错误会带 `param`**。 +2. 官方表没有任何内容审核码，故内容拒绝只能以通用 400 到达，且它不指向任何具体 + 参数，`param` 应为空。 +3. 我方在调用前已用 `capabilities.py` 校验过尺寸、画质、格式，`model`/`n` 由程序 + 生成——**能活着到达服务商并被 400 拒掉的，参数嫌疑本来就不大**。 + +取错的代价不对称，这也是选这个方向的理由：把内容拒绝报成「服务出错」会让用户反复 +重试一个注定被拒的提示词；反过来把一个参数 bug 报成「内容可能不被支持」只是让用户 +多试一次，而排查者看到的 `provider_code` 与日志仍然准确。走这条分支时会记一条 +**WARNING**，那是日后校正它的唯一素材来源。 + +**待补**：拿到真实的审核错误形态（或官方补出业务码）后，把这里换成确定的判定。 + +### 一处厂商改判，对我们无影响 + +文档提醒：**视频过载已从 429 改判为 503**，且 Python SDK 分别抛 `RateLimitError` +与 `InternalServerError`，只捕一类会漏。我们两者都归可重试，故这次改判不影响本 +服务——`tests/providers/openai/test_errors.py` 里有一条测试专门钉住这个「无影响」， +哪天有人把 5xx 改成不可重试，它会红。 + +### 未接的一项：`Retry-After` + +文档在 429 与 503 处反复要求遵守 `Retry-After` 响应头。本服务目前**不读它**。 + +不读的理由是可算的：Java 侧 Worker 的退避阶梯基线 30 秒、指数增长、上限 10 分钟 +（`CreationProperties.retryBackoffFor`），**在绝大多数情形下已长于服务商给的 +`Retry-After`**——也就是我们已经比要求更保守，忽略它只会让重试偏慢，不会加剧限流。 + +要接起来是一次跨语言契约变更：领域 `Failure` 加字段 → `openapi-internal.yaml` 小 +版本 → Java 侧 DTO 与 Worker 调度都要改。收益只是延迟优化，故排在存储决策之后。 ## 7. 同步接口的两笔代价 @@ -232,7 +299,7 @@ edge limits」——**没给具体数值**，故这一条无法在本地校验 | 项 | 状态 | | --- | --- | | HTTP 传输与鉴权（`client.py`） | ✅ 离线测试（MockTransport） | -| 错误分类（`errors.py`） | ✅ 有测试，但**映射本身未经文档证实**（第 6 节） | +| 错误分类（`errors.py`） | ✅ 按官方 Error codes 页逐条落地；仅 400 的两义区分是推断（第 6 节） | | 参数预校验（`capabilities.py`） | ✅ 四条算术规则 + 画质/格式 | | 同步→异步桥（`tasks.py`） | ✅ 含容量上限、TTL、死锁回归 | | 图片业务（`image.py`） | ✅ 文生图 + 图生图（含参考图下载） |