Knowledge Retrieval - Retrieve

Hizmet:: Search Service

API Sürümü:: 2025-08-01-preview

KnowledgeAgent, yedekleme depolarından ilgili verileri alır.

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

URI Parametreleri

Name	İçinde	Gerekli	Tür	Description
agentName	path	True	string	Aracının adı.
endpoint	path	True	string (url)	Arama hizmetinin uç nokta URL'si.
api-version	query	True	string	İstemci API sürümü.

İstek Başlığı

Name	Gerekli	Tür	Description
x-ms-client-request-id		string (uuid)	Hata ayıklamaya yardımcı olmak için istekle birlikte gönderilen izleme kimliği.
x-ms-query-source-authorization		string	Sorgunun yürütüldüğü kullanıcıyı tanımlayan belirteç. Bu belirteç, belgelerde güvenlik kısıtlamalarını zorlamak için kullanılır.

İstek Gövdesi

Name	Gerekli	Tür	Description
messages	True	KnowledgeAgentMessage[]	Doğal dil ileti stili nesnesi.
knowledgeSourceParams		KnowledgeSourceParams[]: SearchIndexKnowledgeSourceParams[]

Yanıtlar

Name	Tür	Description
200 OK	KnowledgeAgentRetrievalResponse	Alma yanıtı başarıyla döndürülür.
Other Status Codes	ErrorResponse	Hata yanıtı.

Örnekler

KnowledgeAgentRetrieve

Örnek isteği

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

Örnek yanıt

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

Tanımlar

Name	Description
ErrorAdditionalInfo	Kaynak yönetimi hatası ek bilgileri.
ErrorDetail	Hata ayrıntısı.
ErrorResponse	Hata yanıtı
Image
KnowledgeAgentAzureBlobActivityArguments	Azure blob alma etkinliğinin çalıştırıldığı bağımsız değişkenleri temsil eder.
KnowledgeAgentAzureBlobActivityRecord	Azure blob alma etkinliği kaydını temsil eder.
KnowledgeAgentAzureBlobReference	Azure Blob Depolama belge başvurusunu temsil eder.
KnowledgeAgentMessage	Doğal dil ileti stili nesnesi.
KnowledgeAgentMessageContentType	İleti içeriğinin türü.
KnowledgeAgentMessageImageContent	Kısa mesaj türü.
KnowledgeAgentMessageTextContent	Kısa mesaj türü.
KnowledgeAgentModelAnswerSynthesisActivityRecord	Bir LLM yanıt sentezi etkinlik kaydını temsil eder.
KnowledgeAgentModelQueryPlanningActivityRecord	Bir LLM sorgu planlama etkinliği kaydını temsil eder.
KnowledgeAgentRetrievalRequest	Alma isteği için giriş sözleşmesi.
KnowledgeAgentRetrievalResponse	Alma yanıtı için çıkış sözleşmesi.
KnowledgeAgentSearchIndexActivityArguments	Arama dizini alma etkinliğinin çalıştırıldığı bağımsız değişkenleri temsil eder.
KnowledgeAgentSearchIndexActivityRecord	Bir arama dizini alma etkinliği kaydını temsil eder.
KnowledgeAgentSearchIndexReference	Bir Azure Search belge başvurusunu temsil eder.
KnowledgeAgentSemanticRerankerActivityRecord	Anlamsal sıralayıcı etkinlik kaydını temsil eder.
KnowledgeSourceKind	Bilgi kaynağının türü.
SearchIndexKnowledgeSourceParams	Arama dizini bilgi kaynağı için çalışma zamanı parametrelerini belirtir

ErrorAdditionalInfo

Nesne

Kaynak yönetimi hatası ek bilgileri.

Name	Tür	Description
info	object	Ek bilgiler.
type	string	Ek bilgi türü.

ErrorDetail

Nesne

Hata ayrıntısı.

Name	Tür	Description
additionalInfo	ErrorAdditionalInfo[]	Hata ek bilgileri.
code	string	Hata kodu.
details	ErrorDetail[]	Hata ayrıntıları.
message	string	Hata iletisi.
target	string	Hata hedefi.

