Laravel 新闻流水线的智能体工程经验
NewSumm 用 Laravel AI SDK 处理每日数万篇新闻,通过队列任务串联采集、向量化、pgvector 聚类和智能体摘要。文章介绍真实项目的代码组织与难以被测试发现的故障,但省略了提示词、模型和阈值。
AI 深度解读
NewSumm 每天从数百家媒体读取数万篇新闻,把同一事件的报道归成一个故事,再生成共识、分歧和摘要。作者用 Laravel AI SDK(laravel/ai)搭建这条流水线,最有价值的经验却集中在模型调用前后:怎样减少请求、拦住坏输入,以及发现「测试全绿、生产停更」的故障。
它给程序员的结论很直接:AI 功能能上线,靠的不只是提示词。批处理、队列、接口契约和错误监控,往往比换模型更影响成本与可靠性。
先决定模型读什么,省钱才有空间
流水线的每一步都是队列任务:抓取并保存文章,用标题和描述生成嵌入向量(embeddings),在 Postgres 中通过 pgvector 按向量相似度聚类,最后只为包含多篇报道的故事生成摘要。
这里要区分两类调用:文章仍需逐篇生成向量,只有最后一步调用文本语言模型。
作者给出的两天样本包含 51,842 篇文章,其中有 4,748 个故事包含至少两篇报道,相当于文章数量的 9.2%。这不是「只有 9.2% 的文章属于多源报道」,而是故事数与文章数之比。作者据此说明,按故事生成摘要,相比逐篇生成,可以把调用量压低约一个数量级。
先减少需要生成的工作,再讨论用哪个模型。
在代码组织上,agent 是实现 Agent 接口、使用 Promptable trait 的普通类,提示词放进 instructions(),进入代码审查和版本管理。
#[UseCheapestModel] 让 SDK 选择提供商最便宜的文本模型。作者认为摘要、比较和字段提取足够具体,小模型可以胜任;代码也不必绑定模型名。通过 StorySummaryAgent::make(compareOutlets: $story->hasEnoughSources())->prompt(...),同一个类还能按来源数量调整指令和输出字段。
不过,原文刻意省略了实际模型、提示词和阈值,提供的是组织方式,没有足够信息复现摘要质量。
一个空白标题,为什么能让整站停止更新
作者每批处理 50 篇文章,用 Embeddings::for($texts)->generate() 请求向量,返回的 $response->embeddings 与输入顺序一致。
问题在于,一条坏输入就可能让整批收到 HTTP 400。
坏输入有三类:描述里塞了全文导致超长;标题和描述都为空;看着是空白,实际包含不换行空格或零宽空格。第三类尤其隐蔽,trim() 和 filled() 都可能放行。
下面这段检查用于识别空字符串,以及完全由 Unicode 控制类、分隔类字符组成的文本:
private function isBlank(string $text): bool
{
return $text === '' || preg_match('/^[\p{C}\p{Z}]+$/u', $text) === 1;
}
要看的是正则里的 \p{C} 和 \p{Z},它覆盖了普通空格判断容易遗漏的字符。
超长输入也不能机械套用「四个字符约等于一个 token」。作者发现,密集的非拉丁文字每个字符可能消耗更多 token,因此使用了更保守的长度上限,但没有公布具体数值。
真正拖垮服务的是重试方式。失败批次一直保留「未处理」状态,任务又按最旧优先执行,于是每轮都撞上同一批坏数据。新文章无法生成向量,聚类和摘要也跟着停了。
他们增加输入检查,并改为最新优先;确认无法处理的文章则标记完成、结果留空,避免永久占队。这里需要分清永久性坏输入和临时故障,不能把网络抖动也当成无结果处理掉。
结构化输出能约束字段,为什么仍然会全量失败
实现 HasStructuredOutput,再通过 schema(JsonSchema $schema) 描述字段,可以让 agent 返回可直接读取的数据:headline、summary、key_points,以及使用 enum(Category::values()) 限定的 category。开启比较时,再加入 coverage_differences。
枚举避免模型今天返回「Technology」,明天又造出「Tech & Science」。但 schema 只能约束结构,不能保证事实正确,返回内容仍需校验。
实体提取则采用共享规则和字段:EntityExtractionAgent::Rules 保存指令,EntityExtractionAgent::fields($schema) 提供结构。新故事一次调用完成摘要和实体提取,旧故事通过独立 agent 回填人物、地点,不必重新生成已发布摘要。
最隐蔽的坑来自提供商的 strict 模式:每个对象都必须设置 additionalProperties: false,并把所有属性列入 required。作者使用的 SDK 会为根对象补前者,却不会自动处理嵌套对象。
嵌套对象需要这样显式关闭额外属性:
'beats' => $schema->array()->items($schema->object([
'title' => $schema->string()->required(),
'text' => $schema->string()->required(),
])->withoutAdditionalProperties()),
关键是最后的 withoutAdditionalProperties();内部字段上的 required() 同样不可漏。
这个问题让每日回顾中断了一天,测试却全部通过。Agent::fake() 不访问提供商,自然不会执行它的 schema 规则;任务又捕获异常、跳过分类并发布空回顾,错误没进入 failed_jobs。日志还截断了指出问题字段的响应内容。
他们后来用 Illuminate\JsonSchema\JsonSchemaTypeFactory 和 Laravel\Ai\ObjectSchema 编译真实 schema,再检查对象及对象数组,核对额外属性限制和必填字段。测试无需请求 API,毫秒级运行。
模拟响应验证业务逻辑,不能代替请求契约验证。
重试、告警和账单,要围着实际调用设计
队列还有一个会直接增加账单的配置:retry_after。
如果任务执行时间超过它,Laravel 可能在第一个 worker 尚未结束时,把任务交给第二个 worker。作者当时保留了默认 90 秒,而任务超时是数分钟,最终出现 726 个失败任务和大量重复模型调用。
原文给出的规则是:同一队列连接的 retry_after 必须大于该连接上最长的任务超时。
错误监控也要看整体结果。如果循环逐项调用模型,每项都捕获异常,那么「任务正常结束」并不能证明成功。所有项目在几秒内全部失败,应触发告警;作者认为这通常指向请求被拒绝,而非单次生成质量差。
成本统计通过两个事件完成:AgentPrompted 记录 agent、模型、promptTokens、cacheReadInputTokens 和 completionTokens;EmbeddingsGenerated 记录向量模型及 token 数。Laravel 的事件发现机制根据 handle* 方法的类型声明识别监听器。
统计写库放进 try/catch,避免记账失败影响已经付费获得的摘要。随后用 php artisan ai:usage 按 agent 汇总,或加 --hourly 按小时查看,再结合配置中的模型价格估算费用。
我的判断
我认同作者把优化顺序放在输入和流水线上。减少重复生成,通常比逐个调整提示词更容易解释,也更容易检查效果。
但「最便宜的模型足够好」仍是他们的经验。原文没有质量评分、人工纠错率或不同模型的对照结果,不能据此判断其他任务也适用。新闻中少数媒体独有的事实是否被保留、聚类错误会不会把不同事件混在一起,也没有展开。
「最新优先」能保护新闻时效,却不能替代坏数据隔离。新数据持续进入时,旧数据可能长期等待;需要完整处理历史数据的团队,应另行安排回填和失败记录。
此外,strict schema 的要求属于作者所用提供商及 SDK 行为,原文未给 SDK 版本。它适合作为检查清单,不能直接当作所有提供商的统一规则。文中的 schema 检查也只展示了对象和对象数组的遍历,更复杂的结构还需补充覆盖。
能拿来做什么
- 如果你在做内容摘要或资讯聚合,先检查是否对同一事件重复生成。可以借鉴「文章先归组、故事再摘要」的顺序,同时保留对聚类质量的检查。
- 在 Node 或 Laravel 的批量向量任务里,先处理超长、空值和不可见空白,并区分永久坏输入与临时失败,避免一条数据拖住整批重试。
- 对需要入库或交给前端渲染的 AI 返回值,使用结构化输出和枚举;保留业务 mock 测试,再补实际请求结构的契约检查,必要时安排小规模真实调用冒烟检查。
- 检查模型任务的超时、队列重新投递时间,以及「全部项目失败」告警;同时按 agent 记录 token,才能分辨费用来自正常生成、历史回填还是重复执行。