Knowledge Bases - Get

Service:: Search Service

Version d’API:: 2026-08-01-preview

Récupère une définition de base de connaissances.

GET {endpoint}/knowledgebases('{knowledgeBaseName}')?api-version=2026-08-01-preview

Paramètres URI

Nom	Dans	Obligatoire	Type	Description
endpoint	path	True	string (uri)	URL du point de terminaison du service de recherche.
knowledgeBaseName	path	True	string	Nom de la base de connaissances.
api-version	query	True	string minLength: 1	Version de l’API à utiliser pour cette opération.

En-tête de la demande

Nom	Obligatoire	Type	Description
Accept		Accept	L’en-tête Accept.
x-ms-client-request-id		string (uuid)	Identificateur de chaîne opaque, globalement unique et généré par le client pour la requête.

Réponses

Nom	Type	Description
200 OK	KnowledgeBase	La demande a réussi.
Other Status Codes	ErrorResponse	Réponse d’erreur inattendue.

Sécurité

api-key

Type: apiKey
Dans: header

OAuth2Auth

Type: oauth2
Flux: implicit
URL d’autorisation: https://login.microsoftonline.com/common/oauth2/v2.0/authorize

Étendues

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

Exemples

SearchServiceGetKnowledgeBase

Exemple de requête

HTTP

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

Exemple de réponse

Code d’état:: 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
  }
}

Définitions

Nom	Description
Accept	L’en-tête Accept.
AzureOpenAIModelName	Nom du modèle Azure Open AI qui sera appelé.
AzureOpenAIVectorizerParameters	Spécifie les paramètres de connexion à la ressource Azure OpenAI.
CorsOptions	Définit les options permettant de contrôler le partage de ressources cross-origin (CORS) pour un index.
ErrorAdditionalInfo	Informations supplémentaires sur l’erreur de gestion des ressources.
ErrorDetail	Détail de l’erreur.
ErrorResponse	Réponse d’erreur courante pour toutes les API Azure Resource Manager afin de retourner les détails de l’erreur pour les opérations ayant échoué. (Cela suit également le format de réponse d’erreur OData.).
KnowledgeBase	Représente une définition de base de connaissances.
KnowledgeBaseAzureOpenAIModel	Spécifie la ressource Azure OpenAI utilisée pour la planification des requêtes.
KnowledgeBaseModelKind	Le modèle d’IA à utiliser pour la planification des requêtes.
KnowledgeBaseRetrieveDefaults	Les paramètres par défaut à l’échelle de la requête pour les requêtes de récupération de la base de connaissances persistaient. Chaque valeur fournit le champ par défaut pour le champ de recherche correspondant ; les valeurs par défaut du service s’appliquent lorsqu’elles ne sont pas définies, et les valeurs au moment de la requête ont la priorité lorsqu’elles sont présentes.
KnowledgeRetrievalAutoReasoningEffort	Sélectionnez automatiquement l’effort de raisonnement lors de la récupération. Le service soumet chaque demande au niveau le moins cher et ne monte que jusqu’au niveau maximal disponible du service.
KnowledgeRetrievalLowReasoningEffort	Exécutez la récupération des connaissances avec un faible effort de raisonnement.
KnowledgeRetrievalMediumReasoningEffort	Exécutez la récupération des connaissances avec un effort de raisonnement moyen.
KnowledgeRetrievalMinimalReasoningEffort	Exécutez la récupération des connaissances avec un minimum d’effort de raisonnement.
KnowledgeRetrievalOutputMode	Configuration de sortie pour cette extraction.
KnowledgeRetrievalReasoningEffortKind	La quantité d’effort à fournir lors de la récupération.
KnowledgeSourceReference	Référence à une source de connaissances.
SearchIndexerDataNoneIdentity	Efface la propriété d’identité d’une source de données.
SearchIndexerDataUserAssignedIdentity	Spécifie l’identité d’une source de données à utiliser.
SearchResourceEncryptionKey	Clé de chiffrement gérée par le client dans Azure Key Vault. Les clés que vous créez et gérez peuvent être utilisées pour chiffrer ou déchiffrer des données au repos, telles que des index et des cartes de synonymes.