ErrorResponse

Nesne

Hata yanıtı

Name	Tür	Description
error	ErrorDetail	Hata nesnesi.

Image

Nesne

Name	Tür	Description
url	string (uri)	Resmin URL'si.

KnowledgeAgentAzureBlobActivityArguments

Nesne

Azure blob alma etkinliğinin çalıştırıldığı bağımsız değişkenleri temsil eder.

Name	Tür	Description
search	string	Blob içeriğini sorgulamak için kullanılan arama dizesi.

KnowledgeAgentAzureBlobActivityRecord

Nesne

Azure blob alma etkinliği kaydını temsil eder.

Name	Tür	Description
azureBlobArguments	KnowledgeAgentAzureBlobActivityArguments	Alma etkinliği için azure blob bağımsız değişkenleri.
count	integer (int32)	Yeniden sıralama eşiğini geçmek için yeterince alakalı olan alınan belgelerin sayısı.
elapsedMs	integer (int32)	Alma etkinliği için milisaniye cinsinden geçen süre.
id	integer (int32)	Etkinlik kaydının kimliği.
knowledgeSourceName	string	Alma etkinliği için bilgi kaynağı.
queryTime	string (date-time)	Bu alma etkinliği için sorgu süresi.
type	string: azureBlob	Etkinlik kaydının türü.

KnowledgeAgentAzureBlobReference

Nesne

Azure Blob Depolama belge başvurusunu temsil eder.

Name	Tür	Description
activitySource	integer (int32)	Başvuru için kaynak etkinlik kimliği.
blobUrl	string	Başvuru için blob URL'si.
id	string	Başvurunun kimliği.
rerankerScore	number (float)	Belge referansı için yeniden sıralayıcı puanı.
sourceData	object
type	string: azureBlob	Başvurunun türü.

KnowledgeAgentMessage

Nesne

Doğal dil ileti stili nesnesi.

Name	Tür	Description
content	KnowledgeAgentMessageContent[]: KnowledgeAgentMessageImageContent[] KnowledgeAgentMessageTextContent[]	İleti içeriğinin türünü belirtir.
role	string	Araç yanıtının rolü.

KnowledgeAgentMessageContentType

Numaralandırma

İleti içeriğinin türü.

Değer	Description
text	Kısa mesaj içerik türü.
image	Resimli mesaj içerik türü.

KnowledgeAgentMessageImageContent

Nesne

Kısa mesaj türü.

Name	Tür	Description
image	Image
type	string: image	Mesajın türü

KnowledgeAgentMessageTextContent

Nesne

Kısa mesaj türü.

Name	Tür	Description
text	string
type	string: text	Mesajın türü

KnowledgeAgentModelAnswerSynthesisActivityRecord

Nesne

Bir LLM yanıt sentezi etkinlik kaydını temsil eder.

Name	Tür	Description
elapsedMs	integer (int32)	Alma etkinliği için milisaniye cinsinden geçen süre.
id	integer (int32)	Etkinlik kaydının kimliği.
inputTokens	integer (int32)	LLM yanıt sentezi etkinliği için giriş belirteçlerinin sayısı.
outputTokens	integer (int32)	LLM yanıt sentezi etkinliği için çıktı belirteçlerinin sayısı.
type	string: modelAnswerSynthesis	Etkinlik kaydının türü.

KnowledgeAgentModelQueryPlanningActivityRecord

Nesne

Bir LLM sorgu planlama etkinliği kaydını temsil eder.

Name	Tür	Description
elapsedMs	integer (int32)	Alma etkinliği için milisaniye cinsinden geçen süre.
id	integer (int32)	Etkinlik kaydının kimliği.
inputTokens	integer (int32)	LLM sorgu planlama etkinliği için giriş belirteçlerinin sayısı.
outputTokens	integer (int32)	LLM sorgu planlama etkinliği için çıktı belirteçlerinin sayısı.
type	string: modelQueryPlanning	Etkinlik kaydının türü.

KnowledgeAgentRetrievalRequest

Nesne

