Knowledge Bases - Create Or Update

Tjänst:: Search Service

API-version:: 2026-05-01-preview

Skapar en ny kunskapsbas eller uppdaterar en kunskapsbas om den redan finns.

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

URI-parametrar

Name	I	Obligatorisk	Typ	Description
endpoint	path	True	string (uri)	Slutpunkts-URL:en för söktjänsten.
knowledgeBaseName	path	True	string	Namnet på kunskapsbasen.
api-version	query	True	string minLength: 1	Den API-version som ska användas för den här åtgärden.

Begärandehuvud

Name	Obligatorisk	Typ	Description
x-ms-client-request-id		string (uuid)	En ogenomskinlig, globalt unik, klientgenererad strängidentifierare för begäran.
Accept		Accept	Acceptera-rubriken.
If-Match		string	Definierar villkoret If-Match. Åtgärden utförs endast om ETag på servern matchar det här värdet.
If-None-Match		string	Definierar villkoret If-None-Match. Åtgärden utförs endast om ETag på servern inte matchar det här värdet.
Prefer	True	Prefer	För HTTP PUT-begäranden instruerar tjänsten att returnera den skapade/uppdaterade resursen när den lyckas.

Begärandetext

Name	Obligatorisk	Typ	Description
knowledgeSources	True	KnowledgeSourceReference[]	Kunskapskällor som refereras till i denna kunskapsbas.
name	True	string	Namnet på kunskapsbasen.
@odata.etag		string	ETag för kunskapsbasen.
answerInstructions		string	Instruktioner som beaktas av kunskapsbasen vid generering av svar.
corsOptions		CorsOptions	Alternativ för att kontrollera Cross-Origin Resource Sharing (CORS) för kunskapsbasen.
description		string	Beskrivningen av kunskapsbasen.
encryptionKey		SearchResourceEncryptionKey	En beskrivning av en krypteringsnyckel som du skapar i Azure Key Vault.
models		KnowledgeBaseModel[]: KnowledgeBaseAzureOpenAIModel[]	Innehåller konfigurationsalternativ för hur du ansluter till AI-modeller.
outputMode		KnowledgeRetrievalOutputMode	Utdataläget för kunskapsbasen.
retrievalInstructions		string	Instruktioner som beaktas av kunskapsbasen vid utveckling av frågeplan.
retrievalReasoningEffort		KnowledgeRetrievalReasoningEffort: KnowledgeRetrievalLowReasoningEffort KnowledgeRetrievalMediumReasoningEffort KnowledgeRetrievalMinimalReasoningEffort	Konfigurationen för återhämtningsresonemangsinsats.

Svar

Name	Typ	Description
200 OK	KnowledgeBase	Begäran har slutförts.
201 Created	KnowledgeBase	Begäran har slutförts och en ny resurs har skapats som ett resultat.
Other Status Codes	ErrorResponse	Ett oväntat felsvar.

Säkerhet

api-key

Typ: apiKey
I: header

OAuth2Auth

Typ: oauth2
Flow: implicit
Auktoriseringswebbadress: https://login.microsoftonline.com/common/oauth2/v2.0/authorize

Omfattningar

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

Exempel

SearchServiceCreateOrUpdateKnowledgeBase

Exempelbegäran

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

Exempelsvar

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

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

Definitioner

Name	Description
Accept	Acceptera-rubriken.
AzureOpenAIModelName	Namnet på Azure Open AI-modellen som ska anropas.
AzureOpenAIVectorizerParameters	Anger parametrarna för att ansluta till Azure OpenAI-resursen.
CorsOptions	Definierar alternativ för att styra resursdelning mellan ursprung (CORS) för ett index.
ErrorAdditionalInfo	Ytterligare information om resurshanteringsfelet.
ErrorDetail	Felinformationen.
ErrorResponse	Vanligt felsvar för alla Azure Resource Manager-API:er för att returnera felinformation för misslyckade åtgärder. (Detta följer även formatet för OData-felsvar.).
KnowledgeBase	Representerar en definition av kunskapsbasen.
KnowledgeBaseAzureOpenAIModel	Anger den Azure OpenAI-resurs som används för att göra frågeplanering.
KnowledgeBaseModelKind	AI-modellen som ska användas för frågeplanering.
KnowledgeRetrievalLowReasoningEffort	Kör kunskapshämtning med låg ansträngning för att resonera.
KnowledgeRetrievalMediumReasoningEffort	Kör kunskapshämtning med medelhög ansträngning för resonemang.
KnowledgeRetrievalMinimalReasoningEffort	Kör kunskapshämtning med minimal ansträngning för att resonera.
KnowledgeRetrievalOutputMode	Utdatakonfigurationen för den här hämtningen.
KnowledgeRetrievalReasoningEffortKind	Mängden ansträngning som ska användas under hämtningen.
KnowledgeSourceReference	Referens till en kunskapskälla.
Prefer	För HTTP PUT-begäranden instruerar tjänsten att returnera den skapade/uppdaterade resursen när den lyckas.
SearchIndexerDataNoneIdentity	Rensar identitetsegenskapen för en datakälla.
SearchIndexerDataUserAssignedIdentity	Anger identiteten för en datakälla som ska användas.
SearchResourceEncryptionKey	En kundhanterad krypteringsnyckel i Azure Key Vault. Nycklar som du skapar och hanterar kan användas för att kryptera eller dekryptera vilande data, till exempel index och synonymmappningar.