Accept

Énumération

L’en-tête Accept.

Valeur	Description
application/json;odata.metadata=minimal

AzureOpenAIModelName

Énumération

Nom du modèle Azure Open AI qui sera appelé.

Valeur	Description
text-embedding-ada-002	TextEmbeddingAda002 modèle.
text-embedding-3-large	TextEmbedding3Large modèle.
text-embedding-3-small	TextEmbedding3Small modèle.
gpt-4o	Modèle GPT4o.
gpt-4o-mini	Modèle GPT4oMini.
gpt-4.1	Modèle GPT41.
gpt-4.1-mini	Modèle GPT41Mini.
gpt-4.1-nano	Modèle Gpt41Nano.
gpt-5	Modèle GPT5.
gpt-5-mini	Modèle Gpt5Mini.
gpt-5-nano	Modèle Gpt5Nano.
gpt-5.1	Modèle GPT51.
gpt-5.2	Modèle GPT52.
gpt-5.4	Modèle GPT54.
gpt-5.4-mini	Modèle Gpt54Mini.
gpt-5.4-nano	Modèle Gpt54Nano.
gpt-5.5	Modèle GPT55.
gpt-5.6-sol	Modèle Gpt56Sol.
gpt-5.6-terra	Modèle GPT56Terra.
gpt-5.6-luna	Modèle Gpt56Luna.

AzureOpenAIVectorizerParameters

Objet

Spécifie les paramètres de connexion à la ressource Azure OpenAI.

Nom	Type	Description
apiKey	string	Clé API de la ressource Azure OpenAI désignée.
authIdentity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	Identité managée affectée par l’utilisateur utilisée pour les connexions sortantes.
deploymentId	string	ID du déploiement du modèle Azure OpenAI sur la ressource désignée.
modelName	AzureOpenAIModelName	Nom du modèle d’incorporation déployé sur le chemin d’accès deploymentId fourni.
resourceUri	string (uri)	URI de ressource de la ressource Azure OpenAI.

CorsOptions

Objet

Définit les options permettant de contrôler le partage de ressources cross-origin (CORS) pour un index.

Nom	Type	Description
allowedOrigins	string[]	La liste des origines à partir desquelles le code JavaScript sera autorisé à accéder à votre index. Peut contenir une liste d’hôtes de la forme {protocol} ://{fully-qualified-domain-name}[ :{port#}], ou un seul '*' pour autoriser toutes les origines (non recommandé).
maxAgeInSeconds	integer (int64)	Durée pendant laquelle les navigateurs doivent mettre en cache les réponses de contrôle en amont CORS. La valeur par défaut est de 5 minutes.

ErrorAdditionalInfo

Objet

Informations supplémentaires sur l’erreur de gestion des ressources.

Nom	Type	Description
info		Informations supplémentaires
type	string	Le type d’informations supplémentaires.

ErrorDetail

Objet

Détail de l’erreur.

Nom	Type	Description
additionalInfo	ErrorAdditionalInfo[]	Informations complémentaires sur l’erreur.
code	string	Code d’erreur.
details	ErrorDetail[]	Détails de l’erreur.
message	string	Message d’erreur.
target	string	Cible d’erreur.

ErrorResponse

Objet

Réponse d’erreur courante pour toutes les API Azure Resource Manager afin de retourner les détails de l’erreur pour les opérations ayant échoué. (Cela suit également le format de réponse d’erreur OData.).

Nom	Type	Description
error	ErrorDetail	Objet d’erreur.

KnowledgeBase

Objet

Représente une définition de base de connaissances.

