Sebelum Anda mulai SearchVectors titik akhir Menghasilkan penyematan vektor Membuat indeks vektor Menulis item dengan data vektor Mencari dengan SearchVectors Menghapus indeks vektor

Membuat dan mencari indeks vektor

Bagian ini menjelaskan cara membuat dan mengelola indeks vektor, menulis item dengan data vektor, dan melakukan pencarian kesamaan menggunakan SearchVectors API.

Sebelum Anda mulai

Sebelum Anda bekerja dengan indeks vektor, verifikasi yang berikut ini:

Tabel Anda menggunakan mode kapasitas sesuai permintaan (PAY_PER_REQUEST). Indeks vektor tidak didukung pada tabel kapasitas yang disediakan.
Identi AWS Identity and Access Management tas (IAM) Anda memiliki dynamodb:CreateTable atau dynamodb:UpdateTable izin untuk membuat indeks vektor.
Identitas IAM Anda memiliki dynamodb:SearchVectors izin pada sumber indeks vektor untuk melakukan pencarian. Format ARN sumber daya adalaharn:aws:dynamodb:region:account-id:table/table-name/index/index-name.

SearchVectors titik akhir

SearchVectorspermintaan menggunakan titik akhir pencarian vektor khusus, yang berbeda dari titik akhir DynamoDB standar yang Anda gunakan untuk membuat dan mengelola indeks vektor (misalnya, dengan,, dan). CreateTable UpdateTable DescribeTable AWS SDK dan SearchVectors permintaan AWS CLI rute ke titik akhir yang benar secara otomatis. Anda tidak perlu mengkonfigurasi atau mengganti titik akhir dalam kode aplikasi Anda.

Jika Anda membuat klien HTTP kustom yang memanggil DynamoDB API secara langsung tanpa AWS SDK, gunakan salah satu titik akhir pencarian vektor berikut, ganti dan sebagaimana mestinya: account-id region

account-id.search-ddb.region.amazonaws.com— Account-based titik akhir.
search-dynamodb.region.api.aws— Dual-stack titik akhir, kompatibel dengan IPv4 dan IPv6.

Menghasilkan penyematan vektor

DynamoDB menyimpan dan mencari penyematan vektor, tetapi tidak menghasilkannya. Anda menghasilkan penyematan dengan model embedding, seperti Amazon Bedrock Titan Text Embeddings atau model Cohere Embed, atau model embedding apa pun yang Anda operasikan. Anda kemudian menyimpan vektor yang dihasilkan dalam item DynamoDB dan meneruskan vektor kueri ke. SearchVectors

Vektor kueri dan vektor yang disimpan harus menggunakan model yang sama

Vektor kueri yang Anda SearchVectors lewati dan vektor yang disimpan dalam item Anda harus diproduksi oleh model penyematan yang sama dan harus memiliki jumlah dimensi yang sama dengan indeks vektor. Mencampur model, atau menanyakan dengan jumlah dimensi yang berbeda dari indeks yang dibuat, menghasilkan hasil yang tidak berarti atau kesalahan validasi.

Aliran tipikal adalah:

Kirim konten sumber Anda (misalnya, deskripsi produk) ke model penyematan dan terima vektor.
Simpan vektor itu dalam item DynamoDB, dalam atribut yang dinamai oleh indeks vektor (VectorAttribute), sebagai daftar (L) angka (N).
Pada waktu kueri, buat vektor dari teks pencarian menggunakan model yang sama, dan berikan sebagaiSearchVector.

Pilih model embedding Anda sebelum membuat indeks

Pilih model embedding Anda sebelum Anda membuat indeks vektor, karena model menentukan jumlah dimensi. Model embedding umum menghasilkan 384, 768, 1024, 1536, atau 3072 dimensi. DynamoDB mendukung hingga 4.096 dimensi. Lihat Persyaratan dan pembatasan.

