AI Client в WordPress 7.0: как добавить ИИ в плагин без привязки к провайдеру

WordPress 7.0 получил встроенный AI Client — единый PHP-интерфейс для обращения к генеративным моделям. Теперь разработчику плагина не обязательно отдельно интегрировать OpenAI, Anthropic или Google, хранить их ключи в собственных настройках и переписывать код при смене сервиса. Плагин описывает задачу, а WordPress выбирает подходящую модель из настроенных владельцем сайта.

Разберём, как устроена новая система, что требуется для запуска и как собрать небольшой плагин, который создаёт черновик описания товара. Пример рассчитан на WordPress 7.0.1 и новее.

Что изменилось в WordPress 7.0

Раньше типичная AI-интеграция (подключение функций искусственного интеллекта) начиналась с SDK конкретного поставщика. Плагин добавлял страницу для API-ключа, самостоятельно отправлял HTTP-запросы, разбирал ответы и обрабатывал ошибки. При переходе на другую модель значительную часть интеграции приходилось менять.

В WordPress 7.0 эта работа разделена на три уровня:

1. Плагин с бизнес-функцией формирует запрос через wp_ai_client_prompt().

2. AI Client определяет требования и выбирает совместимую модель.

3. Плагин провайдера связывается с конкретным внешним сервисом.

API provider-agnostic (не зависящий от конкретного поставщика): один и тот же код может работать с поддерживаемыми моделями разных компаний. Владелец сайта управляет подключениями централизованно, а разработчик функции не получает прямой доступ к ключам.

Важно различать AI Client и AI-агента. Клиент отправляет отдельный запрос модели и возвращает результат. Агент способен выбирать инструменты и выполнять последовательность действий. Если требуется именно автономная автоматизация, полезно заранее определить права, журналы и границы доступа — подробнее об этом есть в статье об управлении и безопасности AI-агентов.

Что нужно для работы AI Client

Сам AI Client входит в ядро WordPress, однако модели в ядро не встроены. Для реального запроса нужны:

• WordPress 7.0 или новее — на момент публикации актуальна версия 7.0.1;

• активный плагин совместимого AI-провайдера;

• API-ключ этого провайдера;

• разрешённые исходящие HTTPS-запросы на сервере;

• средства на балансе или доступная квота у поставщика модели.

WordPress поддерживает официальные плагины-провайдеры для Anthropic, Google и OpenAI. Подключение настраивается в разделе «Настройки → Connectors». Ядро хранит параметры соединения и передаёт их соответствующему провайдеру, поэтому каждому AI-плагину больше не нужна собственная форма для ключа.

После настройки стоит проверить не только наличие функции wp_ai_client_prompt(), но и поддержку нужного типа генерации. Установка WordPress 7.0 сама по себе ещё не означает, что на сайте доступна подходящая модель.

Базовый запрос через wp_ai_client_prompt()

Минимальный вызов выглядит так:

$text = wp_ai_client_prompt( 'Кратко объясни, зачем WordPress-сайту объектный кеш.' )
    ->using_temperature( 0.2 )
    ->generate_text();

if ( is_wp_error( $text ) ) {
    error_log( $text->get_error_message() );
    return;
}

wp_ai_client_prompt() возвращает объект WP_AI_Client_Prompt_Builder. Это fluent interface (цепочка последовательных настроек): к запросу можно добавить системную инструкцию, ограничение числа токенов, желаемые модели, формат JSON и другие параметры. Методы генерации возвращают результат или стандартный объект WP_Error.

Предпочтение конкретной модели задаётся через using_model_preference(), но это именно пожелание, а не жёсткое требование. Плагин должен корректно работать и с другой совместимой моделью. Иначе главная польза общего слоя исчезает.

Практический пример: черновик описания товара

Ниже — минимальный плагин, который добавляет страницу «Инструменты → AI-черновик». Администратор вставляет исходные характеристики товара и получает короткое описание без HTML.

Перед экспериментом сделайте резервную копию сайта. Создайте каталог /wp-content/plugins/one-develop-ai-draft/, поместите в него файл one-develop-ai-draft.php, вставьте код и активируйте плагин на тестовом сайте.

<?php
/**
 * Plugin Name: 1develop AI Draft
 * Description: Создаёт черновик описания через AI Client WordPress 7.0.
 * Requires at least: 7.0
 * Requires PHP: 7.4
 * Version: 1.0.0
 */

if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

add_action( 'admin_menu', function () {
    add_management_page(
        'AI-черновик',
        'AI-черновик',
        'manage_options',
        'one-develop-ai-draft',
        'one_develop_ai_draft_page'
    );
} );

