Creación y búsqueda de índices vectoriales

En esta sección se describe cómo crear y administrar índices vectoriales, escribir elementos con datos vectoriales y realizar búsquedas de similitud mediante la API SearchVectors.

Antes de empezar

Antes de trabajar con índices vectoriales, verifique lo siguiente:

Puntos de conexión de SearchVectors

Las solicitudes de SearchVectors utilizan puntos de conexión de búsqueda vectorial, que son distintos de los puntos de conexión estándar de DynamoDB que se utilizan para crear y administrar índices vectoriales (por ejemplo, con CreateTable, UpdateTable y DescribeTable). Los AWS SDK y AWS CLI dirigen las solicitudes de SearchVectors al punto de conexión correcto automáticamente. No es necesario configurar ni invalidar el punto de conexión en el código de la aplicación.

Si va a crear un cliente HTTP personalizado que llame directamente a la API de DynamoDB sin un AWS SDK, utilice uno de los siguientes puntos de conexión de búsqueda vectorial y sustituya account-id y region según corresponda:

Generación de incrustaciones vectoriales

DynamoDB almacena y busca incrustaciones vectoriales, pero no las genera. Se producen incrustaciones con un modelo de incrustación, como los modelos Amazon Bedrock Titan Text Embeddings o Cohere Embed, o cualquier modelo de incrustación que se utilice. A continuación, se almacena el vector resultante en un elemento de DynamoDB y se pasa un vector de consulta a SearchVectors.

El flujo típico es:

La función de distancia que elija interactúa con la forma en que el modelo produce las incrustaciones. COSINE compara la dirección e ignora la magnitud, por lo que funciona con las incrustaciones estén o no normalizadas. DOT_PRODUCT es sensible a la magnitud: si las incrustaciones no están normalizadas a una unidad de longitud, los vectores más grandes reciben puntuaciones más altas independientemente de la dirección. Si utiliza DOT_PRODUCT y desea una similitud basada en la dirección, normalice las incrustaciones a unidades de longitud antes de almacenarlas. Consulte Cómo clasifican los resultados las funciones de distancia.

Creación de un índice vectorial

Puede crear un índice vectorial al crear una tabla nueva o agregar uno a una tabla existente.

Creación de una tabla con un índice vectorial

Utilice la API CreateTable con el parámetro VectorIndexes para crear una tabla con un índice vectorial. En el ejemplo de AWS CLI siguiente, se crea una tabla de Products con un índice vectorial denominado ProductEmbeddingIndex.

aws dynamodb create-table \
    --table-name Products \
    --attribute-definitions AttributeName=ProductId,AttributeType=S \
                            AttributeName=Category,AttributeType=S \
                            AttributeName=Brand,AttributeType=S \
    --key-schema AttributeName=ProductId,KeyType=HASH \
    --billing-mode PAY_PER_REQUEST \
    --vector-indexes \
        "[
            {
                \"IndexName\": \"ProductEmbeddingIndex\",
                \"VectorAttribute\": {\"AttributeName\": \"Embedding\"},
                \"SearchSchema\": [{\"AttributeName\":\"Category\",\"SearchSchemaElementType\":\"HASH\"},
                                  {\"AttributeName\":\"Brand\",\"SearchSchemaElementType\":\"INLINE_FILTER\"}],
                \"Projection\": {\"ProjectionType\": \"ALL\"},
                \"Dimensions\": 1536,
                \"DistanceFunction\": \"COSINE\"
            }
        ]"

En este ejemplo:

Adición de un índice vectorial a una tabla existente

Use la API de UpdateTable con el parámetro VectorIndexUpdates para agregar un índice vectorial a una tabla existente. En este ejemplo, se agrega un segundo índice independiente denominado ProductEmbeddingIndexV2 a la misma tabla de Products.

