你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Knowledge Bases - Create Or Update

服务:: Search Service

API 版本:: 2025-11-01-preview

创建新的知识库，或者如果已有知识库就更新。

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

URI 参数

名称	在	必需	类型	说明
endpoint	path	True	string (uri)	搜索服务的终结点 URL。
knowledgeBaseName	path	True	string	知识库的名称。
api-version	query	True	string minLength: 1	要用于此操作的 API 版本。

请求头

名称	必需	类型	说明
Accept		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)	请求的不透明、全局唯一的客户端生成的字符串标识符。

请求正文

名称	必需	类型	说明
knowledgeSources	True	KnowledgeSourceReference[]	本知识库引用的知识来源。
name	True	string	知识库的名称。
@odata.etag		string	知识库的 ETag。
answerInstructions		string	知识库在生成答案时考虑的指令。
description		string	知识库的描述。
encryptionKey		SearchResourceEncryptionKey	描述在 Azure Key Vault 中创建的加密密钥。
models		KnowledgeBaseModel[]: KnowledgeBaseAzureOpenAIModel[]	包含有关如何连接到 AI 模型的配置选项。
outputMode		KnowledgeRetrievalOutputMode	知识库的输出模式。
retrievalInstructions		string	知识库在制定查询计划时考虑的指令。
retrievalReasoningEffort		KnowledgeRetrievalReasoningEffort: KnowledgeRetrievalLowReasoningEffort KnowledgeRetrievalMediumReasoningEffort KnowledgeRetrievalMinimalReasoningEffort	检索推理努力配置。

响应

名称	类型	说明
200 OK	KnowledgeBase	请求已成功。
201 Created	KnowledgeBase	请求已成功，因此创建了一个新资源。
Other Status Codes	ErrorResponse	意外错误响应。

安全性

api-key

类型: apiKey
在: header

OAuth2Auth

类型: oauth2
流向: implicit
授权 URL: https://login.microsoftonline.com/common/oauth2/v2.0/authorize

作用域

名称	说明
https://search.azure.com/.default

示例

SearchServiceCreateOrUpdateKnowledgeBase

示例请求

HTTP

PUT https://previewexampleservice.search.windows.net/knowledgebases('base-preview-test')?api-version=2025-11-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-4o-mini"
      },
      "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."
}

示例响应

状态代码:: 200

{
  "@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-4o-mini"
      }
    }
  ],
  "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"
  }
}

状态代码:: 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-4o-mini"
      }
    }
  ],
  "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"
  }
}

定义

名称	说明
Accept	接受（Accept）首部。
AzureOpenAIModelName	将调用的 Azure Open AI 模型名称。
AzureOpenAIVectorizerParameters	指定用于连接到 Azure OpenAI 资源的参数。
ErrorAdditionalInfo	资源管理错误附加信息。
ErrorDetail	错误详细信息。
ErrorResponse	所有 Azure 资源管理器 API 的常见错误响应，以返回失败操作的错误详细信息。（这也遵循 OData 错误响应格式）。
KnowledgeBase	代表知识库定义。
KnowledgeBaseAzureOpenAIModel	指定用于执行查询规划的 Azure OpenAI 资源。
KnowledgeBaseModelKind	用于查询规划的 AI 模型。
KnowledgeRetrievalLowReasoningEffort	以较低的推理工作量运行知识检索。
KnowledgeRetrievalMediumReasoningEffort	以中等推理工作量运行知识检索。
KnowledgeRetrievalMinimalReasoningEffort	以最少的推理工作运行知识检索。
KnowledgeRetrievalOutputMode	此检索的输出配置。
KnowledgeRetrievalReasoningEffortKind	检索期间要使用的工作量。
KnowledgeSourceReference	引用知识来源。
Prefer	对于 HTTP PUT 请求，指示服务在成功时返回创建/更新的资源。
SearchIndexerDataNoneIdentity	清除数据源的标识属性。
SearchIndexerDataUserAssignedIdentity	指定要使用的数据源的标识。
SearchResourceEncryptionKey	Azure Key Vault 中的客户管理的加密密钥。创建和管理的密钥可用于加密或解密静态数据，例如索引和同义词映射。

Accept

枚举

接受（Accept）首部。

值	说明
application/json;odata.metadata=minimal

AzureOpenAIModelName

枚举

将调用的 Azure Open AI 模型名称。

