Knowledge Bases - Create Or Update

Servizio:: Search Service

Versione API:: 2025-11-01-preview

Crea una nuova knowledge base o aggiorna una knowledge base se esiste già.

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

Parametri dell'URI

Nome	In	Necessario	Tipo	Descrizione
endpoint	path	True	string (uri)	URL dell'endpoint del servizio di ricerca.
knowledgeBaseName	path	True	string	Nome della Knowledge Base.
api-version	query	True	string minLength: 1	Versione dell'API da usare per questa operazione.

Intestazione della richiesta

Nome	Necessario	Tipo	Descrizione
Accept		Accept	L'intestazione Accetta.
If-Match		string	Definisce la condizione di If-Match. L'operazione verrà eseguita solo se l'ETag sul server corrisponde a questo valore.
If-None-Match		string	Definisce la condizione If-None-Match. L'operazione verrà eseguita solo se l'ETag sul server non corrisponde a questo valore.
Prefer	True	Prefer	Per le richieste HTTP PUT, indica al servizio di restituire la risorsa creata/aggiornata in caso di esito positivo.
x-ms-client-request-id		string (uuid)	Identificatore di stringa opaco, univoco a livello globale e generato dal client per la richiesta.

Corpo della richiesta

Nome	Necessario	Tipo	Descrizione
knowledgeSources	True	KnowledgeSourceReference[]	Fonti di conoscenza citate da questa base di conoscenza.
name	True	string	Nome della Knowledge Base.
@odata.etag		string	L'ETag della base di conoscenza.
answerInstructions		string	Istruzioni considerate dalla knowledge base quando si generano risposte.
description		string	La descrizione della base di conoscenza.
encryptionKey		SearchResourceEncryptionKey	Descrizione di una chiave di crittografia creata in Azure Key Vault.
models		KnowledgeBaseModel[]: KnowledgeBaseAzureOpenAIModel[]	Contiene opzioni di configurazione su come connettersi ai modelli di intelligenza artificiale.
outputMode		KnowledgeRetrievalOutputMode	La modalità di output per la knowledge base.
retrievalInstructions		string	Istruzioni considerate dalla knowledge base durante lo sviluppo del query plan.
retrievalReasoningEffort		KnowledgeRetrievalReasoningEffort: KnowledgeRetrievalLowReasoningEffort KnowledgeRetrievalMediumReasoningEffort KnowledgeRetrievalMinimalReasoningEffort	La configurazione dello sforzo di ragionamento per il recupero.

Risposte

Nome	Tipo	Descrizione
200 OK	KnowledgeBase	La richiesta ha avuto esito positivo.
201 Created	KnowledgeBase	La richiesta ha avuto esito positivo e di conseguenza è stata creata una nuova risorsa.
Other Status Codes	ErrorResponse	Risposta di errore imprevista.

Sicurezza

api-key

Tipo: apiKey
In: header

OAuth2Auth

Tipo: oauth2
Flow: implicit
URL di autorizzazione: https://login.microsoftonline.com/common/oauth2/v2.0/authorize

Ambiti

Nome	Descrizione
https://search.azure.com/.default

Esempio

SearchServiceCreateOrUpdateKnowledgeBase

Esempio di richiesta

HTTP

PUT https://previewexampleservice.search.windows.net/knowledgebases('base-preview-test')?api-version=2025-11-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."
}

Risposta di esempio

Codice di stato:: 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"
  }
}

Codice di stato:: 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"
  }
}

Definizioni

Nome	Descrizione
Accept	L'intestazione Accetta.
AzureOpenAIModelName	Nome del modello Azure Open AI che verrà chiamato.
AzureOpenAIVectorizerParameters	Specifica i parametri per la connessione alla risorsa OpenAI di Azure.
ErrorAdditionalInfo	Informazioni aggiuntive sull'errore di gestione delle risorse.
ErrorDetail	Dettagli dell'errore.
ErrorResponse	Risposta di errore comune per tutte le API di Azure Resource Manager per restituire i dettagli dell'errore per le operazioni non riuscite. Questo segue anche il formato di risposta di errore OData.
KnowledgeBase	Rappresenta una definizione di base di conoscenza.
KnowledgeBaseAzureOpenAIModel	Specifica la risorsa Azure OpenAI usata per eseguire la pianificazione delle query.
KnowledgeBaseModelKind	Modello di intelligenza artificiale da utilizzare per la pianificazione delle query.
KnowledgeRetrievalLowReasoningEffort	Esegui il recupero delle conoscenze con un basso sforzo di ragionamento.
KnowledgeRetrievalMediumReasoningEffort	Esegui il recupero delle conoscenze con uno sforzo di ragionamento medio.
KnowledgeRetrievalMinimalReasoningEffort	Esegui il recupero delle conoscenze con il minimo sforzo di ragionamento.
KnowledgeRetrievalOutputMode	Configurazione dell'output per il recupero.
KnowledgeRetrievalReasoningEffortKind	Quantità di sforzo da utilizzare durante il recupero.
KnowledgeSourceReference	Riferimento a una fonte di conoscenza.
Prefer	Per le richieste HTTP PUT, indica al servizio di restituire la risorsa creata/aggiornata in caso di esito positivo.
SearchIndexerDataNoneIdentity	Cancella la proprietà Identity di un'origine dati.
SearchIndexerDataUserAssignedIdentity	Specifica l'identità di un'origine dati da usare.
SearchResourceEncryptionKey	Una chiave di crittografia gestita dal cliente in Azure Key Vault. Le chiavi create e gestite dall'utente possono essere utilizzate per crittografare o decrittografare i dati inattivi, ad esempio indici e mappe di sinonimi.