Alma isteği için giriş sözleşmesi.

Name	Tür	Description
knowledgeSourceParams	KnowledgeSourceParams[]: SearchIndexKnowledgeSourceParams[]
messages	KnowledgeAgentMessage[]	Doğal dil ileti stili nesnesi.

KnowledgeAgentRetrievalResponse

Nesne

Alma yanıtı için çıkış sözleşmesi.

Name	Tür	Description
activity	KnowledgeAgentActivityRecord[]: KnowledgeAgentAzureBlobActivityRecord[] KnowledgeAgentModelAnswerSynthesisActivityRecord[] KnowledgeAgentModelQueryPlanningActivityRecord[] KnowledgeAgentSearchIndexActivityRecord[] KnowledgeAgentSemanticRerankerActivityRecord[]	İlerlemeyi ve faturalandırma etkilerini izlemek için etkinlik kayıtları.
references	KnowledgeAgentReference[]: KnowledgeAgentAzureBlobReference[] KnowledgeAgentSearchIndexReference[]	Yanıtta kullanılan alma verileri için başvurular.
response	KnowledgeAgentMessage[]	Doğal dil ileti stili nesnesi.

KnowledgeAgentSearchIndexActivityArguments

Nesne

Arama dizini alma etkinliğinin çalıştırıldığı bağımsız değişkenleri temsil eder.

Name	Tür	Description
filter	string	Filtre dizesi.
search	string	Arama dizinini sorgulamak için kullanılan arama dizesi.

KnowledgeAgentSearchIndexActivityRecord

Nesne

Bir arama dizini alma etkinliği kaydını temsil eder.

Name	Tür	Description
count	integer (int32)	Yeniden sıralama eşiğini geçmek için yeterince alakalı olan alınan belgelerin sayısı.
elapsedMs	integer (int32)	Alma etkinliği için milisaniye cinsinden geçen süre.
id	integer (int32)	Etkinlik kaydının kimliği.
knowledgeSourceName	string	Alma etkinliği için bilgi kaynağı.
queryTime	string (date-time)	Bu alma etkinliği için sorgu süresi.
searchIndexArguments	KnowledgeAgentSearchIndexActivityArguments	Arama dizini, alma etkinliği için bağımsız değişkenler oluşturur.
type	string: searchIndex	Etkinlik kaydının türü.

KnowledgeAgentSearchIndexReference

Nesne

Bir Azure Search belge başvurusunu temsil eder.

Name	Tür	Description
activitySource	integer (int32)	Başvuru için kaynak etkinlik kimliği.
docKey	string	Başvuru için belge anahtarı.
id	string	Başvurunun kimliği.
rerankerScore	number (float)	Belge referansı için yeniden sıralayıcı puanı.
sourceData	object
type	string: searchIndex	Başvurunun türü.

KnowledgeAgentSemanticRerankerActivityRecord

Nesne

Anlamsal sıralayıcı etkinlik kaydını temsil eder.

Name	Tür	Description
elapsedMs	integer (int32)	Alma etkinliği için milisaniye cinsinden geçen süre.
id	integer (int32)	Etkinlik kaydının kimliği.
inputTokens	integer (int32)	Anlamsal sıralayıcı etkinliği için giriş belirteçlerinin sayısı.
type	string: semanticReranker	Etkinlik kaydının türü.

KnowledgeSourceKind

Numaralandırma

Bilgi kaynağının türü.

Değer	Description
searchIndex	Bir Arama Dizini'nden veri okuyan bir bilgi kaynağı.
azureBlob	Azure Blob Depolama'dan bir Arama Dizini'ne veri okuyan ve alan bir bilgi kaynağı.

SearchIndexKnowledgeSourceParams

Nesne

Arama dizini bilgi kaynağı için çalışma zamanı parametrelerini belirtir

Name	Tür	Description
filterAddOn	string	Dizine uygulanan bir filtre koşulu (ör. "State eq VA").
kind	string: searchIndex	Bilgi kaynağının türü.
knowledgeSourceName	string	Parametrelerin uygulandığı dizinin adı.