Kế hoạch tích hợp OpenResponses Gateway

Ngữ cảnh

Mayros Gateway hiện hiển thị endpoint Chat Completions tương thích OpenAI tối thiểu tại /v1/chat/completions (xem OpenAI Chat Completions).

Open Responses là tiêu chuẩn inference mở dựa trên OpenAI Responses API. Nó được thiết kế cho quy trình agentic và sử dụng input dựa trên item cộng sự kiện streaming ngữ nghĩa. Spec OpenResponses định nghĩa /v1/responses, không phải /v1/chat/completions.

Mục tiêu

  • Thêm endpoint /v1/responses tuân thủ ngữ nghĩa OpenResponses.
  • Giữ Chat Completions như lớp tương thích dễ tắt và cuối cùng xóa.
  • Chuẩn hóa xác thực và phân tích với schema có thể tái sử dụng, được cô lập.

Ngoài phạm vi

  • Tính năng OpenResponses đầy đủ trong lần đầu tiên (hình ảnh, file, công cụ được lưu trữ).
  • Thay thế logic thực thi agent nội bộ hoặc điều phối công cụ.
  • Thay đổi hành vi /v1/chat/completions hiện có trong giai đoạn đầu tiên.

Tóm tắt nghiên cứu

Nguồn: OpenAPI OpenResponses, trang spec OpenResponses và bài đăng blog Hugging Face.

Điểm chính được trích xuất:

  • POST /v1/responses chấp nhận trường CreateResponseBody như model, input (chuỗi hoặc ItemParam[]), instructions, tools, tool_choice, stream, max_output_tokens và max_tool_calls.
  • ItemParam là union được phân biệt của:
    • Item message với role system, developer, user, assistant
    • function_call và function_call_output
    • reasoning
    • item_reference
  • Phản hồi thành công trả về ResponseResource với object: "response", status và item output.
  • Streaming sử dụng sự kiện ngữ nghĩa như:
    • 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
  • Spec yêu cầu:
    • Content-Type: text/event-stream
    • event: phải khớp trường type JSON
    • sự kiện terminal phải là literal [DONE]

Kiến trúc đề xuất

  • Thêm src/gateway/open-responses.schema.ts chứa chỉ schema Zod (không có import gateway).
  • Thêm src/gateway/openresponses-http.ts (hoặc open-responses-http.ts) cho /v1/responses.
  • Giữ src/gateway/openai-http.ts nguyên vẹn như adapter tương thích cũ.
  • Thêm cấu hình gateway.http.endpoints.responses.enabled (mặc định false).
  • Giữ gateway.http.endpoints.chatCompletions.enabled độc lập; cho phép cả hai endpoint được bật/tắt riêng biệt.
  • Phát ra cảnh báo khởi động khi Chat Completions được bật để báo hiệu trạng thái cũ.

Đường dẫn ngừng sử dụng cho Chat Completions

  • Duy trì ranh giới module nghiêm ngặt: không có kiểu schema được chia sẻ giữa responses và chat completions.
  • Làm Chat Completions tùy chọn bằng cấu hình để nó có thể bị tắt mà không cần thay đổi mã.
  • Cập nhật tài liệu để gắn nhãn Chat Completions là cũ khi /v1/responses ổn định.
  • Bước tương lai tùy chọn: ánh xạ yêu cầu Chat Completions sang handler Responses cho đường dẫn xóa đơn giản hơn.

Hỗ trợ tập hợp con giai đoạn 1

  • Chấp nhận input như chuỗi hoặc ItemParam[] với role message và function_call_output.
  • Trích xuất message system và developer vào extraSystemPrompt.
  • Sử dụng user hoặc function_call_output gần nhất làm message hiện tại cho agent run.
  • Từ chối phần nội dung không được hỗ trợ (image/file) với invalid_request_error.
  • Trả về message assistant đơn với nội dung output_text.
  • Trả về usage với giá trị zero cho đến khi kế toán token được kết nối.

Chiến lược xác thực (Không có SDK)

  • Triển khai schema Zod cho tập hợp con được hỗ trợ của:
    • CreateResponseBody
    • ItemParam + union phần nội dung message
    • ResponseResource
    • Shape sự kiện streaming được sử dụng bởi gateway
  • Giữ schema trong một module được cô lập, đơn để tránh trôi dạt và cho phép codegen tương lai.

Triển khai streaming (Giai đoạn 1)

  • Dòng SSE với cả event: và data:.
  • Chuỗi bắt buộc (khả thi tối thiểu):
    • response.created
    • response.output_item.added
    • response.content_part.added
    • response.output_text.delta (lặp lại khi cần)
    • response.output_text.done
    • response.content_part.done
    • response.completed
    • [DONE]

Kế hoạch test và xác minh

  • Thêm bao phủ e2e cho /v1/responses:
    • Xác thực yêu cầu
    • Shape phản hồi không stream
    • Thứ tự sự kiện stream và [DONE]
    • Định tuyến phiên với header và user
  • Giữ src/gateway/openai-http.e2e.test.ts không thay đổi.
  • Thủ công: curl đến /v1/responses với stream: true và xác minh thứ tự sự kiện và terminal [DONE].

Cập nhật tài liệu (Follow-up)

  • Thêm trang tài liệu mới cho cách sử dụng và ví dụ /v1/responses.
  • Cập nhật /gateway/openai-http-api với ghi chú cũ và con trỏ đến /v1/responses.