Configuración de la vectorización integrada en Azure AI Search mediante REST

En este artículo, aprenderá a usar un conjunto de aptitudes para fragmentar y vectorizar contenido de un origen de datos compatible. Las habilidades llaman a la Habilidad de división de texto o a la Habilidad de diseño de documento para fragmentar y a una habilidad de implantación asociada a un modelo de implantación compatible para la vectorización de fragmentos. También aprenderá a almacenar el contenido fragmentado y vectorizado en un índice vectorial.

En este artículo se describe el flujo de trabajo de un extremo a otro para la vectorización integrada mediante REST. Para obtener instrucciones basadas en el portal, consulte Inicio rápido: Vectorización de texto e imágenes en Azure Portal.

Prerrequisitos

• Una cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.

• Un servicio azure AI Search. Se recomienda el nivel Básico o superior.

• Un origen de datos admitido.

• Un modelo de inserción compatible.

• Finalización del inicio rápido: Conexión sin claves y Configuración de una identidad administrada asignada por el sistema. Aunque puede usar la autenticación basada en claves para las operaciones del plano de datos, en este artículo se asumen roles e identidades administradas, que son más seguras.

• Visual Studio Code con un cliente REST.

Orígenes de datos compatibles

La vectorización integrada funciona con todos los orígenes de datos admitidos. Sin embargo, este artículo se centra en los orígenes de datos más usados, que se describen en la tabla siguiente.

Origen de datos compatible	Descripción
Azure Blob Storage	Este origen de datos funciona con blobs y tablas. Debe usar una cuenta de rendimiento estándar (de uso general v2). Los niveles de acceso pueden ser frecuente, esporádico o frío.
Azure Data Lake Storage (ADLS) Gen2	Se trata de una cuenta de Azure Storage con un espacio de nombres jerárquico habilitado. Para confirmar que tiene Data Lake Storage, active la pestaña Propiedades de la página Información general .
Microsoft OneLake	Este origen de datos se conecta a archivos y accesos directos de OneLake.

Modelos de inserción compatibles

Para la vectorización integrada, use uno de los siguientes modelos de inserción en una plataforma de Azure AI. Las instrucciones de implementación se proporcionan en una sección posterior.

¹ El punto de conexión del recurso de Azure OpenAI debe tener un subdominio personalizado, como https://my-unique-name.openai.azure.com. Si creó el recurso en Azure Portal, este subdominio se generó automáticamente durante la configuración del recurso.

² Los recursos de Azure OpenAI (con acceso a modelos de inserción) que se crearon en el portal de Foundry no son compatibles. Debe crear un recurso de Azure OpenAI en Azure Portal.

³ Para fines de facturación, debe adjuntar el recurso de Foundry al conjunto de aptitudes del servicio de Búsqueda de Azure AI. A menos que utilice una conexión sin clave (versión preliminar) para crear el conjunto de habilidades, ambos recursos deben estar en la misma región.

⁴ El modelo de incrustación multimodal de Azure Vision está disponible en regiones seleccionadas.

Acceso basado en rol

Puede usar Microsoft Entra ID con asignaciones de roles o autenticación basada en claves con cadenas de conexión de acceso completo. En el caso de las conexiones de Azure AI Search a otros recursos, se recomiendan asignaciones de roles.

Para configurar el acceso basado en roles para la vectorización integrada:

1. En el servicio de búsqueda, habilite los roles y configure una identidad administrada asignada por el sistema.

2. En la plataforma del origen de datos y el proveedor de modelos de inserción, cree asignaciones de roles que permitan al servicio de búsqueda acceder a datos y modelos. Consulte Preparación de los datos y Preparación del modelo de inserción.

Obtención de información de conexión para Azure AI Search

En esta sección, recuperará el punto de conexión y el token de Microsoft Entra para el servicio Azure AI Search. Ambos valores son necesarios para establecer conexiones en solicitudes REST .

1. Inicie sesión en Azure Portal y seleccione el servicio Azure AI Search.

2. Para obtener el punto de conexión de búsqueda, copie la dirección URL en la páginaInformación general. Un punto de conexión de búsqueda de ejemplo es https://my-service.search.windows.net.

