Text Rerank API - qwen3-rerank, gte-rerank-v2, qwen3-vl-rerank | Model Studio - Alibaba Cloud Model Studio

Model rerank memberikan skor ulang pada dokumen yang dikembalikan oleh pengambilan awal sehingga hasil yang paling relevan muncul di bagian atas.

Ikhtisar model

Penting

Model gte-rerank akan dihentikan pada 30 Mei 2026. Beralihlah ke qwen3-rerank.

Singapore

Model

Max documents

Max input tokens per item

Max input tokens per request

Supported languages

Scenarios

qwen3-rerank

500

4.000

120.000

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

Text semantic retrieval
Aplikasi RAG

Beijing

Model

Max documents

Max input tokens per item

Max input tokens per request

Supported languages

Scenarios

qwen3-vl-rerank

Text: 100

Image: 40

Video: 4

8.000

120.000

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

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

Text semantic retrieval
Aplikasi RAG

Max input tokens per item: Token maksimum per kueri atau dokumen. Melebihi batas ini akan memicu pemotongan (truncation), yang dapat mengurangi akurasi peringkat.
Max documents: Dokumen maksimum per permintaan. Untuk qwen3-vl-rerank, batasnya bervariasi berdasarkan jenis dokumen (teks, gambar, video, atau campuran).
Max input tokens per request: Dihitung sebagai Query Tokens × Jumlah dokumen + Total token dokumen. Tidak boleh melebihi batas per permintaan.

Batasan 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

Dapatkan Kunci API dan tetapkan Kunci API sebagai Variabel lingkungan. Untuk menggunakan SDK: instal DashScope SDK.

HTTP

Setiap model menggunakan titik akhir yang berbeda:

qwen3-rerank: POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-api/v1/reranks
qwen3-vl-rerank / gte-rerank-v2: POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/rerank/text-rerank/text-rerank

Ganti {WorkspaceId} dengan workspace ID Anda yang sebenarnya.

Kedua API tersebut berbeda dalam struktur badan permintaan dan format respons. Lihat contoh permintaan dan respons untuk setiap model.

Permintaan	qwen3-rerank # Ini adalah URL wilayah Singapura. Ganti WorkspaceId dengan workspace ID Anda yang sebenarnya. URL berbeda-beda tergantung wilayah. curl --request POST \ --url https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/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." }' Ganti `WorkspaceId` dengan workspace ID Anda yang sebenarnya. qwen3-vl-rerank Text query curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.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": {"text": "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 } }' Image query curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.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": {"image": "https://img.alicdn.com/imgextra/i3/O1CN01rdstgY1uiZWt8gqSL_!!6000000006071-0-tps-1970-356.jpg"}, "documents": [ {"text": "Text rerank models are widely used in search engines and recommendation systems to sort candidate captions 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://{WorkspaceId}.ap-southeast-1.maas.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 } }'
Header permintaan
Content-Type `string` (Wajib) Tipe konten permintaan. Harus berupa `application/json`.
Authorization `string` (Wajib) Mengotentikasi permintaan dengan Kunci API Model Studio. Contoh: Bearer sk-xxxx.
Isi permintaan
model `string` (Wajib) Nama model. Nilai yang didukung: qwen3-rerank, gte-rerank-v2, qwen3-vl-rerank.
input `object` (Wajib) Konten input. Untuk `qwen3-rerank` tanpa objek `input`, letakkan `query` dan dokumen pada level yang sama dengan `model`. Properti query `string \| object` (Wajib) Teks kueri (maksimal 4.000 token). `qwen3-vl-rerank` mendukung dua format `query`: Format string: Masukkan langsung string teks, misalnya `"query": "What is a rerank model?"`. Format objek: Masukkan dictionary yang menentukan tipe modalitas dan nilainya sebagai `{"tipe modalitas": "konten input"}`. Tipe yang didukung: `text` dan `image`. Kueri teks: `"query": {"text": "What is a text rerank model?"}` Kueri gambar: `"query": {"image": "URL Gambar atau string Base64"}` documents `array` (Wajib) Dokumen kandidat untuk diurutkan. Setiap elemen berupa string. `qwen3-vl-rerank` menerima dictionary atau string per elemen: `{"tipe modalitas": "URL teks/gambar/video"}`. Tipe yang didukung: `text`, `image`, `video`. Teks: Kunci adalah `text`, nilai berupa string. String biasa tanpa pembungkus dictionary juga dapat digunakan. Gambar: Kunci adalah `image`, nilai berupa URL atau URI Data Base64 (`data:image/{format};base64,{data}`, di mana `{format}` adalah `jpeg`/`png` dan `{data}` adalah string terenkripsi). Video: Kunci adalah `video`, nilai harus berupa URL yang dapat diakses publik.
parameters `object` (Opsional) Parameter opsional. Untuk `qwen3-rerank`, objek `parameters` tidak diperlukan. Letakkan `top_n` dan `instruct` pada level yang sama dengan `model`. Properti top_n `int` (Opsional) Jumlah dokumen dengan peringkat tertinggi yang akan dikembalikan. Default: semua dokumen. Nilai yang melebihi jumlah total dokumen akan mengembalikan semua dokumen. return_documents `bool` (Opsional) Apakah akan menyertakan teks dokumen dalam hasil. Default: `false`. Model yang mendukung: `gte-rerank-v2`, `qwen3-vl-rerank`. instruct `string` (Opsional) Instruksi penyusunan ulang kustom. Berlaku untuk `qwen3-rerank` dan `qwen3-vl-rerank`. Memandu model untuk menerapkan kebijakan penyusunan ulang yang berbeda. Contoh: Tugas pengambilan Q&A (default): `"Given a web search query, retrieve relevant passages that answer the query."` Fokus: Menemukan jawaban. Model memprioritaskan apakah dokumen menjawab kueri. Contoh: Kueri "Bagaimana cara mencegah pilek?" – Dokumen "Mencuci tangan secara rutin mencegah pilek" mendapat skor tinggi; "Pilek adalah penyakit umum" mendapat skor rendah (relevan secara topik tetapi tidak menjawab). Tugas penyusunan ulang berdasarkan kesamaan semantik: `"Retrieve semantically similar text."` Fokus: Menentukan kesetaraan semantik. Model mengevaluasi apakah kueri dan dokumen memiliki makna inti yang konsisten, terlepas dari diksi atau struktur. Contoh: Dalam skenario FAQ, "Bagaimana cara mengganti kata sandi saya?" dan "Apa yang harus saya lakukan jika lupa kata sandi?" dianggap serupa secara semantik (skor tinggi). Model fokus pada apakah keduanya mencerminkan maksud pengguna yang sama. Tulis instruksi dalam bahasa Inggris. Default: tugas pengambilan Q&A. Instruksi tambahan tersedia di repositori model. fps `float` (Opsional) Hanya untuk `qwen3-vl-rerank`. Mengontrol jumlah frame video yang diekstraksi. Nilai lebih kecil = lebih sedikit frame. Rentang: 0–1 (default: 1,0).

