Detail penggunaan API model rerank umum - Alibaba Cloud Model Studio

Untuk memastikan efisiensi, sistem retrieval dapat mengembalikan hasil yang kurang tepat selama fase retrieval awal. Model rerank melakukan penyortiran ulang yang lebih akurat terhadap dokumen yang telah diambil guna memastikan bahwa dokumen paling relevan dengan kueri pengguna muncul di bagian atas, sehingga meningkatkan akurasi aplikasi.

Ikhtisar model

Singapore

Model Name

Max number of documents

Max input tokens per item

Max input tokens per request

Supported languages

Price (per 1 million tokens)

Free quota

Scenarios

qwen3-rerank

500

4.000

30.000

Lebih dari 100 bahasa utama, seperti Mandarin, Inggris, Spanyol, Prancis, Portugis, Indonesia, Jepang, Korea, Jerman, dan Rusia.

$0,1

Text semantic retrieval
Aplikasi RAG

Beijing

Model name

Max number of documents

Max input tokens per item

Max input tokens per request

Supported languages

Price (per 1 million tokens)

Free quota

Scenarios

qwen3-vl-rerank

100

8.000

800.000

33 bahasa utama, seperti Tiongkok, Inggris, Jepang, Korea, Prancis, dan Jerman

Image: $0,258

Text: $0,1

No free quota

Image clustering
Cross-modal search
Image retrieval
Video retrieval

gte-rerank-v2

500

4.000

30.000

Lebih dari 50 bahasa, termasuk Mandarin, Inggris, Jepang, Korea, Thailand, Spanyol, Prancis, Portugis, Jerman, Indonesia, dan Arab.

$0,115

Text semantic retrieval
Aplikasi RAG

Max input tokens per item: Jumlah maksimum token yang diizinkan untuk setiap kueri atau dokumen. Jika input melebihi batas ini, konten akan dipotong. API menghitung hasil berdasarkan konten yang telah dipotong, yang dapat menyebabkan peringkat menjadi tidak akurat.
Max number of documents: Jumlah maksimum dokumen yang diizinkan dalam satu permintaan.
Max input tokens per request: Dihitung menggunakan rumus Query Tokens × Number of documents + Total document tokens. Total ini tidak boleh melebihi jumlah maksimum token input yang diizinkan per permintaan.

Batas format input

Model	Image	Video
qwen3-vl-rerank	JPEG, PNG, WEBP, BMP, TIFF, ICO, DIB, ICNS, dan SGI (URL atau Base64 didukung)	MP4, AVI, dan MOV (hanya URL)

Prasyarat

Anda harus mendapatkan Kunci API dan menyetel Kunci API sebagai Variabel lingkungan. Untuk menggunakan kit pengembangan perangkat lunak (SDK), Anda juga harus menginstal SDK DashScope.

Panggilan HTTP

POST https://dashscope.aliyuncs.com/api/v1/services/rerank/text-rerank/text-rerank