Accept

Enumerazione

L'intestazione Accetta.

Valore	Descrizione
application/json;odata.metadata=minimal

AzureOpenAIModelName

Enumerazione

Nome del modello Azure Open AI che verrà chiamato.

Valore	Descrizione
text-embedding-ada-002	Modello TextEmbeddingAda002.
text-embedding-3-large	TextEmbedding3Large model.
text-embedding-3-small	Modello Incorporato3Piccolo.
gpt-4o	Modello GPT4o.
gpt-4o-mini	Modello Gpt4oMini.
gpt-4.1	Modello GPT41.
gpt-4.1-mini	Modello GPT41Mini.
gpt-4.1-nano	Modello Gpt41Nano.
gpt-5	Modello GPT5.
gpt-5-mini	Modello GPT5Mini.
gpt-5-nano	Modello Gpt5Nano.

AzureOpenAIVectorizerParameters

Oggetto

Specifica i parametri per la connessione alla risorsa OpenAI di Azure.

Nome	Tipo	Descrizione
apiKey	string	Chiave API della risorsa OpenAI di Azure designata.
authIdentity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	Identità gestita assegnata dall'utente usata per le connessioni in uscita.
deploymentId	string	ID della distribuzione del modello OpenAI di Azure nella risorsa designata.
modelName	AzureOpenAIModelName	Nome del modello di incorporamento distribuito nel percorso deploymentId specificato.
resourceUri	string (uri)	URI della risorsa OpenAI di Azure.

ErrorAdditionalInfo

Oggetto

Informazioni aggiuntive sull'errore di gestione delle risorse.

Nome	Tipo	Descrizione
info		Informazioni aggiuntive.
type	string	Tipo di informazioni aggiuntive.

ErrorDetail

Oggetto

Dettagli dell'errore.

Nome	Tipo	Descrizione
additionalInfo	ErrorAdditionalInfo[]	Informazioni aggiuntive sull'errore.
code	string	Codice di errore.
details	ErrorDetail[]	Dettagli dell'errore.
message	string	Messaggio di errore.
target	string	Destinazione dell'errore.

ErrorResponse

Oggetto

Risposta di errore comune per tutte le API di Azure Resource Manager per restituire i dettagli dell'errore per le operazioni non riuscite. Questo segue anche il formato di risposta di errore OData.

Nome	Tipo	Descrizione
error	ErrorDetail	Oggetto error.

KnowledgeBase

Oggetto

Rappresenta una definizione di base di conoscenza.

Nome	Tipo	Descrizione
@odata.etag	string	L'ETag della base di conoscenza.
answerInstructions	string	Istruzioni considerate dalla knowledge base quando si generano risposte.
description	string	La descrizione della base di conoscenza.
encryptionKey	SearchResourceEncryptionKey	Descrizione di una chiave di crittografia creata in Azure Key Vault.
knowledgeSources	KnowledgeSourceReference[]	Fonti di conoscenza citate da questa base di conoscenza.
models	KnowledgeBaseModel[]: KnowledgeBaseAzureOpenAIModel[]	Contiene opzioni di configurazione su come connettersi ai modelli di intelligenza artificiale.
name	string	Nome della Knowledge Base.
outputMode	KnowledgeRetrievalOutputMode	La modalità di output per la knowledge base.
retrievalInstructions	string	Istruzioni considerate dalla knowledge base durante lo sviluppo del query plan.
retrievalReasoningEffort	KnowledgeRetrievalReasoningEffort: KnowledgeRetrievalLowReasoningEffort KnowledgeRetrievalMediumReasoningEffort KnowledgeRetrievalMinimalReasoningEffort	La configurazione dello sforzo di ragionamento per il recupero.

KnowledgeBaseAzureOpenAIModel

Oggetto

Specifica la risorsa Azure OpenAI usata per eseguire la pianificazione delle query.

