ملء نموذج Vue مسبقاً بمخرجات منظَّمة من وكيل Laravel AI SDK
Gentil Maliyamungu B. · 2026-11-15
استخدم مخطط مخرجات منظَّمة من Laravel AI SDK لاقتراح حقول النموذج، وتحقق منها على الخادم، وادمجها في نموذج Vue دون الكتابة فوق تعديلات المستخدم.
ليست كل ميزة ذكاء اصطناعي بحاجة إلى أن تكون نافذة دردشة. في كثير من الأحيان، أكثر ما يفيد أن يفعله النموذج هو ملء نموذج يراجعه إنسان بعدها: تذكرة دعم من رسالة زبون، أو بطاقة منتج من وصف مورّد، أو قيد مصروف من إيصال.
في هذا الدرس يلصق وكيل دعم رسالة زبون في نموذج Vue، ينقر Draft with AI، فيُملأ الموضوع والفئة والأولوية ورقم الطلب والملخص ورد مقترح. يبقى الإنسان متحكّماً:
- تُتحقق مخرجات النموذج على الخادم بالقواعد نفسها التي تُطبَّق على إرسال بشري، وتُسقط الحقول غير الصالحة ولا تُعرض؛
- الحقول التي كتبها الشخص مسبقاً لا تُستبدل أبداً؛
- الحقول التي ملأتها الذكاء الاصطناعي تُوسَم حتى يعدّلها أحد؛
- الحفظ يشغّل التحقق نفسه مرة أخرى، فلا يستطيع طلب مفبرك تجاوزه.
اختُبر مع laravel/ai 1.4.0 وLaravel 13.42 وPHP 8.4 وVue 3.5.
الوكيل ومخططه
يسمح Laravel AI SDK للوكيل بإعادة مخرجات منظَّمة عبر تنفيذ HasStructuredOutput ووصف الشكل بباني مخطط JSON في Laravel:
php artisan make:agent TicketDraftAgent --structured
<?php
namespace App\Ai\Agents;
use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasStructuredOutput;
use Laravel\Ai\Promptable;
use Stringable;
class TicketDraftAgent implements Agent, HasStructuredOutput
{
use Promptable;
public const CATEGORIES = ['shipping', 'damaged_item', 'refund', 'other'];
public const PRIORITIES = ['low', 'normal', 'high'];
public function instructions(): Stringable|string
{
return <<<'TEXT'
You turn a customer's message into a draft support ticket for a small online shop.
Write the subject and summary in plain English, without inventing facts.
Only fill order_number if the customer wrote one; otherwise use null.
The suggested reply is a first draft for a human agent, not a promise.
TEXT;
}
public function schema(JsonSchema $schema): array
{
return [
'subject' => $schema->string()->max(80)->required(),
'category' => $schema->string()->enum(self::CATEGORIES)->required(),
'priority' => $schema->string()->enum(self::PRIORITIES)->required(),
'order_number' => $schema->string()->nullable()->required(),
'summary' => $schema->string()->required(),
'suggested_reply' => $schema->string()->required(),
];
}
}
الفئات والأولويات ثوابت صنف، حتى يشترك المخطط وقواعد التحقق في قائمة واحدة.
order_number هو nullable() وrequired() معاً. يعني ذلك «ضمّن المفتاح دائماً، واستخدم null عندما لا يوجد»، وهو أوضح للنموذج من حذف المفتاح. ويتوافق أيضاً مع ما تتوقعه أوضاع المخرجات المنظَّمة الصارمة لدى مزوّدين مثل OpenAI: كل خاصية مدرجة كمطلوبة، والقيم الاختيارية تُعبَّر عنها بأنها قابلة لأن تكون فارغة.
ما الذي يستلمه المزوّد
شغّلت هذا مقابل نقطة نهاية متوافقة مع OpenAI وسجّلت الطلب. حوّل SDK المخطط إلى response_format كهذا (مختصر):
{
"type": "json_schema",
"json_schema": {
"name": "schema_definition",
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"subject": { "type": "string", "maxLength": 80 },
"category": { "type": "string", "enum": ["shipping", "damaged_item", "refund", "other"] },
"priority": { "type": "string", "enum": ["low", "normal", "high"] },
"order_number": { "type": ["string", "null"] },
"summary": { "type": "string" },
"suggested_reply": { "type": "string" }
},
"required": ["subject", "category", "priority", "order_number", "summary", "suggested_reply"]
},
"strict": false
}
}
لاحظ "strict": false. مع ذلك المشغّل والإعدادات الافتراضية، يُطلب من المزوّد هذا الشكل دون إلزامه به. حتى في الوضع الصارم، maxLength والقواعد التجارية («this order exists») أمور ينبغي أن تتحقق منها بنفسك. لذا يعامل الخادم جواب النموذج كإدخال مستخدم.
نقطة النهاية: المطالبة ثم التحقق
في البداية خططت لبث المخرجات المنظَّمة حتى تُملأ الحقول أثناء توليدها. في 1.4.0 هذا غير ممكن بعد. استدعاء stream() على وكيل ذي مخرجات منظَّمة يرمي:
InvalidArgumentException: Streaming structured output is not currently supported.
لذا تستخدم نقطة النهاية prompt() وتعيد JSON. لنموذج قصير يكون الانتظار عادة بضع ثوانٍ، وحالة «Drafting…» تكفي.
<?php
namespace App\Http\Controllers;
use App\Ai\Agents\TicketDraftAgent;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Validator;
use Illuminate\Validation\Rule;
class TicketController extends Controller
{
/**
* The rules a ticket must pass, whether a human or the model filled it in.
*/
protected function rules(): array
{
return [
'subject' => ['required', 'string', 'max:80'],
'category' => ['required', Rule::in(TicketDraftAgent::CATEGORIES)],
'priority' => ['required', Rule::in(TicketDraftAgent::PRIORITIES)],
'order_number' => ['nullable', 'digits:4', 'exists:orders,number'],
'summary' => ['required', 'string', 'max:2000'],
'suggested_reply' => ['nullable', 'string', 'max:2000'],
];
}
public function draft(Request $request)
{
$validated = $request->validate([
'message' => ['required', 'string', 'max:5000'],
]);
$draft = (new TicketDraftAgent)->prompt($validated['message'])->toArray();
$errors = Validator::make($draft, $this->rules())->errors()->toArray();
return response()->json([
// Cast so an empty draft is still a JSON object, not [].
'draft' => (object) array_diff_key($draft, $errors),
'rejected' => array_keys($errors),
]);
}
public function store(Request $request)
{
$ticket = $request->validate($this->rules());
// A real app would create a Ticket model here.
return response()->json(['ticket' => $ticket], 201);
}
}
Route::view('/tickets/new', 'tickets');
Route::post('/tickets/draft', [TicketController::class, 'draft'])->middleware('throttle:ai');
Route::post('/tickets', [TicketController::class, 'store']);
بعض النقاط:
->toArray() على الاستجابة المنظَّمة يعطي الحقول بعد فكّها. تدعم الاستجابة أيضاً الوصول كمصفوفة ($response['subject']).
- الحقول غير الصالحة تُسقط، ولا «تُصلَح». إذا اخترع النموذج فئة أو رقم طلب غير موجود، لا يرى العميل تلك القيمة أبداً، بل اسمها فقط في
rejected. يملؤها الشخص.
- قاعدة
exists:orders,number هي الأهم. يستطيع المخطط أن يضمن أن order_number سلسلة. قاعدتك وحدها تعرف إن كان ذلك الطلب موجوداً.
throttle:ai محدّد معدّل بالاسم لنقاط النهاية التي تكلف مالاً (Limit::perMinute(30) لكل مستخدم أو عنوان IP في AppServiceProvider).
عندما يتجاهل النموذج المخطط
أردت أن أعرف ماذا يحدث عندما يجيب نموذج بنثر بدل JSON، فجعلت خادم الاختبار يرد «Sure! Here is a ticket for you.» في 1.4.0، تفك البوابات المخرجات المنظَّمة بتسامح: تجرّب JSON مجرداً، ثم كتلة شيفرة محاطة، وإن لم ينجح شيء تعيد مصفوفة فارغة دون رمي استثناء. أعادت نقطة نهايتي عندئذ:
{"draft":{},"rejected":["subject","category","priority","summary"]}
لم ينكسر شيء. يُظهر النموذج للإنسان أن المسودة تُجاهلت. هذه المصفوفة الفارغة هي أيضاً سبب تحويل draft إلى كائن: من دون التحويل، تصبح مصفوفة PHP الفارغة [] في JSON.
جانب Vue: طلب مسودة لا يفوز فيه إلا آخر استدعاء
// resources/js/composables/useTicketDraft.js
import { ref } from 'vue';
const csrf = () => document.querySelector('meta[name="csrf-token"]')?.content ?? '';
export function useTicketDraft() {
const loading = ref(false);
const error = ref(null);
let controller = null;
async function requestDraft(message) {
controller?.abort(); // a new request replaces an old one
controller = new AbortController();
loading.value = true;
error.value = null;
try {
const response = await fetch('/tickets/draft', {
method: 'POST',
headers: { 'Content-Type': 'application/json', Accept: 'application/json', 'X-CSRF-TOKEN': csrf() },
body: JSON.stringify({ message }),
signal: controller.signal,
});
if (!response.ok) throw new Error(`Draft failed with ${response.status}`);
return await response.json(); // { draft, rejected }
} catch (e) {
if (e.name !== 'AbortError') error.value = e;
return null;
} finally {
loading.value = false;
}
}
return { loading, error, requestDraft, cancel: () => controller?.abort() };
}
دمج المسودة دون الكتابة فوق ما كتبه الإنسان
يحفظ النموذج مجموعتين: touched، الحقول التي كتبها الشخص، وaiFilled، الحقول التي ملأها النموذج ولم يعدّلها أحد بعد.
<script setup>
import { reactive, ref } from 'vue';
import { useTicketDraft } from '../composables/useTicketDraft';
const fields = ['subject', 'category', 'priority', 'order_number', 'summary', 'suggested_reply'];
const customerMessage = ref('');
const form = reactive({ subject: '', category: '', priority: 'normal', order_number: '', summary: '', suggested_reply: '' });
const touched = reactive(new Set());
const aiFilled = reactive(new Set());
const rejected = ref([]);
const errors = ref({});
const saved = ref(false);
const { loading, error, requestDraft } = useTicketDraft();
function edit(field) {
touched.add(field);
aiFilled.delete(field);
}
async function draft() {
const result = await requestDraft(customerMessage.value);
if (!result) return;
for (const field of fields) {
// Never overwrite what the human already typed.
if (touched.has(field) || !(field in result.draft)) continue;
form[field] = result.draft[field] ?? '';
aiFilled.add(field);
}
rejected.value = result.rejected;
}
async function save() {
errors.value = {};
const response = await fetch('/tickets', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Accept: 'application/json',
'X-CSRF-TOKEN': document.querySelector('meta[name="csrf-token"]')?.content ?? '',
},
body: JSON.stringify({ ...form, order_number: form.order_number || null }),
});
if (response.status === 422) {
errors.value = (await response.json()).errors;
return;
}
saved.value = response.ok;
}
</script>
يجعل Vue 3 مجموعة Set التفاعلية تعمل كما تتوقع: يتحدّث aiFilled.has('subject') في القالب عندما تتغيّر المجموعة.
معالج edit() يعمل على @input و@change. هذه الأحداث لا تنطلق إلا عندما يتفاعل شخص مع الحقل. عندما تعيّن الشيفرة form.subject من المسودة، لا ينطلق حدث input، لذا لا تُحسب القيم التي ملأتها الذكاء الاصطناعي تعديلات.
القالب، مختصراً إلى حقلين:
<template>
<form class="space-y-3" @submit.prevent="save">
<label>
Customer message
<textarea v-model="customerMessage" name="message" rows="3" />
</label>
<button type="button" name="draft" :disabled="loading || !customerMessage.trim()" @click="draft">
{{ loading ? 'Drafting…' : 'Draft with AI' }}
</button>
<p v-if="error">Could not draft this ticket. Fill it in by hand.</p>
<p v-if="rejected.length">Ignored suggestions for: {{ rejected.join(', ') }}</p>
<fieldset :disabled="loading">
<label>
Subject <span v-if="aiFilled.has('subject')">AI draft</span>
<input v-model="form.subject" name="subject" @input="edit('subject')" />
</label>
<label>
Category <span v-if="aiFilled.has('category')">AI draft</span>
<select v-model="form.category" name="category" @change="edit('category')">
<option value="" disabled>Choose…</option>
<option value="shipping">Shipping</option>
<option value="damaged_item">Damaged item</option>
<option value="refund">Refund</option>
<option value="other">Other</option>
</select>
</label>
<!-- priority, order_number, summary, suggested_reply follow the same pattern -->
</fieldset>
<ul v-if="Object.keys(errors).length">
<li v-for="(messages, field) in errors" :key="field">{{ field }}: {{ messages[0] }}</li>
</ul>
<button type="submit" :disabled="loading">Create ticket</button>
<p v-if="saved">Ticket created.</p>
</form>
</template>
تعطيل fieldset أثناء تشغيل طلب المسودة يتجنّب حالة مربكة: يكتب الشخص في حقل، ثم تصل المسودة وتملأ الحقول من حوله. إذا أردت أن يواصل الناس الكتابة أثناء المسودة، أزل disabled. فحص touched ما زال يحمي تعديلاتهم.
قرارات تصميم تستحق النسخ
وسم محتوى الذكاء الاصطناعي حتى يلمسه إنسان. تختفي شارة «AI draft» عندما يعدّل الشخص الحقل. تخبر المراجع أي القيم لم يتحقق منها أحد بعد.
أبقِ الرد المقترح مسودة. يسميه المخطط اقتراحاً، وتقول التعليمات «not a promise». لا شيء في هذا المسار يرسله إلى الزبون. ما زال على شخص أن ينسخه أو ينقر Send في نظام التذاكر الحقيقي لديك.
تحقق مرتين. draft() يصفي مخرجات النموذج حتى لا يعرض النموذج قيماً غير صالحة. store() يتحقق من كل شيء مجدداً لأن المتصفح يمكنه إرسال أي شيء. كلاهما يستخدم دالة rules() نفسها.
لا تخترع البيانات الناقصة. تطلب التعليمات من النموذج استخدام null عندما لا يوجد رقم طلب، وتلتقط قاعدة exists الحالات التي يخترع فيها واحداً على أي حال.
اختباره
يستطيع SDK تزييف الوكلاء المنظَّمين: مرّر مصفوفة قيم حقول لكل مطالبة متوقعة. تغطي اختبارات Pest هذه نقطة النهاية:
use App\Ai\Agents\TicketDraftAgent;
it('returns the structured draft from the agent', function () {
TicketDraftAgent::fake([[
'subject' => 'Cracked screen',
'category' => 'damaged_item',
'priority' => 'high',
'order_number' => '1002',
'summary' => 'Phone arrived cracked.',
'suggested_reply' => 'Sorry! Can you send a photo?',
]])->preventStrayPrompts();
$this->postJson('/tickets/draft', ['message' => 'My phone from order 1002 is cracked'])
->assertOk()
->assertJsonPath('draft.category', 'damaged_item')
->assertJsonPath('draft.order_number', '1002')
->assertJsonPath('rejected', []);
TicketDraftAgent::assertPrompted(fn ($prompt) => $prompt->contains('cracked'));
});
it('drops fields that fail validation', function () {
TicketDraftAgent::fake([[
'subject' => 'Broken item',
'category' => 'complaint', // not an allowed category
'priority' => 'high',
'order_number' => '7777', // no such order
'summary' => 'Arrived broken.',
'suggested_reply' => 'Sorry!',
]])->preventStrayPrompts();
$this->postJson('/tickets/draft', ['message' => 'Order 7777 arrived broken'])
->assertOk()
->assertJsonMissingPath('draft.category')
->assertJsonMissingPath('draft.order_number')
->assertJsonPath('rejected', ['category', 'order_number']);
});
يجعل preventStrayPrompts() الاختبار يفشل إذا طلبت الشيفرة من الوكيل أكثر مما زيّفت. ومع Http::preventStrayRequests() في tests/Pest.php، لا يمكن لأي اختبار بلوغ مزوّد حقيقي مصادفة.
اختبارات نقطة النهاية الأربعة (بما فيها حالة المسودة الفارغة) تنجح. شغّلت أيضاً مكوّن Vue مع Vitest وhappy-dom مقابل تطبيق Laravel قيد التشغيل وخادم اختبار متوافق مع OpenAI مكتوب مسبقاً. يكتب الاختبار موضوعاً، يطلب مسودة، ويتحقق من أن الموضوع يبقى كما كُتب، وأن بقية الحقول تُملأ، وأن الحفظ يعرض «Ticket created.» ويتحقق اختبار ثانٍ من إدراج الطلب 7777 كمُتجاهَل وبقاء الحقل فارغاً.
إلى أين بعد ذلك
- إذا كان نموذجك طويلاً وأردت أن تظهر الحقول تدريجياً، راقب سجل تغييرات SDK بحثاً عن بث المخرجات المنظَّمة. حتى ذلك الحين،
prompt() مع حالة تحميل هو الخيار الموثوق.
- للمسودات التي تستغرق وقتاً أطول، استخدم دالة
queue() في SDK وادفع النتيجة إلى المتصفح بالبث.
- سجّل قائمة
rejected. إذا رُفض حقل كثيراً، حسّن التعليمات أو وصف المخطط لذلك الحقل.
النموذج يسوّد والإنسان يقرر. قواعد التحقق هي ما يجعل هذا الفصل يصمد.