Guardrails AI: Validasi Output Terstruktur dengan JSON Schema

Guardrails AI adalah pustaka Python open source yang dirancang untuk membuat output LLM andal dan dapat diprediksi. Ia membungkus panggilan API LLM apa pun - OpenAI, Anthropic, Cohere, model lokal - dengan pipeline validasi yang memeriksa respons model terhadap skema yang ditentukan pengguna dan kumpulan validator tingkat field sebelum mengembalikan hasilnya ke kode aplikasi Anda.

Abstraksi intinya adalah objek `Guard`. Anda membangun Guard dari model Pydantic atau definisi JSON Schema, secara opsional melampirkan validator ke field tertentu, lalu memanggil Guard alih-alih memanggil LLM secara langsung. Guard menangani konstruksi prompt, parsing respons, validasi, dan permintaan ulang otomatis saat validasi gagal - semuanya dalam satu pipeline yang dapat diaudit.

Posisi Guardrails AI dalam stack LLM

Guardrails berada di antara kode aplikasi Anda dan penyedia LLM. Ia tidak menggantikan model dan tidak mengubah cara model dipanggil - ia menambahkan lapisan penegakan kontrak di sekitar panggilan. Bayangkan sebagai validator skema untuk respons API, kecuali "API"-nya adalah model bahasa yang menghasilkan bahasa natural, dan "respons"-nya perlu diurai menjadi data terstruktur sebelum bisa divalidasi.

• Guard: antarmuka utama - membungkus panggilan LLM dan menerapkan skema + validator.
• ValidationOutcome: objek hasil yang dikembalikan panggilan Guard - memuat output tervalidasi, status lulus/gagal, dan error field.
• Validator: callable yang dilampirkan ke field skema dan menegakkan aturan tertentu (tipe, rentang, regex, pemeriksaan eksternal).
• reask: mekanisme percobaan ulang - saat validasi gagal, Guardrails meminta ulang model dengan konteks galat.
• Hub: registri validator Guardrails - kumpulan kurasi validator komunitas yang dapat dipasang via `guardrails hub install`.

Masalah fundamentalnya adalah model bahasa dilatih menghasilkan teks yang masuk akal - bukan menghormati kontrak programatik. Bahkan saat Anda meminta model mengembalikan JSON, ia bisa menghasilkan output dengan field hilang, tipe nilai salah, field tambahan yang tidak diharapkan kode hilir Anda, nilai halusinasi di luar rentang yang diizinkan, atau fragmen teks di sekitar blok JSON yang merusak parsing sepenuhnya.

Lima mode kegagalan output LLM tanpa validasi

• Gagal parse: model membungkus JSON dengan pagar kode markdown, menambahkan komentar sebelum atau sesudah, atau menghasilkan JSON cacat yang tidak bisa diurai.
• Field wajib hilang: model mengabaikan field yang diminta diisi, menyebabkan KeyError atau error referensi nol pada kode hilir.
• Pelanggaran tipe: field yang diharapkan berupa angka datang sebagai string, atau boolean datang sebagai string "true" alih-alih literal `true`.
• Pelanggaran batasan nilai: field rating mengembalikan 11 padahal rentang yang diizinkan 1-10, atau field enum mengembalikan nilai di luar daftar yang ditentukan.
• Struktur halusinasi: model mengarang field tambahan atau menyarang objek secara berbeda dari yang dispesifikasikan skema.

Kegagalan mana pun dari daftar ini dapat merusak data hilir secara diam-diam, menyebabkan pengecualian runtime, atau membiarkan nilai buruk merambat ke logika bisnis. Untuk prototipe berisiko rendah, parsing optimis masih bisa diterima. Untuk pipeline produksi - ekstraksi faktur, parsing data klinis, sinyal deteksi fraud, pengayaan catatan pelanggan - setiap pelanggaran field adalah masalah kualitas data yang harus ditangkap dan ditangani.

Kontrak antara aplikasi Anda dan LLM hanya sekuat validasi yang Anda tegakkan pada setiap respons. Berharap bukanlah strategi validasi.

JSON Schema adalah bahasa yang dipakai Guardrails AI untuk menggambarkan wujud respons LLM yang valid. Definisi JSON Schema menetapkan struktur objek yang diharapkan - field mana yang ada, tipe mereka, mana yang wajib, dan batasan apa yang berlaku pada nilainya. Skema ini menjalankan dua peran: memberi tahu Guardrails cara memvalidasi respons yang diurai, dan dipakai Guardrails untuk membangun instruksi prompt yang memberi tahu model bentuk apa yang harus dihasilkan.

Yang dicakup JSON Schema untuk validasi LLM

Untuk kasus output terstruktur, kata kunci JSON Schema yang paling berguna adalah penegakan tipe, daftar field wajib, nilai enum, format string, dan rentang numerik. Secara bersamaan keduanya mencakup mayoritas aturan tingkat field yang perlu ditegakkan oleh tugas ekstraksi atau generasi.

