Memulai Data Kroma Persisten

import { ChromaClient } from 'chromadb'

Memulai Klien

const client = new ChromaClient();

Operasi Umum Klien

await client.reset() // Hapus basis data

Bekerja dengan Koleksi

Chromadb menggunakan konsep koleksi untuk mengelola set data vektor, yang bisa disamakan dengan tabel di MySQL.

Membuat, Melihat, dan Menghapus Koleksi

Chroma menggunakan nama koleksi dalam URL, sehingga ada beberapa batasan penamaan:

  • Panjang nama harus antara 3 dan 63 karakter.
  • Nama harus diawali dan diakhiri dengan huruf kecil atau angka, dan dapat mengandung titik, tanda hubung, dan garis bawah di antaranya.
  • Nama tidak boleh mengandung dua periode berturut-turut.
  • Nama tidak boleh menjadi alamat IP yang valid.

Untuk membuat koleksi, nama koleksi dan fungsi perhitungan vektor opsional (juga dikenal sebagai fungsi embedding) perlu ditentukan. Jika fungsi embedding disediakan, harus disediakan setiap kali koleksi diakses.

Catatan: Fungsi embedding digunakan untuk menghitung vektor teks.

import { ChromaClient } from 'chromadb'

Buat dan rujuk koleksi seperti yang ditunjukkan di bawah ini:

let collection = await client.createCollection({name: "my_collection", embeddingFunction: emb_fn})

let collection2 = await client.getCollection({name: "my_collection", embeddingFunction: emb_fn})

Fungsi embedding mengambil teks sebagai input dan mengembalikan data vektor yang dihitung.

Catatan: Pemula dapat belajar tentang model embedding teks dari tutorial ini.

Koleksi yang ada dapat dirujuk menggunakan .getCollection berdasarkan nama, dan juga dapat dihapus menggunakan .deleteCollection.

const collection = await client.getCollection({name: "tizi365"}) // Rujuk koleksi tizi365
await client.deleteCollection({name: "my_collection"}) // Hapus koleksi

Fungsi Koleksi Umum

await collection.peek() // Mengembalikan 10 catatan data pertama dalam koleksi
await collection.count() // Mengembalikan jumlah total catatan data dalam koleksi

Menyesuaikan Metode Perhitungan Jarak Vektor

createCollection juga mencakup parameter metadata opsional, di mana nilai hnsw:spasi bisa diatur untuk menyesuaikan metode perhitungan jarak untuk ruang vektor.

Catatan: Data vektor mewakili kesamaan antara vektor dengan menghitung jarak spasial di antara mereka, dengan jarak yang lebih dekat menunjukkan kesamaan yang lebih tinggi dan sebaliknya.

let collection = client.createCollection("collection_name", undefined, metadata={ "hnsw:space": "cosine" })

Opsi valid untuk hnsw:spasi adalah "l2", "ip", atau "cosine". Default adalah "l2".

Menambahkan Data ke Koleksi

Gunakan .add untuk menambahkan data ke koleksi Chroma.

Tambahkan data secara langsung tanpa menentukan vektor dokumen:

await collection.add({
    ids: ["id1", "id2", "id3", ...],
    metadatas: [{"bab": "3", "ayat": "16"}, {"bab": "3", "ayat": "5"}, {"bab": "29", "ayat": "11"}, ...],
    documents: ["lorem ipsum...", "doc2", "doc3", ...],
})
// Penjelasan Parameter
// ids - wajib
// embeddings - opsional
// metadata - opsional
// documents - opsional

Jika Chroma menerima daftar dokumen, itu akan secara otomatis menggunakan fungsi embedding koleksi untuk menghitung vektor untuk dokumen-dokumen (jika fungsi embedding tidak disediakan saat membuat koleksi, nilai default akan digunakan). Chroma juga akan menyimpan dokumen-dokumen itu sendiri. Jika dokumen terlalu besar untuk digunakan dengan fungsi embedding yang dipilih, akan terjadi pengecualian.

