Compartir a través de

Crear un índice vectorial

En Azure AI Search, puede almacenar vectores en un índice de búsqueda y enviar consultas vectoriales para buscar coincidencias en función de la similitud semántica. Un índice vectorial se define mediante un esquema de índice que tiene campos vectoriales, campos no vectores y una sección de configuración de vectores.

La API REST Create or Update Index crea el índice vectorial. Para indexar vectores en Azure AI Search, siga estos pasos:

  • Comience con una definición de esquema básica.
  • Agregue algoritmos vectoriales y compresión opcional.
  • Agregar definiciones de campo vectorial.
  • Cargue datos prevectorizados como un paso independiente o use la vectorización integrada para la fragmentación de datos y la inserción durante la indexación.

En este artículo se usa REST para ilustrarlo. Después de comprender el flujo de trabajo básico, continúe con los ejemplos de código del SDK de Azure en el repositorio azure-search-vector-samples , que proporciona instrucciones sobre el uso de vectores en código de prueba y producción.

Sugerencia

También puede usar Azure Portal para crear un índice vectorial y probar la fragmentación y la vectorización de datos integrados.

Requisitos previos

  • Un servicio Azure AI Search en cualquier región y de cualquier nivel. Si planea usar la vectorización integrada con aptitudes y vectorizadores de Azure AI, Azure AI Search debe estar en la misma región que los modelos de inserción hospedados en Azure AI Vision.

  • Los documentos de origen deben tener incrustaciones vectoriales para cargarlos en el índice. También puede usar la vectorización integrada para este paso.

  • Debe conocer el límite de dimensiones del modelo que crea las incrustaciones para poder asignar ese límite al campo vectorial. Para text-embedding-ada-002, las dimensiones se fijan en 1536. En el caso de inserción de texto-3-pequeña o inserción de texto-3-grande, las dimensiones van de 1 a 1536 y de 1 a 3072, respectivamente.

  • Debe saber qué métrica de similitud se va a usar. Para insertar modelos en Azure OpenAI, la similitud se calcula mediante cosine.

  • Debe saber cómo crear un índice. Un esquema siempre incluye un campo para la clave de documento, los campos de búsqueda o filtros, y otras configuraciones para comportamientos necesarios durante la indexación y las consultas.

Limitaciones

Algunos servicios de búsqueda creados antes de enero de 2019 no pueden crear un índice vectorial. En el caso de que sea su caso, cree un nuevo servicio para usar vectores.

Preparación de documentos para la indexación

Antes de la indexación, ensamblar una carga de documento que incluya campos de datos vectoriales y no vectores. La estructura del documento debe ajustarse a la colección de campos del esquema de índice.

Asegúrese de que los documentos de origen proporcionen el siguiente contenido:

Contenido Descripción
Identificador único Campo o propiedad de metadatos que identifica de forma única cada documento. Todos los índices de búsqueda requieren una clave de documento. Para satisfacer los requisitos de clave de documento, un documento de origen debe tener un campo o propiedad que lo identifique de forma única en el índice. Si está indexando blobs, puede ser el metadata_storage_path que identifica de forma única cada blob. Si va a indexar desde una base de datos, podría ser la clave principal. Este campo de origen debe asignarse a un campo de índice de tipo Edm.String y key=true en el índice de búsqueda.
Contenido no vectorial Proporcione otros campos con contenido legible. El contenido legible es útil para la respuesta de consulta y para las consultas híbridas que incluyen la búsqueda de texto completo o la clasificación semántica en la misma solicitud. Si usa un modelo de finalización de chat, la mayoría de los modelos como ChatGPT esperan texto legible para personas y no aceptan vectores sin procesar como entrada.
Contenido vectorial Representación vectorizada del contenido novector para su uso en el momento de la consulta. Un vector es una matriz de números de punto flotante de precisión sencilla generados por un modelo de inserción. Cada campo vectorial contiene una matriz generada por el modelo. Hay una inserción por campo, donde el campo es un campo de nivel superior (no forma parte de un tipo anidado o complejo). Para una integración sencilla, se recomienda insertar modelos en Azure OpenAI, como la inserción de texto-3 para documentos de texto o la API REST de recuperación de imágenes para imágenes e incrustaciones bidireccionales.

Si puede usar indexadores y conjuntos de aptitudes, considere la posibilidad de vectorización integrada, que codifica imágenes y texto durante la indexación. Sus definiciones de campo son para campos vectoriales, pero los datos de origen entrantes pueden ser texto o imágenes, que se convierten en matrices vectoriales durante la indexación.

