Knowledge Retrieval - Retrieve

Služba:: Search Service

Verze rozhraní API:: 2025-08-01-preview

KnowledgeAgent získává relevantní data ze záložních obchodů.

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

Parametry identifikátoru URI

Name	V	Vyžadováno	Typ	Description
agentName	path	True	string	Název agenta.
endpoint	path	True	string (url)	Adresa URL koncového bodu vyhledávací služby.
api-version	query	True	string	Verze rozhraní API klienta.

Hlavička požadavku

Name	Vyžadováno	Typ	Description
x-ms-client-request-id		string (uuid)	ID sledování odeslané s požadavkem na pomoc s laděním.
x-ms-query-source-authorization		string	Token identifikující uživatele, pro kterého je dotaz prováděn. Tento token se používá k vynucení bezpečnostních omezení dokumentů.

Text požadavku

Name	Vyžadováno	Typ	Description
messages	True	KnowledgeAgentMessage[]	Objekt stylu zprávy v přirozeném jazyce.
knowledgeSourceParams		KnowledgeSourceParams[]: SearchIndexKnowledgeSourceParams[]

Odpovědi

Name	Typ	Description
200 OK	KnowledgeAgentRetrievalResponse	Odpověď na načtení je úspěšně vrácena.
Other Status Codes	ErrorResponse	Chybová odpověď.

Příklady

KnowledgeAgentRetrieve

Ukázkový požadavek

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

Ukázková odpověď

Stavový kód:: 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"
    }
  ]
}

Definice

Name	Description
ErrorAdditionalInfo	Další informace o chybě správy prostředků
ErrorDetail	Podrobnosti o chybě.
ErrorResponse	Chybová odpověď
Image
KnowledgeAgentAzureBlobActivityArguments	Představuje argumenty, se kterými byla spuštěna aktivita načítání objektů blob Azure.
KnowledgeAgentAzureBlobActivityRecord	Představuje záznam aktivity načítání objektů blob v Azure.
KnowledgeAgentAzureBlobReference	Představuje referenční informace k dokumentu služby Azure Blob Storage.
KnowledgeAgentMessage	Objekt stylu zprávy v přirozeném jazyce.
KnowledgeAgentMessageContentType	Typ obsahu zprávy.
KnowledgeAgentMessageImageContent	Typ textové zprávy.
KnowledgeAgentMessageTextContent	Typ textové zprávy.
KnowledgeAgentModelAnswerSynthesisActivityRecord	Představuje záznam aktivity syntézy odpovědí LLM.
KnowledgeAgentModelQueryPlanningActivityRecord	Představuje záznam aktivity plánování dotazu LLM.
KnowledgeAgentRetrievalRequest	Vstupní kontrakt pro požadavek na načtení.
KnowledgeAgentRetrievalResponse	Výstupní kontrakt pro odpověď na načtení.
KnowledgeAgentSearchIndexActivityArguments	Představuje argumenty, se kterými byla spuštěna aktivita načítání vyhledávacího indexu.
KnowledgeAgentSearchIndexActivityRecord	Představuje záznam aktivity načítání indexu vyhledávání.
KnowledgeAgentSearchIndexReference	Představuje referenční dokument Azure Search.
KnowledgeAgentSemanticRerankerActivityRecord	Představuje záznam aktivity sémantického hodnoticího nástroje.
KnowledgeSourceKind	Druh zdroje znalostí.
SearchIndexKnowledgeSourceParams	Určuje parametry běhového prostředí pro zdroj znalostí o indexu vyhledávání

ErrorAdditionalInfo

Objekt

Další informace o chybě správy prostředků

Name	Typ	Description
info	object	Další informace.
type	string	Další typ informací.

ErrorDetail

Objekt

Podrobnosti o chybě.

Name	Typ	Description
additionalInfo	ErrorAdditionalInfo[]	Další informace o chybě.
code	string	Kód chyby.
details	ErrorDetail[]	Podrobnosti o chybě.
message	string	Chybová zpráva.
target	string	Cíl chyby.

