すべてのプロダクト
Search
ドキュメントセンター

:Retrieve

最終更新日:Aug 08, 2025

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

操作説明

  • この操作を呼び出す前に、RAM ユーザーは Alibaba Cloud Model Studio のデータベース権限を取得し、ワークスペースに参加する必要があります。必要な権限は、sfm:Retrieve 権限を含む AliyunBailianDataFullAccess です。Alibaba Cloud アカウントは、承認なしでこの操作を直接呼び出すことができます。この操作は、Alibaba Cloud Model Studio SDK の最新バージョンを使用して呼び出してください。

  • この操作を呼び出す前に、ナレッジベースが作成済みであり、削除されていないことを確認してください。ナレッジベース ID(IndexId)は有効である必要があります。

  • この操作には複雑な取得とマッチングが含まれるため、応答時間が長くなる可能性があります。リクエストに対して適切なタイムアウト期間と再試行ポリシーを設定してください。

  • この操作は冪等です。

速度制限: この操作への頻繁な呼び出しは速度制限の対象となります。この操作は 1 秒間に 20 回以上呼び出さないでください。速度制限が発生した場合は、後でもう一度試してください。

今すぐお試しください

この 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

リクエストパラメーター

パラメーター

タイプ

必須 / 任意

説明

Query

string

任意

入力テキスト。元のプロンプトです。このパラメーターには、長さや文字数に制限はありません。

阿里云百炼平台介绍

DenseSimilarityTopK

integer

任意

ベクトル検索を使用して取得する上位 K テキストセグメントの数。システムは、入力テキストのベクトルを作成し、最も類似した K 個のテキストセグメントを見つけます。値は 0 から 100 の範囲でなければなりません。 DenseSimilarityTopKSparseSimilarityTopK の合計は 200 を超えることはできません。

デフォルト値は 100 です。

100

EnableReranking

boolean

任意

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

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

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

デフォルト値は true です。

true

EnableRewrite

boolean

任意

複数ターン会話の書き換えを有効にするかどうかを指定します。 有効な値:

  • true: 書き換えを有効にします。

  • false: 書き換えを無効にします。

デフォルト値は false です。

false

Rerank

array<object>

任意

再ランキングの構成。

object

任意

再ランキングの構成オブジェクト。

ModelName

string

任意

再ランキングモデルの名前。詳細については、「ナレッジベース」をご参照ください。有効な値:

  • gte-rerank-hybrid: Alibaba Cloud の推奨。

  • gte-rerank: GTE 再ランキングモデル。

gte-rerank-hybrid

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

SparseSimilarityTopK

integer

任意

キーワード検索を使用して取得する上位 K 結果の数。この機能は、入力テキストのキーワードと完全に一致するナレッジベース内のテキストセグメントを見つけます。無関係なテキストセグメントを除外し、より正確な結果を提供するのに役立ちます。 値は 0 から 100 の範囲でなければなりません。 DenseSimilarityTopKSparseSimilarityTopK の合計は 200 を超えることはできません。

デフォルト値は 100 です。

100

WorkspaceId

string

必須

ナレッジベースが配置されているワークスペースの ID。ワークスペース ID の取得方法については、「ワークスペースの使用」をご参照ください。

ws_3Nt27MYcoK191ISp

IndexId

string

必須

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

5pwe0m2g6t

SaveRetrieverHistory

boolean

任意

テキストセグメント取得テストの履歴データを保存するかどうかを指定します。有効な値:

  • true: データを保存します。

  • false: データを保存しません。

デフォルト値は false です。

false

SearchFilters

array<object>

任意

SearchFilters を使用して、タグなどのカスタム取得条件を設定し、セマンティック検索結果をフィルタリングして、クエリに無関係な情報を除外できます。 SearchFilters の構文については、以下のリクエストパラメーターに関する追加情報をご参照ください。

object

任意

取得条件オブジェクト。

