Knowledge Bases - Create Or Update

服務:: Search Service

API 版本:: 2026-04-01

建立新的知識庫，或如果已有的知識庫會更新。

PUT {endpoint}/knowledgebases('{knowledgeBaseName}')?api-version=2026-04-01

URI 參數

名稱	位於	必要	類型	Description
endpoint	path	True	string (uri)	搜尋服務的端點 URL。
knowledgeBaseName	path	True	string	知識庫名稱。
api-version	query	True	string minLength: 1	用於此作業的 API 版本。

要求標頭

名稱	必要	類型	Description
Accept		Accept	接受標頭。
If-Match		string	定義 If-Match 條件。只有在伺服器上的 ETag 符合此值時，才會執行作業。
If-None-Match		string	定義 If-None-Match 條件。只有在伺服器上的 ETag 不符合此值時，才會執行作業。
Prefer	True	Prefer	針對 HTTP PUT 要求，指示服務在成功時傳回建立/更新的資源。
x-ms-client-request-id		string (uuid)	一個不透明、全域唯一、由客戶端產生的請求字串識別碼。

要求本文

名稱	必要	類型	Description
knowledgeSources	True	KnowledgeSourceReference[]	本知識庫所引用的知識來源。
name	True	string	知識庫名稱。
@odata.etag		string	知識庫的 ETag。
description		string	知識庫的描述。
encryptionKey		SearchResourceEncryptionKey	您在 Azure Key Vault 中建立的加密金鑰描述。
models		KnowledgeBaseModel[]: KnowledgeBaseAzureOpenAIModel[]	包含有關如何連接到 AI 模型的配置選項。

回應

名稱	類型	Description
200 OK	KnowledgeBase	要求已成功。
201 Created	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

範例

SearchServiceCreateOrUpdateKnowledgeBase

範例要求

HTTP

PUT https://exampleservice.search.windows.net/knowledgebases('base-example-index')?api-version=2026-04-01





{
  "name": "base-example-index",
  "knowledgeSources": [
    {
      "name": "ks-example-index"
    }
  ],
  "models": [
    {
      "azureOpenAIParameters": {
        "resourceUri": "https://test-sample.openai.azure.com/",
        "deploymentId": "myDeployment",
        "apiKey": "api-key",
        "modelName": "gpt-5-nano"
      },
      "kind": "azureOpenAI"
    }
  ],
  "@odata.etag": "0x1234568AE7E58A1",
  "encryptionKey": {
    "keyVaultKeyName": "myUserManagedEncryptionKey-createdinAzureKeyVault",
    "keyVaultKeyVersion": "myKeyVersion-32charAlphaNumericString",
    "keyVaultUri": "https://myKeyVault.vault.azure.net",
    "accessCredentials": {
      "applicationId": "00000000-0000-0000-0000-000000000000",
      "applicationSecret": "<applicationSecret>"
    }
  },
  "description": "Description of the knowledge base."
}

範例回覆

狀態碼:: 200

{
  "@odata.etag": "0x1234568AE7E58A1",
  "name": "base-example-index",
  "description": "Description of the knowledge base.",
  "knowledgeSources": [
    {
      "name": "ks-example-index"
    }
  ],
  "models": [
    {
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "https://test-sample.openai.azure.com/",
        "deploymentId": "myDeployment",
        "apiKey": "api-key",
        "modelName": "gpt-5-nano"
      }
    }
  ],
  "encryptionKey": {
    "keyVaultKeyName": "myUserManagedEncryptionKey-createdinAzureKeyVault",
    "keyVaultKeyVersion": "myKeyVersion-32charAlphaNumericString",
    "keyVaultUri": "https://myKeyVault.vault.azure.net",
    "accessCredentials": {
      "applicationId": "00000000-0000-0000-0000-000000000000",
      "applicationSecret": "<applicationSecret>"
    }
  }
}

狀態碼:: 201

{
  "@odata.etag": "0x1234568AE7E58A1",
  "name": "base-example-index",
  "description": "Description of the knowledge base.",
  "knowledgeSources": [
    {
      "name": "ks-example-index"
    }
  ],
  "models": [
    {
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "https://test-sample.openai.azure.com/",
        "deploymentId": "myDeployment",
        "apiKey": "api-key",
        "modelName": "gpt-5-nano"
      }
    }
  ],
  "encryptionKey": {
    "keyVaultKeyName": "myUserManagedEncryptionKey-createdinAzureKeyVault",
    "keyVaultKeyVersion": "myKeyVersion-32charAlphaNumericString",
    "keyVaultUri": "https://myKeyVault.vault.azure.net",
    "accessCredentials": {
      "applicationId": "00000000-0000-0000-0000-000000000000",
      "applicationSecret": "<applicationSecret>"
    }
  }
}

定義

