228 lines
16 KiB
Markdown
228 lines
16 KiB
Markdown
## Context
|
||
|
||
当前代码已经具备图片价格字段和部分图片转发能力，但边界不完整：
|
||
|
||
- `backend/ent/schema/group.go` 只有 `rate_multiplier` 和 `image_price_1k/2k/4k`，没有分组级生图能力开关，也没有“图片是否共享分组倍率”的开关。
|
||
- `backend/internal/handler/openai_images.go` 在解析 `/v1/images/*` 后只做通用余额/订阅资格检查，没有检查分组是否允许生图。
|
||
- `backend/internal/service/openai_gateway_service.go` 对 Codex CLI 会自动注入 `image_generation` tool；通用 `/v1/responses` 只记录日志，没有把图片工具产物数量写入 `OpenAIForwardResult.ImageCount`。
|
||
- `backend/internal/service/billing_service.go` 的 `CalculateImageCost` 当前使用 `image_price_* * image_count * rate_multiplier`。这个行为本身可以作为默认兼容模式，但普通编码分组 `rate_multiplier=0.15` 且希望图片最终价为 `0.2/张` 时，管理员必须填写 `image_price=0.2/0.15`，不可读且不适合长期运营。
|
||
- `backend/internal/service/openai_gateway_service.go` 和 `backend/internal/service/gateway_service.go` 的渠道图片计费路径当前传 `RequestCount: 1`，多图请求会按 1 次收费。
|
||
- `backend/internal/service/openai_images.go` 的 OpenAI 图片尺寸分层此前只覆盖少量固定尺寸；`gpt-image-2` 官方文档已经支持满足约束的自定义 `size`，因此本地计费必须能够对未知尺寸做稳定分档，同时不能因为本地映射不认识就提前拦截请求。
|
||
|
||
用户澄清后的业务要求是：普通编码分组可以关闭生图，也可以开启生图；开启后默认继续共享现有分组倍率以保持兼容，但管理员可以打开“生图倍率独立”开关，改用单独的图片倍率输入框。图片分组是推荐的运营隔离方式，但不是唯一承载方式。
|
||
|
||
## Goals / Non-Goals
|
||
|
||
**Goals:**
|
||
- 分组具备明确的 `allow_image_generation` 开关，所有已知生图入口在调度上游前执行同一个权限判断。
|
||
- 分组具备“生图倍率是否独立”的开关；默认 `false`，即共享当前代码里的有效分组倍率。
|
||
- 生图倍率独立开关打开后，图片费用使用单独的 `image_rate_multiplier`，不再使用普通编码分组的倍率。
|
||
- 保留现有 `image_price_1k/2k/4k` 字段作为图片单价配置，不强制把它们迁移成新的语义。
|
||
- 普通编码分组在 `allow_image_generation=false` 时仍可正常使用 `gpt-5.4` / `gpt-5.5` 文本能力，但不能使用图片工具。
|
||
- 普通编码分组在 `allow_image_generation=true` 时可使用 `gpt-5.4` / `gpt-5.5 + image_generation`，且按实际图片数量收费。
|
||
- 通用 `/v1/responses`、OpenAI Images API、流式、非流式、透传路径全部把成功产出的图片数量写入 `ImageCount`。
|
||
- 渠道 `billing_mode=image` 使用真实 `ImageCount`，不再固定按 1 次收费。
|
||
|
||
**Non-Goals:**
|
||
- 不引入新的第三方依赖。
|
||
- 不改变 OpenAI 上游协议；只在现有请求转发、响应解析和计费归因层补齐控制。
|
||
- 不把“图片分组”做成唯一安全边界；分组开关和图片计费逻辑必须适用于任意开启生图的分组。
|
||
- 不在本变更中实现预扣费/资金冻结；失败请求仍不收费，成功请求按实际产物后扣费。
|
||
- 不改变默认历史图片价格行为；默认共享现有有效倍率，历史 `图片价格 * 分组/用户有效倍率` 的扣费行为保持。
|
||
- 不在本变更中新增用户级图片独立倍率覆盖；用户专属普通倍率只在共享倍率模式下继续影响图片。
|
||
|
||
## Decisions
|
||
|
||
### 0. 兼容性优先原则
|
||
|
||
本变更的默认行为必须以“不改变现有已配置分组的最终扣费”为优先级：
|
||
|
||
- 迁移不修改现有 `image_price_1k/2k/4k`。
|
||
- 迁移把所有现有分组设置为 `image_rate_independent=false`，因此现有图片路径继续使用当前有效分组倍率。
|
||
- 管理员不传新字段更新分组时，不得覆盖已保存的 `allow_image_generation`、`image_rate_independent`、`image_rate_multiplier`。
|
||
- 前端编辑旧分组时必须回显服务端值；不能因为表单默认值把旧分组从共享倍率误改成独立倍率，或把允许生图误改成禁止生图。
|
||
- 只有管理员显式打开 `image_rate_independent` 后，图片扣费才从共享倍率切换到图片独立倍率。
|
||
|
||
### 1. 分组字段与迁移策略
|
||
|
||
新增三个分组字段，对应“2 个开关 + 1 个输入框”：
|
||
|
||
- `allow_image_generation BOOLEAN NOT NULL DEFAULT false`
|
||
- `image_rate_independent BOOLEAN NOT NULL DEFAULT false`
|
||
- `image_rate_multiplier DECIMAL(10,4) NOT NULL DEFAULT 1.0`
|
||
|
||
字段语义：
|
||
|
||
- `allow_image_generation`：是否支持当前分组生图。
|
||
- `image_rate_independent=false`：图片计费共享当前普通计费链路里的有效倍率，即当前 `userGroupRateResolver.Resolve(ctx, user.ID, groupID, group.RateMultiplier)` 得到的倍率；这保持现有行为。
|
||
- `image_rate_independent=true`：图片计费使用 `group.image_rate_multiplier`；普通编码的 `rate_multiplier` 和用户专属普通倍率不参与图片扣费。
|
||
- `image_price_1k/2k/4k`：继续表示图片基础单价，由选中的图片倍率模式继续相乘。
|
||
|
||
新建分组默认 `allow_image_generation=false`，避免新普通编码分组意外获得生图能力。为避免升级后立即打断已有图片业务，迁移对现有 `openai`、`gemini`、`antigravity` 分组回填 `allow_image_generation=true`，`anthropic` 分组保持 `false`。该回填只是兼容现状；上线后管理员必须按业务策略关闭不允许生图的普通编码分组。
|
||
|
||
迁移不改写已有 `image_price_1k/2k/4k`，并将所有现有分组设为 `image_rate_independent=false`、`image_rate_multiplier=1`。这样现有最终扣费公式保持不变：
|
||
|
||
```text
|
||
历史/默认模式图片最终扣费 = image_price_* * image_count * 当前有效分组倍率
|
||
```
|
||
|
||
普通编码分组 `rate_multiplier=0.15` 且希望图片 1K 最终扣费 `0.2/张` 时，管理员不再需要填写 `0.2/0.15`，而是设置：
|
||
|
||
```text
|
||
image_rate_independent = true
|
||
image_rate_multiplier = 1
|
||
image_price_1k = 0.2
|
||
```
|
||
|
||
如果希望图片也打折，例如图片标价 `0.2/张`、图片折扣 `0.8`，则设置：
|
||
|
||
```text
|
||
image_rate_independent = true
|
||
image_rate_multiplier = 0.8
|
||
image_price_1k = 0.2
|
||
```
|
||
|
||
### 2. 生图意图统一识别
|
||
|
||
新增一个服务层 helper，输入至少包含 endpoint、请求模型、请求体，输出是否为生图意图：
|
||
|
||
```text
|
||
isImageGenerationIntent =
|
||
endpoint 是 /v1/images/generations 或 /v1/images/edits
|
||
OR requested model 以 gpt-image- 开头
|
||
OR tools[] 存在 type == image_generation
|
||
OR tool_choice 显式指向 image_generation
|
||
```
|
||
|
||
生图意图判断必须在请求体被 Codex 注入、模型改写、渠道映射改写之前执行一次，并在这些改写之后再对最终请求体执行一次。原因是当前代码会在 `backend/internal/service/openai_gateway_service.go` 中注入 `image_generation` tool，也会在 `normalizeOpenAIResponsesImageOnlyModel` 中把 `gpt-image-*` 改写为文本模型 + 图片工具；只检查改写前或只检查改写后都可能漏掉场景。
|
||
|
||
`tool_choice` 判断只把明确指向 `image_generation` 的值视为生图意图；`auto`、`none`、`required` 本身不构成生图意图，但如果 `tools[]` 中存在 `image_generation`，仍由 `tools[]` 规则命中。
|
||
|
||
该判断必须在以下位置使用：
|
||
|
||
- `/v1/images/*` handler 解析请求后、账号调度前。
|
||
- `/v1/responses` 解析 body 后、Codex 自动注入 `image_generation` tool 前。
|
||
- `normalizeOpenAIResponsesImageOnlyModel` 把 `gpt-image-*` 改写为 Responses 文本模型前。
|
||
- OpenAI 高级 scheduler 入口保留现有账号能力检查，同时补齐渠道 restriction 检查，避免启用高级调度时绕过渠道模型限制。
|
||
|
||
当 `allow_image_generation=false` 时：
|
||
|
||
- 显式生图意图返回 HTTP 403，错误类型使用现有 `permission_error` 风格。
|
||
- Codex CLI 请求不自动注入 `image_generation` tool，也不追加图片桥接指令；如果请求没有显式生图意图，则继续按普通文本请求处理。
|
||
|
||
### 3. gpt-5.4 / gpt-5.5 生图承载方式
|
||
|
||
`gpt-5.4` / `gpt-5.5` 生图通过现有 OpenAI Responses API 的 `image_generation` tool 承载，不新增专用 endpoint：
|
||
|
||
```json
|
||
{
|
||
"model": "gpt-5.4",
|
||
"input": "生成一张图片",
|
||
"tools": [
|
||
{
|
||
"type": "image_generation",
|
||
"model": "gpt-image-2",
|
||
"size": "1024x1024",
|
||
"output_format": "png"
|
||
}
|
||
],
|
||
"tool_choice": { "type": "image_generation" }
|
||
}
|
||
```
|
||
|
||
`model=gpt-image-*` 发到 `/v1/responses` 时保留现有改写方向：主模型改为 Responses 文本模型，图片模型放入 `image_generation` tool。计费时如果能从工具配置得到 `gpt-image-*`，图片默认价格按该图片模型解析；如果工具未指定图片模型，则使用当前转发结果的 billing model，并优先使用分组/渠道配置价格。
|
||
|
||
### 4. 图片数量归因
|
||
|
||
新增统一图片输出解析 helper，返回去重后的图片数量和可用图片元信息。必须覆盖以下已有或可借鉴的事件形态：
|
||
|
||
- 非流式 Responses JSON：`output[]` 中 `type == image_generation_call` 且 `result` 非空。
|
||
- Responses SSE：`response.output_item.done` 中 `item.type == image_generation_call` 且 `item.result` 非空。
|
||
- Responses SSE 完成事件：`response.completed.response.output[]` 中图片工具结果。
|
||
- Images API 非流式：顶层 `data[]`。
|
||
- Images API 流式：顶层 `data[]`、`image_generation.completed`、`response.output_item.done`、`response.completed`。
|
||
|
||
去重键按优先级使用 `item.id`、`call_id`、`result` 内容 hash。只统计最终图片，不统计 `partial_image`。
|
||
|
||
`openaiStreamingResult` 增加 `imageCount`、`imageSize`、`imageBillingModel`。`handleStreamingResponse`、`handleStreamingResponsePassthrough`、`handleNonStreamingResponse`、`handleNonStreamingResponsePassthrough` 都必须把解析结果带回 `OpenAIForwardResult`。当 `ImageCount > 0` 时，即使上游 usage 为 0，也必须写 usage log 并进入图片计费。
|
||
|
||
### 5. 图片价格公式
|
||
|
||
图片计费先确定单价，再确定倍率：
|
||
|
||
```text
|
||
unit_price = 渠道 image 模式价格 或 分组 image_price_* 或 默认图片价格
|
||
image_multiplier =
|
||
如果 group.image_rate_independent == true: group.image_rate_multiplier
|
||
否则: 当前有效分组倍率
|
||
total_cost = unit_price * image_count
|
||
actual_cost = total_cost * image_multiplier
|
||
```
|
||
|
||
“当前有效分组倍率”必须沿用当前代码的倍率解析方式：默认配置倍率 → 分组 `rate_multiplier` → 用户专属分组倍率覆盖。这样 `image_rate_independent=false` 时完全保留当前行为。
|
||
|
||
`billing_mode=image` 的渠道价格是图片单价来源之一，仍优先于分组图片价格。图片渠道价格也必须按 `ImageCount` 计数，并使用同一套 `image_multiplier` 选择逻辑。
|
||
|
||
`billing_mode=per_request` 的非图片请求保持当前普通按次语义，继续使用普通 token 倍率；只有已经识别为图片请求且 `ImageCount > 0` 的路径使用图片计费逻辑。
|
||
|
||
`usage_logs.rate_multiplier` 继续表示“本次扣费实际使用的倍率”。因此：
|
||
|
||
- token 日志记录普通 token 有效倍率。
|
||
- image 日志在共享模式记录普通有效倍率。
|
||
- image 日志在独立模式记录 `image_rate_multiplier`。
|
||
|
||
专用 `/v1/images/*` 仍按图片请求语义计费：当 `ImageCount > 0` 时，图片价格决定费用，伴随的上游 token usage 只记录不额外计 token 费用。这保持当前 Images API 的行为。
|
||
|
||
通用 `/v1/responses + image_generation` 的混合文本+图片输出存在一个明确取舍：如果继续沿用“`ImageCount > 0` 时只按图片计费”的当前计费分支，用户可以在一次图片请求中夹带大量文本输出而只付图片费用；如果改成“图片费用 + 非图片 token 费用”，会改变当前 `billing_mode=image` 的单一计费语义，并可能让渠道图片单价不再是全包价格。本变更为最大兼容性不引入混合计费模式，但必须在 usage log 中完整记录 token 与 image_count，便于后续按数据决定是否新增 `image_plus_token` 计费模式。
|
||
|
||
### 6. 尺寸档位与参数透传
|
||
|
||
OpenAI 图片请求的 `size` 参数必须透传给上游；本地只做计费分档，不做 OpenAI 尺寸合法性校验。无论尺寸是否满足官方约束，本地都不能因为未知尺寸或 provider-invalid 尺寸返回 400；如果上游不接受该尺寸，由上游响应错误。
|
||
|
||
官方 `gpt-image-2` 文档给出的常用尺寸与约束是本地计费分档的依据：
|
||
|
||
- 常用尺寸：`1024x1024`、`1536x1024`、`1024x1536`、`2048x2048`、`2048x1152`、`3840x2160`、`2160x3840`、`auto`。
|
||
- 自定义尺寸：官方支持满足约束的任意 `size`，包括边长、16 像素倍数、长短边比例、总像素范围等约束。
|
||
- `2560x1440` 是 2K/QHD 参考边界；超过 `2560x1440` 总像素的输出进入更高档位风险区。
|
||
|
||
OpenAI 图片尺寸分层必须按以下规则：
|
||
|
||
```text
|
||
empty, auto => 2K
|
||
1024x1024 => 1K
|
||
1536x1024, 1024x1536 => 2K
|
||
1792x1024, 1024x1792 => 2K
|
||
2048x2048, 2048x1152, 1152x2048 => 2K
|
||
3840x2160, 2160x3840 => 4K
|
||
未知且无法解析为正整数 WIDTHxHEIGHT => 2K
|
||
未知且 WIDTH * HEIGHT <= 2560*1440 => 2K
|
||
未知且 WIDTH * HEIGHT > 2560*1440 => 4K
|
||
```
|
||
|
||
这个规则只决定 `ImageSize` 和扣费档位，不修改请求体，不删除未知参数，不把未知尺寸改写成预设尺寸。
|
||
|
||
## Risks / Trade-offs
|
||
|
||
- 历史普通编码分组迁移后仍默认允许生图 → 通过管理员可见开关、上线核对清单和新建分组默认关闭来控制；代码无法可靠判断“普通编码分组”和“图片分组”的业务意图。
|
||
- 默认共享现有有效倍率仍保留“图片最终价不直观”的问题 → 这是兼容性选择；需要直观设置图片最终价的分组必须打开 `image_rate_independent`。
|
||
- 独立图片倍率不会读取用户专属普通倍率 → 这是目标行为；如需要用户级图片独立倍率，应作为后续独立需求实现。
|
||
- 通用 Responses 图片工具可能同时输出文本和图片 → 本变更默认仍按图片请求语义计费并完整记录 token；若业务要求文本也收费，应新增独立的混合计费模式，不能混入本次兼容性变更。
|
||
- 本地不再拦截未知或 provider-invalid OpenAI 尺寸 → 非法尺寸会消耗一次上游请求失败成本和用户体验往返，但这是为了保证参数透传、兼容官方新增尺寸和第三方兼容提供商；计费只在成功产出最终图片后发生。
|
||
- Responses 流式解析需要在客户端断开后继续 drain 上游以完成计费 → 沿用当前流式处理“客户端断开后继续读取上游用于计费”的模式，并只新增轻量 JSON 路径提取。
|
||
- 预扣费不在本变更中实现 → 继续使用现有成功后扣费模型，避免失败请求退款、流式中断退款和图片数量未确定时预估错误。
|
||
|
||
## Migration Plan
|
||
|
||
1. 新增数据库迁移，添加 `groups.allow_image_generation`、`groups.image_rate_independent` 和 `groups.image_rate_multiplier`。
|
||
2. 回填现有分组：`openai`、`gemini`、`antigravity` 的 `allow_image_generation=true`，`anthropic=false`；所有现有分组 `image_rate_independent=false`、`image_rate_multiplier=1`。
|
||
3. 不改写现有 `image_price_1k/2k/4k`，保持默认共享倍率模式下的历史扣费结果。
|
||
4. 更新 Ent schema 与生成代码，更新后端 service/handler DTO 和前端类型。
|
||
5. 先接入权限判断，确保未开启生图的分组不会到达上游。
|
||
6. 再接入图片数量解析和图片计费倍率选择，确保开启生图的分组按图片数量收费。
|
||
7. 最后更新前端管理界面、i18n、文档和测试。
|
||
8. 回滚时只能通过新迁移回滚字段行为；不能修改已应用迁移文件。
|
||
|
||
## Open Questions
|
||
|
||
无。当前方案不依赖未确认的上游新尺寸、新模型或新 endpoint。
|