Knowledge Retrieval - Retrieve

Dienst:: Search Service

API-Version:: 2025-08-01-preview

KnowledgeAgent ruft relevante Daten aus Sicherungsspeichern ab.

POST {endpoint}/agents('{agentName}')/retrieve?api-version=2025-08-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	Version der Client-API.

Anforderungsheader

Name	Erforderlich	Typ	Beschreibung
x-ms-client-request-id		string (uuid)	Die Nachverfolgungs-ID, die mit der Anforderung gesendet wird, um das Debuggen zu unterstützen.
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.
knowledgeSourceParams		KnowledgeSourceParams[]: SearchIndexKnowledgeSourceParams[]

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



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

Beispiel für eine Antwort

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

Definitionen

Name	Beschreibung
ErrorAdditionalInfo	Der Ressourcenverwaltungsfehler zusätzliche Informationen.
ErrorDetail	Das Fehlerdetails.
ErrorResponse	Fehlerantwort
Image
KnowledgeAgentAzureBlobActivityArguments	Stellt die Argumente dar, mit denen die Azure Blob-Abrufaktivität ausgeführt wurde.
KnowledgeAgentAzureBlobActivityRecord	Stellt einen Azure-Blob-Abrufaktivitätsdatensatz dar.
KnowledgeAgentAzureBlobReference	Stellt eine Azure Blob Storage-Dokumentreferenz dar.
KnowledgeAgentMessage	Das Nachrichtenstilobjekt in natürlicher Sprache.
KnowledgeAgentMessageContentType	Die Art des Nachrichteninhalts.
KnowledgeAgentMessageImageContent	Art der Textnachricht.
KnowledgeAgentMessageTextContent	Art der Textnachricht.
KnowledgeAgentModelAnswerSynthesisActivityRecord	Stellt einen Aktivitätsdatensatz für die LLM-Antwortsynthese dar.
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.
KnowledgeAgentSearchIndexActivityArguments	Stellt die Argumente dar, mit denen die Aktivität zum Abrufen des Suchindex ausgeführt wurde.
KnowledgeAgentSearchIndexActivityRecord	Stellt einen Aktivitätsdatensatz für den Suchindexabruf dar.
KnowledgeAgentSearchIndexReference	Stellt eine Azure Search-Dokumentreferenz dar.
KnowledgeAgentSemanticRerankerActivityRecord	Stellt einen Aktivitätsdatensatz für die semantische Rangfolge dar.
KnowledgeSourceKind	Die Art der Wissensquelle.
SearchIndexKnowledgeSourceParams	Gibt Laufzeitparameter für eine Wissensquelle für Suchindex an

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 (uri)	Die URL des Bildes.

KnowledgeAgentAzureBlobActivityArguments

Objekt

Stellt die Argumente dar, mit denen die Azure Blob-Abrufaktivität ausgeführt wurde.

Name	Typ	Beschreibung
search	string	Die Suchzeichenfolge, die zum Abfragen von Blobinhalten verwendet wird.

KnowledgeAgentAzureBlobActivityRecord

Objekt

Stellt einen Azure-Blob-Abrufaktivitätsdatensatz dar.

Name	Typ	Beschreibung
azureBlobArguments	KnowledgeAgentAzureBlobActivityArguments	Das azure-Blob argumentiert für die Abrufaktivität.
count	integer (int32)	Die Anzahl der abgerufenen Dokumente, die ausreichend relevant waren, um den Reranker-Schwellenwert zu überschreiten.
elapsedMs	integer (int32)	Die verstrichene Zeit in Millisekunden für die Abrufaktivität.
id	integer (int32)	Die ID des Aktivitätsdatensatzes.
knowledgeSourceName	string	Die Wissensquelle für die Abrufaktivität.
queryTime	string (date-time)	Die Abfragezeit für diese Abrufaktivität.
type	string: azureBlob	Der Typ des Aktivitätsdatensatzes.

KnowledgeAgentAzureBlobReference

Objekt

Stellt eine Azure Blob Storage-Dokumentreferenz dar.

Name	Typ	Beschreibung
activitySource	integer (int32)	Die Quellaktivitäts-ID für die Referenz.
blobUrl	string	Die Blob-URL für die Referenz.
id	string	Die ID der Referenz.
rerankerScore	number (float)	Die Reranker-Bewertung für die Dokumentreferenz.
sourceData	object
type	string: azureBlob	Der Typ der Referenz.

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

Art der Textnachricht.

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

KnowledgeAgentMessageTextContent

Objekt

Art der Textnachricht.

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

KnowledgeAgentModelAnswerSynthesisActivityRecord

Objekt

Stellt einen Aktivitätsdatensatz für die LLM-Antwortsynthese dar.

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

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 Abrufaktivitä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
knowledgeSourceParams	KnowledgeSourceParams[]: SearchIndexKnowledgeSourceParams[]
messages	KnowledgeAgentMessage[]	Das Nachrichtenstilobjekt in natürlicher Sprache.

KnowledgeAgentRetrievalResponse

Objekt

Der Ausgabevertrag für die Abrufantwort.

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

KnowledgeAgentSearchIndexActivityArguments

Objekt

Stellt die Argumente dar, mit denen die Aktivität zum Abrufen des Suchindex ausgeführt wurde.

Name	Typ	Beschreibung
filter	string	Die Filterzeichenfolge.
search	string	Die Suchzeichenfolge, die zum Abfragen des Suchindex verwendet wird.

KnowledgeAgentSearchIndexActivityRecord

Objekt

Stellt einen Aktivitätsdatensatz für den Suchindexabruf dar.

Name	Typ	Beschreibung
count	integer (int32)	Die Anzahl der abgerufenen Dokumente, die ausreichend relevant waren, um den Reranker-Schwellenwert zu überschreiten.
elapsedMs	integer (int32)	Die verstrichene Zeit in Millisekunden für die Abrufaktivität.
id	integer (int32)	Die ID des Aktivitätsdatensatzes.
knowledgeSourceName	string	Die Wissensquelle für die Abrufaktivität.
queryTime	string (date-time)	Die Abfragezeit für diese Abrufaktivität.
searchIndexArguments	KnowledgeAgentSearchIndexActivityArguments	Die Suchindexargumente für die Abrufaktivität.
type	string: searchIndex	Der Typ des Aktivitätsdatensatzes.

KnowledgeAgentSearchIndexReference

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.
rerankerScore	number (float)	Die Reranker-Bewertung für die Dokumentreferenz.
sourceData	object
type	string: searchIndex	Der Typ der Referenz.

KnowledgeAgentSemanticRerankerActivityRecord

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 Abrufaktivität.
id	integer (int32)	Die ID des Aktivitätsdatensatzes.
inputTokens	integer (int32)	Die Anzahl der Eingabetoken für die semantische Rangfolgeaktivität.
type	string: semanticReranker	Der Typ des Aktivitätsdatensatzes.

KnowledgeSourceKind

Enumeration

Die Art der Wissensquelle.

Wert	Beschreibung
searchIndex	Eine Wissensquelle, die Daten aus einem Suchindex liest.
azureBlob	Eine Wissensquelle, die Daten aus Azure Blob Storage liest und in einem Suchindex erfasst.

SearchIndexKnowledgeSourceParams

Objekt

Gibt Laufzeitparameter für eine Wissensquelle für Suchindex an

Name	Typ	Beschreibung
filterAddOn	string	Eine Filterbedingung, die auf den Index angewendet wird (z. B. "State eq VA").
kind	string: searchIndex	Der Typ der Wissensquelle.
knowledgeSourceName	string	Der Name des Indexes, auf den die Parameter angewendet werden.