Skip to main content
Penggunaan aplikasi

Referensi API DashScope untuk aplikasi

Parameter input dan output untuk memanggil aplikasi Agent dan Workflow Alibaba Cloud Model Studio menggunakan API DashScope, disertai contoh pemanggilan untuk skenario umum.

Topik ini hanya berlaku untuk Edisi Internasional (Wilayah Singapura).
Panduan terkait Lihat Pemanggilan aplikasi.

Prasyarat

Selesaikan tugas-tugas berikut:
  1. Buat aplikasi: Buka Manajemen Aplikasi untuk membuat aplikasi Model Studio dan dapatkan ID aplikasinya.
  2. Dapatkan Kunci API: Dapatkan kunci API Anda dari Manajemen Kunci dan konfigurasikan kunci API sebagai variabel lingkungan.
  3. Instal SDK (opsional): Jika Anda menggunakan SDK untuk melakukan panggilan, instal SDK DashScope untuk bahasa pemrograman Anda.

Metode pemanggilan

  • Panggilan API HTTP URL Permintaan: POST https://dashscope-intl.aliyuncs.com/api/v1/apps/APP_ID/completion
    Ganti APP_ID dengan ID aplikasi aktual Anda.
  • Panggilan SDK SDK Python/Java: Titik akhir yang benar telah dikonfigurasi secara default. Titik akhir kustom: Konfigurasikan menggunakan parameter base_url.

Isi permintaan

app_idstring(wajib)ID Aplikasi.Dapatkan ID aplikasi dari kartu aplikasi di halaman Manajemen Aplikasi.
Dalam SDK Java, ini adalah appId. Saat memanggil melalui HTTP, masukkan ID aplikasi aktual Anda di URL, menggantikan APP_ID.
promptstring(wajib)Masukan pengguna yang memandu aplikasi dalam menghasilkan respons.
Saat memanggil melalui HTTP, masukkan prompt dalam objek input.
session_idstring (opsional)Pengidentifikasi riwayat percakapan.Saat Anda meneruskan session_id, permintaan secara otomatis menyertakan riwayat percakapan yang disimpan di cloud. Dalam kasus ini, Anda harus meneruskan prompt.Kedaluwarsa setelah 1 jam tidak aktif.
Dalam SDK Java, ini adalah setSessionId. Saat memanggil melalui HTTP, masukkan session_id dalam objek input.
messagesarray(opsional)Konteks percakapan yang diteruskan ke model diatur secara kronologis.Saat menggunakan parameter messages untuk percakapan multi-putaran, Anda tidak perlu menyertakan prompt atau session_id.Jika Anda meneruskan session_id dan messages, model akan menggunakan konten dalam messages serta mengabaikan session_id dan prompt.
Saat memanggil melalui HTTP, masukkan messages dalam objek input.
Untuk menggunakan parameter ini, versi SDK Dashscope Python Anda minimal 1.20.14, dan versi SDK Dashscope Java Anda minimal 2.17.0.

Jenis pesan

Pesan Sistemobject (opsional)Pesan sistem yang menetapkan peran, nada, tujuan tugas, atau batasan model. Biasanya ditempatkan pertama dalam array messages.
contentstring(wajib)Instruksi sistem yang menentukan peran, pedoman perilaku, gaya respons, dan batasan tugas model.rolestring(wajib)Peran pesan sistem, tetap sebagai system.
Pesan Penggunaobject(wajib)Pesan pengguna yang meneruskan pertanyaan, instruksi, atau konteks ke model.
contentstring(wajib)Konten pesan.
textstring(wajib)Teks masukan.
rolestring(wajib)Peran pesan pengguna, tetap sebagai user.
Pesan Asistenobject (opsional)Respons model, biasanya digunakan sebagai konteks yang dikembalikan ke model dalam percakapan multi-putaran.
contentstring(wajib)Konten teks respons model.rolestring(wajib)Peran pesan asisten, tetap sebagai assistant.
workspace string (opsional)Pengidentifikasi ruang bisnis. Dokumentasi terkait: Dapatkan ID Ruang Kerja.Anda hanya perlu meneruskan ID workspace saat memanggil aplikasi dalam sub-workspace.
Saat memanggil melalui HTTP, tentukan header X-DashScope-WorkSpace.
stream boolean (opsional) Nilai default adalah FalseAktifkan keluaran streaming.Atur ke True untuk meningkatkan pengalaman membaca dan mengurangi risiko timeout.Nilai parameter:
  • False (default): Model mengembalikan semua konten sekaligus setelah generasi selesai.
  • True (direkomendasikan): Model mengeluarkan konten saat menghasilkan, mengembalikan potongan data setiap kali menghasilkan konten baru. Anda harus membaca potongan ini secara real-time untuk menyusun respons lengkap.