{
  "$schema": "https://json-schema.org/draft-07/schema",
  "type": "object",
  "required": ["product_name", "rating", "sentiment", "summary"],
  "additionalProperties": false,
  "properties": {
    "product_name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "rating": {
      "type": "integer",
      "minimum": 1,
      "maximum": 5
    },
    "sentiment": {
      "type": "string",
      "enum": ["positive", "neutral", "negative"]
    },
    "summary": {
      "type": "string",
      "minLength": 20,
      "maxLength": 500
    },
    "pros": {
      "type": "array",
      "items": { "type": "string" },
      "maxItems": 5
    },
    "cons": {
      "type": "array",
      "items": { "type": "string" },
      "maxItems": 5
    }
  }
}

Skema ini memerintahkan Guardrails menolak respons apa pun di mana `rating` di luar 1-5, `sentiment` bukan salah satu dari tiga nilai yang diizinkan, atau `summary` kurang dari 20 karakter. Field yang tercantum dalam `required` harus ada. `additionalProperties: false` menolak field tambahan apa pun yang ditambahkan model atas inisiatifnya sendiri.

Membuat skema dari contoh respons

Saat merancang tugas ekstraksi baru, mendapatkan skema awal yang tepat butuh waktu. Jalan pintas yang praktis: jalankan prompt Anda sekali tanpa validasi, periksa JSON mentah yang dikembalikan model, lalu gunakan Generator JSON Schema untuk menyimpulkan skema Draft-07 secara otomatis dari contoh itu. Skema yang dihasilkan menangkap tipe, field wajib, dan struktur tersarang. Selanjutnya Anda menyempurnakannya - mengetatkan panjang string, menambah batasan enum, menetapkan batas numerik - alih-alih menulis setiap kata kunci dari nol.

Memahami pipeline validasi membantu Anda men-debug kegagalan dan mengonfigurasi strategi respons yang tepat untuk setiap field. Pipeline berjalan dengan urutan tetap pada setiap panggilan Guard: injeksi prompt, parsing respons, validasi JSON Schema, eksekusi validator tingkat field, dan perakitan hasil.

Guardrails AI mendukung dua gaya definisi skema: format Rail spec yang lama dan pendekatan model Pydantic yang modern. Memahami keduanya berguna karena Anda akan menemukan Rail spec di basis kode lama dan contoh komunitas, sementara Pydantic adalah jalur yang direkomendasikan untuk semua proyek baru sejak Guardrails v0.4+.

Model Pydantic sebagai skema Guard

Cara paling bersih mendefinisikan skema output Guardrails di Python adalah subclass `BaseModel` Pydantic. Model Pydantic punya ekspor JSON Schema bawaan, pemeriksaan tipe di IDE, dan sintaks Python yang familiar. Validator Guardrails dilampirkan dengan `Field()` milik Pydantic beserta metadata kustom, atau dengan mengimpor kelas validator langsung dari `guardrails`.

from pydantic import BaseModel, Field
from guardrails import Guard
from guardrails.hub import ValidRange, ValidChoices

class ProductReview(BaseModel):
    product_name: str = Field(description="Name of the product reviewed")
    rating: int = Field(
        description="Rating from 1 to 5",
        validators=[ValidRange(min=1, max=5, on_fail="reask")]
    )
    sentiment: str = Field(
        description="Overall sentiment of the review",
        validators=[ValidChoices(
            choices=["positive", "neutral", "negative"],
            on_fail="reask"
        )]
    )
    summary: str = Field(description="One paragraph summary of the review")

# Build the Guard from the Pydantic model
guard = Guard.from_pydantic(ProductReview)

# Call the LLM through the Guard
outcome = guard(
    openai.chat.completions.create,
    model="gpt-4o",
    messages=[{"role": "user", "content": f"Extract a review from: {raw_text}"}],
    num_reasks=2,
)

if outcome.validation_passed:
    review: ProductReview = outcome.validated_output
else:
    print(outcome.error)

Pipeline Pydantic ke JSON Schema

Di balik layar, Guardrails memanggil `model.model_json_schema()` untuk mengekspor model Pydantic Anda sebagai JSON Schema, lalu memakai skema itu baik untuk injeksi prompt maupun validasi respons. Artinya, setiap model Pydantic yang bisa Anda tulis otomatis menjadi kontrak Guardrails yang valid. Anda dapat menginspeksi skema yang dihasilkan sendiri - tempelkan contoh respons ke Generator JSON Schema untuk melihat skema setaranya, lalu bandingkan dengan output model Pydantic Anda.

Jika aplikasi Anda berbasis TypeScript tetapi memanggil layanan Guardrails Python, Konverter JSON ke Zod Schema menghasilkan skema Zod yang sesuai dari contoh JSON yang sama - berguna untuk memvalidasi kontrak yang sama di sisi klien tanpa menduplikasi definisi skema secara manual.

Rail spec - format warisan

Rail spec adalah berkas XML di mana setiap elemen `<output>` menjelaskan sebuah field dengan atribut `type` dan satu atau lebih elemen anak `<validator>`. Format ini mendahului integrasi Pydantic dan kurang ergonomis bagi pengembang Python, tetapi masih didukung sepenuhnya. Jika Anda mewarisi basis kode Guardrails yang memakai berkas `.rail`, Anda dapat memigrasikan tiap spesifikasi ke model Pydantic secara bertahap - perilaku validasinya setara.