Request	qwen3-rerank curl --request POST \ --url https://dashscope-intl.aliyuncs.com/compatible-api/v1/reranks \ --header "Authorization: Bearer $DASHSCOPE_API_KEY" \ --header "Content-Type: application/json" \ --data '{ "model": "qwen3-rerank", "documents": [ "Rerank models are widely used in search engines and recommendation systems. They sort candidate documents based on text relevance.", "Quantum computing is a cutting-edge field of computer science.", "The development of pre-trained language models has brought new advancements to rerank models." ], "query": "What is a rerank model?", "top_n": 2, "instruct": "Given a web search query, retrieve relevant passages that answer the query." }' qwen3-vl-rerank curl --location 'https://dashscope.aliyuncs.com/api/v1/services/rerank/text-rerank/text-rerank' \ --header "Authorization: Bearer $DASHSCOPE_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "model": "qwen3-vl-rerank", "input":{ "query": "What is a rerank model?", "documents": [ {"text": "Rerank models are widely used in search engines and recommendation systems. They sort candidate documents based on text relevance."}, {"image": "https://img.alicdn.com/imgextra/i3/O1CN01rdstgY1uiZWt8gqSL_!!6000000006071-0-tps-1970-356.jpg"}, {"video": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250107/lbcemt/new+video.mp4"} ] }, "parameters": { "return_documents": true, "top_n": 2, "fps": 1.0 } }' gte-rerank-v2 curl --location 'https://dashscope.aliyuncs.com/api/v1/services/rerank/text-rerank/text-rerank' \ --header "Authorization: Bearer $DASHSCOPE_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "model": "gte-rerank-v2", "input":{ "query": "What is a rerank model?", "documents": [ "Rerank models are widely used in search engines and recommendation systems. They sort candidate documents based on text relevance.", "Quantum computing is a cutting-edge field of computer science.", "The development of pre-trained language models has brought new advancements to rerank models." ] }, "parameters": { "return_documents": true, "top_n": 2 } }'
Request headers
Content-Type `string` (Required) Tipe konten dari permintaan. Harus berupa `application/json`.
Authorization `string` (Required) Kredensial otentikasi menggunakan Kunci API Model Studio. Contoh: `Bearer sk-xxxx`
Request body
model `string` (Required) Nama model. Model yang didukung meliputi qwen3-rerank, gte-rerank-v2, dan qwen3-vl-rerank.
input `object` (Required) Konten input. Saat Anda menggunakan model `qwen3-rerank`, objek `input` tidak diperlukan. Dalam kasus ini, `query` dan dokumen harus berada pada level yang sama dengan parameter `model`. Properties query `string` (Required) Teks kueri. Panjang maksimum adalah 4.000 token. documents `array` (Required) Daftar dokumen kandidat untuk disortir. Setiap elemen berupa string. Saat Anda menggunakan model `qwen3-vl-embedding`, setiap elemen berupa dictionary atau string yang menentukan tipe konten dan nilainya. Formatnya adalah {"modality type": "an input string, or an image or video URL"}. Tipe modalitas yang didukung adalah `text`, `image`, dan `video`. Text: Kuncinya adalah `text`. Nilainya berupa string. Anda juga dapat langsung mengirimkan string tanpa menggunakan dictionary. Image: Kuncinya adalah `image`. Nilainya dapat berupa URL yang dapat diakses publik atau URI Data yang dikodekan Base64. Format Base64-nya adalah `data:image/{format};base64,{data}`, di mana `{format}` adalah format gambar, seperti `jpeg` atau `png`, dan `{data}` adalah string yang dikodekan Base64. Video: Kuncinya adalah `video`. Nilainya harus berupa URL yang dapat diakses publik.
parameters object (Optional) Parameter opsional. Saat Anda menggunakan model `qwen3-rerank`, objek `parameters` tidak diperlukan. Dalam kasus ini, parameter `top_n` dan `instruct` harus berada pada level yang sama dengan parameter `model`. Properties top_n `int` (Optional) Jumlah dokumen dengan peringkat tertinggi yang akan dikembalikan. Secara default, semua dokumen dikembalikan. Jika nilai yang ditentukan melebihi jumlah total dokumen, maka semua dokumen dikembalikan. return_documents `bool` (Optional) Menentukan apakah teks asli dokumen dikembalikan dalam hasil penyortiran. Nilai default-nya adalah `false` untuk mengurangi overhead jaringan. Model yang mendukung: `gte-rerank-v2` dan `qwen3-vl-rerank`. instruct `string` (Optional) Instruksi kustom untuk tugas penyortiran. Parameter ini hanya berlaku saat Anda menggunakan model `qwen3-rerank` atau `qwen3-vl-rerank`. Anda dapat menggunakan parameter ini untuk mengarahkan model menerapkan kebijakan penyortiran yang berbeda. Contoh: Tugas retrieval tanya jawab (Q&A) (default): `"Given a web search query, retrieve relevant passages that answer the query."` Fokus: Menemukan jawaban atas pertanyaan. Model memprioritaskan evaluasi apakah suatu dokumen menjawab pertanyaan dalam kueri. Contoh: Untuk kueri "How to prevent a cold?", dokumen "Washing hands frequently is an effective way to prevent colds" mendapat skor tinggi. Dokumen "A cold is a common illness", meskipun relevan secara topikal, mendapat skor yang jauh lebih rendah karena tidak memberikan jawaban. Tugas penyortiran kesamaan semantik: `"Retrieve semantically similar text."` Fokus: Menentukan kesetaraan semantik. Model mengevaluasi apakah makna inti dari kueri dan dokumen konsisten, terlepas dari kata-kata spesifik atau struktur kalimatnya. Contoh: Dalam skenario FAQ (pertanyaan yang sering diajukan), kueri pengguna "How do I change my password?" dan pertanyaan kandidat "What if I forget my password?" memiliki kesamaan semantik dan seharusnya mendapat skor tinggi. Model berfokus pada apakah keduanya mencerminkan maksud pengguna yang sama. Tulis instruksi dalam bahasa Inggris. Jika Anda tidak menentukan parameter ini, model akan melakukan tugas retrieval Q&A secara default. Untuk instruksi tugas lainnya, lihat contoh di repositori model. fps `float` (Optional) Parameter ini hanya didukung oleh model `qwen3-vl-rerank`. Parameter ini mengontrol jumlah frame yang diekstraksi dari video. Nilai yang lebih kecil menunjukkan jumlah frame yang lebih sedikit diekstraksi. Nilainya berkisar antara 0 hingga 1. Nilai default-nya adalah 1,0.

