Responses API vs Chat Completions: Perbezaan dan Panduan Migrasi Praktikal (2026)

OpenAI mengesyorkan Responses API untuk semua projek baharu sambil menyatakan Chat Completions masih disokong. Kedua-dua endpoint akan wujud bersama untuk jangka panjang, tetapi struktur medan, pengurusan state dan sistem tool berbeza. Panduan ini memecahkan perbezaan kepada empat dimensi, menunjukkan kod tepat yang perlu diubah semasa migrasi, dan diakhiri jadual keputusan ikut senario — setiap contoh berjalan terus pada endpoint EXAIV

Definisi: Responses API ialah antara muka bersatu OpenAI yang diperkenalkan selepas Chat Completions: input dalam array input, output ialah senarai item output bertipe, state perbualan disimpan pihak server secara lalai (store), dan hosted tools seperti carian web, carian fail dan interpreter kod tertanam di dalamnya. Chat Completions ialah protokol tanpa state: setiap request membawa keseluruhan sejarah messages dan klien mengurus konteks sendiri.

Satu jadual untuk semua perbezaan teras

Perbandingan kod: tugasan sama, dua bentuk

Chat Completions (endpoint EXAIV /api/ai/v1/chat/completions):

curl https://exaiv.com/api/ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-6-sol",
    "messages": [
      { "role": "user", "content": "Terangkan apa itu AI gateway dalam satu ayat." }
    ]
  }'

Responses API (endpoint EXAIV /api/ai/v1/responses):

curl https://exaiv.com/api/ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-6-sol",
    "input": "Terangkan apa itu AI gateway dalam satu ayat."
  }'

Pada peringkat SDK: client.chat.completions.create(...) bertukar kepada client.responses.create(...); pembacaan hasil berubah dari completion.choices[0].message.content kepada response.output_text. Rujukan penuh: Chat Completions dan Responses

Migrasi empat langkah

1. messages → input: request teks biasa hantar terus string; request bersejarah namakan semula array messages kepada input, kekalkan struktur role/content
2. Ubah laluan bacaan hasil: choices[0].message.content → lelaran output tapis type === "message", atau guna medan mudah output_text
3. Pindahkan system prompt ke instructions: mesej role: "system" dalam Chat mempunyai parameter tahap atas tersendiri dalam Responses
4. Tulis semula definisi tool: kedua-dua format serupa tetapi tidak identik — semak medan demi medan. Hosted tools Responses (web_search dll.) diaktifkan dengan nama, tanpa gelung orkestrasi sendiri

Pilih yang mana, ikut senario

EXAIV menyediakan kedua-dua endpoint dengan kunci API yang sama, jadi anda tidak perlu memilih pihak selama-lamanya: trafik sedia ada kekal Chat Completions, ciri baharu guna Responses, dan tukar model asas dari halaman model

Mengapa wujud dua interface

Konteks evolusi membantu membuat keputusan. Chat Completions ialah interface awal OpenAI; kerana strukturnya ringkas dan boleh digunakan merentas penyedia, ia menjadi standard de facto yang ditiru seluruh industri — hampir semua vendor model hari ini menyediakan endpoint gaya messages. Responses API ialah reka bentuk semula OpenAI untuk era agen: kemampuan "model mungkin perlu buat beberapa perkara" (panggil tool, carian, jalankan kod) menjadi warganegara kelas pertama dalam lapisan interface, dengan pengurusan state dan pelaksanaan tool kembali ke pihak server. Kedua-duanya menyasarkan senario berbeza — itulah sebabnya mereka wujud bersama.

Jadual pemetaan parameter rujukan pantas

Koresponden yang paling kerap digunakan semasa migrasi:

Medan yang tepat ada di dokumen rujukan; semak satu demi satu semasa migrasi.

Pengurusan state secara mendalam: store dan previous_response_id

Inilah perbezaan falsafah paling mendalam antara dua generasi. Chat Completions mengandaikan "server tidak mengingati apa-apa": setiap giliran anda menghantar semula seluruh sejarah, dan pengurusan tetingkap konteks serta kawalan kos berada di klien anda. Responses API menyimpan perbualan di pihak server secara lalai (store: true); giliran berikutnya hanya merujuk previous_response_id, dan server meneruskan dengan perbualan serta konteks tool yang lengkap.

Kesan praktikal kepada pembangun:

• Kod berkurang: modul yang menyelenggara array messages, memangkas sejarah dan memampatkan konteks boleh dipadam
• Token berkurang: server guna semula konteks sedia ada; kos menghantar semula lenyap
• Perhatikan pematuhan: data perbualan tersimpan di pihak server; pasukan dengan keperluan data-residency boleh guna store: false, dengan pertukaran kembali ke mod hantar penuh setiap giliran

Lima perangkap migrasi yang kerap