名稱	Description
Accept	接受標頭。
AzureOpenAIModelName	將呼叫的 Azure Open AI 模型名稱。
AzureOpenAIVectorizerParameters	指定連線到 Azure OpenAI 資源的參數。
ErrorAdditionalInfo	資源管理錯誤附加資訊。
ErrorDetail	錯誤詳細資料。
ErrorResponse	所有 Azure Resource Manager API 的常見錯誤回應，用於回傳失敗操作的錯誤細節。（這也遵循 OData 錯誤回應格式。）。
KnowledgeBase	代表知識庫定義。
KnowledgeBaseAzureOpenAIModel	指定用來執行查詢規劃的 Azure OpenAI 資源。
KnowledgeBaseModelKind	要用於查詢規劃的 AI 模型。
KnowledgeSourceReference	參考知識來源。
Prefer	針對 HTTP PUT 要求，指示服務在成功時傳回建立/更新的資源。
SearchIndexerDataNoneIdentity	清除資料源的識別屬性。
SearchIndexerDataUserAssignedIdentity	指定要使用之數據源的身分識別。
SearchResourceEncryptionKey	Azure Key Vault 中客戶管理的加密密鑰。您建立和管理的金鑰可用來加密或解密靜態資料，例如索引和同義字對映。

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-5-mini	Gpt5Mini 型號。
gpt-5-nano	Gpt5Nano 模型。
gpt-5.4-mini	Gpt54Mini 型號。
gpt-5.4-nano	Gpt54Nano 模型。

AzureOpenAIVectorizerParameters

Object

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

名稱	類型	Description
apiKey	string	所指定 Azure OpenAI 資源的 API 金鑰。
authIdentity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	用於輸出連線的使用者指派受控識別。
deploymentId	string	指定資源上 Azure OpenAI 模型部署的識別碼。
modelName	AzureOpenAIModelName	在提供的 deploymentId 路徑上部署的內嵌模型名稱。
resourceUri	string (uri)	Azure OpenAI 資源的資源 URI。

ErrorAdditionalInfo

Object

資源管理錯誤附加資訊。

名稱	類型	Description
info		附加資訊。
type	string	其他資訊類型。

ErrorDetail

Object

錯誤詳細資料。

名稱	類型	Description
additionalInfo	ErrorAdditionalInfo[]	錯誤附加資訊。
code	string	錯誤碼。
details	ErrorDetail[]	錯誤詳情
message	string	錯誤訊息。
target	string	錯誤目標。

ErrorResponse

Object

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

名稱	類型	Description
error	ErrorDetail	錯誤物件。

KnowledgeBase

Object

代表知識庫定義。

名稱	類型	Description
@odata.etag	string	知識庫的 ETag。
description	string	知識庫的描述。
encryptionKey	SearchResourceEncryptionKey	您在 Azure Key Vault 中建立的加密金鑰描述。
knowledgeSources	KnowledgeSourceReference[]	本知識庫所引用的知識來源。
models	KnowledgeBaseModel[]: KnowledgeBaseAzureOpenAIModel[]	包含有關如何連接到 AI 模型的配置選項。
name	string	知識庫名稱。

KnowledgeBaseAzureOpenAIModel

Object

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

名稱	類型	Description
azureOpenAIParameters	AzureOpenAIVectorizerParameters	Azure OpenAI 參數。
kind	string: azureOpenAI	要用於查詢規劃的 AI 模型。

KnowledgeBaseModelKind

列舉型別

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

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

KnowledgeSourceReference

Object

參考知識來源。

名稱	類型	Description
name	string	知識來源的名稱。

Prefer

列舉型別

針對 HTTP PUT 要求，指示服務在成功時傳回建立/更新的資源。

值	Description
return=representation

SearchIndexerDataNoneIdentity

Object

清除資料源的識別屬性。

名稱	類型	Description
@odata.type	string: #Microsoft.Azure.Search.DataNoneIdentity	指定身分類型的 URI 片段。

SearchIndexerDataUserAssignedIdentity

Object

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

名稱	類型	Description
@odata.type	string: #Microsoft.Azure.Search.DataUserAssignedIdentity	指定身分類型的 URI 片段。
userAssignedIdentity	string	使用者指派受控識別的完整 Azure 資源標識符，通常格式為 “/subscriptions/12345678-1234-1234-1234-1234567890ab/resourceGroups/rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myId”。

SearchResourceEncryptionKey

Object

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

名稱	類型	Description
accessCredentials.applicationId	string	AAD 應用程式識別碼，已將待用數據加密時要使用的 Azure Key Vault 所需訪問許可權授與。應用程式標識碼不應與 AAD 應用程式的物件標識元混淆。
accessCredentials.applicationSecret	string	指定 AAD 應用程式的驗證金鑰。
identity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	要用於此加密金鑰的明確受控識別。如果未指定，且存取認證屬性為 Null，則會使用系統指派的受控識別。更新資源時，如果未指定明確識別，則會維持不變。如果指定了「none」，則會清除此屬性的值。
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`。