Knowledge Retrieval - Retrieve

Usługa:: Search Service

Wersja interfejsu API:: 2025-08-01-preview

KnowledgeAgent pobiera odpowiednie dane z magazynów zapasowych.

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

Parametry identyfikatora URI

Nazwa	W	Wymagane	Typ	Opis
agentName	path	True	string	Nazwa agenta.
endpoint	path	True	string (url)	Adres URL punktu końcowego usługi wyszukiwania.
api-version	query	True	string	Wersja interfejsu API klienta.

Nagłówek żądania

Nazwa	Wymagane	Typ	Opis
x-ms-client-request-id		string (uuid)	Identyfikator śledzenia wysłany z żądaniem, aby pomóc w debugowaniu.
x-ms-query-source-authorization		string	Token identyfikujący użytkownika, dla którego jest wykonywane zapytanie. Ten token służy do wymuszania ograniczeń zabezpieczeń dokumentów.

Treść żądania

Nazwa	Wymagane	Typ	Opis
messages	True	KnowledgeAgentMessage[]	Obiekt stylu komunikatu w języku naturalnym.
knowledgeSourceParams		KnowledgeSourceParams[]: SearchIndexKnowledgeSourceParams[]

Odpowiedzi

Nazwa	Typ	Opis
200 OK	KnowledgeAgentRetrievalResponse	Odpowiedź pobierania została pomyślnie zwrócona.
Other Status Codes	ErrorResponse	Odpowiedź na błąd.

Przykłady

KnowledgeAgentRetrieve

Przykładowe żądanie

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

Przykładowa odpowiedź

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

Definicje

Nazwa	Opis
ErrorAdditionalInfo	Dodatkowe informacje o błędzie zarządzania zasobami.
ErrorDetail	Szczegóły błędu.
ErrorResponse	Odpowiedź na błąd
Image
KnowledgeAgentAzureBlobActivityArguments	Reprezentuje argumenty, z którymi uruchomiono działanie pobierania obiektów blob platformy Azure.
KnowledgeAgentAzureBlobActivityRecord	Reprezentuje rekord działania pobierania obiektów blob platformy Azure.
KnowledgeAgentAzureBlobReference	Reprezentuje dokumentację Azure Blob Storage.
KnowledgeAgentMessage	Obiekt stylu komunikatu w języku naturalnym.
KnowledgeAgentMessageContentType	Typ treści wiadomości.
KnowledgeAgentMessageImageContent	Typ wiadomości tekstowej.
KnowledgeAgentMessageTextContent	Typ wiadomości tekstowej.
KnowledgeAgentModelAnswerSynthesisActivityRecord	Reprezentuje rekord działania syntezy odpowiedzi LLM.
KnowledgeAgentModelQueryPlanningActivityRecord	Reprezentuje rekord działania planowania zapytań LLM.
KnowledgeAgentRetrievalRequest	Kontrakt wejściowy dla żądania pobrania.
KnowledgeAgentRetrievalResponse	Kontrakt wyjściowy dla odpowiedzi pobierania.
KnowledgeAgentSearchIndexActivityArguments	Reprezentuje argumenty, z którymi zostało uruchomione działanie pobierania indeksu wyszukiwania.
KnowledgeAgentSearchIndexActivityRecord	Reprezentuje rekord działania pobierania indeksu wyszukiwania.
KnowledgeAgentSearchIndexReference	Reprezentuje dokumentację usługi Azure Search.
KnowledgeAgentSemanticRerankerActivityRecord	Reprezentuje semantyczny rekord działania klasyfikatora.
KnowledgeSourceKind	Rodzaj źródła wiedzy.
SearchIndexKnowledgeSourceParams	Określa parametry środowiska uruchomieniowego dla źródła wiedzy indeksu wyszukiwania

ErrorAdditionalInfo

Objekt

Dodatkowe informacje o błędzie zarządzania zasobami.

Nazwa	Typ	Opis
info	object	Dodatkowe informacje.
type	string	Dodatkowy typ informacji.

ErrorDetail

Objekt

Szczegóły błędu.

Nazwa	Typ	Opis
additionalInfo	ErrorAdditionalInfo[]	Dodatkowe informacje o błędzie.
code	string	Kod błędu.
details	ErrorDetail[]	Szczegóły błędu.
message	string	Komunikat o błędzie.
target	string	Element docelowy błędu.

