OpenAI SDK

Официальные OpenAI SDK для Python и TypeScript поддерживают собственный Base URL. Указав https://api.agtcloud.cn/v1, можно теми же методами SDK вызывать совместимые интерфейсы Chat Completions и Responses в AGTCloud.

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

Chat или Responses

Оба интерфейса используют один ключ API AGTCloud, но поддержка моделей может различаться. Подтвердите протоколы модели в каталоге моделей и замените MODEL_ID полным ID модели.

Подготовка

Перед началом убедитесь, что вы:

• Создали ключ API AGTCloud на странице API Keys;
• Подготовили ID модели с поддержкой Chat Completions или Responses;
• Используете доверенную серверную среду Python 3.10+ или Node.js 22+;
• Включили файл блокировки зависимостей и не допускаете неконтролируемого автоматического обновления SDK в рабочей среде.

Требования к среде меняются с версией SDK. Перед обновлением проверьте текущую официальную поддержку и среду развёртывания проекта.

Установка SDK

python -m pip install openai

После установки зафиксируйте фактически разрешённую версию SDK в файле блокировки проекта. При обновлении заново проверьте инициализацию клиента, типы ответа и обработку Streaming.

Настройка ключа API

Рекомендуется серверная переменная окружения для ключа API. Настройки ниже — безопасные примеры с заполнителями; при развёртывании можно использовать сервис управления секретами облачной платформы.

export AGTCLOUD_API_KEY="your-api-key"

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

В Base URL клиента обязательно укажите https://api.agtcloud.cn/v1. Не используйте только API Origin и не добавляйте /chat/completions или /responses: SDK построит путь по вызываемому методу.

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AGTCLOUD_API_KEY"],
    base_url="https://api.agtcloud.cn/v1",
)

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

Responses принимает текст или Typed Items в input; успешный ответ содержит состояние, Output Items и использование токенов. SDK предоставляет output_text для объединения текстового вывода.

response = client.responses.create(
    model="MODEL_ID",
    instructions="Отвечайте кратко и точно на русском языке.",
    input="В трёх пунктах объясните, какие задачи решает сервис агрегации API.",
)

print(response.output_text)

output_text подходит для обычного текста. Для вызовов функций, результатов поиска, элементов рассуждений и других типов последовательно обходите response.output, а не сохраняйте только Message. Полная структура описана в OpenAI Responses Reference.

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

Chat Completions использует упорядоченный массив messages. Обычный текст обычно находится в Assistant Message первого Choice.

completion = client.chat.completions.create(
    model="MODEL_ID",
    messages=[
        {
            "role": "developer",
            "content": "Отвечайте кратко и точно на русском языке.",
        },
        {
            "role": "user",
            "content": "В трёх пунктах объясните, какие задачи решает сервис агрегации API.",
        },
    ],
)

print(completion.choices[0].message.content)

Если модель возвращает вызовы инструментов, message.content может быть пустым: проверяйте message.tool_calls. Поля описаны в Chat Completions Reference.

Получение потокового вывода

OpenAI SDK предоставляет SSE как итерируемый поток событий. События Responses имеют явный type; пример ниже печатает только текстовые приращения, а приложение также должно обрабатывать завершение, ошибки и прерывания.

stream = client.responses.create(
    model="MODEL_ID",
    input="Представьтесь в одном предложении.",
    stream=True,
)

for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)

Продолжение с состоянием (при поддержке платформы)

Если модель, аккаунт и вышестоящий канал поддерживают сохранение и продолжение ответов, сохраните ответ первого шага и передайте его ID в следующем запросе как previous_response_id:

first = client.responses.create(
    model="MODEL_ID",
    store=True,
    input="Запомните кодовое имя проекта: Aurora.",
)

second = client.responses.create(
    model="MODEL_ID",
    previous_response_id=first.id,
    input="Какое кодовое имя у проекта?",
)

print(second.output_text)

При использовании previous_response_id прежние instructions не становятся инструкциями нового шага автоматически. Повторно передавайте ограничения поведения, которые должны продолжать действовать.

Если цепочка вызова не поддерживает хранение и продолжение ответов, храните историю в приложении и передавайте нужные Input и Output Items в следующем input. Полная история требует не только текста, но и связей сообщений, рассуждений и инструментов, необходимых приложению.

Тайм-ауты, повторы и ошибки

OpenAI SDK преобразует HTTP-ошибки в исключения соответствующих типов и ограниченно повторяет некоторые ошибки соединения, тайм-ауты, ограничения частоты и серверные ошибки. В рабочей среде явно задавайте тайм-ауты и предел повторов по типу запроса, чтобы избежать долгого ожидания и повторного расхода.

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

Итоговая проверка

• Base URL клиента равен https://api.agtcloud.cn/v1, без повторного /v1 и без конкретного пути эндпоинта.
• Ключ API читается из доверенной серверной среды и не попадает во фронтенд или контроль версий.
• MODEL_ID заменён моделью, видимой текущему ключу API и поддерживающей выбранный интерфейс.
• Обычный запрос корректно читает текст, состояние и использование.
• Код Streaming различает текстовые приращения, события завершения и ошибки.
• Запросы с инструментами или мультимодальностью отправляются только моделям с подтверждённой поддержкой этих возможностей.

Для системной замены настроек поставщика в существующем проекте прочитайте Миграция SDK поставщиков; для перехода структуры Chat на Responses — Chat → Responses.