HTTP と SDK を使用した Text rerank API の呼び出し - Model Studio

効率を向上させるため、検索システムは初期検索フェーズで十分に正確ではない結果を返す場合があります。再ランキング（rerank）モデルは、取得されたドキュメントに対してより正確なソートを行い、最も関連性の高い結果が上位に表示されるようにします。

モデル概要

シンガポール

モデル名

最大ドキュメント数

アイテムあたりの最大入力トークン数

リクエストあたりの最大入力トークン数

サポート言語

価格（1M トークンあたり）

無料クォータ

シナリオ

qwen3-rerank

500

4,000

120,000

中国語、英語、スペイン語、フランス語、ポルトガル語、インドネシア語、日本語、韓国語、ドイツ語、ロシア語など 100 言語以上

$0.1

100 万トークン

Model Studio のアクティベート後 90 日間有効

テキスト意味的取得
RAG アプリケーション

北京

モデル名

最大ドキュメント数

アイテムあたりの最大入力トークン数

リクエストあたりの最大入力トークン数

サポート言語

価格（1M トークンあたり）

無料クォータ

シナリオ

qwen3-vl-rerank

100

8,000

120,000

中国語、英語、日本語、韓国語、フランス語、ドイツ語など 33 の主要言語

画像：$0.258

テキスト：$0.1

無料クォータなし

画像クラスタリング
クロスモーダル検索
画像取得
動画取得

gte-rerank-v2

500

4,000

30,000

中国語、英語、日本語、韓国語、タイ語、スペイン語、フランス語、ポルトガル語、ドイツ語、インドネシア語、アラビア語など 50 言語以上

$0.115

テキスト意味的取得
RAG アプリケーション

アイテムあたりの最大入力トークン数：各クエリまたはドキュメントに許可される最大トークン数です。入力がこの制限を超えると、切り捨てられます。API は切り捨てられた内容に基づいて結果を計算するため、不正確なランキングになる可能性があります。
最大ドキュメント数：1 回のリクエストで許可される最大ドキュメント数です。
リクエストあたりの最大入力トークン数：次の数式で計算されます。クエリトークン数 × ドキュメント数 + ドキュメントの合計トークン数。この合計値は、リクエストあたりの最大入力トークン数を超えてはなりません。

入力制限事項

モデル	画像	動画
qwen3-vl-rerank	JPEG、PNG、WEBP、BMP、TIFF、ICO、DIB、ICNS、SGI（URL または Base64 形式対応）	MP4、AVI、MOV（URL のみ対応）

前提条件

API キーを取得し、API キーを環境変数として設定する必要があります。SDK を使用する場合は、DashScope SDK をインストールする必要もあります。

HTTP 呼び出し

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

リクエスト	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": {"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 } }' 画像クエリ 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/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 } }'
リクエストヘッダー
Content-Type `string` (必須) リクエストのコンテンツタイプです。`application/json` である必要があります。
Authorization `string` (必須) Model Studio API キーを使用した認証情報です。例: `Bearer sk-xxxx`
リクエストボディ
model `string` (必須) モデル名です。サポートされているモデルには、qwen3-rerank、gte-rerank-v2、qwen3-vl-rerank があります。
input `object` (必須) 入力コンテンツです。 `qwen3-rerank` を `input` オブジェクトなしで使用する場合、`query` と documents は `model` パラメーターと同じレベルにある必要があります。プロパティ query `string \| object` (必須) クエリのコンテンツです。最大長は 4,000 トークンです。 `qwen3-vl-rerank` モデルを使用する場合、`query` パラメーターは次の 2 つの形式をサポートしています。文字列形式: テキスト文字列を直接渡すことができます。例: `"query": "What is a rerank model?"`。オブジェクト形式: 辞書を渡してモダリティタイプと値を指定できます。形式は `{"modality type": "input content"}` です。`text` と `image` のモダリティタイプがサポートされています。テキストクエリ: `"query": {"text": "What is a text rerank model?"}` 画像クエリ: `"query": {"image": "Image URL or Base64-encoded string"}` documents `array` (必須) ソートする候補ドキュメントのリストです。各要素は文字列です。 `qwen3-vl-rerank` モデルを使用する場合、各要素はコンテンツタイプと値を指定する辞書または文字列です。形式は {"modality type": "an input string, or an image or video URL"} です。サポートされているモダリティタイプは `text`、`image`、`video` です。テキスト: キーは `text` で、値は文字列です。辞書を使用せずに文字列を直接渡すこともできます。画像: キーは `image` です。値は公開アクセス可能な URL または Base64 エンコードされたデータ URI にすることができます。Base64 形式は `data:image/{format};base64,{data}` で、`{format}` は `jpeg` や `png` などの画像形式、`{data}` は Base64 エンコードされた文字列です。動画: キーは `video` で、値は公開アクセス可能な URL である必要があります。
parameters object (オプション) オプションのパラメーターです。 `qwen3-rerank` を使用する場合、`parameters` オブジェクトは必須ではありません。この場合、`top_n` と `instruct` パラメーターは `model` パラメーターと同じレベルにある必要があります。プロパティ top_n `int` (オプション) 返される上位ランキングドキュメントの数です。デフォルトでは、すべてのドキュメントが返されます。指定された値がドキュメントの総数を超える場合、すべてのドキュメントが返されます。 return_documents `bool` (オプション) ソート結果にドキュメントの元のテキストを返すかどうかを指定します。ネットワークオーバーヘッドを削減するため、デフォルト値は `false` です。このパラメーターは `gte-rerank-v2` および `qwen3-vl-rerank` モデルでサポートされています。 instruct `string` (オプション) ソートタスクのカスタム命令です。このパラメーターは、`qwen3-rerank` または `qwen3-vl-rerank` モデルを使用する場合にのみ適用されます。このパラメーターを使用して、モデルに異なるソートポリシーを適用するように指示できます。例: Q&A 取得タスク（デフォルト）: `"Given a web search query, retrieve relevant passages that answer the query."` フォーカス: 質問への回答を見つけることです。モデルは、ドキュメントがクエリの質問に回答しているかどうかを評価することを優先します。例: クエリ「風邪を予防する方法は？」の場合、ドキュメント「頻繁な手洗いは風邪を予防する効果的な方法です」は高いスコアを受け取ります。ドキュメント「風邪は一般的な病気です」は、トピック的には関連していますが、回答を提供していないため、著しく低いスコアを受け取ります。意味的類似性ソートタスク: `"Retrieve semantically similar text."` フォーカス: 意味的等価性を判断することです。モデルは、特定の表現や文構造に関係なく、クエリとドキュメントの核心的な意味が一致しているかどうかを評価します。例: よくある質問（FAQ）のシナリオでは、ユーザーのクエリ「パスワードを変更するにはどうすればよいですか？」と候補の質問「パスワードを忘れた場合はどうなりますか？」は意味的に類似しており、高いスコアを受け取るべきです。モデルは、両方が同じユーザーの意図を反映しているかどうかに焦点を当てます。命令は英語で記述することを推奨します。このパラメーターを指定しない場合、システムはデフォルトで Q&A 取得タスクを使用します。その他のタスク命令については、モデルリポジトリの例をご参照ください。 fps `float` (オプション) このパラメーターは `qwen3-vl-rerank` モデルでのみサポートされています。動画から抽出されるフレーム数を制御します。値が小さいほど、抽出されるフレーム数が少なくなります。値の範囲は 0 から 1 です。デフォルト値は 1.0 です。