Fungsi jarak yang Anda pilih berinteraksi dengan bagaimana model Anda menghasilkan penyematan. COSINEmembandingkan arah dan mengabaikan besaran, sehingga berfungsi dengan penyematan apakah mereka dinormalisasi atau tidak. DOT_PRODUCTsensitif terhadap besaran: jika penyematan Anda tidak dinormalisasi ke panjang satuan, vektor yang lebih besar menerima skor yang lebih tinggi terlepas dari arahnya. Jika Anda menggunakan DOT_PRODUCT dan menginginkan kesamaan berbasis arah, normalisasi penyematan Anda ke panjang satuan sebelum Anda menyimpannya. Lihat Bagaimana fungsi jarak memberi peringkat hasil.

Membuat indeks vektor

Anda dapat membuat indeks vektor saat Anda membuat tabel baru atau menambahkan satu ke tabel yang ada.

Membuat tabel dengan indeks vektor

Gunakan CreateTable API dengan VectorIndexes parameter untuk membuat tabel dengan indeks vektor. AWS CLI Contoh berikut membuat Products tabel dengan indeks vektor bernamaProductEmbeddingIndex.


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

Dalam contoh ini:

VectorAttributemenentukan Embedding sebagai atribut yang berisi data vektor.
SearchSchemamendefinisikan Category sebagai kunci partisi indeks vektor (HASH), yang mempartisi indeks berdasarkan kategori untuk penskalaan. Ini juga didefinisikan Brand sebagaiINLINE_FILTER, yang memungkinkan Anda memfilter hasil pencarian berdasarkan merek di lapisan penyimpanan. Karena keduanya Category dan Brand direferensikan dalam SearchSchema, mereka juga harus dideklarasikan dalamAttributeDefinitions, dengan cara yang sama atribut kunci dideklarasikan untuk indeks sekunder global.
Dimensionsdiatur ke 1536, cocok dengan output model embedding umum.
DistanceFunctiondiatur keCOSINE, di mana skor yang lebih rendah menunjukkan kesamaan yang lebih besar.

Menambahkan indeks vektor ke tabel yang ada

Gunakan UpdateTable API dengan VectorIndexUpdates parameter untuk menambahkan indeks vektor ke tabel yang ada. Contoh ini menambahkan indeks independen kedua yang diberi nama ProductEmbeddingIndexV2 ke Products tabel yang sama.


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

Saat Anda menambahkan indeks vektor ke tabel yang ada, DynamoDB melaporkan kemajuan indeks melalui dua bidang dalam DescribeTable respons: IndexStatus nilai dan boolean terpisahBackfilling.

IndexStatusis CREATING — DynamoDB sedang menyiapkan infrastruktur indeks.
IndexStatusis ACTIVE with Backfilling set to true — DynamoDB mengisi indeks dengan data yang ada dari tabel dasar. Tulisan baru ke tabel dasar juga direplikasi ke indeks selama fase ini. Sementara indeks vektor diisi ulang, SearchVectors mengembalikan kesalahan. Tunggu sampai Backfilling false sebelum Anda mencari.
IndexStatusis ACTIVE with Backfilling set to false (or absent) — Indeks terisi penuh dan siap untuk operasi pencarian.

Anda tidak dapat mencari saat indeks diisi ulang

SearchVectorsmengembalikan kesalahan saat indeks vektor diisi ulang. Gunakan DescribeTable untuk memeriksa bendera IndexStatus dan Backfilling bendera, dan tunggu sampai IndexStatus ada ACTIVE dan Backfilling ada false sebelum Anda mencari. Tidak ada nilai status BACKFILLING indeks.

Menulis item dengan data vektor

Anda menulis item dengan data vektor menggunakan API penulisan DynamoDB standar (PutItem,, UpdateItemBatchWriteItem,TransactWriteItems). Simpan penyematan vektor sebagai daftar angka (Ltipe yang mengandung N elemen).

Karena vektor berisi banyak nilai, simpan item ke file sepertiitem.json, lalu berikan file ke 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

Panjang vektor harus sesuai dengan dimensi indeks

EmbeddingVektor yang ditampilkan di sini disingkat. Diitem.json, itu harus berisi 1.536 nilai agar sesuai dengan yang Dimensions Anda tetapkan. ProductEmbeddingIndex Menulis vektor dengan jumlah dimensi yang salah ditolak.

DynamoDB memvalidasi data vektor saat Anda menulis item ke tabel yang memiliki indeks vektor. Tabel berikut menjelaskan perilaku validasi.

