Knowledge Retrieval - Retrieve

Service:: Search Service

API-versie:: 2025-05-01-preview

KnowledgeAgent haalt relevante gegevens op uit backingstores.

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

URI-parameters

Name	In	Vereist	Type	Description
agentName	path	True	string	De naam van de agent.
endpoint	path	True	string (url)	De eindpunt-URL van de zoekservice.
api-version	query	True	string	Client-API-versie.

Aanvraagkoptekst

Name	Vereist	Type	Description
x-ms-client-request-id		string (uuid)	De tracerings-id die is verzonden met de aanvraag om hulp te bieden bij foutopsporing.
x-ms-query-source-authorization		string	Token dat de gebruiker identificeert waarvoor de query wordt uitgevoerd. Dit token wordt gebruikt om beveiligingsbeperkingen op documenten af te dwingen.

Aanvraagbody

Name	Vereist	Type	Description
messages	True	KnowledgeAgentMessage[]	Het object in de stijl van berichten in natuurlijke taal.
targetIndexParams		KnowledgeAgentIndexParams[]

Antwoorden

Name	Type	Description
200 OK	KnowledgeAgentRetrievalResponse	Het ophaalantwoord wordt met succes geretourneerd.
Other Status Codes	ErrorResponse	Foutreactie.

Voorbeelden

KnowledgeAgentRetrieve

Voorbeeldaanvraag

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

Voorbeeldrespons

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

Definities

Name	Description
ErrorAdditionalInfo	Aanvullende informatie over de resourcebeheerfout.
ErrorDetail	De foutdetails.
ErrorResponse	Foutreactie
Image
KnowledgeAgentAzureSearchDocReference	Vertegenwoordigt een Azure Search-documentverwijzing.
KnowledgeAgentIndexParams
KnowledgeAgentMessage	Het object in de stijl van berichten in natuurlijke taal.
KnowledgeAgentMessageContentType	Het type berichtinhoud.
KnowledgeAgentMessageImageContent	Type tekstbericht.
KnowledgeAgentMessageTextContent	Type tekstbericht.
KnowledgeAgentModelQueryPlanningActivityRecord	Vertegenwoordigt een activiteitsrecord voor LLM-queryplanning.
KnowledgeAgentRetrievalRequest	Het invoercontract voor het opgehaalde verzoek.
KnowledgeAgentRetrievalResponse	Het outputcontract voor het ophaalantwoord.
KnowledgeAgentSearchActivityRecord	Vertegenwoordigt een record van een ophaalactiviteit.
KnowledgeAgentSemanticRankerActivityRecord	Vertegenwoordigt een semantische rangschikkingsactiviteitsrecord.
Query	De querydetails voor de ophaalactiviteit.

ErrorAdditionalInfo

Object

Aanvullende informatie over de resourcebeheerfout.

Name	Type	Description
info	object	De aanvullende informatie.
type	string	Het extra informatietype.

ErrorDetail

Object

De foutdetails.

Name	Type	Description
additionalInfo	ErrorAdditionalInfo[]	De fout bevat aanvullende informatie.
code	string	De foutcode.
details	ErrorDetail[]	De foutdetails.
message	string	Het foutbericht.
target	string	Het foutdoel.

ErrorResponse

Object

Foutreactie

Name	Type	Description
error	ErrorDetail	Het foutobject.

Image

Object

Name	Type	Description
url	string	De url van de afbeelding.

KnowledgeAgentAzureSearchDocReference

Object

Vertegenwoordigt een Azure Search-documentverwijzing.

Name	Type	Description
activitySource	integer (int32)	De bronactiviteit-id voor de referentie.
docKey	string	De documentsleutel voor de referentie.
id	string	De ID van de referentie.
sourceData	object
type	string: AzureSearchDoc	Het type referentie.

KnowledgeAgentIndexParams

Object