ErrorResponse

Objekt

Odpowiedź na błąd

Nazwa	Typ	Opis
error	ErrorDetail	Obiekt błędu.

Image

Objekt

Nazwa	Typ	Opis
url	string (uri)	Adres URL obrazu.

KnowledgeAgentAzureBlobActivityArguments

Objekt

Reprezentuje argumenty, z którymi uruchomiono działanie pobierania obiektów blob platformy Azure.

Nazwa	Typ	Opis
search	string	Ciąg wyszukiwania używany do wykonywania zapytań dotyczących zawartości obiektu blob.

KnowledgeAgentAzureBlobActivityRecord

Objekt

Reprezentuje rekord działania pobierania obiektów blob platformy Azure.

Nazwa	Typ	Opis
azureBlobArguments	KnowledgeAgentAzureBlobActivityArguments	Argumenty obiektu blob platformy Azure dla działania pobierania.
count	integer (int32)	Liczba odzyskanych dokumentów, które były wystarczająco istotne, aby przekroczyć próg przeszeregowania.
elapsedMs	integer (int32)	Czas, który upłynął w milisekundach dla działania pobierania.
id	integer (int32)	Identyfikator rekordu działania.
knowledgeSourceName	string	Źródło wiedzy dla działania pobierania.
queryTime	string (date-time)	Czas zapytania dla tego działania pobierania.
type	string: azureBlob	Typ rekordu działania.

KnowledgeAgentAzureBlobReference

Objekt

Reprezentuje dokumentację Azure Blob Storage.

Nazwa	Typ	Opis
activitySource	integer (int32)	Identyfikator działania źródłowego dla odwołania.
blobUrl	string	Adres URL obiektu blob dla odwołania.
id	string	Identyfikator odwołania.
rerankerScore	number (float)	Wynik rerankera dla odwołania do dokumentu.
sourceData	object
type	string: azureBlob	Typ odwołania.

KnowledgeAgentMessage

Objekt

Obiekt stylu komunikatu w języku naturalnym.

Nazwa	Typ	Opis
content	KnowledgeAgentMessageContent[]: KnowledgeAgentMessageImageContent[] KnowledgeAgentMessageTextContent[]	Określa typ treści wiadomości.
role	string	Rola odpowiedzi narzędzia.

KnowledgeAgentMessageContentType

Wyliczenie

Typ treści wiadomości.

Wartość	Opis
text	Rodzaj treści wiadomości tekstowej.
image	Rodzaj treści wiadomości obrazu.

KnowledgeAgentMessageImageContent

Objekt

Typ wiadomości tekstowej.

Nazwa	Typ	Opis
image	Image
type	string: image	Typ wiadomości

KnowledgeAgentMessageTextContent

Objekt

Typ wiadomości tekstowej.

Nazwa	Typ	Opis
text	string
type	string: text	Typ wiadomości

KnowledgeAgentModelAnswerSynthesisActivityRecord

Objekt

Reprezentuje rekord działania syntezy odpowiedzi LLM.

Nazwa	Typ	Opis
elapsedMs	integer (int32)	Czas, który upłynął w milisekundach dla działania pobierania.
id	integer (int32)	Identyfikator rekordu działania.
inputTokens	integer (int32)	Liczba tokenów wejściowych dla działania syntezy odpowiedzi LLM.
outputTokens	integer (int32)	Liczba tokenów wyjściowych dla działania syntezy odpowiedzi LLM.
type	string: modelAnswerSynthesis	Typ rekordu działania.

KnowledgeAgentModelQueryPlanningActivityRecord

Objekt

Reprezentuje rekord działania planowania zapytań LLM.

Nazwa	Typ	Opis
elapsedMs	integer (int32)	Czas, który upłynął w milisekundach dla działania pobierania.
id	integer (int32)	Identyfikator rekordu działania.
inputTokens	integer (int32)	Liczba tokenów wejściowych dla działania planowania zapytań LLM.
outputTokens	integer (int32)	Liczba tokenów wyjściowych dla działania planowania zapytań LLM.
type	string: modelQueryPlanning	Typ rekordu działania.

