feat(ai): 接入 gpt-image-2 图片生成(文生图 + 图生图)
CI / ai-gates (push) Successful in 38s

新增 app/providers/openai/:client 传输(JSON + multipart)、errors 错误映射、
models 厂商 DTO、capabilities 尺寸算术约束、tasks 同步→异步桥、image 图片业务。
装配与配置同步接入,缺 OPENAI_API_KEY 时跳过装配、服务仍可启动。

与火山视频的三处根本差异及其处置:
- 接口同步(无任务 ID、无查询端点)→ SyncTaskRegistry 在本服务内部吸收,
  对外仍是 ADR-023 §4 的两段式提交/轮询。代价:本服务从此持有状态,进程重启
  丢在途任务,且横向扩容前须先解决任务 ID 只在签发进程内有效的问题。
- 产物是 base64 字节而非 URL → 无过期问题,但字节只在内存里。asset_url 放
  data URI 仅为满足领域不变式,绝不能原样写进 media.assets.external_url。
- 图生图走 multipart → 先下载参考图再上传;下载失败与超限按参数错误同步拒绝,
  不变成注定失败的后台任务。

两处需要记住的判断:
- 尺寸上限「3840x2160」文档未说清是逐边还是按像素。逐边理解会禁掉所有高于
  2160 的竖图,而 1024x1536 是文档明示的标准竖图,故必然过严。采用最长边
  ≤3840 且总像素 ≤3840×2160,已在 capabilities.py 与取证页标为推断。
- 两份文档都没有错误码表,故 errors.py 以 HTTP 状态码为主、type/code 为辅,
  顶部标注「未经文档证实」。429 无线索时按限流而非配额耗尽(猜成配额会把可
  重试的限流判死);400 无线索时归服务端错误而非内容被拒(错报会让用户去改
  一个其实没问题的提示词)。

一处死锁已修并回归钉住:SyncTaskRegistry 原用 add_done_callback 记录完成时刻,
而快速完成的任务在注册时已 done,回调便同步地在持有非可重入锁的线程里执行。
改为首次被观察到时惰性记录。

测试 166 → 271(+105)。四道门禁逐条读退出码,全绿。
产物转存仍阻塞于存储决策(ADR-023 §7),图片模型因此未播种进 V7 目录。
This commit is contained in:
2026-09-21 12:10:07 +08:00
parent 062e11b1ff
commit 8275a04903
21 changed files with 2375 additions and 11 deletions
+56
View File
@@ -14,6 +14,7 @@ from __future__ import annotations
import os
from dataclasses import dataclass, field
from app.providers.openai.client import DEFAULT_BASE_URL as OPENAI_DEFAULT_BASE_URL
from app.providers.volcengine.models import DEFAULT_BASE_URL
@@ -83,6 +84,59 @@ class VolcengineSettings:
)
@dataclass(frozen=True)
class OpenAiSettings:
"""OpenAI 图片接入配置。
:param api_key: `OPENAI_API_KEY`。**无默认值**,缺失时该适配器不装配。
:param timeout_sec: **这里确实是生成耗时的上限**,与火山那边不同——OpenAI 的
图片接口是同步的,一次请求里等到图片生成完才返回。故默认值比火山的
「短往返超时」大一个量级。
:param image_model: 图片模型 ID,仅作兜底;正常由 Java 侧传入任务行的快照。
:param max_concurrent: 同时执行的同步调用数上限。**同时也是对服务商并发和
「同时有多少钱在花」的自我限制**——超出的提交排队而非一起打过去。
:param completed_ttl_sec: 已完成任务在内存注册表里的保留时长。须大于 Java 侧
最长的轮询间隔(当前阶梯最长 30 秒),否则结果会在被取走前被清理。
"""
api_key: str = ""
base_url: str = OPENAI_DEFAULT_BASE_URL
timeout_sec: float = 180.0
image_model: str = ""
organization: str = ""
max_concurrent: int = 4
completed_ttl_sec: float = 900.0
max_inflight: int = 256
@classmethod
def from_env(cls) -> OpenAiSettings:
return cls(
api_key=_env("OPENAI_API_KEY"),
base_url=_env("OPENAI_BASE_URL", cls.base_url),
timeout_sec=_env_float("OPENAI_TIMEOUT_SEC", cls.timeout_sec),
image_model=_env("OPENAI_IMAGE_MODEL"),
organization=_env("OPENAI_ORGANIZATION"),
max_concurrent=_env_int("OPENAI_MAX_CONCURRENT", cls.max_concurrent),
completed_ttl_sec=_env_float(
"OPENAI_COMPLETED_TTL_SEC", cls.completed_ttl_sec
),
max_inflight=_env_int("OPENAI_MAX_INFLIGHT", cls.max_inflight),
)
def __post_init__(self) -> None:
if self.max_concurrent < 1:
raise ValueError(
f"OPENAI_MAX_CONCURRENT 必须 >= 1,当前 {self.max_concurrent}"
)
# 小于最长轮询间隔会让结果在被取走前就被清掉——那表现为「任务成功了但查
# 不到」,极难查。
if self.completed_ttl_sec < 60:
raise ValueError(
f"OPENAI_COMPLETED_TTL_SEC 不应小于 60 秒(须大于 Java 侧最长轮询"
f"间隔,否则结果会在被取走前被清理),当前 {self.completed_ttl_sec}"
)
@dataclass(frozen=True)
class ServiceAuthSettings:
"""校验 Java 侧服务身份 JWT 所需的配置(ADR-023 §5)。
@@ -113,6 +167,7 @@ class Settings:
"""本服务的全部配置。"""
volcengine: VolcengineSettings = field(default_factory=VolcengineSettings)
openai: OpenAiSettings = field(default_factory=OpenAiSettings)
service_auth: ServiceAuthSettings = field(default_factory=ServiceAuthSettings)
log_level: str = "INFO"
@@ -120,6 +175,7 @@ class Settings:
def from_env(cls) -> Settings:
return cls(
volcengine=VolcengineSettings.from_env(),
openai=OpenAiSettings.from_env(),
service_auth=ServiceAuthSettings.from_env(),
log_level=_env("PATBOND_AI_LOG_LEVEL", cls.log_level).upper(),
)