Knowledge Bases - Create

服務:: Search Service

API 版本:: 2026-05-01-preview

建立新的知識庫。

POST {endpoint}/knowledgebases?api-version=2026-05-01-preview

URI 參數

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

要求標頭

名稱	必要	類型	Description
Accept		Accept	接受標頭。
x-ms-client-request-id		string (uuid)	要求不透明、全域唯一、用戶端產生的字串標識碼。

要求本文

名稱	必要	類型	Description
knowledgeSources	True	KnowledgeSourceReference[]	本知識庫所引用的知識來源。
name	True	string	知識庫名稱。
@odata.etag		string	知識庫的 ETag。
answerInstructions		string	知識庫在產生答案時會考慮的指令。
corsOptions		CorsOptions	控制知識庫跨原點資源共享（CORS）的選項。
description		string	知識庫的描述。
encryptionKey		SearchResourceEncryptionKey	您在 Azure Key Vault 中建立的加密金鑰描述。
models		KnowledgeBaseModel[]: KnowledgeBaseAzureOpenAIModel[]	包含有關如何連接到 AI 模型的配置選項。
outputMode		KnowledgeRetrievalOutputMode	知識庫的輸出模式。
retrievalInstructions		string	知識庫在制定查詢計畫時會考慮的指示。
retrievalReasoningEffort		KnowledgeRetrievalReasoningEffort: KnowledgeRetrievalLowReasoningEffort KnowledgeRetrievalMediumReasoningEffort KnowledgeRetrievalMinimalReasoningEffort	檢索推理努力的配置。

回應

名稱	類型	Description
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

範例

SearchServiceCreateKnowledgeBase

範例要求

HTTP

POST https://previewexampleservice.search.windows.net/knowledgebases?api-version=2026-05-01-preview


{
  "name": "base-preview-test",
  "knowledgeSources": [
    {
      "name": "ks-preview-test"
    }
  ],
  "models": [
    {
      "azureOpenAIParameters": {
        "resourceUri": "https://test-sample.openai.azure.com/",
        "deploymentId": "myDeployment",
        "apiKey": "api-key",
        "modelName": "gpt-4.1-nano"
      },
      "kind": "azureOpenAI"
    }
  ],
  "retrievalReasoningEffort": {
    "kind": "low"
  },
  "outputMode": "extractiveData",
  "@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.",
  "retrievalInstructions": "Instructions for retrieval for the knowledge base.",
  "answerInstructions": "Instructions for answer synthesis.",
  "corsOptions": {
    "allowedOrigins": [
      "https://myapp.example.com"
    ],
    "maxAgeInSeconds": 300
  }
}

範例回覆

狀態碼:: 201

{
  "@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": "api-key",
        "modelName": "gpt-4.1-nano"
      }
    }
  ],
  "encryptionKey": {
    "keyVaultKeyName": "myUserManagedEncryptionKey-createdinAzureKeyVault",
    "keyVaultKeyVersion": "myKeyVersion-32charAlphaNumericString",
    "keyVaultUri": "https://myKeyVault.vault.azure.net",
    "accessCredentials": {
      "applicationId": "00000000-0000-0000-0000-000000000000",
      "applicationSecret": "<applicationSecret>"
    }
  },
  "retrievalReasoningEffort": {
    "kind": "low"
  },
  "corsOptions": {
    "allowedOrigins": [
      "https://myapp.example.com"
    ],
    "maxAgeInSeconds": 300
  }
}

定義

