Chat Completions → Responses

Chat Completions организует диалог через messages и choices; Responses выражает вход, вызовы инструментов и результаты через input, Typed Items и output. Помимо эндпоинта измените входную структуру, разбор ответа, цикл инструментов и потоковый автомат состояний.

Нужна ли миграция

Responses подходит, если:

• Новому проекту нужны единые Typed Input и Output Items;
• Нужно сохранять состояние между шагами диалога, например через previous_response_id;
• Нужны уже поддерживаемые встроенные инструменты Responses;
• Приложение готово обрабатывать текст, вызовы инструментов и другие выходы по типам Item.

Можно продолжить использовать Chat Completions, если:

• Существующее приложение стабильно опирается на messages, choices и Chat Delta;
• Целевая модель или нужные инструменты поддерживают только Chat Completions;
• Пока нет достаточных регрессионных проверок инструментов, диалогов и Streaming;
• Выгода миграции не оправдывает затраты на изменение разбора ответа и управления состоянием.

Основные изменения

Минимальный запрос: Before / After

{
  "model": "MODEL_ID",
  "messages": [
    {
      "role": "system",
      "content": "Отвечайте кратко и точно."
    },
    {
      "role": "user",
      "content": "Представьте AGTCloud в одном предложении."
    }
  ]
}

В OpenAI SDK Base URL Client остаётся https://api.agtcloud.cn/v1. Метод меняется с client.chat.completions.create(...) на client.responses.create(...). Инициализация Python и TypeScript описана в OpenAI SDK.

Миграция чтения ответа

Chat Completions обычно читает сообщение ассистента из первого Choice:

choices[0].message.content

Responses возвращает упорядоченный output[], который может содержать сообщения, вызовы функций, поиск и другие Items. output_text SDK даёт агрегированный текст, но для инструментов и других выходов обходите весь output.

response.output_text
response.output[]

Миграция состояния многошагового диалога

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

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

Миграция Function Calling

Определение инструментов

Chat Completions размещает определение функции в tools[].function:

{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "Получение погоды в городе",
    "parameters": {
      "type": "object",
      "properties": {
        "city": { "type": "string" }
      },
      "required": ["city"]
    }
  }
}

Responses размещает информацию о функции прямо в объекте Function Tool:

{
  "type": "function",
  "name": "get_weather",
  "description": "Получение погоды в городе",
  "parameters": {
    "type": "object",
    "properties": {
      "city": { "type": "string" }
    },
    "required": ["city"]
  }
}

Передача результата

• Chat: чтение вызовов из assistant.tool_calls[] и добавление Tool Message с tool_call_id.
• Responses: чтение из output[] элементов function_call и отправка function_call_output с call_id, совпадающим с исходным вызовом.

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

Миграция Streaming

Chat Completions возвращает приращения через choices[].delta каждого Chunk и обычно заканчивается [DONE].

Responses использует именованные события, например:

• response.created;
• response.output_item.added;
• response.content_part.added;
• response.output_text.delta;
• response.output_text.done;
• response.completed.

Вместо простого объединения текста создайте диспетчер событий: сначала обработайте тип, затем обновляйте соответствующее состояние по output_index, content_index, item_id и другим идентификаторам.

Миграция Structured Outputs

Chat Completions задаёт формат вывода в response_format; Responses — в text.format. При миграции синхронно измените:

1. Расположение полей запроса;
2. Обёртку JSON Schema;
3. Вспомогательные методы разбора SDK;
4. Обработку отказов, неполных ответов и ошибок проверки Schema.

Подробные поля приведены в Chat Completions и OpenAI Responses.

Миграция Web Search

Интерфейсы поиска двух протоколов различаются:

• Chat Completions использует web_search_options и требует модель с поддержкой поиска;
• Responses включает поддерживаемый Web Search Tool в tools и может вернуть Item вызова поиска и ссылки.

Фильтры доменов, список источников, местоположение пользователя и доступ к актуальному интернету зависят от протокола и модели. Полные примеры приведены в OpenAI Web Search.

Usage, ошибки и прерывания

При миграции мониторинга и чтения биллинга как минимум измените:

Сохраняйте также HTTP-статус, объект ошибки и Request ID. Не ограничивайтесь текстом исключения SDK: журналы должны различать ошибку аутентификации, невидимую модель, ограничение частоты, сбой сервиса и обрыв соединения.

Поэтапная миграция

Проверки регрессии и отката

• Обычный текст, пустой вывод, отказ, неполное состояние и ошибка;
• Один и несколько инструментов, ошибка инструмента и неверные аргументы;
• История без состояния и previous_response_id;
• Нормальное завершение Streaming, обрыв и повторные события;
• Ошибка проверки Structured Outputs;
• Usage, ошибки, Request ID, тайм-ауты и ограничение частоты;
• Возможность вернуться к Chat Completions, если модель не поддерживает нужную возможность Responses.

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

Следующие шаги

• Настройте Python или TypeScript Client через OpenAI SDK;
• Изучите обычный процесс Responses в Текст и диалог;
• Проверьте полные поля и ответы в OpenAI Responses;
• При ошибках вызова прочитайте Ошибки и устранение неполадок.