:Panduan penggunaan

Prasyarat

• Anda telah mengaktifkan layanan Alibaba Cloud Elasticsearch dan telah membuat atau berencana membuat instans AI Engine Edition.

• Anda telah merencanakan VPC, vSwitch, daftar putih alamat IP, dan jaringan klien untuk instans tersebut.

• Anda telah merancang pemetaan berdasarkan data bisnis Anda. Untuk skenario pencarian vektor, Anda juga perlu menentukan model vektor, dimensi, metrik kemiripan, dan metode pembaruan.

• Akun Anda memiliki izin yang diperlukan. Manajemen Collection biasanya memerlukan manage, membaca data memerlukan read, dan menulis data memerlukan write. Untuk informasi lebih lanjut, lihat Izin Collection.

Buat instans

Item pembelian dan tata letak halaman dapat berubah berdasarkan wilayah, versi, dan fase produk. Langkah-langkah berikut didasarkan pada halaman Konsol aktual. Wilayah dan zona yang didukung oleh AI Engine Edition didasarkan pada item yang dapat dibeli di halaman pembelian.

1. Login ke Konsol Alibaba Cloud Elasticsearch dan buka halaman pembuatan instans.

2. Pilih AI Engine Edition dan pilih wilayah serta zona yang disediakan oleh Konsol. Versi Elasticsearch untuk tipe instans ini bersifat tetap. Halaman pembuatan menampilkan versi 9.x, yang tidak dapat diubah. Setelah instans dibuat, Anda dapat melihat nomor versi spesifik di halaman daftar instans atau detail instans.

3. Konfigurasikan node indeks berdasarkan beban kerja tulis dan konfigurasikan node pencarian berdasarkan beban kerja kueri. Komponen opsional lainnya didasarkan pada Konsol.

4. Konfigurasikan VPC, vSwitch, username, dan password. Daftar putih alamat IP tidak dikonfigurasi di halaman pembuatan. Anda mengonfigurasinya di halaman konfigurasi keamanan instans setelah instans dibuat.

5. Konfirmasi konfigurasi dan biaya, lalu buat instans. Setelah status instans berubah menjadi Available, catat alamat akses Elasticsearch dan Kibana.

   Spesifikasi node, jumlah minimum node, dan konfigurasi node master khusus didasarkan pada item yang dapat dibeli saat ini di halaman pembelian.

Jumlah dan spesifikasi node harus ditentukan berdasarkan throughput tulis, konkurensi kueri, konstruksi indeks vektor, set data aktif, dan kebutuhan cache. Operasi spesifik untuk menyesuaikan node dan aturan penagihan didasarkan pada Konsol.

Hubungkan ke instans

Anda dapat menggunakan Kibana Dev Tools, klien yang kompatibel dengan Elasticsearch, atau klien HTTP apa pun untuk mengakses instans. Alamat instans, daftar putih jaringan, sertifikat, dan metode autentikasi didasarkan pada halaman detail instans.

Nama domain akses AI Engine Edition bervariasi berdasarkan jenis jaringan. Nama domain hanya menentukan role node mana yang awalnya menerima permintaan dan tidak membatasi jenis permintaan. Kluster meneruskan permintaan ke role node yang benar-benar menanganinya.

Saat mengakses instans melalui private network, kedua nama domain mendukung operasi baca dan tulis. Untuk akses produksi, gunakan nama domain private network default untuk permintaan kueri dan nama domain private network node indeks untuk permintaan tulis guna mengurangi konsumsi bandwidth jaringan pada node pencarian. Ini sangat penting untuk tulis Bulk, kueri yang mengembalikan hasil besar, atau skenario konkurensi tinggi. Saat mengakses instans melalui public network, gunakan nama domain public network default untuk permintaan baca dan tulis.

Sebagai contoh, jika ID instans adalah es-cn-xxx, nama domain private network node indeks adalah es-cn-xxx-index.elasticsearch.aliyuncs.com. Protokol, port, dan metode akses jaringan didasarkan pada informasi yang ditampilkan di Konsol.

Instans menggunakan HTTP secara default. Jika Anda mengaktifkan HTTPS di Konsol, ubah protokol koneksi klien ke HTTPS.

Jalankan permintaan berikut di Kibana Dev Tools untuk memverifikasi koneksi:

GET /

AI Engine Edition 9.99.0 sesuai dengan versi kernel Elasticsearch 9.5.0. Oleh karena itu, version.number yang dikembalikan oleh permintaan ini adalah nomor versi kernel, yang berbeda dari 9.99.0 yang ditampilkan di Konsol. Versi Elasticsearch aktual didasarkan pada respons API kluster. Saat menginstal plugin kustom, gunakan nomor versi 9.99.0 yang sesuai dengan AI Engine Edition.

Saat menggunakan cURL, ganti alamat instans dan kredensial. Untuk penggunaan produksi, jangan menyimpan password dalam teks biasa di skrip atau riwayat perintah:

curl --user '{username}:{password}' 'http://{elasticsearch-endpoint}/'

Saat menggunakan klien resmi, pilih versi klien berdasarkan dokumentasi kompatibilitas API untuk versi instans Anda, dan gunakan kembali kolam koneksi klien. Jangan membuat klien baru untuk setiap permintaan.

Konvensi akses

• Aplikasi selalu mengakses data melalui nama Collection atau Alias Collection.

• Dalam mode namespace, tulis dan kueri menentukan namespace melalui _slice. Kueri yang tidak menyediakan _slice gagal. Untuk mengkueri semua Slice, gunakan secara eksplisit _slice=_all. Beberapa API dokumen dan kueri juga mendukung routing sebagai alternatif. Untuk informasi lebih lanjut tentang cakupan yang didukung, lihat Parameter kompatibilitas routing.

• Dalam mode recall klaster vektor, tulis menentukan klaster vektor melalui _slice atau routing_field. Kueri KNN dapat secara otomatis memilih beberapa Slice kandidat berdasarkan vektor kueri. Kueri yang tidak dapat secara otomatis memilih Slice kandidat tetap memerlukan _slice eksplisit, atau routing dalam API yang kompatibel.

• Slice digunakan untuk mengatur data dan membatasi cakupan kueri. Slice bukan batas izin akun. Untuk mengisolasi izin penyewa, kombinasikan autentikasi tingkat aplikasi dengan mekanisme keamanan yang didukung produk.