string

任意

取得条件。

Images

array

任意

クエリに画像 URL を提供できます。

string

任意

構造化ナレッジベースからデータを取得する場合、画像 URL を提供できます。ナレッジベースに画像インデックスが含まれている場合、システムは入力画像をベクトルに変換し、関連するレコードを取得します。画像インデックスが存在しない場合、システムは取得に入力画像を使用しません。

説明

このフィールドは、非構造化ナレッジベースではサポートされていません。指定してもフィールドは有効になりません。

説明

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

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

QueryHistory

array<object>

任意

複数ターン会話の書き換えでは、自分で管理する会話履歴を提供できます。このパラメーターは、EnableRewrite が true に設定されている場合にのみ有効になります。それ以外の場合、システムはこのパラメーターを無視します。

object

任意

role

string

任意

ロール。

有効な値:

  • user: コンテンツは、Alibaba Cloud Model Studio アプリケーションに入力したテキストです。

  • assistant: コンテンツは、Alibaba Cloud Model Studio アプリケーションからの返信です。

user

content

string

任意

対応するロールの質問または回答。

代表一段文本。

SearchFilters 構文

  • 取得条件はサブグループをサポートします。サブグループ間のデフォルトの論理関係は AND です。この関係を変更することはできません。
    • サブグループ内のフィールドは、_operator 論理演算子をサポートします。この演算子は、AND または OR に設定できます。デフォルトは AND です。演算子は大文字と小文字を区別しません。

    • サブグループ内のフィールドは、_conditions = [] を使用したネストされたサブ条件をサポートします。サブ条件間の論理関係は、デフォルトで親グループから _operator 値を継承します。_conditions_operator = AND/OR を使用して関係をカスタマイズすることもできます。

  • サブグループ内の取得条件のフィールドは、単一値クエリ (singleQuery)、複数値クエリ (multiQuery)、および範囲クエリ (rangeQuery) をサポートします。
    • 単一値クエリ: 数値または文字列。

    • 複数値クエリ: 数値または文字列の配列。

    • 範囲クエリ: eqneqlike などのプロパティをサポートします。1 つのフィールドにこれらのプロパティを複数含めることはできません。間隔の場合、範囲クエリは gtgtelt、および lte をサポートします。間隔プロパティの値は数値である必要があります。すべてのプロパティは大文字と小文字を区別しません。

例:

{
  "search_filters": [
    {
      "singleQuery": "stringValue",  // 単一値クエリ
      "multiQuery": [                // 複数値クエリ
        "stringValue1",
        "stringValue2"
      ],
      "logicQuery": {                // 論理クエリ
        "like": "prefix"
      },
      "rangeQuery": {                // 範囲クエリ
        "gte": intValue,
        "lte": intValue
      },
      "_conditions": [                // ネストされたサブクエリ条件
        {
          "singleQuery": intValue
        }
      ]
    },
    {
      "_operator": "OR",                // 複数条件クエリ
      "singleQuery": "stringValue"
    }
  ]
}

レスポンスパラメーター

パラメーター

タイプ

説明

object

Code

string

エラーコード。

Index.InvalidParameter

Data

object

返されたデータ。

Nodes

array<object>

ヒットしたテキストセグメントのリスト。

object

テキストセグメントオブジェクト。

Metadata

any

テキストセグメントのメタデータのマップ。

説明

非構造化ナレッジベースのメタデータマップでは、file_path フィールドは無意味です。ビジネスコードでこのフィールドを使用しないでください。

説明

非構造化ナレッジベースからデータを取得する場合、セグメントに画像が含まれていると、画像 URL はメタデータマップの image_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

操作によって返された状態コード。

200

Success

boolean

操作が成功したかどうかを示します。有効な値:

  • true: 操作は成功しました。

  • false: 操作は失敗しました。

true

成功レスポンス

JSONJSON

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

エラーコード

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

変更履歴

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