用 Laravel 和 Vue 实现流式客服聊天
教程用 Laravel 构建能查数据库订单的客服 Agent,再通过兼容 Vercel AI SDK 的流式协议接入 Vue 3 的 useChat。前端会逐步显示回复,并实时呈现工具调用。
AI 深度解读
给 Laravel 客服聊天加流式响应,最容易卡住的地方是前后端对消息格式的理解。Vue 的 useChat 发来整段对话,Laravel 要从中取出本轮问题和历史,再按客户端认识的协议发回查单进度和逐段生成的文字。
作者用一个虚构店铺跑通了这条链路。用户问订单 1001 到哪了,页面先显示查单状态,再接着显示回答。前端可以直接借用按消息片段渲染的方式,全栈开发者则可以用本地模拟服务验证整条链路,连模型 API Key 都可以省下。
一次请求怎么同时带上历史和新问题
作者实际跑通的环境是 laravel/ai 1.4.0、Laravel 13.42、PHP 8.4,前端用 ai 7.0.173、@ai-sdk/vue 4.0.173 和 Vue 3.5。复现时先核对这组版本,尤其是 Vue 端的 API。@ai-sdk/vue 第 4 版推荐用组合式函数 useChat,旧的 Chat 类仍然导出,但已标记为弃用。
后端依次运行 composer require laravel/ai、php artisan vendor:publish --provider="Laravel\Ai\AiServiceProvider" 和 php artisan migrate。发布命令会生成 config/ai.php 和 SDK 的会话迁移文件,示例只用浏览器传回的历史。用 php artisan make:agent SupportAgent 生成的类默认实现了 Conversational,这里要移除该接口和 messages()。在保留它们的情况下调用 withMessages(),SDK 会抛出 LogicException。
下面的控制器把 useChat 发来的 messages 拆成历史和本轮输入,再把 Agent 的输出接到前端能解析的响应协议上。
<?php
namespace App\Http\Controllers;
use App\Ai\Agents\SupportAgent;
use Illuminate\Http\Request;
use Laravel\Ai\Vercel\Vercel;
class ChatController extends Controller
{
public function store(Request $request)
{
$request->validate([
'messages' => ['required', 'array', 'max:50'],
]);
$chat = Vercel::chat($request);
return (new SupportAgent)
->withMessages($chat->history())
->stream($chat)
->usingProtocol($chat->protocol());
}
}
留意 ->stream($chat) 这一行。传入的 $chat 对象会把最新一条用户消息交给 Agent 当作本轮提示,$chat->history() 则把此前的消息转换成 SDK 对象,前一轮的工具调用和结果也会带上。最后一行指定 Vercel 数据协议,响应头里会带有 x-vercel-ai-ui-message-stream: v1。
这套写法用起来很直接。作者接着问订单 9999 时,请求里共有四条消息,前三条被转换成历史。这一轮返回的 No order found with number 9999. 来自工具的查无订单分支。路由最多接收 50 条消息,同时挂了 throttle:ai,按登录用户 ID 或 IP 每分钟放行 30 次。作者测试时还发现,同一用户或 IP 在多条路由上使用普通的 throttle:20,1,可能共用计数。
为什么 Vue 要逐个渲染 message.parts
SupportAgent 的指令要求提到订单号就调用 LookupOrder,查不到就直说。作者用 php artisan make:tool LookupOrder 生成工具,在 JSON Schema 里描述 order_number 是不带 # 的四位数字字符串,在 handle() 里再用 $request->validate() 执行 required|string|digits:4。格式不符时,SDK 会把校验消息作为工具结果交给模型,给它一次修正参数的机会。Agent 上的 #[MaxSteps(5)] 给单轮模型往返设了上限。一次调用工具再生成回答,至少需要两步。
数据库预置了已发货的 1001、延迟的 1002 和已退款的 1003,工具正常命中时返回 number、status 和 eta。未定义 name() 时,SDK 用类的短名 LookupOrder 作为工具名,所以 Vue 模板里识别的是 tool-LookupOrder。同一个工具调用在网络上先发 tool-input-available,再发 tool-output-available,随后正文通过多条 text-delta 到达。作者抓到的 1001 响应里,状态是 shipped,预计送达日期是 2026-11-17,流以 [DONE] 结束。
前端依次运行 npm install vue ai @ai-sdk/vue 和 npm install -D @vitejs/plugin-vue。下面的代码把 useChat 接到 Laravel 的 /chat,并用请求状态控制提交。
<script setup>
import { ref, computed } from 'vue';
import { useChat } from '@ai-sdk/vue';
import { DefaultChatTransport } from 'ai';
const csrfToken = document.querySelector('meta[name="csrf-token"]')?.content ?? '';
const { messages, status, error, sendMessage, stop } = useChat({
transport: new DefaultChatTransport({
api: '/chat',
headers: { 'X-CSRF-TOKEN': csrfToken },
}),
});
const input = ref('');
const busy = computed(() => status.value === 'submitted' || status.value === 'streaming');
function submit() {
const text = input.value.trim();
if (!text || busy.value) return;
sendMessage({ text });
input.value = '';
}
</script>
留意 headers 那一行。POST /chat 注册在 Laravel 的 web.php,会经过 CSRF 中间件。Blade 布局要先输出 csrf-token 元标签,DefaultChatTransport 才能读到值并随请求发送。
模板遍历 message.parts,遇到 text 就显示正文,遇到 tool-LookupOrder 就按状态显示查单中、已查单或错误。作者在运行中的应用里记录过一轮完成后的顺序,依次是 step-start、状态为 output-available 的工具片段、第二个 step-start 和文本片段。step-start 可以跳过。submitted 时显示等待提示,streaming 时持续更新内容,结束后进入 ready,失败时进入 error。前两个阶段都可以把发送按钮换成调用 stop 的按钮。
不接真实模型也能验证什么
作者把 AI_DEFAULT_PROVIDER 设为 openai-compatible,让 mock-llm/server.mjs 模拟 OpenAI Chat Completions。配置里,OPENAI_COMPATIBLE_URL 是 http://127.0.0.1:4010/v1,OPENAI_COMPATIBLE_MODEL 是 mock-model,驱动的 key 字段读取 OPENAI_COMPATIBLE_API_KEY。接入对应的真实服务时,可以在服务端配置 OPENAI_API_KEY 或 OPENROUTER_API_KEY。浏览器只请求 Laravel 路由。
模拟服务看到四位数字就按预设规则触发 LookupOrder,因此查单何时发生是可控的。作者安排了三层检查。Pest 用 SupportAgent::fake() 注入 ToolCall,让真实工具查询测试数据库,再断言响应体有工具名、shipped 和 text-delta。这个 fake 支持 ToolCall 是作者从 1.4.0 源码确认的实现细节,文档没有承诺。Node 脚本在组件外运行真实的 useChat,请求由 php artisan serve 启动的后端。Vitest 则用 happy-dom 挂载 SupportChat.vue,验证流途中有 Stop 按钮,结束时显示回答和 Checked order #1001。
我的判断
这篇最值得借用的是验证方式。只断言页面上最终出现了回答,即使代理把整段响应攒到最后一次发出,测试也能通过。分别看响应事件、真实客户端和组件的中间状态,更容易定位问题。作者确实跑了这些检查,但没给首段到达时间、生产网络下的表现,或与手写 EventSource 的对照数据。开头提到等五到十秒让体验变差,是经验判断。模拟服务也只验证接线,真实模型是否会稳定提取订单号、传错参数后能否纠正,原文没有给出测量结果。
浏览器回传历史适合演示这种只读流程,但历史可以被用户修改,查单本身也可能涉及访问权限。示例的公开路由只有限流,订单工具也只按订单号查询。在真实客服里,即使加了 session 或 Sanctum 登录,工具仍要确认当前账号有权查看该订单。若需求扩展到退款,服务端保存会话和审批状态才有可靠的授权依据。原文这轮只验证查单,人工审批、会话持久化和 RAG 都留在范围之外。
能拿来做什么
- 在 Vue 聊天组件里保留
message.parts,用查单中、查单完成和正文三个阶段做组件测试。至少有一个断言发生在流结束前,才能发现页面是否真的展示了中间状态。 - 本地联调先用
mock-model跑通命中1001和查不到9999两条路径,再切换真实 provider,观察模型是否按要求调用工具并正确处理查无结果。 - 如果本地逐段更新,线上却一下子吐出全文,用
curl对比直连应用和经过代理时的分段到达情况。即使 Laravel 已返回X-Accel-Buffering: no,也要检查 CDN 和负载均衡是否缓冲了响应。 - 上线前用一个已登录但无权查看目标订单的账号测一遍
LookupOrder。在工具里校验订单归属,并检查工具失败时展示的part.errorText是否带有服务端细节。