3. Para obtener el token de Microsoft Entra, ejecute el siguiente comando en el sistema local. Este paso requiere la finalización del inicio rápido: Conexión sin claves.

   az account get-access-token --scope https://search.azure.com/.default --query accessToken --output tsv
   

Preparar los datos

En esta sección, preparará los datos para la vectorización integrada mediante la carga de archivos en un origen de datos compatible, la asignación de roles y la obtención de información de conexión.

Preparación del modelo de inserción

En esta sección, preparará el recurso de Azure AI para la vectorización integrada mediante la asignación de roles, la obtención de un punto de conexión e implementará un modelo de inserción compatible.

Establecer variables

En esta sección, especificará la información de conexión del servicio Azure AI Search, el origen de datos compatible y el modelo de inserción admitido.

1. En Visual Studio Code, pegue los siguientes marcadores de posición en el archivo .rest o .http.

   @baseUrl = PUT-YOUR-SEARCH-SERVICE-URL-HERE
   @token = PUT-YOUR-MICROSOFT-ENTRA-TOKEN-HERE
   

2. Reemplace @baseUrl por el punto de conexión de búsqueda y @token por el token de Microsoft Entra que obtuvo en Obtención de información de conexión para La Búsqueda de Azure AI.

3. En función del origen de datos, agregue las siguientes variables.

   Origen de datos	variables	Escriba esta información.
   Azure Blob Storage (Servicio de almacenamiento de blobs de Azure)	@storageConnectionString y @blobContainer	Cadena de conexión y el nombre del contenedor que creó en Preparar los datos.
   ADLS Gen2	@storageConnectionString y @blobContainer	Cadena de conexión y el nombre del contenedor que creó en Preparar los datos.
   OneLake	@workspaceId y @lakehouseId	El área de trabajo y los identificadores de almacén de lago de datos obtenidos en Prepare sus datos.

4. En función del proveedor de modelos de inserción, agregue las siguientes variables.

   Inserción del proveedor de modelos	variables	Escriba esta información.
   Azure OpenAI	@aoaiEndpoint, @aoaiDeploymentName y @aoaiModelName	El punto de conexión, el nombre de implementación y el nombre del modelo que obtuvo en Preparar su modelo de inserción.
   Azure Vision	@AiFoundryEndpoint	El punto de conexión que obtuvo en Preparar su modelo de inserción.

5. Para comprobar las variables, envíe la siguiente solicitud.

   ### List existing indexes by name
   GET {{baseUrl}}/indexes?api-version=2025-09-01  HTTP/1.1
     Content-Type: application/json
     Authorization: Bearer {{token}}
   

   Debe aparecer una respuesta en un panel adyacente. Si tiene índices existentes, se muestran. En caso contrario, la lista está vacía. Si el código HTTP es 200 OK, está listo para continuar.

Conectar con tus datos

En esta sección, se conectará a un origen de datos compatible para la indexación basada en indexadores. Un indexador de Azure AI Search requiere un origen de datos que especifique el tipo, las credenciales y el contenedor.

1. Use Create Data Source (Crear origen de datos ) para definir un origen de datos que proporcione información de conexión durante la indexación.

   ### Create a data source
   POST {{baseUrl}}/datasources?api-version=2025-09-01  HTTP/1.1
     Content-Type: application/json
     Authorization: Bearer {{token}}
   
     {
       "name": "my-data-source",
       "type": "azureblob",
       "subtype": null,
       "credentials": {
           "connectionString": "{{storageConnectionString}}"
       },
       "container": {
           "name": "{{blobContainer}}",
           "query": null
       },
       "dataChangeDetectionPolicy": null,
       "dataDeletionDetectionPolicy": null
     }
   

2. Establezca type en el origen de datos: azureblob o adlsgen2.

3. Para crear el origen de datos, seleccione Enviar solicitud.

4. Si usa OneLake, establezca credentials.connectionString en ResourceId={{workspaceId}} y container.name en {{lakehouseId}}.

Crear un conjunto de habilidades

