ثلاث طرق لبث رموز نموذج اللغة إلى Vue: fetch وuseChat وLaravel Echo
Gentil Maliyamungu B. · 2026-11-15
الوكيل نفسه من Laravel AI SDK يُبث إلى Vue بثلاث طرق: fetch مع SSE، وuseChat، وتشغيل في قائمة انتظار عبر Reverb وEcho، مع المقايضات.
عندما يتحدث تطبيق Vue إلى خلفية Laravel تستدعي نموذجاً لغوياً، يمكن أن يعني «stream the answer» ثلاثة أشياء مختلفة تماماً:
- المتصفح يرسل POST ويقرأ جسم الاستجابة أثناء وصوله (Server-Sent Events عبر
fetch).
- المتصفح يستخدم مكتبة دردشة تتحدث بروتوكولاً أغنى عبر النوع نفسه من تيار HTTP (
useChat من @ai-sdk/vue).
- المتصفح يرسل POST، ويتلقى 202، ويستمع على WebSocket بينما يشغّل عامل قائمة انتظار النموذج ويبث الأحداث (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())، مشروح بالتفصيل في المقال الأول من هذه السلسلة. هنا أركّز على جانب العميل لكل منها.
أ: fetch وتنسيق SSE الافتراضي
إعادة ->stream() من مسار ترسل text/event-stream مع كائن JSON واحد لكل سطر data:. لسؤال «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»، أو عميل لا تريد فيه اعتمادية. أنت تملك التحليل والسجل وعرض الأدوات.
ب: useChat
useChat يفعل كل ما سبق نيابة عنك، مقابل بروتوكول رسائل واجهة Vercel:
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 (submitted وstreaming وready وerror)، وstop()، وسجل محادثة يُرسل مع كل طلب. تصل الأخطاء كجزء بروتوكول ({"type":"error","errorText":"..."}) وتستقر في error.
الميزة الحقيقية تظهر مع الأدوات. الموافقة البشرية على الأدوات الخطرة مدمجة في البروتوكول: يرسل الخادم جزءاً tool-approval-request، ويجيب العميل بـ addToolApprovalResponse(). مع تنسيق SSE الخام ستصمّم ذلك كله بنفسك.
المقايضة: البروتوكول تعرّفه Vercel AI SDK، وهي تتحرك بسرعة. بين الإصدارات الرئيسية تغيّرت واجهة العميل (DefaultChatTransport وsendMessage وparts بدلاً من content)، لذا ثبّت إصداراتك واقرأ سجل التغييرات عند الترقية.
مناسب لـ: معظم واجهات الدردشة التي تتحكّم فيها بمسار Laravel وبتطبيق Vue معاً.
ج: تشغيل في قائمة انتظار يُبث عبر Reverb وEcho
الخياران الأولان يُبقيان طلب HTTP مفتوحاً طوال التشغيل، وكذلك عامل PHP الذي يخدمه. إذا أمكن أن يطول التشغيل، أو أردت أن يستمر عندما يغلق المستخدم التبويب، ضع الوكيل في قائمة انتظار. broadcastOnQueue() يرسل مهمة، والمهمة تبث كل حدث في التيار على القناة التي تعطيها إياها.
على جانب Laravel تحتاج إلى البث وعامل قائمة انتظار:
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.
الحمولات هي كائنات JSON نفسها كما في الخيار أ، لذا يعمل event.delta بالطريقة نفسها. إليك ما رأيته عند التشغيل:
- مع استدعاء أداة، كان تسلسل البث هو نفسه على تيار HTTP: اثنان من
stream_start، ثم tool_call، ثم tool_result، ثم أحداث النص، ثم stream_end واحد.
- عندما فشل المزوّد، تلقّى Echo كِلا
.error (مع رسالة المزوّد) و .stream_failed (مع «The stream failed.»). يحافظ ??= على الرسالة المفيدة.
- القناة لكل مستخدم، لا لكل تشغيل. إذا بدأ المستخدم نفسه تشغيلين في آن واحد (تبويبان)، تختلط أحداثهما. تتضمن كل حمولة
invocation_id، لذا يمكنك التمسك بأول واحد تراه بعد الإرسال وتجاهل الباقي. أو اسمح بتشغيل واحد في كل مرة، كما يفترض هذا الـ composable.
لا يوجد «إيقاف» مدمج هنا. الإجهاض يعني إلغاء مهمة في القائمة، وعليك أن تبني ذلك.
مناسب لـ: التشغيلات الطويلة، أو العمل في الخلفية الذي يمكن للمستخدم تركه، أو الوكلاء الذين تشغّلهم أصلاً من مهام. التكلفة عمليتان إضافيتان (Reverb وعامل) ومزيد مما يجب مراقبته.
مقارنة جنباً إلى جنب
| أ: fetch + SSE | ب: useChat | ج: قائمة انتظار + Echo |
| الطلب | POST، والاستجابة مبثوثة | POST، والاستجابة مبثوثة | POST يعيد 202، والأحداث عبر WebSocket |
| شيفرة Laravel | ->stream() | Vercel::chat() + usingProtocol() | ->broadcastOnQueue() |
| بنية إضافية | لا شيء | لا شيء | Reverb (أو Pusher/Ably) + عامل قائمة انتظار |
| استدعاءات الأدوات في الواجهة | حلّل tool_call / tool_result بنفسك | أجزاء tool-* مع حالات | حلّل أحداث البث بنفسك |
| الموافقة البشرية | ابنها بنفسك | مدمجة في البروتوكول | الأحداث موجودة (tool_approval_request)، والربط عليك |
| الإيقاف / الإجهاض | AbortController | stop() | لا توجد طريقة مدمجة |
| يصمد أمام إغلاق التبويب | لا | لا | نعم، تبقى المهمة تعمل |
| إشارة الخطأ | حدث فيه message + recoverable، ثم ينتهي الجسم من دون [DONE] | جزء error، ومرجع error | .error ثم .stream_failed |
| اعتماديات العميل | لا شيء | ai، @ai-sdk/vue | laravel-echo، pusher-js، @laravel/echo-vue |
أيها أختار
- ابدأ بـ
useChat إذا كنت تتحكّم في الطرفين. تحصل على أجزاء الأدوات والموافقات ومعالجة السجل في بضعة أسطر.
- انزل إلى fetch + SSE لودجة صغيرة تعرض نصاً فقط، أو عندما لا تستطيع إضافة حزم AI SDK.
- استخدم قائمة الانتظار وEcho عندما يجب أن يعيش التشغيل أطول من الطلب، أو عندما يكون الوكيل يُشغَّل أصلاً من مهمة أو webhook أو مهمة مجدولة.
مهما اخترت، تحقق من التخزين المؤقت في الإنتاج. الطرق الثلاث تعتمد على ألا يحبس شيء بين PHP والمتصفح البيانات: وكيل أو CDN للخيارين أ وب، ومسار WebSocket للخيار ج.
كيف اختُبرت الأمثلة
شغّل العملاء الثلاثة مقابل تطبيق Laravel 13 محلي مع php artisan serve وreverb:start وqueue:work، وخادم صغير متوافق مع OpenAI مكتوب مسبقاً بدل مزوّد مدفوع. نفّذ Vitest مع happy-dom الـ composables والمكوّنات:
- أ: حُلّل جواب البحث عن الطلب واستدعاء الأداة بشكل صحيح، وأنتج خطأ مزوّد مفروض
status: 'error' مع رسالة المزوّد.
- ب: بثّ
SupportChat.vue الجواب (كان زر Stop ظاهراً في منتصف البث)، وأظهر خطأ رسالة الخطأ.
- ج: تلقّى
useQueuedChat داخل مكوّن مركّب الجواب المنتظِر عبر Reverb، ثم تلقّى .error و.stream_failed لإخفاق مفروض.
يشمل العرض المرفق شيفرة كل مقاربة، مع تغطية Vitest لعملاء Vue الثلاثة.