El índice de búsqueda debe incluir campos y contenido para todos los escenarios de consulta que quieras admitir. Supongamos que quieres buscar o filtrar por nombres de producto, versiones, metadatos o direcciones. En este caso, la búsqueda de similitud vectorial no resulta especialmente útil. La búsqueda de palabras clave, la búsqueda geográfica o los filtros que recorren en iteración el contenido textual sería una mejor opción. Un índice de búsqueda que incluye campos vectoriales y no vectores proporciona máxima flexibilidad para la construcción de consultas y la composición de respuestas.

Para obtener un breve ejemplo de una carga de documentos que incluye campos vectoriales y no vectores, consulte la sección datos vectoriales de carga de este artículo.

Empezar con un índice básico

Comience con un esquema mínimo para que tenga una definición con la que trabajar antes de agregar una configuración de vector y campos vectoriales. Un índice simple podría tener un aspecto similar al ejemplo siguiente. Para obtener más información sobre un esquema de índice, consulte Creación de un índice de búsqueda.

Observe que el índice tiene un nombre obligatorio, una clave de documento necesaria ("key": true) y campos para contenido legible para humanos en texto sin formato. Es habitual tener una versión legible de cualquier contenido que quiera vectorizar. Por ejemplo, si tiene un fragmento de texto de un archivo PDF, el esquema de índice debe tener un campo para fragmentos de texto sin formato y un segundo campo para fragmentos vectorizados.

Este es un índice básico con un "name", una colección de "fields", y otras construcciones, para una configuración adicional:

POST https://[servicename].search.windows.net/indexes?api-version=[api-version] 
{
  "name": "example-index",
  "fields": [
    { "name": "documentId", "type": "Edm.String", "key": true, "retrievable": true, "searchable": true, "filterable": true },
    { "name": "myHumanReadableNameField", "type": "Edm.String", "retrievable": true, "searchable": true, "filterable": false, "sortable": true, "facetable": false },
    { "name": "myHumanReadableContentField", "type": "Edm.String", "retrievable": true, "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.microsoft" },
  ],
  "analyzers": [ ],
  "scoringProfiles": [ ],
  "suggesters": [ ],
  "vectorSearch": [ ]
}

Añadir una configuración de vector de búsqueda

A continuación, agregue una "vectorSearch" configuración al esquema. Es útil especificar una configuración antes de las definiciones de campo, ya que los perfiles que defina aquí forman parte de la definición del campo vectorial. En el esquema, la configuración del vector se inserta normalmente después de la colección de campos, quizás después de "analyzers", "scoringProfiles" y "suggesters". Sin embargo, el orden no importa.

Una configuración de vector incluye:

  • vectorSearch.algorithms se usa durante la indexación para crear información de "vecino más cercano" entre los nodos vectoriales.
  • vectorSearch.compressions para la cuantificación escalar o binaria, el sobremuestreo y la reclasificación con vectores originales.
  • vectorSearch.profiles para especificar varias combinaciones de configuraciones de algoritmo y compresión.

2024-07-01 está disponible con carácter general. Admite una configuración de vector que tiene:

  • Algoritmo jerárquico de pequeños mundos navegables (HNSW).
  • Algoritmo k-vecino más próximo (KNN) exhaustivo.
  • Compresión escalar.
  • Compresión binaria, que solo está disponible en 2024-07-01 y en paquetes más recientes del SDK de Azure.
  • Sobremuestreo.
  • Reordenación con vectores originales.

Si elige HNSW en un campo, puede optar por un KNN exhaustivo en el momento de la consulta. Sin embargo, lo contrario no funciona. Si elige exhaustiva para la indexación, no puede solicitar más adelante la búsqueda de HNSW porque las estructuras de datos adicionales que habilitan la búsqueda aproximada no existen.

