多厂商 AI 调度：统一混乱的供应商生态

单一供应商是脆弱的。

当你的应用依赖某个 AI 厂商的 API，你就把命运交给了他们的稳定性、定价策略和服务质量。厂商 API 超时、限流、下线，你的应用就停摆。

多厂商调度的核心不是贪多，而是分散风险。但它带来了新的复杂度：每个厂商的 API 不同，参数不统一，返回格式各异。如何在这种混乱中建立秩序？

核心挑战：差异性

AI 厂商的 API 差异体现在三个层面。关于分布式 Workers 架构的整体设计，参见 purikura-workers-architecture。

参数命名 Fal.ai 用 prompt，KIEAI 用 text，OpenAI 可能用 input。同样的功能，不同的字段名。

参数结构 有的厂商用扁平结构 { width: 1920, height: 1080 }，有的用嵌套对象 { resolution: { width: 1920, height: 1080 } }。

响应格式 Webhook 回调的数据结构完全不同。Fal.ai 返回 output.video.url，KIEAI 返回 data.result_url。

这些差异不是小问题。如果直接在业务代码中处理每个厂商的特殊情况，代码会变成 if-else 地狱。每次添加新厂商，你要改动十几处地方。

统一抽象：UniversalModel

解决方案是建立统一的抽象层。所有厂商的差异被封装在适配器（Adapter）中，业务代码只看到统一的接口。

interface UniversalModel {
  id: string
  name: string
  type: 'image' | 'video'
  vendor: string
  parameters: {
    prompt: string
    resolution?: { width: number; height: number }
    duration?: number
    // ... 统一的参数定义
  }
}

前端只需要知道 UniversalModel，不需要关心是哪个厂商。用户选择模型后，系统自动找到对应的适配器，转换参数，调用 API。

适配器的职责：

1. 参数转换 - 把统一参数转成厂商特定格式
2. 请求构建 - 构造 HTTP 请求（headers、body、auth）
3. 响应解析 - 把厂商响应转成统一格式
4. 错误映射 - 把厂商错误码转成统一的错误类型

这种设计的好处是扩展性。添加新厂商时，你只需要实现一个新的适配器，不需要修改业务代码。测试也更容易，每个适配器可以独立测试。

关键流程：生成、恢复、退款

AI 生成是异步的、不可靠的、需要容错的。

但生成可能失败。厂商 API 超时、限流、内部错误。这时需要两个关键机制。

僵尸任务恢复 任务卡在 processing 状态超过 30 分钟，可能是 Webhook 丢失或厂商没有回调。定时任务每 15 分钟扫描一次，向厂商查询真实状态，同步到数据库。

但不能无限重试。如果 24 小时内查询超过 20 次仍未完成，标记为不可恢复，触发退款。

自动退款 失败任务自动触发退款，返还用户积分。退款也可能失败（数据库连接问题、并发冲突），所以用指数退避重试（详见 exponential-backoff-timeout）。

死信队列（DLQ）是最后的安全网。如果退款重试全部失败，任务进入 DLQ，等待人工处理。DLQ 不是失败的标志，而是对自动化边界的承认。

积分系统：统一的度量

不同厂商的定价模型不同。有的按秒计费，有的按分辨率计费，有的按请求次数计费。如何统一？

答案是积分系统。用户购买积分，生成消耗积分。积分是抽象的货币，屏蔽了厂商定价的差异。

积分计算规则：

function calculateCredits(model: UniversalModel, params: GenerationParams) {
  const baseCost = model.base_credit_cost;
  const resolutionMultiplier = getResolutionMultiplier(params.resolution);
  const durationMultiplier = params.duration / 5; // 每 5 秒为基准

  return Math.ceil(baseCost * resolutionMultiplier * durationMultiplier);
}

这个公式不是理论推导的，而是在实际运营中调整的。基础成本基于厂商 API 的实际费用，乘数根据用户接受度和竞争对手定价调整。

积分系统还解决了另一个问题：预扣款。在任务提交时扣除积分，而不是完成时。这避免了用户余额不足导致的任务失败。如果任务失败，退款流程返还积分。

可观测性：全链路追踪

分布式系统的调试是噩梦。一个请求经过前端、API Gateway、队列、AI 处理器、厂商 API，最后通过 Webhook 回调。任何一个环节出错，如何定位？

答案是全链路追踪。每个请求生成一个 traceId，它随着调用链传播。

// 前端生成 traceId
const traceId = `client_${Date.now()}_${randomId()}`;

// API Gateway 接收并创建新的 trace 上下文
const serverTraceId = traceManager.createTrace('video_generation', {
  clientTraceId: traceId,
  userId: user.id
});

// 队列消息包含 traceId
await queue.send({
  jobId,
  payload,
  traceId: serverTraceId
});

// AI 处理器继承 trace
const span = traceManager.createSpan(traceId, 'vendor_api_call');

每个关键操作都创建一个 Span，记录开始时间、结束时间、状态、错误信息。Span 之间通过 traceId 关联，形成调用树。

当用户报告问题时，你搜索 traceId，看到整个请求的生命周期：什么时候创建、什么时候入队、什么时候调用厂商、什么时候回调、哪里出错。

数据库：单一真相源

所有状态的权威来源是数据库。

数据库的角色不只是存储，更是协调者。当多个 Worker 并发操作同一条记录时，数据库的事务和锁确保了一致性。

架构的本质

多厂商调度的复杂度不在技术细节，而在对不确定性的管理。

厂商 API 会超时、会限流、会下线。Webhook 会丢失。网络会分区。这些都是现实，不是异常。

架构设计不是消除不确定性，而是让系统在不确定性中依然可靠。重试机制、僵尸任务恢复、自动退款、死信队列，这些机制不是完美的，但它们定义了系统在混乱中的行为边界。

关于从意图到架构的思考过程，参见 from-intent-to-architecture。

好的架构不是一次性设计的，而是在约束条件下持续演化的结果。Purikura 的多厂商调度从单一厂商开始，每次遇到问题就添加新的保护层。现在它支持多个厂商，但代价是更高的复杂度。

这个权衡是否值得？取决于你的业务需要多高的可靠性。如果单点故障不可接受，多厂商是必然选择。

最后更新：2025-11-06