AI Pro¶

Важно

Для премиальных продуктов требуется бесплатный плагин License Manager. Установите его и добавьте лицензию продукта перед установкой этого продукта.

Требования¶

AI Pro рассчитан на Grav 1.7+ и последнюю версию плагина Grav Admin. Убедитесь, что ваш сервер может обращаться к эндпоинтам API всех провайдеров ИИ, которые вы планируете использовать.

Установка¶

Установите или обновите через GPM, как любой другой премиальный плагин. Команда ниже предполагает, что вы уже привязали лицензию Grav Premium к сайту.

$ bin/gpm install ai-pro

Вы также можете установить AI Pro на экране Admin → Plugins. После включения плагин добавляет пункт навигации и элементы управления ассистентом в админке.

Быстрый старт¶

Перейдите в Plugins → AI Pro в админке.
Установите для AI Pro значение enabled и выберите провайдера по умолчанию.
Вставьте учётные данные API для провайдеров, которые хотите активировать.
Сохраните конфигурацию и нажмите Test Provider, чтобы проверить соединение.
Откройте любую страницу в админке — плавающий ИИ-ассистент доступен для быстрых промптов и автоматизации работы с контентом.

Настройка провайдеров¶

AI Pro из коробки поддерживает OpenAI, Claude и Gemini, а также любые провайдеры, зарегистрированные через расширения, например AI Pro – DeepSeek. Каждый раздел содержит:

enabled: включает или отключает провайдера без удаления учётных данных.
api_key: ваш токен доступа или секрет.
endpoint: переопределяет базовый URL API по умолчанию, если вы используете региональные эндпоинты или совместимые шлюзы.
model: выберите модель по умолчанию для чата и генерации ответов.
max_tokens, timeout и temperature: настройка ограничений генерации и стиля ответов.

Проверка провайдеров¶

Используйте кнопку Test Provider рядом с любой группой настроек или выполните:

$ bin/plugin ai-pro validate --provider=openai

Команда проверяет учётные данные, сетевой доступ и возможность получить список моделей.

Работа с ассистентом¶

Когда assistant.enabled имеет значение true, AI Pro добавляет в интерфейс админки плавающую кнопку ассистента. Вы можете:

Запускать быстрые промпты, заданные в prompts.*.
Сохранять и загружать беседы отдельно для каждого пользователя.
Получать ответы потоком по мере поступления — идеально для длинных ответов.
Вставлять ответы напрямую в поля страницы или копировать их в буфер обмена.

Включите assistant.site_wide, если ассистент нужен на каждой странице админки, или ограничьте его представлениями редактирования контента.

Фоновая обработка и разбиение на части¶

Длительные задачи, например переписывание контента, могут выполняться в фоне. Раздел processing предлагает:

method: выберите sync для немедленных ответов или background, чтобы поставить работу в очередь.
chunk_size: автоматически разбивает большие промпты на удобные для обработки запросы.
Параметры повторных попыток, чтобы восстановиться после временных сбоев API.

Эти настройки действуют и тогда, когда AI Pro обеспечивает работу других плагинов, например AI Translate, поэтому поведение остаётся единообразным во всём стеке.

Кэширование и контроль затрат¶

Установите response.cache_enabled, чтобы повторно использовать одинаковые запросы в течение настраиваемого cache_ttl. AI Pro отслеживает количество входных и выходных токенов, если провайдер их предоставляет, что позволяет оценивать затраты или вводить ограничения с помощью хуков estimate_cost.

Использование из командной строки¶

AI Pro включает несколько подкоманд CLI в bin/plugin ai-pro:

validate — проверяет конкретного провайдера.
chat — отправляет разовые промпты любому настроенному провайдеру.
models — просматривает списки моделей провайдеров, при необходимости обновляя кэш.
process — выполняет задания из очереди фоновых задач (используется для асинхронной обработки).
completion — выводит скрипты автодополнения оболочки для Bash/Zsh/Fish.

Команда chat¶

# Промпт через аргумент или --prompt
bin/plugin ai-pro chat "Summarize the latest release notes"

# Переопределить провайдера/модель и передавать вывод потоком
bin/plugin ai-pro chat \
  --provider=anthropic \
  --model=claude-3-haiku-20240307 \
  --system="You are a concise technical writer." \
  --stream --show-usage