En esta sección, creará un conjunto de habilidades que llama a una habilidad integrada para fragmentar el contenido y una habilidad de inserción para crear representaciones vectoriales de los fragmentos. El conjunto de aptitudes se ejecuta durante la indexación en una sección posterior.

Llama a una habilidad integrada para fragmentar tu contenido

La creación de particiones del contenido en fragmentos le ayuda a cumplir los requisitos del modelo de inserción y evita la pérdida de datos debido al truncamiento. Para obtener más información sobre la fragmentación, consulte Fragmentos de documentos grandes para soluciones de búsqueda de vectores.

Para la fragmentación de datos integrada, Azure AI Search ofrece la aptitud División de texto y la aptitud Diseño de documento. La aptitud División de texto divide el texto en oraciones o páginas de una longitud determinada, mientras que la aptitud Diseño de documento interrumpe el contenido en función de los límites de párrafo.

1. Use Create Skillset (Crear conjunto de aptitudes) para definir un conjunto de aptitudes.

   ### Create a skillset
   POST {{baseUrl}}/skillsets?api-version=2025-09-01  HTTP/1.1
     Content-Type: application/json
     Authorization: Bearer {{token}}
   
     {
       "name": "my-skillset",
       "skills": []
     }
   

2. En la matriz skills, llame a la aptitud División de texto o a la aptitud Diseño de documento. Puede pegar una de las definiciones siguientes.

       "skills": [
        {
          "@odata.type": "#Microsoft.Skills.Text.SplitSkill",
          "name": "my-text-split-skill",
          "textSplitMode": "pages",
          "maximumPageLength": 2000,
          "pageOverlapLength": 500,
          "maximumPagesToTake": 0,
          "unit": "characters",
          "defaultLanguageCode": "en",
          "inputs": [
           {
             "name": "text",
             "source": "/document/text",
             "inputs": []
           }
          ],
          "outputs": [
           {
             "name": "textItems"
           }
          ]
        },
        {
          "@odata.type": "#Microsoft.Skills.Util.DocumentIntelligenceLayoutSkill",
          "name": "my-document-layout-skill",
          "context": "/document",
          "outputMode": "oneToMany",
          "markdownHeaderDepth": "h3",
          "inputs": [
           {
             "name": "file_data",
             "source": "/document/file_data"
           }
          ],
          "outputs": [
           {
             "name": "markdown_document"
           }
          ]
        }
       ]
   

   Nota:

   La aptitud Diseño de documento está en versión preliminar pública. Si desea llamar a esta aptitud, use una API en versión preliminar, como 2025-03-01-preview.

Llamada a una aptitud de inserción para vectorizar los fragmentos

Para vectorizar el contenido fragmentado, el conjunto de aptitudes necesita una aptitud de inserción que apunte a un modelo de inserción admitido.

1. Después de la habilidad de fragmentación integrada en la matriz skills, llame a la Habilidad Azure OpenAI Embedding o a la Habilidad Azure Vision. Puede pegar una de las definiciones siguientes.

        {
          "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
          "resourceUri": "{{aoaiEndpoint}}",
          "deploymentId": "{{aoaiDeploymentName}}",
          "modelName": "{{aoaiModelName}}",
          "dimensions": 1536,
          "inputs": [
            {
              "name": "text",
              "source": "/document/text"
            }
          ],
          "outputs": [
            {
              "name": "embedding"
            }
          ]
        },
        {
          "@odata.type": "#Microsoft.Skills.Vision.VectorizeSkill",
          "context": "/document",
          "modelVersion": "2023-04-15", 
          "inputs": [
            {
              "name": "url",
              "source": "/document/metadata_storage_path"
            },
            {
              "name": "queryString",
              "source": "/document/metadata_storage_sas_token"
            }
          ],
          "outputs": [
            {
              "name": "vector"
            }
          ]
        }
   

   Nota:

   La capacidad de inserciones multimodales de Azure Vision está en versión preliminar pública. Si quiere llamar a esta aptitud, use la API de versión preliminar más reciente.

2. Si usa la aptitud de inserción de Azure OpenAI, establezca dimensions en el número de incrustaciones el modelo de inserción.

