Creazione e ricerca di indici vettoriali

Questa sezione descrive come creare e gestire indici vettoriali, scrivere elementi con dati vettoriali ed eseguire ricerche di similarità utilizzando l'API. SearchVectors

Prima di iniziare

Prima di lavorare con gli indici vettoriali, verifica quanto segue:

• La tabella utilizza la modalità di capacità su richiesta (). PAY_PER_REQUEST Gli indici vettoriali non sono supportati nelle tabelle di capacità assegnate.

• La tua identità AWS Identity and Access Management (IAM) dispone dynamodb:CreateTable delle dynamodb:UpdateTable autorizzazioni necessarie per creare indici vettoriali.

• La tua identità IAM dispone dell'dynamodb:SearchVectorsautorizzazione sulla risorsa dell'indice vettoriale per eseguire ricerche. Il formato ARN della risorsa èarn:aws:dynamodb:region:account-id:table/table-name/index/index-name.

SearchVectors endpoint

SearchVectorsle richieste utilizzano endpoint dedicati alla ricerca vettoriale, distinti dagli endpoint DynamoDB standard utilizzati per creare e gestire indici vettoriali (ad esempio, con, e). CreateTable UpdateTable DescribeTable Gli AWS SDK e indirizzano automaticamente le richieste verso l'endpoint corretto. AWS CLI SearchVectors Non è necessario configurare o sovrascrivere l'endpoint nel codice dell'applicazione.

Se stai creando un client HTTP personalizzato che richiama direttamente l'API DynamoDB senza un AWS SDK, utilizza uno dei seguenti endpoint di ricerca vettoriale, sostituendo e, se necessario: account-id region

• account-id.search-ddb.region.amazonaws.com— endpoint. Account-based

• search-dynamodb.region.api.aws— Dual-stack endpoint, compatibile sia con IPv4 che con IPv6.

Generazione di incorporamenti vettoriali

DynamoDB archivia e ricerca gli incorporamenti vettoriali, ma non li genera. Produci incorporamenti con un modello di incorporamento, come i modelli Amazon Bedrock Titan Text Embeddings o Cohere Embed, o qualsiasi modello di incorporamento che utilizzi. Quindi memorizzi il vettore risultante in un elemento DynamoDB e passi un vettore di query a. SearchVectors

Il vettore di interrogazione e i vettori memorizzati devono utilizzare lo stesso modello

Il vettore di query a cui si passa SearchVectors e i vettori memorizzati negli elementi devono essere prodotti dallo stesso modello di incorporamento e devono avere lo stesso numero di dimensioni dell'indice vettoriale. La combinazione di modelli o l'interrogazione con un numero di dimensioni diverso da quello con cui è stato creato l'indice produce risultati privi di significato o un errore di convalida.

Il flusso tipico è:

1. Invia il contenuto di origine (ad esempio, una descrizione del prodotto) a un modello di incorporamento e ricevi un vettore.

2. Memorizza quel vettore in un elemento DynamoDB, nell'attributo denominato dal vector index (VectorAttribute), come elenco (L) di numeri (). N

3. Al momento della query, genera un vettore dal testo di ricerca utilizzando lo stesso modello e passalo come. SearchVector

Scegli il tuo modello di incorporamento prima di creare l'indice

Scegliete il modello di incorporamento prima di creare l'indice vettoriale, poiché il modello determina il numero di dimensioni. I modelli di incorporamento più comuni producono dimensioni 384, 768, 1024, 1536 o 3072. DynamoDB supporta fino a 4.096 dimensioni. Per informazioni, consulta Requisiti e limitazioni.

La funzione di distanza scelta interagisce con il modo in cui il modello produce gli incorporamenti. COSINEconfronta la direzione e ignora la grandezza, quindi funziona con gli incorporamenti indipendentemente dal fatto che siano normalizzati o meno. DOT_PRODUCTè sensibile alla grandezza: se gli incorporamenti non sono normalizzati alla lunghezza unitaria, i vettori più grandi ricevono punteggi più alti indipendentemente dalla direzione. Se utilizzi DOT_PRODUCT e desideri una somiglianza basata sulla direzione, normalizza gli incorporamenti in base alla lunghezza unitaria prima di memorizzarli. Per informazioni, consulta In che modo le funzioni di distanza classificano i risultati.