Untuk mengimplementasikan keluaran streaming dengan SDK Java, gunakan antarmuka streamCall. Untuk mengimplementasikan keluaran streaming melalui HTTP, atur header X-DashScope-SSE ke enable.
incremental_output boolean (opsional) Nilai default adalah FalseAktifkan keluaran inkremental dalam mode streaming.Atur ke True untuk meningkatkan pengalaman membaca.Nilai parameter:
  • False (default): Setiap keluaran berisi seluruh urutan yang dihasilkan sejauh ini. Keluaran akhir adalah hasil lengkap.
I
I like
I like apple
I like apple.
  • True (direkomendasikan): Keluaran inkremental. Keluaran berikutnya tidak menyertakan konten yang telah dikeluarkan sebelumnya. Anda harus membaca segmen-segmen ini secara real-time untuk mendapatkan hasil lengkap.
I
like
apple
.
Dalam SDK Java, ini adalah incrementalOutput. Saat memanggil melalui HTTP, masukkan incremental_output dalam objek parameters.
flow_stream_mode string (opsional) Nilai default adalah full_thoughtsMode keluaran streaming untuk Workflow Application.Nilai parameter:
  • message_format (direkomendasikan): Mengeluarkan hasil dari node yang ditentukan (baik node Output atau node End) dalam field message.
    Di aplikasi konsol, aktifkan sakelar Stream untuk node target agar mengembalikan hasil dalam mode streaming. Jika dinonaktifkan, hasil akhir node dikembalikan sekaligus.
    Dalam SDK Java, ini adalah FlowStreamMode.MESSAGE_FORMAT.
  • full_thoughts (default): Mengeluarkan hasil dari semua node dalam field thoughts.
    Saat menggunakan mode ini, Anda juga harus mengatur parameter has_thoughts ke True.
    Dalam SDK Java, ini adalah FlowStreamMode.FULL_THOUGHTS.
  • agent_format: Mengeluarkan hasil dari node yang ditentukan (node LLM atau node akhir) dalam field text. Di aplikasi konsol, aktifkan sakelar Response untuk node target agar mengembalikan hasil dalam mode streaming.
    Jangan gunakan mode ini dengan node paralel, karena dapat menyebabkan pencampuran konten. Pastikan node yang diaktifkan memiliki urutan eksekusi yang jelas.
    Dalam SDK Java, ini adalah FlowStreamMode.AGENT_FORMAT.
Versi SDK Python Anda minimal 1.24.0, dan versi SDK Java Anda minimal 2.21.0. Saat memanggil melalui HTTP, masukkan flow_stream_mode dalam objek parameters.
biz_paramsobject (opsional)Gunakan field ini untuk meneruskan parameter saat aplikasi Anda menggunakan variabel kustom, node, atau plug-in.
Dalam SDK Java, ini adalah bizParams. Saat memanggil melalui HTTP, masukkan biz_params dalam objek input.
Untuk Workflow Application, teruskan variabel kustom untuk node awal secara langsung, contoh:
biz_params = {"city": "Hangzhou"}
Untuk Agent Application, teruskan variabel prompt atau variabel plug-in menggunakan field berikut:

Properti

user_defined_params object (opsional)Informasi parameter plug-in kustom.Plug-in yang ditambahkan dalam aplikasi tidak boleh duplikat, maksimal 10 plug-in.

Properti

tool_idstring (opsional)ID Plug-in, tersedia di kartu plug-in.${plugin_params}string (opsional)Objek paling dalam berisi beberapa pasangan kunci-nilai. Setiap pasangan kunci-nilai merepresentasikan nama parameter yang ditentukan pengguna dan nilainya. Contoh:
"article_index": 2
Langkah penggunaan:
  1. Asosiasikan plug-in yang ditentukan dengan aplikasi Anda dan Publish aplikasi.
  2. Teruskan informasi plug-in melalui parameter ini selama pemanggilan API.
Anda dapat memberikan beberapa pasangan kunci-nilai, di mana setiap kunci adalah TOOL_ID plug-in dan nilai adalah objek parameter yang dibutuhkan plug-in tersebut. Contoh:
"user_defined_params": {
        "<TOOL_ID>": {
            "article_index": 2},
        "<TOOL_ID>": {
            "article_index": 8}
        }
user_defined_tokens object (opsional)Informasi otentikasi tingkat pengguna untuk plug-in kustom.Plug-in yang ditambahkan dalam aplikasi tidak boleh duplikat, maksimal 10 plug-in.

