Knowledge Retrieval - Retrieve

Servizio:: Search Service

Versione API:: 2025-05-01-preview

KnowledgeAgent recupera i dati rilevanti dagli archivi di backup.

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

Parametri dell'URI

Nome	In	Necessario	Tipo	Descrizione
agentName	path	True	string	Nome dell'agente.
endpoint	path	True	string (url)	URL dell'endpoint del servizio di ricerca.
api-version	query	True	string	Versione dell'API client.

Intestazione della richiesta

Nome	Necessario	Tipo	Descrizione
x-ms-client-request-id		string (uuid)	ID di rilevamento inviato con la richiesta per facilitare il debug.
x-ms-query-source-authorization		string	Token che identifica l'utente per il quale viene eseguita la query. Questo token viene utilizzato per applicare restrizioni di sicurezza ai documenti.

Corpo della richiesta

Nome	Necessario	Tipo	Descrizione
messages	True	KnowledgeAgentMessage[]	L'oggetto stile del messaggio in linguaggio naturale.
targetIndexParams		KnowledgeAgentIndexParams[]

Risposte

Nome	Tipo	Descrizione
200 OK	KnowledgeAgentRetrievalResponse	La risposta di recupero viene restituita correttamente.
Other Status Codes	ErrorResponse	Risposta di errore.

Esempio

KnowledgeAgentRetrieve

Esempio di richiesta

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

Risposta di esempio

Codice di stato:: 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"
      }
    }
  ]
}

Definizioni

Nome	Descrizione
ErrorAdditionalInfo	Informazioni aggiuntive sull'errore di gestione delle risorse.
ErrorDetail	Dettagli dell'errore.
ErrorResponse	Risposta di errore
Image
KnowledgeAgentAzureSearchDocReference	Rappresenta un riferimento al documento di Ricerca di Azure.
KnowledgeAgentIndexParams
KnowledgeAgentMessage	L'oggetto stile del messaggio in linguaggio naturale.
KnowledgeAgentMessageContentType	Tipo di contenuto del messaggio.
KnowledgeAgentMessageImageContent	Tipo di messaggio di testo.
KnowledgeAgentMessageTextContent	Tipo di messaggio di testo.
KnowledgeAgentModelQueryPlanningActivityRecord	Rappresenta un record di attività di pianificazione delle query LLM.
KnowledgeAgentRetrievalRequest	Contratto di input per la richiesta di recupero.
KnowledgeAgentRetrievalResponse	Contratto di output per la risposta di recupero.
KnowledgeAgentSearchActivityRecord	Rappresenta un record di attività di recupero.
KnowledgeAgentSemanticRankerActivityRecord	Rappresenta un record di attività del classificatore semantico.
Query	Dettagli della query per l'attività di recupero.

ErrorAdditionalInfo

Oggetto

Informazioni aggiuntive sull'errore di gestione delle risorse.

Nome	Tipo	Descrizione
info	object	Informazioni aggiuntive.
type	string	Tipo di informazioni aggiuntive.

ErrorDetail

Oggetto

Dettagli dell'errore.

Nome	Tipo	Descrizione
additionalInfo	ErrorAdditionalInfo[]	Informazioni aggiuntive sull'errore.
code	string	Codice di errore.
details	ErrorDetail[]	Dettagli dell'errore.
message	string	Messaggio di errore.
target	string	Destinazione dell'errore.

ErrorResponse

Oggetto

Risposta di errore

Nome	Tipo	Descrizione
error	ErrorDetail	Oggetto error.

Image

Oggetto

Nome	Tipo	Descrizione
url	string	L'URL dell'immagine.

KnowledgeAgentAzureSearchDocReference

Oggetto

Rappresenta un riferimento al documento di Ricerca di Azure.

Nome	Tipo	Descrizione
activitySource	integer (int32)	ID attività di origine per il riferimento.
docKey	string	La chiave del documento per il riferimento.
id	string	L'ID del riferimento.
sourceData	object
type	string: AzureSearchDoc	Tipo di riferimento.

KnowledgeAgentIndexParams

Oggetto