Accept

Uppräkning

Acceptera-rubriken.

Värde	Description
application/json;odata.metadata=minimal

AzureOpenAIModelName

Uppräkning

Namnet på Azure Open AI-modellen som ska anropas.

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

AzureOpenAIVectorizerParameters

Objekt

Anger parametrarna för att ansluta till Azure OpenAI-resursen.

Name	Typ	Description
apiKey	string	API-nyckeln för den avsedda Azure OpenAI-resursen.
authIdentity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	Den användartilldelade hanterade identiteten som används för utgående anslutningar.
deploymentId	string	ID för Azure OpenAI-modelldistributionen på den avsedda resursen.
modelName	AzureOpenAIModelName	Namnet på den inbäddningsmodell som distribueras på den angivna deploymentId-sökvägen.
resourceUri	string (uri)	Resurs-URI för Azure OpenAI-resursen.

CorsOptions

Objekt

Definierar alternativ för att styra resursdelning mellan ursprung (CORS) för ett index.

Name	Typ	Description
allowedOrigins	string[]	Listan över ursprung som JavaScript-koden ska beviljas åtkomst till ditt index från. Kan innehålla en lista över värdar i formatet {protocol}://{fully-qualified-domain-name}[:{port#}], eller en enda "*" för att tillåta alla ursprung (rekommenderas inte).
maxAgeInSeconds	integer (int64)	Den varaktighet under vilken webbläsare ska cachelagra CORS-preflight-svar. Standardvärdet är 5 minuter.

ErrorAdditionalInfo

Objekt

Ytterligare information om resurshanteringsfelet.

Name	Typ	Description
info		Ytterligare information.
type	string	Ytterligare informationstyp.

ErrorDetail

Objekt

Felinformationen.

Name	Typ	Description
additionalInfo	ErrorAdditionalInfo[]	Ytterligare information om felet.
code	string	Felkoden.
details	ErrorDetail[]	Felinformationen.
message	string	Felmeddelandet.
target	string	Felmålet.

ErrorResponse

Objekt

Vanligt felsvar för alla Azure Resource Manager-API:er för att returnera felinformation för misslyckade åtgärder. (Detta följer även formatet för OData-felsvar.).

Name	Typ	Description
error	ErrorDetail	Felobjektet.

KnowledgeBase

Objekt

Representerar en definition av kunskapsbasen.

Name	Typ	Description
@odata.etag	string	ETag för kunskapsbasen.
answerInstructions	string	Instruktioner som beaktas av kunskapsbasen vid generering av svar.
corsOptions	CorsOptions	Alternativ för att kontrollera Cross-Origin Resource Sharing (CORS) för kunskapsbasen.
description	string	Beskrivningen av kunskapsbasen.
encryptionKey	SearchResourceEncryptionKey	En beskrivning av en krypteringsnyckel som du skapar i Azure Key Vault.
knowledgeSources	KnowledgeSourceReference[]	Kunskapskällor som refereras till i denna kunskapsbas.
models	KnowledgeBaseModel[]: KnowledgeBaseAzureOpenAIModel[]	Innehåller konfigurationsalternativ för hur du ansluter till AI-modeller.
name	string	Namnet på kunskapsbasen.
outputMode	KnowledgeRetrievalOutputMode	Utdataläget för kunskapsbasen.
retrievalInstructions	string	Instruktioner som beaktas av kunskapsbasen vid utveckling av frågeplan.
retrievalReasoningEffort	KnowledgeRetrievalReasoningEffort: KnowledgeRetrievalLowReasoningEffort KnowledgeRetrievalMediumReasoningEffort KnowledgeRetrievalMinimalReasoningEffort	Konfigurationen för återhämtningsresonemangsinsats.

KnowledgeBaseAzureOpenAIModel

Objekt

Anger den Azure OpenAI-resurs som används för att göra frågeplanering.

Name	Typ	Description
azureOpenAIParameters	AzureOpenAIVectorizerParameters	Azure OpenAI-parametrar.
kind	string: azureOpenAI	AI-modellen som ska användas för frågeplanering.

KnowledgeBaseModelKind

Uppräkning

AI-modellen som ska användas för frågeplanering.

Värde	Description
azureOpenAI	Använd Azure Open AI-modeller för frågeplanering.

