API Chat Completions от OpenAI: возможности и руководство по использованию

Создание приложения на базе ИИ — это не только получение ответов от модели. Вам также нужен надежный способ управлять диалогами, направлять ответы и связать все это с приложением. OpenAI Chat Completions API дает разработчикам возможность контролировать, как ИИ обрабатывает сообщения и генерирует ответы. В этой статье вы узнаете, как он работает и как использовать его в собственных проектах.

OpenAI Chat Completions API позволяет разработчикам интегрировать языковые модели OpenAI в приложения и сервисы. Он генерирует ответы на основе последовательности сообщений и поддерживает такие задачи, как ведение диалога, ответы на вопросы, создание контента и анализ текста.

Chat Completions по-прежнему поддерживается. Для новых проектов OpenAI рекомендует Responses API. Это руководство посвящено Chat Completions и объясняет его формат сообщений, параметры запросов и использование с совместимыми SDK.

В отличие от устаревшего endpoint Completions (/v1/completions), который принимает текстовый prompt, Chat Completions принимает структурированный список сообщений. У каждого сообщения есть роль, например developer, user или assistant, которая помогает модели интерпретировать инструкции и контекст диалога. Поддерживаемые роли и типы контента зависят от выбранной модели.

Разработчики могут использовать API для создания различных функций на базе ИИ, в том числе:

• Диалоговые приложения: Создавайте ИИ-чат-ботов, виртуальных помощников и системы поддержки клиентов, отвечающие на сообщения пользователей.

• Создание контента: Генерируйте статьи, описания товаров, электронные письма, сводки и другие письменные материалы.

• Анализ текста: Классифицируйте текст, извлекайте информацию, анализируйте тональность и выявляйте ключевые моменты в документах.

• Помощь в программировании: Генерируйте фрагменты кода, объясняйте концепции программирования и помогайте разработчикам устранять ошибки.

• Обработка языка: Переводите, переписывайте, упрощайте и вычитывайте тексты на разных языках.

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

Chat Completions API работает по модели «запрос — ответ». Приложение отправляет на endpoint API запрос, содержащий идентификатор модели и список сообщений. Выбранная модель обрабатывает входные данные и возвращает сгенерированный ответ.

Базовый процесс включает следующие шаги:

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

2. Отправьте запрос API: Приложение отправляет POST-запрос на https://api.openai.com/v1/chat/completions с выбранной моделью и списком сообщений. В запросах используется заголовок Authorization: Bearer <API_KEY>. Метод Python SDK client.chat.completions.create() обрабатывает структуру запроса и аутентификацию.

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

4. Получите ответ: Запрос без потоковой передачи возвращает JSON-ответ с результатом генерации и метаданными. При включенной потоковой передаче API отправляет последовательность событий, передаваемых сервером (SSE), которые приложение обрабатывает по мере поступления.

5. Отобразите или обработайте результат: Приложение извлекает сгенерированное сообщение, показывает его пользователю или передает другому компоненту приложения.

Процесс основан на модели запросов и ответов OpenAI Chat Completions API.

Чтобы эффективно использовать Chat Completions API, разработчикам необходимо понимать его основные параметры запросов и их влияние на поведение модели.

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

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

Параметр messages содержит массив сообщений диалога. Каждое сообщение обычно включает поля role и content.

К распространенным ролям относятся:

Выберите роль для инструкций, поддерживаемую вашей моделью; не нужно отправлять сообщения system и developer с одними и теми же инструкциями. Чтобы сохранять контекст между этапами диалога, включайте в каждый запрос соответствующую историю переписки. Совместимые провайдеры могут поддерживать разные роли, поэтому при адаптации интеграции следуйте документации их моделей.

В моделях и конфигурациях, где это поддерживается, temperature регулирует случайность выборки. В справочнике API указан диапазон от 0 до 2 со значением по умолчанию 1. Прежде чем задавать пользовательское значение, проверьте, поддерживает ли его выбранная модель.

• Низкая температура: дает более сфокусированные и предсказуемые ответы, поэтому полезна для классификации, извлечения информации и структурированных задач.

• Высокая температура: допускает больше вариативности в сгенерированном тексте, что может быть полезно для мозгового штурма и творческого письма.

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

Там, где это поддерживается, top_p управляет выбором токенов с помощью ядерной выборки. Он задает порог совокупной вероятности для отбора токенов-кандидатов.

Например, значение 0,1 означает, что модель рассматривает токены, входящие в верхние 10% совокупной вероятностной массы. Меньшие значения обычно дают более сфокусированный результат, а большие допускают больше вариаций.

OpenAI рекомендует настраивать либо temperature, либо top_p, а не изменять оба параметра одновременно.

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

Подходящее ограничение помогает разработчикам контролировать длину ответа и расход токенов. Если модель достигнет этого лимита до завершения ответа, генерация может завершиться с причиной length.

Параметр stream определяет, возвращает ли API сгенерированный ответ целиком или передает его постепенно по мере генерации.

• false: Возвращает полный ответ после завершения генерации.