Nome	Tipo	Descrizione
filterAddOn	string	Una condizione di filtro applicata all'indice (ad esempio, 'State eq VA').
includeReferenceSourceData	boolean	Indica se devono essere inclusi i dati di origine di riferimento.
indexName	string	Nome dell'indice a cui si applicano i parametri.
maxDocsForReranker	integer (int32)	Limita il numero di documenti considerati per la classificazione.
rerankerThreshold	number (float) minimum: 0 maximum: 4	Una soglia per il riposizionamento dei risultati (intervallo: 0-4).

KnowledgeAgentMessage

Oggetto

L'oggetto stile del messaggio in linguaggio naturale.

Nome	Tipo	Descrizione
content	KnowledgeAgentMessageContent[]: KnowledgeAgentMessageImageContent[] KnowledgeAgentMessageTextContent[]	Specifica il tipo di contenuto del messaggio.
role	string	Il ruolo della risposta dello strumento.

KnowledgeAgentMessageContentType

Enumerazione

Tipo di contenuto del messaggio.

Valore	Descrizione
text	Tipo di contenuto del messaggio di testo.
image	Tipo di contenuto del messaggio immagine.

KnowledgeAgentMessageImageContent

Oggetto

Tipo di messaggio di testo.

Nome	Tipo	Descrizione
image	Image
type	string: image	Tipo del messaggio

KnowledgeAgentMessageTextContent

Oggetto

Tipo di messaggio di testo.

Nome	Tipo	Descrizione
text	string
type	string: text	Tipo del messaggio

KnowledgeAgentModelQueryPlanningActivityRecord

Oggetto

Rappresenta un record di attività di pianificazione delle query LLM.

Nome	Tipo	Descrizione
elapsedMs	integer (int32)	Tempo trascorso in millisecondi per l'attività del modello.
id	integer (int32)	L'ID del record dell'attività.
inputTokens	integer (int32)	Il numero di token di input per l'attività di pianificazione delle query LLM.
outputTokens	integer (int32)	Il numero di token di output per l'attività di pianificazione delle query LLM.
type	string: ModelQueryPlanning	Tipo di record dell'attività.

KnowledgeAgentRetrievalRequest

Oggetto

Contratto di input per la richiesta di recupero.

Nome	Tipo	Descrizione
messages	KnowledgeAgentMessage[]	L'oggetto stile del messaggio in linguaggio naturale.
targetIndexParams	KnowledgeAgentIndexParams[]

KnowledgeAgentRetrievalResponse

Oggetto

Contratto di output per la risposta di recupero.

Nome	Tipo	Descrizione
activity	KnowledgeAgentActivityRecord[]: KnowledgeAgentModelQueryPlanningActivityRecord[] KnowledgeAgentSearchActivityRecord[] KnowledgeAgentSemanticRankerActivityRecord[]	I record di attività per tenere traccia dello stato di avanzamento e delle implicazioni di fatturazione.
references	KnowledgeAgentReference[]: KnowledgeAgentAzureSearchDocReference[]	I riferimenti per i dati di recupero utilizzati nella risposta.
response	KnowledgeAgentMessage[]	L'oggetto stile del messaggio in linguaggio naturale.

KnowledgeAgentSearchActivityRecord

Oggetto

Rappresenta un record di attività di recupero.

Nome	Tipo	Descrizione
count	integer (int32)	Conteggio dei documenti recuperati.
elapsedMs	integer (int32)	Il tempo trascorso in millisecondi per l'attività di recupero.
id	integer (int32)	L'ID del record dell'attività.
query	Query	Dettagli della query per l'attività di recupero.
queryTime	string (date-time)	Tempo di query per l'attività di recupero.
targetIndex	string	L'indice target per l'attività di recupero.
type	string: AzureSearchQuery	Tipo di record dell'attività.

KnowledgeAgentSemanticRankerActivityRecord

Oggetto

Rappresenta un record di attività del classificatore semantico.

Nome	Tipo	Descrizione
elapsedMs	integer (int32)	Tempo trascorso in millisecondi per l'attività del modello.
id	integer (int32)	L'ID del record dell'attività.
inputTokens	integer (int32)	Numero di token di input per l'attività di classificazione semantica.
type	string: AzureSearchSemanticRanker	Tipo di record dell'attività.

Query

Oggetto

Dettagli della query per l'attività di recupero.

Nome	Tipo	Descrizione
filter	string	Stringa di filtro.
search	string	Stringa di ricerca.