Setiap dokumen harus memiliki ID unik (ids). Menambahkan ID yang sama dua kali akan mengakibatkan hanya nilai awal yang disimpan. Daftar opsional dari kamus metadata (metadatas) dapat disediakan untuk setiap dokumen untuk menyimpan informasi tambahan untuk penyaringan data selama kueri.

Atau, Anda dapat langsung menyediakan daftar data vektor terkait dokumen, dan Chroma akan menggunakan data vektor yang Anda berikan tanpa menghitung vektor secara otomatis.

await collection.add({
    ids: ["id1", "id2", "id3", ...],
    embeddings: [[1.1, 2.3, 3.2], [4.5, 6.9, 4.4], [1.1, 2.3, 3.2], ...],
    metadatas: [{"bab": "3", "ayat": "16"}, {"bab": "3", "ayat": "5"}, {"bab": "29", "ayat": "11"}, ...],
    documents: ["lorem ipsum...", "doc2", "doc3", ...],
})

Jika dimensi data vektor yang disediakan (panjangnya) tidak cocok dengan dimensi koleksi, akan terjadi pengecualian.

Anda juga dapat menyimpan dokumen-dokumen di tempat lain dan hanya menyediakan data vektor dan daftar metadata ke Chroma. Anda dapat menggunakan ids untuk mengaitkan vektor dengan dokumen-dokumen yang disimpan di tempat lain.

await collection.add({
    ids: ["id1", "id2", "id3", ...],
    embeddings: [[1.1, 2.3, 3.2], [4.5, 6.9, 4.4], [1.1, 2.3, 3.2], ...],
    metadatas: [{"bab": "3", "ayat": "16"}, {"bab": "3", "ayat": "5"}, {"bab": "29", "ayat": "11"}, ...],
})

Catatan: Fungsi inti dari basis data vektor adalah pencarian kesamaan semantik berdasarkan data vektor. Untuk mengurangi ukuran basis data vektor dan meningkatkan efisiensi, kita dapat memilih untuk menyimpan data vektor dan beberapa kondisi atribut yang dapat difilter dalam basis data vektor. Data lain, seperti konten artikel, dapat disimpan di basis data seperti MYSQL, selama mereka terkait melalui ID.

Meminta Data Koleksi

Metode .query dapat digunakan untuk meminta data dataset dari Chroma dalam berbagai cara.

Anda dapat melakukan permintaan menggunakan kumpulan query_embeddings (data vektor).

Tip: Untuk mendapatkan query_embeddings, dalam skenario pengembangan yang sebenarnya, permintaan pengguna biasanya pertama-tama dihitung menjadi vektor query melalui model embedding teks, dan kemudian vektor ini digunakan untuk meminta konten serupa.

const result = await collection.query({
    queryEmbeddings: [[11.1, 12.1, 13.1],[1.1, 2.3, 3.2], ...],
    nResults: 10,
    where: {"metadata_field": "sama_dengan_ini"},
})
// urutan input
// query_embeddings - opsional
// n_results - diperlukan
// where - opsional
// query_texts - opsional

Permintaan akan mengembalikan hasil teratas n_results untuk setiap vektor query (query_embedding) secara berurutan. Sebuah kamus filter where opsional dapat diberikan untuk menyaring hasil berdasarkan metadata yang terkait dengan setiap dokumen. Selain itu, sebuah kamus filter where_document opsional dapat diberikan untuk menyaring hasil berdasarkan konten dokumen.

Jika query_embeddings yang diberikan tidak konsisten dengan dimensi koleksi, akan terjadi pengecualian. Untuk menjamin konsistensi vektor, disarankan untuk menggunakan model embedding teks yang sama untuk menghitung vektor.

Anda juga dapat melakukan permintaan menggunakan kumpulan teks query. Chroma akan pertama-tama menghitung vektor untuk setiap teks query menggunakan fungsi embedding koleksi, dan kemudian menjalankan permintaan menggunakan vektor teks yang dihasilkan.

await collection.query({
    nResults: 10, // n_results
    where: {"metadata_field": "sama_dengan_ini"}, // where
    queryTexts: ["doc10", "thus spake zarathustra", ...], // query_text
})