function one_develop_ai_draft_page(): void {
    if ( ! current_user_can( 'manage_options' ) ) {
        wp_die( esc_html__( 'Недостаточно прав.', 'one-develop-ai-draft' ) );
    }

    $source = '';
    $result = '';
    $error  = '';

    if ( isset( $_POST['one_develop_ai_submit'] ) ) {
        check_admin_referer( 'one_develop_ai_draft' );

        $source = isset( $_POST['one_develop_ai_source'] )
            ? sanitize_textarea_field( wp_unslash( $_POST['one_develop_ai_source'] ) )
            : '';

        if ( '' === $source ) {
            $error = 'Добавьте исходные характеристики товара.';
        } elseif ( ! function_exists( 'wp_ai_client_prompt' ) ) {
            $error = 'Требуется WordPress 7.0 или новее.';
        } else {
            $prompt = wp_ai_client_prompt(
                "Подготовь описание товара на русском языке до 700 знаков.\n\nДанные:\n" . $source
            )
                ->using_system_instruction(
                    'Пиши точно и нейтрально. Не выдумывай свойства, гарантии и результаты.'
                )
                ->using_temperature( 0.2 )
                ->using_max_tokens( 350 );

            if ( ! $prompt->is_supported_for_text_generation() ) {
                $error = 'На сайте не настроена модель с генерацией текста.';
            } else {
                $generated = $prompt->generate_text();

                if ( is_wp_error( $generated ) ) {
                    $error = $generated->get_error_message();
                } else {
                    $result = $generated;
                }
            }
        }
    }
    ?>
    <div class="wrap">
        <h1>AI-черновик описания</h1>

        <?php if ( $error ) : ?>
            <div class="notice notice-error"><p><?php echo esc_html( $error ); ?></p></div>
        <?php endif; ?>

        <form method="post">
            <?php wp_nonce_field( 'one_develop_ai_draft' ); ?>
            <textarea name="one_develop_ai_source" rows="10" class="large-text"
                placeholder="Название, назначение, материалы, размеры..."><?php
                echo esc_textarea( $source );
            ?></textarea>
            <?php submit_button( 'Создать черновик', 'primary', 'one_develop_ai_submit' ); ?>
        </form>

        <?php if ( $result ) : ?>
            <h2>Результат для проверки</h2>
            <textarea rows="10" class="large-text" readonly><?php
                echo esc_textarea( $result );
            ?></textarea>
        <?php endif; ?>
    </div>
    <?php
}

Пример сознательно не сохраняет результат в товар автоматически. Человек должен проверить факты, формулировки и соответствие исходным данным. Для первого теста это безопаснее, чем сразу изменять контент в базе.

Почему проверка is_supported_for_text_generation() обязательна

Метод is_supported_for_text_generation() не отправляет запрос и не расходует квоту. Он сопоставляет параметры с возможностями доступных моделей. Если провайдер отключён, ключ не настроен или модель не поддерживает нужный режим, интерфейс можно скрыть либо показать понятное уведомление.

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

Что учесть перед использованием на рабочем сайте

Данные уходят внешнему сервису

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

Генерация стоит денег и может быть ограничена

Единый API не отменяет тарифы, квоты и rate limit (ограничение частоты запросов) поставщика. Ограничьте доступ по ролям, длину входного текста и число запусков. Для публичной формы понадобятся отдельные лимиты на пользователя или IP, иначе функцию легко превратить в источник непредвиденных расходов.

Ответ нельзя считать достоверным автоматически

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

Долгий запрос не должен тормозить интерфейс

Демонстрационный плагин выполняет вызов синхронно. Для редкой ручной генерации это допустимо, но массовую обработку товаров лучше отправлять в очередь. В WooCommerce для этого подходит Action Scheduler: задача выполняется в фоне, её можно повторить после временной ошибки и не держать открытым HTTP-запрос администратора.

Нужны журналы без утечки содержимого

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

Где AI Client полезен на практике

Общий интерфейс особенно удобен для функций, где выбор конкретной модели не является частью продукта:

• подготовка черновиков описаний и метаданных;

• классификация обращений из форм;

• извлечение структурированных полей в JSON;

• краткие резюме длинных материалов;

• создание ALT-текста для изображений с обязательной проверкой;

• внутренние подсказки редактору или менеджеру магазина.

Если приложение продаёт доступ именно к возможностям определённой модели, прямой SDK всё ещё может быть оправдан. AI Client выбирает совместимый вариант и поэтому не подходит, когда бизнес-логика зависит от уникального API конкретного поставщика.

Миграция старой интеграции

Для нового плагина, рассчитанного только на WordPress 7.0+, используйте wp_ai_client_prompt() и не добавляйте старые Composer-пакеты wordpress/php-ai-client или wordpress/wp-ai-client без необходимости. Репозиторий прежнего WP AI Client уже архивирован в пользу реализации в ядре.

Если плагин поддерживает WordPress ниже 7.0, нельзя безусловно подключать прежний PHP AI Client через общий Composer autoloader: в WordPress 7.0 те же классы уже загружает ядро, возможны конфликты повторного объявления. Официальная документация рекомендует условную загрузку зависимостей для старых версий либо раздельные Composer-конфигурации.

Миграцию лучше провести поэтапно:

1. Зафиксировать существующие сценарии и форматы ответов тестами.

2. Заменить прямой вызов поставщика на wp_ai_client_prompt().

3. Добавить проверку поддержки и обработку WP_Error.

4. Убрать собственное хранение ключей после перехода на Connectors.

5. Проверить работу минимум с двумя провайдерами на тестовом сайте.

6. Перенести массовые операции в очередь и настроить лимиты.

Вывод

AI Client превращает интеграцию генеративных моделей в стандартную возможность WordPress. Разработчик получает единый PHP API и привычные WP_Error, владелец сайта — централизованный выбор провайдера и управление ключами.

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