جاوا اسکرپٹ کروماڈب ویکٹر ڈیٹابیس ترقیاتی گائیڈ

مستقل کروما ڈیٹا کی شروعات

import { ChromaClient } from 'chromadb'

کلائنٹ کا آغاز

const client = new ChromaClient();

عام کلائنٹ کے عمل

await client.reset() // ڈیٹا بیس کو صاف کریں

کلیکشن کے ساتھ کام کرنا

کروما ڈیٹا بیس collection کے تصور کا استعمال کرتا ہے تاکہ فیصلی سے برابر ہوسکے جو MySQL میں جداول کے لئے کیا جاتا ہے۔

کلیکشن کی تخلیق، دیکھنا، اور حذف کرنا

Chroma کلیکشن کے نام کو یو آر ایل میں استعمال کرتا ہے، لہذا کچھ نام رکاوٹیں ہیں:

• نام کی لمبائی 3 اور 63 حروف کے درمیان ہونی چاہئیں۔
• نام کے شروع اور اختتام میں حروف یا نمبر ہونے چاہئیں، اور درمیان میں نقطے، ڈیش، اور انڈر اسکور ہوسکتے ہیں۔
• نام میں دو ہم آہنگ نقطے نہیں ہوسکتے۔
• نام ایک درست IP پتہ نہیں ہوسکتا۔

کلیکشن کی تخلیق کرنے کے لئے، کلیکشن کا نام اور ایک اختیاری ویکٹر حساب کرنے کا فنکشن (جسے انبیڈنگ فنکشن کہتے ہیں) مخصوص کرنا ہوگا۔ اگر ایک انبیڈنگ فنکشن فراہم کی گئی ہے، تو ہر بار کلیکشن تک رسائی حاصل کرتے وقت یہ فنکشن بھی فراہم کیا جانا چاہئے۔

نوٹ: انبیڈنگ فنکشن متن ویکٹرز کا حساب کرنے کے لئے استعمال ہوتا ہے۔

import { ChromaClient } from 'chromadb'

نیچے دیکھایں گئی مثال میں کلیکشن کی تخلیق اور ریفرنس کے طریقہ ظاہر ہوا ہے:

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

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

انبیڈنگ فنکشن میں متن درآمد لیتا ہے اور ایک حساب شدہ ویکٹر ڈیٹا واپس کرتا ہے۔

نوٹ: نوابین متن انبیڈنگ ماڈلز کے بارے میں اس ہدایت نامے سے معلومات حاصل کر سکتے ہیں۔

موجودہ کلیکشنز کو نام کے ذریعہ .getCollection سے حاصل کیا جاسکتا ہے، اور یوں کرکے .deleteCollection سے حذف بھی کیا جاسکتا ہے۔

const collection = await client.getCollection({name: "tizi365"}) // کلیکشن tizi365 کا ریفرنس
await client.deleteCollection({name: "my_collection"}) // کلیکشن حذف کریں

عام کلیکشن فنکشنز

await collection.peek() // کلیکشن میں پہلے 10 ڈیٹا ریکارڈ واپس کرتا ہے
await collection.count() // کلیکشن میں مکمل ڈیٹا ریکارڈ کی تعداد واپس کرتا ہے

ویکٹر فاصلے کے حساب کرنے والے ٹھوسانے کے طریقے ترتیب دینے

createCollection میں ایک اختیاری metadata پیرامیٹر شامل ہوتا ہے، جہاں hnsw:space کی قیمت کو ویکٹر فضا کے لئے فاصلے حساب کرنے والے ٹھوسانے کی ترتیب دی جاسکتی ہے۔

نوٹ: ویکٹر ڈیٹا فاصلہ حساب کرکے ویکٹرز کے درمیان مشابہت کو ظاہر کرتا ہے، جہاں قریبی فاصلے کو بلند مشابہت ظاہر کرتے ہیں اور الٹی صورت میں دور کے فاصلے ہوتے ہیں۔

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

hnsw:space کے درست اختیارات "l2"، "ip"، یا "cosine" ہیں۔ ڈیفالٹ "l2" ہے۔

کالکشن میں ڈیٹا شامل کرنا

.add کا استعمال کرکے کرُما کالکشن میں ڈیٹا شامل کریں۔

دستاویز بنانے کے بغیر ڈیٹا سیدھے طور پر شامل کریں:

await collection.add({
    ids: ["id1", "id2", "id3", ...],
    metadatas: [{"chapter": "3", "verse": "16"}, {"chapter": "3", "verse": "5"}, {"chapter": "29", "verse": "11"}, ...],
    documents: ["lorem ipsum...", "doc2", "doc3", ...],
})
// پیرامیٹر وضاحت
// ids - ضروری
// embeddings - اختیاری
// metadata - اختیاری
// documents - اختیاری