Creazione di un indice vettoriale

È possibile creare un indice vettoriale quando si crea una nuova tabella o se ne aggiunge una a una esistente.

Creazione di una tabella con un indice vettoriale

Usa l'CreateTableAPI con il VectorIndexes parametro per creare una tabella con un indice vettoriale. L' AWS CLI esempio seguente crea una Products tabella con un indice vettoriale denominatoProductEmbeddingIndex.

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\"
            }
        ]"

In questo esempio:

• VectorAttributespecifica Embedding come attributo che contiene dati vettoriali.

• SearchSchemadefinisce Category come una chiave di partizione dell'indice vettoriale (HASH), che partiziona l'indice per categoria per il ridimensionamento. Si definisce anche Brand come unINLINE_FILTER, che consente di filtrare i risultati della ricerca per marchio a livello di archiviazione. Poiché entrambi Category Brand fanno riferimento in SearchSchema, devono essere dichiarati anche in, allo stesso modo in AttributeDefinitions cui vengono dichiarati gli attributi chiave per un indice secondario globale.

• Dimensionsè impostato su 1536, corrispondente all'output dei modelli di incorporamento più comuni.

• DistanceFunctionè impostato suCOSINE, dove i punteggi più bassi indicano una maggiore somiglianza.

Aggiungere un indice vettoriale a una tabella esistente

Usa l'UpdateTableAPI con il VectorIndexUpdates parametro per aggiungere un indice vettoriale a una tabella esistente. Questo esempio aggiunge un secondo indice indipendente denominato ProductEmbeddingIndexV2 alla stessa Products tabella.

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

Quando aggiungi un indice vettoriale a una tabella esistente, DynamoDB riporta l'avanzamento dell'indice attraverso due campi nella DescribeTable risposta: un IndexStatus valore e un booleano separatoBackfilling.

1. IndexStatusis CREATING — DynamoDB sta configurando l'infrastruttura dell'indice.

2. IndexStatusè ACTIVE Backfilling impostato sutrue: DynamoDB sta popolando l'indice con i dati esistenti della tabella di base. Durante questa fase, anche le nuove scritture nella tabella di base vengono replicate nell'indice. Durante il riempimento di un indice vettoriale, SearchVectors restituisce un errore. Attendi che Backfilling sia pronto false prima di eseguire la ricerca.

3. IndexStatusè ACTIVE Backfilling impostato su false (o assente): l'indice è completamente popolato e pronto per le operazioni di ricerca.

Non è possibile eseguire la ricerca mentre l'indice è in fase di riempimento

SearchVectorsrestituisce un errore durante il riempimento di un indice vettoriale. DescribeTableUsalo per controllare sia il IndexStatus flag che il Backfilling flag e attendi che sia ACTIVE e IndexStatus Backfilling sia false prima di effettuare la ricerca. Non esiste un valore per lo stato BACKFILLING dell'indice.

Scrittura di elementi con dati vettoriali

Scrivi elementi con dati vettoriali utilizzando le API di scrittura standard di DynamoDB (PutItem,,UpdateItem,BatchWriteItem). TransactWriteItems Memorizza l'incorporamento vettoriale come elenco di numeri (Ltipo contenente elementi). N

Poiché un vettore contiene molti valori, salva l'elemento in un file comeitem.json, quindi passa il file 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

La lunghezza del vettore deve corrispondere alle dimensioni dell'indice

Il Embedding vettore mostrato qui è abbreviato. Initem.json, deve contenere 1.536 valori corrispondenti a quelli Dimensions impostati. ProductEmbeddingIndex La scrittura di un vettore con un numero errato di dimensioni viene rifiutata.

DynamoDB convalida i dati vettoriali quando si scrivono elementi in una tabella con un indice vettoriale. La tabella seguente descrive il comportamento di convalida.

