Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# 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.
**Topics**
+ [Sebelum Anda mulai](#VectorSearchWorkingWith.Prerequisites)
+ [SearchVectors titik akhir](#VectorSearchWorkingWith.Endpoints)
+ [Menghasilkan penyematan vektor](#VectorSearchWorkingWith.Embeddings)
+ [Membuat indeks vektor](#VectorSearchWorkingWith.Create)
+ [Menulis item dengan data vektor](#VectorSearchWorkingWith.Write)
+ [Mencari dengan SearchVectors](#VectorSearchWorkingWith.Search)
+ [Menghapus indeks vektor](#VectorSearchWorkingWith.Delete)
## 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 adalah`arn:aws:dynamodb:{{region}}:{{account-id}}:table/{{table-name}}/index/{{index-name}}`.
## SearchVectors titik akhir
`SearchVectors`permintaan 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:
1. Kirim konten sumber Anda (misalnya, deskripsi produk) ke model penyematan dan terima vektor.
1. Simpan vektor itu dalam item DynamoDB, dalam atribut yang dinamai oleh indeks vektor (`VectorAttribute`), sebagai daftar (`L`) angka (`N`).
1. Pada waktu kueri, buat vektor dari teks pencarian menggunakan model yang sama, dan berikan sebagai`SearchVector`.
**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](VectorSearch.Requirements.md).
Fungsi jarak yang Anda pilih berinteraksi dengan bagaimana model Anda menghasilkan penyematan. `COSINE`membandingkan arah dan mengabaikan besaran, sehingga berfungsi dengan penyematan apakah mereka dinormalisasi atau tidak. `DOT_PRODUCT`sensitif 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](VectorSearch.md#VectorSearchWorkingWith.Ranking).
## 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 bernama`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\"
}
]"
```
Dalam contoh ini:
+ `VectorAttribute`menentukan `Embedding` sebagai atribut yang berisi data vektor.
+ `SearchSchema`mendefinisikan `Category` sebagai kunci partisi indeks vektor (`HASH`), yang mempartisi indeks berdasarkan kategori untuk penskalaan. Ini juga didefinisikan `Brand` sebagai`INLINE_FILTER`, yang memungkinkan Anda memfilter hasil pencarian berdasarkan merek di lapisan penyimpanan. Karena keduanya `Category` dan `Brand` direferensikan dalam SearchSchema, mereka juga harus dideklarasikan dalam`AttributeDefinitions`, dengan cara yang sama atribut kunci dideklarasikan untuk indeks sekunder global.
+ `Dimensions`diatur ke 1536, cocok dengan output model embedding umum.
+ `DistanceFunction`diatur ke`COSINE`, 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 terpisah`Backfilling`.
1. `IndexStatus`is `CREATING` — DynamoDB sedang menyiapkan infrastruktur indeks.
1. `IndexStatus`is `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.
1. `IndexStatus`is `ACTIVE` with `Backfilling` set to `false` (or absent) — Indeks terisi penuh dan siap untuk operasi pencarian.
**Anda tidak dapat mencari saat indeks diisi ulang**
`SearchVectors`mengembalikan 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`,, `UpdateItem``BatchWriteItem`,`TransactWriteItems`). Simpan penyematan vektor sebagai daftar angka (`L`tipe yang mengandung `N` elemen).
Karena vektor berisi banyak nilai, simpan item ke file seperti`item.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**
`Embedding`Vektor yang ditampilkan di sini disingkat. Di`item.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 dengan`UpdateItem`), 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](VectorSearchDataSync.md#VectorSearchDataSync.OngoingWrites).
### 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 seperti`query-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 a`ProjectionExpression`. Untuk informasi selengkapnya, lihat [Menggunakan ProjectionExpression](#VectorSearchWorkingWith.Search.Projection).
**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` dan`EUCLIDEAN`, skor yang lebih rendah menunjukkan kesamaan yang lebih besar. Untuk`DOT_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 dalam`SearchConditionExpression`. 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 untuk`SearchVectors`, 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 di`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"
```
**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 oleh`SearchVectors`.
## 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.