Asegúrate de tener una estrategia para vectorizar el contenido. Se recomienda la vectorización integrada y los vectorizadores en tiempo de consulta para la codificación integrada.

  1. Use la API REST Create or Update Index para crear el índice.

  2. Añade una sección vectorSearch en el índice que especifique los algoritmos de búsqueda usados para crear el espacio de inserción.

     "vectorSearch": {
     "compressions": [
         {
             "name": "scalar-quantization",
             "kind": "scalarQuantization",
             "rerankWithOriginalVectors": true,
             "defaultOversampling": 10.0,
                 "scalarQuantizationParameters": {
                     "quantizedDataType": "int8"
                 }
         },
         {
             "name": "binary-quantization",
             "kind": "binaryQuantization",
             "rerankWithOriginalVectors": true,
             "defaultOversampling": 10.0
         }
     ],
     "algorithms": [
         {
             "name": "hnsw-1",
             "kind": "hnsw",
             "hnswParameters": {
                 "m": 4,
                 "efConstruction": 400,
                 "efSearch": 500,
                 "metric": "cosine"
             }
         },
         {
             "name": "hnsw-2",
             "kind": "hnsw",
             "hnswParameters": {
                 "m": 8,
                 "efConstruction": 800,
                 "efSearch": 800,
                 "metric": "hamming"
             }
         },
         {
             "name": "eknn",
             "kind": "exhaustiveKnn",
             "exhaustiveKnnParameters": {
                 "metric": "euclidean"
             }
         }

     ],
     "profiles": [
       {
         "name": "vector-profile-hnsw-scalar",
         "compression": "scalar-quantization",
         "algorithm": "hnsw-1"
       }
     ]
 }

    Puntos clave:

    • Los nombres de cada configuración de compresión, algoritmo y perfil deben ser únicos para su tipo dentro del índice.

    • vectorSearch.compressions puede ser scalarQuantization o binaryQuantization. La cuantificación escalar comprime los valores float en tipos de datos más estrechos. La cuantificación binaria convierte los floats en valores binarios de 1 bits.

    • vectorSearch.compressions.rerankWithOriginalVectors usa los vectores originales sin comprimir para recalcular la similitud y reordenar los resultados principales de la consulta de búsqueda inicial. Los vectores sin comprimir existen en el índice de búsqueda aunque stored sea false. Esta propiedad es opcional. El valor predeterminado es true.

    • vectorSearch.compressions.defaultOversampling considera un conjunto más amplio de resultados potenciales para compensar la reducción de información debido a la cuantización. La fórmula para los posibles resultados consta de la k en la consulta, con un multiplicador de sobremuestreo. Por ejemplo, si la consulta especifica un k de 5 y el sobremuestreo es 20, en efecto, la consulta solicita 100 documentos para su uso en la reclasificación, utilizando para ese propósito el vector sin comprimir original. Solo se devuelven los mejores k resultados reclasificados. Esta propiedad es opcional. El valor predeterminado es 4.

    • vectorSearch.compressions.scalarQuantizationParameters.quantizedDataType se debe establecer en int8. Este es el único tipo de datos primitivo que se admite en este momento. Esta propiedad es opcional. El valor predeterminado es int8.

    • vectorSearch.algorithms es hnsw o exhaustiveKnn. Estos son los algoritmos de vecinos más cercanos aproximados (ANN) que se usan para organizar el contenido vectorial durante la indexación.

    • vectorSearch.algorithms.m es el recuento de vínculos bidireccionales. El valor predeterminado es 4. El rango es de 4 a 10. Los valores inferiores deben devolver menos ruido en los resultados.

    • vectorSearch.algorithms.efConstruction es el número de vecinos más próximos usados durante la indexación. El valor predeterminado es 400. El rango va de 100 a 1000.

    • "vectorSearch.algorithms.efSearch es el número de vecinos más próximos usados durante la búsqueda. El valor predeterminado es 500. El rango va de 100 a 1000.

    • vectorSearch.algorithms.metric debe ser cosine si usa Azure OpenAI; de lo contrario, use la métrica de similitud asociada al modelo de inserción que está usando. Los valores admitidos son cosine, dotProduct, euclideany hamming (se usan para indexar datos binarios).

    • vectorSearch.profiles añaden una capa de abstracción para acomodar definiciones más enriquecidas. Un perfil se define en vectorSearch y se hace referencia por nombre en cada campo vectorial. Es una combinación de configuraciones de compresión y algoritmo. Esta propiedad se asigna a un campo vectorial y determina el algoritmo y la compresión de los campos.

Añadir un campo vectorial a la colección de campos

Una vez que tenga una configuración de vector, puede agregar un campo vectorial a la colección fields. Recuerde que la colección de campos debe incluir un campo para la clave de documento, los campos vectoriales y cualquier otro campo novector que necesite para escenarios de búsqueda híbrida o finalización del modelo de chat en cargas de trabajo de RAG.

