Prism для Laravel: модели, JSON, инструменты и streaming в PHP

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

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

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

Prism хорошо ложится на приложение, в котором бизнес-процесс уже описан кодом. Запрос к модели становится одним из его шагов. Для сложного процесса с остановками, событиями и сохранением промежуточного состояния стоит сравнить Neuron AI. Для официального набора Laravel с агентами, очередями и медиа посмотрите Laravel AI SDK.

У пакета требования PHP ^8.2, ext-fileinfo и laravel/framework ^11.0|^12.0|^13.0. Это Laravel-библиотека: установить её как независимый SDK в произвольный PHP-проект без фреймворка не получится тем же способом. Проверьте совместимость через Composer до переноса кода на сервер.

Версия 0.100.1 относится к ветке до 1.0. Следующая минорная версия может менять API, поэтому фиксируйте ограничение версии и composer.lock. Значение ^0.100.1 ограничивает обновления веткой 0.100.x. Перед переходом в следующую ветку проверьте примеры и тесты интеграции.

Команды выполняются в существующем Laravel-приложении. После публикации появится config/prism.php с параметрами провайдеров и сетевых запросов. API-ключ OpenAI задайте через OPENAI_API_KEY в .env. Для примера добавьте services.ai.text_model в config/services.php и свяжите его с AI_TEXT_MODEL.

composer require prism-php/prism:"^0.100.1"
php artisan vendor:publish --tag=prism-config

<?php

use Prism\Prism\Enums\Provider;
use Prism\Prism\Facades\Prism;

$response = Prism::text()
    ->using(Provider::OpenAI, config('services.ai.text_model'))
    ->withSystemPrompt('Пиши кратко по-русски и сохраняй факты исходного текста.')
    ->withPrompt('Сократи: заказ передадут перевозчику в течение двух рабочих дней после оплаты.')
    ->asText();

echo $response->text;

В AI_TEXT_MODEL укажите модель, доступную в вашем аккаунте. Результат лежит в $response->text. Пример не подключает историю и документы: он получает весь исходный факт прямо в запросе. Если задача повторяется, вынесите цепочку в сервис приложения и тестируйте её отдельно от контроллера.

Prism поддерживает подключения к OpenAI, Anthropic, Gemini, Ollama, Groq, DeepSeek, Mistral, OpenRouter и другим сервисам. Провайдер отвечает за доступ к модели, модель за конкретные возможности. Замена значения в using() сохраняет форму вызова, но не гарантирует одинаковую работу инструментов и вложений.

withSystemPrompt() задаёт инструкцию, withPrompt() передаёт задачу, withMessages() используется для истории. Контекстное окно ограничивает объём входных данных. Для длинного диалога приложению нужно выбирать, какие сообщения отправить, а не бесконечно добавлять весь архив.

Structured output означает ответ по схеме. В Prism схему описывают объектами ObjectSchema, StringSchema и другими типами, затем передают в withSchema(). Это удобнее, чем просить обычным текстом «верни JSON» и вручную вырезать его из ответа. Для OpenAI корневой схемой должен быть ObjectSchema.

<?php

use Prism\Prism\Enums\Provider;
use Prism\Prism\Facades\Prism;
use Prism\Prism\Schema\ObjectSchema;
use Prism\Prism\Schema\StringSchema;

$schema = new ObjectSchema(
    name: 'ticket',
    description: 'Поля обращения клиента',
    properties: [
        new StringSchema('subject', 'Тема обращения'),
        new StringSchema('summary', 'Краткое содержание без выдуманных деталей'),
    ],
    requiredFields: ['subject', 'summary'],
);

$response = Prism::structured()
    ->using(Provider::OpenAI, config('services.ai.text_model'))
    ->withSchema($schema)
    ->withPrompt('Клиент пишет: оплатил заказ, но не получил подтверждение по почте.')
    ->asStructured();

$ticket = $response->structured;

Правильная структура не доказывает правильность извлечённых фактов. Перед сохранением проверьте длину полей, допустимые значения и отсутствие чувствительных данных. У разных провайдеров различаются строгий режим схемы и обычный JSON mode; выбирайте модель, которая поддерживает нужный режим.

Tool calling означает, что модель возвращает запрос на выполнение описанной функции. Prism передаёт аргументы обработчику, получает его строковый результат и может продолжить диалог. Для цикла с инструментом нужен withMaxSteps() как минимум 2: запрос функции и ответ после её выполнения занимают отдельные шаги.

<?php

use Prism\Prism\Enums\Provider;
use Prism\Prism\Facades\Prism;
use Prism\Prism\Facades\Tool;

