Knowledge Retrieval - Retrieve

サービス:: Search Service

API バージョン:: 2025-05-01-preview

KnowledgeAgent は、バッキングストアから関連データを取得します。

POST {endpoint}/agents('{agentName}')/retrieve?api-version=2025-05-01-preview

URI パラメーター

名前	/	必須	型	説明
agentName	path	True	string	エージェントの名前。
endpoint	path	True	string (url)	検索サービスのエンドポイント URL。
api-version	query	True	string	クライアント API のバージョン。

要求ヘッダー

名前	必須	型	説明
x-ms-client-request-id		string (uuid)	デバッグに役立つ要求と共に送信される追跡 ID。
x-ms-query-source-authorization		string	クエリが実行されているユーザーを識別するトークン。このトークンは、ドキュメントにセキュリティ制限を適用するために使用されます。

要求本文

名前	必須	型	説明
messages	True	KnowledgeAgentMessage[]	自然言語のメッセージスタイルオブジェクト。
targetIndexParams		KnowledgeAgentIndexParams[]

応答

名前	型	説明
200 OK	KnowledgeAgentRetrievalResponse	取得レスポンスは正常に返されます。
Other Status Codes	ErrorResponse	エラー応答。

例

KnowledgeAgentRetrieve

要求のサンプル

HTTP

POST https://previewexampleservice.search.windows.net/agents('agent-preview-test')/retrieve?api-version=2025-05-01-preview



{
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "text": "hello world",
          "type": "text"
        }
      ]
    }
  ],
  "targetIndexParams": [
    {
      "indexName": "preview-test",
      "filterAddOn": "foo eq bar",
      "maxDocsForReranker": 100,
      "rerankerThreshold": 2.5,
      "includeReferenceSourceData": true
    }
  ]
}

応答のサンプル

状態コード:: 200

{
  "response": [
    {
      "role": "assistant",
      "content": [
        {
          "type": "text",
          "text": "[{...}]"
        }
      ]
    }
  ],
  "activity": [
    {
      "type": "ModelQueryPlanning",
      "id": 0,
      "inputTokens": 11,
      "outputTokens": 22
    },
    {
      "type": "AzureSearchQuery",
      "id": 1,
      "targetIndex": "preview-test",
      "query": {
        "search": "hello world",
        "filter": "foo eq bar"
      },
      "queryTime": "2025-01-01T00:08:45.045Z",
      "count": 2,
      "elapsedMs": 1234
    },
    {
      "type": "AzureSearchQuery",
      "id": 2,
      "targetIndex": "preview-test",
      "query": {
        "search": "hello world two",
        "filter": "foo eq bar"
      },
      "queryTime": "2025-01-01T00:08:45.045Z",
      "count": 2,
      "elapsedMs": 1234
    },
    {
      "type": "AzureSearchSemanticRanker",
      "id": 3,
      "inputTokens": 74
    }
  ],
  "references": [
    {
      "type": "AzureSearchDoc",
      "id": "83dd7d40",
      "activitySource": 1,
      "docKey": "myDocKey1",
      "sourceData": {
        "id": "myDocKey1",
        "title": "high_doc",
        "content": "hello world"
      }
    },
    {
      "type": "AzureSearchDoc",
      "id": "83dd7d41",
      "activitySource": 1,
      "docKey": "myDocKey2",
      "sourceData": {
        "id": "myDocKey2",
        "title": "low_doc",
        "content": "goodbye world"
      }
    }
  ]
}

定義

名前	説明
ErrorAdditionalInfo	リソース管理エラーの追加情報。
ErrorDetail	エラーの詳細。
ErrorResponse	エラー応答
Image
KnowledgeAgentAzureSearchDocReference	Azure Search ドキュメント参照を表します。
KnowledgeAgentIndexParams
KnowledgeAgentMessage	自然言語のメッセージスタイルオブジェクト。
KnowledgeAgentMessageContentType	メッセージの内容の種類。
KnowledgeAgentMessageImageContent	テキストメッセージの種類。
KnowledgeAgentMessageTextContent	テキストメッセージの種類。
KnowledgeAgentModelQueryPlanningActivityRecord	LLM クエリ計画アクティビティレコードを表します。
KnowledgeAgentRetrievalRequest	取得要求の入力コントラクト。
KnowledgeAgentRetrievalResponse	取得応答の出力コントラクト。
KnowledgeAgentSearchActivityRecord	取得アクティビティレコードを表します。
KnowledgeAgentSemanticRankerActivityRecord	セマンティック・ランカー・アクティビティー・レコードを表します。
Query	取得アクティビティのクエリの詳細。

ErrorAdditionalInfo

Object

リソース管理エラーの追加情報。

名前	型	説明
info	object	追加情報。
type	string	追加情報の種類。

ErrorDetail

Object

エラーの詳細。