• Jangan menyimpan atau mengakses langsung indeks pendukung (Backing Index) .sc-*. Nama dan siklus hidupnya dikelola oleh sistem. Beberapa respons API (seperti _index dalam respons tulis dan backing_index dalam respons pendaftaran Slice) mengembalikan nama-nama ini hanya untuk pengamatan dan troubleshooting. Nama-nama tersebut tidak boleh digunakan sebagai target untuk permintaan aplikasi selanjutnya. Saat mengonfigurasi izin role, gunakan pola wildcard .sc-<collection>-*. Untuk informasi lebih lanjut, lihat Izin Collection.

Parameter kompatibilitas routing

Saat menggunakan API baca/tulis dokumen dan kueri yang tercantum dalam panduan ini pada Collection atau Alias Collection, Anda dapat menggunakan parameter standar Elasticsearch routing sebagai pengganti _slice. Ini untuk kompatibilitas dengan klien yang ada. Untuk aplikasi baru, gunakan _slice yang lebih eksplisit secara semantik. URL yang sama atau item Bulk atau MGet yang sama tidak dapat menentukan kedua parameter secara bersamaan.

Kompatibilitas ini tidak berlaku untuk manajemen Collection dan Slice, cache warming, Copy Slice, CAT, Refresh eksplisit, atau Reindex. Reindex harus menggunakan source._slice dan dest._slice. routing_field adalah konfigurasi untuk menurunkan Slice dari bidang dokumen, bukan alias untuk routing.

Konvensi API umum

• Permintaan JSON menggunakan Content-Type: application/json. Bulk dan Multi Search menggunakan Content-Type: application/x-ndjson dan memerlukan baris baru di akhir badan permintaan.

• API Bulk, Multi Search, dan manajemen batch dapat mengalami kegagalan tingkat item. Aplikasi tidak hanya harus memeriksa kode status HTTP. API pendaftaran Slice tunggal dan batch juga menggunakan error tingkat item: permintaan keseluruhan mengembalikan HTTP 200, tetapi field errors tingkat atas mungkin true. Periksa setiap items[].result secara individual.

• HTTP 429 menunjukkan bahwa server saat ini menolak permintaan. Klien harus menggunakan backoff eksponensial dengan batas atas dan hanya mencoba ulang operasi yang cocok untuk dicoba ulang.

• Timeout koneksi atau HTTP 5xx tidak berarti tulis pasti tidak terjadi. Verifikasi dengan ID dokumen stabil atau mekanisme idempoten lainnya sebelum mencoba ulang.

• Saat meneruskan sejumlah besar nilai _slice melalui URL, perhatikan bahwa panjang maksimum baris permintaan HTTP adalah 4096 byte. Saat nama Slice panjang, too_long_http_line_exception mungkin dipicu sebelum mencapai batas jumlah Slice.

  API manajemen Collection umumnya menggunakan parameter kueri berikut. Cakupan yang didukung spesifik didasarkan pada deskripsi setiap API.

Permintaan manajemen yang mengembalikan acknowledged=false atau timeout tidak berarti operasi sisi server telah dikembalikan. Periksa status resource saat ini sebelum mencoba ulang.

Perbandingan mode

Collection menyediakan mode namespace dan mode recall klaster vektor. Anda harus memilih salah satu dari dua mode tersebut. Mode ditentukan oleh parameter pembuatan slice_strategy dan tidak dapat diubah setelah pembuatan. Mode ini memengaruhi makna bisnis Slice, metode pendaftaran, serta routing tulis dan kueri.

Mode recall klaster vektor secara otomatis memilih beberapa Slice kandidat berdasarkan centroid klaster vektor dan mengirim kueri ke Slice-Slice tersebut secara paralel. Ini tidak berarti Anda harus menggunakan mode ini untuk menyimpan vektor. Mode namespace juga mendukung dense_vector, KNN, dan DiskBBQ. Pilih mode recall klaster vektor hanya ketika bisnis Anda perlu secara otomatis meng-recall klaster vektor relevan dan Anda telah menyelesaikan pemeliharaan centroid klaster serta evaluasi tingkat recall.

Panduan pengambilan keputusan

Gunakan panduan berikut untuk memilih antara kedua mode:

• Rekomendasi default — Pilih mode namespace (exact) ketika aplikasi dapat menentukan cakupan kueri dari pengenal bisnis (ID penyewa, ID basis pengetahuan, ID repositori kode) sebelum kueri.

• Pilih mode recall klaster vektor hanya ketika semua kondisi berikut terpenuhi:

  • Bisnis Anda dapat menghasilkan dan terus-menerus memelihara centroid klaster secara offline.

  • Volume data dan jumlah Slice cukup besar sehingga mempersempit cakupan kueri memberikan manfaat nyata.

  • Bisnis Anda memungkinkan pemilihan klaster kandidat sebelum menjalankan kueri KNN, dan Anda telah menentukan jumlah Slice kandidat yang sesuai melalui pengujian tingkat recall.

• Jangan gunakan mode recall klaster vektor ketika:

  • Data tidak memiliki struktur pengelompokan yang stabil, dan vektor centroid yang andal tidak dapat disediakan.

  • Volume data atau jumlah Slice kecil, dan biaya kueri langsung sudah dapat diterima.

  • Kueri harus mencakup semua data vektor, dan perubahan cakupan recall yang diperkenalkan oleh pemilihan klaster kandidat tidak dapat diterima. Dalam kasus ini, gunakan mode namespace dan tentukan secara eksplisit cakupan kueri _slice.

  Setelah memilih mode namespace, lihat Mode namespace: Pencarian vektor DiskBBQ berdasarkan Slice. Setelah memilih mode recall klaster vektor, lihat Mode recall klaster vektor: Pemilihan Slice kandidat otomatis. Kemampuan manajemen Collection, API data, cache warming, Alias, Copy Slice, dan pemantauan lainnya dalam panduan ini berlaku untuk kedua mode kecuali dinyatakan lain.

Replica kueri dan ketersediaan tinggi