Anda juga dapat menggunakan .get untuk meminta data dari koleksi berdasarkan id.

await collection.get({
    ids: ["id1", "id2", "id3", ...], //ids
    where: {"style": "gaya1"} // where
})

.get juga mendukung filter where dan where_document. Jika tidak ada id yang diberikan, akan mengembalikan semua data dalam koleksi yang cocok dengan filter where dan where_document.

Menentukan Bidang yang Dikembalikan

Ketika menggunakan get atau query, Anda dapat menggunakan parameter include untuk menentukan bidang data yang akan dikembalikan, termasuk data vektor, dokumen, dan semua data dalam metadata. Secara default, Chroma mengembalikan dokumen, metadata, dan jarak vektor. Anda dapat menentukan bidang yang akan dikembalikan dengan melewatkan array nama-nama bidang ke parameter includes dari get atau query.

collection.get(
    include=["documents"]
)

collection.query(
    query_embeddings=[[11.1, 12.1, 13.1],[1.1, 2.3, 3.2], ...],
    include=["documents"]
)

Menggunakan Filter Where

Chroma mendukung penyaringan permintaan berdasarkan metadata dan konten dokumen. Filter where digunakan untuk menyaring metadata, dan filter where_document digunakan untuk menyaring konten dokumen. Di bawah ini, kami menjelaskan bagaimana menulis ekspresi kondisi filter.

Menyaring berdasarkan Metadata

Untuk menyaring metadata, kamus filter where harus disediakan untuk permintaan. Kamus harus memiliki struktur berikut:

{
    "metadata_field": {
        <Operator>: <Value>
    }
}

Penyaringan metadata mendukung operator berikut:

  • $eq - Sama dengan (string, integer, float)
  • $ne - Tidak sama dengan (string, integer, float)
  • $gt - Lebih besar dari (int, float)
  • $gte - Lebih besar dari atau sama dengan (int, float)
  • $lt - Kurang dari (integer, float)
  • $lte - Kurang dari atau sama dengan (int, float)

Menggunakan operator $eq ekuivalen dengan menggunakan filter where.

{
    "metadata_field": "search_string"
}


{
    "metadata_field": {
        "$eq": "search_string"
    }
}

Menyaring Konten Dokumen

Untuk menyaring konten dokumen, kamus filter where_document harus disediakan untuk permintaan. Kamus harus memiliki struktur berikut:

{
    "$contains": "search_string"
}

Menggunakan Operator Logika

Anda juga dapat menggunakan operator logika $and dan $or untuk menggabungkan beberapa filter.

Operator $and akan mengembalikan hasil yang cocok dengan semua filter dalam daftar.

{
    "$and": [
        {
            "metadata_field": {
                <Operator>: <Value>
            }
        },
        {
            "metadata_field": {
                <Operator>: <Value>
            }
        }
    ]
}

Operator $or akan mengembalikan hasil yang cocok dengan setiap kondisi filter dalam daftar.

{
    "$or": [
        {
            "metadata_field": {
              <Operator>: <Value>
            }
        },
        {
            "metadata_field": {
                <Operator>: <Value>
            }
        }
    ]
}

Memperbarui Data

Chroma juga mendukung operasi upsert, yang dapat memperbarui data yang ada dan memasukkan data baru jika data tersebut tidak ada.

await collection.upsert({
    ids: ["id1", "id2", "id3"],
    embeddings: [[1.1, 2.3, 3.2], [4.5, 6.9, 4.4], [1.1, 2.3, 3.2]],
    metadatas: [{"chapter": "3", "verse": "16"}, {"chapter": "3", "verse": "5"}, {"chapter": "29", "verse": "11"}],
    documents: ["doc1", "doc2", "doc3"]
})

Menghapus Data

Chroma mendukung penggunaan .delete untuk menghapus data dari koleksi berdasarkan id.

await collection.delete({
    ids: ["id1", "id2", "id3",...], //ids
    where: {"chapter": "20"} //where
})