Knowledge Bases - Get

Serviço:: Search Service

Versão da API:: 2026-08-01-preview

Recupera uma definição de base de conhecimento.

GET {endpoint}/knowledgebases('{knowledgeBaseName}')?api-version=2026-08-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.
x-ms-client-request-id		string (uuid)	Um identificador de cadeia de caracteres opaco, globalmente exclusivo e gerado pelo cliente para a solicitação.

Respostas

Nome	Tipo	Description
200 OK	KnowledgeBase	A solicitação foi bem-sucedida.
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

SearchServiceGetKnowledgeBase

Solicitação de exemplo

HTTP

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

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

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.
CorsOptions	Define opções para controlar o CORS (Compartilhamento de Recursos entre Origens) para um índice.
ErrorAdditionalInfo	Informações adicionais sobre o 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.
KnowledgeBaseRetrieveDefaults	Persistiram os padrões de requisição para toda a solicitação de recuperação da base de conhecimento. Cada valor fornece o padrão para o campo de recuperação correspondente; os padrões de serviço se aplicam quando não estão definidos, e os valores de tempo de solicitação têm precedência quando presentes.
KnowledgeRetrievalAutoReasoningEffort	Selecione automaticamente o esforço de raciocínio durante a recuperação. O serviço segmenta cada solicitação no nível mais barato e escala apenas até o nível mais alto disponível.
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.
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.
gpt-5.1	Modelo GPT51.
gpt-5.2	Modelo GPT52.
gpt-5.4	Modelo GPT54.
gpt-5.4-mini	Modelo Gpt54Mini.
gpt-5.4-nano	Modelo Gpt54Nano.
gpt-5.5	Modelo GPT55.
gpt-5.6-sol	Modelo Gpt56Sol.
gpt-5.6-terra	Modelo GPT56Terra.
gpt-5.6-luna	Modelo Gpt56Luna.

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.

CorsOptions

Objeto

Define opções para controlar o CORS (Compartilhamento de Recursos entre Origens) para um índice.

Nome	Tipo	Description
allowedOrigins	string[]	A lista de origens das quais o código JavaScript terá acesso ao índice. Pode conter uma lista de hosts no formato {protocol}://{fully-qualified-domain-name}[:{port#}] ou um único '*' para permitir todas as origens (não recomendado).
maxAgeInSeconds	integer (int64)	A duração pela qual os navegadores devem armazenar em cache as respostas de comprovação do CORS. O padrão é 5 minutos.

ErrorAdditionalInfo

Objeto

Informações adicionais sobre o 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[]	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 alvo 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.
corsOptions	CorsOptions	Opções para controlar o Compartilhamento de Recursos entre Origens (CORS) para a base de conhecimento.
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: KnowledgeRetrievalAutoReasoningEffort KnowledgeRetrievalLowReasoningEffort KnowledgeRetrievalMediumReasoningEffort KnowledgeRetrievalMinimalReasoningEffort	A configuração do esforço de raciocínio de recuperação.
retrieveDefaults	KnowledgeBaseRetrieveDefaults	Persistiram os padrões de recuperação em toda a requisição para essa base de conhecimento. Esses valores se aplicam para recuperar solicitações que omitem os campos correspondentes; valores de tempo de solicitação têm precedência quando presentes.
tags	object	Pares chave-valor definidos pelo usuário para categorizar a base de conhecimento e atribuir seu uso e custos.

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.

KnowledgeBaseRetrieveDefaults

Objeto

Persistiram os padrões de requisição para toda a solicitação de recuperação da base de conhecimento. Cada valor fornece o padrão para o campo de recuperação correspondente; os padrões de serviço se aplicam quando não estão definidos, e os valores de tempo de solicitação têm precedência quando presentes.

Nome	Tipo	Description
maxOutputDocuments	integer (int32)	O número máximo padrão de documentos na saída de recuperação.
maxOutputSizeInTokens	integer (int32)	O tamanho máximo padrão, em tokens, do conteúdo na saída de recuperação.
maxRuntimeInSeconds	integer (int32)	O tempo máximo padrão de execução em segundos para uma solicitação de recuperação.

KnowledgeRetrievalAutoReasoningEffort

Objeto

Selecione automaticamente o esforço de raciocínio durante a recuperação. O serviço segmenta cada solicitação no nível mais barato e escala apenas até o nível mais alto disponível.

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

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.
auto	Selecione automaticamente o esforço de raciocínio durante a recuperação, escalando do nível mais barato apenas até onde for necessário.

KnowledgeSourceReference

Objeto

Referência a uma fonte de conhecimento.

Nome	Tipo	Description
enableFreshness	boolean	Indica se a recuperação consciente da frescura deve ser habilitada para essa fonte de conhecimento. Quando é verdadeiro, um perfil de pontuação de frescura é aplicado durante a recuperação para os resultados de viés em relação a documentos mais recentes.
enableImageServing	boolean	Indica se o serviço de imagem deve ser ativado para essa fonte de conhecimento. Quando verdade, as imagens extraídas durante a ingestão são entregues aos modelos posteriores no momento da consulta.
name	string	O nome da fonte de conhecimento.

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.
federatedIdentityClientId	string	Suporte a Identidade Gerenciada User-Assigned Multi-Inquilino: O ID do cliente do aplicativo multi-tentante que foi configurado para federar com a identidade gerenciada atribuída pelo usuário.
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-12334-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	Valor padrão	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.
isServiceLevelKey	boolean	False	Um valor opcional indicando se essa chave é uma chave de nível de serviço. O padrão é false.
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`.