Knowledge Bases - Get

取得知識庫定義。

GET {endpoint}/knowledgebases('{knowledgeBaseName}')?api-version=2026-11-01-preview

URI 參數

名稱 位於 必要 類型 Description
endpoint
path True

string (uri)

搜尋服務的端點 URL。

knowledgeBaseName
path True

string

知識庫名稱。

api-version
query True

string

minLength: 1

用於此作業的 API 版本。

要求標頭

名稱 必要 類型 Description
x-ms-client-request-id

string (uuid)

要求不透明、全域唯一、用戶端產生的字串標識碼。

Accept

Accept

Accept 標頭。

回覆

名稱 類型 Description
200 OK

KnowledgeBase

要求已成功。

Other Status Codes

ErrorResponse

未預期的錯誤回應。

安全性

api-key

類型: apiKey
位於: header

OAuth2Auth

類型: oauth2
Flow: implicit
授權 URL: https://login.microsoftonline.com/common/oauth2/v2.0/authorize

範圍

名稱 Description
https://search.azure.com/.default

範例

SearchServiceGetKnowledgeBase
SearchServiceGetKnowledgeBaseMicrosoftRetriever1
SearchServiceGetKnowledgeBaseOpenAICompatible

SearchServiceGetKnowledgeBase

範例要求

GET https://typespecpreviewexampleservice.search.windows.net/knowledgebases('base-preview-test')?api-version=2026-11-01-preview


範例回覆

{
  "@odata.etag": "0x1234568AE7E58A1",
  "name": "base-preview-test",
  "description": "Description of the knowledge base.",
  "retrievalInstructions": "Instructions for retrieval for the knowledge base.",
  "answerInstructions": "Instructions for answer synthesis.",
  "outputMode": "extractiveData",
  "knowledgeSources": [
    {
      "name": "ks-preview-test"
    }
  ],
  "models": [
    {
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "https://test-sample.openai.azure.com",
        "deploymentId": "myDeployment",
        "apiKey": "<redacted>",
        "modelName": "gpt-4o-mini"
      }
    }
  ],
  "encryptionKey": {
    "keyVaultKeyName": "myUserManagedEncryptionKey-createdinAzureKeyVault",
    "keyVaultKeyVersion": "myKeyVersion-32charAlphaNumericString",
    "keyVaultUri": "https://myKeyVault.vault.azure.net",
    "isServiceLevelKey": false,
    "accessCredentials": {
      "applicationId": "00000000-0000-0000-0000-000000000000",
      "applicationSecret": "<applicationSecret>"
    }
  },
  "tags": {
    "businessUnit": "Contoso Engineering Department",
    "costCenter": "ABC-123",
    "owner": "Contoso"
  },
  "retrievalReasoningEffort": {
    "kind": "low"
  },
  "corsOptions": {
    "allowedOrigins": [
      "https://myapp.example.com"
    ],
    "maxAgeInSeconds": 300
  },
  "retrieveDefaults": {
    "maxRuntimeInSeconds": 45,
    "maxOutputDocuments": 8,
    "maxOutputSizeInTokens": 12000
  },
  "tools": [
    {
      "name": "product-search",
      "description": "Search product documentation.",
      "knowledgeSources": [
        {
          "name": "ks-preview-test",
          "alwaysQuerySource": false,
          "filterAddOn": "id ne null",
          "maxOutputDocuments": 50,
          "failOnError": true
        }
      ],
      "retrievalReasoningEffort": {
        "kind": "low"
      },
      "retrieveDefaults": {
        "maxRuntimeInSeconds": 30,
        "maxOutputDocuments": 2,
        "maxOutputSizeInTokens": 5000
      }
    }
  ]
}

SearchServiceGetKnowledgeBaseMicrosoftRetriever1

範例要求

GET https://typespecpreviewexampleservice.search.windows.net/knowledgebases('travel-knowledgebase')?api-version=2026-11-01-preview


範例回覆

{
  "name": "travel-knowledgebase",
  "knowledgeSources": [
    {
      "name": "hotels"
    }
  ],
  "models": [
    {
      "kind": "microsoftRetriever1"
    }
  ],
  "outputMode": "extractiveData",
  "description": "Find hotels using Microsoft Retriever 1."
}

