Panduan Pengembangan Detail Chromadb Python

Instalasi

pip install chromadb

Mempermanenkan Data Chromadb

import chromadb

Anda dapat menentukan jalur penyimpanan untuk file basis data Chroma. Jika data sudah ada, file basis data akan secara otomatis dimuat saat program dimulai.

client = chromadb.PersistentClient(path="/data/tizi365.db")

Parameter path merupakan jalur ke file basis data Chroma.

Catatan: Untuk basis data Chroma, membuat objek klien sekali sudah cukup. Memuat dan menyimpan beberapa klien di jalur yang sama dapat mengakibatkan perilaku yang tidak diharapkan, termasuk penghapusan data. Umumnya, hanya satu klien Chroma harus dibuat dalam aplikasi.

Beberapa fungsi klien yang umum digunakan:

client.reset()  # Menghapus dan mengatur ulang basis data sepenuhnya

Operasi Koleksi

Chromadb menggunakan primitif koleksi untuk mengelola koleksi data vektor, yang dapat disamakan dengan tabel dalam MySQL.

Membuat, Melihat, dan Menghapus Koleksi

Chroma menggunakan nama koleksi dalam URL, sehingga memiliki beberapa pembatasan penamaan:

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

Untuk membuat koleksi, Anda perlu menentukan nama koleksi dan fungsi perhitungan vektor opsional (juga dikenal sebagai fungsi penanaman). Jika fungsi penanaman disediakan, itu harus disediakan setiap kali koleksi diakses.

Catatan: Tujuan dari fungsi perhitungan vektor (fungsi penanaman) adalah untuk menghitung vektor teks.

collection = client.create_collection(name="my_collection", embedding_function=emb_fn)
collection = client.get_collection(name="my_collection", embedding_function=emb_fn)

Fungsi penanaman mengambil teks sebagai masukan dan mengembalikan vektor yang dihitung.

Catatan: Pemula dapat mempelajari panduan model penyemat teks.

Anda dapat merujuk koleksi yang ada dengan fungsi .get_collection, dan gunakan .delete_collection untuk menghapus koleksi. Anda juga dapat menggunakan .get_or_create_collection untuk merujuk koleksi (jika koleksi tersebut ada) atau membuatnya jika tidak ada.

collection = client.get_collection(name="tizi365")
collection = client.get_or_create_collection(name="tizi365")
client.delete_collection(name="tizi365")

Operasi koleksi lain yang umum digunakan:

collection.peek() # Mengembalikan daftar 10 data pertama dalam koleksi
collection.count() # Mengembalikan jumlah total data dalam koleksi
collection.modify(name="new_name") # Mengubah nama koleksi

Menentukan Metode Perhitungan Jarak Vektor

Fungsi create_collection juga termasuk parameter metadata opsional. Dengan mengatur nilai hnsw:space untuk menyesuaikan metode perhitungan jarak ruang vektor.

Catatan: Data vektor mewakili kesamaan antara vektor dengan menghitung jarak spatial antara vektor. Semakin dekat jaraknya, semakin tinggi kesamaannya, dan sebaliknya.

collection = client.create_collection(
        name="collection_name",
        metadata={"hnsw:space": "cosine"} # l2 adalah metode perhitungan default
    )

Opsi valid untuk hnsw:space adalah "l2", "ip", atau "cosine". Defaultnya adalah "l2".

Menambahkan Data ke Koleksi

Gunakan metode .add untuk menambahkan data ke Chroma.

Tambahkan data langsung tanpa menentukan vektor dokumen:

collection.add(
    documents=["lorem ipsum...", "doc2", "doc3", ...],
    metadatas=[{"bab": "3", "ayat": "16"}, {"bab": "3", "ayat": "5"}, {"bab": "29", "ayat": "11"}, ...],
    ids=["id1", "id2", "id3", ...]
)

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

Setiap dokumen harus memiliki ID unik (ids). Menambahkan ID yang sama dua kali akan menghasilkan penyimpanan nilai awal saja. Opsional, Anda dapat menyediakan daftar kamus metadata (metadatas) untuk setiap dokumen, untuk menyimpan informasi tambahan yang dapat digunakan untuk penyaringan data selama kueri.

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

collection.add(
    documents=["doc1", "doc2", "doc3", ...],
    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"}, ...],
    ids=["id1", "id2", "id3", ...]
)

