Marico's space

译者前言：Laravel 生态丰富，但 AI 集成这块的架构坑不少——限流、token 燃烧、Provider 锁定，每一个都能让凌晨两点的你从床上爬起来。这篇文章给了一张系统级地图，不讲任何一个 Provider 的认证流程，但把 OpenAI、Gemini、Claude 三家的本质差异讲清楚了。选 Provider 前，先把架构搭好。

Laravel AI 集成问题域

在选择提供商或绘制服务图之前，你需要诚实地面对你实际在构建什么。使得 AI 在生产环境中难以驾驭的问题并不专属于任何一个提供商。它们是结构性的。

Provider 抽象

在产品生命周期中，你几乎肯定会切换或组合提供商。发布时有意义的模型很少是规模化后有意义的模型，也很少是定价变化后或用例演进后有意义的模型。如果你的应用代码直接耦合到 OpenAI 的 SDK 或 Anthropic 的客户端，那么切换提供商意味着重写功能逻辑，而不仅仅是换一个配置值。

正确的做法是建立一个应用依赖的 provider 接口，并在其后放置具体适配器。

Token 使用与成本控制

语言模型按 token 计费。听起来很简单。实际上，这意味着一个配置错误的 prompt，乘以你的队列吞吐量，就能在一下午产生一张五位数的账单。我们见过这种情况发生。

在生产环境中，token 管理不是可选项。你需要在 API 调用前进行预算强制执行，在响应层面记录使用量，并在支出超过阈值时发出警报。这些属于服务层——不在控制器里，也不在事后才运行的计划任务里。

延迟与流式处理

在 HTTP handler 中进行同步 AI 调用几乎总是错误的。推理延迟从轻量级模型的 800ms 到长篇推理任务的 30 秒不等。PHP-FPM 在整个时间窗口内保持连接打开。在任何有意义的流量下，这都会让你的 worker 池崩溃。

流式处理在用户体验方面有帮助，但它不能解决连接压力问题。后台任务才能解决这个问题。

错误处理与重试

AI API 会失败。它们在流量高峰时返回 429，在模型不稳定时返回 500，偶尔完全超时且没有任何响应体。这些都不是异常情况。它们是常态。

你的重试逻辑必须区分瞬时失败（值得用退避策略重试）和结构性失败（错误的 API key、格式错误的 payload、超出上下文长度）。对所有失败一视同仁是我们看到的 AI 集成 Laravel 应用中最常见的生产 bug 之一。

供应商锁定

每个提供商都有专有扩展——函数调用格式、system prompt 约定、流式事件结构、视觉附件 schema。一旦你把这些结构硬编码到应用逻辑中，下次需要切换时就背负了一个迁移项目。

抽象是缓解之道。但抽象有成本。在正确的层级构建它，把提供商特定的行为放在适配器里，而不是你的领域服务中。

Provider 对比：OpenAI vs Gemini vs Claude

没有哪个提供商对所有用例都是正确答案。以下是 Laravel AI 集成的三个主流选择的诚实对比。

OpenAI 拥有最成熟的 Laravel 生态。第一方包稳定，API 表面文档完善，函数调用在生产环境中经过大规模测试。对于构建通用 AI 功能且架构预算有限的团队来说，它是正确的默认选择。

Gemini 的一百万 token 上下文窗口不是一个营销数字，它真正改变了文档处理、长会话记忆和无 RAG（检索增强生成）检索模式的可能性。缺点是限流执行不一致，且模型在上下文窗口边界处的行为不如 Anthropic 或 OpenAI 的可预测。

Claude 是推理密集型任务、结构化输出提取、代码审查管道以及任何需要可靠遵循复杂多步指令的场景中最一致的模型。安全约束是真实存在的，对于边缘情况偶尔令人沮丧，但指令遵循质量证明了为高风险功能支付略高成本的合理性。

Laravel AI 系统推荐架构

在每个提供商、每个规模、每个用例中保持不变的 pattern 是相同的：通过一个类型化契约隔离 AI，为每个提供商实现具体适配器，并通过 Service Container 注册活跃的 provider。

