Интеграция OpenAI SDK

Чтобы использовать пакет openai со AI Gateway, укажите базовый адрес https://route.smartaipack.ru/v1, передайте ключ из переменной окружения и выберите точный request_model_id в кабинете. Для обычного диалога подойдёт client.chat.completions.create, а текст результата находится в choices[0].message.content.

Отдельный клиент AI Gateway для этого сценария не нужен. Пакет формирует запрос и разбирает совместимый ответ, а AI Gateway принимает его, направляет выбранной модели и учитывает расход. Первый запрос с выпуском ключа разобран в быстром старте, а другие способы подключения — в обзоре интеграций.

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

Установите официальный пакет openai обычным для проекта способом:

pip install openai

или для Node.js:

npm install openai

Версия пакета должна храниться в файле зависимостей проекта. В этой инструкции она намеренно не зафиксирована: перед обновлением проверяйте используемые методы на испытательном запросе.

Что понадобится

1. Зарегистрируйтесь или войдите в AI Gateway и создайте API-ключ.
2. Сохраните ключ в AI_GATEWAY_API_KEY на сервере или в локальной переменной окружения. Не помещайте его в репозиторий, журнал, браузерный код или мобильное приложение. Подробнее — в инструкции по авторизации API.
3. Откройте раздел Модели, выберите вариант с путём /v1/chat/completions и скопируйте его точный request_model_id.
4. Сохраните этот идентификатор в AI_GATEWAY_MODEL_ID. Не сокращайте его и не собирайте префикс поставщика вручную.
5. Проверьте актуальные условия на странице Цены и убедитесь, что на балансе организации есть средства.

Для локального запуска переменные можно задать в текущей сессии терминала:

export AI_GATEWAY_API_KEY="<ВАШ_API-КЛЮЧ>"
export AI_GATEWAY_MODEL_ID="<REQUEST_MODEL_ID_ИЗ_КАТАЛОГА>"

Python

import os

from openai import OpenAI

client = OpenAI(
    base_url="https://route.smartaipack.ru/v1",
    api_key=os.environ["AI_GATEWAY_API_KEY"],
)

completion = client.chat.completions.create(
    model=os.environ["AI_GATEWAY_MODEL_ID"],
    messages=[
        {
            "role": "user",
            "content": "Объясни в двух предложениях, зачем нужен API-шлюз.",
        }
    ],
)

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

Клиент сам добавит /chat/completions к base_url. Поэтому не передавайте полный путь метода в base_url и не добавляйте второй /v1.

TypeScript/JavaScript

Этот пример рассчитан на серверную среду Node.js. Секретный ключ нельзя передавать в клиентский JavaScript: посетитель увидит его в коде страницы или сетевом запросе.

import OpenAI from "openai";

const modelId = process.env.AI_GATEWAY_MODEL_ID;

if (!process.env.AI_GATEWAY_API_KEY || !modelId) {
  throw new Error("Задайте AI_GATEWAY_API_KEY и AI_GATEWAY_MODEL_ID");
}

const client = new OpenAI({
  baseURL: "https://route.smartaipack.ru/v1",
  apiKey: process.env.AI_GATEWAY_API_KEY
});

const completion = await client.chat.completions.create({
  model: modelId,
  messages: [
    {
      role: "user",
      content: "Объясни в двух предложениях, зачем нужен API-шлюз."
    }
  ]
});

console.log(completion.choices[0].message.content);

Успешный вызов подтверждает совместимость выбранного request_model_id с /v1/chat/completions. Он не доказывает, что та же модель доступна на других путях.

Потоковый ответ

Для Chat Completions передайте stream=True в Python или stream: true в TypeScript. Пакет вернёт поток частей ответа. Границы chunk не совпадают со словами: delta.content иногда содержит несколько символов, несколько слов или вообще не содержит текста.

stream = client.chat.completions.create(
    model=os.environ["AI_GATEWAY_MODEL_ID"],
    messages=[
        {
            "role": "user",
            "content": "Дай краткий план внедрения поиска по базе знаний.",
        }
    ],
    stream=True,
)

parts: list[str] = []

try:
    for chunk in stream:
        if not chunk.choices:
            continue

        text = chunk.choices[0].delta.content
        if text:
            parts.append(text)
            print(text, end="", flush=True)
finally:
    stream.close()

full_text = "".join(parts)
print()

Прокси AI Gateway не буферизует поток SSE для /v1/chat/completions, но ваше приложение, сервер или промежуточный прокси всё равно могут задерживать вывод. Практические правила отмены, сборки текста и обработки оборванного соединения есть в руководстве по потоковым ответам.

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

Векторные представления

Метод client.embeddings.create можно использовать только с моделью, у которой в каталоге опубликован путь /v1/embeddings. Скопируйте её request_model_id в отдельную переменную, чтобы случайно не отправить запрос модели для диалога.

embedding_response = client.embeddings.create(
    model=os.environ["AI_GATEWAY_EMBEDDING_MODEL_ID"],
    input="Как подключить смысловой поиск по базе знаний?",
)

vector = embedding_response.data[0].embedding
print(f"Получен вектор из {len(vector)} значений")

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

Ошибки и диагностика

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

Не повторяйте без изменений ошибки 400, 401, 402 и 403. После вызова найдите операцию в разделе Использование, а расход и разбивку по моделям проверьте в Аналитике. Полный порядок разбора ответов собран в статье Ошибки API. Если проблема сохраняется, обратитесь в поддержку и передайте время, путь, модель и статус без секретного ключа.

Что SDK не добавляет

Пакет openai упрощает формирование совместимых запросов и чтение ответов, но не заменяет продуктовые проверки:

• не выбирает модель за приложение — передавайте точный request_model_id из Моделей;
• не проверяет баланс, цену и доступность до запроса — сверяйте цены, использование и аналитику;
• не делает запрос идемпотентным и не гарантирует безопасный повтор после обрыва соединения;
• не скрывает ошибки 400, 401, 402, 403, 429 и 5xx;
• не делает все опубликованные протоколы одинаково доступными через один набор методов.

В частности, /v1/messages, /v1/rerank и /v1/audio/speech могут потребовать прямой HTTP-запрос или отдельную проверку версии клиента. Даже если метод есть в установленном пакете, сначала убедитесь, что выбранная модель опубликована на нужном пути и что форма запроса совпадает с контрактом AI Gateway.