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 do URI

Name	Em	Obrigatório	Tipo	Descrição
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 conhecimento.
api-version	query	True	string minLength: 1	A versão da API a utilizar para esta operação.

Cabeçalho do Pedido

Name	Obrigatório	Tipo	Descrição
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

Name	Tipo	Descrição
200 OK	KnowledgeBase	O pedido foi bem-sucedido.
Other Status Codes	ErrorResponse	Uma resposta de erro inesperada.

Segurança

api-key

Tipo: apiKey
Em: header

OAuth2Auth

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

Âmbitos

Name	Descrição
https://search.azure.com/.default

Exemplos

SearchServiceGetKnowledgeBase

Pedido de amostra

HTTP

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

Resposta da amostra

Código de estado:: 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

Name	Descrição
Accept	O cabeçalho Aceitar.
AzureOpenAIModelName	O nome do modelo de IA aberta do Azure que será chamado.
AzureOpenAIVectorizerParameters	Especifica os parâmetros para se conectar ao recurso OpenAI do Azure.
CorsOptions	Define opções para controlar o CORS (Cross-Origin Resource Sharing) para um índice.
ErrorAdditionalInfo	Informações adicionais sobre o erro de gestão de recursos.
ErrorDetail	O detalhe do erro.
ErrorResponse	Resposta de erro comum para todas as APIs do Azure Resource Manager para retornar 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 consultas.
KnowledgeBaseModelKind	O modelo de IA a ser usado para o planejamento de consultas.
KnowledgeBaseRetrieveDefaults	Persistiram os padrões a nível de pedido para pedidos de recuperação da base de conhecimento. Cada valor fornece o valor padrão para o campo correspondente de pedido de recuperação; os valores predefinidos do serviço aplicam-se quando não estão definidos, e os valores de tempo de pedido têm precedência quando presentes.
KnowledgeRetrievalAutoReasoningEffort	Selecione automaticamente o esforço de raciocínio durante a recuperação. O serviço coloca cada pedido no nível mais barato e escala apenas até onde for necessário, até ao nível máximo disponível do serviço.
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 esforço de raciocínio.
KnowledgeRetrievalOutputMode	A configuração de saída para essa recuperação.
KnowledgeRetrievalReasoningEffortKind	A quantidade de esforço a utilizar durante a recuperação.
KnowledgeSourceReference	Referência a uma fonte de conhecimento.
SearchIndexerDataNoneIdentity	Limpa a propriedade identity de uma fonte de dados.
SearchIndexerDataUserAssignedIdentity	Especifica a identidade a ser usada por uma fonte de dados.
SearchResourceEncryptionKey	Uma chave de criptografia gerenciada pelo cliente no Cofre de Chaves do Azure. 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	Descrição
application/json;odata.metadata=minimal

AzureOpenAIModelName

Enumeração

O nome do modelo de IA aberta do Azure que será chamado.

Valor	Descrição
text-embedding-ada-002	Modelo TextEmbeddingAda002.
text-embedding-3-large	TextEmbedding3 Modelo grande.
text-embedding-3-small	TextEmbedding3Small model.
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

Object

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

Name	Tipo	Descrição
apiKey	string	Chave de API do recurso OpenAI do Azure 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 do modelo OpenAI do Azure no recurso designado.
modelName	AzureOpenAIModelName	O nome do modelo de incorporação implantado no caminho deploymentId fornecido.
resourceUri	string (uri)	O URI do recurso Azure OpenAI.

CorsOptions

Object

Define opções para controlar o CORS (Cross-Origin Resource Sharing) para um índice.

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

ErrorAdditionalInfo

Object

Informações adicionais sobre o erro de gestão de recursos.

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

ErrorDetail

Object

O detalhe do erro.

Name	Tipo	Descrição
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 alvo do erro.

ErrorResponse

Object

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

Name	Tipo	Descrição
error	ErrorDetail	O objeto de erro.

KnowledgeBase

Object

Representa uma definição de base de conhecimento.

Name	Tipo	Descrição
@odata.etag	string	O ETag da base de conhecimento.
answerInstructions	string	Instruções consideradas pela base de conhecimento ao gerar respostas.
corsOptions	CorsOptions	Opções para controlar a Partilha de Recursos entre Origens (CORS) para a base de conhecimento.
description	string	A descrição da base de conhecimento.
encryptionKey	SearchResourceEncryptionKey	Uma descrição de uma chave de criptografia que você cria no Cofre de Chaves do Azure.
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 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 a nível de pedido para esta base de conhecimento. Estes valores aplicam-se para recuperar pedidos que omitam os campos correspondentes; os valores de tempo de pedido têm precedência quando estão presentes.
tags	object	Pares-chave-valor definidos pelo utilizador para categorizar a base de conhecimento e atribuir o seu uso e custos.

KnowledgeBaseAzureOpenAIModel

