tigusigalpa/yandexgpt-php

PHP SDK для работы с YandexGPT API с поддержкой Laravel

v1.0.0 2025-09-28 05:30 UTC

Requires

• php: ^8.0
• guzzlehttp/guzzle: ^7.0
• illuminate/support: ^8.0|^9.0|^10.0|^11.0

Requires (Dev)

• mockery/mockery: ^1.4
• orchestra/testbench: ^6.0|^7.0|^8.0|^9.0
• phpunit/phpunit: ^9.0|^10.0

MIT

• Igor Sazonov

• php
• api
• sdk
• laravel
• yandex
• ai
• gpt

README

Полнофункциональный PHP SDK для работы с YandexGPT API с поддержкой Laravel. Пакет предоставляет удобный интерфейс для интеграции с AI моделями Yandex Cloud.

🚀 Возможности

• Простая интеграция с YandexGPT API
• 🔐 Автоматическое управление OAuth и IAM токенами
• 🎯 Поддержка всех доступных моделей YandexGPT
• 🛠 Полная интеграция с Laravel (Service Provider, Facades, конфигурация)
• 📝 Поддержка диалогов и одиночных запросов
• ⚡ Автоматическое обновление токенов
• 🧪 Покрытие тестами
• 📚 Подробная документация

📦 Установка

Установка из Packagist (рекомендуется)

Установите пакет через Composer:

composer require tigusigalpa/yandexgpt-php

Локальная разработка

Если вы хотите использовать пакет локально для разработки или тестирования:

Способ 1: Через локальный репозиторий

1. Клонируйте или поместите пакет в папку проекта:

# В корне вашего Laravel проекта
mkdir -p packages
cd packages
git clone https://github.com/tigusigalpa/yandexgpt-php.git
# или скопируйте папку с пакетом в packages/yandexgpt-php

1. Добавьте локальный репозиторий в composer.json вашего проекта:

{
    "repositories": [
        {
            "type": "path",
            "url": "./packages/yandexgpt-php"
        }
    ],
    "require": {
        "tigusigalpa/yandexgpt-php": "@dev"
    }
}

1. Установите зависимости:

composer install
# или если пакет уже был установлен
composer update tigusigalpa/yandexgpt-php

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

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

# Удалите существующий пакет (если есть)
rm -rf vendor/tigusigalpa/yandexgpt-php

# Создайте симлинк
ln -s ../../packages/yandexgpt-php vendor/tigusigalpa/yandexgpt-php

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

{
    "repositories": [
        {
            "type": "vcs",
            "url": "https://github.com/tigusigalpa/yandexgpt-php.git"
        }
    ],
    "require": {
        "tigusigalpa/yandexgpt-php": "dev-main"
    }
}

Для Laravel

Пакет автоматически регистрируется в Laravel благодаря автодискавери. Опубликуйте конфигурационный файл:

php artisan vendor:publish --tag=yandexgpt-config

⚙️ Настройка

1. Получение OAuth токена

Перейдите по ссылке для получения OAuth токена:

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

2. Настройка окружения

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

YANDEX_GPT_OAUTH_TOKEN=your_oauth_token_here
# получите folder_id через специальный запрос
YANDEX_GPT_FOLDER_ID=your_folder_id_here
YANDEX_GPT_DEFAULT_MODEL=yandexgpt-lite
YANDEX_GPT_TEMPERATURE=0.6
YANDEX_GPT_MAX_TOKENS=2000

3. Подготовка Yandex Cloud

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

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

IAM токен получается автоматически через SDK с помощью OAuth токена. Токен действует 12 часов и обновляется автоматически.

Получение через SDK:

use Tigusigalpa\YandexGPT\Auth\OAuthTokenManager;

// Создание менеджера аутентификации
$authManager = new OAuthTokenManager('your_oauth_token');

// Получение IAM токена
$iamToken = $authManager->getIamToken();

echo "IAM Token: " . $iamToken . "\n";

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

use Tigusigalpa\YandexGPT\YandexGPTClient;

// Клиент автоматически получает и обновляет IAM токены
$client = new YandexGPTClient('your_oauth_token', 'your_folder_id');

// Получение менеджера аутентификации для ручного управления
$authManager = $client->getAuthManager();
$iamToken = $authManager->getIamToken();

Ручное получение через API:

