USAIGE: відстеження використання токенів та витрат для Laravel AI SDK

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, щоб заповнити провайдера та модель для кожного прогону. Обидва параметри можна перевизначити для конкретного виклику або передати enum Lab безпосередньо:

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

Витрати зберігаються з точністю до часток цента. Таблиця ai_usages зберігає як кількість токенів prompt і completion, так і загальну вартість у доларах США для кожного прогону, тому можна робити запити витрат за функцією, користувачем, моделлю чи діапазоном дат, використовуючи модель 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 або через колбек:

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.