Knowledge Bases - Create Or Update

Service:: Search Service

API-versie:: 2026-05-01-preview

Maakt een nieuwe kennisbank aan of werkt een kennisbank bij als die al bestaat.

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

URI-parameters

Name	In	Vereist	Type	Description
endpoint	path	True	string (uri)	De eindpunt-URL van de zoekservice.
knowledgeBaseName	path	True	string	De naam van de kennisbank.
api-version	query	True	string minLength: 1	De API-versie die voor deze bewerking moet worden gebruikt.

Aanvraagkoptekst

Name	Vereist	Type	Description
Accept		Accept	De Accepteer kop.
If-Match		string	Hiermee definieert u de voorwaarde If-Match. De bewerking wordt alleen uitgevoerd als de ETag op de server overeenkomt met deze waarde.
If-None-Match		string	Definieert de voorwaarde If-None-Match. De bewerking wordt alleen uitgevoerd als de ETag op de server niet overeenkomt met deze waarde.
Prefer	True	Prefer	Voor HTTP PUT-aanvragen geeft u de service de opdracht om de gemaakte/bijgewerkte resource te retourneren als deze is geslaagd.
x-ms-client-request-id		string (uuid)	Een ondoorzichtige, wereldwijd unieke, door de client gegenereerde tekenreeks-id voor de aanvraag.

Aanvraagbody

Name	Vereist	Type	Description
knowledgeSources	True	KnowledgeSourceReference[]	Kennisbronnen die door deze kennisbasis worden aangehaald.
name	True	string	De naam van de kennisbank.
@odata.etag		string	De ETag van de kennisbank.
answerInstructions		string	Instructies die door de kennisbank worden meegenomen bij het genereren van antwoorden.
corsOptions		CorsOptions	Opties om Cross-Origin Resource Sharing (CORS) voor de kennisbank te beheren.
description		string	De beschrijving van de kennisbank.
encryptionKey		SearchResourceEncryptionKey	Een beschrijving van een versleutelingssleutel die u in Azure Key Vault maakt.
models		KnowledgeBaseModel[]: KnowledgeBaseAzureOpenAIModel[]	Bevat configuratieopties voor het maken van verbinding met AI-modellen.
outputMode		KnowledgeRetrievalOutputMode	De uitvoermodus voor de kennisbasis.
retrievalInstructions		string	Instructies die door de kennisbank worden meegenomen bij het ontwikkelen van queryplannen.
retrievalReasoningEffort		KnowledgeRetrievalReasoningEffort: KnowledgeRetrievalLowReasoningEffort KnowledgeRetrievalMediumReasoningEffort KnowledgeRetrievalMinimalReasoningEffort	De configuratie van de ophaal-redeneerinspanning.

Antwoorden

Name	Type	Description
200 OK	KnowledgeBase	De aanvraag is voltooid.
201 Created	KnowledgeBase	De aanvraag is geslaagd en er is een nieuwe resource gemaakt.
Other Status Codes	ErrorResponse	Een onverwachte foutreactie.

Beveiliging

api-key

Type: apiKey
In: header

OAuth2Auth

Type: oauth2
Stroom: implicit
Autorisatie-URL: https://login.microsoftonline.com/common/oauth2/v2.0/authorize

Bereiken

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

Voorbeelden

SearchServiceCreateOrUpdateKnowledgeBase

Voorbeeldaanvraag

HTTP

PUT https://previewexampleservice.search.windows.net/knowledgebases('base-preview-test')?api-version=2026-05-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.",
  "corsOptions": {
    "allowedOrigins": [
      "https://myapp.example.com"
    ],
    "maxAgeInSeconds": 300
  }
}

Voorbeeldrespons

Statuscode:: 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"
  },
  "corsOptions": {
    "allowedOrigins": [
      "https://myapp.example.com"
    ],
    "maxAgeInSeconds": 300
  }
}

Statuscode:: 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"
  },
  "corsOptions": {
    "allowedOrigins": [
      "https://myapp.example.com"
    ],
    "maxAgeInSeconds": 300
  }
}

Definities