KnowledgeRetrievalLowReasoningEffort

Objekt

Kör kunskapshämtning med låg ansträngning för att resonera.

Name	Typ	Description
kind	string: low	Den sortens resonemangsförsök.

KnowledgeRetrievalMediumReasoningEffort

Objekt

Kör kunskapshämtning med medelhög ansträngning för resonemang.

Name	Typ	Description
kind	string: medium	Den sortens resonemangsförsök.

KnowledgeRetrievalMinimalReasoningEffort

Objekt

Kör kunskapshämtning med minimal ansträngning för att resonera.

Name	Typ	Description
kind	string: minimal	Den sortens resonemangsförsök.

KnowledgeRetrievalOutputMode

Uppräkning

Utdatakonfigurationen för den här hämtningen.

Värde	Description
extractiveData	Returnera data från kunskapskällorna direkt utan generativ förändring.
answerSynthesis	Syntetisera ett svar för svarsnyttolasten.

KnowledgeRetrievalReasoningEffortKind

Uppräkning

Mängden ansträngning som ska användas under hämtningen.

Värde	Description
minimal	Utför inga källval, frågeplanering eller iterativ sökning.
low	Använd lågt resonemang under hämtningen.
medium	Använd en måttlig mängd resonemang under hämtningen.

KnowledgeSourceReference

Objekt

Referens till en kunskapskälla.

Name	Typ	Description
enableFreshness	boolean	Indikerar om färskhetsmedveten återvinning bör aktiveras för denna kunskapskälla. När det stämmer tillämpas en färskhetspoängsprofil vid hämtningen för att snedvrida resultat mot nyare dokument.
enableImageServing	boolean	Anger om bildservering bör aktiveras för denna kunskapskälla. När de är sanna levereras bilder som extraheras under inmatning till nedströmsmodeller vid frågetillfället.
name	string	Namnet på kunskapskällan.

Prefer

Uppräkning

För HTTP PUT-begäranden instruerar tjänsten att returnera den skapade/uppdaterade resursen när den lyckas.

Värde	Description
return=representation

SearchIndexerDataNoneIdentity

Objekt

Rensar identitetsegenskapen för en datakälla.

Name	Typ	Description
@odata.type	string: #Microsoft.Azure.Search.DataNoneIdentity	Ett URI-fragment som anger typen av identitet.

SearchIndexerDataUserAssignedIdentity

Objekt

Anger identiteten för en datakälla som ska användas.

Name	Typ	Description
@odata.type	string: #Microsoft.Azure.Search.DataUserAssignedIdentity	Ett URI-fragment som anger typen av identitet.
federatedIdentityClientId	string	Multi-tenant User-Assigned Managed Identity Support: Klient-ID:t för den multi-tentant-appen som har konfigurerats för att federera med den användartilldelade hanterade identiteten.
userAssignedIdentity	string	Det fullständigt kvalificerade Azure-resurs-ID:t för en användartilldelad hanterad identitet, vanligtvis i formuläret "/subscriptions/12345678-1234-1234-1234567890ab/resourceGroups/rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myId" som borde ha tilldelats söktjänsten.

SearchResourceEncryptionKey

Objekt

En kundhanterad krypteringsnyckel i Azure Key Vault. Nycklar som du skapar och hanterar kan användas för att kryptera eller dekryptera vilande data, till exempel index och synonymmappningar.

Name	Typ	Standardvärde	Description
accessCredentials.applicationId	string		Ett AAD-program-ID som har beviljats nödvändiga åtkomstbehörigheter till Azure Key Vault som ska användas när du krypterar dina data i vila. Program-ID:t bör inte förväxlas med objekt-ID:t för ditt AAD-program.
accessCredentials.applicationSecret	string		Autentiseringsnyckeln för det angivna AAD-programmet.
identity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity		En explicit hanterad identitet som ska användas för den här krypteringsnyckeln. Om det inte anges och egenskapen för åtkomstautentiseringsuppgifter är null används den systemtilldelade hanterade identiteten. Om den explicita identiteten är ospecificerad vid uppdatering av resursen förblir den oförändrad. Om "ingen" anges rensas värdet för den här egenskapen.
isServiceLevelKey	boolean	False	Ett valfritt värde som anger om denna nyckel är en servicenivånyckel. Standardvärdet är false.
keyVaultKeyName	string		Namnet på din Azure Key Vault-nyckel som ska användas för att kryptera dina vilande data.
keyVaultKeyVersion	string		Den version av Azure Key Vault-nyckeln som ska användas för att kryptera dina vilande data.
keyVaultUri	string		URI:n för ditt Azure Key Vault, även kallat DNS-namn, som innehåller nyckeln som ska användas för att kryptera dina data i vila. Ett exempel på en URI kan vara `https://my-keyvault-name.vault.azure.net`.