Laravel AI SDK: ИИ-агенты, RAG и работа с моделями в PHP

Laravel AI SDK добавляет в PHP-приложение работу с языковыми моделями, ИИ-агентами, изображениями, аудио и поиском по смыслу. Это официальный пакет Laravel: конфигурация, команды Artisan, очереди и тестовые подмены используют привычные механизмы фреймворка. Модель отвечает за генерацию, а приложение по-прежнему управляет пользователями, данными и бизнес-правилами.

SDK, или набор средств разработки, нужен для функций внутри продукта: помощника поддержки, разбора обращений, обработки файлов. Он не пишет сайт по описанию и не заменяет IDE. Агент здесь означает PHP-объект с инструкцией, доступными функциями и контекстом диалога. Такой объект можно вызывать из контроллера, консольной команды или фоновой задачи.

Хорошая точка входа: действующий Laravel-сервис, где уже есть авторизация, база данных и очереди, а ИИ должен решить одну понятную задачу. Например, подготовить черновик ответа оператору или извлечь поля из заявки. Вы сохраняете основной стек и описываете поведение помощника в PHP.

• Команде поддержки: объяснять правила из базы знаний и находить сведения через разрешённые инструменты.
• Разработчику CRM: превращать свободный текст обращения в поля, которые приложение затем проверяет и сохраняет.
• Автору сервиса обработки контента: объединить расшифровку записи, краткое содержание и поиск по полученным материалам.

Для приложения на Laravel 11 установка потребует пересмотра версий зависимостей. Если серверную часть вы строите на TypeScript, разумнее сначала посмотреть Vercel AI SDK или TanStack AI. Общий HTTP-интерфейс к модели не делает PHP-пакет библиотекой для любого языка.

Embeddings, или векторные представления, записывают смысл текста в виде чисел. По ним можно найти похожие фрагменты, даже если вопрос сформулирован другими словами. Reranking повторно оценивает уже найденные результаты и переставляет их по релевантности. Эти операции решают разные части поиска.

Провайдером называют сервис, который запускает модель и принимает API-запросы. В SDK есть подключения OpenAI, Anthropic, Gemini, Groq, DeepSeek, Mistral, Ollama, OpenRouter и других сервисов. Выбор хранится в config/ai.php; при вызове можно задать провайдера и модель явно.

Наличие провайдера в конфигурации не означает поддержку всех режимов. Текст, генерация изображений, озвучивание, embeddings и файловый поиск имеют отдельные списки совместимости. Перед сменой сервиса проверьте конкретную комбинацию модели и функции. Особенно это касается инструментов, вложений и строгого JSON-ответа.

Пакет требует PHP ^8.3 и компоненты Illuminate веток 12 или 13. Для illuminate/json-schema установлен более узкий порог: ^12.62 или ^13.15. Поэтому фразы «у меня Laravel 12» недостаточно: Composer должен суметь собрать совместимый набор зависимостей.

• Установите Composer и проверьте версию PHP у веб-сервера и CLI: они могут различаться.
• Для сохранения диалогов подготовьте подключение к базе и выполните миграции пакета.
• К облачной модели нужен API-ключ; для локальной модели нужен отдельно запущенный сервер.
• MCP-инструменты требуют laravel/mcp версии ^1.0, а Bedrock требует отдельный AWS SDK.

Перед добавлением зависимости сохраните composer.lock в системе контроля версий и проверьте установку в копии приложения. Обычное ограничение ^1.2 допускает следующие совместимые версии 1.x; точный установленный набор фиксирует lock-файл. Это помогает повторить окружение на сервере.

Выполните команды из корня существующего Laravel-приложения. Публикация конфигурации создаёт настройки SDK и миграции таблиц диалогов. Миграции меняют базу, поэтому сначала запустите их в среде разработки.

composer require laravel/ai:"^1.2"
php artisan vendor:publish --provider="Laravel\Ai\AiServiceProvider"
php artisan migrate
php artisan make:agent SupportAssistant

Добавьте OPENAI_API_KEY в .env, а в config/services.php создайте секцию ai с text_model, читающим переменную AI_TEXT_MODEL. В AI_TEXT_MODEL укажите модель, доступную вашему аккаунту. После изменения конфигурации пересоберите config cache, если он используется. Ключ остаётся на сервере.

OPENAI_API_KEY=your-api-key
AI_TEXT_MODEL=your-enabled-text-model

<?php

use function Laravel\Ai\agent;

