Skip to main content

\"Output

Saat melakukan tugas ekstraksi informasi atau pembuatan data terstruktur, model dapat mengembalikan teks tambahan (seperti ```json ) yang mengganggu penguraian downstream. Mengaktifkan output terstruktur memastikan model mengembalikan string JSON yang valid. Mode Skema JSON juga memberikan kontrol presisi atas struktur dan tipe output, menghilangkan kebutuhan akan validasi tambahan atau percobaan ulang.

Penggunaan

Output terstruktur mendukung dua mode: Objek JSON dan Skema JSON.
  • Mode Objek JSON: Memastikan output adalah string JSON yang valid, tetapi tidak menjamin struktur tertentu. Penggunaan:
    1. Atur parameterresponse_format: Di badan permintaan, atur response_format menjadi {\"type\": \"json_object\"}.
    2. Sertakan kata kunci JSON dalam prompt Anda: Pesan sistem atau pesan pengguna harus mengandung kata "JSON" (tidak peka huruf besar/kecil), jika tidak API akan mengembalikan: 'messages' must contain the word 'json' in some form, to use 'response_format' of type 'json_object'.
  • Mode Skema JSON: Memastikan output sesuai dengan struktur yang ditentukan. Penggunaan: atur response_format menjadi {\"type\": \"json_schema\", \"json_schema\": {...}, \"strict\": true}.
    Tidak diperlukan kata kunci JSON dalam prompt.
Parameter di atas berlaku untuk API Chat Completions. Jika Anda menggunakan API Responses, tetapkan text.format sebagai gantinya; format nilainya sama. Lihat contoh di bawah. Dalam mode JSON Object, API Responses juga mengharuskan prompt memuat kata "JSON"; jika tidak, error 400 akan dikembalikan.
Perbandingan fitur:

Fitur

Mode Objek JSON

Mode Skema JSON

Menghasilkan JSON valid

Ya

Ya

Mengikuti skema secara ketat

Tidak

Ya

Model yang didukung

Sebagian besar model Qwen

Hanya model qwen-plus tertentu

Pengaturan response_format

{\"type\": \"json_object\"}

{\"type\": \"json_schema\", \"json_schema\": {...}, \"strict\": true}

Persyaratan prompt

Harus menyertakan \"JSON\"

Disarankan untuk mendeskripsikan secara eksplisit

Kasus penggunaan

Output JSON fleksibel

Validasi skema presisi

Model yang didukung

Model yang dilabeli "mode non-berpikir" hanya mendukung output terstruktur dalam mode non-berpikir.
  • Objek JSON
  • Skema JSON
  • Qwen
  • GLM
  • DeepSeek
  • Kimi
  • Model generasi teks
    • Qwen-Max: qwen4-max , Seri Qwen3.8-Max, seri Qwen3.7-Max
    • Qwen-Max (mode non-berpikir): Seri Qwen3.6-Max, seri Qwen3-Max, seri Qwen-Max
    • Qwen-Plus: Seri Qwen3.7-Plus
    • Qwen-Plus (mode non-berpikir): Seri Qwen3.6-Plus, seri Qwen3.5-Plus, seri Qwen-Plus
    • Qwen-Flash: Seri Qwen3.8-Flash, Seri Qwen3.7-Flash
    • Qwen-Flash (mode non-berpikir): Seri Qwen3.6-Flash, seri Qwen3.5-Flash, seri Qwen-Flash
    • Qwen-Turbo (mode non-berpikir): Seri Qwen-Turbo
    • Qwen-Coder: Seri Qwen3-Coder
    • Qwen-Long: Seri Qwen-Long
    • Seri open-source Qwen3.8
    • Seri open-source Qwen3.6 (mode non-berpikir)
    • Seri open-source Qwen3.5 (mode non-berpikir)
    • Seri open-source Qwen3 (mode non-berpikir)
    • Seri open-source Qwen3-Coder
    • Seri open-source Qwen2.5 (tidak termasuk model math dan coder)
  • Model multimodal
    • Qwen-VL (mode non-berpikir): Seri Qwen3-VL-Plus, seri Qwen3-VL-Flash, seri Qwen-VL-Max (tidak termasuk versi terbaru dan snapshot), seri Qwen-VL-Plus (tidak termasuk versi terbaru dan snapshot)
    • Qwen-Omni: Seri Qwen3.5-Omni-Plus
    • Seri open-source Qwen3-VL (mode non-berpikir)

Memulai

Contoh ini mengekstrak informasi terstruktur dari profil pribadi. Dapatkan kunci API dan ekspor kunci API sebagai variabel lingkungan. Jika Anda menggunakan OpenAI SDK atau DashScope SDK untuk melakukan panggilan, instal SDK.
  • API Chat Completions Kompatibel OpenAI
  • API Responses Kompatibel OpenAI
  • DashScope
  • Python
  • Node.js
  • curl
from openai import OpenAI.\nimport os.\n\nclient = OpenAI(\n    # Kunci API berbeda berdasarkan wilayah. Jika Anda belum mengonfigurasi variabel lingkungan, ganti baris berikutnya dengan: api_key=\"sk-xxx\"\n    api_key=os.getenv(\"DASHSCOPE_API_KEY\"),\n    # Jika Anda menggunakan model wilayah Singapura, ganti base_url dengan: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1\n    base_url=\"https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1\",\n)\n\ncompletion = client.chat.completions.create(\n    model=\"qwen4-max\",\n    messages=[\n        {\n            \"role\": \"system\",\n            \"content\": \"Ekstrak nama dan usia pengguna, lalu kembalikan dalam format JSON\"\n        },\n        {\n            \"role\": \"user\",\n            \"content\": \"Halo semua, nama saya Alex Brown, saya berusia 34 tahun, email saya alexbrown@example.com, dan saya suka bermain basket serta bepergian\",\n        },\n    ],\n    response_format={\"type\": \"json_object\"}\n)\n\njson_string = completion.choices[0].message.content.\nprint(json_string)

Respons

{\n  \"Name\": \"Alex Brown\",\n  \"Age\": 34\n}

Pemrosesan data gambar dan video

Model multimodal juga mendukung output terstruktur untuk gambar dan video. Gunakan mode JSON untuk mengekstrak data terstruktur dari konten visual, seperti nilai bidang dari tanda terima, lokasi objek dalam gambar, atau peristiwa dalam video.
Untuk batas file gambar dan video, lihat Pemahaman gambar dan video .
  • Kompatibel OpenAI
  • DashScope
  • Python
  • Node.js
  • curl
import os.\nfrom openai import OpenAI.\n\nclient = OpenAI(\n    # Kunci API berbeda berdasarkan wilayah. Dapatkan kunci API: https://www.alibabacloud.com/help/en/model-studio/get-api-key.\n    api_key=os.getenv(\"DASHSCOPE_API_KEY\"),\n    # Untuk model wilayah Beijing, ganti base_url dengan: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1\n    base_url=\"https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1\"\n)\n\ncompletion = client.chat.completions.create(\n    model=\"qwen3-vl-plus\",\n    messages=[\n        {\n            \"role\": \"system\",\n            \"content\": [{\"type\": \"text\", \"text\": \"Anda adalah asisten yang membantu.\"}],\n        },\n        {\n            \"role\": \"user\",\n            \"content\": [\n                {\n                    \"type\": \"image_url\",\n                    \"image_url\": {\n                        \"url\": \"http://duguang-labelling.oss-cn-shanghai.aliyuncs.com/demo_ocr/receipt_zh_demo.jpg\"\n                    },\n                },\n                {\"type\": \"text\", \"text\": \"Ekstrak informasi tiket (tipe array, termasuk travel_date, trains, seat_num, arrival_site, price) dan informasi faktur (tipe array, termasuk invoice_code dan invoice_number) dari gambar. Keluarkan JSON yang berisi array ticket dan invoice\"},\n            ],\n        },\n    ],\n    response_format={\"type\": \"json_object\"}\n)\njson_string = completion.choices[0].message.content.\nprint(json_string)

Respons

{\n  \"ticket\": [\n    {\n      \"travel_date\": \"2013-06-29\",\n      \"trains\": \"stream\",\n      \"seat_num\": \"371\",\n      \"arrival_site\": \"Kawasan Pengembangan\",\n      \"price\": \"8.00\"\n    }\n  ],\n  \"invoice\": [\n    {\n      \"invoice_code\": \"221021325353\",\n      \"invoice_number\": \"10283819\"\n    }\n  ]\n}

Mengoptimalkan prompt

Prompt yang ambigu seperti "kembalikan informasi pengguna" menyebabkan struktur output yang tidak dapat diprediksi. Untuk hasil yang andal, jelaskan skema yang diharapkan dalam prompt Anda: tentukan nama field, tipe, status wajib atau opsional, batasan format (seperti format tanggal), dan sertakan contoh.
  • Kompatibel OpenAI
  • DashScope
  • Python
  • Node.js
from openai import OpenAI.\nimport os.\nimport json.\nimport textwrap  # Menangani indentasi untuk string multi-baris guna meningkatkan keterbacaan kode.\n\n# Respons contoh yang telah ditentukan sebelumnya untuk menunjukkan kepada model format output yang diharapkan.\n# Contoh 1: Respons lengkap dengan semua bidang.\nexample1_response = json.dumps(\n    {\n        \"info\": {\"name\": \"Alice\", \"age\": \"25 tahun\", \"email\": \"alice@example.com\"},\n        \"hobby\": [\"menyanyi\"]\n    },\n    ensure_ascii=False.\n)\n# Contoh 2: Respons dengan beberapa hobi.\nexample2_response = json.dumps(\n    {\n        \"info\": {\"name\": \"Bob\", \"age\": \"30 tahun\", \"email\": \"bob@example.com\"},\n        \"hobby\": [\"menari\", \"berenang\"]\n    },\n    ensure_ascii=False.\n)\n# Contoh 3: Respons tanpa bidang hobby (hobby bersifat opsional)\nexample3_response = json.dumps(\n    {\n        \"info\": {\"name\": \"Dave\", \"age\": \"28 tahun\", \"email\": \"dave@example.com\"}\n    },\n    ensure_ascii=False.\n)\n# Contoh 4: Respons lain tanpa bidang hobby.\nexample4_response = json.dumps(\n    {\n        \"info\": {\"name\": \"Sun Qi\", \"age\": \"35 tahun\", \"email\": \"sunqi@example.com\"}\n    },\n    ensure_ascii=False.\n)\n\n# Inisialisasi klien OpenAI.\nclient = OpenAI(\n    # Jika Anda belum mengonfigurasi variabel lingkungan, ganti baris berikutnya dengan: api_key=\"sk-xxx\"\n    # Kunci API berbeda berdasarkan wilayah. Dapatkan kunci API: https://www.alibabacloud.com/help/en/model-studio/get-api-key.\n    api_key=os.getenv(\"DASHSCOPE_API_KEY\"),\n    # Ini adalah base_url wilayah Singapura. Jika Anda menggunakan model wilayah Tiongkok (Singapura), ganti base_url dengan: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1\n    base_url=\"https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1\",\n)\n\n# dedent menghapus spasi awal umum dari setiap baris, memungkinkan string diindentasi dengan rapi dalam kode tanpa menyertakan spasi tambahan saat runtime.\nsystem_prompt = textwrap.dedent(f\"\"\"\\\n    Ekstrak informasi pribadi dari input pengguna dan outputkan dalam format JSON Schema yang ditentukan:\n\n    [Persyaratan format output]\n    Output harus mengikuti struktur JSON ini secara ketat:\n    {{\n      \"info\": {{\n        \"name\": \"tipe string, bidang wajib, nama pengguna\",\n        \"age\": \"tipe string, bidang wajib, format 'angka tahun', misalnya, '25 tahun'\",\n        \"email\": \"tipe string, bidang wajib, format email standar, misalnya, 'user@example.com'\"\n      }},\n      \"hobby\": [\"tipe array string, bidang opsional, berisi semua hobi pengguna; hilangkan sepenuhnya jika tidak disebutkan\"]\n    }}\n\n    [Aturan ekstraksi bidang]\n    1. name: Identifikasi nama pengguna dari teks, wajib diekstrak.\n    2. age: Identifikasi informasi usia, konversi ke format 'angka tahun', wajib diekstrak.\n    3. email: Identifikasi alamat email, pertahankan format asli, wajib diekstrak.\n    4. hobby: Identifikasi hobi pengguna, outputkan sebagai array string; hilangkan bidang hobby sepenuhnya jika hobi tidak disebutkan.\n\n    [Contoh referensi]\n    Contoh 1 (dengan hobby):\n    Q: Nama saya Alice, saya berusia 25 tahun, email saya alice@example.com, dan hobi saya bernyanyi.\n    A: {example1_response}\n\n    Contoh 2 (dengan beberapa hobi):\n    Q: Nama saya Bob, saya berusia 30 tahun, email saya bob@example.com, dan saya menikmati menari serta berenang.\n    A: {example2_response}\n\n    Contoh 3 (tanpa hobby):\n    Q: Nama saya Dave, saya berusia 28 tahun, dan email saya dave@example.com.\n    A: {example3_response}\n\n    Contoh 4 (tanpa hobi):\n    Q: Saya Sun Qi, berusia 35 tahun, dan email saya adalah sunqi@example.com.\n    A: {example4_response}\n\n    Ekstrak informasi dan hasilkan JSON secara ketat sesuai dengan format dan aturan di atas. Jangan sertakan bidang hobi jika pengguna tidak menyebutkan hobi.\\\n\"\"\")\n\n# Panggil API model untuk ekstraksi informasi.\ncompletion = client.chat.completions.create(\n    model=\"qwen4-max\",\n    messages=[\n        {\n            \"role\": \"system\",\n            \"content\": system_prompt.\n        },\n        {\n            \"role\": \"user\",\n            \"content\": \"Halo semua, nama saya Alex Brown, saya berusia 34 tahun, email saya adalah alexbrown@example.com, dan saya menikmati bermain basket serta bepergian\",\n        },\n    ],\n    response_format={\"type\": \"json_object\"},  # Tentukan format pengembalian JSON.\n)\n\n# Ekstrak dan cetak hasil JSON yang dihasilkan model.\njson_string = completion.choices[0].message.content.\nprint(json_string)

Respons

{\n  \"info\": {\n    \"name\": \"Alex Brown\",\n    \"age\": \"34 tahun\",\n    \"email\": \"alexbrown@example.com\"\n  },\n  \"hobby\": [\"Basket\", \"Bepergian\"]\n}

Mendapatkan output terstruktur

Mengatur response_format type ke json_object akan mengembalikan string JSON yang valid, namun strukturnya mungkin tidak sesuai dengan ekspektasi Anda—cocok untuk skenario sederhana. Untuk penguraian otomatis, interoperabilitas API, dan skenario kompleks lainnya yang memerlukan batasan tipe yang ketat, atur type ke json_schema untuk memaksa model menghasilkan konten yang secara ketat sesuai dengan format yang ditentukan. Format dan contoh response_format:
{\n  \"type\": \"json_schema\",\n  \"json_schema\": {\n    \"name\": \"nama_skema\",       // Nama skema.\n    \"strict\": true,              // Direkomendasikan: ikuti format secara ketat.\n    \"schema\": {\n      \"type\": \"object\",\n      \"properties\": {...},       // Tentukan struktur bidang (lihat contoh di sebelah kanan)\n      \"required\": [...],         // Daftar bidang yang wajib diisi.\n      \"additionalProperties\": false  // Direkomendasikan: hanya keluarkan bidang yang telah didefinisikan.\n    }\n  }\n}
Contoh di atas memaksa model untuk menghasilkan objek JSON dengan dua bidang wajib (name dan age) serta satu bidang opsional email.
Model di wilayah Singapura belum didukung.

Cara menggunakan

Dengan metode parse pada OpenAI SDK, Anda dapat meneruskan kelas Pydantic Python atau objek Zod Node.js secara langsung. SDK akan secara otomatis mengonversinya menjadi JSON Schema—tidak perlu menulis JSON kompleks secara manual. Untuk DashScope SDK, buat JSON Schema secara manual mengikuti format di atas.
  • API Chat Completions Kompatibel OpenAI
  • API Responses Kompatibel OpenAI
  • DashScope

Python

from pydantic import BaseModel, Field.\nfrom openai import OpenAI.\nimport os.\n\nclient = OpenAI(\n    api_key=os.getenv(\"DASHSCOPE_API_KEY\"),\n    # URL berikut adalah untuk wilayah Tiongkok (Singapura). Ganti {WorkspaceId} dengan ID Workspace Anda yang sebenarnya. URL bervariasi menurut wilayah.\n    base_url=\"https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1\"\n)\n\nclass UserInfo(BaseModel):\n    name: str = Field(description=\"Nama pengguna\")\n    age: int = Field(description=\"Usia pengguna dalam tahun\")\n\ncompletion = client.chat.completions.parse(\n    model=\"qwen4-max\",\n    messages=[\n        {\"role\": \"system\", \"content\": \"Ekstrak informasi nama dan usia.\"},\n        {\"role\": \"user\", \"content\": \"Nama saya Liu Wu, usia saya 25 tahun.\"},\n    ],\n    response_format=UserInfo,\n)\n\nresult = completion.choices[0].message.parsed.\nprint(f\"Name: {result.name}, Age: {result.age}\")

Node.js

import OpenAI from \"openai\";\nimport { zodResponseFormat } from \"openai/helpers/zod\";\nimport { z } from \"zod\";\n\nconst openai = new OpenAI(\n    {\n        apiKey: process.env.DASHSCOPE_API_KEY,\n        // URL berikut adalah untuk wilayah Tiongkok (Singapura). Ganti {WorkspaceId} dengan ID Workspace Anda yang sebenarnya. URL bervariasi menurut wilayah.\n        baseURL: \"https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1\"\n    }\n);\n\nconst UserInfo = z.object({\n  name: z.string().describe(\"Nama pengguna\"),\n  age: z.number().int().describe(\"Usia pengguna dalam tahun\"),\n});\n\nconst completion = await openai.chat.completions.parse({\n  model: \"qwen4-max\",\n  messages: [\n    { role: \"system\", content: \"Ekstrak informasi nama dan usia.\" },\n    { role: \"user\", content: \"Nama saya Liu Wu, saya berusia 25 tahun.\" },\n  ],\n  response_format: zodResponseFormat(UserInfo, \"user_info\"),\n});\n\nconst userInfo = completion.choices[0].message.parsed;\nconsole.log(`Name: ${userInfo.name}`);\nconsole.log(`Age: ${userInfo.age}`);
Menjalankan kode menghasilkan output berikut:
Name: Liu Wu, Age: 25

Panduan konfigurasi

Ikuti pedoman ini saat menggunakan JSON Schema untuk output terstruktur yang lebih andal:
  • Deklarasi field wajib Disarankan untuk mencantumkan field wajib dalam array required. Field opsional dapat dihilangkan, misalnya:
{\n  \"properties\": {\n    \"name\": {\"type\": \"string\"},\n    \"age\": {\"type\": \"integer\"},\n    \"email\": {\"type\": \"string\"}\n  },\n  \"required\": [\"name\", \"age\"]\n}
Jika input tidak menyediakan informasi email, output tidak akan menyertakan field ini.
  • Mengimplementasikan field opsional Selain mengecualikan dari required, Anda juga dapat mengizinkan tipe null:
{\n  \"properties\": {\n    \"name\": {\"type\": \"string\"},\n    \"email\": {\"type\": [\"string\", \"null\"]}  // Dapat berupa string atau null.\n  },\n  \"required\": [\"name\", \"email\"]  // Keduanya wajib.\n}
Output akan selalu menyertakan field email, tetapi nilainya dapat berupa null.
  • Konfigurasi additionalProperties Mengontrol apakah field tambahan yang tidak didefinisikan dalam skema diizinkan:
{\n  \"properties\": {\"name\": {\"type\": \"string\"}},\n  \"required\": [\"name\"],\n  \"additionalProperties\": true  // Mengizinkan field tambahan.\n}
Contoh input: \"Saya Zhang San, berusia 25 tahun\"; output: {\"name\": \"Zhang San\", \"age\": 25} (menyertakan field age yang tidak didefinisikan).

Nilai

Perilaku

Kasus penggunaan

false

Hanya mengeluarkan field yang didefinisikan

Kontrol struktur yang presisi

true

Mengizinkan field tambahan

Menangkap lebih banyak informasi

  • Tipe data yang didukung: string, number, integer, boolean, object, array, enum.

Peluncuran produksi

  • Validasi sebelum diteruskan ke downstream Saat menggunakan mode JSON Object, validasi output sebelum meneruskannya ke layanan downstream. Gunakan pustaka seperti jsonschema (Python), Ajv (JavaScript), atau Everit (Java) untuk memastikan output sesuai dengan JSON Schema yang diharapkan, sehingga mencegah kegagalan parsing downstream, kehilangan data, atau gangguan logika bisnis akibat field yang hilang, kesalahan tipe, atau format yang tidak valid. Jika gagal, coba ulang permintaan atau gunakan model untuk menulis ulang output.
  • Jangan menetapkan max_tokens Jangan menetapkan max_tokens saat output terstruktur diaktifkan. Parameter ini membatasi jumlah token output dan defaultnya adalah maksimum model. Penetapan parameter ini dapat memutus string JSON di tengah output, menghasilkan JSON yang tidak valid dan gagal diparsing.
  • Gunakan SDK untuk membuat skema Gunakan SDK untuk membuat skema secara otomatis. Hal ini menghindari kesalahan dari pemeliharaan manual serta menyediakan validasi dan parsing otomatis.
    Python
    from pydantic import BaseModel, Field.\nfrom typing import Optional.\nfrom openai import OpenAI.\nimport os.\n\nclient = OpenAI(\n    api_key=os.getenv(\"DASHSCOPE_API_KEY\"),\n    # URL berikut adalah untuk wilayah Singapura. Ganti {WorkspaceId} dengan ID Workspace Anda yang sebenarnya. URL bervariasi menurut wilayah.\n    base_url=\"https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1\"\n)\nclass UserInfo(BaseModel):\n    name: str = Field(description=\"Nama pengguna\")\n    age: int = Field(description=\"Usia pengguna\")\n    email: Optional[str] = None  # Bidang opsional.\n\ncompletion = client.chat.completions.parse(\n    model=\"qwen4-max\",\n    messages=[\n        {\"role\": \"system\", \"content\": \"Ekstrak informasi nama dan usia.\"},\n        {\"role\": \"user\", \"content\": \"Nama saya Liu Wu, usia saya 25 tahun.\"},\n    ],\n    response_format=UserInfo  # Teruskan model Pydantic secara langsung.\n)\n\nresult = completion.choices[0].message.parsed  # Hasil parsing yang aman tipe.\nprint(f\"Name: {result.name}, Age: {result.age}\")
    

Kode error

Jika panggilan model gagal dan mengembalikan pesan error, lihat Kode error untuk resolusi.