Nom	Type	Description
@odata.etag	string	L’ETag de la base de connaissances.
answerInstructions	string	Instructions prises en compte par la base de connaissances lors de la génération de réponses.
corsOptions	CorsOptions	Options pour contrôler le partage de ressources inter-origine (CORS) pour la base de connaissances.
description	string	La description de la base de connaissances.
encryptionKey	SearchResourceEncryptionKey	Description d’une clé de chiffrement que vous créez dans Azure Key Vault.
knowledgeSources	KnowledgeSourceReference[]	Sources de connaissances référencées par cette base de connaissances.
models	KnowledgeBaseModel[]: KnowledgeBaseAzureOpenAIModel[]	Contient des options de configuration sur la façon de se connecter aux modèles d’IA.
name	string	Nom de la base de connaissances.
outputMode	KnowledgeRetrievalOutputMode	Le mode de sortie pour la base de connaissances.
retrievalInstructions	string	Instructions prises en compte par la base de connaissances lors de l’élaboration du plan de requête.
retrievalReasoningEffort	KnowledgeRetrievalReasoningEffort: KnowledgeRetrievalAutoReasoningEffort KnowledgeRetrievalLowReasoningEffort KnowledgeRetrievalMediumReasoningEffort KnowledgeRetrievalMinimalReasoningEffort	La configuration de l’effort de raisonnement de récupération.
retrieveDefaults	KnowledgeBaseRetrieveDefaults	Des données par défaut de recherche à l’échelle de la requête ont persisté pour cette base de connaissances. Ces valeurs s’appliquent à la récupération de requêtes qui omettent les champs correspondants ; les valeurs au moment de la requête ont la priorité lorsqu’elles sont présentes.
tags	object	Des paires clé-valeur définies par l’utilisateur pour catégoriser la base de connaissances et attribuer son utilisation et ses coûts.

KnowledgeBaseAzureOpenAIModel

Objet

Spécifie la ressource Azure OpenAI utilisée pour la planification des requêtes.

Nom	Type	Description
azureOpenAIParameters	AzureOpenAIVectorizerParameters	Azure OpenAI paramètres.
kind	string: azureOpenAI	Le modèle d’IA à utiliser pour la planification des requêtes.

KnowledgeBaseModelKind

Énumération

Le modèle d’IA à utiliser pour la planification des requêtes.

Valeur	Description
azureOpenAI	Utilisez les modèles Azure Open AI pour la planification des requêtes.

KnowledgeBaseRetrieveDefaults

Objet

Les paramètres par défaut à l’échelle de la requête pour les requêtes de récupération de la base de connaissances persistaient. Chaque valeur fournit le champ par défaut pour le champ de recherche correspondant ; les valeurs par défaut du service s’appliquent lorsqu’elles ne sont pas définies, et les valeurs au moment de la requête ont la priorité lorsqu’elles sont présentes.

Nom	Type	Description
maxOutputDocuments	integer (int32)	Le nombre maximal par défaut de documents dans la sortie de récupération.
maxOutputSizeInTokens	integer (int32)	La taille maximale par défaut, en jetons, du contenu dans la sortie de récupération.
maxRuntimeInSeconds	integer (int32)	Le temps d’exécution maximal par défaut en secondes pour une requête de récupération.

KnowledgeRetrievalAutoReasoningEffort

Objet

Sélectionnez automatiquement l’effort de raisonnement lors de la récupération. Le service soumet chaque demande au niveau le moins cher et ne monte que jusqu’au niveau maximal disponible du service.

Nom	Type	Description
kind	string: auto	Le genre d’effort de raisonnement.

KnowledgeRetrievalLowReasoningEffort

Objet

Exécutez la récupération des connaissances avec un faible effort de raisonnement.

Nom	Type	Description
kind	string: low	Le genre d’effort de raisonnement.

KnowledgeRetrievalMediumReasoningEffort

Objet

Exécutez la récupération des connaissances avec un effort de raisonnement moyen.

Nom	Type	Description
kind	string: medium	Le genre d’effort de raisonnement.

KnowledgeRetrievalMinimalReasoningEffort

Objet

Exécutez la récupération des connaissances avec un minimum d’effort de raisonnement.

Nom	Type	Description
kind	string: minimal	Le genre d’effort de raisonnement.

KnowledgeRetrievalOutputMode

Énumération

Configuration de sortie pour cette extraction.

