BroadRouter
Mulakan

Kunci idempotensi (idempotency key)

Dikemas kini

Kunci idempotensi ialah nilai unik, biasanya ID rawak seperti UUID, yang dilampirkan oleh klien pada permintaan yang mengubah keadaan, seperti pembayaran atau pembelian. Jika permintaan yang sama dihantar semula dengan kunci yang sama, pelayan memulangkan hasil asal dan tidak melakukan tindakan itu dua kali.

Juga dikenali sebagai: idempotency key, Idempotency-Key header, idempotency token, idempotent request, idempotent retry, permintaan idempoten

Rangkaian gagal di tempat yang paling teruk: selepas pelayan bertindak tetapi sebelum anda menerima jawapan. Kunci idempotensi menjadikan cubaan semula selamat.

Cara ia berfungsi

Klien mencipta kunci unik untuk satu tindakan yang dikehendaki dan menghantarnya bersama permintaan. Pelayan menyimpan kunci itu bersama hasilnya. Jika kunci yang sama tiba lagi, pelayan memainkan semula hasil yang disimpan dan tidak bertindak sekali lagi.

Kumpulan kerja IETF HTTPAPI sedang menyeragamkan ini sebagai pengepala permintaan Idempotency-Key (draf 08, Oktober 2026, belum menjadi RFC). Ia menerangkan kunci itu sebagai “a unique value generated by the client which the resource uses to recognize subsequent retries of the same request” (Terjemahan BroadRouter: “nilai unik yang dijana oleh klien yang digunakan oleh sumber untuk mengenal pasti cubaan semula seterusnya bagi permintaan yang sama”) dan mengesyorkan UUID atau ID rawak yang serupa. Kes ralat dalam draf itu:

Situasi Status
Kunci tiada apabila diperlukan 400 Bad Request
Permintaan asal masih diproses 409 Conflict
Kunci diguna semula dengan badan berbeza 422 Unprocessable Content

Builders’ Library AWS membuat perkara yang sama dari sisi klien: “APIs with side effects aren’t safe to retry unless they provide idempotency.” (Terjemahan BroadRouter: “API yang mempunyai kesan sampingan tidak selamat dicuba semula melainkan ia menyediakan idempotensi.”)

Mengapa ia penting

Cubaan semula dengan backoff eksponen ialah amalan standard, dan banyak SDK mencuba semula secara automatik. Tanpa idempotensi, cubaan semula selepas tamat masa boleh mencipta dua pesanan atau dua caj. Dengan kunci, cubaan semula selamat walau apa pun yang dilakukan oleh cubaan pertama. Ini menjadikannya alat teras untuk ejen dan skrip yang membeli, menempah atau mencipta sesuatu tanpa manusia memerhati.

Di BroadNet Inference

BroadNet menggunakan corak ini untuk membeli kunci sejam. POST /portal/keys/hourly menerima request_id dalam badan JSON, dan dokumentasinya menyatakan “Idempotency is required for money safety” (Terjemahan BroadRouter: “Idempotensi diperlukan untuk keselamatan wang”):

curl -X POST https://inference.broadnet.ai/portal/keys/hourly \
  -H "Authorization: Bearer <portal-credential>" \
  -H "Content-Type: application/json" \
  -d '{"request_id":"order-20260920-001","label":"kiosk-1"}'

Menggunakan semula request_id tidak mencipta atau mengenakan caj untuk kunci lain. Selepas tamat masa, sambungan terputus, 409 mint_in_progress atau 5xx, cuba semula dengan request_id yang sama. Main semula memulangkan already_issued: true dan alias kunci; hanya respons berjaya yang pertama mengandungi kunci mentah. Dokumentasinya menyatakan: “Never generate a replacement id until the original result is known.” (Terjemahan BroadRouter: “Jangan sekali-kali menjana id pengganti sehingga hasil asal diketahui.”)

BroadNet tidak mendokumenkan kunci idempotensi untuk /v1/chat/completions atau transkripsi. Lihat kod ralat dan cubaan semula untuk perkara yang patut dicuba semula di sana, dan had kadar untuk sebab cubaan semula membuta tuli boleh memburukkan 429.

Soalan lazim

Bilakah saya patut menjana kunci idempotensi baharu?

Hanya untuk tindakan baharu yang dikehendaki. Guna kunci yang sama untuk setiap cubaan semula bagi satu tindakan, dan jangan cipta kunci baharu sehingga anda tahu hasil cubaan pertama.

Adakah permintaan chat completion LLM memerlukan kunci idempotensi?

Menjana teks tiada kesan sampingan yang kekal, jadi permintaan chat yang diulang biasanya hanya menelan kos token sekali lagi. Kunci ini penting untuk panggilan yang mengenakan caj wang atau mencipta sumber. BroadNet mendokumenkannya hanya untuk pembelian kunci sejam, bukan untuk chat completions.

Apakah yang berlaku jika saya guna semula kunci dengan badan permintaan yang berbeza?

Draf IETF menyatakan pelayan patut menolaknya dengan 422 Unprocessable Content, kerana kunci itu sudah terikat pada permintaan lain.

Baca sebagai MarkdownTanya ChatGPTTanya ClaudeTanya Perplexity