Knowledge Bases - Create Or Update

Serviço:: Search Service

Versão da API:: 2025-11-01-preview

Cria uma nova base de conhecimento ou atualiza uma base de conhecimento se ela já existir.

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

Parâmetros de URI

Nome	Em	Obrigatório	Tipo	Description
endpoint	path	True	string (uri)	A URL do ponto de extremidade do serviço de pesquisa.
knowledgeBaseName	path	True	string	O nome da base de dados de conhecimento.
api-version	query	True	string minLength: 1	A versão da API a ser usada para esta operação.

Cabeçalho da solicitação

Nome	Obrigatório	Tipo	Description
Accept		Accept	O cabeçalho Aceitar.
If-Match		string	Define a condição de If-Match. A operação será executada somente se a ETag no servidor corresponder a esse valor.
If-None-Match		string	Define a condição If-None-Match. A operação será executada somente se a ETag no servidor não corresponder a esse valor.
Prefer	True	Prefer	Para solicitações HTTP PUT, instrui o serviço a retornar o recurso criado/atualizado em caso de êxito.
x-ms-client-request-id		string (uuid)	Um identificador de cadeia de caracteres opaco, globalmente exclusivo e gerado pelo cliente para a solicitação.

Corpo da solicitação

Nome	Obrigatório	Tipo	Description
knowledgeSources	True	KnowledgeSourceReference[]	Fontes de conhecimento referenciadas por esta base de conhecimento.
name	True	string	O nome da base de dados de conhecimento.
@odata.etag		string	A ETag da base de conhecimento.
answerInstructions		string	Instruções consideradas pela base de conhecimento ao gerar respostas.
description		string	A descrição da base de dados de conhecimento.
encryptionKey		SearchResourceEncryptionKey	Uma descrição de uma chave de criptografia que você cria no Azure Key Vault.
models		KnowledgeBaseModel[]: KnowledgeBaseAzureOpenAIModel[]	Contém opções de configuração sobre como se conectar a modelos de IA.
outputMode		KnowledgeRetrievalOutputMode	O modo de saída para a base de conhecimento.
retrievalInstructions		string	Instruções consideradas pela base de conhecimento ao desenvolver o plano de consulta.
retrievalReasoningEffort		KnowledgeRetrievalReasoningEffort: KnowledgeRetrievalLowReasoningEffort KnowledgeRetrievalMediumReasoningEffort KnowledgeRetrievalMinimalReasoningEffort	A configuração do esforço de raciocínio de recuperação.

Respostas

Nome	Tipo	Description
200 OK	KnowledgeBase	A solicitação foi bem-sucedida.
201 Created	KnowledgeBase	A solicitação foi bem-sucedida e um novo recurso foi criado como resultado.
Other Status Codes	ErrorResponse	Uma resposta de erro inesperada.

Segurança

api-key

Tipo: apiKey
Em: header

OAuth2Auth

Tipo: oauth2
Flow: implicit
URL de Autorização: https://login.microsoftonline.com/common/oauth2/v2.0/authorize

Escopos

Nome	Description
https://search.azure.com/.default

Exemplos

SearchServiceCreateOrUpdateKnowledgeBase

Solicitação de exemplo

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."
}

Resposta de exemplo

Código de status:: 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"
  }
}

Código de status:: 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"
  }
}

Definições

Nome	Description
Accept	O cabeçalho Aceitar.
AzureOpenAIModelName	O nome do modelo do Azure Open AI que será chamado.
AzureOpenAIVectorizerParameters	Especifica os parâmetros para se conectar ao recurso do Azure OpenAI.
ErrorAdditionalInfo	As informações adicionais do erro de gerenciamento de recursos.
ErrorDetail	O detalhe do erro.
ErrorResponse	Resposta de erro comum para todas as APIs do Azure Resource Manager retornarem detalhes de erro para operações com falha. (Isso também segue o formato de resposta de erro OData.).
KnowledgeBase	Representa uma definição de base de conhecimento.
KnowledgeBaseAzureOpenAIModel	Especifica o recurso OpenAI do Azure usado para fazer o planejamento de consulta.
KnowledgeBaseModelKind	O modelo de IA a ser usado para planejamento de consulta.
KnowledgeRetrievalLowReasoningEffort	Execute a recuperação de conhecimento com baixo esforço de raciocínio.
KnowledgeRetrievalMediumReasoningEffort	Execute a recuperação de conhecimento com esforço de raciocínio médio.
KnowledgeRetrievalMinimalReasoningEffort	Execute a recuperação de conhecimento com o mínimo de esforço de raciocínio.
KnowledgeRetrievalOutputMode	A configuração de saída para essa recuperação.
KnowledgeRetrievalReasoningEffortKind	A quantidade de esforço a ser usado durante a recuperação.
KnowledgeSourceReference	Referência a uma fonte de conhecimento.
Prefer	Para solicitações HTTP PUT, instrui o serviço a retornar o recurso criado/atualizado em caso de êxito.
SearchIndexerDataNoneIdentity	Limpa a propriedade de identidade de uma fonte de dados.
SearchIndexerDataUserAssignedIdentity	Especifica a identidade de uma fonte de dados a ser usada.
SearchResourceEncryptionKey	Uma chave de criptografia gerenciada pelo cliente no Azure Key Vault. As chaves que você cria e gerencia podem ser usadas para criptografar ou descriptografar dados em repouso, como índices e mapas de sinônimos.