Condizione	Comportamento
L'attributo vettoriale ha un numero errato di dimensioni	La scrittura è rifiutata.
Manca l'attributo chiave della partizione dell'indice vettoriale	La scrittura ha esito positivo sulla tabella di base, ma l'elemento non viene replicato nell'indice vettoriale.
Il tipo di attributo della chiave di partizione dell'indice vettoriale non corrisponde allo schema dell'indice	La scrittura è rifiutata.
Manca l'attributo del filtro in linea	La scrittura ha esito positivo e l'elemento viene replicato nell'indice vettoriale.
I valori vettoriali hanno una precisione maggiore rispetto alla virgola mobile a 32 bit (f32)	La scrittura ha esito positivo. I valori vengono memorizzati così come sono nella tabella di base ma perdono precisione quando vengono replicati nell'indice vettoriale.
L'attributo vettoriale viene eliminato da un elemento	La voce corrispondente nell'indice vettoriale viene eliminata.

La chiave di partizione mancante causa la deindicizzazione silenziosa

Se l'indice vettoriale definisce una chiave di partizione in SearchSchema e si scrive un elemento senza tale attributo (o lo si rimuove conUpdateItem), la scrittura ha esito positivo nella tabella di base ma l'elemento viene escluso silenziosamente dall'indice vettoriale. Non verrà visualizzato nei SearchVectors risultati anche se l'elemento della tabella di base e il relativo incorporamento vettoriale esistono ancora. Assicurati che ogni elemento che desideri sia ricercabile contenga l'attributo chiave di partizione dell'indice vettoriale.

Gli incorporamenti obsoleti producono risultati errati

DynamoDB non ricalcola gli incorporamenti per te. Se modifichi il contenuto sorgente che ha prodotto un incorporamento (ad esempio, modifichi una descrizione del prodotto), il vettore archiviato non si aggiorna automaticamente. È necessario rigenerare l'incorporamento con il modello di incorporamento e riscrivere il nuovo vettore sull'elemento. In caso contrario, l'indice vettoriale continua a restituire risultati basati sul vecchio vettore obsoleto, che può produrre automaticamente corrispondenze errate.

Ricerca con SearchVectors

Usa l'SearchVectorsAPI per trovare gli elementi in un indice vettoriale che sono più simili a un vettore di query. I risultati sono ordinati per rilevanza, con l'elemento più simile per primo. I risultati della ricerca alla fine sono coerenti: potrebbe esserci un breve ritardo tra la scrittura o l'aggiornamento di un vettore e la sua visualizzazione nei risultati di ricerca. Per ulteriori informazioni, consulta Sincronizzazione continua della scrittura.

Ricerca di base

L'esempio seguente cerca i 10 elementi più simili nell'ProductEmbeddingIndexindice. Poiché questo indice contiene una chiave di partizione dell'indice vettoriale (Category) SearchSchema, SearchConditionExpression deve includere il valore della chiave di partizione dell'indice vettoriale.

Salvate il vettore di interrogazione in un file, ad esempioquery-vector.json, come un semplice array JSON di valori numerici.

[
    { "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 risposta include un SearchResults array. Ogni elemento contiene la corrispondenza Item e una Score che indica la somiglianza dell'elemento al vettore di interrogazione.

{
    "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
        }
    ]
}

Per impostazione predefinita, gli attributi del vettore sono esclusi dai risultati

Per impostazione predefinita, i risultati di SearchVectors non includono l'attributo vector (l'incorporamento). I dati vettoriali sono di grandi dimensioni e in genere non sono necessari nella risposta. I risultati includono gli altri attributi proiettati e il Score valore. Per includere l'attributo vector, richiedilo con unProjectionExpression. Per ulteriori informazioni, consulta Usando ProjectionExpression.

SearchVector è un elenco semplice, non di tipo DynamoDB L