名前	型	説明
additionalInfo	ErrorAdditionalInfo[]	エラーの追加情報。
code	string	エラーコード。
details	ErrorDetail[]	エラーの詳細。
message	string	エラーメッセージ。
target	string	エラーターゲット。

ErrorResponse

Object

エラー応答

名前	型	説明
error	ErrorDetail	エラーオブジェクト。

Image

Object

名前	型	説明
url	string	画像の URL。

KnowledgeAgentAzureSearchDocReference

Object

Azure Search ドキュメント参照を表します。

名前	型	説明
activitySource	integer (int32)	参照のソースアクティビティ ID。
docKey	string	参照用のドキュメントキー。
id	string	参照の ID。
sourceData	object
type	string: AzureSearchDoc	参照のタイプ。

KnowledgeAgentIndexParams

Object

名前	型	説明
filterAddOn	string	インデックスに適用されるフィルター条件 (例: 'State eq VA')。
includeReferenceSourceData	boolean	参照元データを含めるかどうかを示します。
indexName	string	パラメータが適用されるインデックスの名前。
maxDocsForReranker	integer (int32)	ランク付けの対象となるドキュメントの数を制限します。
rerankerThreshold	number (float) minimum: 0 maximum: 4	結果の再ランク付けのしきい値 (範囲: 0 から 4)。

KnowledgeAgentMessage

Object

自然言語のメッセージスタイルオブジェクト。

名前	型	説明
content	KnowledgeAgentMessageContent[]: KnowledgeAgentMessageImageContent[] KnowledgeAgentMessageTextContent[]	メッセージの内容の種類を指定します。
role	string	ツール応答の役割。

KnowledgeAgentMessageContentType

列挙

メッセージの内容の種類。

値	説明
text	テキストメッセージの内容の種類。
image	画像メッセージの内容の種類。

KnowledgeAgentMessageImageContent

Object

テキストメッセージの種類。

名前	型	説明
image	Image
type	string: image	メッセージのタイプ

KnowledgeAgentMessageTextContent

Object

テキストメッセージの種類。

名前	型	説明
text	string
type	string: text	メッセージのタイプ

KnowledgeAgentModelQueryPlanningActivityRecord

Object

LLM クエリ計画アクティビティレコードを表します。

名前	型	説明
elapsedMs	integer (int32)	モデルアクティビティの経過時間 (ミリ秒単位)。
id	integer (int32)	アクティビティレコードの ID。
inputTokens	integer (int32)	LLM クエリ計画アクティビティの入力トークンの数。
outputTokens	integer (int32)	LLM クエリ計画アクティビティの出力トークンの数。
type	string: ModelQueryPlanning	アクティビティ・レコードのタイプ。

KnowledgeAgentRetrievalRequest

Object

取得要求の入力コントラクト。

名前	型	説明
messages	KnowledgeAgentMessage[]	自然言語のメッセージスタイルオブジェクト。
targetIndexParams	KnowledgeAgentIndexParams[]

KnowledgeAgentRetrievalResponse

Object

取得応答の出力コントラクト。

名前	型	説明
activity	KnowledgeAgentActivityRecord[]: KnowledgeAgentModelQueryPlanningActivityRecord[] KnowledgeAgentSearchActivityRecord[] KnowledgeAgentSemanticRankerActivityRecord[]	進行状況と請求への影響を追跡するためのアクティビティレコード。
references	KnowledgeAgentReference[]: KnowledgeAgentAzureSearchDocReference[]	応答で使用される取得データの参照。
response	KnowledgeAgentMessage[]	自然言語のメッセージスタイルオブジェクト。

KnowledgeAgentSearchActivityRecord

Object

取得アクティビティレコードを表します。

名前	型	説明
count	integer (int32)	取得したドキュメントの数。
elapsedMs	integer (int32)	取得アクティビティの経過時間 (ミリ秒単位)。
id	integer (int32)	アクティビティレコードの ID。
query	Query	取得アクティビティのクエリの詳細。
queryTime	string (date-time)	この取得アクティビティのクエリ時間。
targetIndex	string	取得アクティビティのターゲット・インデックス。
type	string: AzureSearchQuery	アクティビティ・レコードのタイプ。

KnowledgeAgentSemanticRankerActivityRecord

Object

セマンティック・ランカー・アクティビティー・レコードを表します。

名前	型	説明
elapsedMs	integer (int32)	モデルアクティビティの経過時間 (ミリ秒単位)。
id	integer (int32)	アクティビティレコードの ID。
inputTokens	integer (int32)	セマンティックランカーアクティビティの入力トークンの数。
type	string: AzureSearchSemanticRanker	アクティビティ・レコードのタイプ。

Query

Object

取得アクティビティのクエリの詳細。

名前	型	説明
filter	string	フィルター文字列。
search	string	検索文字列。