Site icon SUSANTOKUN

Structured Output Ollama: JSON Rapi Tanpa Parsing Manual

Model bahasa paling berguna saat keluarannya bisa dibaca program, bukan cuma manusia. Structured output di Ollama memaksa jawaban model mengikuti JSON Schema yang kita tentukan, jadi hasilnya siap di-parse tanpa regex, tanpa preg_match berlapis, dan tanpa try/catch yang menebak-nebak bentuk respons. Biayanya nyaris nol: satu field di body request.

Satu catatan di awal. Dokumentasi resmi Ollama menyebut layanan cloud-nya belum mendukung structured output. Jadi pembahasan ini berlaku untuk server Ollama yang kamu jalankan sendiri, bukan model lewat jalur cloud.

Apa Itu Structured Output

Tanpa pengaturan apa pun, model menjawab dengan teks bebas: kadang rapi, kadang menambah kalimat pembuka, kadang membungkus JSON dalam blok markdown. Enak dibaca manusia, menyiksa kalau diproses mesin.

Structured output mengubah aturan mainnya: Ollama membatasi proses generasi supaya keluarannya cocok dengan bentuk yang kita minta. Ada dua tingkat ketat:

Bedanya penting: mode JSON membereskan sintaks, mode skema membereskan bentuk. Kalau kode kamu mengambil $data['harga'] sementara model mengembalikan {"price": ...}, JSON-nya valid tapi aplikasi tetap pecah.

Tiga Jalur yang Bisa Dipakai

Ollama punya lebih dari satu pintu masuk, dan pilihan pintu menentukan nama field yang dikirim:

Di endpoint native, format menerima string "json" atau objek JSON Schema — referensi API Ollama menyebut tipenya enum<string> | object. Schema dikirim sebagai objek biasa, bukan string yang di-escape.

Mulai dari yang Paling Sederhana

Sebelum menyusun skema, pastikan dulu modelnya mau patuh pada instruksi dasar. Cukup tambahkan "format": "json" dan matikan streaming supaya respons datang utuh:

curl -sS -X POST http://localhost:11434/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-oss",
    "messages": [
      {"role": "user", "content": "Sebutkan satu fakta singkat tentang Indonesia dalam JSON."}
    ],
    "stream": false,
    "format": "json"
  }'

Hasilnya ada di message.content, masih berupa string. Kamu tetap perlu json_decode atau json.loads. Mode JSON tidak menghapus parsing; ia menjamin parsing-nya berhasil.

Naik Level: Kirim JSON Schema

Kalau bentuk keluaran sudah ditentukan, kirim skemanya di field format. Contoh berikut meminta profil singkat sebuah negara dengan tiga field wajib:

curl -sS -X POST http://localhost:11434/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-oss",
    "messages": [
      {"role": "user", "content": "Beri profil singkat tentang Jepang."}
    ],
    "stream": false,
    "format": {
      "type": "object",
      "properties": {
        "negara": {"type": "string"},
        "ibu_kota": {"type": "string"},
        "bahasa": {"type": "array", "items": {"type": "string"}}
      },
      "required": ["negara", "ibu_kota", "bahasa"]
    }
  }'

Satu tips dari dokumentasi yang sering dilewatkan: kirim juga skema yang sama sebagai teks di prompt. Skema di field format mengatur proses generasi, salinan di prompt memberi konteks tentang apa yang diminta. Dua lapisan berbeda, dan menggabungkannya membuat hasil lebih konsisten.

Pydantic: Skema Sekali, Dipakai untuk Validasi

Menulis JSON Schema manual untuk struktur bersarang cepat melelahkan. Di Python, definisikan kelas Pydantic lalu konversi otomatis dengan model_json_schema(). Rilis stabil Pydantic saat artikel ini ditulis adalah 2.14.3, dan metode tersebut tersedia sejak Pydantic v2.

pip install ollama pydantic
from ollama import chat
from pydantic import BaseModel


class Tiket(BaseModel):
    judul: str
    prioritas: str
    perangkat: str
    langkah_reproduksi: list[str]


respons = chat(
    model="gpt-oss",
    messages=[
        {"role": "user", "content": "Ubah laporan berikut jadi tiket terstruktur: ..."}
    ],
    format=Tiket.model_json_schema(),
)

tiket = Tiket.model_validate_json(respons.message.content)
print(tiket.prioritas, len(tiket.langkah_reproduksi))

Skema dan validasi berasal dari satu sumber, jadi tidak mungkin berbeda versi: tambah field di kelas, skema yang dikirim ke model ikut berubah. model_validate_json() juga langsung melempar error kalau isinya tidak sesuai, sehingga kegagalan terdeteksi di batas aplikasi.

