Knowledge Retrieval - Retrieve

Tjänst:: Search Service

API-version:: 2025-08-01-preview

KnowledgeAgent hämtar relevanta data från säkerhetskopieringsbutiker.

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

URI-parametrar

Name	I	Obligatorisk	Typ	Description
agentName	path	True	string	Namnet på agenten.
endpoint	path	True	string (url)	Slutpunkts-URL:en för söktjänsten.
api-version	query	True	string	Klient-API-version.

Begärandehuvud

Name	Obligatorisk	Typ	Description
x-ms-client-request-id		string (uuid)	Spårnings-ID:t som skickades med begäran för att hjälpa till med felsökning.
x-ms-query-source-authorization		string	Token som identifierar den användare som frågan körs för. Denna token används för att framtvinga säkerhetsbegränsningar för dokument.

Begärandetext

Name	Obligatorisk	Typ	Description
messages	True	KnowledgeAgentMessage[]	Objektet för meddelandeformat på naturligt språk.
knowledgeSourceParams		KnowledgeSourceParams[]: SearchIndexKnowledgeSourceParams[]

Svar

Name	Typ	Description
200 OK	KnowledgeAgentRetrievalResponse	Hämtningssvaret returneras.
Other Status Codes	ErrorResponse	Felsvar.

Exempel

KnowledgeAgentRetrieve

Exempelbegäran

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

Exempelsvar

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

Definitioner

Name	Description
ErrorAdditionalInfo	Ytterligare information om resurshanteringsfelet.
ErrorDetail	Felinformationen.
ErrorResponse	Felsvar
Image
KnowledgeAgentAzureBlobActivityArguments	Representerar argumenten som Azure Blob Retrieval-aktiviteten kördes med.
KnowledgeAgentAzureBlobActivityRecord	Representerar en aktivitetspost för hämtning av Azure Blob-blobar.
KnowledgeAgentAzureBlobReference	Representerar en Azure Blob Storage dokumentreferens.
KnowledgeAgentMessage	Objektet för meddelandeformat på naturligt språk.
KnowledgeAgentMessageContentType	Typ av meddelandeinnehåll.
KnowledgeAgentMessageImageContent	Typ av textmeddelande.
KnowledgeAgentMessageTextContent	Typ av textmeddelande.
KnowledgeAgentModelAnswerSynthesisActivityRecord	Representerar en LLM-svarssyntesaktivitetspost.
KnowledgeAgentModelQueryPlanningActivityRecord	Representerar en LLM-frågeplaneringsaktivitetspost.
KnowledgeAgentRetrievalRequest	Indatakontraktet för hämtningsbegäran.
KnowledgeAgentRetrievalResponse	Utdatakontraktet för hämtningssvaret.
KnowledgeAgentSearchIndexActivityArguments	Representerar de argument som sökindexhämtningsaktiviteten kördes med.
KnowledgeAgentSearchIndexActivityRecord	Representerar en post för hämtningsaktivitet för sökindex.
KnowledgeAgentSearchIndexReference	Representerar en referens för ett Azure Search-dokument.
KnowledgeAgentSemanticRerankerActivityRecord	Representerar en semantisk rankningsaktivitetspost.
KnowledgeSourceKind	Typen av kunskapskälla.
SearchIndexKnowledgeSourceParams	Anger körningsparametrar för en kunskapskälla för sökindex

ErrorAdditionalInfo

Objekt

Ytterligare information om resurshanteringsfelet.

Name	Typ	Description
info	object	Ytterligare information.
type	string	Ytterligare informationstyp.

ErrorDetail

Objekt

Felinformationen.

Name	Typ	Description
additionalInfo	ErrorAdditionalInfo[]	Ytterligare information om felet.
code	string	Felkoden.
details	ErrorDetail[]	Felinformationen.
message	string	Felmeddelandet.
target	string	Felmålet.

ErrorResponse

Objekt

Felsvar

Name	Typ	Description
error	ErrorDetail	Felobjektet.

Image

Objekt

Name	Typ	Description
url	string (uri)	Webbadressen till bilden.

KnowledgeAgentAzureBlobActivityArguments

Objekt

Representerar argumenten som Azure Blob Retrieval-aktiviteten kördes med.

Name	Typ	Description
search	string	Söksträngen som används för att fråga blobinnehåll.

KnowledgeAgentAzureBlobActivityRecord

Objekt

Representerar en aktivitetspost för hämtning av Azure Blob-blobar.

Name	Typ	Description
azureBlobArguments	KnowledgeAgentAzureBlobActivityArguments	Azure Blob-argumenten för hämtningsaktiviteten.
count	integer (int32)	Antalet dokument som hämtats som var tillräckligt relevanta för att passera tröskelvärdet för omrankning.
elapsedMs	integer (int32)	Den förflutna tiden i millisekunder för hämtningsaktiviteten.
id	integer (int32)	ID för aktivitetsposten.
knowledgeSourceName	string	Kunskapskällan för hämtningsaktiviteten.
queryTime	string (date-time)	Frågetiden för den här hämtningsaktiviteten.
type	string: azureBlob	Typ av aktivitetspost.

KnowledgeAgentAzureBlobReference

Objekt

Representerar en Azure Blob Storage dokumentreferens.

Name	Typ	Description
activitySource	integer (int32)	Källaktivitets-ID:t för referensen.
blobUrl	string	Blob-URL:en för referensen.
id	string	ID för referensen.
rerankerScore	number (float)	Rankningspoängen för dokumentreferensen.
sourceData	object
type	string: azureBlob	Typen av referens.

KnowledgeAgentMessage

Objekt

Objektet för meddelandeformat på naturligt språk.