Il parametro SearchVector request è un semplice array JSON di oggetti numerici (). [{"N": "0.1234"}, ...] Non inserirlo in un L tipo DynamoDB come faresti quando memorizzi un vettore in un attributo item. Il L wrapper viene utilizzato solo quando si scrivono o si leggono dati vettoriali negli attributi dell'elemento.

Il significato di Score dipende dalla funzione di distanza scelta al momento della creazione dell'indice. Per COSINE eEUCLIDEAN, i punteggi più bassi indicano una maggiore somiglianza. PerDOT_PRODUCT, i punteggi più alti indicano una maggiore somiglianza.

Filtraggio con SearchConditionExpression

SearchConditionExpressionDa utilizzare per filtrare i risultati della ricerca in base alla chiave di partizione dell'indice vettoriale e agli attributi del filtro in linea definiti in. SearchSchema Questa espressione utilizza la stessa sintassi degli altri parametri di espressione DynamoDB.

L'esempio seguente cerca gli elementi nella Electronics categoria (chiave di partizione dell'indice vettoriale) con un filtro in linea. 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 il tuo indice vettoriale ha una chiave di partizione definita in SearchSchema, devi includerla in. SearchConditionExpression Gli attributi del filtro in linea sono opzionali.

L'operatore di uguaglianza (=) è supportato sia SearchConditionExpression per la chiave di partizione dell'indice vettoriale che per gli attributi del filtro in linea. Gli operatori di confronto, intervallo e appartenenza ai set (<>,,,<, <= >>=,IN) non sono ancora disponibili.

Questo filtro consente di definire l'ambito di una ricerca di similarità con un sottoinsieme di dati, un requisito comune nelle applicazioni multi-tenant e Retrieval Augmented Generation (RAG). Ad esempio, per trovare documenti simili a una query ma solo all'interno di un tenant, definisci l'attributo tenant come chiave di partizione dell'indice vettoriale () in e passane il valore in ogni ricerca. HASH SearchSchema Questo isola i risultati relativi a quel tenant. Inoltre, migliora le prestazioni, poiché la ricerca esamina solo i dati pertinenti. Utilizzate gli attributi del filtro in linea per ulteriori vincoli di uguaglianza, ad esempio il tipo o lo stato del documento, da applicare all'interno della partizione indirizzata.

L'ambito delle chiavi di partizione non è un limite di sicurezza

L'utilizzo di una chiave di partizione per definire l'ambito delle ricerche su un singolo tenant è un'ottimizzazione della località dei dati e delle prestazioni, non un meccanismo di controllo degli accessi. Qualsiasi principale che detiene l'dynamodb:SearchVectorsautorizzazione sull'indice può cercare qualsiasi valore della chiave di partizione. Poiché le chiavi di condizione di controllo di accesso granulari (FGAC) non si applicano aSearchVectors, dynamodb:LeadingKeys non è possibile limitare l'accesso ai singoli valori delle chiavi di partizione a livello di policy IAM. Se il carico di lavoro richiede un rigoroso isolamento dei tenant a livello di dati, utilizza tabelle o indici separati con concessioni IAM distinte per ogni tenant.

Usando ProjectionExpression

ProjectionExpressionDa utilizzare per restituire solo attributi specifici nei risultati della ricerca. Questo può ridurre la dimensione della risposta quando non sono necessari tutti gli attributi proiettati. Poiché ProductEmbeddingIndex definisce una chiave di partizione dell'indice vettoriale (Category) al suo interno SearchSchema, questo esempio include ancora il valore della chiave di partizione dell'indice vettoriale in. 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"

Possono essere restituiti solo gli attributi proiettati

È possibile restituire solo gli attributi proiettati nell'indice vettoriale. Gli attributi che non sono nella proiezione dell'indice non possono essere restituiti da. SearchVectors

Eliminazione di un indice vettoriale

Usa l'UpdateTableAPI con il VectorIndexUpdates parametro per eliminare un indice vettoriale.

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

Quando elimini un indice vettoriale, DynamoDB rimuove l'indice e tutti i relativi dati. Questa operazione non influisce sulla tabella base o sui suoi elementi.