SearchServiceGetKnowledgeBaseOpenAICompatible

範例要求

GET https://typespecpreviewexampleservice.search.windows.net/knowledgebases('compatible-model-preview-test')?api-version=2026-11-01-preview


範例回覆

{
  "@odata.etag": "0x1234568AE7E58A1",
  "name": "compatible-model-preview-test",
  "description": "Description of the knowledge base.",
  "retrievalInstructions": "Instructions for retrieval for the knowledge base.",
  "answerInstructions": "Instructions for answer synthesis.",
  "outputMode": "extractiveData",
  "knowledgeSources": [
    {
      "name": "ks-preview-test"
    }
  ],
  "models": [
    {
      "kind": "openAICompatible",
      "openAICompatibleParameters": {
        "uri": "https://model-gateway.contoso.com/teams/catalog/chat/completions?route=primary&api-version=2026-01-01",
        "modelName": "gpt-4.1-mini"
      }
    }
  ],
  "encryptionKey": {
    "keyVaultKeyName": "myUserManagedEncryptionKey-createdinAzureKeyVault",
    "keyVaultKeyVersion": "myKeyVersion-32charAlphaNumericString",
    "keyVaultUri": "https://myKeyVault.vault.azure.net",
    "isServiceLevelKey": false,
    "accessCredentials": {
      "applicationId": "00000000-0000-0000-0000-000000000000",
      "applicationSecret": "<applicationSecret>"
    }
  },
  "tags": {
    "businessUnit": "Contoso Engineering Department",
    "costCenter": "ABC-123",
    "owner": "Contoso"
  },
  "retrievalReasoningEffort": {
    "kind": "low"
  },
  "corsOptions": {
    "allowedOrigins": [
      "https://myapp.example.com"
    ],
    "maxAgeInSeconds": 300
  },
  "retrieveDefaults": {
    "maxRuntimeInSeconds": 45,
    "maxOutputDocuments": 8,
    "maxOutputSizeInTokens": 12000
  },
  "tools": [
    {
      "name": "product-search",
      "description": "Search product documentation.",
      "knowledgeSources": [
        {
          "name": "ks-preview-test",
          "alwaysQuerySource": false,
          "filterAddOn": "id ne null",
          "maxOutputDocuments": 50,
          "failOnError": true
        }
      ],
      "retrievalReasoningEffort": {
        "kind": "low"
      },
      "retrieveDefaults": {
        "maxRuntimeInSeconds": 30,
        "maxOutputDocuments": 2,
        "maxOutputSizeInTokens": 5000
      }
    }
  ]
}

定義

名稱 Description
Accept

Accept 標頭。

AzureOpenAIModelName

將呼叫的 Azure Open AI 模型名稱。

AzureOpenAIVectorizerParameters

指定連線到 Azure OpenAI 資源的參數。

CorsOptions

定義選項,以控制索引的跨原始來源資源分享 (CORS)。

ErrorAdditionalInfo

資源管理錯誤其他資訊。

ErrorDetail

錯誤詳細資料。

ErrorResponse

所有 Azure Resource Manager API 的常見錯誤回應,用於回傳失敗操作的錯誤細節。 (這也遵循 OData 錯誤回應格式。)。

KnowledgeBase

代表知識庫定義。

KnowledgeBaseAzureOpenAIModel

指定用來執行查詢規劃的 Azure OpenAI 資源。

KnowledgeBaseMicrosoftRetriever1Model

指定用於查詢規劃與檢索的 Microsoft Retriever 1。

KnowledgeBaseModelKind

要用於查詢規劃的 AI 模型。

KnowledgeBaseOpenAICompatibleModel

指定由客戶控制的 OpenAI 相容模型,用於知識庫檢索或簡約模式知識來源影像的語言化。 在擷取時,模型設定檔會選擇聊天完成或回應。 不支援標準/CU 擷取或包含 Web 知識來源的知識庫。

KnowledgeBaseOpenAICompatibleParameters

支援 OpenAI 的聊天完成或回應端點的連線參數。 建立時必須必須設定一個非空標頭或 managedIdentityAudience。 更新可以省略標頭,以保留未變更連線與模型設定檔的憑證。

KnowledgeBaseRetrieveDefaults

