Knowledge Retrieval - Retrieve

Hizmet:: Search Service

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

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

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

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

Örnek yanıt

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

Tanımlar

Name	Description
ErrorAdditionalInfo	Kaynak yönetimi hatası ek bilgileri.
ErrorDetail	Hata ayrıntısı.
ErrorResponse	Hata yanıtı
Image
KnowledgeAgentAzureSearchDocReference	Bir Azure Search belge başvurusunu temsil eder.
KnowledgeAgentIndexParams
KnowledgeAgentMessage	Doğal dil ileti stili nesnesi.
KnowledgeAgentMessageContentType	İleti içeriğinin türü.
KnowledgeAgentMessageImageContent	Metin iletisi türü.
KnowledgeAgentMessageTextContent	Metin iletisi türü.
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.
KnowledgeAgentSearchActivityRecord	Bir alma etkinliği kaydını temsil eder.
KnowledgeAgentSemanticRankerActivityRecord	Anlamsal sıralayıcı etkinlik kaydını temsil eder.
Query	Alma etkinliği için sorgu ayrıntıları.

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	Resmin URL'si.

KnowledgeAgentAzureSearchDocReference

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.
sourceData	object
type	string: AzureSearchDoc	Başvurunun türü.

KnowledgeAgentIndexParams

Nesne

Name	Tür	Description
filterAddOn	string	Dizine uygulanan bir filtre koşulu (ör. "State eq VA").
includeReferenceSourceData	boolean	Başvuru kaynağı verilerinin dahil edilip edilmeyeceğini belirtir.
indexName	string	Parametrelerin uygulandığı dizinin adı.
maxDocsForReranker	integer (int32)	Sıralama için dikkate alınan belge sayısını sınırlar.
rerankerThreshold	number (float) minimum: 0 maximum: 4	Sonuçları yeniden sıralamak için bir eşik (aralık: 0-4).

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

Metin iletisi türü.

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

KnowledgeAgentMessageTextContent

Nesne

Metin iletisi türü.

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

KnowledgeAgentModelQueryPlanningActivityRecord

Nesne

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

Name	Tür	Description
elapsedMs	integer (int32)	Model 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
messages	KnowledgeAgentMessage[]	Doğal dil ileti stili nesnesi.
targetIndexParams	KnowledgeAgentIndexParams[]

KnowledgeAgentRetrievalResponse

Nesne

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

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

KnowledgeAgentSearchActivityRecord

Nesne

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

Name	Tür	Description
count	integer (int32)	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.
query	Query	Alma etkinliği için sorgu ayrıntıları.
queryTime	string (date-time)	Bu alma etkinliğinin sorgu zamanı.
targetIndex	string	Alma etkinliği için hedef dizin.
type	string: AzureSearchQuery	Etkinlik kaydının türü.

KnowledgeAgentSemanticRankerActivityRecord

Nesne

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

Name	Tür	Description
elapsedMs	integer (int32)	Model 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: AzureSearchSemanticRanker	Etkinlik kaydının türü.

Query

Nesne

Alma etkinliği için sorgu ayrıntıları.

Name	Tür	Description
filter	string	Filtre dizesi.
search	string	Arama dizesi.