$sum = Tool::as('sum')
    ->for('Сложить два числа')
    ->withNumberParameter('a', 'Первое число')
    ->withNumberParameter('b', 'Второе число')
    ->using(fn (float $a, float $b): string => (string) ($a + $b));

$response = Prism::text()
    ->using(Provider::OpenAI, config('services.ai.text_model'))
    ->withMaxSteps(2)
    ->withTools([$sum])
    ->withPrompt('Используй sum, чтобы сложить 12 и 7.')
    ->asText();

Пример демонстрирует вызов PHP-функции без доступа к данным клиента. Для заказа или CRM проверяйте права внутри обработчика. Число шагов ограничивает цикл, но не заменяет таймаут и лимит запросов. Если инструмент возвращает ошибку аргументов, модель может попробовать исправить вызов, что тоже расходует шаги.

Prism умеет отдавать Server-Sent Events, или SSE: сервер передаёт браузеру события по одному соединению. Есть потоковые ответы и адаптеры для клиентских интерфейсов. Это полезно для чата, где пользователь не должен ждать завершения длинного текста перед появлением первой строки.

В Laravel Telescope и других перехватчиках HTTP-событий есть риск преждевременного чтения потока. Если текст перестал появляться частями, проверьте перехватчики, настройки proxy и буферизацию. Потоковый интерфейс сам по себе не уменьшает время работы модели и не гарантирует завершение операции после закрытия вкладки.

Embeddings превращают текст в вектор чисел для сравнения по смыслу. Prism создаёт векторы, но сам запрос embeddings не превращается в готовую базу знаний. Вам нужны разбиение документов, хранилище векторов, поиск и передача найденного контекста в модель. Эта последовательность называется RAG.

<?php

use Prism\Prism\Enums\Provider;
use Prism\Prism\Facades\Prism;

$response = Prism::embeddings()
    ->using(Provider::OpenAI, 'text-embedding-3-small')
    ->fromInput('Возврат оформляется в личном кабинете.')
    ->asEmbeddings();

$vector = $response->embeddings[0]->embedding;

Передавайте в модель только документы, доступные текущему пользователю, и храните ссылку на источник каждого фрагмента. Для PDF со сложной вёрсткой можно подготовить данные через Docling или MinerU. Если нужен готовый набор компонентов RAG на PHP, сравните подход Neuron AI.

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

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

Prism::fake() принимает заранее подготовленные ответы. TextResponseFake помогает задать текст и другие поля без сетевого запроса. Так можно проверить обработку удачного ответа, последовательность вызовов и сохранение результата. Отдельно проверяйте ошибку ключа, таймаут и неверные аргументы инструмента.

use Prism\Prism\Enums\Provider;
use Prism\Prism\Facades\Prism;
use Prism\Prism\Testing\TextResponseFake;

Prism::fake([TextResponseFake::make()->withText('Краткое описание')]);

$response = Prism::text()
    ->using(Provider::OpenAI, 'test-model')
    ->withPrompt('Сократи описание.')
    ->asText();

expect($response->text)->toBe('Краткое описание');

Тест с fake проверяет логику приложения. Для выбора модели подготовьте реальные примеры входов и критерии: сохранились ли факты, правильно ли выделены поля, не вызван ли лишний инструмент. Иначе работающий HTTP-запрос легко принять за полезную функцию.

Prism выполняется в Laravel-приложении и может обращаться к облачным моделям или локальному серверу Ollama. Адрес Ollama задаётся через OLLAMA_URL; время ожидания часто приходится увеличивать. Локальную модель нужно отдельно установить и запустить на машине с подходящими ресурсами.

$response = \Prism\Prism\Facades\Prism::text()
    ->using(\Prism\Prism\Enums\Provider::Ollama, 'llama3.2')
    ->withPrompt('Объясни правило доставки по-русски.')
    ->withClientOptions(['timeout' => 120])
    ->asText();

У Prism Server отдельное назначение: предоставить доступ к настроенным Prism-моделям через OpenAI-совместимый интерфейс. Такой endpoint нужно защищать авторизацией и лимитами. Сам факт его появления не запускает модель и не делает обращения к внешнему провайдеру бесплатными.

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

Prism удобен, когда нужна явная цепочка: задать вход, выбрать модель, получить текст или структуру. Laravel AI SDK предлагает официальный набор Laravel с агентами, сохранением диалогов и очередями. Neuron AI строит агента на основе workflow и добавляет компоненты для RAG и сложного управления процессом.

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

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

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