aws dynamodb update-table \
    --table-name Products \
    --vector-index-updates \
        "[
            {
                \"Create\": {
                    \"IndexName\": \"ProductEmbeddingIndexV2\",
                    \"VectorAttribute\": {\"AttributeName\": \"Embedding\"},
                    \"Projection\": {\"ProjectionType\": \"ALL\"},
                    \"Dimensions\": 1536,
                    \"DistanceFunction\": \"EUCLIDEAN\"
                }
            }
        ]"

Al agregar un índice vectorial a una tabla existente, DynamoDB informa del progreso del índice mediante dos campos de la respuesta DescribeTable: un valor IndexStatus y un booleano independiente Backfilling.

Puede crear o eliminar solo un índice vectorial por tabla a la vez. Este límite se comparte con la creación de índices secundarios globales en la misma tabla. Una segunda solicitud UpdateTable que crea o elimina un índice mientras hay otra operación de indexación en curso produce un error con LimitExceededException: Subscriber limit exceeded: Only 1 online index can be created or deleted simultaneously per table.

Esto también se aplica a una sola solicitud: una llamada UpdateTable que contiene dos acciones Create en su parámetro VectorIndexUpdates produce un error con el mismo error. Cree índices vectoriales de uno en uno, esperando a que cada uno alcance ACTIVE antes de comenzar con el siguiente. Como cada índice debe terminar de rellenarse antes de que el siguiente pueda empezar, crear varios índices vectoriales en una tabla lleva mucho más tiempo que crear uno solo.

Una solicitud CreateTable puede definir varios índices vectoriales a la vez, hasta el límite de cinco por tabla. Si se supera ese límite, se produce un error con ValidationException: One or more parameter values were invalid: VectorIndex count exceeds the per-table limit of 5.

Escritura de elementos con datos vectoriales

Los elementos se escriben con datos vectoriales mediante las API de escritura estándar de DynamoDB (PutItem, UpdateItem, BatchWriteItem, TransactWriteItems). Almacene la incrustación vectorial como una lista de números (tipo L que contiene N elementos).

Como un vector contiene muchos valores, guarde el elemento en un archivo como item.json, por ejemplo, y pase el archivo a la AWS CLI.

{
    "ProductId": { "S": "prod-123" },
    "Category": { "S": "Electronics" },
    "Title": { "S": "Wireless Headphones" },
    "Embedding": {
        "L": [
            { "N": "0.1234" },
            { "N": "-0.5678" },
            { "N": "0.9012" },
            ...
        ]
    }
}

aws dynamodb put-item \
    --table-name Products \
    --item file://item.json

DynamoDB valida los datos vectoriales al escribir elementos en una tabla que tiene un índice vectorial. En la tabla siguiente, se describe el comportamiento de validación.

Búsqueda con SearchVectors

Utilice la API SearchVectors para buscar los elementos de un índice vectorial que se parezcan más a un vector de consulta. Los resultados se clasifican por relevancia, y el elemento más similar se coloca primero. Los resultados de la búsqueda tienen coherencia final: es posible que transcurra un breve intervalo entre la escritura o actualización de un vector y su aparición en los resultados de la búsqueda. Para obtener más información, consulte Sincronización de escritura continua.

Búsqueda básica

En el siguiente ejemplo, se buscan los 10 elementos más similares del índice ProductEmbeddingIndex. Como este índice tiene una clave de partición de índice vectorial (Category) definida en su SearchSchema, SearchConditionExpression debe incluir el valor de la clave de partición de índice vectorial.

Guarde el vector de consulta en un archivo, por ejemplo query-vector.json, como una matriz JSON simple de valores numéricos.

[
    { "N": "0.1234" },
    { "N": "-0.5678" },
    { "N": "0.9012" },
    ...
]

aws dynamodb search-vectors \
    --table-name Products \
    --index-name ProductEmbeddingIndex \
    --search-vector file://query-vector.json \
    --top-k 10 \
    --search-condition-expression "Category = :cat" \
    --expression-attribute-values "{\":cat\": {\"S\": \"Electronics\"}}"

La respuesta incluye una matriz de SearchResults. Cada elemento contiene la coincidencia Item y una Score que indica el nivel de similitud del elemento al vector de consulta.

