Це переказ статті Івайло Ніколова (dev.to, 17 листопада 2026) про новинний сервіс NewSumm. Він читає новини сотень видань, об'єднує статті про ту саму подію в одну історію і пише короткий підсумок: у чому видання сходяться і де розходяться. У звичайний день це десятки тисяч статей.
Увесь пайплайн працює на Laravel AI SDK (laravel/ai): ембединги для кожної статті та агенти, які підсумовують історії, описують кут подачі кожного видання і витягують людей і місця, про які йдеться. Нижче - Laravel-частина: як організовано код, що SDK дає безкоштовно, і три збої, що коштували команді реального часу, бо жоден тест їх не бачив. Математику кластеризації автор розбирає в окремому пості, тут лишаємося в PHP.
Код спрощено порівняно з реальними класами: промпти, моделі та пороги прибрано навмисно, переноситься саме структура.
1. Форма пайплайна
Кожен крок - завдання в черзі:
- Fetch - забрати фіди і зберегти нові статті.
- Embed - один вектор на статтю із заголовка та опису.
- Cluster - згрупувати статті в історії за подібністю векторів у Postgres з pgvector.
- Summarise - підсумувати кожну історію, до якої приєдналося більше однієї статті.
Мовну модель викликає лише крок 4 і лише для історій з кількох статей. У дводенній вибірці з 51 842 статей історій із двома і більше статтями було 4 748, тобто 9,2% від кількості статей. Більша частина рішення про вартість ухвалюється ще до того, як запрацює будь-який агент: надсилайте моделі історії, а не статті.
2. Ембединги: пакетами, і з перевіркою входу
API ембедингів у SDK - один рядок:
use Laravel\Ai\Embeddings;
$response = Embeddings::for($texts)->generate();
$vectors = $response->embeddings; // по масиву float на кожен вхід, у тому ж порядку
Ембединги генеруються пакетами по 50, тож один HTTP-запит покриває 50 статей. Проблемою був не виклик, а вхідні дані.
Дані з фідів брудні, і один поганий рядок змушує провайдера повернути 400 на весь пакет. Автор натрапив на три випадки:
- Задовгий текст. Деякі фіди кладуть в опис усю статтю. Текст обрізають із запасом до ліміту токенів провайдера, причому нижче, ніж підказує звичне правило «чотири символи на токен»: щільні нелатинські писемності витрачають значно більше токенів на символ.
- Порожній текст. Ні заголовка, ні опису - пропускаємо.
- Виглядає порожнім, але ні. Заголовки, що складаються лише з нерозривного пробілу або пробілу нульової ширини (zero-width space).
trim() і filled() їх пропускають, провайдер бачить порожній рядок і відхиляє пакет.
private function isBlank(string $text): bool
{
return $text === '' || preg_match('/^[\p{C}\p{Z}]+$/u', $text) === 1;
}
Третій випадок ударив найболючіше. Відхилений пакет лишав свої статті позначеними як необроблені, тож їх повторювали на кожному запуску, і завдання (яке тоді йшло від найстаріших) ніколи не просувалося далі. Свіжі статті перестали отримувати ембединги, отже нічого не кластеризувалося і нічого не підсумовувалося. Сайт просто перестав показувати нові історії. Виправлень два: перевіряти вхід і обробляти спершу найновіші, щоб одна «отруєна» стаття ніколи не затримала сьогоднішні новини.
Варто знати: у Laravel 13.43 у Stringable з'явилися isBlank() і isNotBlank(), але цю проблему вони не розв'язують. Метод спирається на хелпер blank(), тобто на звичайний trim(), і тести фреймворку прямо фіксують, що str("\u{00A0}")->isBlank() і str("\u{200B}")->isBlank() повертають false. Для невидимих символів потрібна власна перевірка на кшталт регулярного виразу вище.
Порада. Коли пакетний виклик може впасти через один елемент, позначайте елементи, які неможливо обробити, як оброблені, без результату, а не лишайте їх у черзі. Вічний повтор поганого входу - це повільна відмова сервісу.
3. Агенти - це просто класи
Агент у SDK - це клас, що реалізує Agent і використовує трейт Promptable. Інструкції живуть у методі, тож їх версіонують, рев'юють і тестують як будь-який інший код:
namespace App\Ai\Agents;
use Laravel\Ai\Attributes\UseCheapestModel;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Promptable;
use Stringable;
#[UseCheapestModel]
class StorySummaryAgent implements Agent
{
use Promptable;
public function __construct(public bool $compareOutlets = false) {}
public function instructions(): Stringable|string
{
return 'You are a news editor. Summarise what these articles agree on...';
}
}
Дві речі тут себе виправдали.
#[UseCheapestModel] каже SDK взяти найдешевшу текстову модель провайдера. Завдання вузькі (підсумувати, порівняти, заповнити схему), і малі моделі справляються з ними добре. Атрибут тримає назви моделей поза кодом: змінили провайдера - і всі агенти пішли слідом.
Аргументи конструктора передаються через make(), тож один агент може змінювати поведінку від виклику до виклику без другого класу:
$response = StorySummaryAgent::make(compareOutlets: $story->hasEnoughSources())
->prompt($this->articlesPrompt($articles));
Коли compareOutlets увімкнено, і інструкції, і схема агента отримують розділ «де висвітлення відрізняється». Один клас, один файл тестів, дві поведінки.
4. Structured output перетворює автора на екстрактора
Вільний текст важко зберігати. Потрібні заголовок, підсумок, ключові тези, категорія з фіксованого списку, кут подачі кожного видання, люди й місця. Реалізуємо HasStructuredOutput і описуємо форму:
use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Ai\Contracts\HasStructuredOutput;
class StorySummaryAgent implements Agent, HasStructuredOutput
{
// ...
public function schema(JsonSchema $schema): array
{
return [
'headline' => $schema->string()->required(),
'summary' => $schema->string()->required(),
'key_points' => $schema->array()->items($schema->string())->required(),
'category' => $schema->string()->enum(Category::values())->required(),
...($this->compareOutlets ? [
'coverage_differences' => $schema->string()->required(),
] : []),
];
}
}
Відповідь читається як масив:
$story->update([
'headline' => $response['headline'],
'summary' => $response['summary'],
'category' => $response['category'],
]);
enum на категорії означає, що модель обирає з вашого списку, а не вигадує одного дня «Tech & Science», а наступного «Technology». Те, що повертається, однаково варто валідувати (схема обмежує форму, а не правдивість), але різновидів сміття стає значно менше.
Спільні правила і схема для кількох агентів
Витягування сутностей з'явилося пізніше за підсумки. Перепідсумовувати тисячі опублікованих історій лише заради людей і місць не хотілося, тому для дозаповнення старих даних у витягування є власний агент, а ті самі правила і поля вбудовуються в агент підсумків, щоб нові історії отримували все одним викликом:
class EntityExtractionAgent implements Agent, HasStructuredOutput
{
use Promptable;
public const Rules = <<<'PROMPT'
Record who the story is about, and where it happened...
PROMPT;
public function schema(JsonSchema $schema): array
{
return self::fields($schema);
}
public static function fields(JsonSchema $schema): array
{
return ['entities' => /* people + places */];
}
}
// У StorySummaryAgent::schema():
...EntityExtractionAgent::fields($schema),
Одне джерело правди для правил, два агенти, що ним користуються, і дозаповнення ніколи не чіпає опублікований підсумок.
5. Пастка strict-схеми
Цей збій на день вимкнув щоденний дайджест, а весь набір тестів лишався зеленим.
Режим structured output у провайдера строгий (strict): кожен об'єкт у схемі має містити additionalProperties: false і позначати всі свої властивості як обов'язкові. SDK надсилає запити в strict-режимі і сам додає additionalProperties: false до кореневого об'єкта. До вкладених - не додає.
Тож так працює:
'key_points' => $schema->array()->items($schema->string()),
а так відхиляється з 400 на кожному виклику:
'beats' => $schema->array()->items($schema->object([
'title' => $schema->string()->required(),
'text' => $schema->string()->required(),
])),
Виправлення - один виклик методу на кожному вкладеному об'єкті:
'beats' => $schema->array()->items($schema->object([
'title' => $schema->string()->required(),
'text' => $schema->string()->required(),
])->withoutAdditionalProperties()),
Ситуацію погіршили три речі:
- Фейки не валідують схеми.
Agent::fake() ніколи не звертається до провайдера, тож не може застосувати його правила. Усі тести проходили.
- Завдання ковтало помилку. Воно перехоплювало виняток, писало попередження в лог, пропускало категорію і публікувало порожній дайджест. У
failed_jobs нічого не потрапляло, усе виглядало як тихий день без новин.
- Лог ховав причину. Повідомлення винятку обрізалося раніше, ніж та частина тіла відповіді, де називалося хибне поле.
Тепер тест компілює справжню схему кожного агента рівно так, як її надішле SDK, і рекурсивно її обходить:
use Illuminate\JsonSchema\JsonSchemaTypeFactory;
use Laravel\Ai\ObjectSchema;
function assertStrictModeCompatible(array $schema, string $path = 'root'): void
{
expect($schema['additionalProperties'] ?? null)
->toBeFalse("Object at {$path} is missing additionalProperties: false");
expect($schema['required'] ?? [])
->toEqualCanonicalizing(array_keys($schema['properties'] ?? []), "Object at {$path} must mark every property required");
foreach ($schema['properties'] ?? [] as $name => $property) {
if (($property['type'] ?? null) === 'object') {
assertStrictModeCompatible($property, "{$path}.{$name}");
}
if (($property['type'] ?? null) === 'array' && ($property['items']['type'] ?? null) === 'object') {
assertStrictModeCompatible($property['items'], "{$path}.{$name}[]");
}
}
}
it('compiles a schema strict mode accepts', function (string $agent) {
$schema = (new ObjectSchema((new $agent)->schema(new JsonSchemaTypeFactory)))->toSchema();
assertStrictModeCompatible($schema);
})->with([
StorySummaryAgent::class,
EntityExtractionAgent::class,
DailyRecapAgent::class,
]);
Жодного API-виклику, мілісекунди на виконання, і збірка падає щойно хтось додасть вкладений об'єкт без виправлення.
Увага. Якщо завдання викликає модель у циклі і перехоплює помилки для кожного елемента, піднімайте тривогу, коли падають усі елементи. Усі елементи, що впали за лічені секунди, - це відхилений запит, а не невдала генерація.
6. Агенти в чергах: стежте за retry_after
Підсумки генеруються в завданнях черги, а виклик моделі може тривати довго. Якщо завдання працює довше за retry_after підключення черги, Laravel віддає його другому воркеру, поки перший ще працює, і ви платите за той самий підсумок двічі. У NewSumm на старті стояв стандартний retry_after у 90 секунд при таймаутах завдань у кілька хвилин. Поки це помітили, набралося 726 збійних завдань і чимало дубльованих викликів моделі.
Емпіричне правило: retry_after має бути довшим за найдовший таймаут завдання на цьому підключенні.
7. Скільки це коштує
Дашборди провайдерів показують, скільки ви витратили, але не показують, який агент це витратив. SDK запускає подію після кожного виклику з прикріпленим використанням токенів, тож слухач може записати кожен:
use Laravel\Ai\Events\AgentPrompted;
use Laravel\Ai\Events\EmbeddingsGenerated;
class RecordAiUsage
{
public function handleAgentPrompted(AgentPrompted $event): void
{
$usage = $event->response->usage;
$this->record([
'agent' => class_basename($event->prompt->agent),
'model' => $event->prompt->model,
'input_tokens' => $usage->promptTokens,
'cached_input_tokens' => $usage->cacheReadInputTokens,
'output_tokens' => $usage->completionTokens,
]);
}
public function handleEmbeddingsGenerated(EmbeddingsGenerated $event): void
{
$this->record([
'agent' => 'embeddings',
'model' => $event->model,
'input_tokens' => $event->response->tokens,
]);
}
private function record(array $attributes): void
{
try {
AiUsage::query()->create($attributes);
} catch (Throwable $e) {
Log::warning("Could not record AI usage: {$e->getMessage()}");
}
}
}
Автовиявлення подій у Laravel знаходить методи handle* за підказками типів, тож реєструвати нічого не треба. Зверніть увагу на try/catch: облік ніколи не повинен валити виклик, який він записує. Підсумок, за який уже заплачено, цінніший за рядок про його використання.
Поверх цієї таблиці працює Artisan-команда php artisan ai:usage, що групує токени за агентами (або за годинами з --hourly) і множить їх на ціни моделей із конфігурації.
8. Тестування з фейками і їхні межі
Для всього, що не стосується контракту з провайдером, фейки SDK чудові:
it('stores the overview the agent writes', function () {
EntityOverviewAgent::fake(fn (): array => ['overview' => "First paragraph.\n\nSecond paragraph."]);
// ... запускаємо завдання ...
EntityOverviewAgent::assertPrompted(fn ($prompt) => $prompt->contains('Kyiv'));
});
it('skips articles with blank titles', function () {
Embeddings::fake();
// ... генеруємо ембединги для пакета, де один із заголовків "\u{00A0}" ...
Embeddings::assertGenerated(fn ($prompt) => count($prompt->inputs) === 49);
});
Фейки відповідають на питання «чи правильно мій код поводиться з відповіддю?». На питання «чи прийме провайдер мій запит?» вони відповісти не можуть. Для цього потрібен або контрактний тест на кшталт обходу схеми вище, або один маленький справжній виклик у запланованій smoke-перевірці. Перше в команди є, і автор шкодує, що не з'явилося раніше.
Підсумок
Що автор радить тим, хто починає сьогодні:
- Вирішіть, що читатиме модель, перш ніж обирати модель. Перехід від статей до історій скоротив кількість викликів на порядок, жоден вибір моделі з цим не зрівняється.
- Робіть агентів класами з інструкціями в коді. Їх рев'юють, порівнюють у диффах і тестують як усе інше.
- Використовуйте structured output для всього, що зберігаєте, з
enum скрізь, де відповідь береться зі списку.
- Тестуйте схему, яку надсилаєте, а не лише відповідь, яку підробляєте. Вкладеним об'єктам потрібен
withoutAdditionalProperties().
- Перевіряйте вхід для ембедингів на задовгий, порожній і невидимо-порожній текст і ніколи не дозволяйте одному поганому елементу назавжди заблокувати пакет.
- Записуйте токени по кожному агенту з першого дня. Це один слухач, і він показує, куди насправді йдуть гроші.
- Ніколи мовчки не ковтайте помилку моделі. Логуйте тіло відповіді і піднімайте тривогу, коли падають усі елементи.
SDK робить щасливий шлях коротким. Основна робота була в нещасливих шляхах, і саме їх варто записувати.