‏USAIGE: توکن و هزینهٔ درخواست‌های AI لاراول رو رصد کن

USAIGE یه پکیج لاراوله که مشاهده‌پذیری (observability) رو به Laravel AI SDK می‌چسبونه. به گفتهٔ نویسندهٔ مقاله، هر درخواست AI رو به‌عنوان یه «run» ثبت می‌کنه: تعداد توکن، هزینه، پرووایدر و مدل، زمان‌بندی و وضعیت خطا — و بعد همهٔ اینا رو از طریق یه داشبورد وب داخلی نشون می‌ده.

کل ادغام دور دو تا هلپر سراسری می‌چرخه: ai_run() یه کانتکست ردیابی باز می‌کنه که به شناسهٔ یه فیچر گره خورده، و ai_usage() ثبت می‌کنه که پاسخ SDK چقدر مصرف کرده. یعنی عملاً سه خط:

$run = ai_run('summarize-document');
$response = Ai::text('Summarize: ' . $document->content);
$usage = ai_usage($run, $response);

پکیج شکل پاسخ رو خودکار تشخیص می‌ده: پاسخ‌های Laravel AI SDK، OpenAI PHP SDK و آرایه‌های ساده رو می‌شناسه و بدون تنظیمات اضافه تعداد توکن‌ها رو درمیاره. اگه هیچ‌کدوم از این شکل‌ها جور نبود، می‌تونی خودت شمارش‌ها رو با آرگومان‌های promptTokens و completionTokens پاس بدی.

پرووایدر و مدل هر run از config/ai.php خونده می‌شه، ولی هم می‌شه پرِ کال override کرد و هم مستقیم یه enum از نوع Lab بهش داد. هزینه‌ها با دقت زیرِ سنت ذخیره می‌شن و جدول ai_usages هم توکن‌های prompt و completion رو کنار جمع هزینهٔ دلاری هر run نگه می‌داره — پس با مدل AiRun می‌تونی خرجت رو بر اساس فیچر، کاربر، مدل یا بازهٔ تاریخ کوئری بگیری.

هر run به‌صورت پیش‌فرض به auth()->id() گره می‌خوره، ولی اگه این resolver پیش‌فرض به دردت نخورد، می‌تونی با Usaige::resolveUsersUsing() سراسری عوضش کنی یا آی‌دی کاربر رو پرِ کال بدی. علاوه‌بر این، هر run متادیتای JSON دلخواه هم قبول می‌کنه تا کانتکست‌هایی مثل شناسهٔ تیکت یا tenant رو بچسبونی:

$run = ai_run('generate-report', metadata: [
    'tenant_id' => $tenant->id,
    'ticket'    => 'PROJ-1042',
]);

وقتی یه فراخوانی AI قبل از رسیدن به ai_usage() شکست بخوره، می‌تونی خطا رو صریح ثبت کنی: متد fail() روی run با یه پیام مثل محدودیت نرخ. داشبورد هم روی مسیر /usaige رجیستر می‌شه و همهٔ runها رو با وضعیت، پرووایدر، مدل، تعداد توکن، هزینه و مدت‌زمان لیست می‌کنه. دسترسی بهش از طریق تنظیم middleware تو config/usaige.php یا یه کال‌بک Usaige::auth() کنترل می‌شه؛ مسیر داشبورد، میدل‌ورها و اسم جدول‌های دیتابیس هم همه از فایل کانفیگ منتشرشده قابل تغییرن.

برای نصب به PHP 8.5+ و Laravel 11+ و laravel/ai ^0.8.1 نیاز داری؛ با composer require laraveljutsu/usaige نصب می‌شه و بعدش یه php artisan migrate می‌خواد. سورس و مستندات کاملش هم روی GitHub هست.

نکات کلیدی:

• USAIGE هر درخواست Laravel AI SDK رو به‌شکل یه run با توکن، هزینه، مدل، زمان و خطا ثبت می‌کنه
• کل ادغام با دو هلپر ai_run() و ai_usage() انجام می‌شه؛ شکل پاسخ خودکار تشخیص داده می‌شه
• هزینه با دقت زیرِ سنت ذخیره می‌شه و از جدول ai_usages و مدل AiRun قابل کوئری‌گرفتنه
• هر run به کاربر گره می‌خوره و متادیتای JSON دلخواه (tenant، تیکت و…) قبول می‌کنه
• داشبورد روی /usaige با کنترل دسترسی از طریق middleware یا کال‌بک
• نیازمندی: PHP 8.5+، Laravel 11+ و laravel/ai ^0.8.1