KnowledgeAgentRetrievalRequest

Objekt

Kontrakt wejściowy dla żądania pobrania.

Nazwa	Typ	Opis
knowledgeSourceParams	KnowledgeSourceParams[]: SearchIndexKnowledgeSourceParams[]
messages	KnowledgeAgentMessage[]	Obiekt stylu komunikatu w języku naturalnym.

KnowledgeAgentRetrievalResponse

Objekt

Kontrakt wyjściowy dla odpowiedzi pobierania.

Nazwa	Typ	Opis
activity	KnowledgeAgentActivityRecord[]: KnowledgeAgentAzureBlobActivityRecord[] KnowledgeAgentModelAnswerSynthesisActivityRecord[] KnowledgeAgentModelQueryPlanningActivityRecord[] KnowledgeAgentSearchIndexActivityRecord[] KnowledgeAgentSemanticRerankerActivityRecord[]	Rejestry aktywności do śledzenia postępów i implikacji rozliczeniowych.
references	KnowledgeAgentReference[]: KnowledgeAgentAzureBlobReference[] KnowledgeAgentSearchIndexReference[]	Odwołania do danych wyszukiwania używanych w odpowiedzi.
response	KnowledgeAgentMessage[]	Obiekt stylu komunikatu w języku naturalnym.

KnowledgeAgentSearchIndexActivityArguments

Objekt

Reprezentuje argumenty, z którymi zostało uruchomione działanie pobierania indeksu wyszukiwania.

Nazwa	Typ	Opis
filter	string	Ciąg filtru.
search	string	Ciąg wyszukiwania używany do wykonywania zapytań dotyczących indeksu wyszukiwania.

KnowledgeAgentSearchIndexActivityRecord

Objekt

Reprezentuje rekord działania pobierania indeksu wyszukiwania.

Nazwa	Typ	Opis
count	integer (int32)	Liczba odzyskanych dokumentów, które były wystarczająco istotne, aby przekroczyć próg przeszeregowania.
elapsedMs	integer (int32)	Czas, który upłynął w milisekundach dla działania pobierania.
id	integer (int32)	Identyfikator rekordu działania.
knowledgeSourceName	string	Źródło wiedzy dla działania pobierania.
queryTime	string (date-time)	Czas zapytania dla tego działania pobierania.
searchIndexArguments	KnowledgeAgentSearchIndexActivityArguments	Argumenty indeksu wyszukiwania dla działania pobierania.
type	string: searchIndex	Typ rekordu działania.

KnowledgeAgentSearchIndexReference

Objekt

Reprezentuje dokumentację usługi Azure Search.

Nazwa	Typ	Opis
activitySource	integer (int32)	Identyfikator działania źródłowego dla odwołania.
docKey	string	Klucz dokumentu dla referencji.
id	string	Identyfikator odwołania.
rerankerScore	number (float)	Wynik rerankera dla odwołania do dokumentu.
sourceData	object
type	string: searchIndex	Typ odwołania.

KnowledgeAgentSemanticRerankerActivityRecord

Objekt

Reprezentuje semantyczny rekord działania klasyfikatora.

Nazwa	Typ	Opis
elapsedMs	integer (int32)	Czas, który upłynął w milisekundach dla działania pobierania.
id	integer (int32)	Identyfikator rekordu działania.
inputTokens	integer (int32)	Liczba tokenów wejściowych dla działania klasyfikatora semantycznego.
type	string: semanticReranker	Typ rekordu działania.

KnowledgeSourceKind

Wyliczenie

Rodzaj źródła wiedzy.

Wartość	Opis
searchIndex	Źródło wiedzy, które odczytuje dane z indeksu wyszukiwania.
azureBlob	Źródło wiedzy, które odczytuje i pozyskuje dane z Azure Blob Storage do indeksu wyszukiwania.

SearchIndexKnowledgeSourceParams

Objekt

Określa parametry środowiska uruchomieniowego dla źródła wiedzy indeksu wyszukiwania

Nazwa	Typ	Opis
filterAddOn	string	Warunek filtru zastosowany do indeksu (np. "State eq VA").
kind	string: searchIndex	Typ źródła wiedzy.
knowledgeSourceName	string	Nazwa indeksu, do którego mają zastosowanie parametry.