Knowledge Bases - Create

Servicio:: Search Service

Versión de la API:: 2026-05-01-preview

Crea una nueva base de conocimientos.

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

Parámetros de identificador URI

Nombre	En	Requerido	Tipo	Description
endpoint	path	True	string (uri)	La dirección URL del punto de conexión del servicio de búsqueda.
api-version	query	True	string minLength: 1	Versión de la API que se va a usar para esta operación.

Encabezado de la solicitud

Nombre	Requerido	Tipo	Description
Accept		Accept	El encabezado Aceptar.
x-ms-client-request-id		string (uuid)	Identificador de cadena globalmente único y generado por el cliente para la solicitud.

Cuerpo de la solicitud

Nombre	Requerido	Tipo	Description
knowledgeSources	True	KnowledgeSourceReference[]	Fuentes de conocimiento referenciadas por esta base de conocimiento.
name	True	string	Nombre de la base de conocimiento.
@odata.etag		string	La ETag de la base de conocimiento.
answerInstructions		string	Instrucciones consideradas por la base de conocimiento al generar respuestas.
corsOptions		CorsOptions	Opciones para controlar el Intercambio de Recursos entre Orígenes (CORS) para la base de conocimiento.
description		string	La descripción de la base de conocimientos.
encryptionKey		SearchResourceEncryptionKey	Descripción de una clave de cifrado que se crea en Azure Key Vault.
models		KnowledgeBaseModel[]: KnowledgeBaseAzureOpenAIModel[]	Contiene opciones de configuración sobre cómo conectarse a modelos de IA.
outputMode		KnowledgeRetrievalOutputMode	El modo de salida para la base de conocimiento.
retrievalInstructions		string	Instrucciones consideradas por la base de conocimiento al desarrollar el plan de consulta.
retrievalReasoningEffort		KnowledgeRetrievalReasoningEffort: KnowledgeRetrievalLowReasoningEffort KnowledgeRetrievalMediumReasoningEffort KnowledgeRetrievalMinimalReasoningEffort	La configuración del esfuerzo de razonamiento de recuperación.

Respuestas

Nombre	Tipo	Description
201 Created	KnowledgeBase	La solicitud se ha realizado correctamente y se ha creado un nuevo recurso como resultado.
Other Status Codes	ErrorResponse	Una respuesta de error inesperada.

Seguridad

api-key

Tipo: apiKey
En: header

OAuth2Auth

Tipo: oauth2
Flujo: implicit
Dirección URL de autorización: https://login.microsoftonline.com/common/oauth2/v2.0/authorize

Ámbitos

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

Ejemplos

SearchServiceCreateKnowledgeBase

Solicitud de ejemplo

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

Respuesta de muestra

status code:: 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
  }
}

Definiciones

Nombre	Description
Accept	El encabezado Aceptar.
AzureOpenAIModelName	Nombre del modelo de Azure Open AI al que se llamará.
AzureOpenAIVectorizerParameters	Especifica los parámetros para conectarse al recurso de Azure OpenAI.
CorsOptions	Define las opciones para controlar el uso compartido de recursos entre orígenes (CORS) para un índice.
ErrorAdditionalInfo	Información adicional sobre el error de administración de recursos.
ErrorDetail	Detalle del error.
ErrorResponse	Respuesta de error común para todas las API de Azure Resource Manager para devolver los detalles de error de las operaciones con errores. (Esto también sigue el formato de respuesta de error de OData).
KnowledgeBase	Representa una definición de base de conocimiento.
KnowledgeBaseAzureOpenAIModel	Especifica el recurso de Azure OpenAI que se usa para realizar la planeación de consultas.
KnowledgeBaseModelKind	El modelo de IA que se utilizará para la planificación de consultas.
KnowledgeRetrievalLowReasoningEffort	Ejecute la recuperación de conocimientos con poco esfuerzo de razonamiento.
KnowledgeRetrievalMediumReasoningEffort	Ejecute la recuperación de conocimientos con un esfuerzo de razonamiento medio.
KnowledgeRetrievalMinimalReasoningEffort	Realiza la recuperación de conocimiento con un esfuerzo mínimo de razonamiento.
KnowledgeRetrievalOutputMode	La configuración de salida para esta recuperación.
KnowledgeRetrievalReasoningEffortKind	La cantidad de esfuerzo que se debe utilizar durante la recuperación.
KnowledgeSourceReference	Referencia a una fuente de conocimiento.
SearchIndexerDataNoneIdentity	Borra la propiedad de identidad de un origen de datos.
SearchIndexerDataUserAssignedIdentity	Especifica la identidad de un origen de datos que se va a usar.
SearchResourceEncryptionKey	Una clave de cifrado administrada por el cliente en Azure Key Vault. Las claves que crea y administra se pueden usar para cifrar o descifrar datos en reposo, como índices y mapas de sinónimos.

Accept

Enumeración

El encabezado Aceptar.

Valor	Description
application/json;odata.metadata=minimal