3. Si está utilizando la habilidad de embeddings multimodales de Azure Vision, adjunte su recurso Foundry después de la matriz skills. Estos datos adjuntos son para fines de facturación.

       "skills": [ ... ],
       "cognitiveServices": {
         "@odata.type": "#Microsoft.Azure.Search.AIServicesByIdentity",
         "subdomainUrl": "{{AiFoundryEndpoint}}"
        }
   

4. Para crear el conjunto de aptitudes, seleccione Enviar solicitud.

Crear un índice vectorial

En esta sección, configurará estructuras de datos físicas en el servicio Azure AI Search mediante la creación de un índice vectorial. El esquema de un índice vectorial requiere lo siguiente:

• Nombre
• Campo de clave (cadena)
• Uno o varios campos vectoriales
• Configuración de vectores

Los campos vectoriales almacenan representaciones numéricas de los datos fragmentados. Deben ser accesibles y recuperables, pero no pueden ser filtrables, facetables ni ordenables. Tampoco pueden tener analizadores, normalizadores ni asignaciones de mapa de sinónimos.

Además de los campos vectoriales, el índice de ejemplo de los pasos siguientes contiene campos no vectores para contenido legible. Es habitual incluir equivalentes de texto sin formato del contenido que desea vectorizar. Para obtener más información, consulte Creación de un índice de vectores.

1. Use Create Index (Crear índice ) para definir el esquema de un índice vectorial.

   ### Create a vector index
   POST {{baseUrl}}/indexes?api-version=2025-09-01  HTTP/1.1
     Content-Type: application/json
     Authorization: Bearer {{token}}
   
     {
       "name": "my-vector-index",
       "fields": [],
       "vectorSearch": []
     }
   

2. Agregue una configuración de búsqueda vectorial a la vectorSearch sección.

       "vectorSearch": {
         "algorithms": [
           {
             "name": "hnsw-algorithm",
             "kind": "hnsw",
             "hnswParameters": {
               "m": 4,
               "efConstruction": 400,
               "efSearch": 100,
               "metric": "cosine"
             }
           }
         ],
         "profiles": [
           {
             "name": "vector-profile-hnsw",
             "algorithm": "hnsw-algorithm",
           }
         ]
       }
   

   vectorSearch.algorithms especifica el algoritmo usado para indexar y consultar campos vectoriales, mientras que vectorSearch.profiles vincula la configuración del algoritmo a un perfil que se puede asignar a los campos vectoriales.

3. En función del modelo de inserción, actualice vectorSearch.algorithms.metric. Los valores válidos para las métricas de distancia son cosine, dotproduct, euclideany hamming.

4. Agregue campos a las fields matrices. Incluya un campo clave para la identificación de documentos, campos no vectores para contenido legible y campos vectoriales para incrustaciones.

       "fields": [
         {
           "name": "id",
           "type": "Edm.String",
           "key": true,
           "filterable": true
         },
         {
           "name": "title",
           "type": "Edm.String",
            "searchable": true,
            "filterable": true,
            "sortable": true,
            "retrievable": true
         },
         {
           "name": "titleVector",
           "type": "Collection(Edm.Single)",
            "searchable": true,
            "retrievable": false,
            "stored": true,
            "dimensions": 1536,
            "vectorSearchProfile": "vector-profile-hnsw"
         },
         {
           "name": "content",
           "type": "Edm.String",
            "searchable": true,
            "retrievable": true
         },
         {
           "name": "contentVector",
           "type": "Collection(Edm.Single)",
            "searchable": true,
            "retrievable": false,
            "stored": false,
            "dimensions": 1536,
            "vectorSearchProfile": "vector-profile-hnsw"
         }
       ]
   

5. Dependiendo de su habilidad para incrustar, ajuste dimensions de cada campo vectorial al siguiente valor.

   Aptitud de inserción	Introduzca este valor
   Azure OpenAI	Número de incrustaciones generadas por el modelo de inserción.
   Azure Vision	1024

Adición de un vectorizador al índice

