Membuat operasi API AI idempoten

Membuat operasi API AI idempoten: panduan production dengan keputusan eksplisit, artefak reusable, uji gagal, sinyal operasi, dan batas berbasis sumber.

Membuat operasi API AI idempoten

Membuat operasi API AI idempoten: panduan production dengan keputusan eksplisit, artefak reusable, uji gagal, sinyal operasi, dan batas berbasis sumber.

Jawaban langsung

Terapkan Membuat operasi API AI idempoten sebagai kontrak kontrol keandalan, bukan konfigurasi sekali pakai. Kunci protokol, owner, bukti, dan rollback sebelum traffic dipindah. Titik kontrol: logical_request_id, idempotency_key, request_digest, durable_result.

Kesimpulan dikunci oleh tabel kontrak dan contoh deterministik. ai-api-idempotency tidak boleh rollout bila kontrol wajib tidak memiliki bukti wire, readback persisten, atau owner.

Cakupan dan tanggung jawab

Pisahkan tugas client dari control plane. Client memiliki file atau variabel; gateway memiliki autentikasi, routing, limit, akuntansi, dan attempt; provider memiliki protokol native dan kemampuan yang berubah. Satu respons teks hanya membuktikan satu jalur.

Artikel memiliki keputusan, risiko, dan verifikasi; dokumentasi live memiliki perintah dan langkah UI yang berubah. Ini membentuk pohon kemampuan tanpa menggandakan owner intent pencarian.

Catatan owner halaman ini adalah ai-api-idempotency; kontrol tetapnya logical_request_id, idempotency_key, request_digest, durable_result. Setiap nilai ditinjau pada batas wire atau status persisten, bukan disimpulkan dari label pemasaran.

Artefak praktis: Membuat operasi API AI idempoten

Catatan review berikut adalah artefak yang dikirim. Nilai teknis eksplisit memungkinkan perbandingan konfigurasi, bukti wire, dan status persisten tanpa screenshot.

Kontrol Keputusan tetap Bukti
key_scope principal_plus_operation_plus_idempotency_key principal_id + operation + key
request_binding canonical_digest_must_match request_digest + schema_version
reservation atomic_pending_record_before_side_effect unique_constraint + created_at + owner
replay same_key_same_digest_returns_durable_result original_result_id + replay_count
conflict same_key_different_digest_rejected conflict_status + both_digests_without_payload
recovery stale_pending_requires_owned_reconciliation lease + side_effect_receipt + terminal_write

Contoh deterministik

Contoh hanya memakai placeholder dan input deterministik. Ganti dengan identifier yang ditinjau, bukan secret atau konten pelanggan, dan simpan snapshot tepat.

BEGIN;
INSERT INTO operation_ledger
  (principal_id, operation, idempotency_key, request_digest, status)
VALUES
  (:principal, :operation, :key, :digest, 'pending')
ON CONFLICT DO NOTHING;
-- only the transaction that owns the new row may perform the side effect
-- persist terminal result before returning it to the caller
COMMIT;

Tahap verifikasi

Jalankan tahap secara berurutan. Keberhasilan tahap akhir tidak mengganti batas yang hilang; setiap attempt harus terhubung ke satu permintaan logis.

  1. Bekukan client, kebijakan gateway, alias model, route, dan baseline observasi. Bukti untuk key_scope: terapkan principal_plus_operation_plus_idempotency_key dan simpan principal_id + operation + key.
  2. Jalankan probe positif deterministik dan simpan respons, request ID, route, status akhir, dan usage. Bukti untuk request_binding: terapkan canonical_digest_must_match dan simpan request_digest + schema_version.
  3. Jalankan kasus negatif, limit, atau disconnect pasangannya dan periksa lapisan gagal. Bukti untuk reservation: terapkan atomic_pending_record_before_side_effect dan simpan unique_constraint + created_at + owner.
  4. Ulangi lewat protokol nyata; jangan simpulkan dukungan native dari endpoint lain. Bukti untuk replay: terapkan same_key_same_digest_returns_durable_result dan simpan original_result_id + replay_count.
  5. Rollout ke cohort terbatas dengan owner, kedaluwarsa, ambang berhenti, dan rollback. Bukti untuk conflict: terapkan same_key_different_digest_rejected dan simpan conflict_status + both_digests_without_payload.
  6. Baca ulang konfigurasi dan akuntansi persisten; hapus akses dan data sementara. Bukti untuk recovery: terapkan stale_pending_requires_owned_reconciliation dan simpan lease + side_effect_receipt + terminal_write.

Kegagalan yang harus dicegah

Setiap poin berikut memblokir publikasi. HTTP 200, dashboard, atau satu demo tidak menggantikan kontrol ini.

  • memory_only_deduplication — Jika memory_only_deduplication terjadi, hentikan rollout dan gunakan owner, bukti, serta rollback yang ditetapkan; probe sukses tidak membatalkannya.
  • key_without_digest — Jika key_without_digest terjadi, hentikan rollout dan gunakan owner, bukti, serta rollback yang ditetapkan; probe sukses tidak membatalkannya.
  • check_then_act_race — Jika check_then_act_race terjadi, hentikan rollout dan gunakan owner, bukti, serta rollback yang ditetapkan; probe sukses tidak membatalkannya.
  • model_call_id_as_key — Jika model_call_id_as_key terjadi, hentikan rollout dan gunakan owner, bukti, serta rollback yang ditetapkan; probe sukses tidak membatalkannya.

Sinyal dan kondisi berhenti

Amati sukses dan dampak buruk bersama. Ambang adalah kebijakan workload; tetapkan SLO dan denominator sebelum jendela.

Sinyal Ambang Tindakan
duplicate_side_effect_count 0 stop_operation_and_reconcile
idempotency_digest_conflicts review_each_event reject_and_alert_owner
stale_pending_age <_owned_recovery_deadline reconcile_with_external_receipt
replay_result_mismatch 0 disable_endpoint

Batas Modelflare

Modelflare memusatkan routing kompatibel dan native, key terbatas, grup, usage, dan kegagalan. Channel terkonfigurasi tidak membuktikan semua field, alias, janji retensi, region, atau fallback. Verifikasi secara native dan gunakan settlement persisten sebagai kebenaran biaya.

Ini metode implementasi, bukan sertifikasi, kesimpulan hukum, riwayat uptime, atau benchmark universal. Periksa kontrak, model, harga, retensi, dan region pada T-1; pindahkan tanggal bila fakta inti berubah.

Lanjutkan cluster topik

Artikel induk membahas keputusan luas, artikel saudara langkah berikutnya, dan dokumentasi konfigurasi saat ini. Link isi diperlukan karena managed CMS belum memiliki related-slug.

Pertanyaan umum

Membuat operasi API AI idempoten: Apakah satu permintaan sukses cukup?

Tidak. Kasus negatif, rollout terbatas, readback persisten, dan kondisi berhenti adalah gate terpisah.

Membuat operasi API AI idempoten: Apakah model dan harga dikunci berbulan-bulan?

Tidak. Gunakan placeholder atau snapshot dan validasi ulang pada T-1.

Membuat operasi API AI idempoten: Bukti apa yang disimpan?

ID tanpa data sensitif, versi, waktu, status, usage, biaya final, dan keputusan review.

Sumber dan tanggal verifikasi

Sumber diperiksa pada 2026-08-07. Sumber menetapkan kontrak dan prinsip, bukan route yang belum diuji atau keadaan masa depan.