Kueri dalam kedua mode dilayani oleh shard replika pada node pencarian. index.number_of_replicas harus diatur minimal 1. Jika tidak, kueri tidak dapat dilayani. Mengaturnya ke 1 hanya memenuhi persyaratan dasar kueri dan tidak memberikan ketersediaan tinggi kueri. Untuk produksi, atur minimal 2 dan konfigurasikan minimal dua node pencarian sehingga kueri dapat terus dilayani ketika satu node pencarian gagal.

Mode namespace: Pencarian vektor DiskBBQ berdasarkan Slice

Platform basis pengetahuan perusahaan menyediakan layanan Generasi yang Diperkaya dengan Pengambilan Data (RAG) untuk beberapa penyewa. Setelah aplikasi menyelesaikan autentikasi penyewa, aplikasi dapat menentukan ID penyewa saat ini. Ketika pengguna mengajukan pertanyaan, aplikasi hanya perlu meng-recall segmen konten yang relevan secara semantik dari basis pengetahuan penyewa tersebut.

Skenario ini dapat menentukan cakupan kueri sebelum mengirim permintaan, sehingga cocok untuk mode namespace. Contoh ini membuat Collection bernama knowledge-chunks dan menggunakan setiap penyewa sebagai Slice. Aplikasi menentukan basis pengetahuan penyewa melalui _slice dan kemudian menggunakan DiskBBQ untuk melakukan KNN dalam Slice yang dipilih. Slice digunakan untuk mengatur data dan membatasi cakupan kueri. Autentikasi penyewa tetap ditangani oleh aplikasi atau mekanisme keamanan Elasticsearch yang didukung.

PUT /_slice_collection/knowledge-chunks
{
  "settings": {
    "index.number_of_shards": 2,
    "index.number_of_replicas": 2
  },
  "mappings": {
    "properties": {
      "tenant_id": { "type": "keyword" },
      "document_id": { "type": "keyword" },
      "title": { "type": "text" },
      "content": { "type": "text" },
      "category": { "type": "keyword" },
      "updated_at": { "type": "date" },
      "embedding": {
        "type": "dense_vector",
        "dims": 4,
        "index": true,
        "similarity": "cosine",
        "index_options": {
          "type": "bbq_disk"
        }
      }
    }
  }
}

{
  "acknowledged": true
}

PUT /knowledge-chunks/_doc/chunk-1001?_slice=tenant-a
{
  "tenant_id": "tenant-a",
  "document_id": "doc-refund-policy",
  "title": "Refund and return policy",
  "content": "You can request a refund for duplicate purchases within seven days after the order is completed.",
  "category": "after-sales",
  "updated_at": "2026-07-30T10:00:00Z",
  "embedding": [0.82, 0.10, 0.05, 0.03]
}

PUT /knowledge-chunks/_doc/chunk-1002?_slice=tenant-b
{
  "tenant_id": "tenant-b",
  "document_id": "doc-shipping-status",
  "title": "Check shipping status",
  "content": "Open the logistics information on the order details page to view the latest delivery status.",
  "category": "shipping",
  "updated_at": "2026-07-30T10:01:00Z",
  "embedding": [0.12, 0.78, 0.06, 0.04]
}

GET /knowledge-chunks/_doc/chunk-1001?_slice=tenant-a

POST /knowledge-chunks/_search?_slice=tenant-a
{
  "knn": {
    "field": "embedding",
    "query_vector": [0.80, 0.12, 0.05, 0.03],
    "k": 10,
    "num_candidates": 100
  },
  "_source": ["document_id", "title", "content"]
}

POST /_bulk
{ "index": { "_index": "knowledge-chunks", "_id": "chunk-1003", "_slice": "tenant-a" } }
{ "tenant_id": "tenant-a", "document_id": "doc-change-address", "title": "Change delivery address", "content": "Before an order is shipped, you can change the delivery address on the order details page.", "category": "orders", "updated_at": "2026-07-30T10:02:00Z", "embedding": [0.75, 0.16, 0.06, 0.03] }
{ "index": { "_index": "knowledge-chunks", "_id": "chunk-1004", "_slice": "tenant-b" } }
{ "tenant_id": "tenant-b", "document_id": "doc-invoice", "title": "Request an electronic invoice", "content": "After an order is completed, you can request an electronic invoice on the invoice management page.", "category": "billing", "updated_at": "2026-07-30T10:03:00Z", "embedding": [0.18, 0.70, 0.08, 0.04] }

GET /_cat/slice_collection/knowledge-chunks?v

GET /_cat/slice_collection/knowledge-chunks/slices?v

GET /_slice_collection/knowledge-chunks/slices?page_size=100

{
  "slices": [
    { "id": "tenant-a" },
    { "id": "tenant-b" }
  ]
}

GET /_slice_collection/knowledge-chunks/slices?page_size=100&cursor={next_cursor}

Mode recall klaster vektor: Pemilihan Slice kandidat otomatis

Platform pencarian e-commerce memelihara database vektor produk berskala besar dan telah membagi produk menjadi ribuan klaster vektor melalui pengelompokan offline. Saat pengguna memulai kueri produk serupa, aplikasi hanya memiliki vektor kueri dan tidak dapat menentukan klaster target sebelumnya. Mengkueri semua data produk setiap kali meningkatkan cakupan kueri dan overhead resource seiring pertumbuhan skala data.

Skenario ini cocok untuk mode recall klaster vektor: setiap Slice sesuai dengan klaster vektor, dan vektor centroid klaster tersebut didaftarkan. Saat kueri KNN dieksekusi, sistem pertama-tama menghitung kemiripan antara vektor kueri dan setiap centroid klaster, secara otomatis memilih Slice kandidat yang paling relevan, lalu melakukan pencarian DiskBBQ secara paralel dalam Slice-Slice tersebut, sehingga mempersempit cakupan kueri.

Collection tidak melatih centroid klaster, juga tidak secara otomatis menentukan Slice target berdasarkan vektor dokumen. Aplikasi harus menghitung dan mendaftarkan vektor centroid terlebih dahulu.

Untuk kapan menggunakan dan kapan menghindari mode ini, lihat Panduan pengambilan keputusan.

