Gunakan API Responses yang kompatibel dengan OpenAI untuk memanggil model Qwen. Topik ini menjelaskan parameter input dan output serta menyediakan contoh pemanggilan.
Keunggulan dibandingkan API OpenAI Chat Completions:- Alat bawaan: Hasilkan performa lebih baik pada tugas kompleks dengan alat bawaan seperti pencarian web, scraping web, interpreter kode, teks-ke-gambar, gambar-ke-gambar, dan pencarian basis pengetahuan. Untuk informasi selengkapnya, lihat pemanggilan alat.
- Input lebih fleksibel: Mendukung input berupa string langsung maupun array pesan dalam format chat.
- Pengelolaan konteks yang disederhanakan: Hindari konstruksi manual array riwayat pesan dengan meneruskan
previous_response_iddari respons terakhir. - Peng-cache-an konteks yang praktis: Tambahkan
x-dashscope-session-cache: enable(nilai default: disable) ke header permintaan untuk mengaktifkan peng-cache-an otomatis di sisi server terhadap konteks percakapan. Ini mengurangi latensi inferensi dan biaya untuk percakapan multi-putaran tanpa perubahan kode. Untuk detailnya, lihat cache sesi.
Kompatibilitas dan keterbatasan
API ini kompatibel dengan OpenAI untuk mengurangi biaya migrasi developer, tetapi berbeda dalam parameter, fungsionalitas, dan perilakunya.
Prinsip Inti: Hanya parameter yang secara eksplisit tercantum dalam dokumen ini yang diproses. Parameter OpenAI apa pun yang tidak disebutkan akan diabaikan.
Perbedaan utama berikut akan membantu Anda beradaptasi dengan cepat:
- Parameter yang Tidak Didukung: API ini tidak mendukung beberapa parameter API OpenAI, seperti parameter eksekusi asinkron
background. API saat ini hanya mendukung panggilan sinkron. - Kontrol Upaya Reasoning: Gunakan parameter
reasoning.effortuntuk mengontrol upaya reasoning model. Untuk detail penggunaan, lihat deskripsi parameter ini.
Singapore
base_url untuk konfigurasi pemanggilan SDK adalah https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1.
Titik akhir permintaan HTTP: POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/responses
China (Beijing)
base_url untuk konfigurasi pemanggilan SDK: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1
Titik akhir permintaan HTTP: POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/responses
AS (Virginia)
Konfigurasi pemanggilan SDK base_url: https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/compatible-mode/v1
Titik akhir permintaan HTTP: POST https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/compatible-mode/v1/responses
Jerman (Frankfurt)
Konfigurasi pemanggilan SDK base_url: https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/compatible-mode/v1
Titik akhir permintaan HTTP: POST https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/compatible-mode/v1/responses
China (Hong Kong)
Konfigurasi pemanggilan SDK base_url: https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/compatible-mode/v1
Titik akhir permintaan HTTP: POST https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/compatible-mode/v1/responses
Jepang (Tokyo)
Konfigurasi pemanggilan SDK base_url: https://{WorkspaceId}.ap-northeast-1.maas.aliyuncs.com/compatible-mode/v1
Titik akhir permintaan HTTP: POST https://{WorkspaceId}.ap-northeast-1.maas.aliyuncs.com/compatible-mode/v1/responses
Ganti {WorkspaceId} dengan ID ruang kerja Anda yang sebenarnya.
PentingAlibaba Cloud Model Studio telah merilis domain khusus ruang kerja untuk wilayah China (Beijing), Singapura, dan China (Hong Kong). Domain khusus baru ini memberikan performa unggul dan stabilitas lebih tinggi untuk permintaan inferensi. Kami merekomendasikan migrasi ke domain baru:
- China (Beijing): dari
https://dashscope.aliyuncs.comkehttps://{WorkspaceId}.cn-beijing.maas.aliyuncs.com - Singapura: dari
https://dashscope-intl.aliyuncs.comkehttps://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com - China (Hong Kong): dari
https://cn-hongkong.dashscope.aliyuncs.comkehttps://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com
{WorkspaceId} adalah ID ruang kerja Anda, yang dapat ditemukan di halaman Detail Ruang Kerja di Konsol Alibaba Cloud Model Studio. Domain lama tetap berfungsi penuh.
PentingJalur URL lama /api/v2/apps/protocols/compatible-mode/v1/responses untuk API Responses yang kompatibel dengan OpenAI akan segera ditinggalkan. Harap segera migrasi ke jalur baru /compatible-mode/v1/responses.
Badan permintaanmodel ID model yang akan digunakan. Model yang didukung
PentingModel generasi teks yang tidak tercantum dalam daftar di atas tetapi tersedia melalui Alibaba Cloud Model Studio hanya mendukung kemampuan kompatibilitas dasar. Kemampuan Agent (alat bawaan, dll.) terbatas. input Input untuk model. Format berikut didukung:
Jenis item array EasyInputMessage Objek dengan Properti role Peran penulis pesan. Nilai yang valid: content Konten pesan. Kontennya berupa
Item array konten type Menentukan jenis konten. Nilai yang valid adalah text Konten teks. Diperlukan ketika image_url Mendukung URL atau data yang dikodekan Base64. Diperlukan ketika file_url URL publik file. Diperlukan ketika Batas jumlah halaman PDF bergantung pada type Tetap sebagai ResponseOutputMessage Pesan keluaran model. Untuk melanjutkan percakapan, Anda dapat meneruskan objek Properti type Tetap sebagai id Pengidentifikasi unik pesan keluaran, dari respons sebelumnya. role Tetap sebagai status Status pesan. Nilai yang valid: content Array konten, di mana elemennya berupa objek Properti type Tetap sebagai text Teks respons. annotations Informasi anotasi. Pemanggilan fungsi Instruksi terstruktur yang dihasilkan ketika model memutuskan untuk memanggil alat eksternal. Properti type Tetap sebagai id Pengidentifikasi unik untuk pemanggilan fungsi, dari respons sebelumnya. name Nama fungsi alat. arguments Argumen pemanggilan alat, dalam format string JSON. call_id Pengidentifikasi untuk pemanggilan alat. Ini harus cocok dengan status Status. Nilai yang valid: Keluaran pemanggilan fungsi Keluaran pemanggilan alat. Dalam daftar pesan, objek ini harus segera mengikuti pesan Properti type Tetap sebagai id Pengidentifikasi unik untuk keluaran pemanggilan fungsi. call_id Pengidentifikasi pemanggilan alat harus cocok dengan output Hasil eksekusi fungsi alat. status Status. Nilai yang valid: Reasoning Proses reasoning model. Anda dapat meneruskan item Properti type Tetap sebagai id Pengidentifikasi unik untuk konten reasoning, dari respons sebelumnya. summary Konten ringkasan reasoning. Properti type Tetap sebagai text Teks ringkasan. status Status. Nilai yang valid: Pemanggilan Pencarian Web Objek pemanggilan pencarian web. Anda dapat meneruskan kembali item web_search_call dari output respons sebelumnya ke input, memberikan konteks hasil pencarian dalam percakapan multi-putaran. Properti type Selalu id Pengidentifikasi unik pemanggilan pencarian, dari respons sebelumnya. status Status pencarian. Nilai yang valid: action Rincian tindakan pencarian. Hanya jenis Properti type Jenis pencarian. Selalu queries Daftar kueri pencarian. Setiap elemen berupa string. sources Daftar sumber hasil pencarian. Properti type Jenis sumber. Selalu url URL sumber. instructions Dimasukkan di awal konteks sebagai instruksi sistem. Ketika previous_response_id ID unik dari respons sebelumnya. conversation Percakapan tempat respons saat ini berada (lihat API Percakapan). Riwayat percakapan secara otomatis disertakan sebagai konteks. Input dan output permintaan ini ditambahkan ke percakapan setelah selesai. Tidak dapat digunakan dengan stream Mengaktifkan keluaran streaming. Jika diatur ke store Menentukan apakah respons model yang dihasilkan untuk sesi ini disimpan.
tools Array alat yang dapat dipanggil model saat menghasilkan respons. Mendukung alat bawaan dan alat
Properti Pencarian web Mencari informasi terkini di internet. Dokumentasi terkait: Pencarian Web Properti type Tetap sebagai Contoh: Mengakses dan mengekstraksi konten dari halaman web. Harus digunakan dengan alat Properti type Tetap sebagai Contoh: Menjalankan kode dalam lingkungan sandbox untuk melakukan tugas seperti analisis data. Untuk model Properti type Tetap sebagai Contoh: Mencari gambar berdasarkan deskripsi teks. Dokumentasi terkait: Pencarian Teks-ke-Gambar Properti type Tetap sebagai Contoh: Mencari gambar serupa atau terkait berdasarkan gambar input. Input harus menyertakan URL gambar. Dokumentasi terkait: Pencarian Gambar-ke-Gambar Properti type Tetap sebagai Contoh: Menjalankan pengambilan pengetahuan dengan mencari basis pengetahuan tertentu. Dokumentasi terkait: Pengambilan Pengetahuan Properti type Tetap sebagai vector_store_ids ID basis pengetahuan yang akan dicari. Saat ini, hanya satu ID basis pengetahuan yang dapat diberikan. Contoh: Memanggil layanan eksternal melalui Model Context Protocol (MCP). Dokumentasi terkait: MCP Properti type Tetap sebagai server_protocol Protokol komunikasi dengan layanan MCP, seperti server_label Label yang digunakan untuk mengidentifikasi layanan MCP. server_description Deskripsi layanan. Membantu model memahami fungsinya dan kapan harus menggunakannya. server_url URL titik akhir layanan MCP. headers Header permintaan, digunakan untuk membawa informasi seperti autentikasi (misalnya, Contoh: Memungkinkan model memanggil fungsi yang ditentukan developer. Ketika model menentukan bahwa alat perlu dipanggil, respons mengembalikan item keluaran bertipe Properti type Harus diatur ke name Nama alat. Hanya boleh berisi huruf, angka, garis bawah ( description Deskripsi alat, yang membantu model memutuskan kapan dan bagaimana memanggilnya. parameters Definisi parameter untuk alat, yang harus berupa objek JSON Schema yang valid. Jika
Contoh: tool_choice Mengontrol cara model memilih dan memanggil alat. Parameter ini mendukung dua format: mode string dan mode objek. Mode string
Membatasi model pada himpunan alat tertentu untuk dipilih dan dipanggil. Properti mode
tools Daftar definisi alat yang boleh dipanggil model. type Jenis konfigurasi alat. Tetap sebagai suhu Suhu pengambilan sampel, yang mengontrol keragaman teks yang dihasilkan. Nilai yang lebih tinggi membuat output lebih acak dan beragam, sedangkan nilai yang lebih rendah membuatnya lebih fokus dan deterministik. Kisaran nilai: [0, 2) Baik top_p Ambang batas probabilitas untuk pengambilan sampel top-p, yang mengontrol keragaman teks yang dihasilkan. Nilai yang lebih tinggi membuat output lebih acak dan beragam, sedangkan nilai yang lebih rendah membuatnya lebih fokus dan deterministik. Kisaran nilai: (0, 1.0] Baik enable_thinking Mengaktifkan atau menonaktifkan mode reasoning. Ketika diaktifkan, model melakukan langkah reasoning sebelum merespons. Proses reasoning dikembalikan sebagai item keluaran bertipe Nilai yang valid:
Untuk nilai default berbagai model, lihat Model yang Didukung.
reasoning Mengontrol upaya reasoning model. Model melakukan langkah reasoning sebelum membalas, dan proses reasoning dikembalikan melalui item keluaran bertipe Properti effort Mendukung 7 tingkat bertahap:
ocr_options Parameter tugas bawaan OCR. Hanya berlaku untuk model Saat mengurai file PDF, nilai
max_output_tokens
Nilai minimum adalah 16. Jika output model melebihi nilai ini, generasi dihentikan lebih awal dan statusnya | Panggilan dasarKeluaran streamingPercakapan multi-putaranAlat bawaanPemanggilan fungsiPemahaman dokumenCache sesiMekanisme hit cache: Cache sesi mencocokkan pada awalan prompt sistem. Permintaan berikutnya hit cache ketika prompt sistemnya identik dengan konten yang di-cache. Mengubah prompt pengguna tidak memengaruhi hit cache. Untuk mengonfirmasi apakah cache dihit, periksa |
Objek respons (keluaran non-streaming)id Pengidentifikasi unik untuk respons ini, berupa UUID. ID ini berlaku selama 7 hari dan dapat digunakan dalam parameter created_at Timestamp Unix (dalam detik) untuk permintaan ini. object Jenis objek, yang selalu status Status generasi respons. Nilai yang valid:
model ID model yang digunakan untuk menghasilkan respons. output Array item keluaran yang dihasilkan model. Jenis dan urutan elemen dalam array bergantung pada respons model. Properti elemen array type Jenis item keluaran. Nilai yang valid:
id Pengidentifikasi unik item keluaran. Semua jenis item keluaran berisi bidang ini. role Peran pesan selalu status Status item keluaran. Nilai yang valid: name Nama alat atau fungsi. Parameter ini ada ketika Untuk Untuk arguments Parameter untuk pemanggilan alat, dalam format string JSON. Parameter ini ada ketika
call_id ID unik untuk pemanggilan fungsi. Parameter ini hanya disertakan ketika content Array konten pesan. Parameter ini ada hanya jika Properti elemen array type Jenis konten. Nilainya tetap text Konten teks yang dihasilkan model. annotations Array anotasi teks. Biasanya berupa array kosong. summary Array ringkasan reasoning. Bidang ini ada hanya ketika action Informasi tentang tindakan pencarian. Parameter ini ada hanya ketika Properti query Kata kunci kueri pencarian. type Jenis pencarian. Nilainya selalu sources Daftar sumber pencarian. Setiap elemen berisi bidang code Kode yang dihasilkan dan dieksekusi model. Ini ada hanya ketika outputs Array keluaran eksekusi kode. Ini ada hanya ketika container_id Pengidentifikasi kontainer untuk interpreter kode. Parameter ini ada hanya ketika goal Deskripsi informasi yang akan diekstraksi dari halaman web. Parameter ini tersedia hanya ketika output Keluaran pemanggilan alat. Keluarannya berupa string.
urls Daftar URL untuk halaman web yang diekstraksi. Parameter ini tersedia hanya ketika server_label Label untuk layanan MCP. Ini muncul hanya ketika queries Daftar kueri untuk pengambilan basis pengetahuan. Parameter ini ada hanya ketika results Array hasil pencarian dari basis pengetahuan. Parameter ini ada hanya ketika Properti elemen array file_id ID file dokumen yang cocok. filename Nama file dokumen yang cocok. score Skor relevansi kecocokan. Nilainya berkisar dari 0 hingga 1. Nilai yang lebih besar menunjukkan relevansi yang lebih tinggi. text Cuplikan konten dari dokumen yang cocok. usage Informasi tentang konsumsi token untuk permintaan ini. Properti input_tokens Jumlah token dalam input. Catatan Tambahan output_tokens Jumlah token dalam output model. total_tokens Jumlah total token yang dikonsumsi adalah jumlah dari input_tokens_details Klasifikasi detail halus token input. Properti cached_tokens Jumlah token yang hit cache. Untuk informasi selengkapnya, lihat peng-cache-an konteks. output_tokens_details Rincian terperinci token output. Properti reasoning_tokens Jumlah token reasoning. x_details Array rincian penagihan untuk permintaan. Ini memberikan rincian lebih granular token multimodal daripada bidang Properti input_tokens Jumlah token dalam input. Catatan Tambahan output_tokens Jumlah token dalam output model. total_tokens Jumlah total token yang dikonsumsi adalah jumlah dari x_billing_type Nilainya tetap image_tokens Jumlah token untuk input gambar. Bidang ini dikembalikan ketika input menyertakan gambar dan setara dengan input_tokens_details Rincian granular token input. Bidang ini dikembalikan untuk input multimodal. Saat ini hanya membedakan antara Properti text_tokens Jumlah token untuk input teks. image_tokens Jumlah token untuk input gambar. output_tokens_details Rincian granular token output. Bidang ini memiliki tambahan bidang Properti reasoning_tokens Jumlah token untuk proses reasoning. text_tokens Jumlah token untuk output teks. Bidang ini dikembalikan untuk input multimodal. plugins Statistik untuk pemanggilan alat bawaan. Bidang ini dikembalikan ketika alat bawaan seperti Properti web_search Statistik untuk pemanggilan pencarian web. Properti count Jumlah kali pencarian web dipanggil dalam respons ini. prompt_tokens_details Rincian cache untuk token input. Bidang ini dikembalikan ketika cache sesi diaktifkan. Mungkin mengembalikan objek kosong jika input menyertakan gambar tetapi menghasilkan cache miss. Properti cached_tokens Jumlah token yang ditemukan di cache. cache_creation_input_tokens Jumlah token yang digunakan untuk membuat cache baru dalam permintaan ini. cache_creation Rincian pembuatan cache. Properti ephemeral_5m_input_tokens Jumlah token yang digunakan untuk membuat cache ephemeral baru selama 5 menit. cache_type Jenis cache. Nilainya tetap x_tools Statistik penggunaan alat. Ini berisi jumlah kali setiap alat bawaan dipanggil. Contoh: error Objek error dikembalikan ketika model gagal menghasilkan respons. Jika tidak, nilainya tools Menggemakan konten lengkap parameter tool_choice Menggemakan nilai parameter | |
Objek potongan respons (keluaran streaming)Keluaran streaming mengembalikan serangkaian objek JSON. Setiap objek mencakup bidang type Pengidentifikasi jenis peristiwa. Nilai yang mungkin meliputi:
sequence_number Nomor urutan peristiwa, dimulai dari 0 dan bertambah dengan setiap peristiwa. Gunakan nomor ini untuk memproses peristiwa dalam urutan yang benar. response Objek respons. Muncul dalam peristiwa item Objek item keluaran. Muncul dalam peristiwa Properti id Pengidentifikasi unik untuk item keluaran (misalnya, type Jenis item keluaran. Nilai yang mungkin: role Peran pesan, yang selalu status Status generasi. Dalam peristiwa content Array konten pesan. Dalam peristiwa part Objek bagian konten. Muncul dalam peristiwa Properti type Jenis bagian konten, yang selalu text Konten teks. Ini adalah string kosong dalam peristiwa annotations Array anotasi teks. Biasanya berupa array kosong. logprobs Probabilitas log token. Bidang ini saat ini selalu mengembalikan delta Segmen teks inkremental. Bidang ini muncul dalam peristiwa text Konten teks lengkap. Bidang ini muncul dalam peristiwa item_id Pengidentifikasi unik untuk item keluaran. Gunakan ID ini untuk menghubungkan peristiwa yang termasuk dalam item yang sama. output_index Indeks item keluaran dalam array content_index Indeks bagian konten dalam array | |
FAQ
T: Bagaimana cara meneruskan konteks untuk percakapan multi-putaran?J: Saat membuat permintaan percakapan baru, teruskan id dari respons sukses sebelumnya model sebagai parameter previous_response_id.
J: SDK OpenAI resmi mungkin mengeluarkan bidang tambahan yang ditentukan oleh protokol OpenAI. Layanan kami tidak mendukung bidang-bidang ini, sehingga biasanya bernilai null. Fokuslah hanya pada bidang yang dijelaskan dalam topik ini.