Valeur	Description
extractiveData	Retournez des données à partir des sources de connaissances directement sans modification générative.
answerSynthesis	Synthétisez une réponse pour la charge utile de réponse.

KnowledgeRetrievalReasoningEffortKind

Énumération

La quantité d’effort à fournir lors de la récupération.

Valeur	Description
minimal	N’effectue pas de sélections de sources, de planification de requêtes ou de recherche itérative.
low	Utilisez un raisonnement faible lors de la récupération.
medium	Utilisez une quantité modérée de raisonnement pendant la récupération.
auto	Sélectionnez automatiquement l’effort de raisonnement lors de la récupération, en augmentant du niveau le moins cher uniquement dans la mesure des besoins.

KnowledgeSourceReference

Objet

Référence à une source de connaissances.

Nom	Type	Description
enableFreshness	boolean	Indique si la récupération consciente de la fraîcheur doit être activée pour cette source de connaissances. Lorsque c’est vrai, un profil de notation de fraîcheur est appliqué lors de la récupération pour obtenir des résultats de biais vers des documents plus récents.
enableImageServing	boolean	Indique si la diffusion d’images doit être activée pour cette source de connaissances. Lorsque c’est vrai, les images extraites lors de l’ingestion sont transmises aux modèles en aval au moment de la requête.
name	string	Nom de la source de connaissances.

SearchIndexerDataNoneIdentity

Objet

Efface la propriété d’identité d’une source de données.

Nom	Type	Description
@odata.type	string: #Microsoft.Azure.Search.DataNoneIdentity	Fragment d’URI spécifiant le type d’identité.

SearchIndexerDataUserAssignedIdentity

Objet

Spécifie l’identité d’une source de données à utiliser.

Nom	Type	Description
@odata.type	string: #Microsoft.Azure.Search.DataUserAssignedIdentity	Fragment d’URI spécifiant le type d’identité.
federatedIdentityClientId	string	Support de l’identité gérée multi-locataire User-Assigned : l’identifiant client de l’application multi-tentant configurée pour fédérer avec l’identité managée attribuée par l’utilisateur.
userAssignedIdentity	string	Id de ressource Azure complet d’une identité managée affectée par l’utilisateur sous la forme « /subscriptions/12345678-1234-1234-1234-1234567890ab/resourceGroups/rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myId » qui doit avoir été affecté au service de recherche.

SearchResourceEncryptionKey

Objet

Clé de chiffrement gérée par le client dans Azure Key Vault. Les clés que vous créez et gérez peuvent être utilisées pour chiffrer ou déchiffrer des données au repos, telles que des index et des cartes de synonymes.

Nom	Type	Valeur par défaut	Description
accessCredentials.applicationId	string		ID d’application AAD qui a reçu les autorisations d’accès requises au coffre de clés Azure à utiliser lors du chiffrement de vos données au repos. L’ID d’application ne doit pas être confondu avec l’ID d’objet de votre application AAD.
accessCredentials.applicationSecret	string		Clé d’authentification de l’application AAD spécifiée.
identity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity		Identité managée explicite à utiliser pour cette clé de chiffrement. Si elle n’est pas spécifiée et que la propriété d’informations d’identification d’accès est null, l’identité managée affectée par le système est utilisée. Lors de la mise à jour vers la ressource, si l’identité explicite n’est pas spécifiée, elle reste inchangée. Si « none » est spécifié, la valeur de cette propriété est effacée.
isServiceLevelKey	boolean	False	Une valeur optionnelle indiquant si cette clé est une clé de niveau service. La valeur par défaut est false.
keyVaultKeyName	string		Nom de votre clé Azure Key Vault à utiliser pour chiffrer vos données au repos.
keyVaultKeyVersion	string		Version de votre clé Azure Key Vault à utiliser pour chiffrer vos données au repos.
keyVaultUri	string		URI de votre coffre de clés Azure, également appelé nom DNS, qui contient la clé à utiliser pour chiffrer vos données au repos. Un exemple d’URI peut être `https://my-keyvault-name.vault.azure.net`.