Knowledge Retrieval - Retrieve

Service:: Search Service

Version d'API:: 2025-05-01-preview

KnowledgeAgent récupère les données pertinentes à partir des magasins de sauvegarde.

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

Paramètres URI

Nom	Dans	Obligatoire	Type	Description
agentName	path	True	string	Nom de l’agent.
endpoint	path	True	string (url)	URL du point de terminaison du service de recherche.
api-version	query	True	string	Version de l’API cliente.

En-tête de la demande

Nom	Obligatoire	Type	Description
x-ms-client-request-id		string (uuid)	ID de suivi envoyé avec la demande pour faciliter le débogage.
x-ms-query-source-authorization		string	Jeton identifiant l’utilisateur pour lequel la requête est exécutée. Ce jeton est utilisé pour appliquer des restrictions de sécurité sur les documents.

Corps de la demande

Nom	Obligatoire	Type	Description
messages	True	KnowledgeAgentMessage[]	Objet de style de message en langage naturel.
targetIndexParams		KnowledgeAgentIndexParams[]

Réponses

Nom	Type	Description
200 OK	KnowledgeAgentRetrievalResponse	La réponse de récupération est renvoyée avec succès.
Other Status Codes	ErrorResponse	Réponse d’erreur.

Exemples

KnowledgeAgentRetrieve

Exemple de requête

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

Exemple de réponse

Code d’état:: 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"
      }
    }
  ]
}

Définitions

Nom	Description
ErrorAdditionalInfo	Informations supplémentaires sur l’erreur de gestion des ressources.
ErrorDetail	Détail de l’erreur.
ErrorResponse	Réponse d’erreur
Image
KnowledgeAgentAzureSearchDocReference	Représente une référence de document Recherche Azure.
KnowledgeAgentIndexParams
KnowledgeAgentMessage	Objet de style de message en langage naturel.
KnowledgeAgentMessageContentType	Le type de contenu du message.
KnowledgeAgentMessageImageContent	Type de message texte.
KnowledgeAgentMessageTextContent	Type de message texte.
KnowledgeAgentModelQueryPlanningActivityRecord	Représente un enregistrement d’activité de planification de requête LLM.
KnowledgeAgentRetrievalRequest	Contrat d’entrée pour la demande d’extraction.
KnowledgeAgentRetrievalResponse	Contrat de sortie pour la réponse d’extraction.
KnowledgeAgentSearchActivityRecord	Représente un enregistrement d’activité d’extraction.
KnowledgeAgentSemanticRankerActivityRecord	Représente un enregistrement d’activité de ranker sémantique.
Query	Détails de la requête pour l’activité d’extraction.

ErrorAdditionalInfo

Objet

Informations supplémentaires sur l’erreur de gestion des ressources.

Nom	Type	Description
info	object	Informations supplémentaires.
type	string	Type d’informations supplémentaire.

ErrorDetail

Objet

Détail de l’erreur.

Nom	Type	Description
additionalInfo	ErrorAdditionalInfo[]	Informations supplémentaires sur l’erreur.
code	string	Code d’erreur.
details	ErrorDetail[]	Détails de l’erreur.
message	string	Message d’erreur.
target	string	Cible d’erreur.

ErrorResponse

Objet

Réponse d’erreur

Nom	Type	Description
error	ErrorDetail	Objet d’erreur.

Image

Objet

Nom	Type	Description
url	string	L’URL de l’image.

KnowledgeAgentAzureSearchDocReference

Objet

Représente une référence de document Recherche Azure.

Nom	Type	Description
activitySource	integer (int32)	ID de l’activité source de la référence.
docKey	string	Clé de document de référence.
id	string	ID de la référence.
sourceData	object
type	string: AzureSearchDoc	Type de référence.

KnowledgeAgentIndexParams

Objet

