BroadRouter
Mulakan

JSON mode vs json_schema: output berstruktur yang boleh diharap

Oleh pasukan BroadNet Inference · 4 minit bacaan · Diterbitkan

JSON mode (response_format json_object) hanya menjanjikan JSON yang sah. Output berstruktur (response_format json_schema) juga menjanjikan medan dan jenis anda, jika penyedia menguatkuasakannya. Walau apa pun, semak finish_reason, huraikan, dan sahkan terhadap skema seperti model Pydantic. Jika pengesahan gagal, hantar semula ralat itu dan minta sekali lagi, dengan had cubaan yang ketat.

Kod anda memerlukan data, dan model menulis teks. Output berstruktur merapatkan jurang itu, tetapi “model memulangkan JSON” membawa tiga maksud berbeza bergantung pada cara anda meminta. Artikel ini membandingkan pilihan pada model terbuka yang serasi OpenAI, menunjukkan cara meminta setiap satu, dan memberi gelung sahkan-dan-baiki yang boleh terus dimasukkan ke pengeluaran.

Apakah perbezaan antara JSON mode dan json_schema?

Kaedah Permintaan Apa yang dijanjikan
Prompt sahaja “Balas dalam JSON dengan medan…” Tiada; biasanya JSON, kadangkala dengan teks tambahan
JSON mode response_format: {"type": "json_object"} JSON yang sah, apa-apa bentuk
Output berstruktur response_format: {"type": "json_schema", ...} JSON yang sepadan dengan skema anda, jika dikuatkuasakan

Panduan Structured Outputs OpenAI menyatakannya dengan terus: “While both ensure valid JSON is produced, only Structured Outputs ensure schema adherence.” (Terjemahan: Walaupun kedua-duanya memastikan JSON yang sah dihasilkan, hanya Structured Outputs yang memastikan pematuhan skema.) Ia mengesyorkan output berstruktur berbanding JSON mode bila-bila masa yang boleh.

Pada penyedia model terbuka, jaminannya bergantung pada cara pelayan melaksanakannya. Banyak yang menggunakan penyahkodan terkekang, yang menyekat token yang akan melanggar skema. Sesetengahnya menerima medan itu tetapi tidak menguatkuasakannya. Itulah sebabnya kod di bawah tetap mengesahkan.

Bagaimanakah meminta json_schema?

import os
from openai import OpenAI
from pydantic import BaseModel, Field

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])

class Invoice(BaseModel):
    vendor: str
    currency: str = Field(pattern="^[A-Z]{3}$")
    total: float
    line_items: list[float]

schema = Invoice.model_json_schema()
schema["additionalProperties"] = False

response_format = {"type": "json_schema",
                   "json_schema": {"name": "invoice", "strict": True, "schema": schema}}

Pydantic menjana JSON Schema daripada kelas anda, jadi skema dan pengesah tidak akan pernah tersasar. Jika anda tidak menggunakan Pydantic, penjana skema JSON membina skema strict mode daripada objek sampel. Untuk strict mode, OpenAI memerlukan additionalProperties: false dan setiap sifat disenaraikan sebagai wajib.

Mod manakah yang disokong oleh penyedia anda?

Jalankan ujian ini sekali bagi setiap model sebelum membina di atasnya:

  1. Hantar json_schema dengan prompt yang mengundang medan tambahan (“tambahkan juga komen ringkas”).
  2. Jika permintaan menghasilkan ralat, penyedia tidak menerima json_schema. Cuba json_object.
  3. Jika jawapan mengandungi medan tambahan itu, skema tidak dikuatkuasakan. Anggap ia sebagai JSON mode.
  4. Jika json_object juga menghasilkan ralat, gunakan prompt sahaja dengan pengesahan.

Di BroadNet Inference, dokumentasi menyenaraikan output berstruktur untuk GLM 5.3 dan Qwen3.8 27B (dibandingkan bersebelahan), tetapi tidak menamakan parameter permintaan. Jalankan ujian di atas pada model yang anda gunakan dalam produk.

Bagaimanakah mengesahkan dan membaiki output yang rosak?

import json
from pydantic import ValidationError

def extract(text: str, model="broadnet/glm-5.3", attempts=3) -> Invoice:
    messages = [
        {"role": "system", "content": "Extract the invoice. Reply with JSON only."},
        {"role": "user", "content": text},
    ]
    for attempt in range(attempts):
        r = client.chat.completions.create(model=model, messages=messages,
                                           response_format=response_format,
                                           max_tokens=4000)
        choice = r.choices[0]
        if choice.finish_reason == "length":
            raise RuntimeError("Cut off: raise max_tokens")  # retrying won't help
        if getattr(choice.message, "refusal", None):
            raise RuntimeError(f"Refused: {choice.message.refusal}")
        raw = choice.message.content or ""
        try:
            inv = Invoice.model_validate_json(raw)
            if abs(sum(inv.line_items) - inv.total) > 0.01:
                raise ValueError("total must equal the sum of line_items")
            return inv
        except (ValidationError, ValueError) as e:
            messages += [
                {"role": "assistant", "content": raw},
                {"role": "user", "content": f"That JSON is invalid: {e}. Return corrected JSON only."},
            ]
    raise RuntimeError(f"No valid JSON after {attempts} attempts")

