Knowledge Retrieval - Retrieve

Usługa:: Search Service

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

KnowledgeAgent pobiera odpowiednie dane z magazynów zapasowych.

POST {endpoint}/agents('{agentName}')/retrieve?api-version=2025-05-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 ułatwić debugowanie.
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.
targetIndexParams		KnowledgeAgentIndexParams[]

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

Przykładowa odpowiedź

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

Definicje

Nazwa	Opis
ErrorAdditionalInfo	Dodatkowe informacje o błędzie zarządzania zasobami.
ErrorDetail	Szczegóły błędu.
ErrorResponse	Odpowiedź na błąd
Image
KnowledgeAgentAzureSearchDocReference	Reprezentuje dokumentację usługi Azure Search.
KnowledgeAgentIndexParams
KnowledgeAgentMessage	Obiekt stylu komunikatu w języku naturalnym.
KnowledgeAgentMessageContentType	Typ treści wiadomości.
KnowledgeAgentMessageImageContent	Typ wiadomości SMS.
KnowledgeAgentMessageTextContent	Typ wiadomości SMS.
KnowledgeAgentModelQueryPlanningActivityRecord	Reprezentuje rekord działania planowania zapytań LLM.
KnowledgeAgentRetrievalRequest	Kontrakt wejściowy dla żądania pobrania.
KnowledgeAgentRetrievalResponse	Kontrakt wyjściowy dla odpowiedzi pobierania.
KnowledgeAgentSearchActivityRecord	Reprezentuje rekord działania pobierania.
KnowledgeAgentSemanticRankerActivityRecord	Reprezentuje semantyczny rekord działania klasyfikatora.
Query	Szczegóły zapytania dotyczące działania pobierania.

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	Adres URL obrazu.

KnowledgeAgentAzureSearchDocReference

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.
sourceData	object
type	string: AzureSearchDoc	Typ odwołania.

KnowledgeAgentIndexParams

Objekt

Nazwa	Typ	Opis
filterAddOn	string	Warunek filtru zastosowany do indeksu (np. "State eq VA").
includeReferenceSourceData	boolean	Wskazuje, czy należy uwzględnić dane źródła odniesienia.
indexName	string	Nazwa indeksu, do którego mają zastosowanie parametry.
maxDocsForReranker	integer (int32)	Ogranicza liczbę dokumentów branych pod uwagę przy klasyfikowaniu.
rerankerThreshold	number (float) minimum: 0 maximum: 4	Próg ponownego klasyfikowania wyników (zakres: 0–4).

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 SMS.

Nazwa	Typ	Opis
image	Image
type	string: image	Typ komunikatu

KnowledgeAgentMessageTextContent

Objekt

Typ wiadomości SMS.

Nazwa	Typ	Opis
text	string
type	string: text	Typ komunikatu

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 modelu.
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
messages	KnowledgeAgentMessage[]	Obiekt stylu komunikatu w języku naturalnym.
targetIndexParams	KnowledgeAgentIndexParams[]

KnowledgeAgentRetrievalResponse

Objekt

Kontrakt wyjściowy dla odpowiedzi pobierania.

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

KnowledgeAgentSearchActivityRecord

Objekt

Reprezentuje rekord działania pobierania.

Nazwa	Typ	Opis
count	integer (int32)	Liczba pobranych dokumentów.
elapsedMs	integer (int32)	Czas, który upłynął w milisekundach dla działania pobierania.
id	integer (int32)	Identyfikator rekordu działania.
query	Query	Szczegóły zapytania dotyczące działania pobierania.
queryTime	string (date-time)	Czas zapytania dla tego działania pobierania.
targetIndex	string	Indeks docelowy dla działania pobierania.
type	string: AzureSearchQuery	Typ rekordu działania.

KnowledgeAgentSemanticRankerActivityRecord

Objekt

Reprezentuje semantyczny rekord działania klasyfikatora.

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

Query

Objekt

Szczegóły zapytania dotyczące działania pobierania.

Nazwa	Typ	Opis
filter	string	Ciąg filtru.
search	string	Szukany ciąg.