PUT /_slice_collection/products
{
  "slice_strategy": "vector_cluster",
  "auto_create_slice": false,
  "settings": {
    "index.number_of_shards": 2,
    "index.number_of_replicas": 2
  },
  "mappings": {
    "properties": {
      "cluster_id": { "type": "keyword" },
      "name": { "type": "keyword" },
      "embedding": {
        "type": "dense_vector",
        "dims": 2,
        "index": true,
        "similarity": "cosine",
        "index_options": {
          "type": "bbq_disk"
        }
      }
    }
  },
  "config": {
    "routing_field": "cluster_id",
    "vector_dims": 2,
    "default_query_vector_path": "knn.query_vector",
    "default_query_slice_count": 128,
    "max_query_slice_count": 512
  }
}

PUT /_slice_collection/products/slices/cluster-a
{
  "vector": [0.9, 0.1]
}

PUT /_slice_collection/products/slices
{
  "slices": [
    {
      "slice_id": "cluster-b",
      "vector": [0.1, 0.9]
    },
    {
      "slice_id": "cluster-c",
      "vector": [0.6, 0.4]
    }
  ]
}

PUT /products/_doc/product-1
{
  "cluster_id": "cluster-a",
  "name": "example-product",
  "embedding": [0.92, 0.08]
}

POST /products/_search?query_slice_count=64
{
  "knn": {
    "field": "embedding",
    "query_vector": [0.91, 0.09],
    "k": 10,
    "num_candidates": 100
  }
}

Parameter pembuatan

API untuk membuat Collection adalah:

PUT /_slice_collection/{collection}

Parameter kueri:

Parameter badan permintaan adalah sebagai berikut.

Jika Indeks Pendukung memiliki N shard utama, jumlah maksimum Slice yang dapat diterima berdasarkan batas hitungan saja adalah N × max_slices_per_shard. max_slices_per_shard dan max_storage_per_shard hanya menentukan apakah Slice baru berikutnya terus dialokasikan ke Pendukung ini:

• Setelah salah satu ambang batas tercapai, sistem memilih atau membuat Pendukung lain untuk menampung Slice baru.

• Slice yang ada dapat terus menerima tulisan.

• Mengubah ambang batas tidak memigrasi Slice yang ada atau menyeimbangkan ulang data yang ada.

  Dalam sebagian besar skenario, default last sudah cukup. Gunakan random hanya ketika beberapa Pendukung dapat menerima Slice baru secara bersamaan dan Anda ingin mendistribusikan Slice yang baru didaftarkan secara acak.

Lihat Collection

Lihat Collection tunggal:

GET /_slice_collection/knowledge-chunks

Lihat semua Collection:

GET /_slice_collection

API ini mendukung parameter kueri master_timeout.

{collection} mendukung nama yang dipisahkan koma dan wildcard. Nama eksak yang tidak ada mengembalikan HTTP 404. Wildcard tanpa kecocokan mengembalikan objek kosong.

Contoh respons:

{
  "slice_collections": {
    "knowledge-chunks": {
      "collection_uuid": "opaque-system-id",
      "lifecycle_state": "active",
      "max_slices_per_shard": 200,
      "max_storage_per_shard": "50gb",
      "backing_allocation_strategy": "last",
      "future_only_settings": {},
      "auto_create_slice": true,
      "slice_strategy": "exact",
      "max_managed_backing_generation": 0,
      "aliases": {}
    }
  }
}

Respons mungkin juga berisi pengenal yang dikelola sistem dan field generation. Aplikasi harus memperlakukannya sebagai informasi opak dan tidak menggunakannya untuk membangun nama Pendukung atau mengimplementasikan logika bisnis.

Perbarui Collection

API ini digunakan untuk menyesuaikan strategi alokasi untuk Slice yang didaftarkan selanjutnya dan tidak memindahkan Slice yang ada.

Perbarui konfigurasi yang dapat diubah:

POST /_slice_collection/knowledge-chunks/_update
{
  "max_slices_per_shard": 300,
  "max_storage_per_shard": "80gb",
  "backing_allocation_strategy": "last",
  "auto_create_slice": false,
  "settings": {
    "apack.slice_collection.future.index.number_of_shards": 4
  }
}

Parameter kueri:

Field yang dapat diperbarui meliputi:

• max_slices_per_shard

• max_storage_per_shard

• backing_allocation_strategy

• auto_create_slice

• Pengaturan future-only yang diizinkan dalam settings

  Pengaturan future-only hanya memengaruhi Pendukung yang dibuat setelahnya dan tidak memodifikasi Pendukung yang ada. Pengaturan yang diizinkan secara default adalah:

• index.number_of_shards

• index.routing_partition_size

• index.number_of_routing_shards

  Dalam permintaan _update, pengaturan future-only harus menggunakan awalan apack.slice_collection.future.. Misalnya, index.number_of_shards sesuai dengan apack.slice_collection.future.index.number_of_shards. Saat menulis, awalan datar digunakan. Saat membaca kembali melalui GET /_slice_collection/{collection}, pengaturan disajikan dalam struktur bersarang, misalnya, "future_only_settings": {"index": {"number_of_shards": "4"}}.

Respons yang berhasil adalah {"acknowledged":true}. acknowledged=false menunjukkan bahwa konfirmasi timeout, bukan pembaruan telah dikembalikan.

Perbarui pemetaan dan pengaturan dinamis

Perbarui pemetaan dengan menggunakan nama Collection:

PUT /knowledge-chunks/_mapping
{
  "properties": {
    "channel": { "type": "keyword" }
  }
}

Perbarui pengaturan indeks dinamis dengan menggunakan nama Collection:

PUT /knowledge-chunks/_settings
{
  "index.refresh_interval": "5s"
}

Pemetaan dan pengaturan indeks dinamis diterapkan ke semua Pendukung saat ini dan menjadi konfigurasi seragam untuk Pendukung berikutnya. Jangan memodifikasi Indeks Pendukung individual.

Daftarkan Slice

Saat memilih metode pendaftaran Slice, lihat tabel berikut.

Saat auto_create_slice=false, atau saat Anda ingin menyelesaikan persiapan resource sebelum menulis, Anda dapat mendaftarkan Slice secara eksplisit:

PUT /_slice_collection/knowledge-chunks/slices/tenant-c

API ini mendukung parameter kueri master_timeout.

Contoh respons:

{
  "acknowledged": true,
  "errors": false,
  "items": [
    {
      "slice_id": "tenant-c",
      "result": "created",
      "backing_index": ".sc-knowledge-chunks-...-00000"
    }
  ]
}