curl -d "{\"yandexPassportOauthToken\":\"YOUR_OAUTH_TOKEN\"}" \
  "https://iam.api.cloud.yandex.net/iam/v1/tokens"

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

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

Через SDK:

use Tigusigalpa\YandexGPT\Auth\OAuthTokenManager;

$authManager = new OAuthTokenManager('your_oauth_token');

// Laravel:
// use Tigusigalpa\YandexGPT\Laravel\Facades\YandexGPT;
// $authManager = YandexGPT::getAuthManager();
$clouds = $authManager->listClouds();

foreach ($clouds as $cloud) {
    echo "Cloud ID: " . $cloud['id'] . "\n";
    echo "Name: " . $cloud['name'] . "\n";
}

Через Yandex Cloud CLI:

yc resource-manager cloud list

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

📚 **Документация: ** Получение идентификатора облака

3.3. Создание каталога (Folder)

Через SDK:

$authManager = new OAuthTokenManager('your_oauth_token');
// Laravel:
// use Tigusigalpa\YandexGPT\Laravel\Facades\YandexGPT;
// $authManager = YandexGPT::getAuthManager();

// Создание каталога
$folder = $authManager->createFolder('cloud_id', 'my-ai-folder', 'Каталог для AI проектов');
$folderId = $folder['id'];

// Или получение существующих каталогов
$folders = $authManager->listFolders('cloud_id');
foreach ($folders as $folder) {
    echo "Folder ID: " . $folder['id'] . "\n";
    echo "Name: " . $folder['name'] . "\n";
}

Через Yandex Cloud CLI:

# Создание каталога
yc resource-manager folder create --name my-ai-folder --cloud-id YOUR_CLOUD_ID

# Список каталогов
yc resource-manager folder list --cloud-id YOUR_CLOUD_ID

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

3.4. Назначение роли ai.languageModels.user

Через SDK:

$authManager = new OAuthTokenManager('your_oauth_token');

// Laravel:
// use Tigusigalpa\YandexGPT\Laravel\Facades\YandexGPT;
// $authManager = YandexGPT::getAuthManager();

// Назначение роли пользователю
$authManager->assignRole(
    'folder_id',
    'userAccount', // тип субъекта
    'user_id',     // ID пользователя
    'ai.languageModels.user'
);

Через Yandex Cloud CLI:

# Назначение роли для пользователя
yc resource-manager folder add-access-binding \
  --id YOUR_FOLDER_ID \
  --role ai.languageModels.user \
  --user-account-id YOUR_USER_ID

# Назначение роли для сервисного аккаунта
yc resource-manager folder add-access-binding \
  --id YOUR_FOLDER_ID \
  --role ai.languageModels.user \
  --service-account-id YOUR_SERVICE_ACCOUNT_ID

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

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

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

• Назначение ролей
• Роли для Yandex Foundation Models

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

<?php

use Tigusigalpa\YandexGPT\Auth\OAuthTokenManager;
use Tigusigalpa\YandexGPT\YandexGPTClient;

// 1. Инициализация менеджера аутентификации
$authManager = new OAuthTokenManager('your_oauth_token');

// Laravel:
// use Tigusigalpa\YandexGPT\Laravel\Facades\YandexGPT;
// $authManager = YandexGPT::getAuthManager();

// 2. Получение списка облаков
$clouds = $authManager->listClouds();
$cloudId = $clouds[0]['id']; // Берем первое облако

// 3. Создание каталога (если нужно)
$folder = $authManager->createFolder($cloudId, 'ai-projects', 'Каталог для AI');
$folderId = $folder['id'];

// 4. Назначение роли (если нужно)
$authManager->assignRole(
    $folderId,
    'userAccount',
    'your_user_id',
    'ai.languageModels.user'
);

// 5. Использование клиента
$client = new YandexGPTClient('your_oauth_token', $folderId);
$response = $client->generateText('Привет, как дела?');

echo $response['result']['alternatives'][0]['message']['text'];

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

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

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

Базовое использование (без Laravel)

<?php

require_once 'vendor/autoload.php';

use Tigusigalpa\YandexGPT\YandexGPTClient;
use Tigusigalpa\YandexGPT\Models\YandexGPTModel;

// Создание клиента
$client = new YandexGPTClient('your_oauth_token', 'your_folder_id');

// Простой запрос
$response = $client->generateText(
    'Расскажи о преимуществах PHP',
    YandexGPTModel::YANDEX_GPT_LITE
);