Apa yang membuat gelung ini berfungsi:

  • Semak finish_reason dahulu. Jawapan yang mencapai max_tokens ialah JSON yang terpotong. Mencuba semula dengan had yang sama gagal dengan cara yang sama. Kedua-dua model di atas membuat penaakulan sebelum menjawab, dan penaakulan dikira dalam had, jadi beri ruang.
  • Kendalikan penolakan secara berasingan. Panduan OpenAI menyatakan penolakan “does not necessarily follow the schema you have supplied” (Terjemahan: tidak semestinya mengikut skema yang anda berikan).
  • Hantar semula ralat yang tepat. Cuba semula secara membuta tuli sering memulangkan kesilapan yang sama. “line_items: field required” memberi model sesuatu untuk dibetulkan.
  • Semak peraturan perniagaan dalam kod. Skema tidak boleh menyatakan bahawa jumlah mesti sama dengan item barisnya. Semakan di atas boleh.
  • Hadkan cubaan. Setiap cubaan menghantar semula keseluruhan prompt sebagai token input.

Ciri skema manakah yang menimbulkan masalah?

Pastikan skema ringkas dan membosankan:

  1. Rata lebih baik daripada bersarang. Dua tahap sudah memadai untuk kebanyakan pengekstrakan.
  2. Enum dan bukannya rentetan bebas untuk kategori.
  3. Tiada objek terbuka. Medan dict bentuk bebas mematahkan tujuannya.
  4. Nama medan pendek dengan penerangan. Penerangan dalam skema membimbing model.
  5. Medan pilihan sebagai nullable. Dalam strict mode, senaraikan setiap medan sebagai wajib dan benarkan null.

Panduan OpenAI menyatakan sesetengah ciri JSON Schema tidak disokong dalam strict mode. Pelayan model terbuka mempunyai had mereka sendiri. Jika skema ditolak, permudahkannya sebelum menukar mod.

Bagaimanakah memantau output berstruktur dalam pengeluaran?

Gelung yang membaiki secara senyap boleh menyembunyikan masalah yang membazirkan token setiap hari. Log tiga angka bagi setiap tempat panggilan:

Metrik Apa yang diberitahunya
Kadar kejayaan cubaan pertama Sejauh mana model dan skema sepadan; penurunan sering berlaku selepas perubahan prompt atau model
Purata cubaan bagi setiap kejayaan Kos token untuk pembaikan
Kegagalan akhir Input yang tidak dapat dikendalikan pipeline anda; semaknya secara manual

Jika kejayaan cubaan pertama jatuh di bawah tahap biasa, permudahkan skema atau cuba model lain sebelum menambah lebih banyak cuba semula. Simpan sampel jawapan mentah yang gagal, supaya anda boleh menguji pembetulan terhadap kes sebenar.

Bilakah anda patut menggunakan tool sebaliknya?

Gunakan output berstruktur untuk jawapan akhir: pengekstrakan, klasifikasi, pelan. Gunakan panggilan tools apabila model memerlukan kod anda untuk melakukan sesuatu dan meneruskan. Banyak ejen menggunakan kedua-duanya: tools semasa gelung, skema untuk langkah terakhir. Untuk contoh imej ke JSON, lihat membaca invois bahasa Arab dengan model visi.

Di manakah BroadNet Inference sesuai

BroadNet Inference menyenaraikan output berstruktur untuk GLM 5.3 dan Qwen3.8 27B, di sebalik format chat-completions standard, jadi kod di atas berjalan dengan SDK Python OpenAI tanpa perubahan. Qwen3.8 27B juga menerima imej, yang sesuai untuk pengekstrakan dokumen. Dokumentasi BroadNet tidak menyatakan output berstruktur untuk DeepSeek V4.1 Flash atau Gemma 4 VL 26B, jadi gunakan laluan prompt sahaja dengan pengesahan di sana. Bandingkan harga setiap token di halaman harga.

Soalan lazim

Apakah perbezaan antara JSON mode dan output berstruktur?

JSON mode, response_format jenis json_object, hanya menjanjikan jawapan boleh dihuraikan sebagai JSON. Output berstruktur, jenis json_schema, juga menjanjikan medan dan jenis yang anda tetapkan, jika penyedia menguatkuasakannya. OpenAI mengesyorkan output berstruktur berbanding JSON mode apabila boleh.

Adakah model terbuka menyokong response_format json_schema?

Bergantung pada penyedia. Sesetengahnya menerima json_schema, sesetengahnya hanya json_object, dan sesetengahnya mengabaikan medan itu. Hantar permintaan ujian dengan skema dan prompt yang menggoda model untuk menambah medan tambahan, kemudian semak jawapannya.

Adakah saya masih perlu mengesahkan output berstruktur?

Ya. Jawapan boleh terpotong oleh max_tokens, boleh berupa penolakan, dan boleh melanggar peraturan perniagaan yang tidak dapat dinyatakan oleh skema, seperti jumlah yang mesti sepadan.

Berapa kali saya patut mencuba semula JSON yang tidak sah?

Dua atau tiga cubaan dengan ralat pengesahan disertakan biasanya sudah cukup. Selepas itu, log input dan hantar ke laluan sandaran, model yang lebih kuat atau manusia. Gelung tanpa had membazirkan token.

Patutkah saya menggunakan output berstruktur atau panggilan tools?

Gunakan output berstruktur apabila anda mahu jawapan akhir dalam bentuk tetap. Gunakan panggilan tools apabila model memerlukan kod anda melakukan sesuatu dan kemudian meneruskan.

Baca sebagai MarkdownTanya ChatGPTTanya ClaudeTanya Perplexity