Nom	Type	Description
filterAddOn	string	Une condition de filtre appliquée à l’index (par exemple, 'State eq VA').
includeReferenceSourceData	boolean	Indique si les données de la source de référence doivent être incluses.
indexName	string	Nom de l’index auquel les paramètres s’appliquent.
maxDocsForReranker	integer (int32)	Limite le nombre de documents pris en compte pour le classement.
rerankerThreshold	number (float) minimum: 0 maximum: 4	Un seuil pour les résultats de reclassement (plage : 0-4).

KnowledgeAgentMessage

Objet

Objet de style de message en langage naturel.

Nom	Type	Description
content	KnowledgeAgentMessageContent[]: KnowledgeAgentMessageImageContent[] KnowledgeAgentMessageTextContent[]	Spécifie le type de contenu du message.
role	string	Le rôle de la réponse de l’outil.

KnowledgeAgentMessageContentType

Énumération

Le type de contenu du message.

Valeur	Description
text	Type de contenu de message texte.
image	Type de contenu de message d’image.

KnowledgeAgentMessageImageContent

Objet

Type de message texte.

Nom	Type	Description
image	Image
type	string: image	Type du message

KnowledgeAgentMessageTextContent

Objet

Type de message texte.

Nom	Type	Description
text	string
type	string: text	Type du message

KnowledgeAgentModelQueryPlanningActivityRecord

Objet

Représente un enregistrement d’activité de planification de requête LLM.

Nom	Type	Description
elapsedMs	integer (int32)	Temps écoulé en millisecondes pour l’activité du modèle.
id	integer (int32)	ID de l’enregistrement d’activité.
inputTokens	integer (int32)	Nombre de jetons d’entrée pour l’activité de planification de requête LLM.
outputTokens	integer (int32)	Nombre de jetons de sortie pour l’activité de planification de requête LLM.
type	string: ModelQueryPlanning	Type d’enregistrement d’activité.

KnowledgeAgentRetrievalRequest

Objet

Contrat d’entrée pour la demande d’extraction.

Nom	Type	Description
messages	KnowledgeAgentMessage[]	Objet de style de message en langage naturel.
targetIndexParams	KnowledgeAgentIndexParams[]

KnowledgeAgentRetrievalResponse

Objet

Contrat de sortie pour la réponse d’extraction.

Nom	Type	Description
activity	KnowledgeAgentActivityRecord[]: KnowledgeAgentModelQueryPlanningActivityRecord[] KnowledgeAgentSearchActivityRecord[] KnowledgeAgentSemanticRankerActivityRecord[]	Les enregistrements d’activité permettent de suivre l’avancement et les implications de facturation.
references	KnowledgeAgentReference[]: KnowledgeAgentAzureSearchDocReference[]	Les références des données d’extraction utilisées dans la réponse.
response	KnowledgeAgentMessage[]	Objet de style de message en langage naturel.

KnowledgeAgentSearchActivityRecord

Objet

Représente un enregistrement d’activité d’extraction.

Nom	Type	Description
count	integer (int32)	Le nombre de documents récupérés.
elapsedMs	integer (int32)	Temps écoulé en millisecondes pour l’activité d’extraction.
id	integer (int32)	ID de l’enregistrement d’activité.
query	Query	Détails de la requête pour l’activité d’extraction.
queryTime	string (date-time)	Temps de requête pour cette activité d’extraction.
targetIndex	string	Index cible de l’activité d’extraction.
type	string: AzureSearchQuery	Type d’enregistrement d’activité.

KnowledgeAgentSemanticRankerActivityRecord

Objet

Représente un enregistrement d’activité de ranker sémantique.

Nom	Type	Description
elapsedMs	integer (int32)	Temps écoulé en millisecondes pour l’activité du modèle.
id	integer (int32)	ID de l’enregistrement d’activité.
inputTokens	integer (int32)	Nombre de jetons d’entrée pour l’activité de classement sémantique.
type	string: AzureSearchSemanticRanker	Type d’enregistrement d’activité.

Query

Objet

Détails de la requête pour l’activité d’extraction.

Nom	Type	Description
filter	string	La chaîne de filtre.
search	string	Chaîne de recherche.