• true: Передает данные ответа в приложение потоком через события, отправляемые сервером (SSE).

Потоковая передача полезна для чат-интерфейсов и приложений, где пользователям удобнее видеть ответ по мере его появления, а не ждать весь результат целиком.

Параметр response_format выбирает формат вывода в поддерживаемых моделях. По умолчанию используется текст. Установка для type значения json_object включает режим JSON, который создает корректный JSON, но не обеспечивает соответствие определенной схеме. Добавьте в сообщения инструкцию возвращать JSON.

Для предсказуемых полей и типов данных используйте Structured Outputs на основе JSON Schema с type: "json_schema" и strict: true в совместимой модели. В строгом режиме можно использовать только поддерживаемое подмножество JSON Schema. Перед обработкой результата проверьте, нет ли отказа или усеченного ответа. Подробнее о настройке см. в руководстве по Structured Outputs.

Параметр tool_choice управляет выбором инструментов, когда модель поддерживает вызов инструментов через Chat Completions. Поддержка зависит как от модели, так и от ее конфигурации рассуждений; для использования инструментов некоторым новым моделям требуется Responses API. Проверьте эти требования, прежде чем добавлять инструменты в запрос.

Распространенные настройки:

• none: Не позволяет модели вызывать инструменты.

• auto: Позволяет модели решить, вызывать ли доступный инструмент.

• required: Требует от модели вызвать один или несколько инструментов.

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

Определения параметров и требования к совместимости моделей см. в справочнике Chat Completions API. В примере на Python ниже используется базовый текстовый запрос без инструментов.

Разработчики могут работать с Chat Completions API через HTTP-запросы или официальный SDK. В следующем примере Python используется для отправки диалогового запроса и получения сгенерированного ответа.

Шаг 1. Получите API-ключ

Создайте API-ключ на платформе OpenAI API и убедитесь, что ваша учетная запись имеет доступ к выбранной модели, а также достаточно средств или лимита биллинга для API. Храните ключ в переменной окружения, а не в исходном коде приложения. В macOS или Linux выполните:

Замените YOUR_API_KEY на свой ключ. В Windows задайте ту же переменную OPENAI_API_KEY в оболочке или системном окружении.

Шаг 2. Установите Python SDK OpenAI

Установите официальную библиотеку Python с помощью pip:

Шаг 3. Инициализируйте API-клиент

Импортируйте SDK и инициализируйте клиент. OpenAI() автоматически считывает переменную окружения OPENAI_API_KEY, заданную на шаге 1.

Шаг 4. Отправьте запрос на чат-завершение

Вызовите client.chat.completions.create(), указав модель и список сообщений. В этом примере используется gpt-6-astra с низким уровнем усилий на рассуждения и общим лимитом генерации в 4096 токенов. Если эта модель недоступна для вашей учетной записи, выберите модель, поддерживающую Chat Completions, и настройте параметры в соответствии с ее документацией.

В этом примере:

• model определяет языковую модель, используемую для генерации ответа.

• messages содержат инструкции и пользовательский ввод.

• reasoning_effort задает уровень усилий на рассуждения для моделей, поддерживающих этот параметр.

• max_completion_tokens ограничивает количество генерируемых токенов, включая токены рассуждений. Он не гарантирует определенный объем видимого текста.

• response.choices[0].message.content извлекает ответ ассистента.

Обработайте ответ API

Для этого запроса без потоковой передачи API возвращает JSON с результатом генерации и метаданными запроса. Python SDK преобразует его в объект ChatCompletion, поэтому в примере поля доступны через атрибуты, например response.choices[0].message.content.

К важным полям ответа относятся:

Поле finish_reason помогает разработчикам понять, как завершилась генерация. Распространенные значения: stop, length и tool_calls.

Разработчики также могут проверять поле usage, чтобы отслеживать расход входных и выходных token. Это полезно для оценки затрат на API и оптимизации использования приложения.

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

Для разработчиков, рассматривающих альтернативы OpenAI Chat Completions API, Kimi API предоставляет доступ к большим языковым моделям Moonshot AI через API в формате, совместимом с OpenAI.

Kimi предлагает интерфейсы Chat Completions, Responses и Messages. В примере ниже используется совместимая с OpenAI конечная точка Chat Completions, поэтому вы сможете повторно использовать представленный выше рабочий процесс SDK. Настройте ключ Kimi API, укажите базовый URL Kimi и выберите поддерживаемую модель. О параметрах модели, ролях сообщений и поддержке инструментов читайте в документации Kimi.

Шаг 1. Получите ключ Kimi API

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

Сохраните ключ Kimi в отдельной переменной окружения. В macOS или Linux выполните:

Замените YOUR_KIMI_API_KEY на свой ключ Kimi. В Windows задайте в окружении ту же переменную KIMI_API_KEY.

Шаг 2. Установите OpenAI Python SDK

Если SDK еще не установлен, выполните:

Шаг 3. Настройте клиент Kimi API