Name	Description
Accept	De Accepteer kop.
AzureOpenAIModelName	De Azure Open AI-modelnaam die wordt aangeroepen.
AzureOpenAIVectorizerParameters	Hiermee geeft u de parameters voor het maken van verbinding met de Azure OpenAI-resource.
CorsOptions	Hiermee definieert u opties voor het beheren van CORS (Cross-Origin Resource Sharing) voor een index.
ErrorAdditionalInfo	Aanvullende informatie over de resourcebeheerfout.
ErrorDetail	Het foutdetail.
ErrorResponse	Veelvoorkomende foutreactie voor alle Azure Resource Manager-API's om foutdetails te retourneren voor mislukte bewerkingen. (Dit volgt ook de OData-foutreactieindeling.)
KnowledgeBase	Vertegenwoordigt een definitie van een kennisbasis.
KnowledgeBaseAzureOpenAIModel	Hiermee geeft u de Azure OpenAI-resource op die wordt gebruikt om queryplanning uit te voeren.
KnowledgeBaseModelKind	Het AI-model dat moet worden gebruikt voor queryplanning.
KnowledgeRetrievalLowReasoningEffort	Voer het ophalen van kennis uit met weinig redeneerinspanning.
KnowledgeRetrievalMediumReasoningEffort	Voer het ophalen van kennis uit met gemiddelde redeneerinspanning.
KnowledgeRetrievalMinimalReasoningEffort	Voer het ophalen van kennis uit met minimale redeneerinspanning.
KnowledgeRetrievalOutputMode	De uitvoerconfiguratie voor dit ophalen.
KnowledgeRetrievalReasoningEffortKind	De hoeveelheid inspanning die moet worden gebruikt tijdens het ophalen.
KnowledgeSourceReference	Verwijs naar een kennisbron.
Prefer	Voor HTTP PUT-aanvragen geeft u de service de opdracht om de gemaakte/bijgewerkte resource te retourneren als deze is geslaagd.
SearchIndexerDataNoneIdentity	Hiermee wist u de identiteitseigenschap van een gegevensbron.
SearchIndexerDataUserAssignedIdentity	Hiermee geeft u de identiteit op voor een gegevensbron die moet worden gebruikt.
SearchResourceEncryptionKey	Een door de klant beheerde versleutelingssleutel in Azure Key Vault. Sleutels die u maakt en beheert, kunnen worden gebruikt om inactieve gegevens, zoals indexen en synoniementoewijzingen, te versleutelen of te ontsleutelen.

Accept

Opsomming

De Accepteer kop.

Waarde	Description
application/json;odata.metadata=minimal

AzureOpenAIModelName

Opsomming

De Azure Open AI-modelnaam die wordt aangeroepen.

Waarde	Description
text-embedding-ada-002	TextEmbeddingAda002 model.
text-embedding-3-large	TextEmbedding3Groot model.
text-embedding-3-small	TextEmbedding3Small-model.
gpt-4o	Gpt4o model.
gpt-4o-mini	Gpt4oMini model.
gpt-4.1	Gpt41-model.
gpt-4.1-mini	Gpt41Mini model.
gpt-4.1-nano	Gpt41Nano-model.
gpt-5	Gpt5-model.
gpt-5-mini	Gpt5Mini model.
gpt-5-nano	Gpt5Nano-model.
gpt-5.1	Gpt51 model.
gpt-5.2	Gpt52-model.
gpt-5.4	Gpt54 model.
gpt-5.4-mini	Gpt54Mini model.
gpt-5.4-nano	Gpt54Nano model.
gpt-5.5	Gpt55 model.

AzureOpenAIVectorizerParameters

Object

Hiermee geeft u de parameters voor het maken van verbinding met de Azure OpenAI-resource.

Name	Type	Description
apiKey	string	API-sleutel van de aangewezen Azure OpenAI-resource.
authIdentity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	De door de gebruiker toegewezen beheerde identiteit die wordt gebruikt voor uitgaande verbindingen.
deploymentId	string	ID van de implementatie van het Azure OpenAI-model op de aangewezen resource.
modelName	AzureOpenAIModelName	De naam van het insluitmodel dat is geïmplementeerd op het opgegeven deploymentId-pad.
resourceUri	string (uri)	De resource-URI van de Azure OpenAI-resource.

CorsOptions

Object

Hiermee definieert u opties voor het beheren van CORS (Cross-Origin Resource Sharing) voor een index.

