Knowledge Bases - Create

Служба:: Search Service

Версия API:: 2026-05-01-preview

Создает новую базу знаний.

POST {endpoint}/knowledgebases?api-version=2026-05-01-preview

Параметры URI

Имя	В	Обязательно	Тип	Описание
endpoint	path	True	string (uri)	URL-адрес конечной точки службы поиска.
api-version	query	True	string minLength: 1	Версия API, используемая для данной операции.

Заголовок запроса

Имя	Обязательно	Тип	Описание
Accept		Accept	Заголовок Accept.
x-ms-client-request-id		string (uuid)	Непрозрачный, глобально уникальный, созданный клиентом идентификатор строки для запроса.

Текст запроса

Имя	Обязательно	Тип	Описание
knowledgeSources	True	KnowledgeSourceReference[]	Источники знаний, на которые ссылается эта база знаний.
name	True	string	Название базы знаний.
@odata.etag		string	ETag базы знаний.
answerInstructions		string	Инструкции, учитываемые базой знаний при генерации ответов.
corsOptions		CorsOptions	Опции управления обменом ресурсами между истоками (CORS) для базы знаний.
description		string	Описание базы знаний.
encryptionKey		SearchResourceEncryptionKey	Описание ключа шифрования, созданного в Azure Key Vault.
models		KnowledgeBaseModel[]: KnowledgeBaseAzureOpenAIModel[]	Содержит параметры конфигурации для подключения к моделям ИИ.
outputMode		KnowledgeRetrievalOutputMode	Выходной режим для базы знаний.
retrievalInstructions		string	Инструкции, учитываемые базой знаний при разработке плана запроса.
retrievalReasoningEffort		KnowledgeRetrievalReasoningEffort: KnowledgeRetrievalLowReasoningEffort KnowledgeRetrievalMediumReasoningEffort KnowledgeRetrievalMinimalReasoningEffort	Конфигурация усилия рассуждения для поиска.

Ответы

Имя	Тип	Описание
201 Created	KnowledgeBase	Запрос успешно выполнен, и в результате был создан новый ресурс.
Other Status Codes	ErrorResponse	Непредвиденное сообщение об ошибке.

Безопасность

api-key

Тип: apiKey
В: header

OAuth2Auth

Тип: oauth2
Flow: implicit
URL-адрес авторизации: https://login.microsoftonline.com/common/oauth2/v2.0/authorize

Области

Имя	Описание
https://search.azure.com/.default

Примеры

SearchServiceCreateKnowledgeBase

Образец запроса

HTTP

POST https://previewexampleservice.search.windows.net/knowledgebases?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-4.1-nano"
      },
      "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
  }
}

Пример ответа

Код состояния:: 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-4.1-nano"
      }
    }
  ],
  "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
  }
}

Определения

Имя	Описание
Accept	Заголовок Accept.
AzureOpenAIModelName	Имя модели Azure Open AI, которое будет вызываться.
AzureOpenAIVectorizerParameters	Задает параметры для подключения к ресурсу Azure OpenAI.
CorsOptions	Определяет параметры управления общим доступом к ресурсам между источниками (CORS) для индекса.
ErrorAdditionalInfo	Дополнительные сведения об ошибке управления ресурсами.
ErrorDetail	Подробности ошибки.
ErrorResponse	Распространенный ответ об ошибке для всех API Azure Resource Manager для возврата сведений об ошибке для неудачных операций. (Это также следует формату ответа об ошибках OData.).
KnowledgeBase	Представляет собой определение базы знаний.
KnowledgeBaseAzureOpenAIModel	Указывает ресурс Azure OpenAI, используемый для планирования запросов.
KnowledgeBaseModelKind	Модель ИИ, которая будет использоваться для планирования запросов.
KnowledgeRetrievalLowReasoningEffort	Выполняйте извлечение знаний с минимальными усилиями по рассуждениям.
KnowledgeRetrievalMediumReasoningEffort	Выполняйте извлечение знаний со средними усилиями на рассуждение.
KnowledgeRetrievalMinimalReasoningEffort	Выполняйте извлечение знаний с минимальными усилиями по рассуждениям.
KnowledgeRetrievalOutputMode	Конфигурация выходных данных для этого извлечения.
KnowledgeRetrievalReasoningEffortKind	Количество усилий, затрачиваемых во время извлечения.
KnowledgeSourceReference	Ссылка на источник знаний.
SearchIndexerDataNoneIdentity	Очищает свойство удостоверения источника данных.
SearchIndexerDataUserAssignedIdentity	Указывает удостоверение для используемого источника данных.
SearchResourceEncryptionKey	Ключ шифрования, управляемый клиентом, в Azure Key Vault. Ключи, которые вы создаете и которыми управляете, можно использовать для шифрования или расшифровки хранимых данных, таких как индексы и сопоставления синонимов.