Создайте отдельный kimi_client, указав базовый URL Kimi и переменную KIMI_API_KEY, заданную на шаге 1. Получение ключа через os.environ позволяет сразу увидеть ошибку, если переменная окружения отсутствует.

Шаг 4. Отправьте запрос Chat Completions

Используйте тот же метод SDK с клиентом Kimi. В этом запросе выбрана kimi-k3, для инструкций используется поддерживаемая Kimi роль system, а в ответ возвращается текст без потоковой передачи.

• Варианты моделей для разных задач: Kimi K3.1 Pro поддерживает сложные рассуждения, программирование с долгосрочным планированием и работу со знаниями. Вариант Highspeed обеспечивает более быстрый вывод при тех же возможностях модели. В примере выше используется Kimi K3; информацию о доступности и рекомендации по миграции смотрите в актуальном списке моделей.

• Совместимость с OpenAI API: Разработчики, знакомые с форматом OpenAI Chat Completions, могут использовать похожую структуру запроса и поддерживаемые рабочие процессы SDK при интеграции моделей Kimi.

• Многошаговые диалоги: Разработчики могут передавать историю сообщений, чтобы поддерживать диалоги с учетом контекста, виртуальных помощников и интерактивные приложения.

• Потоковая передача и вызов функций: API поддерживает потоковые ответы и рабочие процессы вызова инструментов, позволяя разработчикам создавать более интерактивные приложения и подключать модели к внешним функциям.

• Мультимодальный ввод: Поддерживаемые модели Kimi могут обрабатывать различные типы входных данных, включая текст, изображения и видео, в зависимости от возможностей модели.

При работе с Chat Completions API разработчики могут столкнуться с ошибками, связанными с аутентификацией, настройкой API, доступностью моделей или лимитами запросов. Понимание этих распространенных проблем поможет выявить неполадки и наладить интеграцию:

• Недействительный или отсутствующий ключ API: Ошибки аутентификации, например HTTP 401, могут возникать, если ключ API неверный, срок его действия истек, он отозван или настроен неправильно. Убедитесь, что ключ действителен, переменная окружения загружена правильно, а запрос содержит необходимые учетные данные для аутентификации.

• Неверный базовый URL API: Запросы, отправленные на неправильную конечную точку, могут возвращать ошибки, например 404, или завершаться сбоем подключения. Убедитесь, что базовый URL соответствует документации поставщика API, а в запросе указан правильный путь к конечной точке. При переключении между OpenAI и совместимыми поставщиками не забудьте соответствующим образом обновить базовый URL.

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

• Превышена длина контекста: Если суммарный объем входных сообщений и сгенерированного вывода превышает контекстное окно модели, API может отклонить запрос. Сократите входные данные, удалите ненужную историю диалога или суммируйте более ранние сообщения перед повторной отправкой запроса.

• Вывод обрезан: Ответ может завершиться до создания запрошенного содержимого, если достигнут лимит max_completion_tokens. Если это поддерживается, увеличьте лимит token или разбейте задачу длинной генерации на несколько меньших запросов. Также можно проверить choices[].finish_reason, чтобы узнать, не завершился ли ответ из-за лимита length.

• Превышен лимит запросов или квота: Для OpenAI HTTP 429 может означать лимит частоты запросов или token, лимит расходов либо другое ограничение использования. Перед повторной попыткой проверьте тип и код ошибки. При временном ограничении частоты снизьте частоту запросов и следуйте Retry-After, если он указан, либо используйте экспоненциальную задержку между повторами.

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

Для более эффективной отладки перед изменением параметров запроса проверьте код состояния HTTP и сообщение об ошибке, возвращенные API. Эти сведения помогут отличить проблемы аутентификации, ошибки конфигурации и ограничения использования.

Chat Completions API подходит для широкого спектра сценариев применения. Структурированный формат сообщений и настраиваемые параметры генерации позволяют использовать его как для простых текстовых функций, так и для более сложных рабочих процессов ИИ.

• ИИ-чат-боты и виртуальные помощники: Разработчики могут использовать API для создания диалоговых помощников для сайтов, мобильных приложений и платформ обслуживания клиентов. Передавая предыдущие сообщения в последующие запросы, приложения могут сохранять контекст диалога и давать более релевантные ответы.

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

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

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

• Бизнес-процессы на базе ИИ: Разработчики могут встраивать API в бизнес-приложения, чтобы автоматизировать повторяющиеся задачи, связанные с обработкой языка. Например, обрабатывать обращения клиентов, создавать отчеты, извлекать информацию из документов и готовить ответы на основе заранее заданных инструкций.

OpenAI Chat Completions API дает разработчикам практичный способ внедрить разговорный ИИ в свои приложения и сделать взаимодействие с пользователями полезнее. Правильный выбор модели, понимание ее параметров и внимательная обработка ответов API могут существенно повлиять на работу приложения. Однако при создании решений на базе ИИ разработчикам необязательно полагаться на одного поставщика. Если хотите рассмотреть другой вариант, попробуйте Kimi API и оцените, насколько его совместимая с OpenAI конфигурация отвечает вашим задачам разработки.