К важным флагам относятся --provider, --model, --system, --context, --temperature, --max-tokens, повторяемый --option key=value, --format text|json и --show-usage. Промпты также можно передавать через STDIN (echo "..." | bin/plugin ai-pro chat).

Просмотр моделей¶

# Список моделей для каждого включённого провайдера
bin/plugin ai-pro models

# Обновить кэш и вернуть JSON для OpenAI
bin/plugin ai-pro models --provider=openai --refresh --json

Запуск фоновых задач¶

bin/plugin ai-pro process --task-id=abc123

Используйте эту команду при отладке асинхронных процессов или при настройке супервизоров для выполнения задач из очереди вне цикла веб-запроса.

Сочетайте эти инструменты с cron или скриптами развёртывания, чтобы автоматизировать обновление документации, списков изменений, дайджестов или пакетное переписывание.

Расширение AI Pro¶

Регистрируйте собственных провайдеров, создавая сопутствующий плагин и подписываясь на событие onAIProvidersRegister.

<?php
namespace Grav\Plugin\AIProMyProvider;

use Grav\Common\Plugin;
use Grav\Plugin\AIPro\Providers\Registry;

class AIProMyProviderPlugin extends Plugin
{
    public static function getSubscribedEvents(): array
    {
        return [
            'onAIProvidersRegister' => ['onAIProvidersRegister', 0],
        ];
    }

    public function onAIProvidersRegister(Registry $providers): void
    {
        $providers->register('my-provider', MyProvider::class);
    }
}

Расширьте AbstractProvider, реализовав обязательные методы (initialize(), buildRequest(), parseResponse(), getEndpoint(), getHeaders()), и AI Pro сделает вашего провайдера доступным в ассистенте админки, фоновом обработчике и CLI.

Пример: плагин, использующий AI Pro¶

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

<?php
namespace Grav\Plugin;

use Grav\Common\Plugin;
use Grav\Common\Page\Page;
use Grav\Plugin\AIPro\AIProService;

class PageSummaryPlugin extends Plugin
{
    public static function getSubscribedEvents(): array
    {
        return [
            'onAdminSave' => ['onAdminSave', 0],
        ];
    }

    public function onAdminSave(): void
    {
        /** @var Page $page */
        $page = $this->grav['page'] ?? null;
        if (!$page instanceof Page) {
            return;
        }

        /** @var AIProService|null $ai */
        $ai = $this->grav['ai-pro'] ?? null;
        if (!$ai instanceof AIProService) {
            return; // AI Pro недоступен
        }

        $request = [
            'messages' => [
                ['role' => 'system', 'content' => 'You summarize Grav CMS pages.'],
                ['role' => 'user', 'content' => sprintf(
                    "Summarize this page in 2 sentences:\n\nTitle: %s\n\nContent:\n%s",
                    $page->title(),
                    strip_tags($page->rawMarkdown())
                )],
            ],
            'max_tokens' => 200,
        ];

        $response = $ai->chat($request); // Использует провайдер по умолчанию
        $summary = $response->getContent();

        if ($summary !== '') {
            $header = $page->header();
            $header->ai_summary = $summary;
            $page->header($header);
        }
    }
}

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

Работа с AI Translate¶

Выберите provider: ai-pro:<name> в AI Translate, чтобы повторно использовать учётные данные, кэширование и фоновые задачи AI Pro. Так у редакторов будет одна централизованная конфигурация — и при переводе контента, и при создании сводок.

Решение проблем¶

Кнопка ассистента отсутствует → Убедитесь, что AI Pro включён, а тема админки обновлена. Очистите кэш командой bin/grav clear-cache.
Проверка провайдера не проходит → Ещё раз проверьте ключи API, сетевые межсетевые экраны и доступность выбранной модели для вашей учётной записи.
Фоновые задачи не выполняются → Проверьте Grav Scheduler или задания cron, если вы выносите обработку за пределы работы в реальном времени.
Ошибки ограничения частоты запросов или квоты → Используйте параметры кэширования и разбиения на части AI Pro, чтобы сократить дублирующиеся вызовы, или переключитесь на провайдера с большей пропускной способностью.

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