Name	Type	Description
allowedOrigins	string[]	De lijst met herkomsten van waaruit JavaScript-code toegang krijgt tot uw index. Kan een lijst met hosts van de vorm {protocol}://{fully-qualified-domain-name}[:{port#}] bevatten, of een enkele '*' om alle origines toe te staan (niet aanbevolen).
maxAgeInSeconds	integer (int64)	De duur waarvoor browsers CORS preflight-antwoorden in de cache moeten opslaan. Standaard ingesteld op 5 minuten.

ErrorAdditionalInfo

Object

Aanvullende informatie over de resourcebeheerfout.

Name	Type	Description
info		De aanvullende informatie.
type	string	Het extra informatietype.

ErrorDetail

Object

Het foutdetail.

Name	Type	Description
additionalInfo	ErrorAdditionalInfo[]	Aanvullende informatie over de fout.
code	string	De foutcode.
details	ErrorDetail[]	De foutgegevens.
message	string	Het foutbericht.
target	string	Het foutdoelwit.

ErrorResponse

Object

Veelvoorkomende foutreactie voor alle Azure Resource Manager-API's om foutdetails te retourneren voor mislukte bewerkingen. (Dit volgt ook de OData-foutreactieindeling.)

Name	Type	Description
error	ErrorDetail	Het foutobject.

KnowledgeBase

Object

Vertegenwoordigt een definitie van een kennisbasis.

Name	Type	Description
@odata.etag	string	De ETag van de kennisbank.
answerInstructions	string	Instructies die door de kennisbank worden meegenomen bij het genereren van antwoorden.
corsOptions	CorsOptions	Opties om Cross-Origin Resource Sharing (CORS) voor de kennisbank te beheren.
description	string	De beschrijving van de kennisbank.
encryptionKey	SearchResourceEncryptionKey	Een beschrijving van een versleutelingssleutel die u in Azure Key Vault maakt.
knowledgeSources	KnowledgeSourceReference[]	Kennisbronnen die door deze kennisbasis worden aangehaald.
models	KnowledgeBaseModel[]: KnowledgeBaseAzureOpenAIModel[]	Bevat configuratieopties voor het maken van verbinding met AI-modellen.
name	string	De naam van de kennisbank.
outputMode	KnowledgeRetrievalOutputMode	De uitvoermodus voor de kennisbasis.
retrievalInstructions	string	Instructies die door de kennisbank worden meegenomen bij het ontwikkelen van queryplannen.
retrievalReasoningEffort	KnowledgeRetrievalReasoningEffort: KnowledgeRetrievalLowReasoningEffort KnowledgeRetrievalMediumReasoningEffort KnowledgeRetrievalMinimalReasoningEffort	De configuratie van de ophaal-redeneerinspanning.

KnowledgeBaseAzureOpenAIModel

Object

Hiermee geeft u de Azure OpenAI-resource op die wordt gebruikt om queryplanning uit te voeren.

Name	Type	Description
azureOpenAIParameters	AzureOpenAIVectorizerParameters	Azure OpenAI parameters.
kind	string: azureOpenAI	Het AI-model dat moet worden gebruikt voor queryplanning.

KnowledgeBaseModelKind

Opsomming

Het AI-model dat moet worden gebruikt voor queryplanning.

Waarde	Description
azureOpenAI	Gebruik Azure Open AI-modellen voor het plannen van query's.

KnowledgeRetrievalLowReasoningEffort

Object

Voer het ophalen van kennis uit met weinig redeneerinspanning.

Name	Type	Description
kind	string: low	Het soort redeneerinspanning.

KnowledgeRetrievalMediumReasoningEffort

Object

Voer het ophalen van kennis uit met gemiddelde redeneerinspanning.

Name	Type	Description
kind	string: medium	Het soort redeneerinspanning.

KnowledgeRetrievalMinimalReasoningEffort

Object

Voer het ophalen van kennis uit met minimale redeneerinspanning.

Name	Type	Description
kind	string: minimal	Het soort redeneerinspanning.

KnowledgeRetrievalOutputMode

Opsomming

De uitvoerconfiguratie voor dit ophalen.

Waarde	Description
extractiveData	Retourneer gegevens uit de kennisbronnen direct zonder generatieve wijziging.
answerSynthesis	Synthetiseer een antwoord voor de payload van het antwoord.

KnowledgeRetrievalReasoningEffortKind

Opsomming