Accept

Перечисление

Заголовок Accept.

Значение	Описание
application/json;odata.metadata=minimal

AzureOpenAIModelName

Перечисление

Имя модели Azure Open AI, которое будет вызываться.

Значение	Описание
text-embedding-ada-002	TextEmbeddingAda002 модель.
text-embedding-3-large	TextEmbedding3Большая модель.
text-embedding-3-small	TextEmbedding3Малая модель.
gpt-4o	Модель gpt4o.
gpt-4o-mini	Модель Gpt4oMini.
gpt-4.1	Модель GPT41.
gpt-4.1-mini	Модель GPT41Mini.
gpt-4.1-nano	Модель Gpt41Nano.
gpt-5	Модель GPT5.
gpt-5-mini	Модель Gpt5Mini.
gpt-5-nano	Модель Gpt5Nano.
gpt-5.1	Модель GPT51.
gpt-5.2	Модель GPT52.
gpt-5.4	Модель GPT54.
gpt-5.4-mini	Модель GPT54Mini.
gpt-5.4-nano	Модель Gpt54Nano.
gpt-5.5	Модель GPT55.

AzureOpenAIVectorizerParameters

Объект

Задает параметры для подключения к ресурсу Azure OpenAI.

Имя	Тип	Описание
apiKey	string	Ключ API указанного ресурса Azure OpenAI.
authIdentity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	Назначаемое пользователем управляемое удостоверение, используемое для исходящих подключений.
deploymentId	string	Идентификатор развертывания модели Azure OpenAI в указанном ресурсе.
modelName	AzureOpenAIModelName	Имя модели внедрения, развернутой по указанному пути deploymentId.
resourceUri	string (uri)	URI ресурса ресурса Azure OpenAI.

CorsOptions

Объект

Определяет параметры управления общим доступом к ресурсам между источниками (CORS) для индекса.

Имя	Тип	Описание
allowedOrigins	string[]	Список источников, из которых коду JavaScript будет предоставлен доступ к вашему индексу. Может содержать список хостов вида {protocol}://{fully-qualified-domain-name}[:{port#}], или один '*' для разрешения всех источников (не рекомендуется).
maxAgeInSeconds	integer (int64)	Продолжительность, в течение которой браузеры должны кэшировать ответы CORS перед проверкой. По умолчанию 5 минут.

ErrorAdditionalInfo

Объект

Дополнительные сведения об ошибке управления ресурсами.

Имя	Тип	Описание
info		Дополнительные сведения.
type	string	Тип дополнительных сведений.

ErrorDetail

Объект

Подробности ошибки.

Имя	Тип	Описание
additionalInfo	ErrorAdditionalInfo[]	Дополнительные сведения об ошибке.
code	string	Код ошибки.
details	ErrorDetail[]	Сведения об ошибке.
message	string	Сообщение об ошибке.
target	string	Целевой объект ошибки.

ErrorResponse

Объект

Распространенный ответ об ошибке для всех API Azure Resource Manager для возврата сведений об ошибке для неудачных операций. (Это также следует формату ответа об ошибках OData.).

Имя	Тип	Описание
error	ErrorDetail	Объект ошибки.

KnowledgeBase

Объект

Представляет собой определение базы знаний.

Имя	Тип	Описание
@odata.etag	string	ETag базы знаний.
answerInstructions	string	Инструкции, учитываемые базой знаний при генерации ответов.
corsOptions	CorsOptions	Опции управления обменом ресурсами между истоками (CORS) для базы знаний.
description	string	Описание базы знаний.
encryptionKey	SearchResourceEncryptionKey	Описание ключа шифрования, созданного в Azure Key Vault.
knowledgeSources	KnowledgeSourceReference[]	Источники знаний, на которые ссылается эта база знаний.
models	KnowledgeBaseModel[]: KnowledgeBaseAzureOpenAIModel[]	Содержит параметры конфигурации для подключения к моделям ИИ.
name	string	Название базы знаний.
outputMode	KnowledgeRetrievalOutputMode	Выходной режим для базы знаний.
retrievalInstructions	string	Инструкции, учитываемые базой знаний при разработке плана запроса.
retrievalReasoningEffort	KnowledgeRetrievalReasoningEffort: KnowledgeRetrievalLowReasoningEffort KnowledgeRetrievalMediumReasoningEffort KnowledgeRetrievalMinimalReasoningEffort	Конфигурация усилия рассуждения для поиска.

KnowledgeBaseAzureOpenAIModel

Объект

Указывает ресурс Azure OpenAI, используемый для планирования запросов.

Имя	Тип	Описание
azureOpenAIParameters	AzureOpenAIVectorizerParameters	Azure OpenAI parameters.
kind	string: azureOpenAI	Модель ИИ, которая будет использоваться для планирования запросов.