Response	Successful response { "output": { "results": [ { "document": { "text": "Rerank models are widely used in search engines and recommendation systems. They sort candidate documents based on text relevance." }, "index": 0, "relevance_score": 0.9334521178273196 }, { "document": { "text": "The development of pre-trained language models has brought new advancements to rerank models." }, "index": 2, "relevance_score": 0.34100082626411193 } ] }, "usage": { "total_tokens": 79 }, "request_id": "85ba5752-1900-47d2-8896-23f99b13f6e1" } Failed response Jika permintaan gagal, bidang `code` dan `message` dalam respons menunjukkan penyebab kesalahan. `{ "code":"InvalidApiKey", "message":"Invalid API-key provided.", "request_id":"fb53c4ec-1c12-4fc4-a580-cdb7c3261fc1" }`
request_id `string` Pengidentifikasi unik untuk permintaan. Digunakan untuk pelacakan dan troubleshooting masalah.
output `object` Output tugas. Properties results `array` Daftar hasil penyortiran, diurutkan berdasarkan `relevance_score` secara menurun. Properties document `dict` Objek dokumen asli. Ini hanya dikembalikan ketika parameter permintaan `return_documents` bernilai `true`. Strukturnya adalah `{"text": "Original document text"}`. index `int` Indeks asli dokumen yang sesuai dalam daftar `documents` input. relevance_score `double` Skor relevansi semantik antara dokumen dan kueri. Nilainya berkisar dari 0,0 hingga 1,0. Skor yang lebih tinggi menunjukkan relevansi yang lebih kuat. Catatan Skor ini merupakan nilai relatif dalam permintaan saat ini dan terutama digunakan untuk menyortir dokumen dalam permintaan ini. Skor ini tidak dapat digunakan sebagai nilai absolut untuk perbandingan lintas permintaan yang berbeda.
usage `object` Memberikan statistik output. Properties total_tokens `int` Jumlah total token yang dikonsumsi oleh permintaan.
code `string` Kode kesalahan. Hanya dikembalikan saat permintaan gagal. Lihat kode kesalahan untuk detailnya.
message `string` Pesan kesalahan detail. Hanya dikembalikan saat permintaan gagal. Lihat kode kesalahan untuk detailnya.

Panggilan SDK

Contoh

Contoh berikut menunjukkan cara memanggil API model rerank.

Nama parameter dalam SDK sebagian besar konsisten dengan API HTTP, tetapi struktur parameternya dienkapsulasi. Misalnya, API HTTP menggunakan struktur bersarang input dan parameters, sedangkan SDK menggunakan struktur datar. Perhatikan perbedaan ini selama pengembangan.

Python

import dashscope

def text_rerank():
    resp = dashscope.TextReRank.call(
        model="gte-rerank-v2",
        query="What is a rerank model?",
        documents=[
            "Rerank models are widely used in search engines and recommendation systems. They sort candidate documents based on text relevance.",
            "Quantum computing is a cutting-edge field of computer science.",
            "The development of pre-trained language models has brought new advancements to rerank models."
        ],
        top_n=2,
        return_documents=True
    )
    print(resp)

if __name__ == '__main__':
    text_rerank()

Contoh output

Catatan

SDK mengenkapsulasi respons HTTP asli. Untuk permintaan yang berhasil, SDK selalu mengembalikan bidang code dan message dengan nilai string kosong.

{
    "status_code": 200,
    "request_id": "4b0805c0-6b36-490d-8bc1-4365f4c89905",
    "code": "",
    "message": "",
    "output": {
        "results": [
            {
                "index": 0,
                "relevance_score": 0.9334521178273196,
                "document": {
                    "text": "Rerank models are widely used in search engines and recommendation systems. They sort candidate documents based on text relevance."
                }
            },
            {
                "index": 2,
                "relevance_score": 0.34100082626411193,
                "document": {
                    "text": "The development of pre-trained language models has brought new advancements to rerank models."
                }
            }
        ]
    },
    "usage": {
        "total_tokens": 79
    }
}

Kode kesalahan

Jika panggilan gagal, lihat Pesan kesalahan untuk troubleshooting.

Ikhtisar model

Singapore

Beijing

Batas format input

Prasyarat

Panggilan HTTP

Request

qwen3-rerank

qwen3-vl-rerank

gte-rerank-v2

Request headers

Request body

Response

Successful response

Failed response

Panggilan SDK

Contoh

Contoh output

Kode kesalahan