echo $response['result']['alternatives'][0]['message']['text'];

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

Интеграция через Service Provider

Пакет автоматически интегрируется с Laravel через Service Provider, который выполняет следующие функции:

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

// В composer.json пакета указано:
"extra": {
    "laravel": {
        "providers": [
            "Tigusigalpa\\YandexGPT\\Laravel\\YandexGPTServiceProvider"
        ],
        "aliases": {
            "YandexGPT": "Tigusigalpa\\YandexGPT\\Laravel\\Facades\\YandexGPT"
        }
    }
}

Что делает Service Provider:

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

public function register()
{
    // Объединение конфигурации
    $this->mergeConfigFrom(
        __DIR__ . '/../../config/yandexgpt.php',
        'yandexgpt'
    );

    // Регистрация singleton
    $this->app->singleton('yandexgpt', function ($app) {
        $config = $app['config']['yandexgpt'];

        return new YandexGPTClient(
            $config['oauth_token'],
            $config['folder_id']
        );
    });

    // Создание алиаса
    $this->app->alias('yandexgpt', YandexGPTClient::class);
}

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

public function boot()
{
    if ($this->app->runningInConsole()) {
        $this->publishes([
            __DIR__ . '/../../config/yandexgpt.php' => config_path('yandexgpt.php'),
        ], 'yandexgpt-config');
    }
}

1. Определение предоставляемых сервисов (provides() метод):
   • Указывает какие сервисы предоставляет провайдер

public function provides()
{
    return ['yandexgpt', YandexGPTClient::class];
}

Публикация конфигурации:

php artisan vendor:publish --tag=yandexgpt-config

После публикации файл конфигурации будет доступен в config/yandexgpt.php для настройки.

Через фасад

<?php

use Tigusigalpa\YandexGPT\Laravel\Facades\YandexGPT;
use Tigusigalpa\YandexGPT\Models\YandexGPTModel;

// Простой запрос
$response = YandexGPT::generateText('Привет, как дела?');

// С указанием модели и параметров
$response = YandexGPT::generateText(
    'Напиши стихотворение о программировании',
    YandexGPTModel::YANDEX_GPT_PRO,
    [
        'completionOptions' => [
            'temperature' => 0.8,
            'maxTokens' => 1000
        ]
    ]
);

echo $response['result']['alternatives'][0]['message']['text'];

Через внедрение зависимостей

<?php

use Tigusigalpa\YandexGPT\YandexGPTClient;

class ChatController extends Controller
{
    public function __construct(private YandexGPTClient $yandexGPT)
    {
    }

    public function generateResponse(Request $request)
    {
        $response = $this->yandexGPT->generateText($request->input('message'));
        
        return response()->json([
            'response' => $response['result']['alternatives'][0]['message']['text']
        ]);
    }
}

Работа с диалогами

use Tigusigalpa\YandexGPT\Laravel\Facades\YandexGPT;

$messages = [
    [
        'role' => 'system',
        'text' => 'Ты полезный помощник-программист'
    ],
    [
        'role' => 'user',
        'text' => 'Как создать REST API на Laravel?'
    ],
    [
        'role' => 'assistant',
        'text' => 'Для создания REST API в Laravel используйте команду php artisan make:controller...'
    ],
    [
        'role' => 'user',
        'text' => 'А как добавить валидацию?'
    ]
];

$response = YandexGPT::generateFromMessages($messages);

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

<?php

use Tigusigalpa\YandexGPT\YandexGPTClient;

$client = new YandexGPTClient('oauth_token', 'folder_id');
$authManager = $client->getAuthManager();

// Получение IAM токена
$iamToken = $authManager->getIamToken();

// Получение списка облаков
$clouds = $authManager->getClouds($iamToken);

// Создание каталога
$folder = $authManager->createFolder(
    $iamToken,
    'cloud_id',
    'my-yandexgpt-folder',
    'Каталог для работы с YandexGPT'
);

// Назначение прав
$authManager->assignRole(
    $iamToken,
    $folder['id'],
    'user_account_id',
    'ai.languageModels.user'
);

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

Модель	Описание	Константа
yandexgpt-lite	Быстрая и экономичная модель	YandexGPTModel::YANDEX_GPT_LITE
yandexgpt	Стандартная модель	YandexGPTModel::YANDEX_GPT
yandexgpt-pro	Продвинутая модель	YandexGPTModel::YANDEX_GPT_PRO
yandexgpt-32k	Модель с расширенным контекстом	YandexGPTModel::YANDEX_GPT_32K