Alur kerja Guardrails yang andal menggabungkan perancangan skema offline, pengujian lokal, dan pemantauan produksi. Fase perancangan skema - saat Anda mendefinisikan wujud output yang valid - adalah langkah terpenting dan paling diuntungkan oleh alat khusus.

Langkah 1: Rancang skema secara offline

Sebelum menulis kode Guardrails apa pun, tetapkan skema output Anda sebagai dokumen JSON Schema mandiri. Bekerja dulu di JSON Schema memungkinkan Anda mengiterasi kontrak secara independen dari panggilan LLM - Anda bisa memvalidasi payload contoh, menyesuaikan batasan, dan memastikan skema benar sebelum menghabiskan kredit API untuk pengujian.

Validator JSON Schema di Aback Tools memungkinkan Anda menempelkan JSON Schema dan payload kandidat, lalu langsung melihat galat validasi tingkat field. Gunakan untuk memastikan array `required`, daftar enum, dan rentang numerik Anda berperilaku sesuai harapan sebelum menerjemahkan skema menjadi model Pydantic. Pemformat & Validator JSON berguna untuk memeriksa bahwa berkas skema Anda sendiri adalah JSON yang valid secara sintaksis sebelum dirujuk.

Langkah 2: Hasilkan Pydantic dari JSON

Jika Anda mengumpulkan contoh respons LLM selama prototyping, Konverter JSON ke Dataclass / Pydantic Python menghasilkan model Pydantic dari payload JSON contoh dalam satu langkah. Alat ini menyimpulkan tipe field, menangani objek tersarang, dan menerapkan `Optional` di mana field bisa absen. Gunakan outputnya sebagai titik awal lalu tambahkan validator Guardrails ke setiap field sesuai batasan dalam JSON Schema Anda.

Langkah 3: Uji secara lokal dengan respons tiruan

Guard di Guardrails bisa dipanggil dengan callable Python apa pun, bukan hanya API LLM sungguhan. Selama pengembangan, berikan fungsi tiruan yang mengembalikan respons string tetap untuk menguji pipeline validasi tanpa panggilan API. Ini membuat iterasi atas perubahan skema, konfigurasi validator, dan prompt reask cepat dan gratis sebelum tersambung ke endpoint model berbayar.

Alur skema yang direkomendasikan dengan Aback Tools

• Generator JSON Schema - menyimpulkan skema awal dari contoh respons LLM.
• Validator JSON Schema - memvalidasi payload kandidat terhadap skema Anda secara offline.
• Pemformat & Validator JSON - memeriksa bahwa berkas skema berupa JSON valid sebelum dipakai.
• JSON ke Dataclass Python - menghasilkan model Pydantic dari payload contoh.
• JSON ke Zod Schema - menghasilkan kontrak sisi TypeScript untuk validasi klien.

Guardrails AI meningkatkan keandalan output terstruktur secara signifikan, tetapi bukan jaminan kebenaran. Memahami keterbatasannya membantu Anda merancang pipeline dengan fallback yang tepat alih-alih memercayai Guard tanpa syarat.

Lingkaran reask tidak selalu konvergen

Ketika model konsisten gagal pada validator tertentu, menambah lebih banyak percobaan reask tidak menolong - itu hanya menghabiskan lebih banyak kredit API untuk hasil yang sama. Beberapa mode kegagalan bersifat sistematis: model sungguhan tidak memahami sebuah batasan, atau batasan itu terlalu ketat untuk dipenuhi model secara andal dengan input yang diberikan. Audit tingkat kegagalan validator Anda dan perlakukan validator dengan tingkat kegagalan tinggi sebagai sinyal untuk meninjau definisi batasan atau prompt.

JSON Schema tidak menangkap galat semantik

Skema dapat memastikan `sentiment` salah satu dari `["positive", "neutral", "negative"]`, tetapi tidak dapat memverifikasi bahwa sentimen yang ditetapkan benar-benar tepat untuk teks input. JSON Schema dan validator menegakkan kontrak struktural dan sintaksis - keduanya tidak bisa menggantikan tinjauan manusia atau pemeriksaan kualitas hilir untuk akurasi konten. Gunakan Guardrails untuk menegakkan format dan struktur output, dan terapkan metrik evaluasi terpisah untuk kebenaran konten.

Overhead latensi dan biaya

Setiap percobaan reask adalah panggilan API LLM tambahan dengan biaya token penuh. Untuk Guard yang dikonfigurasi dengan `num_reasks=3`, ekstraksi dalam skenario terburuk dapat memicu empat panggilan LLM sebelum gagal. Pada pipeline throughput tinggi, overhead ini signifikan. Profilkan laju reask Guard Anda di staging sebelum dideploy ke produksi, dan tetapkan `num_reasks=0` untuk field yang tidak kritis di mana aksi on_fail `filter` atau `noop` adalah alternatif yang dapat diterima daripada mencoba ulang.