ErrorResponse

Objekt

Chybová odpověď

Name	Typ	Description
error	ErrorDetail	Objekt chyby.

Image

Objekt

Name	Typ	Description
url	string (uri)	Adresa URL obrázku.

KnowledgeAgentAzureBlobActivityArguments

Objekt

Představuje argumenty, se kterými byla spuštěna aktivita načítání objektů blob Azure.

Name	Typ	Description
search	string	Vyhledávací řetězec používaný k dotazování na obsah objektů blob.

KnowledgeAgentAzureBlobActivityRecord

Objekt

Představuje záznam aktivity načítání objektů blob v Azure.

Name	Typ	Description
azureBlobArguments	KnowledgeAgentAzureBlobActivityArguments	Argumenty objektu blob azure pro aktivitu načítání.
count	integer (int32)	Počet načtených dokumentů, které byly dostatečně relevantní pro překročení prahové hodnoty pro opětovné pořadí.
elapsedMs	integer (int32)	Čas, který uplynul v milisekundách pro aktivitu načítání.
id	integer (int32)	ID záznamu aktivity.
knowledgeSourceName	string	Zdroj znalostí pro vyhledávací aktivitu.
queryTime	string (date-time)	Čas dotazu pro tuto aktivitu načítání.
type	string: azureBlob	Typ záznamu aktivity.

KnowledgeAgentAzureBlobReference

Objekt

Představuje referenční informace k dokumentu služby Azure Blob Storage.

Name	Typ	Description
activitySource	integer (int32)	ID zdrojové aktivity odkazu.
blobUrl	string	Adresa URL objektu blob pro referenci.
id	string	ID odkazu.
rerankerScore	number (float)	Skóre opětovného hodnocení pro odkaz na dokument.
sourceData	object
type	string: azureBlob	Typ odkazu.

KnowledgeAgentMessage

Objekt

Objekt stylu zprávy v přirozeném jazyce.

Name	Typ	Description
content	KnowledgeAgentMessageContent[]: KnowledgeAgentMessageImageContent[] KnowledgeAgentMessageTextContent[]	Určuje typ obsahu zprávy.
role	string	Role odezvy nástroje.

KnowledgeAgentMessageContentType

Výčet

Typ obsahu zprávy.

Hodnota	Description
text	Druh obsahu textové zprávy.
image	Druh obsahu obrazové zprávy.

KnowledgeAgentMessageImageContent

Objekt

Typ textové zprávy.

Name	Typ	Description
image	Image
type	string: image	Typ zprávy

KnowledgeAgentMessageTextContent

Objekt

Typ textové zprávy.

Name	Typ	Description
text	string
type	string: text	Typ zprávy

KnowledgeAgentModelAnswerSynthesisActivityRecord

Objekt

Představuje záznam aktivity syntézy odpovědí LLM.

Name	Typ	Description
elapsedMs	integer (int32)	Čas, který uplynul v milisekundách pro aktivitu načítání.
id	integer (int32)	ID záznamu aktivity.
inputTokens	integer (int32)	Počet vstupních tokenů pro aktivitu syntézy odpovědí LLM.
outputTokens	integer (int32)	Počet výstupních tokenů pro aktivitu syntézy odpovědí LLM.
type	string: modelAnswerSynthesis	Typ záznamu aktivity.

KnowledgeAgentModelQueryPlanningActivityRecord

Objekt

Představuje záznam aktivity plánování dotazu LLM.

Name	Typ	Description
elapsedMs	integer (int32)	Čas, který uplynul v milisekundách pro aktivitu načítání.
id	integer (int32)	ID záznamu aktivity.
inputTokens	integer (int32)	Počet vstupních tokenů pro aktivitu plánování dotazů LLM.
outputTokens	integer (int32)	Počet výstupních tokenů pro aktivitu plánování dotazů LLM.
type	string: modelQueryPlanning	Typ záznamu aktivity.

KnowledgeAgentRetrievalRequest