Kondisi	Perilaku
Atribut vektor memiliki jumlah dimensi yang salah	Menulis ditolak.
Atribut kunci partisi indeks vektor tidak ada	Menulis berhasil pada tabel dasar, tetapi item tidak direplikasi ke indeks vektor.
Jenis atribut kunci partisi indeks vektor tidak cocok dengan skema indeks	Menulis ditolak.
Atribut filter sebaris tidak ada	Tulis berhasil dan item direplikasi ke indeks vektor.
Nilai vektor memiliki presisi yang lebih tinggi dari 32-bit float point (f32)	Menulis berhasil. Nilai disimpan apa adanya di tabel dasar tetapi kehilangan presisi saat direplikasi ke indeks vektor.
Atribut vektor dihapus dari item	Entri yang sesuai dalam indeks vektor dihapus.

Kunci partisi yang hilang menyebabkan penghapusan indeks senyap

Jika indeks vektor Anda mendefinisikan kunci partisi di SearchSchema dan Anda menulis item tanpa atribut itu (atau menghapusnya denganUpdateItem), penulisan berhasil pada tabel dasar tetapi item diam-diam dikecualikan dari indeks vektor. Itu tidak akan muncul dalam SearchVectors hasil meskipun item tabel dasar dan penyematan vektornya masih ada. Pastikan bahwa setiap item yang Anda inginkan dapat dicari berisi atribut kunci partisi indeks vektor.

Penyematan basi menghasilkan hasil yang salah

DynamoDB tidak menghitung ulang penyematan untuk Anda. Jika Anda mengubah konten sumber yang menghasilkan penyematan (misalnya, Anda mengedit deskripsi produk), vektor yang disimpan tidak diperbarui secara otomatis. Anda harus membuat ulang penyematan dengan model embedding Anda dan menulis vektor baru kembali ke item. Jika tidak, indeks vektor terus mengembalikan hasil berdasarkan vektor lama yang basi, yang secara diam-diam dapat menghasilkan kecocokan yang salah.

Mencari dengan SearchVectors

Gunakan SearchVectors API untuk menemukan item dalam indeks vektor yang paling mirip dengan vektor kueri. Hasil diurutkan berdasarkan relevansi, dengan item yang paling mirip terlebih dahulu. Hasil pencarian akhirnya konsisten: mungkin ada penundaan singkat antara menulis atau memperbarui vektor dan muncul di hasil pencarian. Untuk informasi selengkapnya, lihat Sinkronisasi tulis yang sedang berlangsung.

Pencarian dasar

Contoh berikut mencari 10 item yang paling mirip dalam ProductEmbeddingIndex indeks. Karena indeks ini memiliki kunci partisi indeks vektor (Category) yang ditentukan di dalamnya SearchSchema, SearchConditionExpression harus menyertakan nilai kunci partisi indeks vektor.

Simpan vektor kueri ke file sepertiquery-vector.json, sebagai array JSON biasa dari nilai angka.


