汎用再ランキングモデル API の使用方法の詳細 - Alibaba Cloud Model Studio

効率性を確保するため、検索システムは初期検索フェーズで十分に正確ではない結果を返す場合があります。再ランキングモデルは、取得されたドキュメントに対してより正確な 2 回目のソートを行い、ユーザーのクエリと最も関連性の高いドキュメントが上位に表示されるようにすることで、アプリケーションの精度を向上させます。

モデル概要

シンガポール

モデル名

最大ドキュメント数

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

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

サポート言語

価格（100 万トークンあたり）

無料クォータ

シナリオ

qwen3-rerank

500

4,000

30,000

中国語、英語、スペイン語、フランス語、ポルトガル語、インドネシア語、日本語、韓国語、ドイツ語、ロシア語など 100 を超える主要言語

$0.1

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

北京

モデル名

最大ドキュメント数

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

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

サポート言語

価格（100 万トークンあたり）

無料クォータ

シナリオ

qwen3-vl-rerank

100

8,000

800,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": "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 } }'
リクエストヘッダー
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` およびドキュメントは、`model` パラメーターと同じレベルに配置する必要があります。プロパティ query `string` （必須）クエリテキストです。最大長は 4,000 トークンです。 documents `array` （必須）ソート対象の候補ドキュメントのリストです。各要素は文字列です。 `qwen3-vl-embedding` モデルを使用する場合、各要素はコンテンツタイプと値を指定する辞書または文字列です。形式は {"モダリティタイプ": "入力文字列、またはイメージまたはビデオの URL"} です。サポートされているモダリティタイプは `text`、`image`、および `video` です。テキスト：キーは `text` です。値は文字列です。辞書を使用せずに文字列を直接渡すこともできます。イメージ：キーは `image` です。値は公開アクセス可能な URL または Base64 エンコードされた Data 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()

サンプル出力

説明

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 呼び出し

例

サンプル出力

エラーコード