AzureOpenAIModelName

Enumeración

Nombre del modelo de Azure Open AI al que se llamará.

Valor	Description
text-embedding-ada-002	TextEmbeddingAda002 modelo.
text-embedding-3-large	TextEmbedding3 Modelo grande.
text-embedding-3-small	TextoEmbede3Modelo pequeño.
gpt-4o	Modelo GPT4o.
gpt-4o-mini	Modelo Gpt4oMini.
gpt-4.1	Modelo GPT41.
gpt-4.1-mini	Modelo Gpt41Mini.
gpt-4.1-nano	Modelo Gpt41Nano.
gpt-5	Modelo GPT5.
gpt-5-mini	Modelo Gpt5Mini.
gpt-5-nano	Modelo Gpt5Nano.
gpt-5.1	Modelo GPT51.
gpt-5.2	Modelo GPT52.
gpt-5.4	Modelo GPT54.
gpt-5.4-mini	Modelo GPT54Mini.
gpt-5.4-nano	Modelo Gpt54Nano.
gpt-5.5	Modelo GPT55.

AzureOpenAIVectorizerParameters

Objeto

Especifica los parámetros para conectarse al recurso de Azure OpenAI.

Nombre	Tipo	Description
apiKey	string	Clave de API del recurso de Azure OpenAI designado.
authIdentity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	La identidad administrada asignada por el usuario que se usa para las conexiones salientes.
deploymentId	string	Identificador de la implementación del modelo de Azure OpenAI en el recurso designado.
modelName	AzureOpenAIModelName	Nombre del modelo de inserción que se implementa en la ruta de acceso deploymentId proporcionada.
resourceUri	string (uri)	Identificador URI del recurso de Azure OpenAI.

CorsOptions

Objeto

Define las opciones para controlar el uso compartido de recursos entre orígenes (CORS) para un índice.

Nombre	Tipo	Description
allowedOrigins	string[]	La lista de orígenes desde los que se concederá acceso al código JavaScript al índice. Puede contener una lista de hosts con el formato {protocol}://{fully-qualified-domain-name}[:{port#}], o un solo '*' para permitir todos los orígenes (no recomendado).
maxAgeInSeconds	integer (int64)	La duración durante la cual los exploradores deben almacenar en caché las respuestas preparatorias de CORS. El valor predeterminado es 5 minutos.

ErrorAdditionalInfo

Objeto

Información adicional sobre el error de administración de recursos.

Nombre	Tipo	Description
info		Información adicional.
type	string	Tipo de información adicional.

ErrorDetail

Objeto

Detalle del error.

Nombre	Tipo	Description
additionalInfo	ErrorAdditionalInfo[]	Información adicional del error.
code	string	Código de error.
details	ErrorDetail[]	Detalles del error.
message	string	El mensaje de error.
target	string	Destino del error.

ErrorResponse

Objeto

Respuesta de error común para todas las API de Azure Resource Manager para devolver los detalles de error de las operaciones con errores. (Esto también sigue el formato de respuesta de error de OData).

Nombre	Tipo	Description
error	ErrorDetail	Objeto de error.

KnowledgeBase

Objeto

Representa una definición de base de conocimiento.

Nombre	Tipo	Description
@odata.etag	string	La ETag de la base de conocimiento.
answerInstructions	string	Instrucciones consideradas por la base de conocimiento al generar respuestas.
corsOptions	CorsOptions	Opciones para controlar el Intercambio de Recursos entre Orígenes (CORS) para la base de conocimiento.
description	string	La descripción de la base de conocimientos.
encryptionKey	SearchResourceEncryptionKey	Descripción de una clave de cifrado que se crea en Azure Key Vault.
knowledgeSources	KnowledgeSourceReference[]	Fuentes de conocimiento referenciadas por esta base de conocimiento.
models	KnowledgeBaseModel[]: KnowledgeBaseAzureOpenAIModel[]	Contiene opciones de configuración sobre cómo conectarse a modelos de IA.
name	string	Nombre de la base de conocimiento.
outputMode	KnowledgeRetrievalOutputMode	El modo de salida para la base de conocimiento.
retrievalInstructions	string	Instrucciones consideradas por la base de conocimiento al desarrollar el plan de consulta.
retrievalReasoningEffort	KnowledgeRetrievalReasoningEffort: KnowledgeRetrievalLowReasoningEffort KnowledgeRetrievalMediumReasoningEffort KnowledgeRetrievalMinimalReasoningEffort	La configuración del esfuerzo de razonamiento de recuperación.

KnowledgeBaseAzureOpenAIModel

Objeto

Especifica el recurso de Azure OpenAI que se usa para realizar la planeación de consultas.

Nombre	Tipo	Description
azureOpenAIParameters	AzureOpenAIVectorizerParameters	Azure OpenAI.
kind	string: azureOpenAI	El modelo de IA que se utilizará para la planificación de consultas.

KnowledgeBaseModelKind

Enumeración