Nome	Tipo	Descrizione
azureOpenAIParameters	AzureOpenAIVectorizerParameters	Parametri Azure OpenAI.
kind	string: azureOpenAI	Modello di intelligenza artificiale da utilizzare per la pianificazione delle query.

KnowledgeBaseModelKind

Enumerazione

Modello di intelligenza artificiale da utilizzare per la pianificazione delle query.

Valore	Descrizione
azureOpenAI	Usa i modelli di Azure Open AI per la pianificazione delle query.

KnowledgeRetrievalLowReasoningEffort

Oggetto

Esegui il recupero delle conoscenze con un basso sforzo di ragionamento.

Nome	Tipo	Descrizione
kind	string: low	Il tipo di sforzo di ragionamento.

KnowledgeRetrievalMediumReasoningEffort

Oggetto

Esegui il recupero delle conoscenze con uno sforzo di ragionamento medio.

Nome	Tipo	Descrizione
kind	string: medium	Il tipo di sforzo di ragionamento.

KnowledgeRetrievalMinimalReasoningEffort

Oggetto

Esegui il recupero delle conoscenze con il minimo sforzo di ragionamento.

Nome	Tipo	Descrizione
kind	string: minimal	Il tipo di sforzo di ragionamento.

KnowledgeRetrievalOutputMode

Enumerazione

Configurazione dell'output per il recupero.

Valore	Descrizione
extractiveData	Restituisci i dati direttamente dalle fonti di conoscenza senza alterazioni generative.
answerSynthesis	Sintetizzare una risposta per il payload della risposta.

KnowledgeRetrievalReasoningEffortKind

Enumerazione

Quantità di sforzo da utilizzare durante il recupero.

Valore	Descrizione
minimal	Non esegue alcuna selezione di origine, pianificazione delle query o ricerca iterativa.
low	Usa un ragionamento basso durante il recupero.
medium	Usa una moderata quantità di ragionamento durante il recupero.

KnowledgeSourceReference

Oggetto

Riferimento a una fonte di conoscenza.

Nome	Tipo	Descrizione
name	string	Il nome dell'origine della conoscenza.

Prefer

Enumerazione

Per le richieste HTTP PUT, indica al servizio di restituire la risorsa creata/aggiornata in caso di esito positivo.

Valore	Descrizione
return=representation

SearchIndexerDataNoneIdentity

Oggetto

Cancella la proprietà Identity di un'origine dati.

Nome	Tipo	Descrizione
@odata.type	string: #Microsoft.Azure.Search.DataNoneIdentity	Frammento di URI che specifica il tipo di identità.

SearchIndexerDataUserAssignedIdentity

Oggetto

Specifica l'identità di un'origine dati da usare.

Nome	Tipo	Descrizione
@odata.type	string: #Microsoft.Azure.Search.DataUserAssignedIdentity	Frammento di URI che specifica il tipo di identità.
userAssignedIdentity	string	L'ID risorsa di Azure completo di un'identità gestita assegnata all'utente, in genere nel formato "/subscriptions/12345678-1234-1234-1234-1234567890ab/resourceGroups/rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myId" che avrebbe dovuto essere assegnato al servizio di ricerca.

SearchResourceEncryptionKey

Oggetto

Una chiave di crittografia gestita dal cliente in Azure Key Vault. Le chiavi create e gestite dall'utente possono essere utilizzate per crittografare o decrittografare i dati inattivi, ad esempio indici e mappe di sinonimi.

Nome	Tipo	Descrizione
accessCredentials.applicationId	string	ID applicazione AAD a cui sono state concesse le autorizzazioni di accesso necessarie all'insieme di credenziali delle chiavi di Azure da usare durante la crittografia dei dati inattivi. L'ID applicazione non deve essere confuso con l'ID oggetto per l'applicazione AAD.
accessCredentials.applicationSecret	string	Chiave di autenticazione dell'applicazione AAD specificata.
identity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	Identità gestita esplicita da usare per questa chiave di crittografia. Se non specificato e la proprietà delle credenziali di accesso è Null, viene usata l'identità gestita assegnata dal sistema. Se l'identità esplicita non viene specificata, l'aggiornamento alla risorsa rimane invariato. Se si specifica "none", il valore di questa proprietà viene cancellato.
keyVaultKeyName	string	Nome della chiave di Azure Key Vault da usare per crittografare i dati inattivi.
keyVaultKeyVersion	string	Versione della chiave di Azure Key Vault da usare per crittografare i dati inattivi.
keyVaultUri	string	L'URI dell'insieme di credenziali delle chiavi di Azure, detto anche nome DNS, che contiene la chiave da usare per crittografare i dati inattivi. Un URI di esempio potrebbe essere `https://my-keyvault-name.vault.azure.net`.