De hoeveelheid inspanning die moet worden gebruikt tijdens het ophalen.

Waarde	Description
minimal	Voert geen bronselecties, queryplanning of iteratieve zoekopdrachten uit.
low	Gebruik een lage redenering tijdens het ophalen.
medium	Gebruik een matige hoeveelheid redeneren tijdens het ophalen.

KnowledgeSourceReference

Object

Verwijs naar een kennisbron.

Name	Type	Description
enableFreshness	boolean	Geeft aan of versheidsbewuste retrieval voor deze kennisbron moet worden ingeschakeld. Wanneer het waar is, wordt tijdens het ophalen een freshness scoring profiel toegepast om resultaten te bevoordelen ten gunste van nieuwere documenten.
enableImageServing	boolean	Geeft aan of beeldservering ingeschakeld moet worden voor deze kennisbron. Wanneer het waar is, worden de tijdens het innemen extraheren van afbeeldingen bij de query aan downstream-modellen geleverd.
name	string	De naam van de kennisbron.

Prefer

Opsomming

Voor HTTP PUT-aanvragen geeft u de service de opdracht om de gemaakte/bijgewerkte resource te retourneren als deze is geslaagd.

Waarde	Description
return=representation

SearchIndexerDataNoneIdentity

Object

Hiermee wist u de identiteitseigenschap van een gegevensbron.

Name	Type	Description
@odata.type	string: #Microsoft.Azure.Search.DataNoneIdentity	Een URI-fragment dat het type identiteit specificeert.

SearchIndexerDataUserAssignedIdentity

Object

Hiermee geeft u de identiteit op voor een gegevensbron die moet worden gebruikt.

Name	Type	Description
@odata.type	string: #Microsoft.Azure.Search.DataUserAssignedIdentity	Een URI-fragment dat het type identiteit specificeert.
federatedIdentityClientId	string	Multi-tenant User-Assigned Managed Identity Support: De client-id van de multi-tentant app die is geconfigureerd om te federeren met de door de gebruiker toegewezen beheerde identiteit.
userAssignedIdentity	string	De volledig gekwalificeerde Azure-resource-id van een door de gebruiker toegewezen beheerde identiteit, meestal in de vorm '/subscriptions/12345678-1234-1234-1234567890ab/resourceGroups/rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myId' die aan de zoekservice moet zijn toegewezen.

SearchResourceEncryptionKey

Object

Een door de klant beheerde versleutelingssleutel in Azure Key Vault. Sleutels die u maakt en beheert, kunnen worden gebruikt om inactieve gegevens, zoals indexen en synoniementoewijzingen, te versleutelen of te ontsleutelen.

Name	Type	Default value	Description
accessCredentials.applicationId	string		Een AAD-toepassings-id waaraan de vereiste toegangsmachtigingen zijn verleend voor de Azure Key Vault die moet worden gebruikt bij het versleutelen van uw data-at-rest. De toepassings-id mag niet worden verward met de object-id voor uw AAD-toepassing.
accessCredentials.applicationSecret	string		De verificatiesleutel van de opgegeven AAD-toepassing.
identity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity		Een expliciete beheerde identiteit die moet worden gebruikt voor deze versleutelingssleutel. Als dit niet is opgegeven en de eigenschap toegangsreferenties null is, wordt de door het systeem toegewezen beheerde identiteit gebruikt. Bij het bijwerken van de resource, als de expliciete identiteit niet is opgegeven, blijft deze ongewijzigd. Als 'geen' is opgegeven, wordt de waarde van deze eigenschap gewist.
isServiceLevelKey	boolean	False	Een optionele waarde die aangeeft of deze sleutel een serviceniveausleutel is. De standaardwaarde is vals.
keyVaultKeyName	string		De naam van uw Azure Key Vault-sleutel die moet worden gebruikt om uw data-at-rest te versleutelen.
keyVaultKeyVersion	string		De versie van uw Azure Key Vault-sleutel die moet worden gebruikt om uw data-at-rest te versleutelen.
keyVaultUri	string		De URI van uw Azure Key Vault, ook wel DNS-naam genoemd, die de sleutel bevat die moet worden gebruikt voor het versleutelen van uw data-at-rest. Een voorbeeld van een URI kan `https://my-keyvault-name.vault.azure.net`zijn.