// Получение всех доступных моделей
$models = YandexGPT::getAvailableModels();

// Получение описаний моделей
$descriptions = YandexGPT::getModelDescriptions();

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

$options = [
    'completionOptions' => [
        'stream' => false,           // Потоковая передача (пока не поддерживается)
        'temperature' => 0.6,        // Креативность (0.0 - 1.0)
        'maxTokens' => 2000         // Максимальное количество токенов
    ]
];

$response = YandexGPT::generateText('Ваш запрос', 'yandexgpt-lite', $options);

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

<?php

use Tigusigalpa\YandexGPT\Exceptions\AuthenticationException;
use Tigusigalpa\YandexGPT\Exceptions\ApiException;
use Tigusigalpa\YandexGPT\Laravel\Facades\YandexGPT;

try {
    $response = YandexGPT::generateText('Привет!');
} catch (AuthenticationException $e) {
    // Ошибки аутентификации (неверный токен, права доступа)
    Log::error('YandexGPT Auth Error: ' . $e->getMessage());
} catch (ApiException $e) {
    // Ошибки API (неверные параметры, лимиты)
    Log::error('YandexGPT API Error: ' . $e->getMessage());
} catch (Exception $e) {
    // Другие ошибки
    Log::error('YandexGPT Error: ' . $e->getMessage());
}

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

Полный конфигурационный файл config/yandexgpt.php:

<?php

return [
    // OAuth токен
    'oauth_token' => env('YANDEX_GPT_OAUTH_TOKEN'),
    
    // ID каталога
    'folder_id' => env('YANDEX_GPT_FOLDER_ID'),
    
    // Модель по умолчанию
    'default_model' => env('YANDEX_GPT_DEFAULT_MODEL', 'yandexgpt-lite'),
    
    // Параметры по умолчанию
    'default_options' => [
        'temperature' => (float) env('YANDEX_GPT_TEMPERATURE', 0.6),
        'maxTokens' => (int) env('YANDEX_GPT_MAX_TOKENS', 2000),
        'stream' => false,
    ],
    
    // Настройки HTTP клиента
    'http_options' => [
        'timeout' => (int) env('YANDEX_GPT_TIMEOUT', 30),
        'connect_timeout' => (int) env('YANDEX_GPT_CONNECT_TIMEOUT', 10),
    ],
];

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

Чат-бот для Laravel

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Tigusigalpa\YandexGPT\Laravel\Facades\YandexGPT;
use Tigusigalpa\YandexGPT\Models\YandexGPTModel;

class ChatBotController extends Controller
{
    public function chat(Request $request)
    {
        $request->validate([
            'message' => 'required|string|max:1000',
            'history' => 'array'
        ]);

        $messages = $request->input('history', []);
        $messages[] = [
            'role' => 'user',
            'text' => $request->input('message')
        ];

        try {
            $response = YandexGPT::generateFromMessages(
                $messages,
                YandexGPTModel::YANDEX_GPT_LITE
            );

            $botResponse = $response['result']['alternatives'][0]['message']['text'];
            
            $messages[] = [
                'role' => 'assistant',
                'text' => $botResponse
            ];

            return response()->json([
                'success' => true,
                'response' => $botResponse,
                'history' => $messages
            ]);

        } catch (\Exception $e) {
            return response()->json([
                'success' => false,
                'error' => 'Произошла ошибка при генерации ответа'
            ], 500);
        }
    }
}

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

<?php

use Tigusigalpa\YandexGPT\Laravel\Facades\YandexGPT;
use Tigusigalpa\YandexGPT\Models\YandexGPTModel;

class ContentGenerator
{
    public function generateArticle(string $topic, int $length = 1000): string
    {
        $prompt = "Напиши статью на тему '{$topic}'. Длина статьи должна быть примерно {$length} слов. Включи введение, основную часть и заключение.";

        $response = YandexGPT::generateText(
            $prompt,
            YandexGPTModel::YANDEX_GPT_PRO,
            [
                'completionOptions' => [
                    'temperature' => 0.7,
                    'maxTokens' => $length * 2 // Примерно 2 токена на слово
                ]
            ]
        );

        return $response['result']['alternatives'][0]['message']['text'];
    }

