Configuración de la vectorización integrada en Búsqueda de Azure AI mediante REST

En este artículo, aprenderá a usar un conjunto de aptitudes para fragmentar y vectorizar contenido de un origen de datos compatible. El conjunto de habilidades incluye la habilidad de División de texto o la habilidad de Diseño de documento para fragmentación y una habilidad de incorporación asociada a un modelo de inserció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 Quickstart: Vectorizar texto e imágenes en el portal de Azure.

Requisitos previos

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

• Un servicio Búsqueda de Azure AI. Se recomienda el nivel Básico o superior.

• Un origen de datos admitido.

• Un modelo de inserción admitido.

• 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 la extensión de cliente REST.

Orígenes de datos admitidos

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	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 caliente, templado 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 Properties de la página Overview.
Microsoft OneLake	Este origen de datos se conecta a archivos y accesos directos de OneLake.

Modelos de inserción admitidos

Use uno de los siguientes modelos de inserción para la vectorización integrada. Las instrucciones de implementación se proporcionan en una sección posterior.

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

² los recursos de Azure OpenAI (con acceso a modelos de embedding) que fueron creados en el portal de Microsoft Foundry no se admiten. Debe crear un recurso Azure OpenAI en el portal de Azure.

³ Para fines de facturación, debe adjuntar el recurso de Microsoft Foundry al conjunto de aptitudes de Azure AI Search. A menos que use una conexión sin clave para crear el conjunto de aptitudes, ambos recursos deben estar en la misma región.

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

Acceso basado en roles

Puede usar Microsoft Entra ID con asignaciones de roles o autenticación basada en claves con cadenas de conexión de acceso completo. Para Búsqueda de Azure AI conexiones 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 Búsqueda de Azure AI

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

1. Vaya al servicio de búsqueda en el portal Azure.

2. Para obtener el punto de conexión de búsqueda, copie la dirección URL en la página Información general . Un ejemplo de punto de conexión para búsqueda 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
   

Preparación de 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 IA de Azure para la vectorización integrada mediante la asignación de roles, la obtención de un punto de conexión y la implementación de un modelo de incrustación compatible.

Establecer variables

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

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 extremo de búsqueda y @token por el token de Microsoft Entra que obtuvo en Obtener información de conexión para 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 (almacenamiento de blobs de Azure)	@storageConnectionString y @blobContainer	La cadena de conexión y el nombre del contenedor que creó en Prepare your data.
   ADLS Gen2	@storageConnectionString y @blobContainer	La cadena de conexión y el nombre del contenedor que creó en Prepare your data.
   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, @aoaiDeploymentNamey @aoaiModelName	El punto de conexión, el nombre de implementación y el nombre del modelo que obtuvo en Preparar su modelo de incrustación.
   Azure Vision	@AiFoundryEndpoint	El endpoint que obtuviste en Preparar tu modelo de incrustación.

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

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

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

Conexión a los datos

En esta sección, se conectará a un origen de datos compatible para la indexación basada en indexadores. Un indexer en Búsqueda de Azure AI 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=2026-04-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 utiliza una habilidad integrada para dividir su contenido y una habilidad de incrustación para crear representaciones vectoriales de los fragmentos. El conjunto de habilidades 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 integrada de datos, Búsqueda de Azure AI ofrece la habilidad Text Split y la habilidad Azure Content Understanding. La habilidad «División de texto» divide el texto en oraciones o páginas de una longitud determinada, mientras que la habilidad Azure Content Understanding realiza una fragmentación semántica que tiene en cuenta el diseño y respeta los límites de los párrafos.

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

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

2. En la matriz skills, llame a la habilidad Dividir texto o a la habilidad Azure Content Understanding. 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.ContentUnderstandingSkill",
          "name": "my-content-understanding-skill",
          "context": "/document",
          "chunkingProperties": {
            "method": "semantic",
            "unit": "tokens",
            "maximumLength": 500
          },
          "inputs": [
           {
             "name": "file_data",
             "source": "/document/file_data"
           }
          ],
          "outputs": [
           {
             "name": "text_sections",
             "targetName": "text_sections"
           }
          ]
        }
       ]
   

Llame a una función de embebido 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 aptitud de fragmentación integrada en la skills matriz, llame a la aptitud de inserción de OpenAI de Azure o Azure Vision custom embeddings skill (versión preliminar). 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 funcionalidad de incrustaciones multimodales de Azure Vision está en versión preliminar. Si quiere invocar esta aptitud, use la versión preliminar más reciente de la API.

2. Si está utilizando la habilidad de incrustación de Azure OpenAI, establezca dimensions en el número de incrustaciones generadas por su modelo de incrustación.

3. Si está utilizando la aptitud de inserciones multimodal de Azure Vision, adjunte el recurso de Microsoft 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.

Creación de un índice vectorial

En esta sección, configurará estructuras de datos físicas en el servicio de Búsqueda de Azure AI mediante la creación de un índice de vector. 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 vectorial.

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

   ### Create a vector index
   POST {{baseUrl}}/indexes?api-version=2026-04-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. En función de tu habilidad de incrustación, establece dimensions para cada campo vectorial al siguiente valor.

   Aptitud de inserción	Escriba 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 OpenAI de Azure o Azure Vectorizador de visión (versión preliminar) después vectorSearch.profilesde . 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 Azure Vision está en versión preliminar. Si desea llamar a este vectorizador, use la versión preliminar más reciente de la API.

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á un indexador para impulsar toda la canalización de vectorización, desde la recuperación de datos hasta la ejecución del conjunto de aptitudes a la indexación. Se recomienda ejecutar el indexador según una programación para procesar los cambios o documentos que se han perdido debido a la limitació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=2026-04-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=2026-04-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 Azure Vision está en versión preliminar. Si desea llamar a este vectorizador, use la versión preliminar más reciente de la API.

   En el caso de las consultas que invocan la vectorización integrada, kind debe configurarse 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

• Inserción de vectores integrados en Búsqueda de Azure AI
• Quickstart: Búsqueda vectorial en el portal de Azure
• ejemplo Python para la vectorización integrada