Structured Outputs pada API AI: Menjaga Respons JSON Tetap Valid dan Konsisten

Model kecerdasan buatan sering diminta mengembalikan data dalam format JSON untuk mengisi formulir, membuat ringkasan terstruktur, atau meneruskan hasil ke layanan lain. Masalahnya, instruksi seperti “jawab dalam JSON” saja belum menjamin hasil selalu valid. Model dapat menambahkan penjelasan di luar objek, mengubah nama properti, menghilangkan nilai, atau menghasilkan tipe data yang tidak sesuai harapan aplikasi.

Structured Outputs adalah pendekatan untuk membatasi bentuk respons model berdasarkan skema yang ditentukan. Dengan dukungan API yang sesuai, pengembang dapat meminta keluaran yang mengikuti struktur tertentu, bukan sekadar berharap model mematuhi instruksi teks. Teknik ini membantu integrasi AI menjadi lebih dapat diprediksi, meskipun tetap tidak menggantikan validasi, penanganan kesalahan, dan pemeriksaan makna data.

Apa itu Structured Outputs?

Structured Outputs mengikat keluaran model pada struktur data yang didefinisikan, umumnya menggunakan JSON Schema. Skema menjelaskan properti yang diperbolehkan, tipe nilainya, apakah sebuah properti wajib, serta batasan lain yang didukung oleh penyedia API. Misalnya, aplikasi pemesanan dapat mengharapkan objek dengan properti nama_produk, jumlah, dan perlu_konfirmasi. Respons dengan bentuk berbeda bisa ditolak atau ditangani sebelum mencapai proses bisnis.

Structured Outputs berbeda dari mode JSON biasa. Mode JSON berfokus pada sintaks agar respons berbentuk JSON yang dapat diurai, sedangkan keluaran terstruktur juga menargetkan kesesuaian terhadap skema. Dukungan dan batasan fitur tidak sama di semua penyedia atau model; periksa dokumentasi API yang digunakan sebelum merancang alur produksi.

Mengapa format yang konsisten penting?

• Mengurangi kegagalan parsing: aplikasi tidak perlu menebak bagian mana dari jawaban yang merupakan objek JSON.
• Mempermudah validasi: struktur dan tipe data dapat diperiksa dengan aturan yang eksplisit.
• Menjaga kontrak antarlayanan: frontend, backend, dan layanan analitik menerima bentuk data yang lebih stabil.
• Meningkatkan keterujian: skema dapat digunakan sebagai dasar pengujian otomatis ketika prompt, model, atau kode berubah.

Namun, JSON yang valid belum tentu benar secara faktual. Model bisa menghasilkan nilai yang secara sintaks sesuai skema tetapi keliru, tidak lengkap secara konteks, atau tidak sesuai aturan bisnis. Karena itu, kesesuaian bentuk dan kebenaran isi harus diperlakukan sebagai dua pemeriksaan terpisah.

Merancang JSON Schema yang praktis

Mulailah dari kebutuhan aplikasi, bukan dari semua informasi yang mungkin bisa dihasilkan model. Tentukan properti minimum yang benar-benar dibutuhkan, pilih tipe data yang tepat, dan nyatakan kolom wajib secara jelas. Hindari skema terlalu longgar yang menerima hampir semua bentuk respons, tetapi jangan pula membuatnya terlalu rumit sehingga sulit dipelihara.

Contoh sederhana untuk hasil klasifikasi tiket dukungan:

{
  "type": "object",
  "properties": {
    "kategori": {
      "type": "string",
      "enum": ["akun", "pembayaran", "teknis", "lainnya"]
    },
    "prioritas": {
      "type": "string",
      "enum": ["rendah", "sedang", "tinggi"]
    },
    "ringkasan": {
      "type": "string"
    }
  },
  "required": ["kategori", "prioritas", "ringkasan"],
  "additionalProperties": false
}

Contoh ini menggambarkan prinsip umum JSON Schema. API tertentu mungkin mensyaratkan aturan tambahan, misalnya semua properti harus wajib atau hanya mendukung subset kata kunci skema. Sesuaikan definisi dengan dokumentasi platform, lalu uji skema tersebut pada contoh input nyata dan kasus tepi.

Alur implementasi yang disarankan

1. Definisikan kontrak: tulis skema dan dokumentasikan arti setiap properti, termasuk satuan, nilai yang diperbolehkan, dan bagaimana nilai yang tidak diketahui direpresentasikan.
2. Kirim skema ke API: gunakan parameter Structured Outputs atau fitur keluaran terstruktur yang disediakan model. Jangan hanya menaruh contoh JSON dalam prompt jika API mendukung pembatasan skema secara langsung.
3. Periksa status respons: tangani penolakan model, respons terpotong, batas token, timeout, dan status API lainnya. Jangan menganggap setiap respons berisi objek yang siap dipakai.
4. Validasi di sisi aplikasi: parse hasil, periksa struktur sesuai kebutuhan, lalu jalankan aturan bisnis seperti batas jumlah, kepemilikan sumber daya, atau izin pengguna.
5. Uji perubahan: buat pengujian untuk respons normal, data ambigu, nilai kosong, permintaan yang ditolak, dan perubahan versi skema.

Dalam implementasi produksi, jangan meneruskan hasil model langsung ke perintah sensitif seperti pembayaran, penghapusan data, atau perubahan hak akses. Jadikan hasil AI sebagai masukan yang harus melewati otorisasi dan validasi deterministik. Untuk konteks kontrak dan dokumentasi API, lihat juga panduan OpenAPI Overlays; detail format keluaran dapat diperiksa pada panduan Structured Outputs resmi OpenAI. Untuk tindakan berisiko tinggi, tambahkan konfirmasi manusia atau mekanisme persetujuan sesuai dampaknya.

Kesimpulan

Structured Outputs membantu menjaga bentuk respons sesuai skema, tetapi tidak menjamin bahwa setiap nilai benar atau lengkap. Validasi hasil, tangani penolakan dan kegagalan secara eksplisit, bedakan nilai kosong dari data yang tidak diketahui, dan jangan biarkan aplikasi memperlakukan keluaran model sebagai fakta tepercaya tanpa pemeriksaan.