Knowledge Retrieval - Retrieve

Dienst:: Search Service

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

KnowledgeAgent ruft relevante Daten aus Sicherungsspeichern ab.

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

URI-Parameter

Name	In	Erforderlich	Typ	Beschreibung
agentName	path	True	string	Der Name des Agents.
endpoint	path	True	string (url)	Die Endpunkt-URL des Suchdiensts.
api-version	query	True	string	Client-API-Version.

Anforderungsheader

Name	Erforderlich	Typ	Beschreibung
x-ms-client-request-id		string (uuid)	Die Tracking-ID, die mit der Anforderung gesendet wurde, um beim Debuggen zu helfen.
x-ms-query-source-authorization		string	Token, das den Benutzer identifiziert, für den die Abfrage ausgeführt wird. Dieses Token wird verwendet, um Sicherheitseinschränkungen für Dokumente durchzusetzen.

Anforderungstext

Name	Erforderlich	Typ	Beschreibung
messages	True	KnowledgeAgentMessage[]	Das Nachrichtenstilobjekt in natürlicher Sprache.
targetIndexParams		KnowledgeAgentIndexParams[]

Antworten

Name	Typ	Beschreibung
200 OK	KnowledgeAgentRetrievalResponse	Die Abrufantwort wird erfolgreich zurückgegeben.
Other Status Codes	ErrorResponse	Fehlerantwort.

Beispiele

KnowledgeAgentRetrieve

Beispielanforderung

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

Beispiel für eine Antwort

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

Definitionen

Name	Beschreibung
ErrorAdditionalInfo	Der Ressourcenverwaltungsfehler zusätzliche Informationen.
ErrorDetail	Das Fehlerdetails.
ErrorResponse	Fehlerantwort
Image
KnowledgeAgentAzureSearchDocReference	Stellt eine Azure Search-Dokumentreferenz dar.
KnowledgeAgentIndexParams
KnowledgeAgentMessage	Das Nachrichtenstilobjekt in natürlicher Sprache.
KnowledgeAgentMessageContentType	Die Art des Nachrichteninhalts.
KnowledgeAgentMessageImageContent	Textnachrichtentyp.
KnowledgeAgentMessageTextContent	Textnachrichtentyp.
KnowledgeAgentModelQueryPlanningActivityRecord	Stellt einen Datensatz für die LLM-Abfrageplanungsaktivität dar.
KnowledgeAgentRetrievalRequest	Der Eingabevertrag für den Abrufauftrag.
KnowledgeAgentRetrievalResponse	Der Ausgabevertrag für die Abrufantwort.
KnowledgeAgentSearchActivityRecord	Stellt einen Datensatz der Abrufaktivität dar.
KnowledgeAgentSemanticRankerActivityRecord	Stellt einen Aktivitätsdatensatz für die semantische Rangfolge dar.
Query	Die Abfragedetails für die Abrufaktivität.

ErrorAdditionalInfo

Objekt

Der Ressourcenverwaltungsfehler zusätzliche Informationen.

Name	Typ	Beschreibung
info	object	Die zusätzlichen Informationen.
type	string	Der zusätzliche Informationstyp.

ErrorDetail

Objekt

Das Fehlerdetails.

Name	Typ	Beschreibung
additionalInfo	ErrorAdditionalInfo[]	Die zusätzlichen Informationen des Fehlers.
code	string	Der Fehlercode.
details	ErrorDetail[]	Die Fehlerdetails.
message	string	Die Fehlermeldung.
target	string	Das Fehlerziel.

ErrorResponse

Objekt

Fehlerantwort

Name	Typ	Beschreibung
error	ErrorDetail	Das Fehlerobjekt.

Image

Objekt

Name	Typ	Beschreibung
url	string	Die URL des Bildes.

KnowledgeAgentAzureSearchDocReference

Objekt

Stellt eine Azure Search-Dokumentreferenz dar.

Name	Typ	Beschreibung
activitySource	integer (int32)	Die Quellaktivitäts-ID für die Referenz.
docKey	string	Der Dokumentschlüssel für die Referenz.
id	string	Die ID der Referenz.
sourceData	object
type	string: AzureSearchDoc	Der Typ der Referenz.

KnowledgeAgentIndexParams

Objekt

Name	Typ	Beschreibung
filterAddOn	string	Eine Filterbedingung, die auf den Index angewendet wird (z. B. "State eq VA").
includeReferenceSourceData	boolean	Gibt an, ob Referenzquelldaten eingeschlossen werden sollen.
indexName	string	Der Name des Indexes, auf den die Parameter angewendet werden.
maxDocsForReranker	integer (int32)	Begrenzt die Anzahl der Dokumente, die für die Rangfolge berücksichtigt werden.
rerankerThreshold	number (float) minimum: 0 maximum: 4	Ein Schwellenwert für die Neueinstufung von Ergebnissen (Bereich: 0-4).

