Knowledge Bases - Create Or Update

Služba:: Search Service

Verze rozhraní API:: 2026-05-01-preview

Vytváří novou znalostní bázi nebo aktualizuje znalostní bázi, pokud už existuje.

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

Parametry identifikátoru URI

Name	V	Vyžadováno	Typ	Description
endpoint	path	True	string (uri)	Adresa URL koncového bodu vyhledávací služby.
knowledgeBaseName	path	True	string	Název znalostní báze.
api-version	query	True	string minLength: 1	Verze rozhraní API, která se má použít pro tuto operaci.

Hlavička požadavku

Name	Vyžadováno	Typ	Description
Accept		Accept	Hlavička Accept.
If-Match		string	Definuje podmínku If-Match. Operace bude provedena pouze v případě, že značka ETag na serveru odpovídá této hodnotě.
If-None-Match		string	Definuje podmínku If-None-Match. Operace bude provedena pouze v případě, že značky ETag na serveru neodpovídají této hodnotě.
Prefer	True	Prefer	U požadavků HTTP PUT dává pokyn službě, aby v případě úspěchu vrátila vytvořený/aktualizovaný prostředek.
x-ms-client-request-id		string (uuid)	Neprůzrný globálně jedinečný identifikátor řetězce vygenerovaný klientem pro požadavek.

Text požadavku

Name	Vyžadováno	Typ	Description
knowledgeSources	True	KnowledgeSourceReference[]	Znalostní zdroje odkazující v této znalostní bázi.
name	True	string	Název znalostní báze.
@odata.etag		string	Značka ETag znalostní báze.
answerInstructions		string	Instrukce zohledněné znalostní bází při generování odpovědí.
corsOptions		CorsOptions	Možnosti pro kontrolu sdílení zdrojů napříč původem (CORS) pro znalostní bázi.
description		string	Popis znalostní báze.
encryptionKey		SearchResourceEncryptionKey	Popis šifrovacího klíče, který vytvoříte v Azure Key Vault.
models		KnowledgeBaseModel[]: KnowledgeBaseAzureOpenAIModel[]	Obsahuje možnosti konfigurace, jak se připojit k modelům AI.
outputMode		KnowledgeRetrievalOutputMode	Výstupní režim znalostní báze.
retrievalInstructions		string	Instrukce zohledněné znalostní bází při tvorbě plánu dotazů.
retrievalReasoningEffort		KnowledgeRetrievalReasoningEffort: KnowledgeRetrievalLowReasoningEffort KnowledgeRetrievalMediumReasoningEffort KnowledgeRetrievalMinimalReasoningEffort	Konfigurace úsilí o vyhledávání a uvažování.

Odpovědi

Name	Typ	Description
200 OK	KnowledgeBase	Požadavek byl úspěšný.
201 Created	KnowledgeBase	Požadavek byl úspěšný a v důsledku toho byl vytvořen nový prostředek.
Other Status Codes	ErrorResponse	Neočekávaná chybová odpověď

Zabezpečení

api-key

Typ: apiKey
V: header

OAuth2Auth

Typ: oauth2
Tok: implicit
URL autorizace: https://login.microsoftonline.com/common/oauth2/v2.0/authorize

Rozsahy

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

Příklady

SearchServiceCreateOrUpdateKnowledgeBase

Ukázkový požadavek

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

Ukázková odpověď

Stavový kód:: 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
  }
}

Stavový kód:: 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
  }
}

Definice