Zod untuk JavaScript

Di ekosistem JavaScript, padanannya adalah Zod. Dokumentasi Ollama memakai z.toJSONSchema() untuk mengubah skema Zod menjadi JSON Schema, lalu .parse() untuk memvalidasi hasilnya:

import ollama from 'ollama';
import { z } from 'zod';

const Tiket = z.object({
  judul: z.string(),
  prioritas: z.enum(['rendah', 'sedang', 'tinggi']),
  perangkat: z.string(),
  langkah: z.array(z.string()),
});

const respons = await ollama.chat({
  model: 'gpt-oss',
  messages: [{ role: 'user', content: 'Ubah laporan berikut jadi tiket: ...' }],
  format: z.toJSONSchema(Tiket),
});

const tiket = Tiket.parse(JSON.parse(respons.message.content));
console.log(tiket.prioritas);

Perhatikan penggunaan z.enum(). Untuk nilai yang pilihannya tertutup, enum jauh lebih baik daripada z.string(): model punya daftar nilai sah, dan kamu tidak perlu menormalkan kata seperti “tinggi”, “Tinggi”, atau “high” di kode.

Menyusun Skema yang Tidak Bikin Model Bingung

Skema yang ketat bukan berarti skema yang rumit. Beberapa aturan praktis yang terbukti menghemat waktu debugging:

Satu lagi dari halaman tips resmi: turunkan temperature mendekati nol. Structured output mengunci bentuk keluaran, bukan pilihan isinya. Dengan temperature rendah, hasil antar-request lebih bisa dibandingkan.

Kapan Structured Output Bukan Jawaban

Fitur ini sering dipasang di tempat yang salah. Tiga situasi yang sebaiknya dilewati:

Catatan Produksi

Setelah jalan di laptop, tiga hal biasanya muncul di server. Pertama, skema besar memakan token konteks — skema bersarang dengan puluhan field ikut dihitung sebagai prompt, jadi ruang efektif untuk data kamu berkurang. Pecah skema jadi beberapa request kalau mulai terasa.

Kedua, JSON valid tidak sama dengan data benar. Model bisa mengembalikan "prioritas": "tinggi" untuk keluhan sepele. Validasi skema menjaga tipe dan bentuk; aturan bisnis tetap tugas kode kamu. Perlakukan keluarannya seperti input pengguna: terpercaya secara struktur, belum tentu benar isinya.

Ketiga, siapkan jalur retry yang jelas. Kalau validasi gagal atau sebuah enum tidak dikenali, kirim ulang request dengan pesan error sebagai konteks tambahan, bukan mengulang prompt yang sama persis. Satu retry dengan koreksi biasanya cukup; kalau masih gagal, masuk antrean tinjauan manusia.

FAQ

Apakah structured output menjamin isi jawaban benar?

Tidak. Yang dijamin hanya bentuk: JSON valid dan field sesuai skema. Kebenaran isi tetap bergantung pada model, prompt, dan data masukan. Karena itu validasi skema perlu dipasangkan dengan aturan bisnis dan, untuk keputusan penting, tinjauan manusia.

Bisa dipakai bersama model vision?

Bisa. Model vision menerima parameter format yang sama, jadi deskripsi gambar bisa diminta sebagai objek: ringkasan, objek yang terdeteksi, dan kategori lokasi. Dokumentasi Ollama mencontohkannya dengan menambahkan images pada pesan dan temperature nol.

Kenapa request ke endpoint OpenAI-compatible saya berbeda hasilnya?

Karena nama field-nya beda. Di /v1/chat/completions kamu memakai response_format, dan halaman kompatibilitas OpenAI mencantumkannya sebagai field yang didukung bersama mode JSON. Butuh skema penuh? Jalur native /api/chat dengan format lebih langsung.

Kesimpulan

Structured output adalah cara termurah membuat model lokal bisa dipercaya oleh kode: satu field tambahan, satu skema, dan sebagian besar parsing defensif hilang. Mulai dari format: "json", naik ke skema begitu bentuk data stabil, dan ikat skema ke kelas Pydantic atau Zod supaya validasi tidak tertinggal dari definisi.

Kalau aplikasi kamu memakai Laravel, pola yang sama bisa dipasang lewat SDK resmi — lihat Mengenal Laravel AI SDK untuk lapisan abstraksinya, dan Prism PHP kalau kamu ingin satu antarmuka untuk beberapa penyedia. Untuk kebutuhan pencarian berbasis makna, pgvector di PostgreSQL melengkapi sisi penyimpanan vektor.

Referensi

Exit mobile version