$response = agent(
    instructions: 'Объясняй условия доставки простым русским языком. Не придумывай отсутствующие сведения.',
)->prompt(
    'Сократи правило: доставка занимает 3 рабочих дня после передачи заказа перевозчику.',
    provider: 'openai',
    model: config('services.ai.text_model'),
);

echo (string) $response;

Пример принимает готовое правило доставки и просит сократить его. Он не подключает базу знаний и не открывает доступ к заказам. Сначала убедитесь, что запрос проходит с выбранной моделью, затем вынесите повторяющуюся инструкцию в класс SupportAssistant. Ошибки ключа, квоты и сети обрабатывайте отдельно от успешного ответа.

Для повторного использования создайте агент через make:agent. Класс реализует Laravel\Ai\Contracts\Agent и использует Promptable. Метод instructions() задаёт поведение. Дополнительные интерфейсы подключают историю диалога, инструменты или схему результата, поэтому простому помощнику не нужен весь набор возможностей сразу.

<?php

namespace App\Ai\Agents;

use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Promptable;

class SupportAssistant implements Agent
{
    use Promptable;

    public function instructions(): string
    {
        return 'Помогай оператору поддержки. Если правило не передано в запросе, попроси уточнение.';
    }
}

Вызывайте SupportAssistant::make()->prompt(...) там, где нужна функция продукта. Создание через make() разрешает зависимости из контейнера Laravel: например, сервис поиска или настройки клиента. Не складывайте постоянную инструкцию, текст пользователя и секретные ключи в одну строку. У каждого элемента своё назначение.

Когда следующий шаг ожидает поля, свободный абзац неудобен. HasStructuredOutput задаёт схему через JsonSchema, а результат читается как массив. Это подходит для извлечения темы обращения, языка и категории. Схема описывает форму данных; проверки бизнес-правил остаются в приложении.

public function schema(\Illuminate\Contracts\JsonSchema\JsonSchema $schema): array
{
    return [
        'subject' => $schema->string()->required(),
        'category' => $schema->string()->required(),
    ];
}

Попросите модель заполнить subject и category из текста обращения. Затем проверьте, что category входит в разрешённый список вашей CRM. Даже ответ правильной формы может неверно понять жалобу. До автоматической маршрутизации полезно показывать оператору извлечённые поля и исходный текст рядом.

Инструмент, или tool, описывает функцию, которую модель может попросить выполнить: найти статус заказа, получить правила тарифа, подобрать документы. В Laravel AI для него задают описание, схему аргументов и обработчик handle(). PHP-код выполняется вашим сервером, поэтому именно обработчик проверяет права пользователя.

MCP, Model Context Protocol, подключает готовые инструменты внешнего сервера. Это полезно, когда нужная функция уже опубликована через протокол. При этом подключение MCP не делает все чужие инструменты подходящими для вашего продукта: выбирайте нужные и проверяйте параметры передачи данных.

• Начните с чтения: статус заказа или поиск разрешённых справочных материалов.
• В обработчике извлекайте пользователя из доверенного контекста приложения, а не из имени, которое вернула модель.
• Для записи отделите подготовку предложения от его выполнения; для операций, которым нужно подтверждение, используйте механизм согласования инструментов.

RemembersConversations сохраняет сообщения в базе и загружает их при продолжении разговора. Агент реализует Conversational; forUser() начинает разговор, continue() продолжает его. Для этого нужны опубликованные миграции. Если в классе вручную определить messages(), этот метод перекроет загрузку истории через trait, механизм повторного использования методов в PHP.

$response = \App\Ai\Agents\SupportAssistant::make()
    ->continue($conversationId, as: $user)
    ->prompt('Объясни второй пункт ответа подробнее.');

return (string) $response;

Фрагмент предполагает, что SupportAssistant уже реализует Conversational и использует RemembersConversations, а $conversationId и $user получены обработчиком. История разговора помогает уточняющим вопросам. Она не заменяет постоянную базу знаний: большой архив инструкций лучше искать отдельно и передавать только нужные фрагменты.

RAG означает генерацию ответа с предварительным поиском по внешним данным. Вы сначала готовите текст документов, затем делите его на фрагменты, создаёте векторы и сохраняете их с указанием источника. По вопросу пользователя находите подходящие фрагменты и передаёте их агенту. Модель получает контекст для конкретного ответа.

<?php

use Laravel\Ai\Embeddings;

$result = Embeddings::for([
    'Возврат оформляется через личный кабинет.',
    'Срок доставки указан при подтверждении заказа.',
])->generate();

$vectors = $result->embeddings;