知識庫檢索請求的持續性全請求預設值。 每個值提供匹配的檢索-請求欄位的預設值;未設定時服務預設值適用,存在時優先執行請求時間值。

KnowledgeBaseTool

一個具名的檢索工具,包含客戶提供的描述及其部分知識庫來源。

KnowledgeBaseToolKnowledgeSourceReference

參考現有的知識來源及選定的持久擷取預設值子集,而非完整的請求時間參數模型。 參考來源決定其類型;儲存知識庫時,不相容的預設值會被拒絕。 明確的擷取請求值優先,但篩選器會與 AND 結合使用。

KnowledgeRetrievalAutoReasoningEffort

檢索時自動選擇推理努力。 服務會將每個請求放在最便宜的層級,並只會在需要時逐步升級,直到服務最高可用層級。

KnowledgeRetrievalLowReasoningEffort

以低推理工作量運行知識檢索。

KnowledgeRetrievalMediumReasoningEffort

以中等推理努力運行知識檢索。

KnowledgeRetrievalMinimalReasoningEffort

以最少的推理工作執行知識檢索。

KnowledgeRetrievalOutputMode

此擷取的輸出組態。

KnowledgeRetrievalReasoningEffortKind

擷取期間要使用的工作量。

KnowledgeSourceReference

參考知識來源。

SearchIndexerDataNoneIdentity

清除資料源的識別屬性。

SearchIndexerDataUserAssignedIdentity

指定要使用之數據源的身分識別。

SearchResourceEncryptionKey

Azure Key Vault 中客戶管理的加密密鑰。 您建立和管理的金鑰可用來加密或解密靜態資料,例如索引和同義字對映。

Accept

Accept 標頭。

值 Description
application/json;odata.metadata=minimal

AzureOpenAIModelName

將呼叫的 Azure Open AI 模型名稱。

值 Description
text-embedding-ada-002

TextEmbeddingAda002 模型。

text-embedding-3-large

TextEmbedding3Large 模型。

text-embedding-3-small

TextEmbedding3小型模型。

gpt-4o

Gpt4o 模型。

gpt-4o-mini

Gpt4oMini 型號。

gpt-4.1

GPT41 型號。

gpt-4.1-mini

Gpt41Mini 型號。

gpt-4.1-nano

Gpt41Nano 模型。

gpt-5

GPT5 型號。

gpt-5-mini

Gpt5Mini 型號。

gpt-5-nano

Gpt5Nano 模型。

gpt-5.1

GPT51 型號。

gpt-5.2

Gpt52 型號。

gpt-5.4

GPT54 型號。

gpt-5.4-mini

Gpt54Mini 型號。

gpt-5.4-nano

Gpt54Nano 模型。

gpt-5.5

Gpt55 型號。

gpt-5.6-sol

Gpt56Sol 模型。

gpt-5.6-terra

Gpt56Terra 型號。

gpt-5.6-luna

Gpt56Luna 型號。

gpt-6-astra

Gpt6Astra 型號。

gpt-6-sol

Gpt6Sol 模型。

gpt-6-luna

Gpt6Luna 模型。

gpt-6.1-sol

Gpt61Sol 模型。

AzureOpenAIVectorizerParameters

指定連線到 Azure OpenAI 資源的參數。

名稱 類型 Description
apiKey

string

所指定 Azure OpenAI 資源的 API 金鑰。

authIdentity SearchIndexerDataIdentity:

用於輸出連線的使用者指派受控識別。

deploymentId

string

指定資源上 Azure OpenAI 模型部署的識別碼。

modelName

AzureOpenAIModelName

在提供的 deploymentId 路徑上部署的內嵌模型名稱。

resourceUri

string (uri)

Azure OpenAI 資源的資源 URI。

CorsOptions

定義選項,以控制索引的跨原始來源資源分享 (CORS)。

名稱 類型 Description
allowedOrigins

string[]

JavaScript 程式碼將從中獲得索引存取權的來源清單。 可以包含 {protocol}://{fully-qualified-domain-name}[:{port#}] 形式的主機清單,或單一 '*' 以允許所有來源 (不建議)。

maxAgeInSeconds

integer (int64)

瀏覽器應快取 CORS 預檢回應的持續時間。 預設為 5 分鐘。