1. Hasil kosong: laluan bacaan belum diubah — kandungan kini dalam output, bukan choices[0].message.content
2. Tool call gagal senyap: format definisi tools kedua-dua generasi berbeza; menyalin medan mentah gagal tanpa suara — semak satu demi satu
3. Penghurai SSE rosak: jenis event benar-benar berbeza; logik delta tidak boleh dipakai atas response.output_text.delta
4. Ralat berbilang calon: parameter n dibuang dalam Responses; logik yang bergantung padanya perlu ditulis semula atau kekal di Chat
5. Kebocoran state: store diaktifkan secara lalai, data ujian turut tersimpan — senario sensitif data matikannya secara jelas

FAQ

Migrasi streaming, event demi event

Nama event ialah tempat paling banyak masa migrasi dibelanjakan. Peta ringkasnya:

Dua perbezaan struktural untuk dihadam: delta sisi Chat ialah serpihan tanpa nama yang anda susun sendiri, manakala event Responses menamakan apa yang dibawanya; dan dalam Responses, satu giliran berbilang tool ialah satu kitaran request, bukan beberapa pusingan request/response. Penghurai SSE, logik cuba semula dan pengendalian timeout semuanya perlu ditulis semula terhadap nama event baharu — bahagian inilah yang selalu kos lebih daripada jangkaan.

Guna Responses melalui gateway

Tiga perkara berbalas diketahui apabila endpoint diproxy:

• Hosted tools dilaksanakan di hulu: carian web, interpreter kod dan rakan-rakan berjalan di pihak OpenAI; gateway meneruskan request dan menyalin hasil kembali tanpa disentuh
• State pihak server kekal di hulu: previous_response_id merujuk state tersimpan di pihak OpenAI; gateway meneruskannya secara telus
• Kunci dan pengebilan milik gateway: satu kunci EXAIV berlaku untuk kedua-dua endpoint, dibilkan per model dan token tanpa mengira endpoint — harga masa nyata di halaman harga

Senarai semak pra-migrasi

Lima soalan mengikut turutan — berhenti pada jawapan "belum" pertama dan baiki lapisan itu dahulu:

1. Adakah panggilan teks biasa berjaya di endpoint baharu (tiada tool, tiada streaming)?
2. Adakah laluan bacaan hasil memulangkan teks sebenar (bukan undefined)?
3. Adakah definisi tool parse tanpa ralat skema?
4. Adakah satu pusingan tool penuh selesai (panggil → laksana → sambung)?
5. Adakah streaming dirender penuh dari mula hingga akhir dengan nama event baharu?

Garis masa migrasi yang realistik

Untuk codebase bersaiz sederhana dengan tools dan streaming, beginilah rupa migrasi tenama tiga hari:

Hari pertama — teks sahaja. Halakan salinan satu aliran ke endpoint baharu. messages menjadi input, laluan hasil menjadi output_text. Jalankan ujian sedia ada. Kebanyakan pasukan mendapati panggilan teks biasa lulus tanpa kejutan; matlamat hari ini hanya membuktikan pengangkutan berfungsi.

Hari kedua — tools. Tulis semula satu definisi tool dalam format baharu dan jalankan satu kitaran penuh: model meminta panggilan, anda melaksanakannya, anda menyambung giliran yang sama. Jangka menghabiskan sebahagian besar hari di sini — inilah kerja pemetaan medan yang diperingatkan jadual di atas. Pastikan ralat tool muncul dengan betul, bukan senyap.

Hari ketiga — streaming. Tukar penghurai SSE kepada event bernama. Render hujung-ke-hujung dalam UI sebenar anda. Cubit semula dan timeout ditala mengikut perlakuan sebenar, bukan andaian.

Apa yang sengaja dielakkan garis masa ini: memigrasi semua aliran sekaligus, menulis semula orkestrasi yang boleh kekal di Chat Completions suku tahun lagi, dan menguji streaming paling akhir pada hari Jumaat. Trafik boleh beralih aliran demi aliran — melalui gateway, ikut request — selagi kedua-dua endpoint berjalan selari.

FAQ

Skala: bila patut menahan diri daripada migrasi

Tidak semua kod layak dimigrasi bulan ini, dan mengakuinya juga sebahagian daripada rancangan baik. Tiga isyarat untuk menahan diri:

• Tiada keperluan hosted tools: jika aliran anda semata-mata teks masuk-teks keluar dengan orkestrasi sendiri yang stabil, nilai migrasi ialah masa depan semata — nyata tetapi tidak mendesak
• Bergantung pada n > 1: parameter itu tiada dalam Responses; menulis semula logik pemilihan calon ialah projek tersendiri
• Kontrak keluaran ketat: jika penghurai anda menjangka bentuk choices di banyak tempat, kos sentuhan luas melebihi manfaat hari ini

Catat aliran-aliran itu, kunci ujiannya, dan semak semula setiap suku tahun. Kedua-dua endpoint tidak akan ke mana-mana.

FAQ

Bacaan berkaitan

• Rujukan Chat Completions API
• Rujukan Responses API
• Rujukan Anthropic Messages API