SDK даёт генерацию embeddings и интеграции поиска, но не устраняет подготовку исходных файлов. Для сложных PDF и сканов пригодятся Docling или MinerU: они извлекают текст и структуру. Затем ваш процесс загрузки переносит результат в поисковое хранилище и сохраняет права доступа к каждому документу.

Laravel AI объединяет генерацию изображений, синтез речи, расшифровку аудио и вложения в запросах. Это разные операции: передать фотографию модели для анализа и сгенерировать новую картинку требуют разных возможностей провайдера. Выбирайте режим по задаче продукта.

• Голосовое обращение: получить расшифровку, извлечь тему и показать оператору текст с исходной записью.
• Описание товара: анализировать разрешённое изображение и подготовить черновик, который проверит менеджер.
• Обучающий сервис: озвучить утверждённый текст, сохранив исходник и созданный аудиофайл.

Вложения отправляются выбранному сервису. Локальное хранение файла в Laravel не означает локальную обработку моделью. Для персональных данных задайте правила отправки и удаления; ограничения форматов и размера проверяйте у того провайдера, который действительно обрабатывает запрос.

Streaming отдаёт ответ частями: интерфейс может показывать начало текста до завершения генерации. Queueing переносит вызов в фоновую задачу. Первый подход удобен для диалога, второй для обработки длинной записи или партии документов. Очередь нужно запускать отдельным процессом-обработчиком очереди Laravel.

Failover переключает запрос на резервный сервис при определённых сбоях, например превышении лимита, перегрузке или отсутствии средств. Ошибка валидации и некорректный запрос не становятся поводом для переключения. Модель резервного сервиса может отвечать иначе, поэтому оба пути должны соответствовать требованиям функции.

$response = \App\Ai\Agents\SupportAssistant::make()->prompt(
    'Сократи переданные правила доставки.',
    provider: ['openai', 'anthropic'],
);

Promptable предоставляет fake() и проверки отправленных запросов. Это позволяет проверять ветвление приложения без обращения к модели: например, что черновик сохраняется и возвращается оператору. preventStrayPrompts() помогает поймать вызов агента, которому забыли задать тестовую подмену.

use App\Ai\Agents\SupportAssistant;

SupportAssistant::fake(['Доставка занимает 3 рабочих дня.'])
    ->preventStrayPrompts();

$answer = SupportAssistant::make()->prompt('Сократи правило доставки.');

expect((string) $answer)->toBe('Доставка занимает 3 рабочих дня.');
SupportAssistant::assertPrompted('Сократи правило доставки.');

Подмена доказывает работу вашего кода с заранее известным ответом. Для оценки самой модели нужен отдельный набор обращений: обычные вопросы, неполные сведения, противоречия и попытки получить чужие данные. Проверяйте содержание ответа, извлечённые поля и использованные инструменты.

Пакет выполняется на вашем PHP-сервере. При облачном провайдере генерация идёт через внешний API; через Ollama или совместимый endpoint можно направить запрос в отдельно развёрнутую модель. Для openai-compatible нужно указать URL, а для произвольных моделей embeddings ещё и настройки используемой модели.

MIT разрешает коммерческое использование, изменение и распространение пакета при сохранении уведомления об авторстве и текста лицензии. Гарантии не предоставляются. Лицензия библиотеки не оплачивает API-запросы и не распространяется на модели, хостинг и дополнительные сервисы. Их условия и расходы оцениваются отдельно.

Для рабочего сервиса задайте лимит входного текста, таймаут, число шагов инструментов и бюджет запросов. Сохраняйте информацию о потреблении, чтобы одна затянувшаяся цепочка агента не превратилась в неизвестный счёт. SDK упрощает вызов модели; эксплуатация всё равно требует контроля на стороне приложения.

Начните выбор с требований к приложению. Если вся задача сводится к извлечению полей, достаточно одного запроса и проверки результата. Если процесс должен приостанавливаться, искать документы и выполнять действия, сравнивайте способы управления состоянием. Большое число возможностей само по себе не оправдывает более сложную архитектуру.

Для приложения на Symfony сравните этот подход с Symfony AI. В нём есть отдельные компоненты Platform, Agent, Chat и Store и настройка через Symfony Bundle. За пределами Symfony компоненты можно собрать вручную; выбор зависит от того, какие механизмы уже есть в вашем PHP-проекте. Ссылка на подробный обзор находится в таблице альтернатив.

• Laravel AI SDK на GitHub
• Laravel AI SDK: сайт и документация