ErrorAdditionalInfo

資源管理錯誤其他資訊。

名稱 類型 Description
info

其他資訊。

type

string

其他信息類型。

ErrorDetail

錯誤詳細資料。

名稱 類型 Description
additionalInfo

ErrorAdditionalInfo[]

錯誤的其他資訊。

code

string

錯誤碼。

details

ErrorDetail[]

錯誤詳情

message

string

錯誤訊息。

target

string

錯誤目標。

ErrorResponse

所有 Azure Resource Manager API 的常見錯誤回應,用於回傳失敗操作的錯誤細節。 (這也遵循 OData 錯誤回應格式。)。

名稱 類型 Description
error

ErrorDetail

error 物件。

KnowledgeBase

代表知識庫定義。

名稱 類型 Description
@odata.etag

string

知識庫的 ETag。

answerInstructions

string

知識庫在產生答案時會考慮的指令。

corsOptions

CorsOptions

控制知識庫跨原點資源共享(CORS)的選項。

description

string

知識庫的描述。

encryptionKey

SearchResourceEncryptionKey

您在 Azure Key Vault 中建立的加密金鑰描述。

knowledgeSources

KnowledgeSourceReference[]

本知識庫所引用的知識來源。

models KnowledgeBaseModel[]:

包含有關如何連接到 AI 模型的配置選項。

name

string

知識庫名稱。

outputMode

KnowledgeRetrievalOutputMode

知識庫的輸出模式。

retrievalInstructions

string

知識庫在制定查詢計畫時會考慮的指示。

retrievalReasoningEffort KnowledgeRetrievalReasoningEffort:

檢索推理努力的配置。

retrieveDefaults

KnowledgeBaseRetrieveDefaults

此知識庫的請求範圍持續檢索預設值。 這些值適用於擷取省略對應欄位的請求;當有請求時間值時,請求時間值會優先。

tags

object

使用者定義的鍵值對,用於分類知識庫及其使用與成本。

tools

KnowledgeBaseTool[]

命名的檢索工具,每個工具僅限於此知識庫來源的子集。 設定完成後,MCP 除了內建的 knowledge_base_retrieve 工具外,還會宣傳這些工具,該工具會從完整知識庫擷取資料。 在此 API 版本中省略工具或提供空陣列會清除現有工具。

KnowledgeBaseAzureOpenAIModel

指定用來執行查詢規劃的 Azure OpenAI 資源。

名稱 類型 Description
azureOpenAIParameters

AzureOpenAIVectorizerParameters

Azure OpenAI 參數。

kind string:

azureOpenAI

要用於查詢規劃的 AI 模型。

KnowledgeBaseMicrosoftRetriever1Model

指定用於查詢規劃與檢索的 Microsoft Retriever 1。

名稱 類型 Description
kind string:

microsoftRetriever1

要用於查詢規劃的 AI 模型。

KnowledgeBaseModelKind

要用於查詢規劃的 AI 模型。

值 Description
azureOpenAI

使用 Azure Open AI 模型進行查詢規劃。

openAICompatible

使用客戶控制的 OpenAI 相容端點來擷取知識庫或進行知識來源影像的口述化。

microsoftRetriever1

使用 Microsoft Retriever 1 進行查詢規劃與檢索。

KnowledgeBaseOpenAICompatibleModel

指定由客戶控制的 OpenAI 相容模型,用於知識庫檢索或簡約模式知識來源影像的語言化。 在擷取時,模型設定檔會選擇聊天完成或回應。 不支援標準/CU 擷取或包含 Web 知識來源的知識庫。

名稱 類型 Description
kind string:

openAICompatible

要用於查詢規劃的 AI 模型。

openAICompatibleParameters

KnowledgeBaseOpenAICompatibleParameters

OpenAI 相容端點的連線與驗證參數。

KnowledgeBaseOpenAICompatibleParameters

支援 OpenAI 的聊天完成或回應端點的連線參數。 建立時必須必須設定一個非空標頭或 managedIdentityAudience。 更新可以省略標頭,以保留未變更連線與模型設定檔的憑證。

名稱 類型 Description
authIdentity SearchIndexerDataIdentity:

