USAIGE: моніторинг Token Usage та витрат для Laravel AI SDK Requests

USAIGE — це Laravel-пакет, який додає інструменти моніторингу (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 та звичайні масиви, витягуючи кількість токенів без додаткових налаштувань. Якщо формат не збігається, дані можна передати вручну:

$usage = ai_usage($run, promptTokens: 200, completionTokens: 80);

# Провайдери, моделі та розрахунок витрат

USAIGE зчитує config/ai.php для автоматичного визначення провайдера та моделі. Ці параметри можна перевизначити під час виклику або передавши Lab enum:

$run = ai_run('classify-ticket', model: 'gpt-4o-mini', provider: 'openai');

Витрати зберігаються з точністю до десятих частин цента. Таблиця ai_usages містить дані про токени та загальну суму в USD для кожного запуску, що дозволяє аналізувати витрати за функціями, користувачами, моделями або датами за допомогою моделі AiRun.

# Відстеження користувачів та метадані

За замовчуванням запит пов’язується з auth()->id(). Якщо стандартний метод не підходить, логіку ідентифікації можна змінити глобально:

use Laraveljutsu\Usaige\Facades\Usaige;

Usaige::resolveUsersUsing(fn () => auth()->user()?->team_id);

Також можна передавати ID користувача безпосередньо у виклик. Запити підтримують довільні метадані у форматі JSON для контексту (наприклад, ID тікета чи орендаря):

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

Якщо AI-запит завершився помилкою ще до виклику ai_usage(), її можна зафіксувати явно:

$run->fail('Rate limit exceeded');

# Дашборд

Пакет реєструє дашборд за адресою /usaige, де відображається список усіх запусків зі статусами, токенами, витратами та тривалістю. Доступ до нього регулюється через конфігурацію middleware у config/usaige.php або через callback:

Usaige::auth(fn ($request) => $request->user()?->isAdmin());

Шлях до дашборду, middleware та назви таблиць бази даних можна налаштувати у файлі конфігурації.

# Встановлення

Для роботи пакета необхідні PHP 8.5+, Laravel 11+ та laravel/ai ^0.8.1:

composer require laraveljutsu/usaige
php artisan migrate

Вихідний код та повна документація доступні на GitHub.