اگر کرُما کو دستاویز کی فہرست موصول ہوتی ہے، تو یہ خود بخود کالکشن کی امبیڈنگ فنکشن کا استعمال کرکے ڈیٹا فیکٹرز حاصل کرے گا (اگر کالکشن کو بنانے کے وقت امبیڈنگ فنکشن فراہم نہ کی گئی تو ڈیفالٹ قیمت استعمال ہوگی)۔ کرُما وہیضستاویز خود بھی محفوظ کرے گا۔ اگر منتخب کردہ امبیڈنگ فنکشن کے ساتھ کسی ڈاکومینٹ کی سائز زیادہ ہو تو ایک استثنا واقع ہوگا۔

ہر ڈاکومینٹ کا ایک یکتا شناخت (ids) ہونا ضروری ہے۔ اگر کسی ID کو دو بار شامل کیا جائے تو صرف ابتدائی قیمت محفوظ ہوگی۔ ہر ڈاکومینٹ کے لئے فلٹرنگ ڈیٹا کو محفوظ کرنے کے لئے امکانی میٹا ڈیٹا کی فہرست (میٹا ڈیٹاز) دی جا سکتی ہے۔

یا تو، آپ ڈاکومینٹ سے متعلق ویکٹر ڈیٹا کی فہرست فراہم کرسکتے ہیں، اور کرُما وہیڈیٹا جو آپ فراہم کریں بخود استعمال کرے گا بغیر خود بخود فیکٹر حاصل کرے گا۔

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: [{"chapter": "3", "verse": "16"}, {"chapter": "3", "verse": "5"}, {"chapter": "29", "verse": "11"}, ...],
    documents: ["lorem ipsum...", "doc2", "doc3", ...],
})

اگر فراہم کردہ ویکٹر ڈیٹا کا آکار (لمبائی) کالکشن کے آکار سے میل نہ کرے تو ایک استثنا واقع ہوگا۔

آپ دستاویز کو کہیں اور محفوظ کرکے کرُما کو صرف ویکٹر ڈیٹا اور میٹا ڈیٹا کی فہرست فراہم کرسکتے ہیں۔ آپ ویکٹروں کو اس طرح کے دستاویز کے ساتھ منسلک کرنے کے لئے ادارے میں استعمال کرسکتے ہیں۔

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: [{"chapter": "3", "verse": "16"}, {"chapter": "3", "verse": "5"}, {"chapter": "29", "verse": "11"}, ...],
})

نوٹ: ویکٹر ڈیٹا بیس کا بنیادی فنکشن ویکٹر ڈیٹا پر مبنی معنوی مشابہت تلاش ہے۔ ویکٹر ڈیٹا بیس کا سائز کم کرنے اور کارکردگی کو بہتر بنانے کے لئے ہم ویکٹر ڈیٹا اور مختلف قابل فلٹر کنڈیشنز کو ویکٹر ڈیٹا بیس میں محفوظ کرسکتے ہیں۔ دوسری ڈیٹا جیسے کہ مائی ایس کیسل ویسے ڈیٹابیس میں محفوظ کرسکتے ہیں، بس اس شرط سے کہ انہیں یکتا شناخت کے ذریعے منسلک کیا گیا ہو۔

کلیکشن ڈیٹا کی کوئیری کرنا

.query میتھڈ کا استعمال مختلف طریقوں سے کرایا جا سکتا ہے تاکہ چروما ڈیٹا سیٹ کی کوئیری ہوسکے۔

آپ کوئیری اس طرح کرسکتے ہیں:

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

موجودہ کوئیری ویکٹر (کوئیری ایمبیڈنگ) کے لئے ہر کوئیری ویکٹر کے لئے ٹاپ n_results نتائج واپس کریگا۔ ایک ضمنی ویرہ کارٹن کو فراہم کرسکتے ہیں تاکہ ہر دستاویز کے ساتھ جڑے میٹا ڈیٹا کو فلٹر کریں۔

آپ کوئیری کرنے کے لئے بھی مسلسل متن کے تھروے سے ویکٹر کا استعمال کرسکتے ہیں۔ متن ویکٹر کا استعمال کرتے ہوئے ثابت کریں کے ویکٹر ہمیشہ کلیکشن کے ایمبیڈنگ فنکشن کے لئے حاصل ہوں۔

آپ یہ بھی استعمال کرسکتے ہیں

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

