Knowledge Retrieval - Retrieve

Servizio:: Search Service

Versione API:: 2025-08-01-preview

KnowledgeAgent recupera i dati rilevanti dagli archivi di backup.

POST {endpoint}/agents('{agentName}')/retrieve?api-version=2025-08-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 di assistenza per 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.
knowledgeSourceParams		KnowledgeSourceParams[]: SearchIndexKnowledgeSourceParams[]

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-08-01-preview



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

Risposta di esempio

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

Definizioni

Nome	Descrizione
ErrorAdditionalInfo	Informazioni aggiuntive sull'errore di gestione delle risorse.
ErrorDetail	Dettagli dell'errore.
ErrorResponse	Risposta di errore
Image
KnowledgeAgentAzureBlobActivityArguments	Rappresenta gli argomenti con cui è stata eseguita l'attività di recupero del BLOB di Azure.
KnowledgeAgentAzureBlobActivityRecord	Rappresenta un record di attività di recupero BLOB di Azure.
KnowledgeAgentAzureBlobReference	Rappresenta un riferimento al documento di Archiviazione BLOB di Azure.
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.
KnowledgeAgentModelAnswerSynthesisActivityRecord	Rappresenta un record di attività di sintesi delle risposte LLM.
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.
KnowledgeAgentSearchIndexActivityArguments	Rappresenta gli argomenti con cui è stata eseguita l'attività di recupero dell'indice di ricerca.
KnowledgeAgentSearchIndexActivityRecord	Rappresenta un record dell'attività di recupero dell'indice di ricerca.
KnowledgeAgentSearchIndexReference	Rappresenta un riferimento al documento di Ricerca di Azure.
KnowledgeAgentSemanticRerankerActivityRecord	Rappresenta un record di attività del classificatore semantico.
KnowledgeSourceKind	Il tipo di fonte di conoscenza.
SearchIndexKnowledgeSourceParams	Specifica i parametri di runtime per un'origine conoscenza dell'indice di ricerca

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 (uri)	L'URL dell'immagine.

KnowledgeAgentAzureBlobActivityArguments

Oggetto

Rappresenta gli argomenti con cui è stata eseguita l'attività di recupero del BLOB di Azure.

Nome	Tipo	Descrizione
search	string	Stringa di ricerca usata per eseguire query sul contenuto del BLOB.

KnowledgeAgentAzureBlobActivityRecord

Oggetto

Rappresenta un record di attività di recupero BLOB di Azure.

Nome	Tipo	Descrizione
azureBlobArguments	KnowledgeAgentAzureBlobActivityArguments	Argomenti del BLOB di Azure per l'attività di recupero.
count	integer (int32)	Il conteggio dei documenti recuperati che erano sufficientemente rilevanti per superare la soglia di reranker.
elapsedMs	integer (int32)	Il tempo trascorso in millisecondi per l'attività di recupero.
id	integer (int32)	L'ID del record dell'attività.
knowledgeSourceName	string	La fonte di conoscenza per l'attività di recupero.
queryTime	string (date-time)	Tempo di query per l'attività di recupero.
type	string: azureBlob	Tipo di record dell'attività.

KnowledgeAgentAzureBlobReference

Oggetto

Rappresenta un riferimento al documento di Archiviazione BLOB di Azure.

Nome	Tipo	Descrizione
activitySource	integer (int32)	ID attività di origine per il riferimento.
blobUrl	string	URL del BLOB per il riferimento.
id	string	L'ID del riferimento.
rerankerScore	number (float)	Punteggio del reranker per il riferimento al documento.
sourceData	object
type	string: azureBlob	Tipo di riferimento.

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	Il tipo di messaggio

KnowledgeAgentMessageTextContent

Oggetto

Tipo di messaggio di testo.

Nome	Tipo	Descrizione
text	string
type	string: text	Il tipo di messaggio

KnowledgeAgentModelAnswerSynthesisActivityRecord

Oggetto

Rappresenta un record di attività di sintesi delle risposte LLM.

Nome	Tipo	Descrizione
elapsedMs	integer (int32)	Il tempo trascorso in millisecondi per l'attività di recupero.
id	integer (int32)	L'ID del record dell'attività.
inputTokens	integer (int32)	Il numero di token di input per l'attività di sintesi delle risposte LLM.
outputTokens	integer (int32)	Il numero di token di output per l'attività di sintesi delle risposte LLM.
type	string: modelAnswerSynthesis	Tipo di record dell'attività.

KnowledgeAgentModelQueryPlanningActivityRecord

Oggetto

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

Nome	Tipo	Descrizione
elapsedMs	integer (int32)	Il tempo trascorso in millisecondi per l'attività di recupero.
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
knowledgeSourceParams	KnowledgeSourceParams[]: SearchIndexKnowledgeSourceParams[]
messages	KnowledgeAgentMessage[]	L'oggetto stile del messaggio in linguaggio naturale.

KnowledgeAgentRetrievalResponse

Oggetto

Contratto di output per la risposta di recupero.

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

KnowledgeAgentSearchIndexActivityArguments

Oggetto

Rappresenta gli argomenti con cui è stata eseguita l'attività di recupero dell'indice di ricerca.

Nome	Tipo	Descrizione
filter	string	Stringa di filtro.
search	string	Stringa di ricerca utilizzata per eseguire una query sull'indice di ricerca.

KnowledgeAgentSearchIndexActivityRecord

Oggetto

Rappresenta un record dell'attività di recupero dell'indice di ricerca.

Nome	Tipo	Descrizione
count	integer (int32)	Il conteggio dei documenti recuperati che erano sufficientemente rilevanti per superare la soglia di reranker.
elapsedMs	integer (int32)	Il tempo trascorso in millisecondi per l'attività di recupero.
id	integer (int32)	L'ID del record dell'attività.
knowledgeSourceName	string	La fonte di conoscenza per l'attività di recupero.
queryTime	string (date-time)	Tempo di query per l'attività di recupero.
searchIndexArguments	KnowledgeAgentSearchIndexActivityArguments	Gli argomenti dell'indice di ricerca per l'attività di recupero.
type	string: searchIndex	Tipo di record dell'attività.

KnowledgeAgentSearchIndexReference

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.
rerankerScore	number (float)	Punteggio del reranker per il riferimento al documento.
sourceData	object
type	string: searchIndex	Tipo di riferimento.

KnowledgeAgentSemanticRerankerActivityRecord

Oggetto

Rappresenta un record di attività del classificatore semantico.

Nome	Tipo	Descrizione
elapsedMs	integer (int32)	Il tempo trascorso in millisecondi per l'attività di recupero.
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: semanticReranker	Tipo di record dell'attività.

KnowledgeSourceKind

Enumerazione

Il tipo di fonte di conoscenza.

Valore	Descrizione
searchIndex	Origine della conoscenza che legge i dati da un indice di ricerca.
azureBlob	Un'origine delle informazioni che legge e inserisce dati da Archiviazione BLOB di Azure in un indice di ricerca.

SearchIndexKnowledgeSourceParams

Oggetto

Specifica i parametri di runtime per un'origine conoscenza dell'indice di ricerca

Nome	Tipo	Descrizione
filterAddOn	string	Una condizione di filtro applicata all'indice (ad esempio, 'State eq VA').
kind	string: searchIndex	Tipo di origine della conoscenza.
knowledgeSourceName	string	Nome dell'indice a cui si applicano i parametri.