План интеграции OpenResponses Gateway

Контекст

Mayros Gateway в настоящее время предоставляет минимальный совместимый с OpenAI эндпоинт Chat Completions на /v1/chat/completions (см. OpenAI Chat Completions).

Open Responses - это открытый стандарт вывода, основанный на Responses API OpenAI. Он разработан для агентских рабочих процессов и использует входные данные на основе элементов плюс семантические события потоковой передачи. Спецификация OpenResponses определяет /v1/responses, а не /v1/chat/completions.

Цели

  • Добавить эндпоинт /v1/responses, соответствующий семантике OpenResponses.
  • Сохранить Chat Completions как слой совместимости, который легко отключить и в конечном итоге удалить.
  • Стандартизировать валидацию и разбор с изолированными, переиспользуемыми схемами.

Не-цели

  • Полная поддержка функций OpenResponses в первом проходе (изображения, файлы, размещенные инструменты).
  • Замена внутренней логики выполнения агента или оркестрации инструментов.
  • Изменение существующего поведения /v1/chat/completions во время первой фазы.

Резюме исследования

Источники: OpenAPI OpenResponses, сайт спецификации OpenResponses и пост в блоге Hugging Face.

Извлеченные ключевые пункты:

  • POST /v1/responses принимает поля CreateResponseBody, такие как model, input (строка или ItemParam[]), instructions, tools, tool_choice, stream, max_output_tokens и max_tool_calls.
  • ItemParam - это размеченное объединение:
    • элементы message с ролями system, developer, user, assistant
    • function_call и function_call_output
    • reasoning
    • item_reference
  • Успешные ответы возвращают ResponseResource с object: "response", status и элементами output.
  • Потоковая передача использует семантические события, такие как:
    • response.created, response.in_progress, response.completed, response.failed
    • response.output_item.added, response.output_item.done
    • response.content_part.added, response.content_part.done
    • response.output_text.delta, response.output_text.done
  • Спецификация требует:
    • Content-Type: text/event-stream
    • event: должен совпадать с полем JSON type
    • терминальное событие должно быть буквальным [DONE]
  • Элементы Reasoning могут предоставлять content, encrypted_content и summary.
  • Примеры HF включают OpenResponses-Version: latest в запросах (опциональный заголовок).

Предлагаемая архитектура

  • Добавить src/gateway/open-responses.schema.ts, содержащий только схемы Zod (без импортов gateway).
  • Добавить src/gateway/openresponses-http.ts (или open-responses-http.ts) для /v1/responses.
  • Сохранить src/gateway/openai-http.ts нетронутым как адаптер совместимости legacy.
  • Добавить конфигурацию gateway.http.endpoints.responses.enabled (по умолчанию false).
  • Сохранить gateway.http.endpoints.chatCompletions.enabled независимым; разрешить оба эндпоинта переключаться отдельно.
  • Выдавать предупреждение при запуске, когда Chat Completions включен, для сигнализации статуса legacy.

Путь устаревания для Chat Completions

  • Поддерживать строгие границы модулей: нет общих типов схем между responses и chat completions.
  • Сделать Chat Completions opt-in через конфигурацию, чтобы его можно было отключить без изменений кода.
  • Обновить документацию для маркировки Chat Completions как legacy после стабилизации /v1/responses.
  • Опциональный будущий шаг: отображать запросы Chat Completions на обработчик Responses для более простого пути удаления.

Поддерживаемое подмножество фазы 1

  • Принять input как строку или ItemParam[] с ролями сообщений и function_call_output.
  • Извлечь system и developer сообщения в extraSystemPrompt.
  • Использовать самое последнее сообщение user или function_call_output как текущее сообщение для запусков агента.
  • Отклонять неподдерживаемые части содержимого (image/file) с invalid_request_error.
  • Возвращать одно сообщение assistant с содержимым output_text.
  • Возвращать usage с обнуленными значениями до подключения учета токенов.

Стратегия валидации (без SDK)

  • Реализовать схемы Zod для поддерживаемого подмножества:
    • CreateResponseBody
    • ItemParam + объединения частей содержимого сообщений
    • ResponseResource
    • Формы событий потоковой передачи, используемые gateway
  • Сохранить схемы в одном, изолированном модуле, чтобы избежать расхождения и разрешить будущую кодогенерацию.

Реализация потоковой передачи (фаза 1)

  • SSE строки с обоими event: и data:.
  • Требуемая последовательность (минимально жизнеспособная):
    • response.created
    • response.output_item.added
    • response.content_part.added
    • response.output_text.delta (повторять по необходимости)
    • response.output_text.done
    • response.content_part.done
    • response.completed
    • [DONE]

План тестов и проверки

  • Добавить e2e покрытие для /v1/responses:
    • Требуется аутентификация
    • Форма ответа без потоковой передачи
    • Порядок событий потоковой передачи и [DONE]
    • Маршрутизация сессий с заголовками и user
  • Сохранить src/gateway/openai-http.e2e.test.ts без изменений.
  • Вручную: curl к /v1/responses с stream: true и проверить порядок событий и терминальный [DONE].

Обновления документации (продолжение)

  • Добавить новую страницу документации для использования /v1/responses и примеров.
  • Обновить /gateway/openai-http-api с заметкой legacy и указателем на /v1/responses.