用於取得 managedIdentityAudience 權杖的使用者指派管理身份。 省略使用搜尋服務系統指派的識別碼。 僅允許與 managedIdentityAudience 合作。

headers

object (password)

非空儲存的 HTTP 標頭用於端點驗證。 名稱與數值皆為機密,且永遠不會在回應中回傳。 空白地圖無效。 與 managedIdentityAudience 及 authIdentity 互斥。 更新時,省略標頭僅保留在同一資源與模型綁定上,且端點、模型設定檔及驗證身份未變;否則,請提供新的憑證。

managedIdentityAudience

string

客戶第三方 Microsoft Entra 應用程式用於管理身份驗證的純標準應用程式 GUID。 請勿包含 api:// 前綴或 /.default 後綴。 互斥且標頭。

modelName

AzureOpenAIModelName

一個支援的聊天模式名稱,用以決定搜尋的功能與限制。 對於知識來源影像的口述,此會作為請求主體中的模型選擇器傳送;URI 路徑會獨立於此名稱之外選取聊天完成或回應。 在知識庫檢索方面,GPT-6 模型檔案使用 Responses,現有模型檔案則使用 Chat Completions;端點必須支援所選協定,包括回應的無狀態工具延續。 擷取請求主體省略模型;URI 或閘道器選擇實際模型並提供所需的提供者模型識別碼。 不支援嵌入模型與任意提供者協定。

uri

string (uri)

完整的 HTTPS POST URL,包括路徑與查詢參數。 未附加路徑或 API 版本而未更改傳送;不會執行重定向。 若要擷取知識庫,端點必須接受模型檔案的聊天完成或回應協定。 對於知識來源影像的口述化,URI 路徑必須以 /chat/completions 或 /response 結尾;查詢參數不會選擇協定。

KnowledgeBaseRetrieveDefaults

知識庫檢索請求的持續性全請求預設值。 每個值提供匹配的檢索-請求欄位的預設值;未設定時服務預設值適用,存在時優先執行請求時間值。

名稱 類型 Description
maxOutputDocuments

integer (int32)

預設最大文件數為擷取輸出。

maxOutputSizeInTokens

integer (int32)

擷取輸出中內容的預設最大大小(以標記為單位)。

maxRuntimeInSeconds

integer (int32)

取回請求的預設最大執行時間(秒數)。

KnowledgeBaseTool

一個具名的檢索工具,包含客戶提供的描述及其部分知識庫來源。

名稱 類型 Description
description

string

minLength: 1
maxLength: 1024

非空說明工具使用時間,最多 1024 個字元。 在 MCP 目錄中逐字刊登廣告。

knowledgeSources

KnowledgeBaseToolKnowledgeSourceReference[]

一個非空的唯一來源參照清單。 每個來源都必須屬於知識庫。 不同的工具可能會引用同一個來源。

name

string

minLength: 2
maxLength: 64
pattern: ^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])$

獨特且區分大小寫的工具名稱。 包含 2 至 64 個小寫 ASCII 字母、數字或連字號,且不包含前尾連字號。

retrievalReasoningEffort KnowledgeRetrievalReasoningEffort:

會覆寫知識庫對此工具的推理工作。 明確的擷取請求值優先。

retrieveDefaults

KnowledgeBaseRetrieveDefaults

擷取覆蓋此工具知識庫預設值的預設值。 明確的擷取請求值優先。

KnowledgeBaseToolKnowledgeSourceReference

參考現有的知識來源及選定的持久擷取預設值子集,而非完整的請求時間參數模型。 參考來源決定其類型;儲存知識庫時,不相容的預設值會被拒絕。 明確的擷取請求值優先,但篩選器會與 AND 結合使用。

名稱 類型 Description
alwaysQuerySource

boolean

是否必須查詢來源。 不支援 MCP 伺服器來源。 明確的請求排除優先權。

failOnError

boolean

若此來源遇到錯誤,是否應失敗擷取。

filterAddOn

string

額外的 OData 篩選器用於搜尋索引來源。 儲存知識庫時,因不支援的來源類型而被拒絕。 搭配來源與請求篩選器,搭配 AND 進行。

maxOutputDocuments

integer (int32)

minimum: 50
maximum: 200

從此來源擷取的文件最大數量介於 50 到 200 件之間。

