YandexGPT PHP SDK

🌐 Язык: Русский | English

🔗 GitHub Repository: https://github.com/tigusigalpa/yandexgpt-php

Комплексная PHP-библиотека для взаимодействия с YandexGPT API, включающая интеграцию с Laravel. Библиотека обеспечивает простой и понятный интерфейс для работы с искусственным интеллектом Yandex Cloud, в том числе с возможностями YandexART и моделью Alice AI.

🚀 Основные функции

• 🔌 Легкое подключение к YandexGPT API
• 🔨 Интеграция с YandexART
• 🤖 Поддержка модели Alice AI с контекстом 32K токенов
• 🔐 Автоматизированная работа с OAuth и IAM токенами через пакет yandex-cloud-client-php
• 🎯 Совместимость со всеми моделями YandexGPT
• 🛠 Бесшовная интеграция с Laravel (Service Provider, Facades, настройки)
• 📝 Работа с диалоговыми и одиночными запросами
• ⚡ Автоматическое продление токенов
• 🧪 Тестовое покрытие
• 📚 Развернутая документация

📦 Установка

Установка через Packagist (предпочтительный способ)

Добавьте библиотеку с помощью Composer:

Библиотека автоматически установит зависимость

Разработка в локальной среде

Для локальной разработки или тестирования пакета:

Вариант 1: Использование локального репозитория

1. Скопируйте или клонируйте библиотеку в директорию проекта:

2. Внесите изменения в composer.json вашего проекта:

3. Выполните установку зависимостей:

Способ 2: Через симлинки

1. Создайте симлинк в vendor:

Способ 3: Через VCS репозиторий

Интеграция с Laravel

Библиотека автоматически подключается в Laravel через механизм автообнаружения. Опубликуйте файл настроек:

⚙️ Конфигурация

1. Как получить OAuth токен

📚 Документация: OAuth-токен

Воспользуйтесь ссылкой для генерации OAuth токена:

https://oauth.yandex.ru/authorize?response_type=token&client_id=1a6990aa636648e9b2ef855fa7bec2fb

2. Конфигурация переменных окружения

Внесите следующие параметры в

3. Настройка Yandex Cloud

Для использования YandexGPT API требуется выполнить ряд действий в Yandex Cloud. Большая часть процесса автоматизирована SDK, однако полезно понимать общую логику:

3.1. Получение IAM токена

📚 **Документация: ** Получение IAM-токена для аккаунта на Яндексе

SDK автоматически генерирует IAM токен на основе OAuth токена. Срок действия токена составляет 12 часов, после чего происходит автоматическое продление.

Генерация через SDK:

Автоматизированное управление токенами в YandexGPTClient:

Прямой запрос к API:

3.2. Получение Cloud ID

Документация: Получение списка ресурсов Cloud

Через SDK:

Через Yandex Cloud CLI:

Через веб-консоль: Yandex Cloud Console → выберите облако → скопируйте ID

3.3. Получение Folder ID

Документация: Получение списка ресурсов Folder в указанном облаке

Через SDK:

Через Yandex Cloud CLI:

Создание каталога

📚 Документация: Создание каталога

3.4. Назначение ролей на каталог или облако

📚 Документация:

Аутентификация в API Yandex AI Studio

Управление доступом в Yandex AI Studio

Назначить роль на каталог или облако

Назначение роли на облако

Объект Subject для облака

Назначение роли на каталог

Объект Subject для каталога

Пошаговые инструкции для Identity and Access Management

UserAccount API

Identity and Access Management API, REST: YandexPassportUserAccount.GetByLogin

Через SDK:

Через Yandex Cloud CLI:

Через веб-консоль:

1. Откройте Yandex Cloud Console
2. Выберите каталог
3. Перейдите в раздел "Права доступа"
4. Нажмите "Назначить роли"
5. Выберите пользователя и роль
   ai.languageModels.user

3.5. Полный пример настройки

3.6. Полезные ссылки

• 📖 Быстрый старт YandexGPT
• 🔑 Аутентификация в API
• 🏗️ Управление ресурсами
• 🤖 API Foundation Models
• 💰 Тарифы YandexGPT

💡 Примеры использования

Простой пример (вне Laravel)

Работа в Laravel

Подключение через Service Provider

Библиотека автоматически интегрируется в Laravel посредством Service Provider, обеспечивающего следующие возможности:

Авторегистрация в системе:

Функционал Service Provider:

1. Регистрация компонентов (метод
   register()
   ):
   • Слияние конфигурации библиотеки с настройками приложения
   • Регистрация
     YandexGPTClient
     как singleton в контейнере
   • Формирование псевдонима для удобного внедрения

2. Инициализация компонентов (метод
   boot()
   ):
   • Публикация файла конфигурации для персонализации

3. Декларация сервисов (метод
   provides()
   ):
   • Определяет перечень сервисов, предоставляемых провайдером

Публикация файла настроек:

После выполнения команды файл настроек будет доступен по пути

Использование фасада

Внедрение зависимостей (Dependency Injection)

Диалоговые сценарии

Управление ресурсами Yandex Cloud

Управление пользователями и ролями (IAM)