応答	成功応答 { "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" } 失敗応答リクエストが失敗した場合、応答の `code` フィールドと `message` フィールドはエラーの原因を示します。 `{ "code":"InvalidApiKey", "message":"Invalid API-key provided.", "request_id":"fb53c4ec-1c12-4fc4-a580-cdb7c3261fc1" }`
request_id `string` リクエストの一意の識別子です。問題の追跡とトラブルシューティングに使用します。
output `object` タスクの出力です。プロパティ results `array` `relevance_score` の降順でソートされたソート結果のリストです。プロパティ document `dict` 元のドキュメントオブジェクトです。このパラメーターは、`return_documents` リクエストパラメーターが `true` に設定されている場合にのみ返されます。構造は `{"text": "Original document text"}` です。 index `int` 入力 `documents` リスト内の対応するドキュメントの元のインデックスです。 relevance_score `double` ドキュメントとクエリ間の意味的関連性スコアです。値の範囲は 0.0 から 1.0 です。スコアが高いほど、関連性が強いことを示します。説明このスコアは現在のリクエスト内の相対値であり、主にこのリクエスト内のドキュメントをソートするために使用されます。異なるリクエスト間で比較するための絶対値として使用することはできません。
usage `object` 出力の統計です。プロパティ total_tokens `int` リクエストによって消費されたトークンの総数です。
code `string` エラーコードです。リクエストが失敗した場合にのみ返されます。詳細については、「エラーコード」をご参照ください。
message `string` 詳細なエラーメッセージです。リクエストが失敗した場合にのみ返されます。詳細については、「エラーコード」をご参照ください。

SDK の使用

例

次の例は、再ランキングモデル API を呼び出す方法を示しています。

SDK のパラメーター名はほとんど HTTP API と一致していますが、パラメーター構造はカプセル化されています。たとえば、HTTP API はネストされた input および parameters 構造を使用しますが、SDK はフラットな構造を使用します。開発中にこの違いに注意してください。

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

次の例は、画像をクエリとして使用して、qwen3-vl-rerank モデルでマルチモーダルソートを使用する方法を示しています。

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

出力例

説明

SDK は元の HTTP 応答をカプセル化します。リクエストが成功した場合、SDK は常に code フィールドと message フィールドを空の文字列として返します。

{
    "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
    }
}

エラーコード

モデル呼び出しが失敗し、エラーメッセージが返された場合は、解決策について「エラーメッセージ」をご参照ください。

モデル概要

シンガポール

北京

入力制限事項

前提条件

HTTP 呼び出し

リクエスト

qwen3-rerank

qwen3-vl-rerank

gte-rerank-v2

リクエストヘッダー

リクエストボディ

応答

成功応答

失敗応答

SDK の使用

例

出力例

エラーコード