Output terstruktur

Output terstruktur berarti model menjawab dengan JSON yang bisa langsung di-parse kodemu, bukan teks bebas. Di Chat completions, kamu memintanya lewat response_format. kenari meneruskan field itu ke sebagian model dan membuangnya untuk model lain, dan kenari tidak memeriksa hasilnya. Anggap response_format sebagai permintaan kepada model, dan validasi setiap balasan di kodemu sendiri.

Minta JSON

{"type": "json_object"} meminta satu objek JSON yang valid. Beri tahu juga model di prompt untuk menjawab dengan JSON, karena sebagian provider mewajibkannya.

curl https://kenari.id/v1/chat/completions \
  -H "Authorization: Bearer $KENARI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "step-3-7-flash:free",
    "response_format": {"type": "json_object"},
    "messages": [
      {"role": "system", "content": "Balas dengan satu objek JSON saja."},
      {"role": "user", "content": "Ambil vendor dan total: Faktur dari Toko Maju, total 417000 rupiah."}
    ]
  }'

Minta skema

{"type": "json_schema"} meminta JSON yang sesuai dengan sebuah JSON Schema. Beri skema itu name, dan taruh skemanya di schema.

{
  "model": "step-3-7-flash:free",
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "invoice",
      "schema": {
        "type": "object",
        "properties": {
          "vendor": {"type": "string"},
          "total": {"type": "integer"}
        },
        "required": ["vendor", "total"]
      }
    }
  },
  "messages": [
    {"role": "user", "content": "Ambil field faktur ini: Faktur dari Toko Maju, total 417000 rupiah."}
  ]
}

Apa yang dilakukan kenari dengan response_format

kenari tidak menafsirkan response_format. Hasilnya bergantung pada format API yang dipakai provider untuk melayani model. Itu bukan endpoint yang kamu panggil, dan GET /v1/models tidak menampilkannya, jadi rencanakan validasi dan coba lagi di setiap model:

Model dilayani lewat	Penanganan `response_format`
API gaya OpenAI	Diteruskan apa adanya. Penerapannya bergantung pada model.
API gaya Anthropic atau API gaya Responses	Tidak dikirim. Model menjawab hanya dari prompt-mu.
API apa pun, dan request juga memuat server tool `kenari:`	Tidak dikirim.

kenari tidak pernah mengembalikan error hanya karena model mengabaikan field ini, dan GET /v1/models tidak menyebutkan model mana yang menegakkannya. Jika provider menolak field ini, kamu mendapat 400. Jadi sebuah balasan bisa berupa JSON valid, JSON tidak valid, atau JSON yang dibungkus code fence.

Pola yang andal: validasi lalu coba lagi

Minta JSON, validasi balasan terhadap skema-mu, dan kirim error validasinya kembali jika gagal. Pola ini dapat digunakan di semua model.

import os

from openai import OpenAI
from pydantic import BaseModel, ValidationError


class Invoice(BaseModel):
    vendor: str
    total: int


client = OpenAI(
    base_url="https://kenari.id/v1",
    api_key=os.environ["KENARI_API_KEY"],
)


def extract_invoice(text: str, attempts: int = 3) -> Invoice:
    messages = [
        {"role": "system", "content": "Balas dengan satu objek JSON saja."},
        {"role": "user", "content": f"Ambil vendor dan total dari: {text}"},
    ]
    for _ in range(attempts):
        response = client.chat.completions.create(
            model="step-3-7-flash:free",
            messages=messages,
            response_format={
                "type": "json_schema",
                "json_schema": {"name": "invoice", "schema": Invoice.model_json_schema()},
            },
        )
        reply = response.choices[0].message.content or ""
        try:
            return Invoice.model_validate_json(reply)
        except ValidationError as error:
            messages += [
                {"role": "assistant", "content": reply},
                {"role": "user", "content": f"Balasan itu tidak valid: {error}. Balas hanya dengan JSON yang sudah diperbaiki."},
            ]
    raise RuntimeError("tidak ada JSON valid setelah beberapa percobaan")


print(extract_invoice("Faktur dari Toko Maju, total 417000 rupiah."))

Mengirim response_format sekaligus memvalidasi tidak menambah biaya tersendiri dan membantu di model yang mendukungnya. Setiap percobaan ulang adalah request baru, yang ditagih seperti biasa di model berbayar.