すべてのプロダクト
Search

このプロダクト

    Alibaba Cloud Model Studio:Retrieve

    ドキュメントセンター

    Alibaba Cloud Model Studio:Retrieve

    最終更新日:May 21, 2026

    指定されたナレッジベースから情報を取得します。

    操作説明

    • 呼び出し方法： この API を呼び出すには、最新の Alibaba Cloud Model Studio SDK の使用を推奨します。SDK は複雑な署名計算を処理することで、API 呼び出しを簡素化します。

    • 必要な権限：

      • RAM ユーザー (サブアカウント)： この API を呼び出すには、RAM ユーザーに Alibaba Cloud Model Studio の API 権限 および ワークスペースへの参加 権限が付与されている必要があります。AliyunBailianDataFullAccess ポリシーを使用すると、必要な sfm:Retrieve 権限が含まれます。

      • Alibaba Cloud アカウント (メインアカウント)： このアカウントはデフォルトで必要な権限を備えており、直接 API を呼び出すことができます。

    • 応答遅延： この API 呼び出しは複雑な取得およびマッチング操作を伴うため、応答時間が長くなる可能性があります。適切なリクエストタイムアウトとリトライ戦略を設定することを推奨します。

    • べき等性： この API はべき等です。

    今すぐお試しください

    この API を OpenAPI Explorer でお試しください。手作業による署名は必要ありません。呼び出しに成功すると、入力したパラメーターに基づき、資格情報が組み込まれた SDK コードが自動的に生成されます。このコードをダウンロードしてローカルで使用できます。

    テスト

    RAM 認証

    下表に、この API を呼び出すために必要な認証情報を示します。認証情報は、RAM (Resource Access Management) ポリシーを使用して定義できます。以下で各列名について説明します。

    • アクション：特定のリソースに対して実行可能な操作。ポリシー構文ではAction要素として指定します。

    • API：アクションを具体的に実行するための API。

    • アクセスレベル：各 API に対して事前定義されているアクセスの種類。有効な値：create、list、get、update、delete。

    • リソースタイプ：アクションが作用するリソースの種類。リソースレベルでの権限をサポートするかどうかを示すことができます。ポリシーの有効性を確保するため、アクションの対象として適切なリソースを指定してください。

      • リソースレベルの権限を持つ API の場合、必要なリソースタイプはアスタリスク (*) でマークされます。ポリシーのResource要素で対応する ARN を指定してください。

      • リソースレベルの権限を持たない API の場合、「すべてのリソース」と表示され、ポリシーのResource要素でアスタリスク (*) でマークされます。

    • 条件キー：サービスによって定義された条件のキー。このキーにより、きめ細やかなアクセス制御が可能になります。この制御は、アクション単体に適用することも、特定のリソースに対するアクションに適用することもできます。Alibaba Cloud は、サービス固有の条件キーに加えて、すべての RAM 統合サービスに適用可能な一連の共通条件キーを提供しています。

    • 依存アクション：ある特定のアクションを実行するために、前提として実行が必要となる他のアクション。依存アクションの権限も RAM ユーザーまたは RAM ロールに付与する必要があります。

    アクション

    アクセスレベル

    リソースタイプ

    条件キー

    依存アクション

    sfm:Retrieve

    none

    *All Resource

    *

    		 なし なし

    リクエスト構文

    POST /{WorkspaceId}/index/retrieve HTTP/1.1

    パスパラメーター

    パラメーター

    型

    必須 / 任意

    説明

    例
    WorkspaceId

    string

    必須

    ナレッジベースを含むワークスペースの ID です。詳細については、「ワークスペースの使用方法」をご参照ください。

    llm-3shx2gu255oqxxxx

    リクエストパラメーター

    パラメーター

    型

    必須 / 任意

    説明

    例
    Query

    string

    任意

    クエリ（元のユーザープロンプト）です。クエリの長さに制限はありません。

    阿里云百炼平台介绍
    DenseSimilarityTopK

    integer

    任意

    ベクター検索を使用して取得する上位 K 件の類似テキストチャンクの数です。これは、クエリのベクター表現を生成し、ナレッジベース内で最も類似したベクターを持つ K 件のテキストチャンクを検索することで実現されます。値は 0 ～ 100 の整数である必要があります。DenseSimilarityTopK と SparseSimilarityTopK の合計は 200 を超えてはなりません。

    デフォルト値：100。

    100
    EnableReranking

    boolean

    任意

    再ランキングを有効にするかどうかを指定します。詳細については、「ナレッジベース」をご参照ください。有効な値：

    • true： 再ランキングを有効にします。

    • false： 再ランキングを無効にします。

    デフォルト値：true。

    列挙値:

    • true :

      有効

    • false :

      無効

    true
    EnableRewrite

    boolean

    任意

    会話型クエリ書き換えを有効にするかどうかを指定します。 会話型クエリ書き換え。 有効な値：

    • true： 会話型クエリ書き換えを有効にします。

    • false： 会話型クエリ書き換えを無効にします。

    デフォルト値：false。

    列挙値:

    • true :

      有効

    • false :

      無効

    false
    Rerank

    array<object>

    任意

    再ランキングの構成です。

    object

    任意

    再ランキングの構成を含むオブジェクトです。

    ModelName

    string

    任意

    使用する再ランキングモデルです。ここでモデルを指定すると、ナレッジベース作成時に選択されたデフォルトモデルがオーバーライドされます。有効な値：

    • gte-rerank-hybrid： gte-rerank (ハイブリッド) モデルを使用して再ランキングを実行します。

    • gte-rerank： gte-rerank モデルを使用して再ランキングを実行します。

    このパラメーターを指定しない場合、ナレッジベースに構成されたモデルが使用されます。

    説明

    セマンティックランキングのみを行う場合は、gte-rerank を使用してください。セマンティックランキングとテキストマッチングの両方の特徴量が必要な場合は、関連性を高めるために gte-rerank-hybrid の使用を推奨します。

    列挙値:

    • gte-rerank-hybrid :

      gte-rerank (ハイブリッド) モデルを使用して再ランキングを実行します。

    • gte-rerank :

      gte-rerank モデルを使用して再ランキングを実行します。

    gte-rerank-hybrid
    RerankMode

    string

    任意

    このパラメーターはまだ利用できません。値を指定しないでください。

    列挙値:

    • similar: 相似模式。 :

      similar： 類似度モード。

    • custom: 自定义模式。 :

      custom： カスタムモード。

    • qa:（默认值） 问答模式。 :

      qa： （デフォルト）Q&A モード。

    qa
    RerankInstruct

    string

    任意

    このパラメーターはまだ利用できません。値を指定しないでください。

    RerankMinScore

    number

    任意

    再ランキング時の類似度しきい値です。この値よりも類似度スコアが高いテキストチャンクのみが返されます。値は 0.01 ～ 1.00 の範囲内である必要があります。このパラメーターは、ナレッジベースの類似度しきい値設定をオーバーライドします。

    指定しない場合、ナレッジベースに構成されたしきい値が使用されます。

    0.20
    RerankTopN

    integer

    任意

    再ランキング後に返される上位テキストチャンクの数です。値は 1 ～ 20 の整数である必要があります。デフォルト値：5。

    5
    Rewrite

    array<object>

    任意

    会話型クエリ書き換えの構成です。

    object

    任意

    会話型クエリ書き換えの構成を含むオブジェクトです。

    ModelName

    string

    任意

    会話型クエリ書き換えのモデルを指定します。この機能は、会話のコンテキストに基づいて元のクエリを自動的に書き換え、取得結果を改善します。有効な値：

    • conv-rewrite-qwen-1.8b： この機能で現在サポートされている唯一のモデルです。

    このパラメーターを指定しない場合、デフォルトで conv-rewrite-qwen-1.8b が使用されます。

    列挙値:

    • conv-rewrite-qwen-1.8b :

      conv-rewrite-qwen-1.8b モデル

    conv-rewrite-qwen-1.8b
    SparseSimilarityTopK

    integer

    任意

    キーワード検索を使用して取得する上位 K 件のテキストチャンクの数です。この機能は、クエリ内のキーワードと完全一致するナレッジベース内のテキストチャンクを検索します。これにより、関係のないテキストチャンクを除外し、より正確な結果を提供できます。 値は 0 ～ 100 の整数である必要があります。 DenseSimilarityTopK と SparseSimilarityTopK の合計は 200 を超えてはなりません。

    デフォルト値：100。

    100
    IndexId

    string

    必須

    ナレッジベースの ID です。これは、CreateIndex 操作によって返される Data.Id 値です。

    説明

    • 指定されたナレッジベースが存在し、削除されていないことを確認してください。

    5pwe0mxxxx
    SaveRetrieverHistory

    boolean

    任意

    テスト目的で取得履歴を保存するかどうかを指定します。有効な値：

    • true： 取得履歴を保存します。

    • false： 取得履歴を保存しません。

    デフォルト値：false。

    false
    SearchFilters

    array<object>

    任意

    タグなどのカスタム取得条件を指定して、セマンティック取得結果をフィルターし、関係のない情報を除外します。 フィルターロジックは、is_displayed_chunk_content パラメーターが true に設定されている場合にのみ適用されます。詳細については、「ナレッジベースの SearchFilters」をご参照ください。

    object

    任意

    検索条件オブジェクトです。

    string

    任意

    Images

    array

    任意

    クエリに含める画像の URL です。

    string

    任意

    画像ベースの Q&A ナレッジベースから情報を取得する際、画像の URL を提供できます。ナレッジベース内に画像インデックスが存在する場合、システムは入力画像をベクターに変換して関連レコードを取得します。画像インデックスが存在しない場合、入力画像は取得に使用されません。

    説明

    このフィールドは、ドキュメント検索またはデータクエリタイプのナレッジベースではサポートされていません。指定しても効果はありません。

    説明

    リンクが公開アクセス可能であり、有効な画像ファイルを指していることを確認してください。例：https://example.com/downloads/pic.jpg

    https://example.com/downloads/pic.jpg
    QueryHistory

    array<object>

    任意

    会話履歴。これは対話型クエリ書き換えに使用されます。このパラメーターは、EnableRewrite が true に設定されている場合にのみ有効です。

    object

    任意

    role

    string

    任意

    メッセージを送信したエンティティのロールです。

    有効な値：

    • user： content がエンドユーザーからのものであることを示します。

    • assistant： content が Model Studio アプリケーションからの応答であることを示します。

    user

    content

    string

    任意

    指定された role のメッセージ内容です。

    代表一段文本。

    レスポンスフィールド

    フィールド

    型

    説明

    例

    object

    Code

    string

    エラーコードです。

    Index.InvalidParameter
    Data

    object

    API によって返されるビジネスデータです。

    Nodes

    array<object>

    取得されたテキストチャンクの配列です。

    object

    テキストチャンクオブジェクトです。

    Metadata

    any

    テキストチャンクのメタデータマップです。

    説明

    ドキュメント検索ナレッジベースの場合、メタデータマップ内の file_path フィールドは該当せず、アプリケーションコードで使用しないでください。

    説明

    ドキュメント検索ナレッジベースからデータを取得する際、テキストチャンクに画像が含まれている場合、その URL はメタデータマップの image_url フィールドで返されます。この URL は有効期限切れになります。

    { "parent": "", "file_path": "https://***", "image_url": [ "http://***" ], "nid": "***", "title": "阿里云百炼文档", "doc_id": "doc_***", "content": "阿里云百炼是基于通义大模型、行业大模型以及三方大模型的一站式大模型开发平台。面向企业客户和个人开发者，提供完整的模型服务工具和全链路应用开发套件，预置丰富的能力插件，提供API及SDK等便捷的集成方式，高效完成大模型应用构建", "workspace_id": "ws_***", "hier_title": "阿里云百炼文档", "doc_name": "阿里云百炼文档介绍.pdpf", "pipeline_id": "rhd***", "_id": "ws_***" }
    Score

    number

    テキストチャンクの類似度スコアで、0 ～ 1 の範囲です。

    0.3
    Text

    string

    テキストチャンクの内容です。

    阿里云百炼是基于通义大模型、行业大模型以及三方大模型的一站式大模型开发平台。面向企业客户和个人开发者，提供完整的模型服务工具和全链路应用开发套件，预置丰富的能力插件，提供API及SDK等便捷的集成方式，高效完成大模型应用构建。
    Message

    string

    エラーメッセージです。

    Required parameter(%s) missing or invalid, please check the request parameters.
    RequestId

    string

    リクエスト ID です。

    17204B98-7734-4F9A-8464-2446A84821CA
    Status

    string

    応答の HTTP ステータスコードです。

    200
    Success

    boolean

    API 呼び出しが成功したかどうかを示します。有効な値：

    • true： 呼び出しが成功しました。

    • false： 呼び出しが失敗しました。

    true

    例

    成功レスポンス

    JSONJSON

    {
  "Code": "Index.InvalidParameter",
  "Data": {
    "Nodes": [
      {
        "Metadata": "{\n  \"parent\": \"\",\n  \"file_path\": \"https://***\",\n  \"image_url\": [\n    \"http://***\"\n  ],\n  \"nid\": \"***\",\n  \"title\": \"阿里云百炼文档\",\n  \"doc_id\": \"doc_***\",\n  \"content\": \"阿里云百炼是基于通义大模型、行业大模型以及三方大模型的一站式大模型开发平台。面向企业客户和个人开发者，提供完整的模型服务工具和全链路应用开发套件，预置丰富的能力插件，提供API及SDK等便捷的集成方式，高效完成大模型应用构建\",\n  \"workspace_id\": \"ws_***\",\n  \"hier_title\": \"阿里云百炼文档\",\n  \"doc_name\": \"阿里云百炼文档介绍.pdpf\",\n  \"pipeline_id\": \"rhd***\",\n  \"_id\": \"ws_***\"\n}",
        "Score": 0.3,
        "Text": "阿里云百炼是基于通义大模型、行业大模型以及三方大模型的一站式大模型开发平台。面向企业客户和个人开发者，提供完整的模型服务工具和全链路应用开发套件，预置丰富的能力插件，提供API及SDK等便捷的集成方式，高效完成大模型应用构建。"
      }
    ]
  },
  "Message": "Required parameter(%s) missing or invalid, please check the request parameters.",
  "RequestId": "17204B98-7734-4F9A-8464-2446A84821CA",
  "Status": "200",
  "Success": true
}

    エラーコード

    完全なリストについては、「エラーコード」をご参照ください。

    変更履歴

    完全なリストについては、「変更履歴」をご参照ください。