Accept

Enumeração

O cabeçalho Aceitar.

Valor	Description
application/json;odata.metadata=minimal

AzureOpenAIModelName

Enumeração

O nome do modelo do Azure Open AI que será chamado.

Valor	Description
text-embedding-ada-002	TextEmbeddingAda002 modelo.
text-embedding-3-large	TextEmbedding3 Modelo grande.
text-embedding-3-small	TextEmbedding3Small modelo.
gpt-4o	Modelo GPT4o.
gpt-4o-mini	Modelo Gpt4oMini.
gpt-4.1	Modelo GPT41.
gpt-4.1-mini	Modelo GPT41Mini.
gpt-4.1-nano	Modelo GPT41Nano.
gpt-5	Modelo GPT5.
gpt-5-mini	Modelo Gpt5Mini.
gpt-5-nano	Modelo Gpt5Nano.

AzureOpenAIVectorizerParameters

Objeto

Especifica os parâmetros para se conectar ao recurso do Azure OpenAI.

Nome	Tipo	Description
apiKey	string	Chave de API do recurso Azure OpenAI designado.
authIdentity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	A identidade gerenciada atribuída pelo usuário usada para conexões de saída.
deploymentId	string	ID da implantação de modelo do Azure OpenAI no recurso designado.
modelName	AzureOpenAIModelName	O nome do modelo de inserção implantado no caminho deploymentId fornecido.
resourceUri	string (uri)	O URI do recurso do Azure OpenAI.

ErrorAdditionalInfo

Objeto

As informações adicionais do erro de gerenciamento de recursos.

Nome	Tipo	Description
info		As informações adicionais.
type	string	O tipo de informação adicional.

ErrorDetail

Objeto

O detalhe do erro.

Nome	Tipo	Description
additionalInfo	ErrorAdditionalInfo[]	As informações adicionais do erro.
code	string	O código de erro.
details	ErrorDetail[]	Os detalhes do erro.
message	string	A mensagem de erro.
target	string	O destino do erro.

ErrorResponse

Objeto

Resposta de erro comum para todas as APIs do Azure Resource Manager retornarem detalhes de erro para operações com falha. (Isso também segue o formato de resposta de erro OData.).

Nome	Tipo	Description
error	ErrorDetail	O objeto de erro.

KnowledgeBase

Objeto

Representa uma definição de base de conhecimento.

Nome	Tipo	Description
@odata.etag	string	A ETag da base de conhecimento.
answerInstructions	string	Instruções consideradas pela base de conhecimento ao gerar respostas.
description	string	A descrição da base de dados de conhecimento.
encryptionKey	SearchResourceEncryptionKey	Uma descrição de uma chave de criptografia que você cria no Azure Key Vault.
knowledgeSources	KnowledgeSourceReference[]	Fontes de conhecimento referenciadas por esta base de conhecimento.
models	KnowledgeBaseModel[]: KnowledgeBaseAzureOpenAIModel[]	Contém opções de configuração sobre como se conectar a modelos de IA.
name	string	O nome da base de dados de conhecimento.
outputMode	KnowledgeRetrievalOutputMode	O modo de saída para a base de conhecimento.
retrievalInstructions	string	Instruções consideradas pela base de conhecimento ao desenvolver o plano de consulta.
retrievalReasoningEffort	KnowledgeRetrievalReasoningEffort: KnowledgeRetrievalLowReasoningEffort KnowledgeRetrievalMediumReasoningEffort KnowledgeRetrievalMinimalReasoningEffort	A configuração do esforço de raciocínio de recuperação.

KnowledgeBaseAzureOpenAIModel

Objeto

Especifica o recurso OpenAI do Azure usado para fazer o planejamento de consulta.