KnowledgeBaseModelKind

Перечисление

Модель ИИ, которая будет использоваться для планирования запросов.

Значение	Описание
azureOpenAI	Используйте модели Azure Open AI для планирования запросов.

KnowledgeRetrievalLowReasoningEffort

Объект

Выполняйте извлечение знаний с минимальными усилиями по рассуждениям.

Имя	Тип	Описание
kind	string: low	Своего рода попытка рассуждения.

KnowledgeRetrievalMediumReasoningEffort

Объект

Выполняйте извлечение знаний со средними усилиями на рассуждение.

Имя	Тип	Описание
kind	string: medium	Своего рода попытка рассуждения.

KnowledgeRetrievalMinimalReasoningEffort

Объект

Выполняйте извлечение знаний с минимальными усилиями по рассуждениям.

Имя	Тип	Описание
kind	string: minimal	Своего рода попытка рассуждения.

KnowledgeRetrievalOutputMode

Перечисление

Конфигурация выходных данных для этого извлечения.

Значение	Описание
extractiveData	Возвращайте данные из источников знаний напрямую без генеративного изменения.
answerSynthesis	Синтезируйте ответ для полезной нагрузки ответа.

KnowledgeRetrievalReasoningEffortKind

Перечисление

Количество усилий, затрачиваемых во время извлечения.

Значение	Описание
minimal	Не выполняет выбор источников, планирование запросов или итеративный поиск.
low	Используйте низкое рассуждение во время поиска.
medium	Используйте умеренное количество рассуждений во время поиска.

KnowledgeSourceReference

Объект

Ссылка на источник знаний.

Имя	Тип	Описание
enableFreshness	boolean	Указывает, следует ли включать поиск с учётом свежести для этого источника знаний. Если это верно, при извлечении применяется профиль оценки свежести для смещения результатов в пользу новых документов.
enableImageServing	boolean	Указывает, следует ли включать подачу изображений для этого источника знаний. Когда это верно, изображения, извлеченные во время загрузки, передаются в последующие модели во время запроса.
name	string	Название источника знаний.

SearchIndexerDataNoneIdentity

Объект

Очищает свойство удостоверения источника данных.

Имя	Тип	Описание
@odata.type	string: #Microsoft.Azure.Search.DataNoneIdentity	Фрагмент URI, указывающий тип удостоверения.

SearchIndexerDataUserAssignedIdentity

Объект

Указывает удостоверение для используемого источника данных.

Имя	Тип	Описание
@odata.type	string: #Microsoft.Azure.Search.DataUserAssignedIdentity	Фрагмент URI, указывающий тип удостоверения.
federatedIdentityClientId	string	Многоарендная User-Assigned управляемая поддержка идентичности: идентификатор клиента многостороннего приложения, настроенного для федерации с управляемой идентичностью, назначенной пользователем.
userAssignedIdentity	string	Полный идентификатор ресурса Azure назначаемого пользователем управляемого удостоверения обычно в форме "/subscriptions/12345678-1234-1234-1234-1234567890ab/resourceGroups/rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myId", который должен быть назначен службе поиска.

SearchResourceEncryptionKey

Объект

Ключ шифрования, управляемый клиентом, в Azure Key Vault. Ключи, которые вы создаете и которыми управляете, можно использовать для шифрования или расшифровки хранимых данных, таких как индексы и сопоставления синонимов.

Имя	Тип	Значение по умолчанию	Описание
accessCredentials.applicationId	string		Идентификатор приложения AAD, которому было предоставлено необходимые разрешения на доступ к Azure Key Vault, который будет использоваться при шифровании неактивных данных. Идентификатор приложения не следует путать с идентификатором объекта для приложения AAD.
accessCredentials.applicationSecret	string		Ключ проверки подлинности указанного приложения AAD.
identity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity		Явное управляемое удостоверение, используемое для этого ключа шифрования. Если не указано, а свойство учетных данных доступа равно NULL, используется управляемое удостоверение, назначаемое системой. При обновлении ресурса, если явное удостоверение не указано, оно остается неизменным. Если задано значение none, то значение этого свойства очищается.
isServiceLevelKey	boolean	False	Необязательное значение, указывающее, является ли этот ключ ключом уровня сервиса. По умолчанию — false.
keyVaultKeyName	string		Имя ключа Azure Key Vault, используемого для шифрования неактивных данных.
keyVaultKeyVersion	string		Версия ключа Azure Key Vault, используемая для шифрования неактивных данных.
keyVaultUri	string		Универсальный код ресурса (URI) Хранилища ключей Azure, который также называется DNS-именем, который содержит ключ, используемый для шифрования неактивных данных. Пример URI может быть `https://my-keyvault-name.vault.azure.net`.