[
    { "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\"}}"

Responsnya termasuk SearchResults array. Setiap elemen berisi pencoco Item kan dan a Score yang menunjukkan seberapa mirip item dengan vektor kueri.


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

Atribut vektor dikecualikan dari hasil secara default

Secara default, hasil dari SearchVectors tidak menyertakan atribut vektor (penyematan). Data vektor besar, dan Anda biasanya tidak membutuhkannya dalam respons. Hasilnya termasuk atribut proyeksi lainnya dan nil Score ainya. Untuk menyertakan atribut vektor, minta dengan aProjectionExpression. Untuk informasi selengkapnya, lihat Menggunakan ProjectionExpression.

SearchVector adalah daftar biasa, bukan tipe DynamoDB L

Parameter SearchVector permintaan adalah array JSON polos dari number object ([{"N": "0.1234"}, ...]). Jangan membungkusnya dalam L tipe DynamoDB seperti yang Anda lakukan saat menyimpan vektor dalam atribut item. Pem L bungkus hanya digunakan saat menulis atau membaca data vektor dalam atribut item.

Arti Score tergantung pada fungsi jarak yang Anda pilih saat Anda membuat indeks. Untuk COSINE danEUCLIDEAN, skor yang lebih rendah menunjukkan kesamaan yang lebih besar. UntukDOT_PRODUCT, skor yang lebih tinggi menunjukkan kesamaan yang lebih besar.

Penyaringan dengan SearchConditionExpression

Gunakan SearchConditionExpression untuk memfilter hasil pencarian berdasarkan kunci partisi indeks vektor dan atribut filter sebaris yang ditentukan dalam SearchSchema. Ekspresi ini menggunakan sintaks yang sama dengan parameter ekspresi DynamoDB lainnya.

Contoh berikut mencari item dalam Electronics kategori (kunci partisi indeks vektor) dengan filter Brand sebaris.


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

Jika indeks vektor Anda memiliki kunci partisi yang ditentukan di SearchSchema, Anda harus memasukkannya ke dalamSearchConditionExpression. Atribut filter sebaris bersifat opsional.

Operator kesetaraan (=) didukung SearchConditionExpression untuk kunci partisi indeks vektor dan atribut filter sebaris. Operator perbandingan, jangkauan, dan set-keanggotaan (<><<=>,>=,,,,IN) belum tersedia.

Pemfilteran ini adalah cara Anda menjangkau pencarian kesamaan ke subset data Anda, persyaratan umum dalam aplikasi multi-tenant dan Retrieval Augmented Generation (RAG). Misalnya, untuk menemukan dokumen yang mirip dengan kueri tetapi hanya dalam satu penyewa, tentukan atribut tenant sebagai kunci partisi indeks vektor (HASH) di SearchSchema dan berikan nilainya di setiap pencarian. Ini mengisolasi hasil ke penyewa itu. Ini juga meningkatkan kinerja, karena pencarian hanya memeriksa data yang relevan. Gunakan atribut filter sebaris untuk batasan kesetaraan tambahan, seperti jenis dokumen atau status, yang ingin Anda terapkan dalam partisi yang dirutekan.

Pelingkupan kunci partisi bukan batas keamanan

Menggunakan kunci partisi untuk menjangkau pencarian ke penyewa tunggal adalah pengoptimalan data dan kinerja, bukan mekanisme kontrol akses. Setiap prinsipal yang memegang dynamodb:SearchVectors izin pada indeks dapat mencari nilai kunci partisi apa pun. Karena kunci kondisi kontrol akses halus (FGAC) seperti tidak berlaku untukSearchVectors, Anda dynamodb:LeadingKeys tidak dapat membatasi akses ke nilai kunci partisi individual di tingkat kebijakan IAM. Jika beban kerja Anda memerlukan isolasi penyewa yang ketat di lapisan data, gunakan tabel atau indeks terpisah dengan hibah IAM yang berbeda untuk setiap penyewa.

Menggunakan ProjectionExpression

Gunakan ProjectionExpression untuk mengembalikan hanya atribut tertentu dalam hasil pencarian. Ini dapat mengurangi ukuran respons ketika Anda tidak memerlukan semua atribut yang diproyeksikan. Karena ProductEmbeddingIndex mendefinisikan kunci partisi indeks vektor (Category) di dalamnya SearchSchema, contoh ini masih menyertakan nilai kunci partisi indeks vektor diSearchConditionExpression.


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"

Hanya atribut yang diproyeksikan yang dapat dikembalikan

Anda hanya dapat mengembalikan atribut yang diproyeksikan ke indeks vektor. Atribut yang tidak ada dalam proyeksi indeks tidak dapat dikembalikan olehSearchVectors.

Menghapus indeks vektor

Gunakan UpdateTable API dengan VectorIndexUpdates parameter untuk menghapus indeks vektor.


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

Ketika Anda menghapus indeks vektor, DynamoDB menghapus indeks dan semua datanya. Operasi ini tidak mempengaruhi tabel dasar atau itemnya.

Awas Javascript dinonaktifkan atau tidak tersedia di browser Anda.

Untuk menggunakan Dokumentasi AWS, Javascript harus diaktifkan. Lihat halaman Bantuan browser Anda untuk petunjuk.

Konvensi Dokumen

Bekerja dengan indeks vektor

Persyaratan dan pembatasan