Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.
Vektorindizes erstellen und durchsuchen
In diesem Abschnitt wird beschrieben, wie Sie Vektorindizes erstellen und verwalten, Elemente mit Vektordaten schreiben und Ähnlichkeitssuchen mithilfe der API durchführen. SearchVectors
Themen
Bevor Sie beginnen
Bevor Sie mit Vektorindizes arbeiten, überprüfen Sie Folgendes:
-
Ihre Tabelle verwendet den On-Demand-Kapazitätsmodus (
PAY_PER_REQUEST). Vektorindizes werden in Tabellen mit bereitgestellter Kapazität nicht unterstützt. -
Ihre AWS Identity and Access Management (IAM
dynamodb:CreateTable-) Identität verfügt über unseredynamodb:UpdateTableBerechtigungen zum Erstellen von Vektorindizes. -
Ihre IAM-Identität ist für die Vektorindexressource
dynamodb:SearchVectorsberechtigt, Suchvorgänge durchzuführen. Das ARN-Format der Ressource lautetarn:aws:dynamodb:.region:account-id:table/table-name/index/index-name
SearchVectors Endpunkte
SearchVectorsAnfragen verwenden dedizierte Endpunkte für die Vektorsuche, die sich von den Standard-DynamoDB-Endpunkten unterscheiden, die Sie zum Erstellen und Verwalten von Vektorindizes verwenden (z. B. with, und). CreateTable UpdateTable DescribeTable Die AWS SDKs leiten Anfragen automatisch an den richtigen Endpunkt weiter AWS CLI . SearchVectors Sie müssen den Endpunkt in Ihrem Anwendungscode nicht konfigurieren oder überschreiben.
Wenn Sie einen benutzerdefinierten HTTP-Client erstellen, der die DynamoDB-API direkt ohne AWS SDK aufruft, verwenden Sie einen der folgenden Endpunkte für die Vektorsuche und ersetzen Sie gegebenenfalls und: account-id region
-
account-id.search-ddb.region.amazonaws.com -
search-dynamodb.— Dual-stack Endpunkt, kompatibel mit IPv4 und IPv6.region.api.aws
Generieren von Vektor-Einbettungen
DynamoDB speichert und durchsucht Vektoreinbettungen, generiert sie jedoch nicht. Sie erstellen Einbettungen mit einem Einbettungsmodell wie den Modellen Amazon Bedrock Titan Text Embeddings oder Cohere Embed oder einem anderen von Ihnen verwendeten Einbettungsmodell. Anschließend speichern Sie den resultierenden Vektor in einem DynamoDB-Element und übergeben einen Abfrage-Vektor an. SearchVectors
Der Abfrage-Vektor und die gespeicherten Vektoren müssen dasselbe Modell verwenden
Der Abfrage-Vektor, an den Sie übergeben, SearchVectors und die in Ihren Elementen gespeicherten Vektoren müssen von demselben Einbettungsmodell erzeugt werden und müssen dieselbe Anzahl von Dimensionen wie der Vektorindex haben. Das Mischen von Modellen oder Abfragen mit einer anderen Anzahl von Dimensionen als der, mit der der Index erstellt wurde, führt zu bedeutungslosen Ergebnissen oder zu einem Validierungsfehler.
Der typische Ablauf ist:
-
Senden Sie Ihren Quellinhalt (z. B. eine Produktbeschreibung) an ein Einbettungsmodell und erhalten Sie einen Vektor.
-
Speichern Sie diesen Vektor in einem DynamoDB-Element in dem vom Vektorindex (
VectorAttribute) benannten Attribut als Liste (L) von Zahlen ().N -
Generieren Sie zur Abfragezeit einen Vektor aus dem Suchtext unter Verwendung desselben Modells und übergeben Sie ihn als.
SearchVector
Wählen Sie Ihr Einbettungsmodell aus, bevor Sie den Index erstellen
Wählen Sie Ihr Einbettungsmodell aus, bevor Sie den Vektorindex erstellen, da das Modell die Anzahl der Dimensionen bestimmt. Gängige Einbettungsmodelle erzeugen 384, 768, 1024, 1536 oder 3072 Dimensionen. DynamoDB unterstützt bis zu 4.096 Dimensionen. Siehe Anforderungen und Einschränkungen.
Die von Ihnen gewählte Abstandsfunktion wirkt sich darauf aus, wie Ihr Modell Einbettungen erzeugt. COSINEvergleicht die Richtung und ignoriert die Größe. Sie funktioniert also mit Einbettungen, unabhängig davon, ob sie normalisiert sind oder nicht. DOT_PRODUCTreagiert empfindlich auf die Größe: Wenn Ihre Einbettungen nicht auf Längeneinheiten normalisiert sind, erhalten größere Vektoren unabhängig von der Richtung höhere Werte. Wenn Sie eine richtungsbasierte Ähnlichkeit verwenden DOT_PRODUCT und wünschen, normalisieren Sie Ihre Einbettungen auf Längeneinheiten, bevor Sie sie speichern. Siehe Wie ordnen Entfernungsfunktionen Ergebnisse.
Einen Vektorindex erstellen
Sie können einen Vektorindex erstellen, wenn Sie eine neue Tabelle erstellen oder einer vorhandenen Tabelle einen hinzufügen.
Eine Tabelle mit einem Vektorindex erstellen
Verwenden Sie die CreateTable API mit dem VectorIndexes Parameter, um eine Tabelle mit einem Vektorindex zu erstellen. Im folgenden AWS CLI Beispiel wird eine Products Tabelle mit einem Vektorindex namens erstelltProductEmbeddingIndex.
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 diesem Beispiel:
-
VectorAttributegibtEmbeddingals das Attribut an, das Vektordaten enthält. -
SearchSchemadefiniertCategoryals Vektorindex einen Partitionsschlüssel (HASH), der den Index zur Skalierung nach Kategorien partitioniert. Es definiert sich auchBrandals einINLINE_FILTER, mit dem Sie Suchergebnisse auf der Speicherebene nach Marke filtern können. Da aufBrandbeideCategoryund in der verwiesen wird SearchSchema, müssen sie auch in deklariert werdenAttributeDefinitions, genauso wie Schlüsselattribute für einen globalen sekundären Index deklariert werden. -
Dimensionsist auf 1536 gesetzt, was der Ausgabe gängiger Einbettungsmodelle entspricht. -
DistanceFunctionist auf gesetztCOSINE, wobei niedrigere Werte auf eine größere Ähnlichkeit hinweisen.
Hinzufügen eines Vektorindexes zu einer vorhandenen Tabelle
Verwenden Sie die UpdateTable API mit dem VectorIndexUpdates Parameter, um einer vorhandenen Tabelle einen Vektorindex hinzuzufügen. In diesem Beispiel wird ein zweiter, unabhängiger Index mit ProductEmbeddingIndexV2 dem Namen derselben Products Tabelle hinzugefügt.
aws dynamodb update-table \ --table-name Products \ --vector-index-updates \ "[ { \"Create\": { \"IndexName\": \"ProductEmbeddingIndexV2\", \"VectorAttribute\": {\"AttributeName\": \"Embedding\"}, \"Projection\": {\"ProjectionType\": \"ALL\"}, \"Dimensions\": 1536, \"DistanceFunction\": \"EUCLIDEAN\" } } ]"
Wenn Sie einer vorhandenen Tabelle einen Vektorindex hinzufügen, meldet DynamoDB den Indexfortschritt anhand von zwei Feldern in der DescribeTable Antwort: einem IndexStatus Wert und einem separaten Backfilling booleschen Wert.
-
IndexStatusistCREATING— DynamoDB richtet die Indexinfrastruktur ein. -
IndexStatusistACTIVEmitBackfillinggesetzt auftrue— DynamoDB füllt den Index mit vorhandenen Daten aus der Basistabelle. Neue Schreibvorgänge in die Basistabelle werden in dieser Phase ebenfalls in den Index repliziert. Während ein Vektorindex aufgefüllt wird, wird ein FehlerSearchVectorszurückgegeben. Warten Sie, bisBackfillinges soweit istfalse, bevor Sie suchen. -
IndexStatusistACTIVEaufBackfillinggesetztfalse(oder fehlt) — Der Index ist vollständig gefüllt und bereit für Suchvorgänge.
Sie können nicht suchen, während der Index aufgefüllt wird
SearchVectorsgibt einen Fehler zurück, während ein Vektorindex aufgefüllt wird. Verwenden Sie diese OptionDescribeTable, um sowohl das IndexStatus als auch das Backfilling Flag zu überprüfen und zu warten, bis IndexStatus es ACTIVE und Backfilling ist, false bevor Sie suchen. Es gibt keinen BACKFILLING Indexstatuswert.
Elemente mit Vektordaten schreiben
Sie schreiben Elemente mit Vektordaten mithilfe der Standard-DynamoDB-Schreib-APIs (PutItem,, UpdateItemBatchWriteItem,TransactWriteItems). Speichern Sie die Vektoreinbettung als Liste von Zahlen (LTyp, der Elemente enthältN).
Da ein Vektor viele Werte enthält, speichern Sie das Element in einer Datei wieitem.json, und übergeben Sie die Datei dann an die 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
Die Länge des Vektors muss den Indexabmessungen entsprechen
Der hier gezeigte Embedding Vektor ist abgekürzt. Initem.json, er muss 1.536 Werte enthalten, um den von Dimensions Ihnen eingestellten Werten zu entsprechen. ProductEmbeddingIndex Das Schreiben eines Vektors mit der falschen Anzahl von Dimensionen wird abgelehnt.
DynamoDB validiert Vektordaten, wenn Sie Elemente in eine Tabelle schreiben, die über einen Vektorindex verfügt. In der folgenden Tabelle wird das Validierungsverhalten beschrieben.
| Bedingung | Behavior |
|---|---|
| Das Vektorattribut hat eine falsche Anzahl von Dimensionen | Der Schreibvorgang wurde abgelehnt. |
| Das Partitionsschlüsselattribut für den Vektorindex fehlt | Der Schreibvorgang in die Basistabelle ist erfolgreich, aber das Element wird nicht in den Vektorindex repliziert. |
| Der Attributtyp des Vektorindex-Partitionsschlüssels entspricht nicht dem Indexschema | Der Schreibvorgang wurde abgelehnt. |
| Das Inline-Filterattribut fehlt | Der Schreibvorgang ist erfolgreich und das Element wird in den Vektorindex repliziert. |
| Vektorwerte haben eine höhere Genauigkeit als 32-Bit-Gleitkommawerte (f32) | Der Schreibvorgang war erfolgreich. Werte werden unverändert in der Basistabelle gespeichert, verlieren jedoch an Genauigkeit, wenn sie in den Vektorindex repliziert werden. |
| Das Vektorattribut wird aus einem Element gelöscht | Der entsprechende Eintrag im Vektorindex wird gelöscht. |
Ein fehlender Partitionsschlüssel führt zu einer unbeaufsichtigten Deindexierung
Wenn Ihr Vektorindex einen Partitionsschlüssel in der definiert SearchSchema und Sie ein Element ohne dieses Attribut schreiben (oder es mit entfernenUpdateItem), ist der Schreibvorgang in der Basistabelle erfolgreich, aber das Element wird stillschweigend aus dem Vektorindex ausgeschlossen. Es erscheint nicht in den SearchVectors Ergebnissen, obwohl das Element der Basistabelle und seine Vektoreinbettung noch existieren. Stellen Sie sicher, dass jedes Element, das durchsuchbar sein soll, das Schlüsselattribut für die Vektorindexpartition enthält.
Veraltete Einbettungen führen zu falschen Ergebnissen
DynamoDB berechnet Einbettungen nicht für Sie neu. Wenn Sie den Quellinhalt ändern, der zu einer Einbettung geführt hat (z. B. wenn Sie eine Produktbeschreibung bearbeiten), wird der gespeicherte Vektor nicht automatisch aktualisiert. Sie müssen die Einbettung mit Ihrem Einbettungsmodell neu generieren und den neuen Vektor zurück in das Element schreiben. Andernfalls gibt der Vektorindex weiterhin Ergebnisse zurück, die auf dem alten, veralteten Vektor basieren, was unbemerkt zu falschen Übereinstimmungen führen kann.
Suchen mit SearchVectors
Verwenden Sie die SearchVectors API, um Elemente in einem Vektorindex zu finden, die einem Abfrage-Vektor am ähnlichsten sind. Die Ergebnisse werden nach Relevanz sortiert, wobei das ähnlichste Element zuerst angezeigt wird. Die Suchergebnisse sind letztendlich konsistent: Zwischen dem Schreiben oder Aktualisieren eines Vektors und seiner Anzeige in den Suchergebnissen kann es zu einer kurzen Verzögerung kommen. Weitere Informationen finden Sie unter Fortlaufende Schreibsynchronisierung.
Einfache Suche
Im folgenden Beispiel wird nach den 10 ähnlichsten Elementen im ProductEmbeddingIndex Index gesucht. Da für diesen Index ein Vektorindex-Partitionsschlüssel (Category) definiert ist SearchSchema, SearchConditionExpression muss er den Wert des Vektorindex-Partitionsschlüssels enthalten.
Speichern Sie den Abfrage-Vektor in einer Dateiquery-vector.json, z. B. als einfaches JSON-Array mit Zahlenwerten.
[ { "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\"}}"
Die Antwort enthält ein SearchResults Array. Jedes Element enthält das passende Element Item und einScore, das angibt, wie ähnlich das Element dem Abfragevektor ist.
{ "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 } ] }
Vektorattribute sind standardmäßig aus den Ergebnissen ausgeschlossen
Standardmäßig enthalten die Ergebnisse von das Vektorattribut (die Einbettung) SearchVectors nicht. Vektordaten sind umfangreich und werden in der Antwort in der Regel nicht benötigt. Die Ergebnisse beinhalten die anderen projizierten Attribute und den Score Wert. Um das Vektorattribut einzubeziehen, fordern Sie es mit einem anProjectionExpression. Weitere Informationen finden Sie unter Verwenden ProjectionExpression.
SearchVector ist eine einfache Liste, kein DynamoDB L-Typ
Der SearchVector Anforderungsparameter ist ein einfaches JSON-Array von Zahlenobjekten ()[{"N": "0.1234"}, ...]. Binden Sie ihn nicht in einen L DynamoDB-Typ ein, wie Sie es beim Speichern eines Vektors in einem Elementattribut tun würden. Der L Wrapper wird nur verwendet, wenn Vektordaten in Elementattributen geschrieben oder gelesen werden.
Die Bedeutung von Score hängt von der Distanzfunktion ab, die Sie bei der Erstellung des Indexes ausgewählt haben. Bei COSINE und EUCLIDEAN deuten niedrigere Werte auf eine größere Ähnlichkeit hin. Denn DOT_PRODUCT höhere Punktzahlen bedeuten eine größere Ähnlichkeit.
Filtern mit SearchConditionExpression
Wird verwendetSearchConditionExpression, um Suchergebnisse auf der Grundlage des Vektorindex-Partitionsschlüssels und der in der definierten Inline-Filterattribute zu filtern SearchSchema. Dieser Ausdruck verwendet dieselbe Syntax wie andere DynamoDB-Ausdrucksparameter.
Im folgenden Beispiel wird mit einem Brand Inline-Filter nach Elementen in der Electronics Kategorie (Vektorindex-Partitionsschlüssel) gesucht.
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\"}}"
Wenn in Ihrem Vektorindex ein Partitionsschlüssel definiert ist SearchSchema, müssen Sie ihn in den aufnehmenSearchConditionExpression. Inline-Filterattribute sind optional.
Der Gleichheitsoperator (=) wird sowohl SearchConditionExpression für Vektorindex-Partitionsschlüssel als auch für Inline-Filterattribute unterstützt. Vergleichs-, Range- und Set-Mitgliedschaftsoperatoren (<><,,<=,>,>=,IN) sind noch nicht verfügbar.
Mit dieser Filterung können Sie eine Ähnlichkeitssuche auf eine Teilmenge Ihrer Daten ausdehnen. Dies ist eine häufige Anforderung in Anwendungen mit mehreren Mandanten und RAG-Anwendungen (Retrieval Augmented Generation). Um beispielsweise Dokumente zu finden, die einer Abfrage ähneln, aber nur innerhalb eines Mandanten enthalten sind, definieren Sie das Mandantenattribut als Vektorindex-Partitionsschlüssel (HASH) in der SearchSchema und übergeben Sie seinen Wert bei jeder Suche. Dadurch werden die Ergebnisse für diesen Mandanten isoliert. Es verbessert auch die Leistung, da bei der Suche nur die relevanten Daten untersucht werden. Verwenden Sie Inline-Filterattribute für zusätzliche Gleichheitsbeschränkungen, wie z. B. einen Dokumenttyp oder einen Status, die Sie innerhalb der gerouteten Partition anwenden möchten.
Die Festlegung des Gültigkeitsbereichs von Partitionsschlüsseln stellt keine Sicherheitsgrenze dar
Die Verwendung eines Partitionsschlüssels zur Beschränkung der Suche auf einen einzelnen Mandanten ist eine Optimierung der Datenlokalität und der Leistung, kein Mechanismus zur Zugriffskontrolle. Jeder Prinzipal, der die dynamodb:SearchVectors Berechtigung für den Index besitzt, kann nach jedem Partitionsschlüsselwert suchen. Da FGAC-Bedingungsschlüssel (Fine-Grained Access Control) wie z. B. dynamodb:LeadingKeys nicht gelten fürSearchVectors, können Sie den Zugriff auf einzelne Partitionsschlüsselwerte auf IAM-Richtlinienebene nicht einschränken. Wenn Ihre Arbeitslast eine strikte Mandantenisolierung auf der Datenebene erfordert, verwenden Sie separate Tabellen oder Indizes mit unterschiedlichen IAM-Zuweisungen für jeden Mandanten.
Verwenden ProjectionExpression
Wird verwendetProjectionExpression, um nur bestimmte Attribute in den Suchergebnissen zurückzugeben. Dadurch kann sich der Umfang der Antwortvariablen verringern, wenn Sie nicht alle projizierten Attribute benötigen. Da in diesem Beispiel ein Vektorindex-Partitionsschlüssel (Category) ProductEmbeddingIndex definiert ist SearchSchema, enthält dieses Beispiel immer noch den Wert des Vektorindex-Partitionsschlüssels inSearchConditionExpression.
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"
Nur projizierte Attribute können zurückgegeben werden
Sie können nur Attribute zurückgeben, die in den Vektorindex projiziert werden. Attribute, die nicht in der Indexprojektion enthalten sind, können von nicht zurückgegeben werdenSearchVectors.
Löschen eines Vektorindex
Verwenden Sie die UpdateTable API mit dem VectorIndexUpdates Parameter, um einen Vektorindex zu löschen.
aws dynamodb update-table \ --table-name Products \ --vector-index-updates \ "[ {\"Delete\": {\"IndexName\": \"ProductEmbeddingIndex\"}} ]"
Wenn Sie einen Vektorindex löschen, entfernt DynamoDB den Index und alle zugehörigen Daten. Dieser Vorgang wirkt sich nicht auf die Basistabelle oder ihre Elemente aus.