每个提供商——OpenAI、Gemini、Claude——都有各自的适配器类实现这个接口。你的应用服务、队列任务和控制器都依赖 AIProviderInterface。它们永远不知道背后是哪个提供商。

现在切换提供商只需一行配置变更。领域逻辑不需要移动。

Token 管理与成本控制

这是大多数架构指南跳过的章节。这也是决定你的 AI 功能在财务上是否可行的章节。

Token 成本会复利。每天运行 500 次、每次 2000 tokens 的功能是一天 100 万 tokens。乘以你的模型每 token 费率，再乘以 30，你就得到了一个从第一天起就应该进入预算讨论的月度基础设施账单。

执行检查点必须在分发前。这意味着在 API 调用发起前检查预估 token 数量与配置的预算，而不是在响应到达后。你无法追回已经消耗的 tokens。

遥测是成本控制的另一半。在每个响应上记录 prompt tokens、completion tokens、模型、延迟以及用户或租户身份。没有这些数据，你就无法归因成本、识别昂贵的调用模式，或对模型选择做出明智决策。

流式响应 vs 标准响应

在流式响应和同步响应之间做选择是一个有基础设施后果的用户体验决策。

同步调用适用于后台任务、计划任务，以及任何在用户看到结果前就已写入存储的场景。它们实现更简单，测试更容易，不需要任何特殊传输基础设施。如果你的 AI 调用为写入 Eloquent 的 Queue Worker 提供数据，同步是正确的默认选择。

流式处理适用于有人在等待且输出足够长以至于完整响应延迟会降低体验的场景。实践中阈值大约是 1.5-2 秒。低于这个阈值，流式处理增加复杂度但没有可感知的好处。

Server-Sent Events 是 Laravel 的正确默认选择，它们不需要额外基础设施，通过标准 HTTP 工作，并与 Livewire 干净集成。WebSockets 在你需要双向通信或多客户端广播时是合理的。Livewire 轮询是一个合理的备选方案，适合想完全避免流式基础设施的团队，代价是可感知的响应性。

选择正确的 Provider：决策框架

别再把 provider 选择当作偏好来对待。把它当作一个有明确输入的工程决策。

使用 OpenAI 当：

• 你需要在生成的同时需要原生嵌入（text-embedding-3-small 覆盖大多数检索用例）
• 你的团队需要最广泛记录的集成路径
• 你在构建函数调用管道，其中工具可靠性比推理深度更重要
• 你想为一个后续可能演进 MVP 使用最低开销的 Laravel AI 集成

使用 Gemini 当：

• 你的用例涉及超过 128K tokens 的文档或会话
• 你正在大规模处理多模态输入——文档、图片、混合媒体
• 你想尝试使用 Gemini 的长上下文作为检索代理的无 RAG 模式
• 大量成本是主要考虑因素（Gemini 2.0 Flash 在高调用率下很有竞争力）

使用 Claude 当：

• 任务需要精确可靠地遵循多步指令
• 你正在从非结构化文本中提取结构化输出（JSON 提取、数据规范化）
• 安全和拒绝行为很重要——受监管行业、内容审核管道
• 代码生成或审查是工作负载的重要组成部分

混合 Provider 架构

前面描述的接口模式使多提供商设置变得实用。按任务类型路由，OpenAI 用于嵌入，Claude 用于结构化提取，Gemini 用于长文档摘要，这是一个合法的生产架构，不是过度设计。Service Container 按任务类型解析正确的适配器，你的领域代码保持干净。

结论

如果你从本指南中学到一件事，那就是：提供商是可互换的。架构不是。

OpenAI、Gemini 和 Claude 都会在接下来十二个月中改进、弃用模型、改变定价和引入新能力。三个中的任何一个今天可能是正确选择，两个季度后可能是错误选择。平稳度过这些变化的团队是在需要之前就构建了抽象层的团队，而不是那些将应用耦合到特定 SDK 现在正重写功能逻辑来切换提供商的团队。

生产级 Laravel AI 集成是一个系统设计问题。接口契约、适配器层、token 预算强制执行、流式传输决策、遥测管道——这些决策决定了你的 AI 功能在运维上是否可持续，还是只是一个扩展性差的 demo。

先构建这一层。然后再选提供商。