名稱	Description
Accept	接受標頭。
AzureOpenAIModelName	將呼叫的 Azure Open AI 模型名稱。
AzureOpenAIVectorizerParameters	指定連線到 Azure OpenAI 資源的參數。
CorsOptions	定義選項，以控制索引的跨原始來源資源分享（CORS）。
ErrorAdditionalInfo	資源管理錯誤其他資訊。
ErrorDetail	錯誤詳細資料。
ErrorResponse	所有 Azure Resource Manager API 的常見錯誤回應，以傳回失敗作業的錯誤詳細數據。（這也遵循 OData 錯誤回應格式。）。
KnowledgeBase	代表知識庫定義。
KnowledgeBaseAzureOpenAIModel	指定用來執行查詢規劃的 Azure OpenAI 資源。
KnowledgeBaseModelKind	要用於查詢規劃的 AI 模型。
KnowledgeRetrievalLowReasoningEffort	以低推理工作量運行知識檢索。
KnowledgeRetrievalMediumReasoningEffort	以中等推理努力運行知識檢索。
KnowledgeRetrievalMinimalReasoningEffort	以最少的推理工作執行知識檢索。
KnowledgeRetrievalOutputMode	此擷取的輸出組態。
KnowledgeRetrievalReasoningEffortKind	擷取期間要使用的工作量。
KnowledgeSourceReference	參考知識來源。
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-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 型號。

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。

CorsOptions

Object

定義選項，以控制索引的跨原始來源資源分享（CORS）。

名稱	類型	Description
allowedOrigins	string[]	JavaScript 程式碼將從中獲得索引存取權的來源清單。可以包含 {protocol}：//{fully-qualified-domain-name}[：{port#}] 形式的主機清單，或單一 '*' 以允許所有來源（不建議）。
maxAgeInSeconds	integer (int64)	瀏覽器應快取 CORS 預檢回應的持續時間。預設為 5 分鐘。

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	error 物件。

KnowledgeBase

Object

代表知識庫定義。

名稱	類型	Description
@odata.etag	string	知識庫的 ETag。
answerInstructions	string	知識庫在產生答案時會考慮的指令。
corsOptions	CorsOptions	控制知識庫跨原點資源共享（CORS）的選項。
description	string	知識庫的描述。
encryptionKey	SearchResourceEncryptionKey	您在 Azure Key Vault 中建立的加密金鑰描述。
knowledgeSources	KnowledgeSourceReference[]	本知識庫所引用的知識來源。
models	KnowledgeBaseModel[]: KnowledgeBaseAzureOpenAIModel[]	包含有關如何連接到 AI 模型的配置選項。
name	string	知識庫名稱。
outputMode	KnowledgeRetrievalOutputMode	知識庫的輸出模式。
retrievalInstructions	string	知識庫在制定查詢計畫時會考慮的指示。
retrievalReasoningEffort	KnowledgeRetrievalReasoningEffort: KnowledgeRetrievalLowReasoningEffort KnowledgeRetrievalMediumReasoningEffort KnowledgeRetrievalMinimalReasoningEffort	檢索推理努力的配置。

KnowledgeBaseAzureOpenAIModel

Object

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

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

KnowledgeBaseModelKind

列舉型別

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

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

KnowledgeRetrievalLowReasoningEffort

Object

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

名稱	類型	Description
kind	string: low	那種推理努力。

KnowledgeRetrievalMediumReasoningEffort

Object

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

名稱	類型	Description
kind	string: medium	那種推理努力。

KnowledgeRetrievalMinimalReasoningEffort

Object

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

名稱	類型	Description
kind	string: minimal	那種推理努力。

KnowledgeRetrievalOutputMode

列舉型別

此擷取的輸出組態。

值	Description
extractiveData	直接從知識來源傳回資料，無需生成式變更。
answerSynthesis	合成回應承載的答案。

KnowledgeRetrievalReasoningEffortKind

列舉型別

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

值	Description
minimal	不會執行任何來源選取、查詢規劃或反覆搜尋。
low	在檢索期間使用低推理。
medium	在檢索過程中使用適量的推理。

KnowledgeSourceReference

Object

參考知識來源。

名稱	類型	Description
enableFreshness	boolean	指示是否應啟用此知識來源的新鮮度感知檢索。當為真時，檢索時會套用新鮮度評分輪廓，以偏向較新文件的結果。
enableImageServing	boolean	指示是否應啟用此知識來源的影像服務。若屬實，擷取過程中擷取的影像會在查詢時傳送至下游模型。
name	string	知識來源的名稱。

SearchIndexerDataNoneIdentity

Object

清除資料源的識別屬性。

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

SearchIndexerDataUserAssignedIdentity

Object

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

名稱	類型	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

Object

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

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