Knowledge Retrieval - Retrieve

서비스:: Search Service

API 버전:: 2025-08-01-preview

KnowledgeAgent는 백업 저장소에서 관련 데이터를 검색합니다.

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

URI 매개 변수

Name	In(다음 안에)	필수	형식	Description
agentName	path	True	string	에이전트의 이름입니다.
endpoint	path	True	string (url)	검색 서비스의 엔드포인트 URL입니다.
api-version	query	True	string	클라이언트 API 버전.

요청 헤더

Name	필수	형식	Description
x-ms-client-request-id		string (uuid)	디버깅을 돕기 위해 요청과 함께 전송된 추적 ID입니다.
x-ms-query-source-authorization		string	쿼리가 실행되는 사용자를 식별하는 토큰입니다. 이 토큰은 문서에 보안 제한을 적용하는 데 사용됩니다.

요청 본문

Name	필수	형식	Description
messages	True	KnowledgeAgentMessage[]	자연어 메시지 스타일 개체입니다.
knowledgeSourceParams		KnowledgeSourceParams[]: SearchIndexKnowledgeSourceParams[]

응답

Name	형식	Description
200 OK	KnowledgeAgentRetrievalResponse	검색 응답이 성공적으로 반환됩니다.
Other Status Codes	ErrorResponse	오류 응답입니다.

예제

KnowledgeAgentRetrieve

샘플 요청

HTTP

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



{
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "text": "hello world",
          "type": "text"
        }
      ]
    }
  ],
  "knowledgeSourceParams": [
    {
      "filterAddOn": "foo eq bar",
      "knowledgeSourceName": "ks-preview-test",
      "kind": "searchIndex"
    }
  ]
}

샘플 응답

상태 코드:: 200

{
  "response": [
    {
      "content": [
        {
          "type": "text",
          "text": "[{...}]"
        }
      ]
    }
  ],
  "activity": [
    {
      "type": "modelQueryPlanning",
      "id": 0,
      "inputTokens": 11,
      "outputTokens": 22,
      "elapsedMs": 10
    },
    {
      "type": "searchIndex",
      "id": 1,
      "knowledgeSourceName": "ks-preview-test",
      "queryTime": "2025-01-01T00:08:45.045Z",
      "count": 2,
      "elapsedMs": 1234,
      "searchIndexArguments": {
        "search": "hello world",
        "filter": "foo eq bar"
      }
    },
    {
      "type": "searchIndex",
      "id": 2,
      "knowledgeSourceName": "ks-preview-test",
      "queryTime": "2025-01-01T00:08:45.045Z",
      "count": 2,
      "elapsedMs": 1234,
      "searchIndexArguments": {
        "search": "hello world two",
        "filter": "foo eq bar"
      }
    },
    {
      "type": "semanticReranker",
      "id": 3,
      "inputTokens": 74,
      "elapsedMs": 0
    }
  ],
  "references": [
    {
      "type": "searchIndex",
      "id": "83dd7d40",
      "activitySource": 1,
      "sourceData": {
        "id": "myDocKey1",
        "title": "high_doc",
        "content": "hello world"
      },
      "rerankerScore": 3.5,
      "docKey": "myDocKey1"
    },
    {
      "type": "searchIndex",
      "id": "83dd7d41",
      "activitySource": 1,
      "sourceData": {
        "id": "myDocKey2",
        "title": "low_doc",
        "content": "goodbye world"
      },
      "rerankerScore": 2.7,
      "docKey": "myDocKey2"
    }
  ]
}

정의

Name	Description
ErrorAdditionalInfo	리소스 관리 오류 추가 정보입니다.
ErrorDetail	오류 세부 정보입니다.
ErrorResponse	오류 응답
Image
KnowledgeAgentAzureBlobActivityArguments	Azure Blob 검색 작업이 실행된 인수를 나타냅니다.
KnowledgeAgentAzureBlobActivityRecord	Azure Blob 검색 활동 레코드를 나타냅니다.
KnowledgeAgentAzureBlobReference	Azure Blob Storage 문서 참조를 나타냅니다.
KnowledgeAgentMessage	자연어 메시지 스타일 개체입니다.
KnowledgeAgentMessageContentType	메시지 콘텐츠의 유형입니다.
KnowledgeAgentMessageImageContent	문자 메시지 유형.
KnowledgeAgentMessageTextContent	문자 메시지 유형.
KnowledgeAgentModelAnswerSynthesisActivityRecord	LLM 답변 합성 활동 레코드를 나타냅니다.
KnowledgeAgentModelQueryPlanningActivityRecord	LLM 쿼리 계획 활동 레코드를 나타냅니다.
KnowledgeAgentRetrievalRequest	검색 요청에 대한 입력 계약입니다.
KnowledgeAgentRetrievalResponse	검색 응답에 대한 출력 계약입니다.
KnowledgeAgentSearchIndexActivityArguments	검색 인덱스 검색 활동이 실행된 인수를 나타냅니다.
KnowledgeAgentSearchIndexActivityRecord	검색 인덱스 검색 활동 레코드를 나타냅니다.
KnowledgeAgentSearchIndexReference	Azure 검색 문서 참조를 나타냅니다.
KnowledgeAgentSemanticRerankerActivityRecord	의미 체계 랭커 활동 레코드를 나타냅니다.
KnowledgeSourceKind	지식 소스의 종류.
SearchIndexKnowledgeSourceParams	검색 인덱스 지식 원본에 대한 런타임 매개 변수를 지정합니다.