Properti

tool_idstring (opsional)ID Plug-in, tersedia di kartu plug-in. Teruskan melalui field <TOOL_ID>.user_token string (opsional)Teruskan informasi otentikasi pengguna yang dibutuhkan plug-in ini, seperti nilai aktual DASHSCOPE_API_KEY.
Langkah penggunaan:
  1. Asosiasikan plug-in yang ditentukan dengan aplikasi Anda dan Publish aplikasi.
  2. Teruskan informasi otentikasi tingkat pengguna plug-in melalui parameter ini selama pemanggilan API.
Anda dapat memberikan beberapa pasangan kunci-nilai, di mana setiap kunci adalah TOOL_ID plug-in dan nilai adalah objek user_token.
has_thoughts boolean (opsional) Nilai default adalah FalseProses pemanggilan plug-in dan pengambilan basis pengetahuan, ditampilkan dalam field thoughts.Nilai parameter:
  • True: Keluaran disertakan.
  • False (default): Keluaran tidak disertakan.
Dalam SDK Java, ini adalah hasThoughts. Saat memanggil melalui HTTP, masukkan has_thoughts dalam objek parameters.
rag_options object (opsional)Digunakan untuk mengonfigurasi parameter terkait pengambilan, termasuk tetapi tidak terbatas pada mengambil basis pengetahuan atau dokumen tertentu.
Hanya Agent Application yang mendukung parameter ini.
Dalam SDK Java, ini adalah ragOptions. Saat memanggil melalui HTTP, masukkan rag_optionsdalam objek parameters.

Properti

pipeline_ids array(wajib)Daftar yang berisi satu atau lebih ID basis pengetahuan. Maksimal 5.Mengambil semua dokumen dalam basis pengetahuan yang ditentukan.Cara mendapatkan:
  • Basis Pengetahuan untuk mendapatkan ID basis pengetahuan;
  • Atau melalui API CreateIndex (hanya mendukung basis pengetahuan tak terstruktur), yang mengembalikan Data.Id.
Dalam SDK Java, ini adalah pipelineIds.
file_idsarray(opsional)Daftar yang berisi satu atau lebih ID dokumen tak terstruktur. Maksimal 5.Mengambil dokumen tak terstruktur dalam basis pengetahuan yang ditentukan.Saat meneruskan ID dokumen, Anda juga harus meneruskan ID basis pengetahuan yang dimiliki dokumen-dokumen ini dalam field pipeline_ids.Cara mendapatkan:
Dalam SDK Java, ini adalah fileIds.
metadata_filterobject (opsional)Digunakan untuk memfilter dokumen tak terstruktur berdasarkan metadata. Dengan menentukan satu atau lebih pasangan kunci-nilai, ambil dokumen tak terstruktur dalam basis pengetahuan yang ditentukan yang memiliki metadata ini.Prasyarat:Saat meneruskan metadata, Anda juga harus meneruskan ID basis pengetahuan yang dimiliki metadata ini dalam field pipeline_ids.Cara melihat:
  • Kunjungi halaman Basis Pengetahuan, klik View DetailsMetadata Information di kartu basis pengetahuan untuk melihat.
  • Atau melalui API ListChunks untuk mendapatkan.
Objek ini terdiri dari satu atau lebih pasangan kunci-nilai:
  • Kunci: String jenis, merepresentasikan nama metadata.
  • Nilai:
    • Pencocokan eksak: Nilai adalah String, artinya hanya dokumen dengan nilai field ini yang persis sama dengan string ini yang diambil.
      • Contoh: "author": "John.Doe"
    • Pencocokan "ATAU" multi-nilai: Nilai adalah Array (array) atau List (list) yang berisi beberapa String. Ini berarti dokumen dengan nilai field ini yang cocok dengan nilai apa pun dalam array diambil (logika ATAU).
      • Contoh: "source": ["internal_wiki", "public_docs"]
Logika kombinasi: Kunci berbeda menggunakan logika "DAN". Misalnya, "author": "John.Doe", "source": ["internal_wiki", "public_docs"] berarti memfilter dokumen yang ditulis oleh "John.Doe" DAN bersumber dari "internal_wiki" ATAU "public_docs".
Dalam SDK Java, ini adalah metadataFilter.
tags array (opsional)Daftar yang berisi satu atau lebih tag untuk dokumen tak terstruktur.Anda dapat mengambil dokumen tak terstruktur dengan tag ini.Cara melihat:
  • Percakapan satu putaran
  • Percakapan multi-putaran
  • Meneruskan parameter
  • Keluaran streaming
  • Pengambilan basis pengetahuan
  • Python
  • Java
  • HTTP