Name	Typ	Description
content	KnowledgeAgentMessageContent[]: KnowledgeAgentMessageImageContent[] KnowledgeAgentMessageTextContent[]	Anger typen av meddelandeinnehåll.
role	string	Rollen för verktygets svar.

KnowledgeAgentMessageContentType

Uppräkning

Typ av meddelandeinnehåll.

Värde	Description
text	Typ av textmeddelandeinnehåll.
image	Typ av innehåll i bildmeddelanden.

KnowledgeAgentMessageImageContent

Objekt

Typ av textmeddelande.

Name	Typ	Description
image	Image
type	string: image	Typ av meddelande

KnowledgeAgentMessageTextContent

Objekt

Typ av textmeddelande.

Name	Typ	Description
text	string
type	string: text	Typ av meddelande

KnowledgeAgentModelAnswerSynthesisActivityRecord

Objekt

Representerar en LLM-svarssyntesaktivitetspost.

Name	Typ	Description
elapsedMs	integer (int32)	Den förflutna tiden i millisekunder för hämtningsaktiviteten.
id	integer (int32)	ID för aktivitetsposten.
inputTokens	integer (int32)	Antalet indatatoken för LLM-svarssyntesaktiviteten.
outputTokens	integer (int32)	Antalet utdatatoken för LLM-svarssyntesaktiviteten.
type	string: modelAnswerSynthesis	Typ av aktivitetspost.

KnowledgeAgentModelQueryPlanningActivityRecord

Objekt

Representerar en LLM-frågeplaneringsaktivitetspost.

Name	Typ	Description
elapsedMs	integer (int32)	Den förflutna tiden i millisekunder för hämtningsaktiviteten.
id	integer (int32)	ID för aktivitetsposten.
inputTokens	integer (int32)	Antalet indatatoken för LLM-frågeplaneringsaktiviteten.
outputTokens	integer (int32)	Antalet utdatatoken för LLM-frågeplaneringsaktiviteten.
type	string: modelQueryPlanning	Typ av aktivitetspost.

KnowledgeAgentRetrievalRequest

Objekt

Indatakontraktet för hämtningsbegäran.

Name	Typ	Description
knowledgeSourceParams	KnowledgeSourceParams[]: SearchIndexKnowledgeSourceParams[]
messages	KnowledgeAgentMessage[]	Objektet för meddelandeformat på naturligt språk.

KnowledgeAgentRetrievalResponse

Objekt

Utdatakontraktet för hämtningssvaret.

Name	Typ	Description
activity	KnowledgeAgentActivityRecord[]: KnowledgeAgentAzureBlobActivityRecord[] KnowledgeAgentModelAnswerSynthesisActivityRecord[] KnowledgeAgentModelQueryPlanningActivityRecord[] KnowledgeAgentSearchIndexActivityRecord[] KnowledgeAgentSemanticRerankerActivityRecord[]	Aktivitetsposterna för att spåra förlopp och faktureringskonsekvenser.
references	KnowledgeAgentReference[]: KnowledgeAgentAzureBlobReference[] KnowledgeAgentSearchIndexReference[]	Referenserna för de hämtningsdata som används i svaret.
response	KnowledgeAgentMessage[]	Objektet för meddelandeformat på naturligt språk.

KnowledgeAgentSearchIndexActivityArguments

Objekt

Representerar de argument som sökindexhämtningsaktiviteten kördes med.

Name	Typ	Description
filter	string	Filtersträngen.
search	string	Söksträngen som används för att fråga sökindexet.

KnowledgeAgentSearchIndexActivityRecord

Objekt

Representerar en post för hämtningsaktivitet för sökindex.

Name	Typ	Description
count	integer (int32)	Antalet dokument som hämtats som var tillräckligt relevanta för att passera tröskelvärdet för omrankning.
elapsedMs	integer (int32)	Den förflutna tiden i millisekunder för hämtningsaktiviteten.
id	integer (int32)	ID för aktivitetsposten.
knowledgeSourceName	string	Kunskapskällan för hämtningsaktiviteten.
queryTime	string (date-time)	Frågetiden för den här hämtningsaktiviteten.
searchIndexArguments	KnowledgeAgentSearchIndexActivityArguments	Sökindexargumenten för hämtningsaktiviteten.
type	string: searchIndex	Typ av aktivitetspost.

KnowledgeAgentSearchIndexReference

Objekt

Representerar en referens för ett Azure Search-dokument.

Name	Typ	Description
activitySource	integer (int32)	Källaktivitets-ID:t för referensen.
docKey	string	Dokumentnyckeln för referensen.
id	string	ID för referensen.
rerankerScore	number (float)	Rankningspoängen för dokumentreferensen.
sourceData	object
type	string: searchIndex	Typen av referens.

KnowledgeAgentSemanticRerankerActivityRecord

Objekt

Representerar en semantisk rankningsaktivitetspost.

Name	Typ	Description
elapsedMs	integer (int32)	Den förflutna tiden i millisekunder för hämtningsaktiviteten.
id	integer (int32)	ID för aktivitetsposten.
inputTokens	integer (int32)	Antalet indatatoken för den semantiska rangordningsaktiviteten.
type	string: semanticReranker	Typ av aktivitetspost.

KnowledgeSourceKind

Uppräkning

Typen av kunskapskälla.

Värde	Description
searchIndex	En kunskapskälla som läser data från ett sökindex.
azureBlob	En kunskapskälla som läser och matar in data från Azure Blob Storage till ett sökindex.

SearchIndexKnowledgeSourceParams

Objekt

Anger körningsparametrar för en kunskapskälla för sökindex

Name	Typ	Description
filterAddOn	string	Ett filtervillkor som tillämpas på indexet (t.ex. "State eq VA").
kind	string: searchIndex	Typen av kunskapskälla.
knowledgeSourceName	string	Namnet på det index som parametrarna gäller för.