ErrorAdditionalInfo

Object

리소스 관리 오류 추가 정보입니다.

Name	형식	Description
info	object	추가 정보입니다.
type	string	추가 정보 유형입니다.

ErrorDetail

Object

오류 세부 정보입니다.

Name	형식	Description
additionalInfo	ErrorAdditionalInfo[]	오류 추가 정보입니다.
code	string	오류 코드입니다.
details	ErrorDetail[]	오류 세부 정보입니다.
message	string	오류 메시지입니다.
target	string	오류 대상입니다.

ErrorResponse

Object

오류 응답

Name	형식	Description
error	ErrorDetail	오류 개체입니다.

Image

Object

Name	형식	Description
url	string (uri)	이미지의 URL입니다.

KnowledgeAgentAzureBlobActivityArguments

Object

Azure Blob 검색 작업이 실행된 인수를 나타냅니다.

Name	형식	Description
search	string	Blob 콘텐츠를 쿼리하는 데 사용되는 검색 문자열입니다.

KnowledgeAgentAzureBlobActivityRecord

Object

Azure Blob 검색 활동 레코드를 나타냅니다.

Name	형식	Description
azureBlobArguments	KnowledgeAgentAzureBlobActivityArguments	검색 작업에 대한 azure blob 인수입니다.
count	integer (int32)	순위 변경 임계값을 통과하기에 충분히 관련성이 있는 검색된 문서 수입니다.
elapsedMs	integer (int32)	검색 활동에 대한 경과 시간(밀리초)입니다.
id	integer (int32)	활동 레코드의 ID입니다.
knowledgeSourceName	string	검색 활동에 대한 지식 소스입니다.
queryTime	string (date-time)	이 검색 활동에 대한 쿼리 시간입니다.
type	string: azureBlob	활동 레코드의 유형입니다.

KnowledgeAgentAzureBlobReference

Object

Azure Blob Storage 문서 참조를 나타냅니다.

Name	형식	Description
activitySource	integer (int32)	참조의 원본 활동 ID입니다.
blobUrl	string	참조에 대한 Blob URL입니다.
id	string	참조의 ID입니다.
rerankerScore	number (float)	문서 참조에 대한 순위 변경기 점수입니다.
sourceData	object
type	string: azureBlob	참조의 유형입니다.

KnowledgeAgentMessage

Object

자연어 메시지 스타일 개체입니다.

Name	형식	Description
content	KnowledgeAgentMessageContent[]: KnowledgeAgentMessageImageContent[] KnowledgeAgentMessageTextContent[]	메시지 콘텐츠의 유형을 지정합니다.
role	string	도구 응답의 역할입니다.

KnowledgeAgentMessageContentType

열거형

메시지 콘텐츠의 유형입니다.

값	Description
text	문자 메시지 콘텐츠 종류입니다.
image	이미지 메시지 콘텐츠 종류입니다.

KnowledgeAgentMessageImageContent

Object

문자 메시지 유형.

Name	형식	Description
image	Image
type	string: image	메시지 유형

KnowledgeAgentMessageTextContent

Object

문자 메시지 유형.

Name	형식	Description
text	string
type	string: text	메시지 유형

KnowledgeAgentModelAnswerSynthesisActivityRecord

Object

LLM 답변 합성 활동 레코드를 나타냅니다.

Name	형식	Description
elapsedMs	integer (int32)	검색 활동에 대한 경과 시간(밀리초)입니다.
id	integer (int32)	활동 레코드의 ID입니다.
inputTokens	integer (int32)	LLM 답변 합성 활동에 대한 입력 토큰 수입니다.
outputTokens	integer (int32)	LLM 답변 합성 활동에 대한 출력 토큰 수입니다.
type	string: modelAnswerSynthesis	활동 레코드의 유형입니다.

