Knowledge Retrieval - Retrieve

서비스:: Search Service

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

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

POST {endpoint}/agents('{agentName}')/retrieve?api-version=2025-05-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[]	자연어 메시지 스타일 개체입니다.
targetIndexParams		KnowledgeAgentIndexParams[]

응답

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-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"
      }
    }
  ]
}

정의

Name	Description
ErrorAdditionalInfo	리소스 관리 오류 추가 정보입니다.
ErrorDetail	오류 세부 정보입니다.
ErrorResponse	오류 응답
Image
KnowledgeAgentAzureSearchDocReference	Azure Search 문서 참조를 나타냅니다.
KnowledgeAgentIndexParams
KnowledgeAgentMessage	자연어 메시지 스타일 개체입니다.
KnowledgeAgentMessageContentType	메시지 콘텐츠의 유형입니다.
KnowledgeAgentMessageImageContent	문자 메시지 유형입니다.
KnowledgeAgentMessageTextContent	문자 메시지 유형입니다.
KnowledgeAgentModelQueryPlanningActivityRecord	LLM 쿼리 계획 활동 레코드를 나타냅니다.
KnowledgeAgentRetrievalRequest	검색 요청에 대한 입력 계약입니다.
KnowledgeAgentRetrievalResponse	검색 응답에 대한 출력 계약입니다.
KnowledgeAgentSearchActivityRecord	검색 작업 레코드를 나타냅니다.
KnowledgeAgentSemanticRankerActivityRecord	시맨틱 랭커 활동 레코드를 나타냅니다.
Query	검색 작업에 대한 쿼리 세부 정보입니다.

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	이미지의 URL입니다.

KnowledgeAgentAzureSearchDocReference

Object

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

Name	형식	Description
activitySource	integer (int32)	참조에 대한 소스 활동 ID입니다.
docKey	string	참조에 대한 문서 키입니다.
id	string	참조의 ID입니다.
sourceData	object
type	string: AzureSearchDoc	참조의 유형입니다.

KnowledgeAgentIndexParams

Object

Name	형식	Description
filterAddOn	string	인덱스에 적용되는 필터 조건(예: 'State eq VA').
includeReferenceSourceData	boolean	참조 소스 데이터를 포함해야 하는지 여부를 나타냅니다.
indexName	string	params가 적용되는 인덱스의 이름입니다.
maxDocsForReranker	integer (int32)	순위를 매기는 데 고려되는 문서 수를 제한합니다.
rerankerThreshold	number (float) minimum: 0 maximum: 4	결과의 순위를 다시 지정하기 위한 임계값(범위: 0-4).

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	메시지의 형식

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
messages	KnowledgeAgentMessage[]	자연어 메시지 스타일 개체입니다.
targetIndexParams	KnowledgeAgentIndexParams[]

KnowledgeAgentRetrievalResponse

Object

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

Name	형식	Description
activity	KnowledgeAgentActivityRecord[]: KnowledgeAgentModelQueryPlanningActivityRecord[] KnowledgeAgentSearchActivityRecord[] KnowledgeAgentSemanticRankerActivityRecord[]	진행 상황 및 청구 의미를 추적하기 위한 활동 기록입니다.
references	KnowledgeAgentReference[]: KnowledgeAgentAzureSearchDocReference[]	응답에 사용된 검색 데이터에 대한 참조입니다.
response	KnowledgeAgentMessage[]	자연어 메시지 스타일 개체입니다.

KnowledgeAgentSearchActivityRecord

Object

검색 작업 레코드를 나타냅니다.

Name	형식	Description
count	integer (int32)	검색된 문서의 수입니다.
elapsedMs	integer (int32)	검색 작업에 대해 경과된 시간(밀리초)입니다.
id	integer (int32)	활동 레코드의 ID입니다.
query	Query	검색 작업에 대한 쿼리 세부 정보입니다.
queryTime	string (date-time)	이 검색 작업에 대한 쿼리 시간입니다.
targetIndex	string	검색 작업에 대한 대상 인덱스입니다.
type	string: AzureSearchQuery	활동 레코드의 유형입니다.

KnowledgeAgentSemanticRankerActivityRecord

Object

시맨틱 랭커 활동 레코드를 나타냅니다.

Name	형식	Description
elapsedMs	integer (int32)	모델 활동의 경과 시간(밀리초)입니다.
id	integer (int32)	활동 레코드의 ID입니다.
inputTokens	integer (int32)	시맨틱 랭커 활동에 대한 입력 토큰의 수입니다.
type	string: AzureSearchSemanticRanker	활동 레코드의 유형입니다.

Query

Object

검색 작업에 대한 쿼리 세부 정보입니다.

Name	형식	Description
filter	string	필터 문자열입니다.
search	string	검색 문자열입니다.