backing_index hanya untuk pengamatan dan troubleshooting dan tidak boleh digunakan sebagai target untuk permintaan aplikasi selanjutnya.

Daftarkan hingga 20480 Slice dengan nama unik sekaligus:

PUT /_slice_collection/knowledge-chunks/slices
{
  "slices": [
    "tenant-d",
    { "slice": "tenant-e" },
    { "slice_id": "tenant-f" }
  ]
}

API ini mendukung parameter kueri master_timeout. Ketiga format dapat dicampur dalam permintaan yang sama.

Pendaftaran batch mungkin sebagian berhasil. result setiap item mungkin created, updated, noop, atau failed. errors tingkat atas adalah true selama ada item yang gagal. Saat nama Slice tidak valid (misalnya, berisi :, dimulai dengan karakter non-alfanumerik, menggunakan nilai terpesan _all, atau melebihi batas panjang), API pendaftaran juga mengembalikan HTTP 200 dan memberikan failed dan alasan error dalam item yang sesuai.

Daftar Slice dengan paginasi

GET /_slice_collection/knowledge-chunks/slices?prefix=tenant-&page_size=100

Hasil dikembalikan dalam urutan menaik berdasarkan nama Slice. Jika Slice ditambahkan atau dihapus secara bersamaan selama paginasi, hasilnya konsisten lemah. Pertahankan prefix yang sama saat melanjutkan paginasi.

Hapus Slice

DELETE /_slice_collection/knowledge-chunks/slices/tenant-c

Parameter kueri:

Respons berhasil:

{
  "acknowledged": true
}

Setelah Slice dihapus, Slice dengan nama yang sama dapat didaftarkan ulang. Data baru diisolasi dari data lama yang menunggu pembersihan di latar belakang. Catatan:

• Setelah Slice dihapus, kueri yang menentukan nama Slice mengembalikan HTTP 404 (resource_not_found_exception) alih-alih hasil kosong.

• Kueri cakupan penuh menggunakan _slice=_all mungkin sementara mengembalikan data lama sebelum pembersihan fisik selesai.

• Respons penghapusan tidak menunjukkan bahwa ruang penyimpanan telah dilepaskan.

Tulis dan baca data

Collection menggunakan kembali API dokumen standar Elasticsearch dan menentukan namespace atau klaster vektor melalui _slice. API umum adalah sebagai berikut.

Aturan:

• Permintaan dokumen tunggal hanya dapat menentukan satu Slice. Nilai yang dipisahkan koma dan _all tidak diizinkan.

• index, create, dan update dapat mendaftarkan Slice yang belum ada secara otomatis saat auto_create_slice=true. Operasi baca dan hapus tidak mendaftarkan Slice secara otomatis. Menentukan Slice yang belum ada mengembalikan HTTP 404.

• Beberapa API dokumen dan kueri dapat menggunakan routing untuk merepresentasikan Slice logis. Untuk cakupan yang didukung dan aturan konflik, lihat Parameter kompatibilitas routing.

• Setiap permintaan Bulk dapat mendaftarkan otomatis hingga 512 Slice yang hilang berbeda. Slice yang ada tidak dihitung terhadap batas ini.

• wait_for_active_shards tidak digunakan sebagai kondisi untuk menunggu replika dalam pipeline tulis AI Engine Edition. Untuk menunggu dokumen dapat dicari, gunakan refresh=wait_for.

• Bidang dense_vector tidak termasuk dalam _source yang dikembalikan secara default. Baik GET /{collection}/_doc/{id} maupun GET /{collection}/_source/{id} tidak mengembalikan nilai vektor. Untuk mengembalikannya, tentukan secara eksplisit _source_includes.

Refresh dan visibilitas kueri

Permintaan tulis yang berhasil menunjukkan bahwa data telah dipersisten, bukan bahwa data dapat dikueri oleh node pencarian. AI Engine Edition menggunakan arsitektur tanpa status. Refresh memerlukan node indeks untuk menghasilkan dan menerbitkan Commit baru, lalu node pencarian memuat versi yang dapat dicari. Ini adalah operasi lintas-node terdistribusi dengan overhead lebih tinggi daripada Refresh lokal di Elasticsearch stateful tradisional.

Anda dapat mengkueri dan menyesuaikan index.refresh_interval melalui pengaturan Collection. Nilai saat ini dapat dilihat melalui GET /{collection}/_settings. Interval Refresh yang lebih pendek meningkatkan overhead resource. Untuk produksi, atur ke 5s atau lebih tinggi. Jika Anda memiliki persyaratan visibilitas latensi rendah, sesuaikan nilai berdasarkan beban kerja bisnis Anda. Nilai efektif aktual didasarkan pada pengaturan Collection saat ini. Refresh otomatis dapat dinonaktifkan dengan mengatur nilai ke -1. Sebelum memperpendek interval ini, evaluasi frekuensi penerbitan Commit, throughput tulis, dan I/O penyimpanan objek.

Pilih salah satu metode berikut berdasarkan persyaratan bisnis Anda untuk visibilitas kueri:

index.refresh_interval=-1 menonaktifkan Refresh otomatis. Dalam kasus ini, tulisan menggunakan refresh=wait_for akan menunggu tanpa batas hingga permintaan lain memicu Refresh eksplisit. Jangan menggabungkan pengaturan ini tanpa proses Refresh eksplisit. Untuk produksi, saat diperlukan baca-setelah-tulis, pilih antara menunggu Refresh otomatis atau Refresh eksplisit berdasarkan persyaratan latensi bisnis Anda, dan evaluasi overhead Refresh terdistribusi. Refresh hanya mengatasi visibilitas kueri. Ini tidak berarti semua replika kueri tersedia dan tidak dapat menggantikan probe kueri dan pemeriksaan ketersediaan tinggi.

Bulk

Setiap item Bulk dapat memberikan _slice sendiri dalam metadata aksi, seperti yang ditunjukkan dalam contoh mulai cepat. Saat semua item dalam batch ditulis ke Slice yang sama, Anda dapat memberikan nilai default di URL:

POST /knowledge-chunks/_bulk?_slice=tenant-a
{ "index": { "_id": "chunk-2001" } }
{ "tenant_id": "tenant-a", "document_id": "doc-account-security", "title": "Account security settings", "content": "Administrators can enable multi-factor authentication on the security settings page." }

