detail penggunaan API model text rerank umum - Alibaba Cloud Model Studio

Untuk meningkatkan efisiensi, sistem retrieval mungkin mengembalikan hasil yang kurang presisi pada fase awal. Model rerank melakukan pengurutan ulang yang lebih akurat terhadap dokumen yang telah diambil guna memastikan hasil paling relevan muncul di posisi teratas.

Ikhtisar Model

Singapore

Model Name

Max number of documents

Max input tokens per item

Max input tokens per request

Supported languages

Price (per 1M tokens)

Free quota

Scenarios

qwen3-rerank

500

4.000

120.000

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

$0,1

1 juta token

Berlaku selama 90 hari setelah mengaktifkan Model Studio

Text semantic retrieval
RAG applications

Beijing

Model name

Max number of documents

Max input tokens per item

Max input tokens per request

Supported languages

Price (per 1M tokens)

Free quota

Scenarios

qwen3-vl-rerank

100

8.000

120.000

33 bahasa utama, seperti Tionghoa, 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
RAG applications

Max input tokens per item: Jumlah maksimum token yang diizinkan untuk setiap kueri atau dokumen. Jika input melebihi batas ini, konten akan dipotong (truncated). API menghitung hasil berdasarkan konten yang telah dipotong, yang dapat menyebabkan peringkat 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.

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

Anda harus mendapatkan kunci API dan menyetel kunci API sebagai variabel lingkungan. Untuk menggunakan 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 Text query 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": {"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://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": {"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://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 `qwen3-rerank` tanpa objek `input`, parameter `query` dan dokumen harus berada pada level yang sama dengan parameter `model`. Properties query `string \| object` (Required) Konten kueri. Panjang maksimum adalah 4.000 token. Saat Anda menggunakan model `qwen3-vl-rerank`, parameter `query` mendukung dua format berikut: Format string: Anda dapat langsung mengirimkan string teks. Contohnya, `"query": "What is a rerank model?"`. Format objek: Anda dapat mengirimkan dictionary untuk menentukan tipe modalitas dan nilainya. Formatnya adalah `{"modality type": "input content"}`. Tipe modalitas yang didukung adalah `text` dan `image`. Kueri teks: `"query": {"text": "What is a text rerank model?"}` Kueri gambar: `"query": {"image": "Image URL or Base64-encoded string"}` documents `array` (Required) Daftar dokumen kandidat yang akan diurutkan. Setiap elemen berupa string. Saat Anda menggunakan model `qwen3-vl-rerank`, setiap elemen berupa dictionary atau string yang menentukan tipe konten dan nilainya. Formatnya adalah {"modality type": "input string, atau URL gambar/video"}. Tipe modalitas yang didukung adalah `text`, `image`, dan `video`. Teks: Kuncinya adalah `text`, dan nilainya berupa string. Anda juga dapat langsung mengirimkan string tanpa menggunakan dictionary. Gambar: Kuncinya adalah `image`. Nilainya dapat berupa URL publik atau Data URI 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`, dan nilainya harus berupa URL publik.
parameters object (Optional) Parameter opsional. Saat Anda menggunakan `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 peringkat teratas 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 pengurutan. Nilai default-nya adalah `false` untuk mengurangi overhead jaringan. Parameter ini didukung oleh model `gte-rerank-v2` dan `qwen3-vl-rerank`. instruct `string` (Optional) Instruksi kustom untuk tugas pengurutan. Parameter ini hanya berlaku saat Anda menggunakan model `qwen3-rerank` atau `qwen3-vl-rerank`. Anda dapat menggunakan parameter ini untuk mengarahkan model menerapkan kebijakan pengurutan yang berbeda. Contohnya: Tugas retrieval Q&A (default): `"Given a web search query, retrieve relevant passages that answer the query."` Fokus: Menemukan jawaban atas pertanyaan. Model memprioritaskan evaluasi apakah 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 jauh lebih rendah karena tidak memberikan jawaban. Tugas pengurutan kesamaan semantik: `"Retrieve semantically similar text."` Fokus: Menentukan kesetaraan semantik. Model mengevaluasi apakah makna inti dari kueri dan dokumen konsisten, terlepas dari pemilihan kata atau struktur kalimat tertentu. 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 fokus pada apakah keduanya mencerminkan maksud pengguna yang sama. Kami menyarankan Anda menulis instruksi dalam bahasa Inggris. Jika Anda tidak menentukan parameter ini, sistem secara default menggunakan tugas retrieval Q&A. Untuk contoh 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 lebih sedikit frame yang 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. Gunakan untuk pelacakan dan troubleshooting masalah.
output `object` Output dari tugas. Properties results `array` Daftar hasil pengurutan, diurutkan berdasarkan `relevance_score` secara menurun. Properties document `dict` Objek dokumen asli. Parameter ini hanya dikembalikan jika parameter permintaan `return_documents` diatur ke `true`. Strukturnya adalah `{"text": "Original document text"}`. index `int` Indeks asli dokumen yang sesuai dalam daftar input `documents`. 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 mengurutkan dokumen dalam permintaan ini. Skor ini tidak dapat digunakan sebagai nilai absolut untuk perbandingan lintas permintaan yang berbeda.
usage `object` Statistik output. Properties total_tokens `int` Jumlah total token yang dikonsumsi oleh permintaan.
code `string` Kode kesalahan. Hanya dikembalikan jika permintaan gagal. Lihat kode kesalahan untuk detailnya.
message `string` Pesan kesalahan detail. Hanya dikembalikan jika permintaan gagal. Lihat kode kesalahan untuk detailnya.

Gunakan SDK

Contoh

Contoh berikut menunjukkan cara memanggil API model rerank.

Nama parameter dalam SDK sebagian besar konsisten dengan API HTTP, tetapi struktur parameternya telah dienkapsulasi. Misalnya, API HTTP menggunakan struktur bersarang input dan parameters, sedangkan SDK menggunakan struktur flat. 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 berikut menunjukkan cara menggunakan model qwen3-vl-rerank untuk pengurutan multimodal menggunakan gambar sebagai kueri.

Python

import dashscope
from http import HTTPStatus
import json

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 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 pemanggilan model gagal dan mengembalikan pesan kesalahan, lihat Pesan Kesalahan untuk penyelesaiannya.

Ikhtisar Model

Singapore

Beijing

Batasan Input

Prasyarat

Panggilan HTTP

Request

qwen3-rerank

qwen3-vl-rerank

gte-rerank-v2

Request headers

Request body

Response

Successful response

Failed response

Gunakan SDK

Contoh

Contoh output

Kode Kesalahan