Object

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

Name	Tipo	Descrição
azureOpenAIParameters	AzureOpenAIVectorizerParameters	Parâmetros Azure OpenAI.
kind	string: azureOpenAI	O modelo de IA a ser usado para o planejamento de consultas.

KnowledgeBaseModelKind

Enumeração

O modelo de IA a ser usado para o planejamento de consultas.

Valor	Descrição
azureOpenAI	Use modelos de IA aberta do Azure para planejamento de consultas.

KnowledgeBaseRetrieveDefaults

Object

Persistiram os padrões a nível de pedido para pedidos de recuperação da base de conhecimento. Cada valor fornece o valor padrão para o campo correspondente de pedido de recuperação; os valores predefinidos do serviço aplicam-se quando não estão definidos, e os valores de tempo de pedido têm precedência quando presentes.

Name	Tipo	Descrição
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 predefinido, em tokens, do conteúdo na saída de recuperação.
maxRuntimeInSeconds	integer (int32)	O tempo máximo de execução padrão em segundos para um pedido de recuperação.

KnowledgeRetrievalAutoReasoningEffort

Object

Selecione automaticamente o esforço de raciocínio durante a recuperação. O serviço coloca cada pedido no nível mais barato e escala apenas até onde for necessário, até ao nível máximo disponível do serviço.

Name	Tipo	Descrição
kind	string: auto	O tipo de esforço de raciocínio.

KnowledgeRetrievalLowReasoningEffort

Object

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

Name	Tipo	Descrição
kind	string: low	O tipo de esforço de raciocínio.

KnowledgeRetrievalMediumReasoningEffort

Object

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

Name	Tipo	Descrição
kind	string: medium	O tipo de esforço de raciocínio.

KnowledgeRetrievalMinimalReasoningEffort

Object

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

Name	Tipo	Descrição
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	Descrição
extractiveData	Retornar dados das fontes de conhecimento diretamente, sem alteração generativa.
answerSynthesis	Sintetize uma resposta para a carga útil de resposta.

KnowledgeRetrievalReasoningEffortKind

Enumeração

A quantidade de esforço a utilizar durante a recuperação.

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

KnowledgeSourceReference

Object

Referência a uma fonte de conhecimento.

Name	Tipo	Descrição
enableFreshness	boolean	Indica se a recuperação consciente da frescura deve ser ativada para esta fonte de conhecimento. Quando é verdade, aplica-se um perfil de pontuação de frescura durante a recuperação aos resultados de viés em relação a documentos mais recentes.
enableImageServing	boolean	Indica se o serviço de imagem deve ser ativado para esta fonte de conhecimento. Quando é verdade, as imagens extraídas durante a ingestão são entregues aos modelos a jusante no momento da consulta.
name	string	O nome da fonte de conhecimento.

SearchIndexerDataNoneIdentity

Object

Limpa a propriedade identity de uma fonte de dados.

Name	Tipo	Descrição
@odata.type	string: #Microsoft.Azure.Search.DataNoneIdentity	Um fragmento de URI especificando o tipo de identidade.

SearchIndexerDataUserAssignedIdentity

Object

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

Name	Tipo	Descrição
@odata.type	string: #Microsoft.Azure.Search.DataUserAssignedIdentity	Um fragmento de URI especificando o tipo de identidade.
federatedIdentityClientId	string	Multi-tenant User-Assigned Managed Identity Support: O id do cliente da aplicação multi-tentant que foi configurada para federar com a identidade gerida atribuída pelo utilizador.
userAssignedIdentity	string	A ID de recurso do Azure totalmente qualificada de uma identidade gerenciada atribuída ao usuário normalmente no formato "/subscriptions/12345678-1234-1234-1234-1234567890ab/resourceGroups/rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myId" que deveria ter sido atribuída ao serviço de pesquisa.

SearchResourceEncryptionKey

Object

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

Name	Tipo	Valor predefinido	Descrição
accessCredentials.applicationId	string		Uma ID de Aplicativo AAD que recebeu as permissões de acesso necessárias ao Cofre da Chave do Azure que deve ser usada ao criptografar seus dados em repouso. A ID do aplicativo não deve ser confundida com a ID do objeto do seu aplicativo 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 ao sistema será usada. Na atualização do 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 que indica se esta chave é uma chave de nível de serviço. O valor padrão é falso.
keyVaultKeyName	string		O nome da sua chave do Cofre da Chave do Azure a ser usada para criptografar seus dados em repouso.
keyVaultKeyVersion	string		A versão da chave do Cofre da Chave do Azure a ser usada para criptografar seus dados em repouso.
keyVaultUri	string		O URI do seu Cofre da Chave do Azure, também conhecido como nome DNS, que contém a chave a ser usada para criptografar seus dados em repouso. Um exemplo de URI pode ser `https://my-keyvault-name.vault.azure.net`.