Los campos vectoriales se caracterizan por su tipo de datos, una dimensions propiedad basada en el modelo de inserción que se usa para generar los vectores y un perfil de vector que creó en un paso anterior.

2024-07-01 está disponible con carácter general.

  1. Use la API REST Create or Update Index para crear el índice y agregar un campo vectorial a la colección fields.

    {
  "name": "example-index",
  "fields": [
    {
        "name": "contentVector",
        "type": "Collection(Edm.Single)",
        "searchable": true,
        "retrievable": false,
        "stored": false,
        "dimensions": 1536,
        "vectorSearchProfile": "vector-profile-1"
    }
  ]
}

  2. Especifique un campo vectorial con los atributos siguientes. Puedes almacenar una inserción generada por campo. Para cada campo vectorial:

    • type debe ser un tipo de datos vectorial. Collection(Edm.Single) es el más común para insertar modelos.
    • dimensions es el número de dimensiones generadas en el modelo de inserción. Para la inserción de texto-ada-002, se fija en 1536. Para la serie de modelos de inserción de texto-3, hay un intervalo de valores. Si usa la vectorización integrada y una aptitud de inserción para generar vectores, asegúrese de que esta propiedad está establecida en el mismo valor de dimensiones que usa la aptitud de inserción.
    • vectorSearchProfile es el nombre de un perfil definido en otra parte del índice.
    • searchable debe ser verdadero.
    • retrievable puede ser true o false. True devuelve los vectores sin formato (1536 de ellos) como texto sin formato y consume espacio de almacenamiento. Establécelo en true si vas a pasar un resultado vectorial a una aplicación de nivel inferior.
    • stored puede ser true o false. Determina si se almacena una copia adicional de vectores para la recuperación. Para obtener más información, vea Reducción del tamaño del vector.
    • filterable, facetabley sortable deben ser false.

  3. Agregue campos no vectoriales filtrables a la colección, como title con filterable establecido en true, si desea invocar prefiltrado o postfiltrado en la consulta vectorial.

  4. Añade otros campos que definan la sustancia y la estructura del contenido textual que estás indexando. Como mínimo, necesitas una clave de documento.

    También debes agregar campos que sean útiles en la consulta o en su respuesta. En el ejemplo siguiente se muestran los campos vectoriales para el título y el contenido (titleVector y contentVector) que son equivalentes a los vectores. También proporciona campos para contenido textual equivalente (title y content) que son útiles para ordenar, filtrar y leer en un resultado de búsqueda.

    En el ejemplo siguiente se muestra la colección de campos:

    PUT https://my-search-service.search.windows.net/indexes/my-index?api-version=2024-07-01&allowIndexDowntime=true
Content-Type: application/json
api-key: {{admin-api-key}}
{
    "name": "{{index-name}}",
    "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": true,
            "stored": true,
            "dimensions": 1536,
            "vectorSearchProfile": "vector-profile-1"
        },
        {
            "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-1"
        }
    ],
    "vectorSearch": {
        "algorithms": [
            {
                "name": "hnsw-1",
                "kind": "hnsw",
                "hnswParameters": {
                    "m": 4,
                    "efConstruction": 400,
                    "efSearch": 500,
                    "metric": "cosine"
                }
            }
        ],
        "profiles": [
            {
                "name": "vector-profile-1",
                "algorithm": "hnsw-1"
            }
        ]
    }
}

Carga de datos vectoriales para la indexación

El contenido que proporciones para la indexación debe ajustarse al esquema de índice e incluir un valor de cadena único para la clave de documento. Los datos vectorizados previamente se cargan en uno o varios campos vectoriales, que pueden coexistir con otros campos que contienen contenido no vectorial.

Para la ingesta de datos, puede usar metodologías de inserción o extracción.

Use Documents - Index para cargar datos vectoriales y no vectoriales en un índice. Las API de inserción para la indexación son idénticas en todas las versiones estables y en versión preliminar. Use cualquiera de las API siguientes para cargar documentos:

POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/index?api-version=2024-07-01