En esta sección, habilitará la vectorización en el momento de la consulta definiendo un vectorizador en el índice. El vectorizador usa el modelo de inserción que indexa los datos para descodificar una cadena de búsqueda o una imagen en un vector para la búsqueda vectorial.

1. Agregue el vectorizador de Azure OpenAI o el vectorizador de Azure Vision después de vectorSearch.profiles. Puede pegar una de las definiciones siguientes.

         "profiles": [ ... ],
         "vectorizers": [
           {
             "name": "my-openai-vectorizer",
             "kind": "azureOpenAI",
             "azureOpenAIParameters": {
               "resourceUri": "{{aoaiEndpoint}}",
               "deploymentId": "{{aoaiDeploymentName}}",
               "modelName": "{{aoaiModelName}}"
             }
           },
           {
             "name": "my-ai-services-vision-vectorizer",
             "kind": "aiServicesVision",
             "aiServicesVisionParameters": {
               "resourceUri": "{{AiFoundryEndpoint}}",
               "modelVersion": "2023-04-15"
             }
           }
         ]
   

   Nota:

   El vectorizador de Azure Vision está en versión preliminar pública. Si desea llamar a este vectorizador, use una API en versión preliminar, como 2025-03-01-preview.

2. Especifique el vectorizador en vectorSearch.profiles.

         "profiles": [
           {
             "name": "vector-profile-hnsw",
             "algorithm": "hnsw-algorithm",
             "vectorizer": "my-openai-vectorizer"
           }
         ]
   

3. Para crear el índice vectorial, seleccione Enviar solicitud.

Creación de un indexador

En esta sección, crearás un indexador para impulsar toda la canalización de vectorización, desde la recuperación de datos hasta la ejecución del conjunto de habilidades e indexación. Recomendamos que ejecute el indexador según un horario para procesar los cambios o documentos que se han perdido debido a la restricción.

1. Use Create Indexer para definir un indexador que ejecute la canalización de vectorización.

   ### Create an indexer
   POST {{baseUrl}}/indexers?api-version=2025-09-01  HTTP/1.1
     Content-Type: application/json
     Authorization: Bearer {{token}}
   
     {
       "name": "my-indexer",
       "dataSourceName": "my-data-source",
       "targetIndexName": "my-vector-index",
       "skillsetName": "my-skillset",
       "schedule": {
         "interval": "PT2H"
       },
       "parameters": {
         "batchSize": null,
         "maxFailedItems": null,
         "maxFailedItemsPerBatch": null
       }
     }
   

2. Para crear el indexador, seleccione Enviar solicitud.

Ejecución de una consulta vectorial para confirmar la indexación

En esta sección, comprobará que el contenido se indizó correctamente mediante la creación de una consulta vectorial. Dado que configuró un vectorizador en una sección anterior, el motor de búsqueda puede descodificar texto sin formato o una imagen en un vector para la ejecución de consultas.

1. Use Documents - Search Post para definir una consulta vectorizada en el momento de la consulta.

   ### Run a vector query
   POST {{baseUrl}}/indexes('my-vector-index')/docs/search.post.search?api-version=2025-09-01  HTTP/1.1
     Content-Type: application/json
     Authorization: Bearer {{token}}
   
     {
       "count": true,
       "select": "title, content",
       "vectorQueries": [
           {
             "kind": "text",
             "text": "a sample text string for integrated vectorization",
             "fields": "titleVector, contentVector",
             "k": "3"
           }
       ]
     }
   

   Nota:

   El vectorizador de Azure Vision está en versión preliminar pública. Si ha llamado previamente a este vectorizador, use una API de vista previa, como 2025-03-01-preview.

   En el caso de las consultas que invocan la vectorización integrada, kind debe establecerse en text y text debe especificar una cadena de texto. Esta cadena se pasa al vectorizador asignado al campo vectorial. Para obtener más información, consulte Consulta con vectorización integrada.

2. Para ejecutar la consulta vectorial, seleccione Enviar solicitud.

Contenido relacionado

• Vectorización integrada en Azure AI Search
• Inicio rápido: Vectorización de texto e imágenes en Azure Portal
• Ejemplo de Python para la vectorización integrada