El modelo de IA que se utilizará para la planificación de consultas.

Valor	Description
azureOpenAI	Use modelos de Azure Open AI para la planeación de consultas.

KnowledgeRetrievalLowReasoningEffort

Objeto

Ejecute la recuperación de conocimientos con poco esfuerzo de razonamiento.

Nombre	Tipo	Description
kind	string: low	El tipo de esfuerzo de razonamiento.

KnowledgeRetrievalMediumReasoningEffort

Objeto

Ejecute la recuperación de conocimientos con un esfuerzo de razonamiento medio.

Nombre	Tipo	Description
kind	string: medium	El tipo de esfuerzo de razonamiento.

KnowledgeRetrievalMinimalReasoningEffort

Objeto

Realiza la recuperación de conocimiento con un esfuerzo mínimo de razonamiento.

Nombre	Tipo	Description
kind	string: minimal	El tipo de esfuerzo de razonamiento.

KnowledgeRetrievalOutputMode

Enumeración

La configuración de salida para esta recuperación.

Valor	Description
extractiveData	Devolver datos de las fuentes de conocimiento directamente sin alteración generativa.
answerSynthesis	Sintetiza una respuesta para la carga útil de respuesta.

KnowledgeRetrievalReasoningEffortKind

Enumeración

La cantidad de esfuerzo que se debe utilizar durante la recuperación.

Valor	Description
minimal	No realiza ninguna selección de origen, planeación de consultas ni búsqueda iterativa.
low	Utilice un razonamiento bajo durante la recuperación.
medium	Use una cantidad moderada de razonamiento durante la recuperación.

KnowledgeSourceReference

Objeto

Referencia a una fuente de conocimiento.

Nombre	Tipo	Description
enableFreshness	boolean	Indica si se debe habilitar la recuperación consciente de la frescura para esta fuente de conocimiento. Cuando es cierto, se aplica un perfil de puntuación de frescura durante la recuperación para sesgar los resultados hacia documentos más recientes.
enableImageServing	boolean	Indica si se debe habilitar el servicio de imágenes para esta fuente de conocimiento. Cuando es cierto, las imágenes extraídas durante la ingestión se entregan a los modelos aguas abajo en el momento de la consulta.
name	string	El nombre de la fuente de conocimiento.

SearchIndexerDataNoneIdentity

Objeto

Borra la propiedad de identidad de un origen de datos.

Nombre	Tipo	Description
@odata.type	string: #Microsoft.Azure.Search.DataNoneIdentity	Fragmento de URI que especifica el tipo de identidad.

SearchIndexerDataUserAssignedIdentity

Objeto

Especifica la identidad de un origen de datos que se va a usar.

Nombre	Tipo	Description
@odata.type	string: #Microsoft.Azure.Search.DataUserAssignedIdentity	Fragmento de URI que especifica el tipo de identidad.
federatedIdentityClientId	string	Soporte de Identidad Gestionada User-Assigned Multi-inquilino: El id de cliente de la aplicación multi-tenente configurada para federarse con la identidad gestionada asignada por el usuario.
userAssignedIdentity	string	El identificador de recurso de Azure completo de una identidad administrada asignada por el usuario normalmente con el formato "/subscriptions/12345678-1234-1234-1234-1234567890ab/resourceGroups/rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myId" que se debe haber asignado al servicio de búsqueda.

SearchResourceEncryptionKey

Objeto

Una clave de cifrado administrada por el cliente en Azure Key Vault. Las claves que crea y administra se pueden usar para cifrar o descifrar datos en reposo, como índices y mapas de sinónimos.

Nombre	Tipo	Valor predeterminado	Description
accessCredentials.applicationId	string		Un identificador de aplicación de AAD al que se concedieron los permisos de acceso necesarios a Azure Key Vault que se va a usar al cifrar los datos en reposo. El identificador de aplicación no debe confundirse con el id. de objeto de la aplicación de AAD.
accessCredentials.applicationSecret	string		Clave de autenticación de la aplicación de AAD especificada.
identity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity		Una identidad administrada explícita que se va a usar para esta clave de cifrado. Si no se especifica y la propiedad de credenciales de acceso es null, se usa la identidad administrada asignada por el sistema. Al actualizar al recurso, si la identidad explícita no está especificada, permanece sin cambios. Si se especifica "none", se borra el valor de esta propiedad.
isServiceLevelKey	boolean	False	Un valor opcional que indica si esta clave es una clave de nivel de servicio. El valor predeterminado es falso.
keyVaultKeyName	string		Nombre de la clave de Azure Key Vault que se usará para cifrar los datos en reposo.
keyVaultKeyVersion	string		Versión de la clave de Azure Key Vault que se usará para cifrar los datos en reposo.
keyVaultUri	string		El URI de Azure Key Vault, también denominado nombre DNS, que contiene la clave que se va a usar para cifrar los datos en reposo. Un URI de ejemplo podría ser `https://my-keyvault-name.vault.azure.net`.