{
    "value": [
        {
            "id": "1",
            "title": "Azure App Service",
            "content": "Azure App Service is a fully managed platform for building, deploying, and scaling web apps. You can host web apps, mobile app backends, and RESTful APIs. It supports a variety of programming languages and frameworks, such as .NET, Java, Node.js, Python, and PHP. The service offers built-in auto-scaling and load balancing capabilities. It also provides integration with other Azure services, such as Azure DevOps, GitHub, and Bitbucket.",
            "category": "Web",
            "titleVector": [
                -0.02250031754374504,
                 . . . 
                        ],
            "contentVector": [
                -0.024740582332015038,
                 . . .
            ],
            "@search.action": "upload"
        },
        {
            "id": "2",
            "title": "Azure Functions",
            "content": "Azure Functions is a serverless compute service that enables you to run code on-demand without having to manage infrastructure. It allows you to build and deploy event-driven applications that automatically scale with your workload. Functions support various languages, including C#, F#, Node.js, Python, and Java. It offers a variety of triggers and bindings to integrate with other Azure services and external services. You only pay for the compute time you consume.",
            "category": "Compute",
            "titleVector": [
                -0.020159931853413582,
                . . .
            ],
            "contentVector": [
                -0.02780858241021633,
                 . . .
            ],
            "@search.action": "upload"
        }
        . . .
    ]
}

Consulta del índice para el contenido vectorial

Para fines de validación, puede consultar el índice mediante el Explorador de búsqueda en Azure Portal o mediante una llamada a la API REST. Dado que Azure AI Search no puede convertir un vector en texto legible, intenta devolver campos del mismo documento que proporcionen evidencia de la coincidencia. Por ejemplo, si la consulta vectorial tiene como destino el titleVector campo, puede seleccionar title los resultados de la búsqueda.

Los campos deben atribuirse como retrievable para incluirse en los resultados.

  • Revise los índices de Administración de búsquedas>Índices para ver el tamaño del índice total y el tamaño del índice vectorial. Un tamaño de índice vectorial positivo indica que los vectores están presentes.

  • Use el Explorador de búsqueda para consultar un índice. El Explorador de búsqueda tiene dos vistas: vista de consulta (valor predeterminado) y vista JSON.

    • Establezca Opciones de consulta>Ocultar valores vectoriales en los resultados de la búsqueda para obtener resultados más legibles.

    • Use la vista JSON para las consultas vectoriales. Puede pegar una definición JSON de la consulta vectorial que desea ejecutar. Si el índice tiene una asignación de vectorizador, también puede usar la conversión integrada de texto a vector o de imagen a vector. Para obtener más información sobre la búsqueda de imágenes, consulte Inicio rápido: Búsqueda de imágenes en el Explorador de búsqueda.

    • Usa la vista de consulta predeterminada para obtener una confirmación rápida de que el índice contiene vectores. La vista de consulta es para la búsqueda de texto completo. Aunque no se puede usar para las consultas vectoriales, puedes enviar una búsqueda vacía (search=*) para comprobar el contenido. El contenido de todos los campos, incluidos los campos vectoriales, se devuelve como texto sin formato.

Para obtener más información, consulte Creación de una consulta vectorial.

Actualización de un índice vectorial

Para actualizar un índice vectorial, modifique el esquema y vuelva a cargar documentos para rellenar nuevos campos. Las API para las actualizaciones de esquema incluyen Crear o actualizar índice (REST), CreateOrUpdateIndex en el SDK de Azure para .NET, create_or_update_index en el SDK de Azure para Python y métodos similares en otros SDK de Azure.

Para obtener instrucciones estándar sobre cómo actualizar un índice, consulte Actualización o recompilación de un índice.

Entre los puntos clave se incluyen:

  • La eliminación y reconstrucción completa del índice suele ser necesaria para las actualizaciones y eliminaciones de los campos existentes.

  • Puede realizar las siguientes modificaciones sin requisito de recompilación:

    • Agregue nuevos campos a una colección de campos.
    • Agregue nuevas configuraciones de vectores, asignadas a nuevos campos, pero no a los campos existentes que ya están vectorizados.
    • Cambiar retrievable (los valores son true o false) en un campo existente. Los campos vectoriales deben ser buscables y recuperables, pero si quiere deshabilitar el acceso a un campo vectorial en situaciones en las que la eliminación y la recompilación no son factibles, puede establecer que se pueda recuperar en false.

Pasos siguientes

Como paso siguiente, se recomienda crear una consulta vectorial.

Los ejemplos de código del repositorio azure-search-vector-samples muestran flujos de trabajo de un extremo a otro que incluyen definición de esquema, vectorización, indexación y consultas.

Hay código de demostración para Python, C# y JavaScript.