Chat Completions → Responses

Chat Completions tổ chức hội thoại bằng messages và choices; Responses dùng input, Typed Items và output để biểu diễn đầu vào, gọi công cụ và kết quả. Khi chuyển đổi, ngoài điểm cuối, cần điều chỉnh cấu trúc đầu vào, phân tích phản hồi, vòng lặp công cụ và máy trạng thái luồng.

Có cần chuyển đổi không

Các trường hợp phù hợp chuyển sang Responses:

• Dự án mới muốn dùng Typed Input và Output Items thống nhất;
• Cần khả năng trạng thái nhiều lượt như previous_response_id;
• Cần công cụ tích hợp đã được Responses hỗ trợ;
• Ứng dụng sẵn sàng xử lý văn bản, gọi công cụ và đầu ra khác theo kiểu Item.

Các trường hợp có thể tiếp tục dùng Chat Completions:

• Ứng dụng hiện tại phụ thuộc ổn định vào messages, choices và Chat Delta;
• Mô hình đích hoặc công cụ cần dùng chỉ hỗ trợ Chat Completions;
• Chưa có đủ kiểm thử hồi quy cho công cụ, nhiều lượt và Streaming;
• Lợi ích chuyển đổi không bù được chi phí sửa phân tích phản hồi và quản lý trạng thái.

Thay đổi cốt lõi

Yêu cầu tối thiểu Before / After

{
  "model": "MODEL_ID",
  "messages": [
    {
      "role": "system",
      "content": "Trả lời ngắn gọn và chính xác."
    },
    {
      "role": "user",
      "content": "Hãy giới thiệu AGTCloud bằng một câu."
    }
  ]
}

Khi dùng OpenAI SDK, Base URL của Client vẫn là https://api.agtcloud.cn/v1. Đổi phương thức từ client.chat.completions.create(...) sang client.responses.create(...). Xem OpenAI SDK để biết khởi tạo Python và TypeScript đầy đủ.

Chuyển đổi cách đọc phản hồi

Chat Completions thường đọc thông điệp trợ lý từ Choice đầu tiên:

choices[0].message.content

Responses trả output[] có thứ tự, có thể chứa đồng thời thông điệp, gọi hàm, gọi tìm kiếm hoặc Item khác. output_text của SDK đọc văn bản tổng hợp, nhưng nếu cần công cụ hoặc đầu ra khác, phải duyệt toàn bộ output.

response.output_text
response.output[]

Chuyển đổi trạng thái nhiều lượt

Khi dùng previous_response_id, instructions lượt trước không tự kế thừa. Mỗi lượt vẫn cần đặt lại chỉ dẫn theo nhu cầu ứng dụng.

Sau khi chuyển đổi, không phát lại đầy đủ cùng lịch sử rồi đồng thời tham chiếu lại nó qua previous_response_id, vì có thể tạo ngữ cảnh lặp.

Chuyển đổi Function Calling

Định nghĩa công cụ

Chat Completions đặt định nghĩa hàm trong tools[].function:

{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "Truy vấn thời tiết của thành phố",
    "parameters": {
      "type": "object",
      "properties": {
        "city": { "type": "string" }
      },
      "required": ["city"]
    }
  }
}

Responses đặt thông tin hàm trực tiếp trong đối tượng Function Tool:

{
  "type": "function",
  "name": "get_weather",
  "description": "Truy vấn thời tiết của thành phố",
  "parameters": {
    "type": "object",
    "properties": {
      "city": { "type": "string" }
    },
    "required": ["city"]
  }
}

Trả kết quả

• Chat: đọc lời gọi từ assistant.tool_calls[], thêm Tool Message có tool_call_id.
• Responses: đọc function_call từ output[], rồi gửi function_call_output với call_id khớp lời gọi gốc.

Dù dùng giao thức nào, ứng dụng của bạn thực thi hàm. Không thực thi trực tiếp tham số chưa kiểm tra hoặc trình bày lỗi công cụ như kết quả bình thường.

Chuyển đổi Streaming

Chat Completions trả phần tăng thêm qua choices[].delta của mỗi Chunk và thường kết thúc bằng [DONE].

Responses dùng sự kiện có tên, ví dụ:

• response.created；
• response.output_item.added；
• response.content_part.added；
• response.output_text.delta；
• response.output_text.done；
• response.completed。

Khi chuyển đổi, thay logic chỉ ghép văn bản bằng bộ phân phối sự kiện: xử lý theo kiểu sự kiện trước, rồi cập nhật trạng thái tương ứng bằng output_index, content_index, item_id và các mã khác.

Chuyển đổi Structured Outputs

Chat Completions đặt định dạng đầu ra trong response_format; Responses đặt cấu hình tương ứng trong text.format. Khi chuyển đổi, sửa đồng thời:

1. Vị trí trường yêu cầu;
2. Cấu trúc bao bọc JSON Schema;
3. Phương thức hỗ trợ phân tích của SDK;
4. Xử lý từ chối, phản hồi không đầy đủ và kiểm tra Schema thất bại.

Xem trường chi tiết trong Chat Completions và OpenAI Responses.

Chuyển đổi Web Search

Điểm vào tìm kiếm của hai giao thức khác nhau:

• Chat Completions dùng web_search_options và yêu cầu mô hình hỗ trợ tìm kiếm;
• Responses bật Web Search Tool được hỗ trợ trong tools, có thể trả Item gọi tìm kiếm và trích dẫn.

Lọc tên miền, danh sách nguồn, vị trí người dùng và truy cập Internet thời gian thực phụ thuộc giao thức cùng mô hình đã chọn. Xem ví dụ đầy đủ trong OpenAI Web Search.

Usage, lỗi và gián đoạn

Khi chuyển đổi logic giám sát và đọc dữ liệu tính phí, ít nhất điều chỉnh:

Giữ đồng thời mã trạng thái HTTP, đối tượng lỗi và Request ID. Không chỉ thu thập văn bản ngoại lệ SDK; nhật ký ứng dụng cần phân biệt xác thực thất bại, mô hình không hiển thị, giới hạn tốc độ, lỗi dịch vụ và mất kết nối.

Chuyển đổi theo giai đoạn

Danh sách kiểm tra hồi quy và dự phòng

• Văn bản thông thường, đầu ra trống, từ chối, trạng thái không đầy đủ và thất bại;
• Một công cụ, nhiều công cụ, công cụ thất bại và kiểm tra tham số thất bại;
• Phát lại lịch sử không trạng thái và previous_response_id;
• Streaming hoàn tất bình thường, ngắt luồng và sự kiện lặp;
• Kiểm tra Structured Outputs thất bại;
• Usage, thông tin lỗi, Request ID, thời gian chờ và giới hạn tốc độ;
• Có thể chuyển lại Chat Completions khi mô hình đích không hỗ trợ một khả năng Responses.

Trước khi chuyển đổi trong môi trường production, giữ cấu hình riêng cho Chat và Responses cùng công tắc có kiểm soát. Chỉ dọn đường phân tích cũ sau khi chỉ số nghiệp vụ, nhật ký và xử lý lỗi ổn định.

Bước tiếp theo

• Dùng OpenAI SDK để cấu hình Client Python hoặc TypeScript;
• Xem Văn bản và hội thoại để hiểu quy trình gọi Responses thường dùng;
• Kiểm tra toàn bộ trường và phản hồi trong OpenAI Responses;
• Khi gọi bị lỗi, xem Lỗi và khắc phục sự cố.