Name	Type	Description
filterAddOn	string	Een filtervoorwaarde die op de index wordt toegepast (bijvoorbeeld 'Staat eq VA').
includeReferenceSourceData	boolean	Geeft aan of referentiebrongegevens moeten worden opgenomen.
indexName	string	De naam van de index waarop de parameters van toepassing zijn.
maxDocsForReranker	integer (int32)	Beperkt het aantal documenten dat in aanmerking komt voor rangschikking.
rerankerThreshold	number (float) minimum: 0 maximum: 4	Een drempel voor het opnieuw rangschikken van de resultaten (bereik: 0-4).

KnowledgeAgentMessage

Object

Het object in de stijl van berichten in natuurlijke taal.

Name	Type	Description
content	KnowledgeAgentMessageContent[]: KnowledgeAgentMessageImageContent[] KnowledgeAgentMessageTextContent[]	Hiermee geeft u het type inhoud van het bericht op.
role	string	De rol van de reactie van de tool.

KnowledgeAgentMessageContentType

Opsomming

Het type berichtinhoud.

Waarde	Description
text	Soort van inhoud van sms-berichten.
image	Soort afbeeldingsbericht.

KnowledgeAgentMessageImageContent

Object

Type tekstbericht.

Name	Type	Description
image	Image
type	string: image	Het type bericht

KnowledgeAgentMessageTextContent

Object

Type tekstbericht.

Name	Type	Description
text	string
type	string: text	Het type bericht

KnowledgeAgentModelQueryPlanningActivityRecord

Object

Vertegenwoordigt een activiteitsrecord voor LLM-queryplanning.

Name	Type	Description
elapsedMs	integer (int32)	De verstreken tijd in milliseconden voor de modelactiviteit.
id	integer (int32)	De ID van de activiteitsrecord.
inputTokens	integer (int32)	Het aantal invoertokens voor de LLM-queryplanningsactiviteit.
outputTokens	integer (int32)	Het aantal uitvoertokens voor de LLM-queryplanningsactiviteit.
type	string: ModelQueryPlanning	Het type activiteitsrecord.

KnowledgeAgentRetrievalRequest

Object

Het invoercontract voor het opgehaalde verzoek.

Name	Type	Description
messages	KnowledgeAgentMessage[]	Het object in de stijl van berichten in natuurlijke taal.
targetIndexParams	KnowledgeAgentIndexParams[]

KnowledgeAgentRetrievalResponse

Object

Het outputcontract voor het ophaalantwoord.

Name	Type	Description
activity	KnowledgeAgentActivityRecord[]: KnowledgeAgentModelQueryPlanningActivityRecord[] KnowledgeAgentSearchActivityRecord[] KnowledgeAgentSemanticRankerActivityRecord[]	De activiteitsrecords voor het bijhouden van de voortgang en de gevolgen voor de facturering.
references	KnowledgeAgentReference[]: KnowledgeAgentAzureSearchDocReference[]	De verwijzingen naar de ophaalgegevens die in het antwoord worden gebruikt.
response	KnowledgeAgentMessage[]	Het object in de stijl van berichten in natuurlijke taal.

KnowledgeAgentSearchActivityRecord

Object

Vertegenwoordigt een record van een ophaalactiviteit.

Name	Type	Description
count	integer (int32)	Het aantal opgehaalde documenten.
elapsedMs	integer (int32)	De verstreken tijd in milliseconden voor de ophaalactiviteit.
id	integer (int32)	De ID van de activiteitsrecord.
query	Query	De querydetails voor de ophaalactiviteit.
queryTime	string (date-time)	De querytijd voor deze ophaalactiviteit.
targetIndex	string	De doelindex voor de ophaalactiviteit.
type	string: AzureSearchQuery	Het type activiteitsrecord.

KnowledgeAgentSemanticRankerActivityRecord

Object

Vertegenwoordigt een semantische rangschikkingsactiviteitsrecord.

Name	Type	Description
elapsedMs	integer (int32)	De verstreken tijd in milliseconden voor de modelactiviteit.
id	integer (int32)	De ID van de activiteitsrecord.
inputTokens	integer (int32)	Het aantal invoertokens voor de semantische rangschikkingsactiviteit.
type	string: AzureSearchSemanticRanker	Het type activiteitsrecord.

Query

Object

De querydetails voor de ophaalactiviteit.

Name	Type	Description
filter	string	De filterreeks.
search	string	De zoekreeks.