Knowledge Bases - Create Or Update

Usługa:: Search Service

Wersja interfejsu API:: 2025-11-01-preview

Tworzy nową bazę wiedzy lub aktualizuje ją, jeśli już istnieje.

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

Parametry identyfikatora URI

Nazwa	W	Wymagane	Typ	Opis
endpoint	path	True	string (uri)	Adres URL punktu końcowego usługi wyszukiwania.
knowledgeBaseName	path	True	string	Nazwa bazy wiedzy.
api-version	query	True	string minLength: 1	Wersja interfejsu API do użycia dla tej operacji.

Nagłówek żądania

Nazwa	Wymagane	Typ	Opis
Accept		Accept	Nagłówek Accept.
If-Match		string	Definiuje warunek If-Match. Operacja zostanie wykonana tylko wtedy, gdy element ETag na serwerze jest zgodny z tą wartością.
If-None-Match		string	Definiuje warunek If-None-Match. Operacja zostanie wykonana tylko wtedy, gdy element ETag na serwerze nie jest zgodny z tą wartością.
Prefer	True	Prefer	W przypadku żądań HTTP PUT instruuje usługę, aby zwróciła utworzony/zaktualizowany zasób w przypadku powodzenia.
x-ms-client-request-id		string (uuid)	Nieprzezroczystym, globalnie unikatowym identyfikatorem ciągu generowanego przez klienta dla żądania.

Treść żądania

Nazwa	Wymagane	Typ	Opis
knowledgeSources	True	KnowledgeSourceReference[]	Źródła wiedzy odwoływane przez tę bazę wiedzy.
name	True	string	Nazwa bazy wiedzy.
@odata.etag		string	Element ETag bazy wiedzy.
answerInstructions		string	Instrukcje uwzględniane przez bazę wiedzy podczas generowania odpowiedzi.
description		string	Opis bazy wiedzy.
encryptionKey		SearchResourceEncryptionKey	Opis klucza szyfrowania utworzonego w usłudze Azure Key Vault.
models		KnowledgeBaseModel[]: KnowledgeBaseAzureOpenAIModel[]	Zawiera opcje konfiguracji dotyczące sposobu nawiązywania połączenia z modelami AI.
outputMode		KnowledgeRetrievalOutputMode	Tryb wyjściowy bazy wiedzy.
retrievalInstructions		string	Instrukcje brane pod uwagę w bazie wiedzy podczas opracowywania planu zapytań.
retrievalReasoningEffort		KnowledgeRetrievalReasoningEffort: KnowledgeRetrievalLowReasoningEffort KnowledgeRetrievalMediumReasoningEffort KnowledgeRetrievalMinimalReasoningEffort	Konfiguracja wysiłku rozumowania wyszukiwania.

Odpowiedzi

Nazwa	Typ	Opis
200 OK	KnowledgeBase	Żądanie zakończyło się pomyślnie.
201 Created	KnowledgeBase	Żądanie zakończyło się pomyślnie i w rezultacie został utworzony nowy zasób.
Other Status Codes	ErrorResponse	Nieoczekiwana odpowiedź na błąd.

Zabezpieczenia

api-key

Typ: apiKey
W: header

OAuth2Auth

Typ: oauth2
Flow: implicit
Adres URL autoryzacji: https://login.microsoftonline.com/common/oauth2/v2.0/authorize

Zakresy

Nazwa	Opis
https://search.azure.com/.default

Przykłady

SearchServiceCreateOrUpdateKnowledgeBase

Przykładowe żądanie

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

Przykładowa odpowiedź

Kod stanu:: 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"
  }
}

Kod stanu:: 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"
  }
}

Definicje

Nazwa	Opis
Accept	Nagłówek Accept.
AzureOpenAIModelName	Nazwa modelu Azure Open AI, który zostanie wywołany.
AzureOpenAIVectorizerParameters	Określa parametry nawiązywania połączenia z zasobem usługi Azure OpenAI.
ErrorAdditionalInfo	Dodatkowe informacje o błędzie zarządzania zasobami.
ErrorDetail	Szczegóły błędu.
ErrorResponse	Typowa odpowiedź na błędy dla wszystkich interfejsów API usługi Azure Resource Manager w celu zwrócenia szczegółów błędu dla operacji, które zakończyły się niepowodzeniem. (Jest to również zgodne z formatem odpowiedzi na błąd OData).
KnowledgeBase	Reprezentuje definicję bazy wiedzy.
KnowledgeBaseAzureOpenAIModel	Określa zasób usługi Azure OpenAI używany do planowania zapytań.
KnowledgeBaseModelKind	Model sztucznej inteligencji, który ma być używany do planowania zapytań.
KnowledgeRetrievalLowReasoningEffort	Uruchamiaj pobieranie wiedzy przy niewielkim wysiłku związanym z rozumowaniem.
KnowledgeRetrievalMediumReasoningEffort	Uruchamianie wyszukiwania wiedzy ze średnim wysiłkiem rozumowania.
KnowledgeRetrievalMinimalReasoningEffort	Uruchamiaj wyszukiwanie wiedzy przy minimalnym wysiłku związanym z rozumowaniem.
KnowledgeRetrievalOutputMode	Konfiguracja wyjściowa dla tego pobierania.
KnowledgeRetrievalReasoningEffortKind	Ilość wysiłku do użycia podczas pobierania.
KnowledgeSourceReference	Odniesienie do źródła wiedzy.
Prefer	W przypadku żądań HTTP PUT instruuje usługę, aby zwróciła utworzony/zaktualizowany zasób w przypadku powodzenia.
SearchIndexerDataNoneIdentity	Czyści właściwość tożsamości źródła danych.
SearchIndexerDataUserAssignedIdentity	Określa tożsamość źródła danych do użycia.
SearchResourceEncryptionKey	Klucz szyfrowania zarządzany przez klienta w usłudze Azure Key Vault. Klucze, które tworzysz i którymi zarządzasz, mogą służyć do szyfrowania lub odszyfrowywania danych magazynowanych, takich jak indeksy i mapy synonimów.