Objekt

Vstupní kontrakt pro požadavek na načtení.

Name	Typ	Description
knowledgeSourceParams	KnowledgeSourceParams[]: SearchIndexKnowledgeSourceParams[]
messages	KnowledgeAgentMessage[]	Objekt stylu zprávy v přirozeném jazyce.

KnowledgeAgentRetrievalResponse

Objekt

Výstupní kontrakt pro odpověď na načtení.

Name	Typ	Description
activity	KnowledgeAgentActivityRecord[]: KnowledgeAgentAzureBlobActivityRecord[] KnowledgeAgentModelAnswerSynthesisActivityRecord[] KnowledgeAgentModelQueryPlanningActivityRecord[] KnowledgeAgentSearchIndexActivityRecord[] KnowledgeAgentSemanticRerankerActivityRecord[]	Záznamy o aktivitách pro sledování průběhu a důsledků fakturace.
references	KnowledgeAgentReference[]: KnowledgeAgentAzureBlobReference[] KnowledgeAgentSearchIndexReference[]	Odkazy na načítání dat použitých v odpovědi.
response	KnowledgeAgentMessage[]	Objekt stylu zprávy v přirozeném jazyce.

KnowledgeAgentSearchIndexActivityArguments

Objekt

Představuje argumenty, se kterými byla spuštěna aktivita načítání vyhledávacího indexu.

Name	Typ	Description
filter	string	Řetězec filtru.
search	string	Hledaný řetězec použitý k dotazování na vyhledávací index.

KnowledgeAgentSearchIndexActivityRecord

Objekt

Představuje záznam aktivity načítání indexu vyhledávání.

Name	Typ	Description
count	integer (int32)	Počet načtených dokumentů, které byly dostatečně relevantní pro překročení prahové hodnoty pro opětovné pořadí.
elapsedMs	integer (int32)	Čas, který uplynul v milisekundách pro aktivitu načítání.
id	integer (int32)	ID záznamu aktivity.
knowledgeSourceName	string	Zdroj znalostí pro vyhledávací aktivitu.
queryTime	string (date-time)	Čas dotazu pro tuto aktivitu načítání.
searchIndexArguments	KnowledgeAgentSearchIndexActivityArguments	Argumenty indexu vyhledávání pro aktivnost vyhledávání.
type	string: searchIndex	Typ záznamu aktivity.

KnowledgeAgentSearchIndexReference

Objekt

Představuje referenční dokument Azure Search.

Name	Typ	Description
activitySource	integer (int32)	ID zdrojové aktivity odkazu.
docKey	string	Klíč dokumentu pro odkaz.
id	string	ID odkazu.
rerankerScore	number (float)	Skóre opětovného hodnocení pro odkaz na dokument.
sourceData	object
type	string: searchIndex	Typ odkazu.

KnowledgeAgentSemanticRerankerActivityRecord

Objekt

Představuje záznam aktivity sémantického hodnoticího nástroje.

Name	Typ	Description
elapsedMs	integer (int32)	Čas, který uplynul v milisekundách pro aktivitu načítání.
id	integer (int32)	ID záznamu aktivity.
inputTokens	integer (int32)	Počet vstupních tokenů pro aktivitu sémantického řazení.
type	string: semanticReranker	Typ záznamu aktivity.

KnowledgeSourceKind

Výčet

Druh zdroje znalostí.

Hodnota	Description
searchIndex	Zdroj znalostí, který čte data z indexu vyhledávání.
azureBlob	Zdroj znalostí, který čte a ingestuje data z Azure Blob Storage do indexu vyhledávání.

SearchIndexKnowledgeSourceParams

Objekt

Určuje parametry běhového prostředí pro zdroj znalostí o indexu vyhledávání

Name	Typ	Description
filterAddOn	string	Podmínka filtru aplikovaná na index (např. 'State eq VA').
kind	string: searchIndex	Typ zdroje znalostí.
knowledgeSourceName	string	Název indexu, na který se parametry vztahují.