Contoh permintaan
import os
from http import HTTPStatus
from dashscope import Application
import dashscope
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
response = Application.call(
    # Jika Anda belum mengonfigurasi variabel lingkungan, ganti baris berikut dengan api_key="sk-xxx" menggunakan Kunci API Model Studio Anda. Namun, jangan hard code kunci API Anda langsung di kode untuk lingkungan produksi guna mengurangi risiko kebocoran kunci API.
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    app_id='APP_ID',# Ganti dengan ID aplikasi aktual Anda
    prompt='Siapa kamu?')

if response.status_code != HTTPStatus.OK:
    print(f'request_id={response.request_id}')
    print(f'code={response.status_code}')
    print(f'message={response.message}')
    print(f'Lihat dokumentasi: https://www.alibabacloud.com/help/zh/model-studio/developer-reference/error-code')
else:
    print(response.output.text)

Objek respons

status_code stringKode status HTTP.200 menunjukkan keberhasilan; jika tidak, permintaan gagal.Jika gagal, dapatkan kode kesalahan dari code dan detail kesalahan dari message.
SDK Java tidak mengembalikan parameter ini. Jika gagal, melemparkan pengecualian yang berisi konten status_code dan message.
request_id stringID unik untuk pemanggilan ini.
SDK Java mengembalikan ini sebagai requestId.
code stringKode kesalahan. Kosong jika berhasil.
Hanya dikembalikan oleh SDK Python.
message stringDetail kesalahan. Kosong jika berhasil.
Hanya dikembalikan oleh SDK Python.
output objectHasil pemanggilan.

properti output

text stringKonten respons model.finish_reason stringAlasan respons berakhir.stop berarti penyelesaian alami (menemui penanda yang telah ditentukan), null berarti gangguan paksa (misalnya, mencapai batas panjang maksimum atau penghentian manual).session_idstringID unik untuk percakapan saat ini.Teruskan ini dalam permintaan berikutnya untuk membawa catatan percakapan historis.thoughtsarraySaat Anda mengatur parameter has_thoughts ke True selama pemanggilan, Anda dapat melihat pemanggilan plug-in, proses pengambilan basis pengetahuan, atau proses pemikiran model pemikiran mendalam dalam thoughts.
thought stringProses pemikiran model.Saat Anda memilih model pemikiran mendalam di konsol Anda Agent Application dan berhasil menerbitkannya, jika Anda mengatur parameter has_thoughts ke True selama pemanggilan API, proses pemikiran model akan dikembalikan dalam field ini.reasoningContentstringProses pemikiran model.Saat Anda memilih model pemikiran mendalam di konsol Anda Workflow Application dan berhasil menerbitkannya, jika Anda mengatur parameter has_thoughts ke True selama pemanggilan API, proses pemikiran model akan dikembalikan dalam field ini.action_type stringJenis langkah eksekusi yang dikembalikan oleh model. Misalnya, API berarti mengeksekusi plug-in API, agentRag berarti mengeksekusi pengambilan basis pengetahuan, dan reasoning berarti mengeksekusi proses pemikiran model pemikiran mendalam.action_name stringNama aksi yang dieksekusi, seperti pengambilan basis pengetahuan, plug-in API, atau proses pemikiran.action stringLangkah-langkah eksekusi.action_input_stream stringHasil streaming dari parameter input.action_input stringParameter input plug-in.observation stringProses pengambilan atau eksekusi plug-in.
doc_references arrayDokumen referensi yang dikutip oleh model.Di konsol Model Studio Anda Agent Application, aktifkan sakelar Show Source dan Publish aplikasi agar doc_references mungkin berisi informasi valid.
index_id stringIndeks dokumen yang direferensikan, misalnya, [1].title stringJudul segmen teks yang direferensikan.doc_id stringID dokumen yang direferensikan.doc_name stringNama dokumen yang direferensikan.text stringKonten teks spesifik yang direferensikan oleh model.biz_id stringPengidentifikasi asosiasi bisnis yang direferensikan oleh model.images arrayDaftar URL gambar yang direferensikan oleh model.
usage objectPenggunaan token untuk permintaan ini.

Properti Penggunaan