Nome	Tipo	Description
azureOpenAIParameters	AzureOpenAIVectorizerParameters	Azure OpenAI.
kind	string: azureOpenAI	O modelo de IA a ser usado para planejamento de consulta.

KnowledgeBaseModelKind

Enumeração

O modelo de IA a ser usado para planejamento de consulta.

Valor	Description
azureOpenAI	Use modelos de IA aberta do Azure para planejamento de consulta.

KnowledgeRetrievalLowReasoningEffort

Objeto

Execute a recuperação de conhecimento com baixo esforço de raciocínio.

Nome	Tipo	Description
kind	string: low	O tipo de esforço de raciocínio.

KnowledgeRetrievalMediumReasoningEffort

Objeto

Execute a recuperação de conhecimento com esforço de raciocínio médio.

Nome	Tipo	Description
kind	string: medium	O tipo de esforço de raciocínio.

KnowledgeRetrievalMinimalReasoningEffort

Objeto

Execute a recuperação de conhecimento com o mínimo de esforço de raciocínio.

Nome	Tipo	Description
kind	string: minimal	O tipo de esforço de raciocínio.

KnowledgeRetrievalOutputMode

Enumeração

A configuração de saída para essa recuperação.

Valor	Description
extractiveData	Retorne dados das fontes de conhecimento diretamente sem alteração geradora.
answerSynthesis	Sintetize uma resposta para a carga de resposta.

KnowledgeRetrievalReasoningEffortKind

Enumeração

A quantidade de esforço a ser usado durante a recuperação.

Valor	Description
minimal	Não executa nenhuma seleção de origem, planejamento de consulta ou pesquisa iterativa.
low	Use raciocínio baixo durante a recuperação.
medium	Use uma quantidade moderada de raciocínio durante a recuperação.

KnowledgeSourceReference

Objeto

Referência a uma fonte de conhecimento.

Nome	Tipo	Description
name	string	O nome da fonte de conhecimento.

Prefer

Enumeração

Para solicitações HTTP PUT, instrui o serviço a retornar o recurso criado/atualizado em caso de êxito.

Valor	Description
return=representation

SearchIndexerDataNoneIdentity

Objeto

Limpa a propriedade de identidade de uma fonte de dados.

Nome	Tipo	Description
@odata.type	string: #Microsoft.Azure.Search.DataNoneIdentity	Um fragmento de URI especificando o tipo de identidade.

SearchIndexerDataUserAssignedIdentity

Objeto

Especifica a identidade de uma fonte de dados a ser usada.

Nome	Tipo	Description
@odata.type	string: #Microsoft.Azure.Search.DataUserAssignedIdentity	Um fragmento de URI especificando o tipo de identidade.
userAssignedIdentity	string	A ID de recurso do Azure totalmente qualificada de uma identidade gerenciada atribuída pelo usuário, normalmente no formato "/subscriptions/12345678-1234-1234-1234567890ab/resourceGroups/rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myId" que deveria ter sido atribuída ao serviço de pesquisa.

SearchResourceEncryptionKey

Objeto

Uma chave de criptografia gerenciada pelo cliente no Azure Key Vault. As chaves que você cria e gerencia podem ser usadas para criptografar ou descriptografar dados em repouso, como índices e mapas de sinônimos.

Nome	Tipo	Description
accessCredentials.applicationId	string	Uma ID de aplicativo do AAD que recebeu as permissões de acesso necessárias para o Azure Key Vault que deve ser usada ao criptografar seus dados em repouso. A ID do aplicativo não deve ser confundida com a ID do objeto para seu aplicativo do AAD.
accessCredentials.applicationSecret	string	A chave de autenticação do aplicativo AAD especificado.
identity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	Uma identidade gerenciada explícita a ser usada para essa chave de criptografia. Se não for especificado e a propriedade de credenciais de acesso for nula, a identidade gerenciada atribuída pelo sistema será usada. Ao atualizar para o recurso, se a identidade explícita não for especificada, ela permanecerá inalterada. Se "nenhum" for especificado, o valor dessa propriedade será limpo.
keyVaultKeyName	string	O nome da chave do Azure Key Vault a ser usada para criptografar seus dados em repouso.
keyVaultKeyVersion	string	A versão da chave do Azure Key Vault a ser usada para criptografar seus dados em repouso.
keyVaultUri	string	O URI do Azure Key Vault, também conhecido como nome DNS, que contém a chave a ser usada para criptografar seus dados em repouso. Um URI de exemplo pode ser `https://my-keyvault-name.vault.azure.net`.