Accept

Wyliczenie

Nagłówek Accept.

Wartość	Opis
application/json;odata.metadata=minimal

AzureOpenAIModelName

Wyliczenie

Nazwa modelu Azure Open AI, który zostanie wywołany.

Wartość	Opis
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.

AzureOpenAIVectorizerParameters

Objekt

Określa parametry nawiązywania połączenia z zasobem usługi Azure OpenAI.

Nazwa	Typ	Opis
apiKey	string	Klucz interfejsu API wyznaczonego zasobu usługi Azure OpenAI.
authIdentity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	Tożsamość zarządzana przypisana przez użytkownika używana na potrzeby połączeń wychodzących.
deploymentId	string	Identyfikator wdrożenia modelu Usługi Azure OpenAI w wyznaczonym zasobie.
modelName	AzureOpenAIModelName	Nazwa modelu osadzania wdrożonego w podanej ścieżce deploymentId.
resourceUri	string (uri)	Identyfikator URI zasobu usługi Azure OpenAI.

ErrorAdditionalInfo

Objekt

Dodatkowe informacje o błędzie zarządzania zasobami.

Nazwa	Typ	Opis
info		Dodatkowe informacje.
type	string	Dodatkowy typ informacji.

ErrorDetail

Objekt

Szczegóły błędu.

Nazwa	Typ	Opis
additionalInfo	ErrorAdditionalInfo[]	Dodatkowe informacje o błędzie.
code	string	Kod błędu.
details	ErrorDetail[]	Szczegóły błędu.
message	string	Komunikat o błędzie.
target	string	Element docelowy błędu.

ErrorResponse

Objekt

Typowa odpowiedź na błędy dla wszystkich interfejsów API usługi Azure Resource Manager w celu zwrócenia szczegółów błędu dla operacji, które zakończyły się niepowodzeniem. (Jest to również zgodne z formatem odpowiedzi na błąd OData).

Nazwa	Typ	Opis
error	ErrorDetail	Obiekt błędu.

KnowledgeBase

Objekt

Reprezentuje definicję bazy wiedzy.

Nazwa	Typ	Opis
@odata.etag	string	Element ETag bazy wiedzy.
answerInstructions	string	Instrukcje uwzględniane przez bazę wiedzy podczas generowania odpowiedzi.
description	string	Opis bazy wiedzy.
encryptionKey	SearchResourceEncryptionKey	Opis klucza szyfrowania utworzonego w usłudze Azure Key Vault.
knowledgeSources	KnowledgeSourceReference[]	Źródła wiedzy odwoływane przez tę bazę wiedzy.
models	KnowledgeBaseModel[]: KnowledgeBaseAzureOpenAIModel[]	Zawiera opcje konfiguracji dotyczące sposobu nawiązywania połączenia z modelami AI.
name	string	Nazwa bazy wiedzy.
outputMode	KnowledgeRetrievalOutputMode	Tryb wyjściowy bazy wiedzy.
retrievalInstructions	string	Instrukcje brane pod uwagę w bazie wiedzy podczas opracowywania planu zapytań.
retrievalReasoningEffort	KnowledgeRetrievalReasoningEffort: KnowledgeRetrievalLowReasoningEffort KnowledgeRetrievalMediumReasoningEffort KnowledgeRetrievalMinimalReasoningEffort	Konfiguracja wysiłku rozumowania wyszukiwania.

KnowledgeBaseAzureOpenAIModel

Objekt

Określa zasób usługi Azure OpenAI używany do planowania zapytań.

Nazwa	Typ	Opis
azureOpenAIParameters	AzureOpenAIVectorizerParameters	Azure OpenAI parametry.
kind	string: azureOpenAI	Model sztucznej inteligencji, który ma być używany do planowania zapytań.