{
    "SearchResults": [
        {
            "Item": {
                "ProductId": { "S": "prod-456" },
                "Category": { "S": "Electronics" },
                "Title": { "S": "Bluetooth Speaker" }
            },
            "Score": 0.0023
        },
        {
            "Item": {
                "ProductId": { "S": "prod-789" },
                "Category": { "S": "Electronics" },
                "Title": { "S": "Noise Cancelling Earbuds" }
            },
            "Score": 0.0145
        }
    ]
}

El significado de Score depende de la función de distancia que haya elegido al crear el índice. Para COSINE y EUCLIDEAN, las puntuaciones más bajas indican una mayor similitud. Para DOT_PRODUCT, las puntuaciones más altas indican una mayor similitud.

Filtro con SearchConditionExpression

Use SearchConditionExpression para filtrar los resultados de la búsqueda en función de la clave de partición del índice vectorial y los atributos de filtro en línea definidos en el SearchSchema. Esta expresión utiliza la misma sintaxis que otros parámetros de expresión de DynamoDB.

En el siguiente ejemplo, se buscan los elementos de la categoría Electronics (clave de partición del índice vectorial) con un filtro en línea Brand.

aws dynamodb search-vectors \
    --table-name Products \
    --index-name ProductEmbeddingIndex \
    --search-vector file://query-vector.json \
    --top-k 10 \
    --search-condition-expression "Category = :cat AND Brand = :brand" \
    --expression-attribute-values "{\":cat\": {\"S\": \"Electronics\"}, \":brand\": {\"S\": \"Acme\"}}"

Si el índice vectorial tiene una clave de partición definida en el SearchSchema, debe incluirla en SearchConditionExpression. Los atributos de filtro en línea son opcionales.

El operador de igualdad (=) se admite en SearchConditionExpression para los atributos de clave de partición de índice vectorial y filtro en línea. Los operadores de comparación, rango y pertenencia a conjuntos (<>, <, <=, >, >=, IN) aún no están disponibles.

Este filtrado permite aplicar una búsqueda por similitud a un subconjunto de datos, un requisito habitual en las aplicaciones multiusuario y en las aplicaciones de generación aumentada por recuperación (RAG). Por ejemplo, para encontrar documentos similares a una consulta pero solo dentro de un inquilino, defina el atributo de inquilino como una clave de partición de índice vectorial (HASH) en el SearchSchema y pase su valor en cada búsqueda. Esto aísla los resultados para ese inquilino. También mejora el rendimiento, ya que la búsqueda examina solo los datos relevantes. Utilice los atributos de filtro en línea para establecer restricciones de igualdad adicionales, como el tipo o el estado del documento, que desee aplicar dentro de la partición enrutada.

Uso de ProjectionExpression

Utilice ProjectionExpression para devolver solo atributos específicos en los resultados de búsqueda. Esto puede reducir el tamaño de la respuesta cuando no necesite todos los atributos proyectados. Como ProductEmbeddingIndex define una clave de partición de índice vectorial (Category) en su SearchSchema, este ejemplo todavía incluye el valor de la clave de partición de índice vectorial en SearchConditionExpression.

aws dynamodb search-vectors \
    --table-name Products \
    --index-name ProductEmbeddingIndex \
    --search-vector file://query-vector.json \
    --top-k 5 \
    --search-condition-expression "Category = :cat" \
    --expression-attribute-values "{\":cat\": {\"S\": \"Electronics\"}}" \
    --projection-expression "ProductId, Title"

Eliminación de un índice vectorial

Utilice la API de UpdateTable con el parámetro VectorIndexUpdates para eliminar un índice vectorial.

aws dynamodb update-table \
    --table-name Products \
    --vector-index-updates \
        "[
            {\"Delete\": {\"IndexName\": \"ProductEmbeddingIndex\"}}
        ]"

Cuando elimina un índice vectorial, DynamoDB elimina el índice y todos sus datos. Esta operación no afecta a la tabla base ni a sus elementos.