值	说明
text-embedding-ada-002	TextEmbeddingAda002 模型。
text-embedding-3-large	TextEmbedding3大型模型。
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模型。

AzureOpenAIVectorizerParameters

对象

指定用于连接到 Azure OpenAI 资源的参数。

名称	类型	说明
apiKey	string	指定的 Azure OpenAI 资源的 API 密钥。
authIdentity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	用于出站连接的用户分配的托管标识。
deploymentId	string	指定资源上的 Azure OpenAI 模型部署的 ID。
modelName	AzureOpenAIModelName	在提供的 deploymentId 路径中部署的嵌入模型的名称。
resourceUri	string (uri)	Azure OpenAI 资源的资源 URI。

ErrorAdditionalInfo

对象

资源管理错误附加信息。

名称	类型	说明
info		附加信息。
type	string	附加信息类型。

ErrorDetail

对象

错误详细信息。

名称	类型	说明
additionalInfo	ErrorAdditionalInfo[]	错误附加信息。
code	string	错误代码。
details	ErrorDetail[]	错误详细信息。
message	string	错误消息。
target	string	错误目标。

ErrorResponse

对象

所有 Azure 资源管理器 API 的常见错误响应，以返回失败操作的错误详细信息。（这也遵循 OData 错误响应格式）。

名称	类型	说明
error	ErrorDetail	错误对象。

KnowledgeBase

对象

代表知识库定义。

名称	类型	说明
@odata.etag	string	知识库的 ETag。
answerInstructions	string	知识库在生成答案时考虑的指令。
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

对象

指定用于执行查询规划的 Azure OpenAI 资源。

名称	类型	说明
azureOpenAIParameters	AzureOpenAIVectorizerParameters	Azure OpenAI 参数。
kind	string: azureOpenAI	用于查询规划的 AI 模型。

KnowledgeBaseModelKind

枚举

用于查询规划的 AI 模型。

值	说明
azureOpenAI	使用 Azure Open AI 模型进行查询规划。

KnowledgeRetrievalLowReasoningEffort

对象

以较低的推理工作量运行知识检索。

名称	类型	说明
kind	string: low	那种推理努力。

KnowledgeRetrievalMediumReasoningEffort

对象

以中等推理工作量运行知识检索。

名称	类型	说明
kind	string: medium	那种推理努力。

KnowledgeRetrievalMinimalReasoningEffort

对象

以最少的推理工作运行知识检索。

名称	类型	说明
kind	string: minimal	那种推理努力。

KnowledgeRetrievalOutputMode

枚举

此检索的输出配置。

值	说明
extractiveData	直接从知识源返回数据，无需生成更改。
answerSynthesis	合成响应有效负载的答案。

KnowledgeRetrievalReasoningEffortKind

枚举

检索期间要使用的工作量。

值	说明
minimal	不执行任何源选择、查询规划或迭代搜索。
low	在检索过程中使用低推理。
medium	在检索过程中使用适量的推理。

KnowledgeSourceReference

对象

引用知识来源。

名称	类型	说明
name	string	知识源的名称。

Prefer

枚举

对于 HTTP PUT 请求，指示服务在成功时返回创建/更新的资源。

值	说明
return=representation

SearchIndexerDataNoneIdentity

对象

清除数据源的标识属性。

名称	类型	说明
@odata.type	string: #Microsoft.Azure.Search.DataNoneIdentity	指定身份类型的 URI 片段。

SearchIndexerDataUserAssignedIdentity

对象

指定要使用的数据源的标识。

名称	类型	说明
@odata.type	string: #Microsoft.Azure.Search.DataUserAssignedIdentity	指定身份类型的 URI 片段。
userAssignedIdentity	string	用户分配的托管标识的完全限定的 Azure 资源 ID，通常采用“/subscriptions/12345678-1234-1234-1234567890ab/resourceGroups/rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myId”的形式，应分配给搜索服务。

SearchResourceEncryptionKey

对象

Azure Key Vault 中的客户管理的加密密钥。创建和管理的密钥可用于加密或解密静态数据，例如索引和同义词映射。

名称	类型	说明
accessCredentials.applicationId	string	向 AAD 应用程序 ID 授予对静态数据加密时要使用的 Azure Key Vault 所需的访问权限。应用程序 ID 不应与 AAD 应用程序的对象 ID 混淆。
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`。