آپ .get کا بھی استعمال کرسکتے ہیں تاکہ آپ کلیکشن سے شناخت کے دستاویز دیکھ سکیں۔

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

.get میں بھی where اور where_document فلٹر کا سپورٹ ہوتا ہے۔ اگر کوئی id فراہم نہیں کیا جائے، تو یہ where اور where_document فلٹر کے مطابقت کاری ہو جائے گا۔

واپسی شدہ فیلڈز کا تعین کرنا

جب get یا query کا استعمال کرتے ہیں، آپ include پیرامیٹر کو استعمال کر کے واپسی دیکھا سکتے ہیں کہ کون سے ڈیٹا فیلڈز واپس کرنے ہیں، جو ویکٹر ڈیٹا، داستانیں اور میٹا ڈیٹا شامل ہیں۔ چروما پہلے سے واپس ساتھ ویکٹر دوریاں دیتا ہے۔ آپ get یا query کے includes پیرامیٹر میں فیلڈ ناموں کی ایک ایرے فراہم کر کے واپس کرنے والے فیلڈز کا تعین کرسکتے ہیں۔

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

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

وہاں فلٹر کا استعمال کرنا

چروما میٹا ڈیٹا اور داستان کی بنیاد پر کوئیری بنانے کی حمایت کرتا ہے۔ where فلٹر ہمیں میٹا ڈیٹا کو فلٹر کرنے کے لئے اور where_document فلٹر ہمیں داستان کے مواد کو فلٹر کرنے کے لئے استعمال ہوتا ہے۔ نیچے، ہم فلٹر حالت کے شرائطی فائدے بیان کریں گے۔

میٹا ڈیٹا کے ذریعہ فلٹر کرنا

میٹا ڈیٹا کو فلٹر کرنے کے لئے، کوئیری کے لئے ایک ویرہ کارٹن فلٹر ڈکشنری فراہم کیا گیا ہونا چاہئے۔ ڈکشنری کا نیچا مواد ہونا چاہئے:

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

میٹا ڈیٹا کو فلٹر کرنے کی کمیونیات نیچے پر آتی ہے:

• $eq - برابر ہے (مش نوع، عدد، فلوٹ)
• $ne - برابر نہیں ہے (مش نوع، عدد، فلوٹ)
• $gt - سے زیادہ ہے (عدد، فلوٹ)
• $gte - سے زیادہ یا عدوى ہے (عدد، فلوٹ)
• $lt - سے کم ہے (عدد، فلوٹ)
• $lte - سے کم یا برابر ہے (عدد، فلوٹ)

$eq آپریٹر کا استعمال ویرہ کارٹن کو استعمال کرنے کے لئے ایک لازمی فلٹر ہے۔

{
    "metadata_field": "search_string"
}


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

داستانی مواد کا فلٹر کرنا

داستانی مواد کو فلٹر کرنے کے لئے، کوئیری کے لئے ایک where_document فلٹر ڈکشنری فراہم کرسکتے ہیں۔ ڈکشنری کا نیچے مواد ہونا چاہئے:

{
    "$contains": "search_string"
}

منطقی عملیات کا استعمال

آپ میں سےائی کر کے بھیاور اورْ کا استعمال کرکے متعدد فلٹر کو ملا کر استعمال کرسکتے ہیں۔

$and عملی‌ات کو باآینچہ بصورت کر سکتے ہیں جو فلٹر کی فہرست میں تمام فلٹر کو مطابقت رکھنے والے نتائج واپس کرے گا۔

{
    "$and": [
        {
            "metadata_field": {
                <مشغلہ>: <قیمت>
            }
        },
        {
            "metadata_field": {
                <مشغلہ>: <قیمت>
            }
        }
    ]
}

$or عملی‌ات کو باآینچہ بصورت کر سکتے ہیں جو فلٹر کی فہرست میں کسی بھی فلٹر کی مطابقت والے نتائج واپس کرے گا۔

{
    "$or": [
        {
            "metadata_field": {
                <مشغلہ>: <قیمت>
            }
        },
        {
            "metadata_field": {
                <مشغلہ>: <قیمت>
            }
        }
    ]
}

ڈیٹا کی تازی کرنا

کروما بھی اپ‌سرٹ عمل کو سپورٹ کرتا ہے، جو موجودہ ڈیٹا کو تازہ کرتا ہے اور اگر ڈیٹا موجود نہیں ہو تو نیا ڈیٹا شامل کرتا ہے۔

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

ڈیٹا کا حذف کرنا

کروما اسے .delete استعمال کرتا ہے تا کے کلیکشن سے ڈیٹا کو آئی ڈی کے ذریعے حذف کرسکے۔

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