Name	Description
Accept	Hlavička Accept.
AzureOpenAIModelName	Název modelu Azure Open AI, který se bude volat.
AzureOpenAIVectorizerParameters	Určuje parametry pro připojení k prostředku Azure OpenAI.
CorsOptions	Definuje možnosti pro řízení sdílení prostředků mezi zdroji (CORS) pro index.
ErrorAdditionalInfo	Další informace o chybě při správě prostředků
ErrorDetail	Podrobnosti o chybě.
ErrorResponse	Běžná chybová odpověď pro všechna rozhraní API Azure Resource Manageru pro vrácení podrobností o chybě pro neúspěšné operace (To se také řídí formátem odpovědi na chybu OData.)
KnowledgeBase	Představuje definici znalostní báze.
KnowledgeBaseAzureOpenAIModel	Určuje prostředek Azure OpenAI používaný k plánování dotazů.
KnowledgeBaseModelKind	Model umělé inteligence, který se má použít pro plánování dotazů.
KnowledgeRetrievalLowReasoningEffort	Provádějte načítání znalostí s nízkým úsilím při uvažování.
KnowledgeRetrievalMediumReasoningEffort	Spusťte získávání znalostí se středním úsilím při uvažování.
KnowledgeRetrievalMinimalReasoningEffort	Spouštějte načítání znalostí s minimálním úsilím při uvažování.
KnowledgeRetrievalOutputMode	Výstupní konfigurace pro toto načtení.
KnowledgeRetrievalReasoningEffortKind	Množství úsilí, které je třeba vynaložit při načítání.
KnowledgeSourceReference	Odkaz na zdroj znalostí.
Prefer	U požadavků HTTP PUT dává pokyn službě, aby v případě úspěchu vrátila vytvořený/aktualizovaný prostředek.
SearchIndexerDataNoneIdentity	Vymaže vlastnost identity zdroje dat.
SearchIndexerDataUserAssignedIdentity	Určuje identitu zdroje dat, která se má použít.
SearchResourceEncryptionKey	Šifrovací klíč spravovaný zákazníkem ve službě Azure Key Vault. Klíče, které vytvoříte a spravujete, lze použít k šifrování nebo dešifrování neaktivních uložených dat, jako jsou indexy a mapy synonym.

Accept

Výčet

Hlavička Accept.

Hodnota	Description
application/json;odata.metadata=minimal

AzureOpenAIModelName

Výčet

Název modelu Azure Open AI, který se bude volat.

Hodnota	Description
text-embedding-ada-002	Model TextEmbeddingAda002.
text-embedding-3-large	TextEmbedding3Large model.
text-embedding-3-small	Model TextEmbedding3Small.
gpt-4o	Model Gpt4o.
gpt-4o-mini	Model Gpt4oMini.
gpt-4.1	Model Gpt41.
gpt-4.1-mini	Model Gpt41Mini.
gpt-4.1-nano	Model Gpt41Nano.
gpt-5	Model GPT5.
gpt-5-mini	Model Gpt5Mini.
gpt-5-nano	Model Gpt5Nano.
gpt-5.1	Model GPT51.
gpt-5.2	Model Gpt52.
gpt-5.4	Model GPT54.
gpt-5.4-mini	Model Gpt54Mini.
gpt-5.4-nano	Model Gpt54Nano.
gpt-5.5	Model Gpt55.

AzureOpenAIVectorizerParameters

Objekt

Určuje parametry pro připojení k prostředku Azure OpenAI.

Name	Typ	Description
apiKey	string	Klíč rozhraní API určeného prostředku Azure OpenAI
authIdentity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	Spravovaná identita přiřazená uživatelem používaná pro odchozí připojení.
deploymentId	string	ID nasazení modelu Azure OpenAI v určeném prostředku
modelName	AzureOpenAIModelName	Název modelu vložení, který je nasazený na zadané cestě deploymentId.
resourceUri	string (uri)	Identifikátor URI prostředku Azure OpenAI.

CorsOptions

Objekt

Definuje možnosti pro řízení sdílení prostředků mezi zdroji (CORS) pro index.

Name	Typ	Description
allowedOrigins	string[]	Seznam zdrojů, ze kterých bude kódu JavaScript udělen přístup k vašemu indexu. Může obsahovat seznam hostitelů ve tvaru {protocol}://{fully-qualified-domain-name}[:{port#}] nebo jeden znak *, který povoluje všechny zdroje (nedoporučuje se).
maxAgeInSeconds	integer (int64)	Doba, po kterou by prohlížeče měly ukládat předběžné odpovědi CORS do mezipaměti. Výchozí hodnota je 5 minut.