KnowledgeAgentMessage

Objekt

Das Nachrichtenstilobjekt in natürlicher Sprache.

Name	Typ	Beschreibung
content	KnowledgeAgentMessageContent[]: KnowledgeAgentMessageImageContent[] KnowledgeAgentMessageTextContent[]	Gibt den Typ des Nachrichteninhalts an.
role	string	Die Rolle der Tool-Reaktion.

KnowledgeAgentMessageContentType

Enumeration

Die Art des Nachrichteninhalts.

Wert	Beschreibung
text	Art des Inhalts von Textnachrichten.
image	Art des Inhalts von Bildnachrichten.

KnowledgeAgentMessageImageContent

Objekt

Textnachrichtentyp.

Name	Typ	Beschreibung
image	Image
type	string: image	Der Typ der Nachricht

KnowledgeAgentMessageTextContent

Objekt

Textnachrichtentyp.

Name	Typ	Beschreibung
text	string
type	string: text	Der Typ der Nachricht

KnowledgeAgentModelQueryPlanningActivityRecord

Objekt

Stellt einen Datensatz für die LLM-Abfrageplanungsaktivität dar.

Name	Typ	Beschreibung
elapsedMs	integer (int32)	Die verstrichene Zeit in Millisekunden für die Modellaktivität.
id	integer (int32)	Die ID des Aktivitätsdatensatzes.
inputTokens	integer (int32)	Die Anzahl der Eingabetoken für die LLM-Abfrageplanungsaktivität.
outputTokens	integer (int32)	Die Anzahl der Ausgabetoken für die LLM-Abfrageplanungsaktivität.
type	string: ModelQueryPlanning	Der Typ des Aktivitätsdatensatzes.

KnowledgeAgentRetrievalRequest

Objekt

Der Eingabevertrag für den Abrufauftrag.

Name	Typ	Beschreibung
messages	KnowledgeAgentMessage[]	Das Nachrichtenstilobjekt in natürlicher Sprache.
targetIndexParams	KnowledgeAgentIndexParams[]

KnowledgeAgentRetrievalResponse

Objekt

Der Ausgabevertrag für die Abrufantwort.

Name	Typ	Beschreibung
activity	KnowledgeAgentActivityRecord[]: KnowledgeAgentModelQueryPlanningActivityRecord[] KnowledgeAgentSearchActivityRecord[] KnowledgeAgentSemanticRankerActivityRecord[]	Die Aktivitätsdatensätze zur Nachverfolgung des Fortschritts und der Auswirkungen auf die Abrechnung.
references	KnowledgeAgentReference[]: KnowledgeAgentAzureSearchDocReference[]	Die Referenzen für die Abrufdaten, die in der Antwort verwendet werden.
response	KnowledgeAgentMessage[]	Das Nachrichtenstilobjekt in natürlicher Sprache.

KnowledgeAgentSearchActivityRecord

Objekt

Stellt einen Datensatz der Abrufaktivität dar.

Name	Typ	Beschreibung
count	integer (int32)	Die Anzahl der abgerufenen Dokumente.
elapsedMs	integer (int32)	Die verstrichene Zeit in Millisekunden für die Abrufaktivität.
id	integer (int32)	Die ID des Aktivitätsdatensatzes.
query	Query	Die Abfragedetails für die Abrufaktivität.
queryTime	string (date-time)	Die Abfragezeit für diese Abrufaktivität.
targetIndex	string	Der Zielindex für die Abrufaktivität.
type	string: AzureSearchQuery	Der Typ des Aktivitätsdatensatzes.

KnowledgeAgentSemanticRankerActivityRecord

Objekt

Stellt einen Aktivitätsdatensatz für die semantische Rangfolge dar.

Name	Typ	Beschreibung
elapsedMs	integer (int32)	Die verstrichene Zeit in Millisekunden für die Modellaktivität.
id	integer (int32)	Die ID des Aktivitätsdatensatzes.
inputTokens	integer (int32)	Die Anzahl der Eingabetoken für die semantische Rangfolgeaktivität.
type	string: AzureSearchSemanticRanker	Der Typ des Aktivitätsdatensatzes.

Query

Objekt

Die Abfragedetails für die Abrufaktivität.

Name	Typ	Beschreibung
filter	string	Die Filterzeichenfolge.
search	string	Die Suchzeichenfolge.