把大模型 token 流式送进 Vue 的三种做法:fetch、useChat 和 Laravel Echo
Gentil Maliyamungu B. · 2026-11-15
同一个 Laravel AI SDK 智能体,用三种方式流式送进 Vue:带 SSE 的 fetch、useChat,以及通过 Reverb 和 Echo 的排队运行,并比较取舍。
当 Vue 应用与会调用语言模型的 Laravel 后端通信时,“stream the answer” 可以指三种相当不同的事情:
- 浏览器发起 POST,并在响应体到达时读取它(通过
fetch 的 Server-Sent Events)。
- 浏览器使用一套能讲更丰富协议的聊天库,走的仍是同一种 HTTP 流(
useChat,来自 @ai-sdk/vue)。
- 浏览器发起 POST,收到 202,然后在 WebSocket 上监听,与此同时队列 worker 运行模型并广播事件(Laravel Reverb 和 Echo)。
Laravel AI SDK 对这三种都开箱即用。我把同一个小小的客服智能体(可以用 LookupOrder 工具查询订单)放在三条路由后面,为每种写法做了 Vue 客户端,并在本地 Laravel 应用上把三者都跑过。本文用可运行的代码比较它们,以及只有真正跑起来才会看到的细节。
测试环境为 laravel/ai 1.4.0、Laravel 13.42、Reverb 1.13、ai 7.0.173、@ai-sdk/vue 4.0.173、@laravel/echo-vue 2.6.3 和 Vue 3.5。
三条路由
use App\Ai\Agents\SupportAgent;
use Illuminate\Broadcasting\PrivateChannel;
use Illuminate\Http\Request;
// A: the SDK's default SSE event format.
Route::post('/chat/raw', function (Request $request) {
$validated = $request->validate(['message' => ['required', 'string', 'max:2000']]);
return (new SupportAgent)->stream($validated['message']);
})->middleware('throttle:ai');
// B: the Vercel UI message stream that useChat expects.
Route::post('/chat', [ChatController::class, 'store'])->middleware('throttle:ai');
// C: run on a queue, broadcast over Reverb.
Route::post('/chat/queued', function (Request $request) {
$validated = $request->validate(['message' => ['required', 'string', 'max:2000']]);
(new SupportAgent)->broadcastOnQueue(
$validated['message'],
new PrivateChannel('App.Models.User.'.$request->user()->id),
);
return response()->noContent(202);
})->middleware(['auth', 'throttle:ai']);
路由 B 的控制器是 Vercel::chat($request) 加上 ->stream($chat)->usingProtocol($chat->protocol()),在本系列第一篇文章里有详细说明。这里我着重看各自的客户端。
A:fetch 与默认 SSE 格式
从路由返回 ->stream() 会发送 text/event-stream,每一行 data: 对应一个 JSON 对象。对于 “Where is order 1002?”,按顺序出现的事件类型是:
stream_start, tool_call, tool_result, stream_start, text_start,
text_delta (x9), text_end, stream_end, [DONE]
模型的每一步都有一个 stream_start(工具调用是第一步,回答是第二步),但只有一个 stream_end,出现在最后。text_delta 看起来是这样的:
{"id":"01a1debe-...","invocation_id":"01a1debe-...","type":"text_delta","message_id":"01a1debe-...","delta":"Order ","timestamp":1794738385}
浏览器的 EventSource 只能发 GET 请求,而你不会希望把用户消息放进查询字符串。所以用 fetch 来读这条流:
// resources/js/composables/useFetchStream.js
import { ref } from 'vue';
export function useFetchStream(url) {
const text = ref('');
const tools = ref([]);
const status = ref('ready'); // ready | streaming | error
const error = ref(null);
let controller = null;
function handle(event) {
// Provider errors put the provider's error code in `type`, so detect them by shape.
if ('recoverable' in event && 'message' in event) {
throw new Error(event.message);
}
switch (event.type) {
case 'text_delta':
text.value += event.delta;
break;
case 'tool_call':
tools.value.push({ id: event.tool_id, name: event.tool_name, input: event.arguments, result: null });
break;
case 'tool_result': {
const call = tools.value.find((t) => t.id === event.tool_id);
if (call) call.result = event.successful ? event.result : `Failed: ${event.error}`;
break;
}
}
}
async function send(message) {
controller = new AbortController();
text.value = '';
tools.value = [];
error.value = null;
status.value = 'streaming';
let finished = false;
try {
const response = await fetch(url, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Accept: 'text/event-stream',
'X-CSRF-TOKEN': document.querySelector('meta[name="csrf-token"]')?.content ?? '',
},
body: JSON.stringify({ message }),
signal: controller.signal,
});
if (!response.ok) throw new Error(`Request failed with ${response.status}`);
const reader = response.body.pipeThrough(new TextDecoderStream()).getReader();
let buffer = '';
for (;;) {
const { value, done } = await reader.read();
if (done) break;
buffer += value;
// SSE frames are separated by a blank line.
let boundary;
while ((boundary = buffer.indexOf('\n\n')) !== -1) {
const frame = buffer.slice(0, boundary);
buffer = buffer.slice(boundary + 2);
for (const line of frame.split('\n')) {
if (!line.startsWith('data: ')) continue;
const data = line.slice(6);
if (data === '[DONE]') { finished = true; continue; }
handle(JSON.parse(data));
}
}
}
if (!finished) throw new Error('The stream ended before the server finished.');
status.value = 'ready';
} catch (e) {
if (e.name === 'AbortError') {
status.value = 'ready';
return;
}
error.value = e;
status.value = 'error';
}
}
const stop = () => controller?.abort();
return { text, tools, status, error, send, stop };
}
其中有两点来自实际运行,而不是来自阅读文档:
- 错误并不是
type: "error"。 当我让提供方在流的中途失败时,事件是 {"type":"server_error","message":"The mock provider failed on purpose.","recoverable":false,...}。这个 type 是提供方自己的错误码。文档的广播部分对广播错误说了同样的话(“the provider's own error code is available in the payload's type key”)。在原始流上,我通过是否存在 message 和 recoverable 来检测错误。
- 失败的流没有
[DONE]。 连接只是被关闭。要把 “the body ended without [DONE]” 当作失败,否则一篇写到一半的答案看起来会像已经完成。
帧还可能被拆到不同的网络分片里,所以代码会一直缓冲到看见空行,而不是直接解析每一个分片。
适合: 小部件、一次性的 “summarize this” 按钮,或不想引入依赖的客户端。解析、历史和工具渲染都由你自己负责。
B:useChat
useChat 会替你做上面这些事,对接的是 Vercel UI 消息协议:
import { useChat } from '@ai-sdk/vue';
import { DefaultChatTransport } from 'ai';
const { messages, status, error, sendMessage, stop } = useChat({
transport: new DefaultChatTransport({
api: '/chat',
headers: { 'X-CSRF-TOKEN': csrfToken },
}),
});
你会得到 messages,其中带有类型化的 parts(text、tool-LookupOrder,其状态包括 input-available 和 output-available、以及 reasoning 等等),一个 status ref(submitted、streaming、ready、error),stop(),以及每次请求都会发送的对话历史。错误以协议分段的形式到达({"type":"error","errorText":"..."}),并进入 error。
真正的优势出现在工具上。对高风险工具的人工批准已经做进协议:服务器发送 tool-approval-request 分段,客户端用 addToolApprovalResponse() 回答。如果用原始 SSE 格式,这些都得自己设计。
代价是:协议由变化很快的 Vercel AI SDK 定义。在主要版本之间,客户端 API 已经改过(DefaultChatTransport、sendMessage、用 parts 代替 content),所以请锁定版本,并在升级时阅读 changelog。
适合: 大多数由你同时控制 Laravel 路由和 Vue 应用的聊天界面。
C:用 Reverb 和 Echo 广播排队运行
前两种做法会在整段运行期间一直占用一个打开的 HTTP 请求,服务它的 PHP worker 也是如此。如果一次运行可能很久,或你希望用户关掉标签页后它仍继续,就把智能体放到队列上。broadcastOnQueue() 会派发一个任务,该任务把每个流事件广播到你给它的频道上。
在 Laravel 一侧,你需要广播和一个队列 worker:
php artisan install:broadcasting --reverb
php artisan reverb:start
php artisan queue:work
默认的 routes/channels.php 已经为对应用户授权了 App.Models.User.{id},所以我在那条私有频道上广播。
事件按类型广播,而且是自定义名称,因此 Echo 监听器需要前导的点。使用 @laravel/echo-vue 时,useEcho 会在挂载时订阅,在卸载时离开:
// resources/js/composables/useQueuedChat.js
import { ref } from 'vue';
import { useEcho } from '@laravel/echo-vue';
export function useQueuedChat(userId) {
const text = ref('');
const status = ref('ready'); // ready | waiting | streaming | error
const error = ref(null);
const channel = `App.Models.User.${userId}`;
useEcho(channel, '.text_delta', (event) => {
status.value = 'streaming';
text.value += event.delta;
});
useEcho(channel, '.stream_end', () => {
status.value = 'ready';
});
useEcho(channel, '.error', (event) => {
error.value = new Error(event.message);
status.value = 'error';
});
useEcho(channel, '.stream_failed', (event) => {
// A provider error is followed by stream_failed; keep the more specific message.
error.value ??= new Error(event.message ?? 'The queued run failed.');
status.value = 'error';
});
async function send(message) {
text.value = '';
error.value = null;
status.value = 'waiting';
const response = await fetch('/chat/queued', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Accept: 'application/json',
'X-CSRF-TOKEN': document.querySelector('meta[name="csrf-token"]')?.content ?? '',
},
body: JSON.stringify({ message }),
});
if (response.status !== 202) {
error.value = new Error(`Request failed with ${response.status}`);
status.value = 'error';
}
}
return { text, status, error, send };
}
再在应用的入口文件里配置一次 Echo:
import { configureEcho } from '@laravel/echo-vue';
configureEcho({ broadcaster: 'reverb' });
只提供广播器名称时,@laravel/echo-vue 2.6 会根据 VITE_REVERB_* 变量补全密钥、主机、端口和协议,这些变量由 install:broadcasting 写入你的 .env。
载荷和选项 A 里是同样的 JSON 对象,所以 event.delta 的用法相同。下面是我运行时看到的情况:
- 有工具调用时,广播顺序和 HTTP 流上一样:两个
stream_start,一个 tool_call,一个 tool_result,然后是文本事件,再加一个 stream_end。
- 提供方失败时,Echo 同时收到了
.error(带有提供方消息)和 .stream_failed(内容是 “The stream failed.”)。??= 会保留那条有用的消息。
- 频道是按用户而不是按一次运行来的。如果同一用户同时开始两次运行(两个标签页),事件会混在一起。每个载荷都包含
invocation_id,所以你可以锁定发送后看到的第一个,并忽略其余的。或者一次只允许一次运行,就像这个组合式函数所假定的那样。
这里没有内置的 “stop”。中止意味着取消一个排队任务,这需要你自己实现。
适合: 耗时长的运行、用户可以离开的后台工作,或你已经从任务里触发的智能体。代价是再多两个进程(Reverb 和一个 worker),以及更多需要监控的东西。
对照表
| A:fetch + SSE | B:useChat | C:队列 + Echo |
| 请求 | POST,响应为流式 | POST,响应为流式 | POST 返回 202,事件走 WebSocket |
| Laravel 代码 | ->stream() | Vercel::chat() + usingProtocol() | ->broadcastOnQueue() |
| 额外基础设施 | 无 | 无 | Reverb(或 Pusher/Ably)+ 队列 worker |
| 界面中的工具调用 | 自己解析 tool_call / tool_result | 带状态的 tool-* 分段 | 自己解析广播事件 |
| 人工批准 | 自己实现 | 协议内置 | 事件存在(tool_approval_request),接线要自己做 |
| 停止 / 中止 | AbortController | stop() | 没有内置方式 |
| 关闭标签页后是否继续 | 否 | 否 | 是,任务会继续跑 |
| 错误信号 | 带 message + recoverable 的事件,然后响应体在没有 [DONE] 的情况下结束 | error 分段、error ref | .error,然后 .stream_failed |
| 客户端依赖 | 无 | ai、@ai-sdk/vue | laravel-echo、pusher-js、@laravel/echo-vue |
我会怎么选
- 如果两端都由你控制,从
useChat 开始。只需几行代码,就能得到工具分段、批准和历史处理。
- 对于只显示文本的小部件,或无法加入 AI SDK 包时,退回到 fetch + SSE。
- 当运行必须比这次请求活得更久,或智能体已经由任务、webhook 或定时任务触发时,使用队列和 Echo。
无论选哪一种,都要在生产环境检查缓冲。这三种都依赖 PHP 和浏览器之间不要把数据攒住:A 和 B 看代理或 CDN,C 看 WebSocket 路径。
这些例子是如何测试的
三个客户端都对着本地的 Laravel 13 应用运行,使用 php artisan serve、reverb:start、queue:work,以及一个小型脚本化的 OpenAI 兼容服务器,而不是付费提供方。Vitest 配合 happy-dom 运行了组合式函数和组件:
- A: 查单答案和工具调用解析正确,强制的提供方错误产生了带有提供方消息的
status: 'error'。
- B:
SupportChat.vue 流式输出了答案(Stop 按钮在流进行中可见),错误会显示错误消息。
- C: 挂载组件里的
useQueuedChat 通过 Reverb 收到了排队后的答案,然后在强制失败时收到 .error 和 .stream_failed。
配套演示包含每种做法的代码,并为三个 Vue 客户端提供了 Vitest 覆盖。