Laravel наконец подружился с нейросетями. Разбираемся, как работает официальный AI SDK

Если вы хоть раз пробовали подключить к PHP-проекту сразу несколько нейросетей - например, OpenAI, Anthropic или Gemini, - то наверняка сталкивались с одной и той же проблемой: модели умеют делать похожие вещи, но работать с ними приходится совершенно по-разному.

У каждого провайдера свой формат ответа, свои ошибки, свои ограничения и свой способ потоковой передачи текста. В итоге разработчики тратят время не на создание AI-функций, а на поддержку собственных адаптеров, клиентов и прослоек, которые просто приводят разные ответы к одному виду.

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

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

В феврале 2026 года Laravel закрыл эту проблему официально, выпустив первый релиз Laravel AI SDK - пакета laravel/ai, который даёт единый способ работать с OpenAI, Anthropic, Gemini и ещё более чем десятком провайдеров. Если вы пишете фичи с нейросетями на PHP - или только планируете первую интеграцию - этот материал объяснит, как убрать хаос и начать писать чистый, переносимый код за один вечер.

Что такое Laravel AI SDK

Laravel AI SDK - это официальный пакет, который даёт единый, «ларавельный» API для вызова больших языковых моделей. Если вы работали с Eloquent - логику поймёте быстро: вместо прямых HTTP-запросов к API конкретного провайдера вы описываете агента - PHP-класс с инструкциями, инструментами и (опционально) схемой ответа, - а SDK сам решает, как обратиться к выбранной модели.

Смена провайдера превращается в изменение одного аргумента или переменной окружения, а не в переписывание слоя интеграции.

Откуда это взялось

Пакет анонсировала сама команда Laravel в официальном блоге как первую (на момент анонса - бета) версию SDK. Он не «пришёл вместе с Laravel 13» - это отдельный Composer-пакет, документация по которому есть и для Laravel 12.x, и для 13.x. До его появления PHP-проекты действительно обрастали зоопарком самописных врапперов под каждого провайдера - с этим согласны и в самой команде Laravel, и авторы независимых разборов SDK.

На сегодня SDK поддерживает генерацию текста, изображений, речи (TTS), распознавание речи (STT), эмбеддинги, реранкинг и файлы/векторные хранилища для более чем десятка провайдеров: OpenAI, Anthropic, Gemini, Groq, xAI, Azure OpenAI, AWS Bedrock, DeepSeek, Mistral, Ollama, OpenRouter, Cohere, Jina, VoyageAI, ElevenLabs - плюс любой OpenAI-совместимый эндпоинт (LM Studio, vLLM, Together и так далее).

Пошаговое подключение

Шаг 1. Установка через Composer

composer require laravel/ai
php artisan vendor:publish --provider="Laravel\Ai\AiServiceProvider"
php artisan migrate

Миграции создают таблицы agent_conversations и agent_conversation_messages - SDK использует их для хранения истории диалогов, если вы захотите этой функцией воспользоваться.

Шаг 2. Ключи в переменных окружения Никаких секретов в коде - всё в .env:

OPENAI_API_KEY="sk-..."
ANTHROPIC_API_KEY="sk-ant-..."
GEMINI_API_KEY="..."

Шаг 3. Первый агент Ядро SDK - это классы-агенты. Создаём модератора комментариев:

php artisan make:agent CommentModerator

<?php

namespace App\Ai\Agents;

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

class CommentModerator implements Agent
{
    use Promptable;

    public function instructions(): string
    {
        return 'Ответь только "ok" или "spam", без пояснений.';
    }
}

Вызов агента:

$response = (new CommentModerator)->prompt($commentText);

$isClean = trim((string) $response) === 'ok';

Никакой ручной распаковки JSON и разбора HTTP-статусов - только бизнес-логика.

Шаг 4. Смена провайдера или модели

Явно указать провайдер и модель для конкретного вызова можно прямо в prompt():

use Laravel\Ai\Enums\Lab;

$response = (new CommentModerator)->prompt(
    $commentText,
    provider: Lab::Anthropic,
    model: 'claude-haiku-4-5-20251001',
);

А для автоматического переключения на резервного провайдera при рейт-лимите или сбое - передать массив провайдеров:

$response = (new CommentModerator)->prompt(
    $commentText,
    provider: [Lab::OpenAI, Lab::Anthropic],
);

