RESTリクエスト例

この例では、5つのパッセージのみが再ランク付けのために提出されている。 最大1,000入力まで指定可能。 しかし、クロスエンコーダー・モデルは、各パッセージをクエリーと一緒に次々に処理するため、指定するパッセージが多ければ多いほど、リランキング処理に時間がかかる。

あなたが提出する各入力は、リランカー・モデルによって定義された最大入力トークン制限に適合していなければなりません。

この例では、モデルが許容する以上のトークンがある場合に対応するため、行を強制的に切り捨てる「truncate_input_tokensパラメータを指定しています。 さもなければ、リクエストは失敗するかもしれない。

この例では、元のパッセージのテキストがレスポンスに含まれるように、'inputsリターン・オプション・パラメータが含まれています。 実際のワークフローでは、「inputsパラメータを含める必要はないかもしれない。

テキスト・リランカー・メソッドのペイロードの「model_id」に、使用したいリランカー・モデルを指定する。

以下の例では、{url}variable with the right value for your instance, such asus-south.ml.cloud.ibm.comを置き換えます。独自のベアラートークンとプロジェクトIDを追加します。

curl -X POST \
  'https://{url}/ml/v1/text/rerank?version=2024-10-17' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer eyJraWQiOi...' \
  --data '{
      "inputs": [
        {
          "text": "A foundation model is a large-scale generative AI model that can be adapted to a wide range of downstream tasks."
        },
        {
          "text": "Generative AI is a class of AI algorithms that can produce various types of content including text, source code, imagery, audio, and synthetic data."
        },
        {
          "text": "Agentic AI is a generative AI flow that can decompose a prompt into multiple tasks, assign tasks to appropriate gen AI agents, and synthesize an answer without human intervention."
        },
        {
          "text": "AI ethics is a multidisciplinary field that studies how to optimize AI'\''s beneficial impact while reducing risks and adverse outcomes. Examples of AI ethics issues are data responsibility and privacy, fairness, explainability, robustness, transparency, environmental sustainability, inclusion, moral agency, value alignment, accountability, trust, and technology misuse."
        },
        {
          "text": "AI governance is an organization'\''s act of governing, through its corporate instructions, staff, processes and systems to direct, evaluate, monitor, and take corrective action throughout the AI lifecycle, to provide assurance that the AI system is operating as the organization intends, as its stakeholders expect, and as required by relevant regulation."
        }
      ],
      "query": "What is an agent-driven AI workflow?",
      "parameters":{
        "truncate_input_tokens": 512,
        "return_options":{
          "inputs":true
        }
      },
      "model_id": "cross-encoder/ms-marco-minilm-l-12-v2",
      "project_id": "51f3a990-4372-4ac3-9ddb-ed99d9b50840"
    }'

最高順位のパッセージだけを返したい場合は、「top_nパラメータを指定します。 次のサンプルは、クエリに最も関連する1つのパッセージのみを返すようにモデルを指定する方法を示しています：

"parameters":{
    "truncate_input_tokens": 512,
    "return_options":{
      "inputs":true,
      "top_n": 1
    }
}

RESTレスポンスの例

リクエスト例に対して、以下の応答が返される。 いくつか気づいたことがある：

• パッセージは、高得点のパッセージを最初に表示するように並び替えられる。

  このモデルは、'エージェントAI定義をリストの一番上に正確に返す。それは、それがエージェント駆動型ワークフローに関する質問に最も密接に関連しているからである。

• 0から4までのインデックス値は、リクエストで送信された'inputs配列の中のパッセージの元の位置を表す。

  例えば、Agentic AIに関する文章はリストの3番目の文章なので、インデックス値は「2である。

• input_token_countフィールドは、リクエストで処理されたトークンの総数を示す。

  トークンのカウント方法についての詳細は、課金情報をご覧ください。

{
  "model_id": "cross-encoder/ms-marco-minilm-l-12-v2",
  "created_at": "2024-10-17T14:01:47.322Z",
  "results": [
    {
      "index": 2,
      "score": 5.063366413116455,
      "input": {
        "text": "Agentic AI is a generative AI flow that can decompose a prompt into multiple tasks, assign tasks to appropriate gen AI agents, and synthesize an answer without human intervention."
      }
    },
    {
      "index": 4,
      "score": -0.992393970489502,
      "input": {
        "text": "AI governance is an organization's act of governing, through its corporate instructions, staff, processes and systems to direct, evaluate, monitor, and take corrective action throughout the AI lifecycle, to provide assurance that the AI system is operating as the organization intends, as its stakeholders expect, and as required by relevant regulation."
      }
    },
    {
      "index": 1,
      "score": -3.5372314453125,
      "input": {
        "text": "Generative AI is a class of AI algorithms that can produce various types of content including text, source code, imagery, audio, and synthetic data."
      }
    },
    {
      "index": 0,
      "score": -4.646212100982666,
      "input": {
        "text": "A foundation model is a large-scale generative AI model that can be adapted to a wide range of downstream tasks."
      }
    },
    {
      "index": 3,
      "score": -4.926990032196045,
      "input": {
        "text": "AI ethics is a multidisciplinary field that studies how to optimize AI's beneficial impact while reducing risks and adverse outcomes. Examples of AI ethics issues are data responsibility and privacy, fairness, explainability, robustness, transparency, environmental sustainability, inclusion, moral agency, value alignment, accountability, trust, and technology misuse."
      }
    }
  ],
  "input_token_count": 292,
  "system": {
    "warnings": [
      {
        "message": "This model is a Non-IBM Product governed by a third-party license that may impose use restrictions and other obligations. By using this model you agree to its terms as identified in the following URL.",
        "id": "disclaimer_warning",
        "more_info": "https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-models.html?context=wx"
      }
    ]
  }
}

先ほどのサンプルのように、パラメーター・オブジェクトに「"top_n": 1含めると、レスポンスは次のようになる：

{
  "model_id": "cross-encoder/ms-marco-minilm-l-12-v2",
  "created_at": "2024-10-17T20:18:50.867Z",
  "results": [
    {
      "index": 2,
      "score": 5.063366413116455,
      "input": {
        "text": "Agentic AI is a generative AI flow that can decompose a prompt into multiple tasks, assign tasks to appropriate gen AI agents, and synthesize an answer without human intervention."
      }
    }
  ],
  "input_token_count": 292,
  "system": {
    "warnings": [
      {
        "message": "This model is a Non-IBM Product governed by a third-party license that may impose use restrictions and other obligations. By using this model you agree to its terms as identified in the following URL.",
        "id": "disclaimer_warning",
        "more_info": "https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-models.html?context=wx"
      }
    ]
  }
}