_slice dalam item dapat mengganti nilai default URL. Mode namespace tidak menurunkan Slice dari bidang dokumen. Bahkan jika badan dokumen berisi bidang tenant_id, lokasi tulis aktual tetap ditentukan oleh _slice. Untuk penanganan error, lihat Konvensi API umum.

Multi Get

MGet cocok untuk membaca beberapa dokumen dengan ID yang diketahui sekaligus. Setiap item dapat mengakses Slice berbeda:

POST /knowledge-chunks/_mget
{
  "docs": [
    { "_id": "chunk-1001", "_slice": "tenant-a" },
    { "_id": "chunk-1002", "_slice": "tenant-b" }
  ]
}

_slice di URL dapat berfungsi sebagai nilai default. Setiap item dapat mengganti nilai default. Setiap item pada akhirnya harus diselesaikan ke satu Slice.

Reindex

Reindex cocok untuk migrasi data antara indeks reguler dan Collection, atau antara Collection berbeda. Untuk menyalin Slice dalam Collection yang sama, gunakan Copy Slice.

Saat sumber adalah Collection, Anda harus secara eksplisit menentukan source._slice dalam badan permintaan. Jika tidak, HTTP 400 dikembalikan. Saat tujuan adalah Collection, hanya satu Slice tujuan yang dapat ditentukan, dan nilainya harus menggunakan format ={slice}:

POST /_reindex
{
  "source": {
    "index": "source-knowledge-chunks",
    "_slice": "tenant-a,tenant-b"
  },
  "dest": {
    "index": "target-knowledge-chunks",
    "_slice": "=tenant-archive"
  }
}

Slice tujuan didaftarkan secara otomatis jika belum ada. Parameter slices tingkat atas merepresentasikan paralelisme Reindex Elasticsearch dan tidak terkait dengan jumlah Slice bisnis. Saat salah satu sisi adalah Collection, Reindex tidak mendukung skrip. Saat Collection adalah tujuan, pipeline ingest eksplisit tidak didukung.

Kueri data

Kueri Collection terus menggunakan Elasticsearch Query DSL. Bagian ini hanya mencakup cakupan kueri Slice yang ditambahkan oleh AI Engine Edition. Untuk Query DSL dan kemampuan kueri yang tidak tercantum dalam panduan ini, cakupan yang didukung aktual dari instans 9.99.0 yang berlaku.

Menentukan _slice secara eksplisit dalam kueri berlaku untuk kedua mode. Mode namespace biasanya memerlukan cakupan kueri eksplisit. Kueri KNN dalam mode recall klaster vektor dapat secara otomatis memilih beberapa Slice kandidat. Untuk informasi lebih lanjut, lihat Mode recall klaster vektor: Pemilihan Slice kandidat otomatis.

GET /knowledge-chunks/_search?_slice=tenant-a,tenant-b&ignore_missing_slice=true

PUT /_cluster/settings
{
  "persistent": {
    "apack.slice_collection.search.default_to_all_slices": true
  }
}

GET /knowledge-chunks/_search

PUT /_slice_collection/knowledge-chunks
{
  "settings": {
    "index.sliced_postings.enabled": true
  }
}

Warm Slice cache

API _warm_slice memuat data yang mungkin diakses oleh kueri berikutnya ke Slice tertentu dari penyimpanan objek ke cache bersama di node pencarian, mengurangi latensi kueri pertama untuk data dingin. Cakupan pemanasan mencakup vektor DiskBBQ, data indeks terbalik terkait Slice, nilai dokumen, dan bidang yang disimpan, serta mencakup semua replika yang dapat dicari dari shard tempat Slice berada.

Pemanasan hanya untuk optimasi cache. Ini hanya memengaruhi kecepatan akses berikutnya, tidak mengubah hasil kueri, dan tidak menjamin berapa lama data tetap dalam cache.

Kasus penggunaan pemanasan:

• Pengguna akan membuka basis pengetahuan, repositori kode, atau ruang memori Agent yang belum diakses dalam waktu lama. Anda dapat memanaskan Slice yang sesuai sebelum kueri pertama.

• Setelah impor batch atau migrasi data selesai, Anda dapat memanaskan Slice yang akan diaktifkan sebelum mengalihkan trafik kueri.

• Namespace tertentu diketahui mengalami puncak akses selama periode waktu tertentu. Anda dapat memanaskan Slice ini terlebih dahulu.

  Pemanasan aktif tidak disarankan saat akses data tidak dapat diprediksi, saat sejumlah besar Slice perlu dipanaskan sekaligus, atau saat Slice target sudah merupakan data panas. Pemanasan skala besar mengonsumsi penyimpanan objek dan sumber daya jaringan, cache, dan komputasi node pencarian. Ini juga dapat mengeluarkan data panas yang ada dari cache.

POST /knowledge-chunks/_warm_slice?_slice=tenant-a

{
  "status": "ACCEPTED",
  "message": "cache warm hint accepted",
  "task": "{nodeId}:{taskId}"
}

GET /_tasks/{nodeId}:{taskId}

POST /knowledge-chunks/_warm_slice?_slice=tenant-a&store_result=true

POST /knowledge-chunks/_warm_slice?_slice=tenant-a&wait_for_completion=true&timeout=60s

Pengindeksan vektor DiskBBQ

DiskBBQ sesuai dengan tipe indeks bbq_disk dari dense_vector. Ini adalah kemampuan pengindeksan vektor yang digunakan dalam shard, bukan mode Collection ketiga. Baik mode namespace maupun mode recall klaster vektor dapat menggunakan DiskBBQ. Bagian ini menjelaskan metode konfigurasi dan kueri. Untuk referensi kinerja AI Engine Edition, lihat Ikhtisar fitur.

Kasus penggunaan DiskBBQ:

• Skala vektor besar, dan Anda ingin mengurangi tekanan memori resident melalui pengindeksan vektor native disk.

• Anda dapat menggunakan set data evaluasi bisnis untuk menyetel keseimbangan antara tingkat recall, latensi kueri, dan overhead baca data.

  DiskBBQ tidak disarankan sebagai pendekatan default saat dataset kecil, hasil tetangga terdekat eksak diperlukan, atau evaluasi tingkat recall belum selesai.

