Chat Completions vẫn chạy, vẫn trả kết quả, và vẫn nằm trong hàng nghìn dự án production. Nhưng nó không còn là con đường được khuyến nghị cho code mới. Nếu bạn đang viết tính năng AI hôm nay, mặc định đúng là Responses API; Chat Completions chỉ nên giữ lại khi có lý do cụ thể.
Bài này dạy Chat Completions như một đường legacy: bạn cần hiểu nó để đọc và bảo trì code cũ, nhưng cần biết chính xác cái gì đã chuyển sang Responses và cái gì sẽ âm thầm hỏng nếu bạn không chuyển.
Mục lục
Cập nhật 2026: vì sao đây là đường legacy
- OpenAI khuyến nghị Responses API cho mọi dự án mới. Chat Completions vẫn được phục vụ nhưng không còn là mặc định.
- Hosted tools, trạng thái qua `previous_response_id` và encrypted reasoning chỉ tồn tại trên Responses.
- Từ GPT-5.4, Chat Completions không gọi được tool trừ khi `reasoning_effort` bằng `none`. Riêng GPT-6 Astra và GPT-6.1 Sol bắt buộc dùng Responses nếu muốn tool calling.
- Assistants API đã bị gỡ: trang tài liệu trả 404. Mọi code dựa trên Assistants phải viết lại trên Responses cộng Conversations.
- SDK Python chính thức là `openai` 3.46.0; phiên bản này hỗ trợ cả hai API, nhưng tên hàm và kiểu dữ liệu trả về khác nhau.
Hai API, một họ model
Cả hai endpoint gọi cùng dòng GPT-6, cùng cửa sổ 1.05M, cùng giá. Khác biệt nằm ở hình dạng request và những gì server làm thay bạn. Chat Completions nhận một mảng `messages` và trả về `choices`; nó không có khái niệm trạng thái phiên, không có tool do OpenAI host, và không có reasoning được mã hóa.
Responses nhận `input` dạng chuỗi hoặc danh sách item, trả về mảng `output`, và có thể giữ trạng thái cuộc gọi để bạn không phải gửi lại toàn bộ lịch sử. Với agent, đây không phải tiện ích nhỏ: mỗi item trong `output` có kiểu rõ ràng, gồm cả lời gọi tool và kết quả tool, nên vòng lặp dễ viết đúng hơn.
Chat Completions là stateless, và đó là vấn đề
Mỗi lần gọi Chat Completions là một lần độc lập. Server không nhớ gì giữa hai request; toàn bộ ngữ cảnh phải nằm trong mảng `messages` bạn gửi. Với chatbot ba lượt, bạn gửi lại lượt một và hai ở lượt ba. Với cuộc hội thoại 40 lượt, bạn gửi lại gần như toàn bộ lịch sử ở lượt 40.
Hệ quả là token đầu vào tăng gần tuyến tính theo số lượt, trong khi token đầu ra gần như phẳng. Chi phí vì thế dồn vào phần bạn không nhìn thấy: lịch sử. Đây cũng là lý do các ứng dụng chat phải tự đặt ra chiến lược cắt lịch sử, tóm tắt định kỳ hoặc chuyển sang trạng thái do server giữ. Không có chiến lược nào trong số đó miễn phí; cắt lịch sử làm mất ngữ cảnh, tóm tắt tốn thêm một lần gọi model.
Responses giải quyết phần plumbing bằng `previous_response_id`, nhưng không xóa bài toán chi phí. Trạng thái ở server giúp code gọn hơn và giảm nguy cơ gửi sai thứ tự message; nó không làm token biến mất. Vì vậy hãy đo `usage` của cả hai cách trước khi tuyên bố cách nào rẻ hơn.
Request Chat Completions tối thiểu
Đây là hình dạng một lần gọi legacy. Nó không có tham số sinh token, không có tool, chỉ có model và messages — đủ để thấy API hoạt động.
curl https://api.openai.com/v1/chat/completions \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-6.1-terra",
"messages": [
{ "role": "system", "content": "Bạn là trợ lý kỹ thuật, trả lời ngắn." },
{ "role": "user", "content": "Giải thích KV cache trong một đoạn." }
]
}'
Phản hồi có dạng `choices`, mỗi phần tử chứa `message.content`. Đó là toàn bộ hợp đồng mà hàng nghìn client đang dựa vào, và cũng là thứ sẽ vỡ nếu bạn đổi endpoint mà không đổi code parse.
Nếu bạn cần tool trên đường này với các model từ GPT-5.4 trở đi, phải đặt rõ mức reasoning bằng none. Bỏ qua field này là lý do phổ biến nhất khiến tool không bao giờ được gọi.
{
"model": "gpt-6.1-terra",
"reasoning_effort": "none",
"messages": [{ "role": "user", "content": "Tra cứu đơn hàng 12345." }],
"tools": [{ "type": "function", "function": { "name": "get_order", "parameters": { "type": "object", "properties": { "id": { "type": "string" } } } } }]
}
Với Astra và Sol, cùng payload này không phải giải pháp: hai model đó cần Responses cho tool calling. Đừng cố xoay quanh bằng cách hạ effort, vì bạn đang hạ chất lượng suy luận để giữ một API sắp bị bỏ.
Request Responses tương đương
Cùng một tác vụ, viết theo hình dạng mới. `instructions` thay cho system message, `input` thay cho mảng messages, `max_output_tokens` thay cho giới hạn token cũ.
curl https://api.openai.com/v1/responses \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-6.1-sol",
"instructions": "Bạn là trợ lý kỹ thuật, trả lời ngắn.",
"input": "Giải thích KV cache trong một đoạn.",
"max_output_tokens": 800,
"reasoning": { "effort": "medium" }
}'
Phản hồi không còn `choices`. Bạn nhận một mảng `output`; phần chữ nằm trong item kiểu `message`, và bên trong item đó là các content part kiểu `output_text`. Viết parser theo cấu trúc này ngay từ đầu sẽ tiết kiệm một lần refactor sau.
Với hội thoại nhiều lượt, bạn có hai lựa chọn: gửi lại lịch sử trong `input`, hoặc dùng `previous_response_id` để server nối tiếp lượt trước. Lựa chọn thứ hai giảm code phía client nhưng không có nghĩa là miễn phí token; hãy đo `usage` của từng request để biết context được tính bao nhiêu.
Bảng ánh xạ khi chuyển đổi
| Chat Completions | Responses | Ghi chú |
|---|---|---|
| `messages` role system | `instructions` | Tách riêng khỏi lịch sử |
| `messages` user/assistant | `input` items | Giữ nguyên role |
| `max_tokens` / `max_completion_tokens` | `max_output_tokens` | Bao gồm reasoning token |
| `tools` + `tool_calls` | `tools` + `function_call` | Astra/Sol bắt buộc Responses |
| message role tool | `function_call_output` | Item riêng, có `call_id` |
| Không có | `previous_response_id` | Trạng thái do server giữ |
Ba dòng cuối là phần dễ làm sai nhất. Tool result không còn là một message trong mảng; nó là item đầu vào riêng, phải khớp `call_id` với lời gọi trước đó. Nếu bạn map sai, model sẽ thấy một đoạn văn lạ thay vì kết quả tool, và hành vi sẽ khó đoán.
Tool calling: nơi hai API thật sự khác nhau
Trên Chat Completions, tool là một mảng JSON Schema và model trả về `tool_calls` trong message. Trên Responses, tool cũng là JSON Schema, nhưng kết quả trả về là item `function_call` trong `output`, và bạn gửi kết quả bằng item `function_call_output`. Vòng lặp vì thế rõ ràng hơn nhưng cũng dài hơn về code.
Điều cần nhớ: hosted tools và encrypted reasoning chỉ có trên Responses. Nếu sản phẩm của bạn cần web search, file search hoặc chạy code do nhà cung cấp host, bạn không có lựa chọn nào khác. Nếu bạn cần reasoning được mã hóa để không lưu nội dung suy luận ở client, đó cũng là tính năng chỉ Responses có.
Về phía Anthropic và Google, khái niệm tương đương là tool use trong Messages API và function calling trong Gemini API. Chúng không phải bản sao của Responses, nên khi thiết kế lớp trừu tượng cho nhiều nhà cung cấp, hãy trừu tượng theo khái niệm “tool call” chứ đừng cố mô phỏng đúng hình dạng của một API.
Khi nào vẫn nên giữ Chat Completions
- Client tương thích OpenAI. Nhiều gateway và thư viện bên thứ ba chỉ hiểu `/v1/chat/completions`. Nếu bạn đang phát hành SDK nội bộ, đây là lý do chính đáng để giữ một adapter legacy.
- Tác vụ một lượt, không tool, không trạng thái. Một lệnh phân loại hay trích xuất đơn giản không cần Responses; giữ đường cũ giúp giảm bề mặt code.
- Đường dự phòng khi provider sự cố. Nếu bạn có nhiều nhà cung cấp tương thích OpenAI, Chat Completions là hình dạng chung dễ nhất để fallback.
- Di sản chưa có ngân sách chuyển đổi. Hợp lý về mặt vận hành, nhưng phải ghi rõ ngày rà soát lại; “tạm thời” không nên kéo dài quá một quý.
Ngược lại, đừng giữ Chat Completions cho agent, cho tính năng cần hosted tools, hay cho bất cứ thứ gì chạy trên Astra và Sol với tool calling. Ở ba trường hợp đó, đường cũ không phải lựa chọn rẻ hơn mà là lựa chọn không hoạt động.
Checklist chuyển từ Chat Completions sang Responses
- Pin `openai` 3.46.0 và đọc đúng tài liệu của phiên bản đó trước khi đổi endpoint.
- Map `messages` sang `instructions` cộng `input`; đừng gửi system message lẫn trong lịch sử.
- Đổi parser từ `choices[0].message.content` sang duyệt `output` và content part `output_text`.
- Chuyển tool result sang item `function_call_output`, khớp `call_id` với `function_call`.
- Quyết định rõ: gửi lại lịch sử hay dùng `previous_response_id`; đo `usage` trong cả hai trường hợp.
- Xoá toàn bộ code Assistants; không còn endpoint để gọi.
- Chạy lại bộ eval và so sánh chi phí, vì reasoning token giờ nằm trong ngân sách output.
- Kiểm tra lại `reasoning.effort` cho từng tác vụ; mức mặc định của Sol là `medium`.
Cạm bẫy khi bảo trì code legacy
- Giữ Chat Completions vì “đang chạy được”. Nó chạy được cho tác vụ không tool; với agent, bạn đang tự chặn đường nâng cấp model.
- Đổi endpoint mà giữ parser cũ. Không có `choices` trong Responses; lỗi này thường xuất hiện ngay lần gọi đầu tiên nhưng chỉ ở nhánh xử lý thành công, nên test lỗi có thể không bắt được.
- Gửi lại toàn bộ lịch sử mỗi lượt. Đây là cách nhanh nhất để chạm ngưỡng 272K và tăng chi phí mà không ai để ý.
- Nghĩ `previous_response_id` miễn phí token. Nó giảm code, không giảm hóa đơn; luôn đọc `usage`.
- Hạ `reasoning_effort` xuống none để cứu tool trên Chat. Với Astra và Sol, đây không phải đường hợp lệ; hãy chuyển API thay vì hạ chất lượng.
- Để sót code Assistants. Nó không còn chạy; hãy grep toàn bộ repo trước khi lên kế hoạch migration.
Nhìn tới 2027
Hướng đi đã rõ: API có trạng thái, tool do nhà cung cấp host, và reasoning được mã hóa sẽ là mặc định. Chat Completions nhiều khả năng tiếp tục được phục vụ cho tương thích, nhưng mọi tính năng mới sẽ xuất hiện trên Responses trước. Điều đó có nghĩa chi phí bảo trì hai đường sẽ tăng, và dự án nào chuyển sớm sẽ ít phải viết lại hơn.
Với các nhà cung cấp khác, xu hướng tương tự: Messages API của Anthropic đã có thinking kiểu `adaptive`, còn Google gom function calling vào một SDK duy nhất cho Developer API và Vertex AI. Lớp trừu tượng của bạn nên giả định “trạng thái phiên là chuyện của server” ngay từ hôm nay.
Việc cần làm ngay
- Chọn một endpoint duy nhất cho code mới và ghi vào tài liệu kiến trúc.
- Đánh dấu mọi file còn gọi Chat Completions, kèm lý do giữ lại.
- Viết một test khẳng định parser đọc được cả `output_text` lẫn `function_call`.
- Thêm log `usage` trước khi tối ưu bất cứ thứ gì.
Để hiểu vì sao độ dài context ảnh hưởng trực tiếp đến chi phí, đọc Nắm Vững Khả Năng và Độ Dài Ngữ Cảnh Của Các Mô Hình OpenAI. Nếu bạn đang xây agent có tool, bài Tạo Đặc Vụ AI Thông Minh Hơn Với OpenAI Functions và Tools là bước tiếp theo. Và khi cần so sánh chi phí giữa các model, xem Tokens, Cửa Sổ Ngữ Cảnh và Chi Phí API.