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:
- Atur parameter
response_format: Di badan permintaan, aturresponse_formatmenjadi{\"type\": \"json_object\"}. - 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'.
- Atur parameter
-
Mode Skema JSON: Memastikan output sesuai dengan struktur yang ditentukan. Penggunaan: atur
response_formatmenjadi{\"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 |
|
|
Persyaratan prompt | Harus menyertakan \"JSON\" | Disarankan untuk mendeskripsikan secara eksplisit |
Kasus penggunaan | Output JSON fleksibel | Validasi skema presisi |
Model yang didukung
- 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)
- glm-5.1
- Mode non-berpikir: glm-5
deepseek-v4.1-flash-1017Lebih banyak model akan segera hadir.
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}
import OpenAI from \"openai\";\n\nconst openai = new OpenAI({\n // Jika Anda belum mengonfigurasi variabel lingkungan, ganti baris berikutnya dengan: apiKey: \"sk-xxx\"\n apiKey: process.env.DASHSCOPE_API_KEY,\n // Untuk model wilayah Singapura, ganti baseURL dengan: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1\n baseURL: \"https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1\"\n});\n\nconst completion = await openai.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 senang bermain basket serta bepergian\"\n }\n ],\n response_format: {\n type: \"json_object\"\n }\n});\n\nconst jsonString = completion.choices[0].message.content;\nconsole.log(jsonString);
Respons
{\n \"name\": \"Alex Brown\",\n \"age\": 34\n}
# ======= Penting =======\n# Kunci API berbeda berdasarkan wilayah. Untuk mendapatkan kunci API, kunjungi: https://www.alibabacloud.com/help/en/model-studio/get-api-key.\n# Jika Anda menggunakan model di wilayah Beijing, ganti URL dengan: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/chat/completions.\n# === Hapus komentar ini sebelum eksekusi ===\ncurl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/chat/completions \\\n-H \"Authorization: Bearer $DASHSCOPE_API_KEY\" \\\n-H \"Content-Type: application/json\" \\\n-d '{\n \"model\": \"qwen4-max\",\n \"messages\": [\n {\n \"role\": \"system\",\n \"content\": \"Anda perlu mengekstrak nama (string), usia (string), dan email (string). Keluarkan hasil sebagai string JSON. Jangan sertakan konten lain yang tidak relevan.\\nContoh:\\nQ: Nama saya Alice, saya berusia 25 tahun, dan email saya adalah alice@example.com\\nA: {\\\"name\\\":\\\"Alice\\\",\\\"age\\\":\\\"25 years old\\\",\\\"email\\\":\\\"alice@example.com\\\"}\\nQ: Nama saya Bob, saya berusia 30 tahun, dan email saya adalah bob@example.com\\nA: {\\\"name\\\":\\\"Bob\\\",\\\"age\\\":\\\"30 years old\\\",\\\"email\\\":\\\"bob@example.com\\\"}\\nQ: Nama saya Charlie, email saya adalah charlie@example.com, dan saya berusia 40 tahun\\nA: {\\\"name\\\":\\\"Charlie\\\",\\\"age\\\":\\\"40 years old\\\",\\\"email\\\":\\\"charlie@example.com\\\"}\"\n },\n {\n \"role\": \"user\",\n \"content\": \"Halo semua, nama saya Alex Brown, saya berusia 34 tahun, dan email saya adalah alexbrown@example.com\"\n }\n ],\n \"response_format\": {\n \"type\": \"json_object\"\n }\n}'
Respons
Contoh respons berikut menggunakanqwen3.8-max untuk menjelaskan field respons.{\n \"choices\": [\n {\n \"message\": {\n \"role\": \"assistant\",\n \"content\": \"{\\\"name\\\":\\\"Alex Brown\\\",\\\"age\\\":\\\"34 years old\\\"}\"\n },\n \"finish_reason\": \"stop\",\n \"index\": 0,\n \"logprobs\": null.\n }\n ],\n \"object\": \"chat.completion\",\n \"usage\": {\n \"prompt_tokens\": 207,\n \"completion_tokens\": 20,\n \"total_tokens\": 227,\n \"prompt_tokens_details\": {\n \"cached_tokens\": 0\n }\n },\n \"created\": 1756455080,\n \"system_fingerprint\": null,\n \"model\": \"qwen3.8-max\",\n \"id\": \"chatcmpl-624b665b-fb93-99e7-9ebd-bb6d86d314d2\"\n}
text.format. Untuk detail parameter dan panduan migrasi, lihat Responses Kompatibel OpenAI.- Python
- Node.js
- curl
from openai import OpenAI
import os
client = OpenAI(
# Kunci API berbeda berdasarkan wilayah. Jika Anda belum mengonfigurasi variabel lingkungan, ganti baris berikutnya dengan: api_key="sk-xxx"
api_key=os.getenv("DASHSCOPE_API_KEY"),
# Jika Anda menggunakan model wilayah Singapura, ganti base_url dengan: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)
response = client.responses.create(
model="qwen4-max",
input="Halo semua, nama saya Alex Brown, saya berusia 34 tahun, email saya adalah alexbrown@example.com, dan saya senang bermain bola basket serta bepergian. Ekstrak nama dan usia pengguna, lalu kembalikan dalam format JSON.",
text={"format": {"type": "json_object"}},
)
print(response.output_text)
Respons
{"nama": "Alex Brown", "usia": 34}
import OpenAI from "openai";
const openai = new OpenAI({
// Jika Anda belum mengonfigurasi variabel lingkungan, ganti baris berikutnya dengan: apiKey: "sk-xxx"
apiKey: process.env.DASHSCOPE_API_KEY,
baseURL: "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1"
});
const response = await openai.responses.create({
model: "qwen4-max",
input: "Halo semua, nama saya Alex Brown, saya berusia 34 tahun, email saya adalah alexbrown@example.com, dan saya senang bermain bola basket serta bepergian. Ekstrak nama dan usia pengguna, lalu kembalikan dalam format JSON.",
text: { format: { type: "json_object" } }
});
console.log(response.output_text);
Respons
{"nama": "Alex Brown", "usia": 34}
curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/responses \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen4-max",
"input": "Halo semua, nama saya Alex Brown, saya berusia 34 tahun, email saya adalah alexbrown@example.com, dan saya senang bermain bola basket serta bepergian. Ekstrak nama dan usia pengguna, lalu kembalikan dalam format JSON.",
"text": {
"format": {
"type": "json_object"
}
}
}'
Respons
Contoh respons berikut menggunakanqwen3.8-max untuk menjelaskan field respons.{
"id": "resp_3b59521f-fbef-9873-9c54-c3fdc94da946",
"created_at": 1793277220,
"model": "qwen3.8-max",
"object": "response",
"output": [
{
"id": "reasoning_3a4a1e6d-2a2f-4c3f-a3ea-0f0a5c1b9f11",
"summary": [
{
"text": "We need answer user request. Need output JSON only.",
"type": "summary_text"
}
],
"type": "reasoning"
},
{
"id": "msg_acbe8467-497c-4c09-8584-dae4a1c97f9b",
"content": [
{
"annotations": [],
"text": "{\"nama\": \"Alex Brown\", \"usia\": 34}",
"type": "output_text",
"logprobs": null
}
],
"role": "assistant",
"status": "completed",
"type": "message"
}
],
"status": "completed",
"text": {
"format": {
"type": "json_object"
},
"verbosity": null
},
"usage": {
"input_tokens": 123,
"output_tokens": 118,
"output_tokens_details": {
"reasoning_tokens": 95
},
"total_tokens": 241
}
}
- Python
- Java
- curl
import os
import dashscope
# Berikut adalah konfigurasi untuk wilayah Tiongkok (Singapura). Ganti {WorkspaceId} dengan ID ruang kerja aktual Anda. Nilai region berbeda-beda untuk setiap wilayah.
# Untuk model di wilayah Tiongkok (Singapura), ganti region dengan: ap-southeast-1
client = dashscope.Client(
# Jika Anda belum mengonfigurasi variabel lingkungan, ganti baris berikutnya dengan: api_key="sk-xxx" (kunci API Alibaba Cloud Model Studio),
api_key=os.getenv('DASHSCOPE_API_KEY'),
workspace="{WorkspaceId}",
region="ap-southeast-1",
)
messages=[
{
"role": "system",
"content": [{"text": "Ekstrak nama dan usia pengguna, lalu kembalikan dalam format JSON"}]
},
{
"role": "user",
"content": [{"text": "Halo semua, nama saya Alex Brown, saya berusia 34 tahun, email saya adalah alexbrown@example.com, dan saya senang bermain bola basket serta bepergian"}],
},
]
response = client.multimodal.chat.create(
model="qwen4-max",
messages=messages,
response_format={'type': 'json_object'}
)
json_string = response.choices[0].message.content
print(json_string)
Respons
{\n \"name\": \"Alex Brown\",\n \"age\": 34\n}
import java.util.Arrays;\nimport java.util.Collections;\nimport com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversation;\nimport com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationParam;\nimport com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationResult;\nimport com.alibaba.dashscope.common.MultiModalMessage;\nimport com.alibaba.dashscope.common.Role;\nimport com.alibaba.dashscope.exception.ApiException;\nimport com.alibaba.dashscope.exception.NoApiKeyException;\nimport com.alibaba.dashscope.exception.UploadFileException;\nimport com.alibaba.dashscope.common.ResponseFormat;\nimport com.alibaba.dashscope.utils.Constants;\n\npublic class Main {\n // Untuk menggunakan model di wilayah Singapura, ganti URL dengan: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1\n static {\n Constants.baseHttpApiUrl=\"https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1\";\n }\n public static void simpleMultiModalConversationCall()\n throws ApiException, NoApiKeyException, UploadFileException {\n MultiModalConversation conv = new MultiModalConversation();\n MultiModalMessage systemMessage = MultiModalMessage.builder().role(Role.SYSTEM.getValue())\n .content(Arrays.asList(\n Collections.singletonMap(\"text\", \"Ekstrak nama dan usia pengguna, lalu kembalikan dalam format JSON\"))).build();\n MultiModalMessage userMessage = MultiModalMessage.builder().role(Role.USER.getValue())\n .content(Arrays.asList(\n Collections.singletonMap(\"text\", \"Halo semua, nama saya Alex Brown, saya berusia 34 tahun, email saya alexbrown@example.com, dan saya suka bermain basket serta bepergian\"))).build();\n ResponseFormat jsonMode = ResponseFormat.builder().type(\"json_object\").build();\n MultiModalConversationParam param = MultiModalConversationParam.builder()\n // Jika Anda belum mengonfigurasi variabel lingkungan, ganti baris berikut dengan: .apiKey(\"sk-xxx\")\n .apiKey(System.getenv(\"DASHSCOPE_API_KEY\"))\n .model(\"qwen4-max\")\n .messages(Arrays.asList(systemMessage, userMessage))\n .responseFormat(jsonMode)\n .build();\n MultiModalConversationResult result = conv.call(param);\n System.out.println(result.getOutput().getChoices().get(0).getMessage().getContent().get(0).get(\"text\"));\n }\n public static void main(String[] args) {\n try {\n simpleMultiModalConversationCall();\n } catch (ApiException | NoApiKeyException | UploadFileException e) {\n System.out.println(e.getMessage());\n }\n }\n}
Respons
{\n \"name\": \"Alex Brown\",\n \"age\": 34\n}
# ======= Catatan penting =======\n# Untuk model wilayah Beijing, ganti URL dengan: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation.\n# Kunci API berbeda untuk setiap wilayah. Dapatkan kunci API: https://www.alibabacloud.com/help/en/model-studio/get-api-key.\n# === Hapus komentar ini sebelum menjalankan ===\n\ncurl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation \\\n-H \"Authorization: Bearer $DASHSCOPE_API_KEY\" \\\n-H \"Content-Type: application/json\" \\\n-d '{\n \"model\": \"qwen4-max\",\n \"input\": {\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 senang bermain basket serta bepergian\"\n }\n ]\n },\n \"parameters\": {\n \"response_format\": {\n \"type\": \"json_object\"\n }\n }\n}'
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}
import OpenAI from \"openai\";\n\nconst openai = new OpenAI({\n // Kunci API berbeda berdasarkan wilayah. Dapatkan kunci API: https://www.alibabacloud.com/help/en/model-studio/get-api-key.\n // Jika Anda belum mengonfigurasi variabel lingkungan, ganti baris berikutnya dengan: apiKey: \"sk-xxx\" (kunci API Model Studio)\n apiKey: process.env.DASHSCOPE_API_KEY,\n // Untuk model wilayah Beijing, ganti base_url dengan https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1\n baseURL: \"https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1\"\n});\n\nasync function main() {\n const response = await openai.chat.completions.create({\n model: \"qwen3-vl-plus\",\n messages: [{\n role: \"system\",\n content: [{\n type: \"text\",\n text: \"Anda adalah asisten yang membantu.\"\n }]\n },\n {\n role: \"user\",\n content: [{\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 {\n type: \"text\",\n 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 ],\n response_format: {type: \"json_object\"}\n });\n console.log(response.choices[0].message.content);\n}\n\nmain()
Respons
{\n \"ticket\": [\n {\n \"travel_date\": \"2013-06-29\",\n \"trains\": \"stream\",\n \"seat_num\": \"371\",\n \"arrival_site\": \"Development Zone\",\n \"price\": \"8.00\"\n }\n ],\n \"invoice\": [\n {\n \"invoice_code\": \"221021325353\",\n \"invoice_number\": \"10283819\"\n }\n ]\n}
# ======= Catatan penting =======\n# Untuk model wilayah Beijing, ganti base_url dengan: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/chat/completions.\n# Kunci API berbeda berdasarkan wilayah. Dapatkan kunci API: https://www.alibabacloud.com/help/en/model-studio/get-api-key.\n# === Hapus komentar ini sebelum menjalankan ===\n\ncurl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/chat/completions' \\\n--header \"Authorization: Bearer $DASHSCOPE_API_KEY\" \\\n--header 'Content-Type: application/json' \\\n--data '{\n \"model\": \"qwen3-vl-plus\",\n \"messages\": [\n {\"role\":\"system\",\n \"content\":[\n {\"type\": \"text\", \"text\": \"Anda adalah asisten yang membantu.\"}]},\n {\n \"role\": \"user\",\n \"content\": [\n {\"type\": \"image_url\", \"image_url\": {\"url\": \"http://duguang-labelling.oss-cn-shanghai.aliyuncs.com/demo_ocr/receipt_zh_demo.jpg\"}},\n {\"type\": \"text\", \"text\": \"Ekstrak informasi tiket (tipe array, mencakup travel_date, trains, seat_num, arrival_site, price) dan informasi faktur (tipe array, mencakup invoice_code dan invoice_number) dari gambar. Keluarkan JSON yang berisi array ticket dan invoice\"}\n ]\n }],\n \"response_format\":{\"type\": \"json_object\"}\n}'
Respons
{\n \"ticket\": [\n {\n \"travel_date\": \"2013-06-29\",\n \"trains\": \"stream\",\n \"seat_num\": \"371\",\n \"arrival_site\": \"Development Zone\",\n \"price\": \"8.00\"\n }\n ],\n \"invoice\": [\n {\n \"invoice_code\": \"221021325353\",\n \"invoice_number\": \"10283819\"\n }\n ]\n}
- Python
- Java
- curl
import os
import dashscope
# Berikut adalah konfigurasi untuk wilayah Tiongkok (Beijing). Ganti {WorkspaceId} dengan ID ruang kerja aktual Anda. Nilai region berbeda-beda untuk setiap wilayah.
# Untuk model di wilayah Tiongkok (Beijing), ganti region dengan: cn-beijing
client = dashscope.Client(
# Jika Anda belum mengonfigurasi variabel lingkungan, ganti baris berikutnya dengan: api_key="sk-xxx" (kunci API Model Studio),
api_key = os.getenv('DASHSCOPE_API_KEY'),
workspace = "{WorkspaceId}",
region = "cn-beijing",
)
messages = [
{
"role": "system",
"content": [
{"text": "Anda adalah asisten yang membantu."}]
},
{
"role": "user",
"content": [
{"image": "http://duguang-labelling.oss-cn-shanghai.aliyuncs.com/demo_ocr/receipt_zh_demo.jpg"},
{"text": "Ekstrak informasi tiket (tipe array, mencakup travel_date, trains, seat_num, arrival_site, price) dan informasi faktur (tipe array, mencakup invoice_code dan invoice_number) dari gambar. Keluarkan JSON yang berisi array ticket dan invoice"}]
}]
response = client.multimodal.chat.create(
model = 'qwen4-max',
messages = messages,
response_format={'type': 'json_object'}
)
json_string = response.choices[0].message.content
print(json_string)
Respons
{\n \"ticket\": [\n {\n \"travel_date\": \"2013-06-29\",\n \"trains\": \"Liushui\",\n \"seat_num\": \"371\",\n \"arrival_site\": \"Development Zone\",\n \"price\": \"8.00\"\n }\n ],\n \"invoice\": [\n {\n \"invoice_code\": \"221021325353\",\n \"invoice_number\": \"10283819\"\n }\n ]\n}
// Versi DashScope Java SDK harus 2.21.4 atau lebih tinggi.\n\nimport java.util.Arrays;\nimport java.util.Collections;\nimport com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversation;\nimport com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationParam;\nimport com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationResult;\nimport com.alibaba.dashscope.common.MultiModalMessage;\nimport com.alibaba.dashscope.common.Role;\nimport com.alibaba.dashscope.exception.ApiException;\nimport com.alibaba.dashscope.exception.NoApiKeyException;\nimport com.alibaba.dashscope.exception.UploadFileException;\nimport com.alibaba.dashscope.common.ResponseFormat;\nimport com.alibaba.dashscope.utils.Constants;\n\npublic class Main {\n \n // Untuk model wilayah Beijing, ganti URL dengan: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1\n static {\n Constants.baseHttpApiUrl=\"https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1\";\n }\n public static void simpleMultiModalConversationCall()\n throws ApiException, NoApiKeyException, UploadFileException {\n MultiModalConversation conv = new MultiModalConversation();\n MultiModalMessage systemMessage = MultiModalMessage.builder().role(Role.SYSTEM.getValue())\n .content(Arrays.asList(\n Collections.singletonMap(\"text\", \"Anda adalah asisten yang membantu.\"))).build();\n MultiModalMessage userMessage = MultiModalMessage.builder().role(Role.USER.getValue())\n .content(Arrays.asList(\n Collections.singletonMap(\"image\", \"http://duguang-labelling.oss-cn-shanghai.aliyuncs.com/demo_ocr/receipt_zh_demo.jpg\"),\n Collections.singletonMap(\"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 tiket dan faktur\"))).build();\n ResponseFormat jsonMode = ResponseFormat.builder().type(\"json_object\").build();\n MultiModalConversationParam param = MultiModalConversationParam.builder()\n // Jika Anda belum mengonfigurasi variabel lingkungan, ganti baris berikutnya dengan: .apiKey(\"sk-xxx\") (Kunci API Model Studio)\n .apiKey(System.getenv(\"DASHSCOPE_API_KEY\"))\n .model(\"qwen3-vl-plus\")\n .messages(Arrays.asList(systemMessage, userMessage))\n .responseFormat(jsonMode)\n .build();\n MultiModalConversationResult result = conv.call(param);\n System.out.println(result.getOutput().getChoices().get(0).getMessage().getContent().get(0).get(\"text\"));\n }\n public static void main(String[] args) {\n try {\n simpleMultiModalConversationCall();\n } catch (ApiException | NoApiKeyException | UploadFileException e) {\n System.out.println(e.getMessage());\n }\n }\n}
Respons
{\n \"ticket\": [\n {\n \"travel_date\": \"2013-06-29\",\n \"trains\": \"stream\",\n \"seat_num\": \"371\",\n \"arrival_site\": \"Development Zone\",\n \"price\": \"8.00\"\n }\n ],\n \"invoice\": [\n {\n \"invoice_code\": \"221021325353\",\n \"invoice_number\": \"10283819\"\n }\n ]\n}
# ======= Catatan penting =======\n# Untuk model wilayah Beijing, ganti URL dengan: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation.\n# Kunci API berbeda berdasarkan wilayah. Dapatkan kunci API: https://www.alibabacloud.com/help/en/model-studio/get-api-key.\n# === Hapus komentar ini sebelum menjalankan ===\n\ncurl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation \\\n-H \"Authorization: Bearer $DASHSCOPE_API_KEY\" \\\n-H 'Content-Type: application/json' \\\n-d '{\n \"model\": \"qwen3-vl-plus\",\n \"input\": {\n \"messages\": [\n {\n \"role\": \"system\",\n \"content\": [\n {\n \"text\": \"Anda adalah asisten yang membantu.\"\n }\n ]\n },\n {\n \"role\": \"user\",\n \"content\": [\n {\n \"image\": \"http://duguang-labelling.oss-cn-shanghai.aliyuncs.com/demo_ocr/receipt_zh_demo.jpg\"\n },\n {\n \"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 ]\n },\n \"parameters\": {\n \"response_format\": {\n \"type\": \"json_object\"\n }\n }\n}'
Respons
{\n \"output\": {\n \"choices\": [\n {\n \"message\": {\n \"content\": [\n {\n \"text\": \"{\\n \\\"ticket\\\": [\\n {\\n \\\"travel_date\\\": \\\"2013-06-29\\\",\\n \\\"trains\\\": \\\"nomor kereta\\\",\\n \\\"seat_num\\\": \\\"371\\\",\\n \\\"arrival_site\\\": \\\"Zona Pengembangan\\\",\\n \\\"price\\\": \\\"8.00\\\"\\n }\\n ],\\n \\\"invoice\\\": [\\n {\\n \\\"invoice_code\\\": \\\"221021325353\\\",\\n \\\"invoice_number\\\": \\\"10283819\\\"\\n }\\n ]\\n}\"\n }\n ],\n \"role\": \"assistant\"\n },\n \"finish_reason\": \"stop\"\n }\n ]\n },\n \"usage\": {\n \"total_tokens\": 598,\n \"input_tokens_details\": {\n \"image_tokens\": 418,\n \"text_tokens\": 68\n },\n \"output_tokens\": 112,\n \"input_tokens\": 486,\n \"output_tokens_details\": {\n \"text_tokens\": 112\n },\n \"image_tokens\": 418\n },\n \"request_id\": \"b129dce1-0d5d-4772-b8b5-bd3a1d5cde63\"\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}
import OpenAI from \"openai\";\n\n// Respons contoh yang telah ditentukan sebelumnya (untuk menunjukkan format output yang diharapkan kepada model)\n// Contoh 1: Respons lengkap dengan semua bidang.\nconst example1Response = JSON.stringify({\n info: { name: \"Alice\", age: \"25 tahun\", email: \"alice@example.com\" },\n hobby: [\"bernyanyi\"]\n}, null, 2);\n\n// Contoh 2: Respons dengan beberapa hobi.\nconst example2Response = JSON.stringify({\n info: { name: \"Bob\", age: \"30 tahun\", email: \"bob@example.com\" },\n hobby: [\"menari\", \"berenang\"]\n}, null, 2);\n\n// Contoh 3: Respons tanpa bidang hobi (hobi bersifat opsional)\nconst example3Response = JSON.stringify({\n info: { name: \"Dave\", age: \"28 tahun\", email: \"dave@example.com\" }\n}, null, 2);\n\n// Contoh 4: Respons lain tanpa bidang hobi.\nconst example4Response = JSON.stringify({\n info: { name: \"Sun Qi\", age: \"35 tahun\", email: \"sunqi@example.com\" }\n}, null, 2);\n\n// Inisialisasi konfigurasi klien OpenAI.\nconst openai = new OpenAI({\n // Jika Anda belum mengonfigurasi variabel lingkungan, ganti baris berikutnya dengan: apiKey: \"sk-xxx\" (kunci API Alibaba Cloud Model Studio),\n // Kunci API berbeda berdasarkan wilayah. Dapatkan kunci API: https://www.alibabacloud.com/help/en/model-studio/get-api-key.\n apiKey: process.env.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 baseURL: \"https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1\"\n});\n\n// Buat permintaan penyelesaian chat menggunakan prompt terstruktur untuk meningkatkan akurasi output.\nconst completion = await openai.chat.completions.create({\n model: \"qwen4-max\",\n messages: [\n {\n role: \"system\",\n content: `Ekstrak informasi pribadi dari input pengguna dan outputkan dalam format JSON Schema yang ditentukan:\n\n[Persyaratan format output]\nOutput harus secara ketat mengikuti struktur JSON ini:\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]\n1. name: Identifikasi nama pengguna dari teks, harus diekstrak.\n2. age: Identifikasi informasi usia, konversi ke format 'angka tahun', harus diekstrak.\n3. email: Identifikasi alamat email, pertahankan format asli, harus diekstrak.\n4. hobby: Identifikasi hobi pengguna, output sebagai array string; hilangkan bidang hobby sepenuhnya jika hobi tidak disebutkan.\n\n[Contoh referensi]\nContoh 1 (dengan hobi):\nQ: Nama saya Alice, saya berusia 25 tahun, email saya adalah alice@example.com, dan hobi saya adalah bernyanyi.\nA: ${example1Response}\n\nContoh 2 (dengan beberapa hobi):\nQ: Nama saya Bob, saya berusia 30 tahun, email saya adalah bob@example.com, dan saya menikmati menari serta berenang.\nA: ${example2Response}\n\nContoh 3 (tanpa hobi):\nQ: Nama saya Dave, saya berusia 28 tahun, dan email saya adalah dave@example.com.\nA: ${example3Response}\n\nContoh 4 (tanpa hobi):\nQ: Saya Sun Qi, berusia 35 tahun, dan email saya adalah sunqi@example.com.\nA: ${example4Response}\n\nEkstrak informasi dan output JSON secara ketat sesuai dengan format dan aturan di atas. Jangan sertakan bidang hobby jika pengguna tidak menyebutkan hobi.`\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: {\n type: \"json_object\"\n }\n});\n\n// Ekstrak dan cetak hasil JSON yang dihasilkan model.\nconst jsonString = completion.choices[0].message.content;\nconsole.log(jsonString);
Respons
{\n \"info\": {\n \"name\": \"Alex Brown\",\n \"age\": \"34 tahun\",\n \"email\": \"alexbrown@example.com\"\n },\n \"hobby\": [\n \"playing basketball\",\n \"traveling\"\n ]\n}
- Python
- Java
import os
import json
import dashscope
# Berikut adalah konfigurasi untuk wilayah Tiongkok (Singapura). Ganti {WorkspaceId} dengan ID ruang kerja aktual Anda. Nilai region berbeda-beda untuk setiap wilayah.
# Untuk model di wilayah Tiongkok (Singapura), ganti region dengan: ap-southeast-1
client = dashscope.Client(
# Jika Anda belum mengonfigurasi variabel lingkungan, ganti baris berikutnya dengan: api_key="sk-xxx" (kunci API Alibaba Cloud Model Studio),
api_key=os.getenv('DASHSCOPE_API_KEY'),
workspace="{WorkspaceId}",
region="ap-southeast-1",
)
# Contoh respons yang telah ditentukan sebelumnya (untuk menunjukkan kepada model format output yang diharapkan)
example1_response = json.dumps(
{
"info": {"name": "Alice", "age": "25 tahun", "email": "alice@example.com"},
"hobby": ["bernyanyi"]
},
ensure_ascii=False
)
example2_response = json.dumps(
{
"info": {"name": "Bob", "age": "30 tahun", "email": "bob@example.com"},
"hobby": ["menari", "berenang"]
},
ensure_ascii=False
)
example3_response = json.dumps(
{
"info": {"name": "Charlie", "age": "40 tahun", "email": "charlie@example.com"},
"hobby": ["Rap", "bola basket"]
},
ensure_ascii=False
)
messages=[
{
"role": "system",
"content": f"""Ekstrak informasi pribadi dari input pengguna dan keluarkan dalam format JSON Schema yang ditentukan:
[Persyaratan format output]
Output harus secara ketat mengikuti struktur JSON ini:
{{
"info": {{
"name": "tipe string, bidang wajib, nama pengguna",
"age": "tipe string, bidang wajib, format 'angka tahun', misalnya, '25 tahun'",
"email": "tipe string, bidang wajib, format email standar, misalnya, 'user@example.com'"
}},
"hobby": ["tipe array string, bidang opsional, berisi semua hobi pengguna; abaikan sepenuhnya jika tidak disebutkan"]
}}
[Aturan ekstraksi bidang]
1. name: Identifikasi nama pengguna dari teks, wajib diekstrak.
2. age: Identifikasi informasi usia, konversi ke format 'number years old', wajib diekstrak.
3. email: Identifikasi alamat email, pertahankan format asli, wajib diekstrak.
4. hobby: Identifikasi hobi pengguna, output sebagai array string; abaikan bidang hobby sepenuhnya jika hobi tidak disebutkan.
[Contoh referensi]
Contoh 1 (dengan hobi):
Q: Nama saya Alice, saya berusia 25 tahun, email saya adalah alice@example.com, dan hobi saya adalah bernyanyi.
A: {example1_response}
Contoh 2 (dengan beberapa hobi):
Q: Nama saya Bob, saya berusia 30 tahun, email saya adalah bob@example.com, dan saya menikmati menari serta berenang.
A: {example2_response}
Contoh 3 (dengan beberapa hobi):
Q: Email saya adalah charlie@example.com, saya berusia 40 tahun, nama saya Charlie, dan saya bisa Rap serta bermain basket.
A: {example3_response}
Ekstrak informasi dan output JSON secara ketat sesuai dengan format dan aturan di atas. Jangan sertakan bidang hobby jika pengguna tidak menyebutkan hobi."""
},
{
"role": "user",
"content": [{"text": "Halo semua, nama saya Alex Brown, saya berusia 34 tahun, email saya adalah alexbrown@example.com, dan saya menikmati bermain basket serta traveling"}],
},
]
response = client.multimodal.chat.create(
model="qwen4-max",
messages=messages,
response_format={'type': 'json_object'}
)
json_string = response.choices[0].message.content
print(json_string)
Respons
{\n \"info\": {\n \"name\": \"Alex Brown\",\n \"age\": \"34 years old\",\n \"email\": \"alexbrown@example.com\"\n },\n \"hobby\": [\n \"playing basketball\",\n \"traveling\"\n ]\n}
import java.util.Arrays;\nimport java.util.Collections;\nimport com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversation;\nimport com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationParam;\nimport com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationResult;\nimport com.alibaba.dashscope.common.MultiModalMessage;\nimport com.alibaba.dashscope.common.Role;\nimport com.alibaba.dashscope.exception.ApiException;\nimport com.alibaba.dashscope.exception.NoApiKeyException;\nimport com.alibaba.dashscope.exception.UploadFileException;\nimport com.alibaba.dashscope.common.ResponseFormat;\nimport com.alibaba.dashscope.utils.Constants;\n\npublic class Main {\n // Untuk menggunakan model di wilayah Singapura, ganti URL dengan: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1\n static {\n Constants.baseHttpApiUrl=\"https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1\";\n }\n public static void simpleMultiModalConversationCall()\n throws ApiException, NoApiKeyException, UploadFileException {\n MultiModalConversation conv = new MultiModalConversation();\n MultiModalMessage systemMessage = MultiModalMessage.builder().role(Role.SYSTEM.getValue())\n .content(Arrays.asList(\n Collections.singletonMap(\"text\", \"\"\"\n Ekstrak informasi pribadi dari input pengguna dan keluarkan dalam format JSON Schema yang ditentukan:\n\n[Persyaratan Format Output]\nOutput harus secara ketat mengikuti struktur JSON di bawah ini:\n{\n \"info\": {\n \"name\": \"Tipe String, bidang wajib, nama pengguna\",\n \"age\": \"Tipe String, bidang wajib, dalam format 'Number years old', misalnya, '25 years old'\",\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. Jika tidak ada hobi yang disebutkan, jangan sertakan bidang ini dalam output.\"]\n}\n\n[Aturan Ekstraksi Bidang]\n1. name: Identifikasi nama pengguna dari teks. Ini adalah bidang wajib.\n2. age: Identifikasi informasi usia dan ubah menjadi format 'Number years old'. Ini adalah bidang wajib.\n3. email: Identifikasi alamat email dan pertahankan format aslinya. Ini adalah bidang wajib.\n4. hobby: Identifikasi hobi pengguna dan keluarkan sebagai array string. Jika tidak ada hobi yang disebutkan, hilangkan sepenuhnya bidang hobby.\n\n[Contoh]\nContoh 1 (dengan hobi):\nQ: Nama saya Alice, saya berusia 25 tahun, email saya alice@example.com, dan hobi saya menyanyi.\nA: {\"info\":{\"name\":\"Alice\",\"age\":\"25 years old\",\"email\":\"alice@example.com\"},\"hobby\":[\"singing\"]}\n\nContoh 2 (dengan beberapa hobi):\nQ: Nama saya Bob, saya berusia 30 tahun, email saya bob@example.com, dan saya suka menari serta berenang.\nA: {\"info\":{\"name\":\"Bob\",\"age\":\"30 years old\",\"email\":\"bob@example.com\"},\"hobby\":[\"dancing\",\"swimming\"]}\n\nContoh 3 (tanpa hobi):\nQ: Nama saya Charlie, email saya charlie@example.com, dan saya berusia 40 tahun.\nA: {\"info\":{\"name\":\"Charlie\",\"age\":\"40 years old\",\"email\":\"charlie@example.com\"}}\"\"\"))).build();\n MultiModalMessage userMessage = MultiModalMessage.builder().role(Role.USER.getValue())\n .content(Arrays.asList(\n Collections.singletonMap(\"text\", \"Halo semua, nama saya Alex Brown, saya berusia 34 tahun, email saya alexbrown@example.com, dan saya senang bermain basket serta bepergian.\"))).build();\n ResponseFormat jsonMode = ResponseFormat.builder().type(\"json_object\").build();\n MultiModalConversationParam param = MultiModalConversationParam.builder()\n // Jika Anda belum mengonfigurasi variabel lingkungan, ganti baris berikut dengan: .apiKey(\"sk-xxx\")\n .apiKey(System.getenv(\"DASHSCOPE_API_KEY\"))\n .model(\"qwen4-max\")\n .messages(Arrays.asList(systemMessage, userMessage))\n .responseFormat(jsonMode)\n .build();\n MultiModalConversationResult result = conv.call(param);\n System.out.println(result.getOutput().getChoices().get(0).getMessage().getContent().get(0).get(\"text\"));\n }\n public static void main(String[] args) {\n try {\n simpleMultiModalConversationCall();\n } catch (ApiException | NoApiKeyException | UploadFileException e) {\n System.out.println(e.getMessage());\n }\n }\n}
Respons
{\n \"info\": {\n \"name\": \"Alex Brown\",\n \"age\": \"34 tahun\",\n \"email\": \"alexbrown@example.com\"\n },\n \"hobby\": [\n \"Bermain bola basket\",\n \"Bepergian\"\n ]\n}
Mendapatkan output terstruktur
Mengaturresponse_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}
name dan age) serta satu bidang opsional email.
Model di wilayah Singapura belum didukung.
Cara menggunakan
Dengan metodeparse 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}`);
Name: Liu Wu, Age: 25
text.format, yang mendukung jenis json_schema dan json_object. Metode parse dari SDK OpenAI juga dapat digunakan: teruskan kelas Pydantic atau objek Zod ke text_format.from pydantic import BaseModel, Field
from openai import OpenAI
import os
client = OpenAI(
api_key=os.getenv("DASHSCOPE_API_KEY"),
# URL berikut adalah untuk wilayah Tiongkok (Singapura). Ganti {WorkspaceId} dengan ID Workspace Anda yang sebenarnya. URL bervariasi menurut wilayah.
base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1"
)
class UserInfo(BaseModel):
name: str = Field(description="Nama pengguna")
age: int = Field(description="Usia pengguna dalam tahun")
response = client.responses.parse(
model="qwen4-max",
input="Nama saya Liu Wu, usia saya 25 tahun.",
text_format=UserInfo,
)
result = response.output_parsed
print(f"Name: {result.name}, Age: {result.age}")
Name: Liu Wu, Age: 25
Java SDK belum didukung.
Python
import os
import dashscope
import json
# Berikut adalah konfigurasi untuk wilayah Tiongkok (Singapura). Ganti {WorkspaceId} dengan ID ruang kerja aktual Anda. Nilai region berbeda-beda untuk setiap wilayah.
client = dashscope.Client(
# Jika variabel lingkungan belum dikonfigurasi, ganti baris berikut dengan: api_key="sk-xxx"
api_key=os.getenv("DASHSCOPE_API_KEY"),
workspace="{WorkspaceId}",
region="ap-southeast-1",
)
messages = [
{
"role": "user",
"content": [{"text": "Nama saya Liu Wu, usia saya 25 tahun."}],
},
]
response = client.multimodal.chat.create(
model="qwen4-max",
messages=messages,
response_format={
"type": "json_schema",
"json_schema": {
"name": "user_info",
"strict": True,
"schema": {
"properties": {
"name": {"title": "Nama", "type": "string"},
"age": {"title": "Usia", "type": "integer"},
},
"required": ["name", "age"],
"title": "UserInfo",
"type": "object",
},
},
},
)
json_object = json.loads(response.choices[0].message.content)
print(f"Name: {json_object['name']}, Age: {json_object['age']}")
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}
-
Mengimplementasikan field opsional
Selain mengecualikan dari
required, Anda juga dapat mengizinkan tipenull:
{\n \"properties\": {\n \"name\": {\"type\": \"string\"},\n \"email\": {\"type\": [\"string\", \"null\"]} // Dapat berupa string atau null.\n },\n \"required\": [\"name\", \"email\"] // Keduanya wajib.\n}
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}
\"Saya Zhang San, berusia 25 tahun\"; output: {\"name\": \"Zhang San\", \"age\": 25} (menyertakan field age yang tidak didefinisikan).
Nilai | Perilaku | Kasus penggunaan |
|---|---|---|
| Hanya mengeluarkan field yang didefinisikan | Kontrol struktur yang presisi |
| 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_tokenssaat 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.
PythonCopy
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}\")