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` **Topics** + [Bevor Sie beginnen](#VectorSearchWorkingWith.Prerequisites) + [SearchVectors Endpunkte](#VectorSearchWorkingWith.Endpoints) + [Generieren von Vektor-Einbettungen](#VectorSearchWorkingWith.Embeddings) + [Einen Vektorindex erstellen](#VectorSearchWorkingWith.Create) + [Elemente mit Vektordaten schreiben](#VectorSearchWorkingWith.Write) + [Suchen mit SearchVectors](#VectorSearchWorkingWith.Search) + [Löschen eines Vektorindex](#VectorSearchWorkingWith.Delete) ## 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 unsere `dynamodb:UpdateTable` Berechtigungen zum Erstellen von Vektorindizes. + Ihre IAM-Identität ist für die Vektorindexressource `dynamodb:SearchVectors` berechtigt, Suchvorgänge durchzuführen. Das ARN-Format der Ressource lautet`arn:aws:dynamodb:{{region}}:{{account-id}}:table/{{table-name}}/index/{{index-name}}`. ## SearchVectors Endpunkte `SearchVectors`Anfragen 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`— Account-based Endpunkt. + `search-dynamodb.{{region}}.api.aws`— Dual-stack Endpunkt, kompatibel mit IPv4 und IPv6. ## 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: 1. Senden Sie Ihren Quellinhalt (z. B. eine Produktbeschreibung) an ein Einbettungsmodell und erhalten Sie einen Vektor. 1. Speichern Sie diesen Vektor in einem DynamoDB-Element in dem vom Vektorindex (`VectorAttribute`) benannten Attribut als Liste (`L`) von Zahlen (). `N` 1. 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](VectorSearch.Requirements.md). Die von Ihnen gewählte Abstandsfunktion wirkt sich darauf aus, wie Ihr Modell Einbettungen erzeugt. `COSINE`vergleicht die Richtung und ignoriert die Größe. Sie funktioniert also mit Einbettungen, unabhängig davon, ob sie normalisiert sind oder nicht. `DOT_PRODUCT`reagiert 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](VectorSearch.md#VectorSearchWorkingWith.Ranking). ## 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 erstellt`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 diesem Beispiel: + `VectorAttribute`gibt `Embedding` als das Attribut an, das Vektordaten enthält. + `SearchSchema`definiert `Category` als Vektorindex einen Partitionsschlüssel (`HASH`), der den Index zur Skalierung nach Kategorien partitioniert. Es definiert sich auch `Brand` als ein`INLINE_FILTER`, mit dem Sie Suchergebnisse auf der Speicherebene nach Marke filtern können. Da auf `Brand` beide `Category` und in der verwiesen wird SearchSchema, müssen sie auch in deklariert werden`AttributeDefinitions`, genauso wie Schlüsselattribute für einen globalen sekundären Index deklariert werden. + `Dimensions`ist auf 1536 gesetzt, was der Ausgabe gängiger Einbettungsmodelle entspricht. + `DistanceFunction`ist auf gesetzt`COSINE`, 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. 1. `IndexStatus`ist `CREATING` — DynamoDB richtet die Indexinfrastruktur ein. 1. `IndexStatus`ist `ACTIVE` mit `Backfilling` gesetzt auf `true` — 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 Fehler `SearchVectors` zurückgegeben. Warten Sie, bis `Backfilling` es soweit ist`false`, bevor Sie suchen. 1. `IndexStatus`ist `ACTIVE` auf `Backfilling` gesetzt `false` (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** `SearchVectors`gibt einen Fehler zurück, während ein Vektorindex aufgefüllt wird. Verwenden Sie diese Option`DescribeTable`, 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`,, `UpdateItem``BatchWriteItem`,`TransactWriteItems`). Speichern Sie die Vektoreinbettung als Liste von Zahlen (`L`Typ, der Elemente enthält`N`). Da ein Vektor viele Werte enthält, speichern Sie das Element in einer Datei wie`item.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. In`item.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 entfernen`UpdateItem`), 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](VectorSearchDataSync.md#VectorSearchDataSync.OngoingWrites). ### 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 Datei`query-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 ein`Score`, 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 an`ProjectionExpression`. Weitere Informationen finden Sie unter [Verwenden ProjectionExpression](#VectorSearchWorkingWith.Search.Projection). **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 verwendet`SearchConditionExpression`, 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 aufnehmen`SearchConditionExpression`. 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ür`SearchVectors`, 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 verwendet`ProjectionExpression`, 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 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" ``` **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 werden`SearchVectors`. ## 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.