Jika dimensi data vektor yang diberikan (panjang) tidak cocok dengan dimensi koleksi, maka akan terjadi pengecualian.

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

collection.add(
    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"}, ...],
    ids=["id1", "id2", "id3", ...]
)

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 atribut penyaringan yang diperlukan di basis data vektor. Data lain, seperti konten artikel, dapat disimpan di basis data seperti MYSQL, selama mereka terkait melalui ID.

Penggunaan Pengumpulan Data

Metode .query dapat digunakan untuk mengambil data Chroma dari kumpulan data dalam berbagai cara.

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

Tip: Pada skenario pengembangan nyata, query_embeddings biasanya diperoleh dengan pertama-tama menghitung vektor dari query pengguna melalui sebuah model penanaman teks, dan kemudian menggunakan vektor ini untuk mengambil konten serupa.

collection.query(
    query_embeddings=[[11,1, 12.1, 13,1],[1,1, 2,3, 3,2], ...],
    n_results=10,
    where={"metadata_field": "sama_dengan_ini"},
    where_document={"$contains":"kata_kunci"}
)

Query akan mengembalikan n_results hasil yang paling cocok dengan masing-masing 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, kamus filter where_document opsional dapat diberikan untuk menyaring hasil berdasarkan konten dokumen.

Jika query_embeddings yang diberikan tidak konsisten dengan dimensi koleksi, maka akan terjadi pengecualian. Untuk memastikan dimensi vektor yang konsisten, gunakan model penanaman teks yang sama untuk menghitung vektor.

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

collection.query(
    query_texts=["doc10", "thus spake zarathustra", ...],
    n_results=10,
    where={"metadata_field": "sama_dengan_ini"},
    where_document={"$contains":"kata_kunci"}
)

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

collection.get(
    ids=["id1", "id2", "id3", ...],
    where={"gaya": "gaya1"}
)

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

Menentukan Kolom yang Dikembalikan

Ketika menggunakan get atau query, Anda dapat menggunakan parameter include untuk menentukan data yang akan dikembalikan--embedding, dokumen, atau metadata, dan untuk query, data jarak perlu dikembalikan. Secara default, Chroma mengembalikan dokumen dan metadata, dan mengembalikan data jarak untuk query, sambil "ids" selalu dikembalikan. Anda dapat menentukan kolom yang akan dikembalikan dengan melewatkan array nama-nama kolom ke parameter include dari metode query atau get.

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 query berdasarkan metadata dan konten dokumen. Filter where digunakan untuk menyaring metadata, dan filter where_document digunakan untuk menyaring konten dokumen, dan berikut ini menjelaskan cara menulis ekspresi kondisi filter.

Menyaring Berdasarkan Metadata

Untuk menyaring metadata, Anda harus menyediakan kamus filter where untuk query. 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": "kata_kunci"
}

{
    "metadata_field": {
        "$eq": "kata_kunci"
    }
}

Menyaring Konten Dokumen

Untuk menyaring konten dokumen, Anda harus menyediakan kamus filter where_document untuk query. Kamus harus memiliki struktur berikut:

{
    "$contains": "kata_kunci"
}

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 salah satu kondisi filter dalam daftar.

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

Memperbarui Data dalam Koleksi

Menggunakan .update memungkinkan Anda untuk memperbarui properti data dalam sebuah koleksi.

collection.update(
    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", ...],
)

Jika suatu id tidak ditemukan dalam koleksi, sebuah kesalahan akan dicatat dan pembaruan akan diabaikan. Jika dokumen yang diberikan tidak memiliki vektor yang sesuai, fungsi embedding koleksi akan digunakan untuk menghitung vektor.

Jika data vektor yang diberikan memiliki dimensi yang berbeda dengan koleksi, maka akan terjadi pengecualian.

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

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 dalam Koleksi

Chroma mendukung penggunaan .delete untuk menghapus data dari sebuah koleksi berdasarkan id. Vektor, dokumen, dan metadata yang terkait dengan setiap data juga akan dihapus.

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

.delete juga mendukung filter where. Jika tidak ada id yang diberikan, maka akan menghapus semua item dalam koleksi yang cocok dengan filter where.

Panduan Pengembangan Database Vektor Python Chromadb