PUT /{collection}/_mapping
{
  "properties": {
    "embedding": {
      "type": "dense_vector",
      "dims": 4,
      "index": true,
      "similarity": "cosine",
      "index_options": {
        "type": "bbq_disk"
      }
    }
  }
}

{
  "index_options": {
    "type": "bbq_disk",
    "cluster_size": 384,
    "flat_index_threshold": -1,
    "default_visit_percentage": 0.0,
    "rescore_vector": { "oversample": 3.0 },
    "bits": 1
  }
}

POST /knowledge-chunks/_search?_slice=tenant-a
{
  "knn": {
    "field": "embedding",
    "query_vector": [0.80, 0.12, 0.05, 0.03],
    "k": 10,
    "visit_percentage": 10.0
  },
  "_source": ["document_id", "title", "content"]
}

Alias Collection

Alias Collection menyediakan aplikasi dengan nama akses stabil. Alias dapat digunakan untuk mengkueri beberapa Collection secara seragam atau mengalihkan target tulis. Anda dapat menambahkan Alias saat membuat Collection melalui field aliases, atau mengelola Alias dengan menggunakan API Elasticsearch standar _aliases.

Kasus penggunaan Alias Collection:

• Migrasi versi: Aplikasi selalu mengakses Alias tetap. Setelah persiapan data selesai, alihkan target tulis dari Collection lama ke Collection baru.

• Kueri multi-Collection: Kueri beberapa Collection yang menggunakan slice_strategy yang sama melalui satu Alias.

• Decoupling aplikasi: Konfigurasi bisnis hanya menyimpan Alias dan tidak bergantung langsung pada nama Collection yang berisi versi atau tanggal.

  Alias Collection tidak berlaku jika bisnis Anda bergantung pada filter Alias atau routing, atau jika Anda ingin menyertakan indeks reguler dan Collection dalam Alias yang sama.

Contoh berikut mengasumsikan bahwa knowledge-chunks-v1 dan knowledge-chunks-v2 keduanya adalah Collection yang menggunakan mode namespace (exact). Tambahkan keduanya ke Alias yang sama dan atur knowledge-chunks-v2 sebagai target tulis:

POST /_aliases
{
  "actions": [
    {
      "add": {
        "index": "knowledge-chunks-v1",
        "alias": "knowledge-chunks-current"
      }
    },
    {
      "add": {
        "index": "knowledge-chunks-v2",
        "alias": "knowledge-chunks-current",
        "is_write_index": true
      }
    }
  ]
}

Lihat Alias:

GET /_alias/knowledge-chunks-current

Hapus anggota dari Alias:

POST /_aliases
{
  "actions": [
    {
      "remove": {
        "index": "knowledge-chunks-v1",
        "alias": "knowledge-chunks-current"
      }
    }
  ]
}

Perhatikan hal berikut saat menggunakan Alias:

• Anggota Alias yang sama harus menggunakan slice_strategy yang sama. Anggota yang menggunakan mode recall klaster vektor (vector_cluster) juga harus menggunakan dimensi vektor yang sama.

• Saat Alias multi-anggota digunakan untuk tulis, tepat satu anggota harus memiliki is_write_index=true.

• API seperti Search, Count, dan Bulk dapat mengakses Alias multi-anggota berdasarkan semantik Alias.

• GET dokumen tunggal dan setiap item dalam MGet harus diselesaikan secara unik ke satu Collection. Oleh karena itu, hanya Alias single-anggota yang dapat digunakan.

• filter, routing, index_routing, search_routing, is_hidden, dan remove_index saat ini tidak didukung untuk Alias.

  Saat Anda mengkueri Alias multi-anggota, Slice target harus ada di semua Collection anggota. Jika tidak, HTTP 404 dikembalikan. Selama migrasi versi, set Slice Collection lama dan baru biasanya berbeda. Dalam kasus ini, secara eksplisit sertakan ignore_missing_slice=true, misalnya, GET /knowledge-chunks-current/_search?_slice=tenant-a&ignore_missing_slice=true, sehingga permintaan melewati anggota yang hilang dan mengembalikan normal.

Salin Slice

Salin Slice menyalin dokumen yang dapat direplikasi dari satu Slice ke Slice lain dalam Collection yang sama secara online. Ini cocok untuk migrasi data, bukan untuk snapshot titik-waktu, backup, atau pengalihan trafik atomik.

Kasus penggunaan Salin Slice:

• Salin data pengujian atau verifikasi untuk penyewa sambil mempertahankan pemetaan Collection yang sama dengan Slice sumber.

• Siapkan namespace baru dalam Collection yang sama. Setelah Salin selesai dan diverifikasi, lapisan aplikasi mengalihkan nama akses.

• Lakukan migrasi data online untuk Slice sambil menjaga Slice sumber dan tujuan tetap dapat dibaca dan ditulis.

  Tulisan mungkin masih terjadi selama Salin. Oleh karena itu, hasilnya bukan snapshot titik-waktu dari sumber. Untuk backup, pemulihan bencana, snapshot konsisten ketat, atau pengalihan trafik atomik, jangan gunakan Salin Slice.

POST /_slice_collection/knowledge-chunks/slices/tenant-a/_copy/tenant-a-copy?wait_for_completion=false
{
  "workers": 8,
  "batch_size": 5000,
  "requests_per_second": -1
}

{
  "copy_id": "tenant-a-copy:1h",
  "completed": false,
  "timed_out": false,
  "state": "RUNNING",
  "source": "tenant-a",
  "target": "tenant-a-copy",
  "workers": 8,
  "progress": { "total": 0, "created": 0, "version_conflicts": 0 },
  "status_url": "/_slice_collection/knowledge-chunks/_copy/tenant-a-copy%3A1h",
  "cancel_url": "/_slice_collection/knowledge-chunks/_copy/tenant-a-copy%3A1h/_cancel"
}

GET /_slice_collection/knowledge-chunks/_copy/{copy_id}

PUT /_cluster/settings
{
  "persistent": {
    "apack.slice_collection.copy.reservation_retention": "1d"
  }
}

POST /_slice_collection/knowledge-chunks/_copy/{copy_id}/_cancel

Pemantauan kluster