name

string

minLength: 1

知識庫中知識來源的名稱。

rerankerThreshold

number (float)

退回文件的最低重新排名分數。 需要啟用重新排序功能。

KnowledgeRetrievalAutoReasoningEffort

檢索時自動選擇推理努力。 服務會將每個請求放在最便宜的層級,並只會在需要時逐步升級,直到服務最高可用層級。

名稱 類型 Description
kind string:

auto

那種推理努力。

KnowledgeRetrievalLowReasoningEffort

以低推理工作量運行知識檢索。

名稱 類型 Description
kind string:

low

那種推理努力。

KnowledgeRetrievalMediumReasoningEffort

以中等推理努力運行知識檢索。

名稱 類型 Description
kind string:

medium

那種推理努力。

KnowledgeRetrievalMinimalReasoningEffort

以最少的推理工作執行知識檢索。

名稱 類型 Description
kind string:

minimal

那種推理努力。

KnowledgeRetrievalOutputMode

此擷取的輸出組態。

值 Description
extractiveData

直接從知識來源傳回資料,無需生成式變更。

answerSynthesis

合成回應承載的答案。

KnowledgeRetrievalReasoningEffortKind

擷取期間要使用的工作量。

值 Description
minimal

不會執行任何來源選取、查詢規劃或反覆搜尋。

low

在檢索期間使用低推理。

medium

在檢索過程中使用適量的推理。

auto

在取回時自動選擇推理努力,從最低層級逐步升級到所需程度。

KnowledgeSourceReference

參考知識來源。

名稱 類型 Description
enableFreshness

boolean

指示是否應啟用此知識來源的新鮮度感知檢索。 當為真時,檢索時會套用新鮮度評分輪廓,以偏向較新文件的結果。

enableImageServing

boolean

指示是否應啟用此知識來源的影像服務。 若屬實,擷取過程中擷取的影像會在查詢時傳送至下游模型。

name

string

知識來源的名稱。

SearchIndexerDataNoneIdentity

清除資料源的識別屬性。

名稱 類型 Description
@odata.type string:

#Microsoft.Azure.Search.DataNoneIdentity

指定身分類型的 URI 片段。

SearchIndexerDataUserAssignedIdentity

指定要使用之數據源的身分識別。

名稱 類型 Description
@odata.type string:

#Microsoft.Azure.Search.DataUserAssignedIdentity

指定身分類型的 URI 片段。

federatedIdentityClientId

string

多租戶 User-Assigned 受管理身份支援:多重帳篷應用程式的用戶端 ID,已設定與使用者指派的受管理身份聯合。

userAssignedIdentity

string

使用者指派受控識別的完整 Azure 資源標識符,通常格式為 “/subscriptions/12345678-1234-1234-1234-1234567890ab/resourceGroups/rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myId”。

SearchResourceEncryptionKey

Azure Key Vault 中客戶管理的加密密鑰。 您建立和管理的金鑰可用來加密或解密靜態資料,例如索引和同義字對映。

名稱 類型 預設值 Description
accessCredentials.applicationId

string

AAD 應用程式識別碼,已將待用數據加密時要使用的 Azure Key Vault 所需訪問許可權授與。 應用程式標識碼不應與 AAD 應用程式的物件標識元混淆。

accessCredentials.applicationSecret

string

指定 AAD 應用程式的驗證金鑰。

identity SearchIndexerDataIdentity:

要用於此加密金鑰的明確受控識別。 如果未指定,且存取認證屬性為 Null,則會使用系統指派的受控識別。 更新資源時,如果未指定明確識別,則會維持不變。 如果指定了 「none」 ,則會清除此屬性的值。

isServiceLevelKey

boolean

False

一個可選值,用以指示此鍵是否為服務層級鍵。 預設值為 false。

keyVaultKeyName

string

要用來加密待用數據的 Azure Key Vault 金鑰名稱。

keyVaultKeyVersion

string

要用來加密待用數據的 Azure Key Vault 金鑰版本。

keyVaultUri

string

Azure Key Vault 的 URI,也稱為 DNS 名稱,其中包含用來加密待用數據的密鑰。 範例 URI 可能會 https://my-keyvault-name.vault.azure.net。