Failover срабатывает только на «поправимых» исключениях - рейт-лимит, перегрузка провайдера, нехватка кредитов. Обычная ошибка валидации резервный провайдер не подключит.

Шаг 5. Стриминг для чатов

Если нужно выводить ответ по мере генерации:

use App\Ai\Agents\CommentModerator;

Route::get('/chat', function () {
    return (new CommentModerator)->stream('Расскажи о Laravel');
});

Метод stream() возвращает объект, который Laravel сам превращает в SSE-ответ (Server-Sent Events) при возврате из роута - отдельно настраивать ob_flush/flush вручную не требуется.

Что реально решает SDK

Разнобой форматов. Каждый провайдер отдаёт ответ в своей структуре. SDK приводит всё к единому интерфейсу - вы просто читаете (string) $response или, для структурированного вывода, обращаетесь к ответу как к массиву.

Структурированный вывод. Если агент реализует интерфейс HasStructuredOutput и описывает JSON-схему в методе schema(), ответ модели гарантированно приходит в предсказуемом формате - удобно для классификации, извлечения данных, лид-скоринга.

Инструменты и RAG. Агентам можно давать доступ к собственным PHP-инструментам (php artisan make:tool), к MCP-серверам, к встроенным provider tools (веб-поиск, чтение URL, поиск по файлам) и даже к другим агентам как саб-агентам.

Тестирование. У каждого класса (агентов, Image, Audio, Embeddings и т.д.) есть метод fake() с ассертами вроде assertPrompted() - можно тестировать AI-логику без реальных вызовов к провайдерам.

Где применять прямо сейчас

Помимо чат-ботов и модерации, SDK хорошо ложится в сценарии посерьёзнее: семантический поиск по документам через эмбеддинги и векторные колонки Postgres (pgvector), RAG поверх собственной базы данных через инструмент SimilaritySearch, извлечение структурированных данных из свободного текста (например, квалификация лидов из CSV), многоагентные пайплайны (маршрутизация, параллельные саб-агенты, оркестратор-воркеры).

Часто задаваемые вопросы

Это платный инструмент? Сам SDK бесплатный и открытый. Платите вы только провайдерам моделей за использованные токены - как и без SDK.

Можно ли мигрировать, если у меня уже написаны врапперы? Да. Логику вызова модели придётся перенести в класс-агент, но бизнес-код, читающий ответ, меняется минимально. Ограничение - узкоспециализированные параметры конкретного провайдера, которых нет в общем API; для них есть метод providerOptions(), позволяющий передать «сырые» настройки нужному провайдеру.

Безопасно ли хранить ключи в .env? Да, это стандартный подход для Laravel. Важно не коммитить .env в репозиторий и использовать разные ключи для локальной разработки и продакшена.

Помогает ли SDK бороться с галлюцинациями моделей? Напрямую нет. Но даёт рычаги контроля: низкую температуру для фактологических задач, строгие системные промпты и структурированный вывод, снижающий пространство для «отсебятины» модели.

Что если провайдер временно недоступен? Настройте failover, передав массив провайдеров в prompt() - при рейт-лимите или перегрузке SDK сам переключится на следующий в списке.

Выдержит ли сервер потоковую передачу? Да, если веб-сервер не буферизирует ответы. Для nginx может потребоваться отключить proxy_buffering.

Практичные советы напоследок

Кэшируйте эмбеддинги - SDK умеет это делать «из коробки» (->cache() или глобальная настройка в config/ai.php), что экономит токены на повторяющихся запросах.

Логируйте использование - SDK бросает события вроде AgentPrompted, EmbeddingsGenerated, ImageGenerated, на которые можно подписаться и писать метрики по стоимости и задержке.

Не забывайте про fallback-провайдера - передавайте массив провайдеров туда, где сбой критичен для пользователя.

Используйте очереди для тяжёлых задач - у агентов, изображений, аудио и транскрипций есть метод queue(), не блокирующий ответ пользователю.

Итог

Появление официального AI SDK - важный шаг для PHP-экосистемы: работа с нейросетями перестаёт быть нишевым экспериментом с самописными врапперами и становится штатной инженерной практикой на уровне фреймворка. Код становится короче и переносимее - но, как и с любым новым инструментом, стоит сверяться с актуальной документацией на laravel.com, а не с пересказами: SDK ещё активно развивается, и детали API могут меняться от релиза к релизу.