Respons	Respons sukses qwen3-rerank `{ "object": "list", "results": [ { "index": 0, "relevance_score": 0.9334521178273196 }, { "index": 2, "relevance_score": 0.34100082626411193 } ], "model": "qwen3-rerank", "id": "85ba5752-1900-47d2-8896-23f99b13f6e1", "usage": { "total_tokens": 79 } }` qwen3-vl-rerank / gte-rerank-v2 { "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" } Respons gagal Jika permintaan gagal, `code` dan `message` menunjukkan penyebab error. `{ "code":"InvalidApiKey", "message":"Invalid API-key provided.", "request_id":"fb53c4ec-1c12-4fc4-a580-cdb7c3261fc1" }`
request_id `string` Identifikasi unik permintaan untuk pelacakan dan troubleshooting.
output `object` Output tugas. Untuk `qwen3-rerank`, respons tidak berisi objek `output`. Array `results` berada di level teratas. Properti results `array` Hasil penyusunan ulang, diurutkan berdasarkan `relevance_score` menurun. Properti document `dict` Objek dokumen asli. Hanya dikembalikan jika `return_documents` bernilai `true`. Format: `{"text": "Teks dokumen asli"}`. index `int` Indeks dokumen dalam array `documents` input. relevance_score `double` Relevansi semantik antara dokumen dan kueri. Rentang: 0,0–1,0 (semakin tinggi = semakin relevan). Catatan Skor bersifat relatif terhadap permintaan saat ini dan tidak dapat dibandingkan lintas permintaan.
usage `object` Statistik penggunaan token. Properti total_tokens `int` Total token yang dikonsumsi oleh permintaan.
code `string` Kode error. Hanya dikembalikan untuk permintaan yang gagal. Lihat Kode error.
message `string` Pesan error detail. Hanya dikembalikan untuk permintaan yang gagal. Lihat Kode error.

Gunakan SDK

Contoh

Panggil API model rerank.

Nama parameter SDK sesuai dengan API HTTP, tetapi strukturnya berbeda. HTTP menggunakan objek input dan parameters bersarang; SDK menggunakan struktur datar.

Python

import dashscope
# Wilayah Tiongkok (Beijing). Ganti {WorkspaceId} dengan workspace ID Anda yang sebenarnya. Konfigurasi bervariasi tergantung wilayah.
dashscope.base_http_api_url = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"

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()

Gunakan qwen3-vl-rerank untuk penyusunan ulang multimodal dengan kueri gambar.

Python

import dashscope
from http import HTTPStatus
import json
# Wilayah Tiongkok (Beijing). Ganti {WorkspaceId} dengan workspace ID Anda yang sebenarnya. 
dashscope.base_http_api_url = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"

def vl_rerank():
    resp = dashscope.TextReRank.call(
        model="qwen3-vl-rerank",
        query={"image": "https://img.alicdn.com/imgextra/i3/O1CN01rdstgY1uiZWt8gqSL_!!6000000006071-0-tps-1970-356.jpg"},
        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"}
        ],
        top_n=2,
        return_documents=True
    )
    if resp.status_code == HTTPStatus.OK:
        print(json.dumps(resp, default=str, ensure_ascii=False, indent=4))
    else:
        print(resp)


if __name__ == '__main__':
    vl_rerank()

Contoh output

Catatan

SDK membungkus respons HTTP. Untuk permintaan sukses, code dan message selalu berupa 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 error

Jika pemanggilan model gagal dan mengembalikan pesan error, lihat Kode error untuk penyelesaian.

Ikhtisar model

Singapore

Beijing

Batasan input

Prasyarat

HTTP

Permintaan

qwen3-rerank

qwen3-vl-rerank

gte-rerank-v2

Header permintaan

Isi permintaan

Respons

Respons sukses

qwen3-rerank

qwen3-vl-rerank / gte-rerank-v2

Respons gagal

Gunakan SDK

Contoh

Contoh output

Kode error