    public function generateSEODescription(string $content): string
    {
        $prompt = "Создай SEO-описание (meta description) для следующего контента. Описание должно быть до 160 символов:\n\n{$content}";

        $response = YandexGPT::generateText($prompt, YandexGPTModel::YANDEX_GPT_LITE);

        return $response['result']['alternatives'][0]['message']['text'];
    }
}

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

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

# Переход в директорию пакета
cd packages/yandexgpt-php

# Установка зависимостей для разработки
composer install

# Запуск тестов
composer test

# Запуск тестов с покрытием
composer test-coverage

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

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

<?php

namespace App\Http\Controllers;

use Tigusigalpa\YandexGPT\YandexGPTClient;
use Tigusigalpa\YandexGPT\Models\YandexGPTModel;
use Tigusigalpa\YandexGPT\Exceptions\AuthenticationException;
use Tigusigalpa\YandexGPT\Exceptions\ApiException;

class TestYandexGPTController extends Controller
{
    public function test()
    {
        try {
            $client = new YandexGPTClient(
                env('YANDEX_GPT_OAUTH_TOKEN'),
                env('YANDEX_GPT_FOLDER_ID')
            );

            $response = $client->generateText(
                'Привет! Это тест YandexGPT SDK',
                YandexGPTModel::YANDEX_GPT_LITE
            );

            return response()->json([
                'success' => true,
                'response' => $response['result']['alternatives'][0]['message']['text']
            ]);

        } catch (AuthenticationException $e) {
            return response()->json([
                'success' => false,
                'error' => 'Authentication error: ' . $e->getMessage()
            ], 401);
        } catch (ApiException $e) {
            return response()->json([
                'success' => false,
                'error' => 'API error: ' . $e->getMessage()
            ], 400);
        }
    }
}

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

// routes/web.php
Route::get('/test-yandexgpt', [TestYandexGPTController::class, 'test']);

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

curl http://your-domain.com/test-yandexgpt

❓ Troubleshooting и FAQ

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

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

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

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

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

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

$authManager = new OAuthTokenManager('your_oauth_token');

// Laravel:
// use Tigusigalpa\YandexGPT\Laravel\Facades\YandexGPT;
// $authManager = YandexGPT::getAuthManager();
$clouds = $authManager->listClouds();
$folders = $authManager->listFolders($clouds[0]['id']);

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

A: Убедитесь, что в .env файле правильно задан YANDEX_GPT_OAUTH_TOKEN без пробелов и кавычек.

Q: Как работать с большими текстами?

A: Используйте модель yandexgpt-32k для работы с контекстом до 32K токенов:

$response = $client->generateText(
    $longText,
    YandexGPTModel::YANDEX_GPT_32K
);

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

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

Решение:

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

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

Решение:

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

YANDEX_GPT_OAUTH_TOKEN=your_actual_token_here
YANDEX_GPT_FOLDER_ID=your_folder_id_here

1. Очистите кеш конфигурации: 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 в конфигурации:

// config/yandexgpt.php
'http_options' => [
    'timeout' => 60,
    'connect_timeout' => 30,
],

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

Отладка

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

use Tigusigalpa\YandexGPT\YandexGPTClient;
use GuzzleHttp\Client;
use GuzzleHttp\HandlerStack;
use GuzzleHttp\Middleware;

// Создание HTTP клиента с логированием
$stack = HandlerStack::create();
$stack->push(Middleware::log(
    app('log')->getLogger(),
    new \GuzzleHttp\MessageFormatter('{method} {uri} HTTP/{version} {req_body} RESPONSE: {code} - {res_body}')
));

$httpClient = new Client(['handler' => $stack]);
$client = new YandexGPTClient('oauth_token', 'folder_id', $httpClient);

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

// Проверка всех настроек
$config = config('yandexgpt');
dd($config);

// Проверка переменных окружения
dd([
    'oauth_token' => env('YANDEX_GPT_OAUTH_TOKEN'),
    'folder_id' => env('YANDEX_GPT_FOLDER_ID'),
]);

✅ Требования

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

📄 Лицензия

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

🤝 Поддержка

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

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

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

📜 Changelog

Все изменения документируются в CHANGELOG.md.

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

Если вы обнаружили уязвимость в безопасности, пожалуйста, отправьте email на [e-mail] вместо создания issue.