KnowledgeAgentModelQueryPlanningActivityRecord

Object

LLM 쿼리 계획 활동 레코드를 나타냅니다.

Name	형식	Description
elapsedMs	integer (int32)	검색 활동에 대한 경과 시간(밀리초)입니다.
id	integer (int32)	활동 레코드의 ID입니다.
inputTokens	integer (int32)	LLM 쿼리 계획 활동에 대한 입력 토큰 수입니다.
outputTokens	integer (int32)	LLM 쿼리 계획 활동에 대한 출력 토큰 수입니다.
type	string: modelQueryPlanning	활동 레코드의 유형입니다.

KnowledgeAgentRetrievalRequest

Object

검색 요청에 대한 입력 계약입니다.

Name	형식	Description
knowledgeSourceParams	KnowledgeSourceParams[]: SearchIndexKnowledgeSourceParams[]
messages	KnowledgeAgentMessage[]	자연어 메시지 스타일 개체입니다.

KnowledgeAgentRetrievalResponse

Object

검색 응답에 대한 출력 계약입니다.

Name	형식	Description
activity	KnowledgeAgentActivityRecord[]: KnowledgeAgentAzureBlobActivityRecord[] KnowledgeAgentModelAnswerSynthesisActivityRecord[] KnowledgeAgentModelQueryPlanningActivityRecord[] KnowledgeAgentSearchIndexActivityRecord[] KnowledgeAgentSemanticRerankerActivityRecord[]	진행 상황 및 청구 영향을 추적하기 위한 활동 레코드입니다.
references	KnowledgeAgentReference[]: KnowledgeAgentAzureBlobReference[] KnowledgeAgentSearchIndexReference[]	응답에 사용된 검색 데이터에 대한 참조입니다.
response	KnowledgeAgentMessage[]	자연어 메시지 스타일 개체입니다.

KnowledgeAgentSearchIndexActivityArguments

Object

검색 인덱스 검색 활동이 실행된 인수를 나타냅니다.

Name	형식	Description
filter	string	필터 문자열입니다.
search	string	검색 인덱스를 쿼리하는 데 사용되는 검색 문자열입니다.

KnowledgeAgentSearchIndexActivityRecord

Object

검색 인덱스 검색 활동 레코드를 나타냅니다.

Name	형식	Description
count	integer (int32)	순위 변경 임계값을 통과하기에 충분히 관련성이 있는 검색된 문서 수입니다.
elapsedMs	integer (int32)	검색 활동에 대한 경과 시간(밀리초)입니다.
id	integer (int32)	활동 레코드의 ID입니다.
knowledgeSourceName	string	검색 활동에 대한 지식 소스입니다.
queryTime	string (date-time)	이 검색 활동에 대한 쿼리 시간입니다.
searchIndexArguments	KnowledgeAgentSearchIndexActivityArguments	검색 활동에 대한 검색 인덱스 인수입니다.
type	string: searchIndex	활동 레코드의 유형입니다.

KnowledgeAgentSearchIndexReference

Object

Azure 검색 문서 참조를 나타냅니다.

Name	형식	Description
activitySource	integer (int32)	참조의 원본 활동 ID입니다.
docKey	string	참조에 대한 문서 키입니다.
id	string	참조의 ID입니다.
rerankerScore	number (float)	문서 참조에 대한 순위 변경기 점수입니다.
sourceData	object
type	string: searchIndex	참조의 유형입니다.

KnowledgeAgentSemanticRerankerActivityRecord

Object

의미 체계 랭커 활동 레코드를 나타냅니다.

Name	형식	Description
elapsedMs	integer (int32)	검색 활동에 대한 경과 시간(밀리초)입니다.
id	integer (int32)	활동 레코드의 ID입니다.
inputTokens	integer (int32)	의미 체계 순위 지정 활동에 대한 입력 토큰 수입니다.
type	string: semanticReranker	활동 레코드의 유형입니다.

KnowledgeSourceKind

열거형

지식 소스의 종류.

값	Description
searchIndex	검색 인덱스에서 데이터를 읽는 지식 소스입니다.
azureBlob	Azure Blob Storage에서 검색 인덱스로 데이터를 읽고 수집하는 기술 자료입니다.

SearchIndexKnowledgeSourceParams

Object

검색 인덱스 지식 원본에 대한 런타임 매개 변수를 지정합니다.

Name	형식	Description
filterAddOn	string	인덱스에 적용된 필터 조건(예: 'State eq VA').
kind	string: searchIndex	지식 소스의 유형입니다.
knowledgeSourceName	string	매개 변수가 적용되는 인덱스의 이름입니다.