ErrorAdditionalInfo

Objekt

Další informace o chybě při správě prostředků

Name	Typ	Description
info		Další informace.
type	string	Další typ informací.

ErrorDetail

Objekt

Podrobnosti o chybě.

Name	Typ	Description
additionalInfo	ErrorAdditionalInfo[]	Další informace o chybě.
code	string	Kód chyby.
details	ErrorDetail[]	Podrobnosti o chybě.
message	string	Chybová zpráva.
target	string	Cíl chyby.

ErrorResponse

Objekt

Běžná chybová odpověď pro všechna rozhraní API Azure Resource Manageru pro vrácení podrobností o chybě pro neúspěšné operace (To se také řídí formátem odpovědi na chybu OData.)

Name	Typ	Description
error	ErrorDetail	Objekt chyby.

KnowledgeBase

Objekt

Představuje definici znalostní báze.

Name	Typ	Description
@odata.etag	string	Značka ETag znalostní báze.
answerInstructions	string	Instrukce zohledněné znalostní bází při generování odpovědí.
corsOptions	CorsOptions	Možnosti pro kontrolu sdílení zdrojů napříč původem (CORS) pro znalostní bázi.
description	string	Popis znalostní báze.
encryptionKey	SearchResourceEncryptionKey	Popis šifrovacího klíče, který vytvoříte v Azure Key Vault.
knowledgeSources	KnowledgeSourceReference[]	Znalostní zdroje odkazující v této znalostní bázi.
models	KnowledgeBaseModel[]: KnowledgeBaseAzureOpenAIModel[]	Obsahuje možnosti konfigurace, jak se připojit k modelům AI.
name	string	Název znalostní báze.
outputMode	KnowledgeRetrievalOutputMode	Výstupní režim znalostní báze.
retrievalInstructions	string	Instrukce zohledněné znalostní bází při tvorbě plánu dotazů.
retrievalReasoningEffort	KnowledgeRetrievalReasoningEffort: KnowledgeRetrievalLowReasoningEffort KnowledgeRetrievalMediumReasoningEffort KnowledgeRetrievalMinimalReasoningEffort	Konfigurace úsilí o vyhledávání a uvažování.

KnowledgeBaseAzureOpenAIModel

Objekt

Určuje prostředek Azure OpenAI používaný k plánování dotazů.

Name	Typ	Description
azureOpenAIParameters	AzureOpenAIVectorizerParameters	Azure OpenAI parametry.
kind	string: azureOpenAI	Model umělé inteligence, který se má použít pro plánování dotazů.

KnowledgeBaseModelKind

Výčet

Model umělé inteligence, který se má použít pro plánování dotazů.

Hodnota	Description
azureOpenAI	K plánování dotazů používejte modely Azure Open AI.

KnowledgeRetrievalLowReasoningEffort

Objekt

Provádějte načítání znalostí s nízkým úsilím při uvažování.

Name	Typ	Description
kind	string: low	Druh úsilí o uvažování.

KnowledgeRetrievalMediumReasoningEffort

Objekt

Spusťte získávání znalostí se středním úsilím při uvažování.

Name	Typ	Description
kind	string: medium	Druh úsilí o uvažování.

KnowledgeRetrievalMinimalReasoningEffort

Objekt

Spouštějte načítání znalostí s minimálním úsilím při uvažování.

Name	Typ	Description
kind	string: minimal	Druh úsilí o uvažování.

KnowledgeRetrievalOutputMode

Výčet

Výstupní konfigurace pro toto načtení.

Hodnota	Description
extractiveData	Vraťte data ze zdrojů znalostí přímo bez generativních změn.
answerSynthesis	Syntetizuje odpověď pro datovou část odpovědi.

KnowledgeRetrievalReasoningEffortKind

Výčet

Množství úsilí, které je třeba vynaložit při načítání.