KnowledgeBaseModelKind

Wyliczenie

Model sztucznej inteligencji, który ma być używany do planowania zapytań.

Wartość	Opis
azureOpenAI	Używanie modeli sztucznej inteligencji usługi Azure Open do planowania zapytań.

KnowledgeRetrievalLowReasoningEffort

Objekt

Uruchamiaj pobieranie wiedzy przy niewielkim wysiłku związanym z rozumowaniem.

Nazwa	Typ	Opis
kind	string: low	Rodzaj wysiłku rozumowania.

KnowledgeRetrievalMediumReasoningEffort

Objekt

Uruchamianie wyszukiwania wiedzy ze średnim wysiłkiem rozumowania.

Nazwa	Typ	Opis
kind	string: medium	Rodzaj wysiłku rozumowania.

KnowledgeRetrievalMinimalReasoningEffort

Objekt

Uruchamiaj wyszukiwanie wiedzy przy minimalnym wysiłku związanym z rozumowaniem.

Nazwa	Typ	Opis
kind	string: minimal	Rodzaj wysiłku rozumowania.

KnowledgeRetrievalOutputMode

Wyliczenie

Konfiguracja wyjściowa dla tego pobierania.

Wartość	Opis
extractiveData	Zwracanie danych ze źródeł wiedzy bezpośrednio bez generatywnych zmian.
answerSynthesis	Zsyntetyzuj odpowiedź dla ładunku odpowiedzi.

KnowledgeRetrievalReasoningEffortKind

Wyliczenie

Ilość wysiłku do użycia podczas pobierania.

Wartość	Opis
minimal	Nie wykonuje żadnych wyborów źródłowych, planowania zapytań ani wyszukiwania iteracyjnego.
low	Używaj niskiego rozumowania podczas pobierania.
medium	Używaj umiarkowanej ilości rozumowania podczas pobierania.

KnowledgeSourceReference

Objekt

Odniesienie do źródła wiedzy.

Nazwa	Typ	Opis
name	string	Nazwa źródła wiedzy.

Prefer

Wyliczenie

W przypadku żądań HTTP PUT instruuje usługę, aby zwróciła utworzony/zaktualizowany zasób w przypadku powodzenia.

Wartość	Opis
return=representation

SearchIndexerDataNoneIdentity

Objekt

Czyści właściwość tożsamości źródła danych.

Nazwa	Typ	Opis
@odata.type	string: #Microsoft.Azure.Search.DataNoneIdentity	Fragment identyfikatora URI określający typ tożsamości.

SearchIndexerDataUserAssignedIdentity

Objekt

Określa tożsamość źródła danych do użycia.

Nazwa	Typ	Opis
@odata.type	string: #Microsoft.Azure.Search.DataUserAssignedIdentity	Fragment identyfikatora URI określający typ tożsamości.
userAssignedIdentity	string	W pełni kwalifikowany identyfikator zasobu platformy Azure tożsamości zarządzanej przypisanej przez użytkownika zwykle w postaci "/subscriptions/12345678-1234-1234-1234-1234567890ab/resourceGroups/rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myId", który powinien zostać przypisany do usługi wyszukiwania.

SearchResourceEncryptionKey

Objekt

Klucz szyfrowania zarządzany przez klienta w usłudze Azure Key Vault. Klucze, które tworzysz i którymi zarządzasz, mogą służyć do szyfrowania lub odszyfrowywania danych magazynowanych, takich jak indeksy i mapy synonimów.

Nazwa	Typ	Opis
accessCredentials.applicationId	string	Identyfikator aplikacji usługi AAD, któremu udzielono wymaganych uprawnień dostępu do usługi Azure Key Vault, która ma być używana podczas szyfrowania danych magazynowanych. Identyfikator aplikacji nie powinien być mylony z identyfikatorem obiektu aplikacji usługi AAD.
accessCredentials.applicationSecret	string	Klucz uwierzytelniania określonej aplikacji usługi AAD.
identity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	Jawna tożsamość zarządzana używana dla tego klucza szyfrowania. Jeśli nie zostanie określona, a właściwość poświadczeń dostępu ma wartość null, zostanie użyta tożsamość zarządzana przypisana przez system. Po zaktualizowaniu zasobu, jeśli tożsamość jawna jest nieokreślona, pozostaje niezmieniona. Jeśli określono wartość "none", wartość tej właściwości zostanie wyczyszczone.
keyVaultKeyName	string	Nazwa klucza usługi Azure Key Vault, który ma być używany do szyfrowania danych magazynowanych.
keyVaultKeyVersion	string	Wersja klucza usługi Azure Key Vault, która ma być używana do szyfrowania danych magazynowanych.
keyVaultUri	string	Identyfikator URI usługi Azure Key Vault, nazywany również nazwą DNS, który zawiera klucz używany do szyfrowania danych magazynowanych. Przykładowy identyfikator URI może być `https://my-keyvault-name.vault.azure.net`.