Criação e pesquisa de índices vetoriais

Esta seção descreve como criar e gerenciar índices vetoriais, gravar itens com dados vetoriais e realizar pesquisas por similaridade usando a API SearchVectors.

Antes de começar

Antes de trabalhar com índices vetoriais, verifique o seguinte:

Endpoints de SearchVectors

As solicitações de SearchVectors usam endpoints dedicados de pesquisa vetorial, que são distintos dos endpoints padrão do DynamoDB que você usa para criar e gerenciar índices vetoriais (por exemplo, com CreateTable, UpdateTable e DescribeTable). Os SDKs da AWS e a AWS CLI encaminham as solicitações de SearchVectors para o endpoint correto automaticamente. Você não precisa configurar ou substituir o endpoint no código do seu aplicativo.

Se você estiver criando um cliente HTTP personalizado que chame a API do DynamoDB diretamente sem um SDK da AWS, use um dos seguintes endpoints de pesquisa vetorial, substituindo account-id e region conforme apropriado:

Geração de incorporações vetoriais

O DynamoDB armazena e pesquisa incorporações vetoriais, mas não as gera. Você produz incorporações com um modelo de incorporação, como os modelos do Amazon Bedrock Titan Text Embeddings ou Cohere Embed, ou qualquer modelo de incorporação que opere. Em seguida, você armazena o vetor resultante em um item do DynamoDB e transmite um vetor de consulta para SearchVectors.

O fluxo típico é:

A função de distância escolhida interage com a forma como seu modelo produz incorporações. COSINE compara a direção e ignora a magnitude, então funciona com incorporações, estejam elas normalizadas ou não. DOT_PRODUCT é sensível à magnitude: se as incorporações não forem normalizadas para o comprimento da unidade, vetores maiores receberão pontuações mais altas, independentemente da direção. Se você usar DOT_PRODUCT e quiser similaridade baseada em direção, normalize as incorporações para o comprimento unitário antes de armazená-las. Consulte Como as funções de distância classificam os resultados.

Criar um índice vetorial

Você pode criar um índice vetorial ao criar uma nova tabela ou adicionar um a uma tabela existente.

Criação de uma tabela com um índice vetorial

Use a API CreateTable com o parâmetro VectorIndexes para criar uma tabela com um índice vetorial. O exemplo de AWS CLI a seguir cria uma tabela Products com um índice vetorial chamado 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\"
            }
        ]"

Neste exemplo:

Adição de um índice vetorial a uma tabela existente

Use a API UpdateTable com o parâmetro VectorIndexUpdates para adicionar um índice vetorial a uma tabela existente. Este exemplo adiciona um segundo índice independente chamado ProductEmbeddingIndexV2 à mesma tabela Products.

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

Quando você adiciona um índice vetorial a uma tabela existente, o DynamoDB relata o andamento do índice por meio de dois campos na resposta DescribeTable: um valor IndexStatus e um booleano separado Backfilling.

Gravação de itens com dados vetoriais

Você grava itens com dados vetoriais usando as APIs de gravação padrão do DynamoDB (PutItem, UpdateItem, BatchWriteItem, TransactWriteItems). Armazene a incorporação vetorial como uma lista de números (tipo L contendo elementos N).

Como um vetor contém muitos valores, salve o item em um arquivo como item.json e, em seguida, transmita o arquivo para a 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

O DynamoDB valida dados vetoriais quando você grava itens em uma tabela que tem um índice vetorial. A tabela a seguir descreve o comportamento de validação.

Pesquisa com SearchVectors

Use a API SearchVectors para encontrar itens em um índice vetorial que sejam mais semelhantes a um vetor de consulta. Os resultados são classificados por relevância, com o item mais semelhante primeiro. Os resultados da pesquisa eventualmente são consistentes: pode haver um pequeno atraso entre gravar ou atualizar um vetor e ele aparecer nos resultados da pesquisa. Para obter mais informações, consulte Sincronização de gravações em andamento.

Pesquisa básica

O exemplo a seguir pesquisa os 10 itens mais semelhantes no índice ProductEmbeddingIndex. Como esse índice tem uma chave de partição de índice vetorial (Category) definida em SearchSchema, a SearchConditionExpression deve incluir o valor da chave de partição de índice vetorial.

Salve o vetor de consulta em um arquivo como query-vector.json, como uma matriz JSON simples 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\"}}"

A resposta inclui uma matriz SearchResults. Cada elemento contém o Item correspondente e uma Score que indica a semelhança do item com o vetor 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
        }
    ]
}

O significado da Score depende da função de distância escolhida ao criar o índice. Para COSINE e EUCLIDEAN, pontuações mais baixas indicam maior similaridade. Para DOT_PRODUCT, pontuações mais altas indicam maior similaridade.

Filtragem com SearchConditionExpression

Use SearchConditionExpression para filtrar os resultados da pesquisa com base na chave de partição do índice vetorial e nos atributos de filtro integrado definidos no SearchSchema. Essa expressão usa a mesma sintaxe de outros parâmetros de expressão do DynamoDB.

O exemplo a seguir pesquisa itens na categoria Electronics (chave de partição de índice vetorial) com um filtro integrado 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\"}}"

Se o índice vetorial tiver uma chave de partição definida no SearchSchema, você deverá incluí-la na SearchConditionExpression. Os atributos de filtro integrado são opcionais.

O operador de igualdade (=) é compatível com SearchConditionExpression tanto para a chave de partição do índice vetorial quanto para os atributos de filtro integrado. Os operadores de comparação, intervalo e associação por conjuntos (<>, <, <=, >, >=, IN) ainda não estão disponíveis.

Nessa filtragem, você define o escopo de uma pesquisa por similaridade em um subconjunto de seus dados, um requisito comum em aplicativos multilocatários e de geração aumentada via recuperação (RAG). Por exemplo, para encontrar documentos semelhantes a uma consulta, mas somente dentro de um locatário, defina o atributo do locatário como uma chave de partição de índice vetorial (HASH) no SearchSchema e transmita seu valor em cada pesquisa. Isso isola os resultados desse locatário. Também melhora o desempenho, porque a pesquisa examina somente os dados relevantes. Use atributos de filtro integrado para restrições de igualdade adicionais, como um tipo ou status de documento, que você deseja aplicar na partição roteada.

Uso da ProjectionExpression

Use ProjectionExpression para retornar apenas atributos específicos nos resultados da pesquisa. Isso pode reduzir o tamanho da resposta quando você não precisa de todos os atributos projetados. Como ProductEmbeddingIndex define uma chave de partição de índice vetorial (Category) em SearchSchema, esse exemplo ainda inclui o valor da chave de partição de índice vetorial em 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"

Excluir um índice de vetores

Use a API UpdateTable com o parâmetro VectorIndexUpdates para excluir um índice vetorial.

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

Quando você exclui um índice vetorial, o DynamoDB remove o índice e todos os dados. Essa operação não afeta a tabela de base nem os itens.