Hodnota	Description
minimal	Neprovádí žádné výběry zdrojů, plánování dotazů ani iterativní vyhledávání.
low	Při načítání používejte nízké uvažování.
medium	Při načítání používejte mírné množství uvažování.

KnowledgeSourceReference

Objekt

Odkaz na zdroj znalostí.

Name	Typ	Description
enableFreshness	boolean	Uvádí, zda by mělo být pro tento zdroj znalostí umožněno vyhledávání s ohledem na čerstvost. Pokud je to pravda, při vyhledávání se používá profil hodnocení čerstvosti, který zkresluje výsledky směrem k novějším dokumentům.
enableImageServing	boolean	Uvádí, zda by mělo být pro tento zdroj znalostí povoleno podávání obrazů. Pokud je to pravda, obrázky extrahované během ingesteru jsou doručeny modelům po proudu v době dotazu.
name	string	Název zdroje znalostí.

Prefer

Výčet

U požadavků HTTP PUT dává pokyn službě, aby v případě úspěchu vrátila vytvořený/aktualizovaný prostředek.

Hodnota	Description
return=representation

SearchIndexerDataNoneIdentity

Objekt

Vymaže vlastnost identity zdroje dat.

Name	Typ	Description
@odata.type	string: #Microsoft.Azure.Search.DataNoneIdentity	Fragment identifikátoru URI určující typ identity.

SearchIndexerDataUserAssignedIdentity

Objekt

Určuje identitu zdroje dat, která se má použít.

Name	Typ	Description
@odata.type	string: #Microsoft.Azure.Search.DataUserAssignedIdentity	Fragment identifikátoru URI určující typ identity.
federatedIdentityClientId	string	Multi-tenant User-Assigned Managed Identity Support: Klientské ID multi-tentant aplikace, které bylo nakonfigurováno tak, aby federovalo s uživatelem přiřazenou spravovanou identitou.
userAssignedIdentity	string	Plně kvalifikované ID prostředku Azure spravované identity přiřazené uživatelem obvykle ve formátu /subscriptions/12345678-1234-1234-1234-1234-1234567890ab/resourceGroups/rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myId, které by měly být přiřazeny vyhledávací službě.

SearchResourceEncryptionKey

Objekt

Šifrovací klíč spravovaný zákazníkem ve službě Azure Key Vault. Klíče, které vytvoříte a spravujete, lze použít k šifrování nebo dešifrování neaktivních uložených dat, jako jsou indexy a mapy synonym.

Name	Typ	Default value	Description
accessCredentials.applicationId	string		ID aplikace AAD, kterému byla udělena požadovaná přístupová oprávnění ke službě Azure Key Vault, která se má použít při šifrování neaktivních uložených dat. ID aplikace by nemělo být zaměňováno s ID objektu pro vaši aplikaci AAD.
accessCredentials.applicationSecret	string		Ověřovací klíč zadané aplikace AAD.
identity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity		Explicitní spravovaná identita, která se má použít pro tento šifrovací klíč. Pokud není zadána vlastnost přihlašovacích údajů přístupu null, použije se spravovaná identita přiřazená systémem. Při aktualizaci prostředku zůstane explicitní identita beze změny. Pokud je zadána hodnota "none", hodnota této vlastnosti je vymazána.
isServiceLevelKey	boolean	False	Volitelná hodnota označující, zda je tento klíč klíčem na úrovni služby. Výchozí hodnota je nastavená na false.
keyVaultKeyName	string		Název klíče služby Azure Key Vault, který se má použít k šifrování neaktivních uložených dat.
keyVaultKeyVersion	string		Verze klíče služby Azure Key Vault, která se má použít k šifrování neaktivních uložených dat.
keyVaultUri	string		Identifikátor URI služby Azure Key Vault, označovaný také jako název DNS, který obsahuje klíč, který se má použít k šifrování neaktivních uložených dat. Příkladem identifikátoru URI může být `https://my-keyvault-name.vault.azure.net`.