SDK предоставляет полный набор функций для работы с Identity and Access Management (IAM):

Получение информации о пользователях

Назначение ролей на каталог

Назначение ролей на облако

Полный пример: получение пользователя и назначение роли

🤖 Доступные модели

📚 Полный список доступных моделей: Модели генерации в Yandex AI Studio

🔧 Параметры генерации

⚠️ Обработка ошибок

🛠️ Конфигурация

Полный конфигурационный файл

📚 Примеры использования

Чат-бот для Laravel

Генерация контента

🧪 Тестирование

Запуск тестов пакета

Тестирование в Laravel проекте

1. Создайте тестовый контроллер или используйте существующий:

2. Добавьте маршрут для тестирования:

3. Протестируйте через браузер или API клиент:

❓ Troubleshooting и FAQ

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

Q: Как получить OAuth токен?

A: Перейдите по ссылке: https://oauth.yandex.ru/authorize?response_type=token&client_id=1a6990aa636648e9b2ef855fa7bec2fb

После авторизации скопируйте токен из URL адреса.

Q: Как получить Folder ID?

A: Используйте SDK для получения списка каталогов:

Q: Почему возникает ошибка "OAuth токен не может быть пустым"?

A: Убедитесь, что в

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

#### Ошибка: "Class 'Tigusigalpa\YandexGPT\YandexGPTClient' not found"

**Решение:**

1. Убедитесь, что пакет установлен: `composer show tigusigalpa/yandexgpt-php`
2. Очистите автозагрузчик: `composer dump-autoload`
3. Проверьте, что пакет добавлен в `composer.json`

#### Ошибка: "YandexGPT OAuth токен не настроен"

**Решение:**

1. Добавьте в `.env` файл:

```env
YANDEX_GPT_OAUTH_TOKEN=your_actual_token_here
YANDEX_GPT_FOLDER_ID=your_folder_id_here

2. Очистите кеш конфигурации:
   php artisan config:clear

Ошибка: "Ошибка API YandexGPT (код 401): Unauthorized"

Решение:

1. Проверьте правильность OAuth токена
2. Убедитесь, что токен не истек (OAuth токены действуют 1 год)
3. Проверьте права доступа к каталогу

Ошибка: "Ошибка API YandexGPT (код 403): Forbidden"

Решение:

1. Убедитесь, что у пользователя есть роль
   ai.languageModels.user
2. Проверьте правильность Folder ID
3. Убедитесь, что каталог существует и доступен

Ошибка: "Connection timeout"

Решение:

1. Увеличьте timeout в конфигурации:

2. Проверьте интернет-соединение
3. Убедитесь, что нет блокировки файрволом

Отладка

Включение детального логирования

Проверка конфигурации

🖼️ Генерация изображений (YandexART)

📚 Ресурсы

• 📖 Документация: https://yandex.cloud/ru/docs/ai-studio/quickstart/yandexart
• 🛠️ Документация по отправке запроса
• 🎨 Сайт: https://ya.ru/ai/art

SDK поддерживает генерацию изображений с помощью YandexART. Доступны три метода:

• 📨 generateImageAsync — отправка запроса на генерацию и получение объекта операции
• 🔎 getOperation — проверка статуса операции по её ID
• ⏳ generateImage — синхронная обёртка с ожиданием результата

Требования доступа:

• Необходимо назначить роль
  ai.imageGeneration.user
  на каталог (Folder), где будет выполняться генерация изображений
• Для работы текстовых моделей также требуется роль
  ai.languageModels.user

Модель YandexART:

• Используется модель
  yandex-art/latest
  с URI вида
  art://<folder_id>/yandex-art/latest

Примеры использования

1. Базовая асинхронная генерация:

2. Синхронная генерация с ожиданием результата:

Пример сгенерированного изображения Омска

3. Использование через Laravel Facade:

4. Prompt chaining (YandexGPT → YandexART):

Формат сообщений для YandexART

Метод принимает либо строку (один запрос), либо массив сообщений. Каждое сообщение может быть:

• строкой: 'описание сцены'
• массивом: ['text' => 'описание', 'weight' => 1]

Пример массива сообщений:

Параметры generationOptions

Параметр generationOptions (необязателен) позволяет задать настройки генерации. Список доступных опций зависит от API YandexART. Примеры опций:

Обработка ошибок

Методы могут выбрасывать исключения ApiException и AuthenticationException. Проверяйте поле error в ответе операции и наличие поля response.image при успешном завершении.

✅ Требования

• PHP 8.0 или выше
• Laravel 8.0 или выше (для интеграции с Laravel)
• Guzzle HTTP 7.0 или выше

📄 Лицензия

Этот пакет распространяется под лицензией MIT. Подробности в файле LICENSE.

🤝 Поддержка

• Документация YandexGPT API
• Quickstart
• Список моделей

🧑‍💻 Участие в разработке

Мы приветствуем участие в разработке! Пожалуйста, ознакомьтесь с руководством по участию.

🛡️ Безопасность

Если вы обнаружили уязвимость в безопасности, пожалуйста, отправьте email на sovletig@gmail.com вместо создания issue.