Di panel navigasi kiri halaman detail instans di Konsol, pilih Monitoring and Logs > Cluster Monitoring untuk melihat metrik operasional instans. Saat mengonfigurasi ambang batas peringatan, atur berdasarkan SLO bisnis Anda dan garis dasar uji stres. Nama metrik spesifik dan titik masuk peringatan didasarkan pada Konsol.

Tabel berikut mencantumkan pemetaan antara target pengamatan umum dan metrik Konsol.

Halaman pemantauan kluster mengelompokkan metrik berdasarkan kategori dan tidak menyediakan pengelompokan berbasis role untuk node indeks dan node pencarian. Untuk mengamati dua jenis node secara terpisah, alihkan Tipe Resource ke Node Tertentu lalu filter berdasarkan nama node: nama node indeks berisi -index-, dan nama node pencarian berisi -search-. AI Engine Edition tidak memiliki node hangat. Anda hanya perlu memantau node indeks, node pencarian, dan metrik pemantauan yang sebenarnya disediakan oleh AI Engine Edition.

API CAT

API CAT cocok untuk pengamatan manual dan troubleshooting. Untuk ikhtisar harian, mulai dengan Collection. Saat terjadi anomali kapasitas atau shard, periksa Pendukung. Untuk menemukan distribusi data dan hitungan dokumen namespace tertentu, periksa Slice. Aplikasi tidak boleh bergantung pada output CAT untuk permintaan bisnis.

Kolom default:

Parameter kueri umum:

CAT Slice juga mendukung backing={backing} untuk mempersempit cakupan ke nama Pendukung lengkap tertentu. Sortir di semua Pendukung berdasarkan docs.count adalah kueri berbiaya tinggi dan memerlukan pengaturan eksplisit allow_expensive_search=true.

Untuk pemrosesan terprogram, gunakan format=json dan tentukan kolom secara eksplisit:

GET /_cat/slice_collection/knowledge-chunks?format=json&h=collection,state,backings,slices,docs.count,pri.store.size

API CAT dirancang untuk troubleshooting manual dan kueri operasi terbatas:

• CAT Slice mengembalikan maksimal 10000 baris. Saat batas terlampaui, header HTTP Warning menunjukkan bahwa hasil tidak lengkap.

• Saat Anda memerlukan daftar Slice lengkap dan stabil terpaginasi, gunakan GET /_slice_collection/{collection}/slices.

• docs.count adalah data near-real-time. Dokumen yang telah ditulis tetapi belum di-refresh mungkin tidak dihitung.

• pri.store.size dan store.size merepresentasikan ukuran data yang diindeks, yang tidak setara dengan penggunaan disk lokal pada node tanpa status. Ukuran ini juga tidak termasuk data historis dalam penyimpanan objek yang menunggu pembersihan.

Hapus Collection

API ini berlaku untuk mengambil data bisnis offline atau membersihkan contoh dalam panduan ini. Penghapusan menghapus konfigurasi Collection dan data yang dikelola sistem. Operasi ini tidak dapat dikembalikan. Untuk membersihkan hanya Slice tertentu, gunakan API hapus Slice.

DELETE /_slice_collection/knowledge-chunks

Parameter kueri:

Respons berhasil:

{
  "acknowledged": true
}

{collection} mendukung nama yang dipisahkan koma. Secara default, wildcard * dan _all tidak diizinkan. Permintaan mengembalikan HTTP 400. Untuk menggunakannya, sesuaikan pengaturan kluster action.destructive_requires_name.

Penghapusan mengembalikan HTTP 409 saat operasi Salin Slice sedang berjalan atau dibatalkan. Pembatalan bersifat asinkron. Penghapusan masih akan ditolak hingga state berubah menjadi CANCELLED. Konfirmasi bahwa state=CANCELLED sebelum mengeksekusi penghapusan.

acknowledged=true menunjukkan bahwa penghapusan resource logis dan metadata telah dikonfirmasi. Indeks historis dan file Translog dalam penyimpanan objek diklaim kembali secara asinkron oleh proses latar belakang. Ruang fisik tidak dijamin dilepaskan segera saat respons dikembalikan.

Izin Koleksi

Saat mengonfigurasi role, nama indeks harus mencakup nama Collection dan wildcard Pendukung yang sesuai:

<collection>
.sc-<collection>-*

Misalnya, jika nama Collection adalah knowledge-chunks, konfigurasikan knowledge-chunks dan .sc-knowledge-chunks-* dalam role. Mengonfigurasi hanya nama Collection menyebabkan operasi seperti baca/tulis dokumen tunggal, MGet, Refresh eksplisit, dan _update_by_query mengembalikan HTTP 403.

.sc-* hanya untuk konfigurasi izin. Aplikasi masih harus mengakses data melalui nama Collection dan tidak boleh mengakses atau menyimpan nama Indeks Pendukung tertentu secara langsung.

Slice bukan batas isolasi izin penyewa. Untuk mengisolasi izin, implementasikan di lapisan aplikasi atau melalui model keamanan Elasticsearch yang didukung lainnya.

Perbedaan umum dari Elasticsearch stateful tradisional

Pengaturan yang ditandai sebagai tidak berlaku dalam tabel berikut mungkin mengembalikan HTTP 200 saat dimodifikasi, dan nilai baru mungkin terlihat saat dibaca kembali. Ini tidak menunjukkan bahwa fitur diaktifkan.

Selain itu, replika dalam arsitektur tanpa status terutama digunakan untuk kueri dan cache. Replika ini tidak setara dengan replika persisten dalam Elasticsearch stateful tradisional yang dapat dipromosikan menjadi shard utama. Jumlah replika kueri dan node pencarian bersama-sama menentukan kapasitas dan ketersediaan kueri. Data persisten disimpan dalam penyimpanan objek. Meningkatkan jumlah replika tidak dapat menggantikan strategi backup.

Batasan saat menggunakan Collection dan Slice

Batasan berikut hanya berlaku untuk penggunaan Collection dan Slice dalam AI Engine Edition. Ini tidak berarti kemampuan dengan nama yang sama juga tidak tersedia untuk indeks reguler.

Referensi cepat API

Berikut adalah ringkasan API publik 9.99.0 yang diperlukan untuk kasus penggunaan dalam panduan ini. Ini bukan daftar API Elasticsearch lengkap, juga tidak mencakup API yang dipelihara secara internal.