modelsarrayInformasi model untuk pemanggilan ini.
model_id stringID model yang digunakan oleh aplikasi ini.input_tokens integerJumlah token input.output_tokens integerJumlah token output.
Contoh respons percakapan satu putaran
{
    "output": {
        "finish_reason": "stop",
        "session_id": "6105c965c31b40958a43dc93c28c7a59",
        "text": "Saya Qwen, asisten AI yang dikembangkan oleh Alibaba Cloud. Saya dirancang untuk menjawab berbagai pertanyaan, memberikan informasi, dan berdialog dengan pengguna. Bagaimana saya bisa membantu Anda?"
    },
    "usage": {
        "models": [
            {
                "output_tokens": 36,
                "model_id": "qwen-plus",
                "input_tokens": 74
            }
        ]
    },
    "request_id": "f97ee37d-0f9c-9b93-b6bf-bd263a232bf9"
}
Contoh respons basis pengetahuan tertentuSaat memanggil fitur basis pengetahuan aplikasi dan ingin mengeluarkan informasi dokumen referensi dari dokumen yang diambil, buka konsol Model Studio Anda Agent Application, klik Retrieve Configuration, aktifkan sakelar Show Source, dan Publish aplikasi.
{
    "text": "Berdasarkan anggaran Anda, saya merekomendasikan mempertimbangkan Bailian Zephyr Z9. Ponsel ini ringan dan portabel, dilengkapi layar 6,4 inci dengan resolusi 1080 x 2340 piksel, dipasangkan dengan penyimpanan 128GB dan RAM 6GB, menjadikannya sempurna untuk penggunaan sehari-hari<ref>[1]</ref>. Selain itu, dilengkapi baterai 4000mAh dan lensa zoom digital 30x untuk menangkap detail jarak jauh, dengan harga antara 2499-2799 yuan, sepenuhnya memenuhi persyaratan anggaran Anda<ref>[1]</ref>.",
    "finish_reason": "stop",
    "session_id": "6c1d47fa5eca46b2ad0668c04ccfbf13",
    "thoughts": null,
    "doc_references": [
        {
            "index_id": "1",
            "title": "Pengenalan Produk Ponsel Bailian",
            "doc_id": "file_7c0e9abee4f142f386e488c9baa9cf38_10317360",
            "doc_name": "Pengenalan Produk Ponsel Seri Bailian",
            "doc_url": null,
            "text": "【Nama Dokumen】:Pengenalan Produk Ponsel Seri Bailian\n【Judul】:Pengenalan Produk Ponsel Bailian\n【Konten】:Harga Referensi: 5999- 6499. Bailian Ace Ultra ——Untuk Gamer: Dilengkapi layar 6,67 inci 1080 x 2400 piksel, RAM internal 10GB dan penyimpanan 256GB, memastikan gaming lancar. Bailian Ace Ultra ——Untuk Gamer: Dilengkapi layar 6,67 inci 1080 x 2400 piksel, RAM internal 10GB dan penyimpanan 256GB, memastikan gaming lancar. Baterai 5500mAh dengan sistem pendingin cair menjaga perangkat tetap dingin selama sesi gaming berkepanjangan. Speaker ganda dinamis tinggi meningkatkan audio imersif untuk gaming. Harga Referensi: 3999- 4299. Bailian Zephyr Z9 ——Seni Desain Tipis: Desain ringan 6,4 inci 1080 x 2340 piksel, dipasangkan dengan penyimpanan 128GB dan RAM 6GB, menangani tugas sehari-hari dengan mudah. Baterai 4000mAh memastikan penggunaan sepanjang hari, sedangkan lensa zoom digital 30x menangkap detail jarak jauh tanpa mengorbankan daya. Harga Referensi: 2499- 2799. Bailian Flex Fold+ ——Era Baru Ponsel Lipat: Menggabungkan inovasi dan kemewahan dengan layar utama 7,6 inci 1800 x 2400 piksel dan layar luar 4,7 inci 1080 x 2400 piksel, mendukung desain henti-bebas multi-sudut untuk skenario berbeda. Penyimpanan 512GB, RAM 12GB, ditambah baterai 4700mAh dan kaca fleksibel ultra-tipis UTG, membuka babak baru untuk ponsel lipat. Selain itu, ponsel ini mendukung Dual SIM Dual Standby dan panggilan satelit, menjaga Anda tetap terhubung di seluruh dunia. Harga Eceran Referensi: 9999- 10999.\n",
            "biz_id": null,
            "images": [

            ],
            "page_number": [
                0]
        }]
}
Contoh respons kesalahanSaat permintaan gagal, respons menyertakan detail kesalahan melalui kode dan pesan.Contoh ini menunjukkan respons kesalahan untuk API-KEY yang tidak valid.
request_id=1d14958f-0498-91a3-9e15-be477971967b,
code=401,
message=Invalid API-key provided.

Batas laju

QPM (queries per minute) default untuk satu aplikasi adalah 15.000.

Kode kesalahan

Jika pemanggilan gagal dan mengembalikan kesalahan, lihat Informasi kesalahan untuk solusi.