Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà. # 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` **Topics** + [Prima di iniziare](#VectorSearchWorkingWith.Prerequisites) + [SearchVectors endpoint](#VectorSearchWorkingWith.Endpoints) + [Generazione di incorporamenti vettoriali](#VectorSearchWorkingWith.Embeddings) + [Creazione di un indice vettoriale](#VectorSearchWorkingWith.Create) + [Scrittura di elementi con dati vettoriali](#VectorSearchWorkingWith.Write) + [Ricerca con SearchVectors](#VectorSearchWorkingWith.Search) + [Eliminazione di un indice vettoriale](#VectorSearchWorkingWith.Delete) ## 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 utilizzano solo la modalità di capacità su richiesta e richiedono una tabella che utilizzi anche la modalità di capacità su richiesta, quindi non è possibile combinare le due modalità di capacità. + La tua identità AWS Identity and Access Management (IAM) dispone delle `dynamodb:UpdateTable` autorizzazioni necessarie per `dynamodb:CreateTable` creare indici vettoriali. + La tua identità IAM dispone dell'`dynamodb:SearchVectors`autorizzazione 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 `SearchVectors`le 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 appropriato: {{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. 1. Memorizza quel vettore in un elemento DynamoDB, nell'attributo denominato dal vector index (`VectorAttribute`), come elenco (`L`) di numeri (). `N` 1. 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. Consulta [Requisiti e limitazioni](VectorSearch.Requirements.md). La funzione di distanza scelta interagisce con il modo in cui il modello produce gli incorporamenti. `COSINE`confronta 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. Consulta [In che modo le funzioni di distanza classificano i risultati](VectorSearch.md#VectorSearchWorkingWith.Ranking). ## Creazione di un indice vettoriale Puoi creare un indice vettoriale quando crei una nuova tabella o ne aggiungi uno a una tabella esistente. ### Creazione di una tabella con un indice vettoriale Usa l'`CreateTable`API 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 denominato`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\" } ]" ``` In questo esempio: + `VectorAttribute`specifica `Embedding` come attributo che contiene dati vettoriali. + `SearchSchema`definisce `Category` come una chiave di partizione dell'indice vettoriale (`HASH`), che partiziona l'indice per categoria per il ridimensionamento. Si definisce anche `Brand` come un`INLINE_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 su`COSINE`, dove i punteggi più bassi indicano una maggiore somiglianza. ### Aggiungere un indice vettoriale a una tabella esistente Usa l'`UpdateTable`API 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 separato`Backfilling`. 1. `IndexStatus`è ed è assente o`CREATING`. `Backfilling` `false` DynamoDB sta effettuando il provisioning dell'infrastruttura dell'indice. 1. `IndexStatus`è ed è`CREATING`. `Backfilling` `true` DynamoDB sta compilando l'indice a partire dai dati della tabella di base esistente. Le nuove scritture nella tabella di base vengono replicate nell'indice durante questa fase. `SearchVectors`restituisce un`ValidationException`. Questa fase può richiedere molto tempo anche quando il tavolo base contiene pochissimi elementi. 1. `IndexStatus`è `ACTIVE` e non `Backfilling` viene più segnalato. L'indice è pronto per la ricerca. **Non è possibile eseguire la ricerca mentre l'indice è in fase di riempimento** `SearchVectors`restituisce un intervallo di `ValidationException` tempo in cui un indice vettoriale è in fase di riempimento. Usalo `DescribeTable` per controllare sia il `IndexStatus` flag che il `Backfilling` flag e attendi che `IndexStatus` sia `ACTIVE` e non `Backfilling` sia `true` prima di effettuare la ricerca. Non esiste un valore per lo stato `BACKFILLING` dell'indice; un indice che compila i report `IndexStatus` `CREATING` con un valore `Backfilling` impostato `true` su. **Un indice appena pronto non è immediatamente ricercabile** `SearchVectors`le richieste sono servite da un endpoint di ricerca dedicato, separato dall'endpoint che serve. `DescribeTable` Dopo i `DescribeTable` primi report `IndexStatus``ACTIVE`, l'endpoint di ricerca può richiedere più tempo prima di iniziare a fornire l'indice. Durante tale intervallo `SearchVectors` restituisce un`ValidationException`, in genere`The table does not have the specified index`. Considera «a» `ValidationException` sulle prime ricerche dopo la creazione dell'indice come riutilizzabile anziché come un errore. Il codice che viene eseguito immediatamente dopo l'osservazione `ACTIVE` può sembrare funzionare in un ambiente e fallire in un altro. L'intervallo è breve e varia. Per un controllo di idoneità che non dipenda da nessuno dei due campi di stato, inviate una `SearchVectors` richiesta reale in un ciclo di ripetizioni. Considerate la prima risposta positiva come il segnale che l'indice è pronto. È possibile creare o eliminare un solo indice vettoriale per tabella alla volta. Questo limite è condiviso con la creazione di un indice secondario globale sulla stessa tabella. Una seconda `UpdateTable` richiesta che crea o elimina un indice mentre è in corso un'altra operazione sull'indice ha esito negativo. `LimitExceededException: Subscriber limit exceeded: Only 1 online index can be created or deleted simultaneously per table` Ciò vale anche per una singola richiesta: una `UpdateTable` chiamata contenente due `Create` azioni nel relativo `VectorIndexUpdates` parametro ha esito negativo con lo stesso errore. Crea gli indici vettoriali uno alla volta, aspettando che ciascuno arrivi `ACTIVE` prima di iniziare il successivo. Poiché ogni indice deve terminare il riempimento prima di poter iniziare il successivo, la creazione di più indici vettoriali su una tabella richiede molto più tempo rispetto alla creazione di uno. Una `CreateTable` richiesta può definire più indici vettoriali contemporaneamente, fino al limite di cinque per tabella. Il superamento di tale limite non riesce con. `ValidationException: One or more parameter values were invalid: VectorIndex count exceeds the per-table limit of 5` ## 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 (`L`tipo contenente elementi). `N` Poiché un vettore contiene molti valori, salva l'elemento in un file come`item.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. In`item.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 con`UpdateItem`), 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'`SearchVectors`API 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 delle scritture](VectorSearchDataSync.md#VectorSearchDataSync.OngoingWrites). ### Ricerca di base L'esempio seguente cerca i 10 elementi più simili nell'`ProductEmbeddingIndex`indice. 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 esempio`query-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 un`ProjectionExpression`. Per ulteriori informazioni, consulta [Usando ProjectionExpression](#VectorSearchWorkingWith.Search.Projection). **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` e`EUCLIDEAN`, i punteggi più bassi indicano una maggiore somiglianza. Per`DOT_PRODUCT`, i punteggi più alti indicano una maggiore somiglianza. ### Filtraggio con SearchConditionExpression `SearchConditionExpression`Da 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:SearchVectors`autorizzazione sull'indice può cercare qualsiasi valore della chiave di partizione. Poiché le chiavi di condizione di controllo di accesso granulari (FGAC) non si applicano a`SearchVectors`, `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 `ProjectionExpression`Da 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'`UpdateTable`API 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.