پائیتھون کروماڈب ویکٹر ڈیٹابیس ڈویلپمنٹ گائیڈ

پایتھان کروما ڈی بی تفصیلی ترتیبی گائیڈ

تنصیب

pip install chromadb

چروما ڈی بی ڈیٹا کو مستقل بنانا

import chromadb

آپ کو کروما ڈیٹا بیس فائل کے لیے ذخیرہ کرنے کا راستہ تعین کرسکتے ہیں۔ اگر ڈیٹا موجود ہوتا ہے تو پروگرام شروع ہونے پر ڈیٹا بیس فائل خود بخود لوڈ ہوجائے گا۔

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

راستہ پیرامیٹر چروما ڈی بی فائل کا راستہ ہے۔

نوٹ: چروما ڈیٹا بیس کے لیے ایک بار کلائنٹ آبجکٹ بنانا کافی ہے۔ ایک ہی راستے میں متعدد کلائنٹس کو لوڈ اور سیو کرنا غیر متوقع رویہ میں موجب ہوسکتا ہے، جس میں ڈیٹا حذف ہوسکتا ہے۔ عموماً، ایک ہی کروما کلائنٹ کو اطلاق کیا جانا چاہئے۔

کلائنٹ آبجیکٹ کے کچھ عام استعمال ہونے والے فعل:

client.reset()  # ڈیٹا بیس کو صاف کرتا ہے اور مکمل بحال کرتا ہے

کلیکشن آپریشنز

چروما ڈی بی ویکٹر ڈیٹا کی مینجمنٹ کے لیے collection کا استعمال کرتا ہے جو MYSQL میں جدولوں کی طرح ہوسکتے ہیں۔

کلیکشنز بنانا، دیکھنا، اور حذف کرنا

چروما کلیکشن نام کے لینک میں کل استعمال ہوتا ہے، لہذا اس میں کچھ نامکمل پابندیاں ہوتی ہیں:

• نام کی لمبائی 3 سے 63 حروف کے درمیان ہونی چاہئے۔
• نام کو آغاز اور ختم کرنا چاہئے ایک چھوٹا لیٹر یا نمبر سے، اور درمیان میں دو نقطوں، ہائفنز اور انڈر اسکورس ہوسکتے ہیں۔
• نام میں دو نقطے نہیں ہوسکتے ہیں۔
• نام ایک درست آئی پی پتہ نہیں ہوسکتا۔

کلیکشن بنانے کے لیے، آپ کو کلیکشن نام اور ایک اختیاری ویکٹر حساب کرنے والی فنکشن (جسے تھوڑ سا ingimating فنکشن بھی کہتے ہیں) تعین کرنا ہوگا۔ اگر ایک ویکٹر حساب کرنے کا فنکشن فراہم کیا گیا ہے، تو ہر بار جب کلیکشن تک رسائی حاصل ہوتی ہے تو یہ بھی فراہم کرنا لازمی ہے۔

نوٹ: ویکٹر حساب کرنے والی فنکشن (نشانی بنانے والی فنکشن) کا مقصد ٹیکسٹ ویکٹر حاصل کرنا ہوتا ہے۔

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

ویکٹر حساب کرنے والی فنکشن ان پٹ کے طور پر لینے کے ساتھ، اسے واپس کرنے والے کے لیے، اور استعمال کرنے کے لیے .delete_collection یہ بھی استعمال کرنے والے کے لیے، .get_or_create_collectionاور ایک کالیکشن کو حوالہ دینے کے لیے استعمال کرنے والے کے لیے استعمال کیا جاسکتا ہے۔

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

دوسرے عام استعمال ہونے والے کلیکشن آپریشنز:

collection.peek() # کلیکشن کے پہلے 10 ڈیٹا کی فہرست واپس کرتا ہے
collection.count() # کلیکشن میں ڈیٹا کی کل تعداد واپس کرتی ہے
collection.modify(name="new_name") # کلیکشن کا نام تبدیل کرتا ہے

ویکٹر دوری حساب کرنے کی ترکیب کا تعین کرنا

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

نوٹ: ویکٹر ڈیٹا نے نشانی بٹوین ویکٹرس کی فضائی دور پیمائش کرکے ویکٹر کے درمیان مشابہت کو ظاہر کرتا ہے۔ جتنا قریب دوری ہوتی ہے ویکٹرس کی مشابہت زیادہ ہوتی ہے، اور الٹا بھی۔

collection = client.create_collection(
        name="collection_name",
        metadata={"hnsw:space": "cosine"} # l2 ایک اختیاری حساب کرنے والی ترکیب ہے
    )

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

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

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

بغیر دستاویز سمیت دستاویز ویکٹرز مخصوص نہیں کرتے ہوئے ڈیٹا شامل کریں:

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

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

ہر دستاویز کو ایک یکتا شناکت (ids) کے ساتھ ہونا ضروری ہے۔ ایک ہی شناکت کو دوبارہ شامل کرنے سے ابتدائی قیمت کو محفوظ کرنا ممکن ہوگا۔ اختیاری طور پر، آپ ہر دستاویز کے لئے اضافی معلومات کو محفوظ کرنے کے لئے ایک فہرست میں میٹا ڈیٹا کی ڈکشنریاں (metadatas) مہیا کرسکتے ہیں جو سوالات کے دوران ڈیٹا کی فلٹرنگ کے لئے استعمال ہوسکتی ہیں۔

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

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

اگر فراہم کردہ ویکٹر ڈیٹا کی محدودیت (لمبائی) کلیکشن کی محدودیتوں سے مُطابقت نہیں رکھتی، تو ایک استثناء واقع ہوگا۔

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

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

نوٹ: ویکٹر ڈیٹا بیس کا بنیادی فنکشن بنامتناسب مماثلت تلاش پر مشتمل ہے۔ موصولہ سائز کی کمی اور کارروائی کی بہتری کے لئے، ہم سائز کی کمی کے پاس منسلک ساتھ ساتھ ویکٹر ڈیٹا اور ضروری فلٹرنگ خصوصیاتوں کو ویکٹر ڈیٹا بیس میں محفوظ کر سکتے ہیں۔ دیگر ڈیٹا، مثلاً مضامین کو MYSQL جیسے ڈیٹا بیس میں محفوظ کیا جا سکتا ہے، جب تک کے وہ IDs کے ذریعے منسلک ہوں۔

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

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

آپ کو query_embeddings (ویکٹر ڈیٹا) کا استعمال کرتے ہوئے سوال کر سکتے ہیں۔

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

collection.query(
    query_embeddings=[[11.1, 12.1, 13.1],[1.1, 2.3, 3.2], ...],
    n_results=10,
    where={"metadata_field": "is_equal_to_this"},
    where_document={"$contains":"search_string"}
)

اس سوال سے n_results نتائج واپس کئے جائیں گے جو ہر سوال ویکٹر (query_embedding) کے سب سے بہترین مواد کے ساتھ مماثل ہوں۔ ایک اختیاری where فلٹر ڈکشنری فراہم کی جا سکتی ہے تاکہ ہر دستاویز سے منسلک میٹا ڈیٹا کے بنیاد پر نتائج کو فلٹر کیا جا سکے۔ علاوہ ازیں، ایک اختیاری where_document فلٹر ڈکشنری بھی فراہم کی جا سکتی ہے تاکہ دستاویز کی مواد کے بنیاد پر نتائج کو فلٹر کیا جا سکے۔

اگر فراہم کیے گئے query_embeddings کا کچھ بھی مطابقت نہیں کرتا ہے تو ایک استثناء واقع ہو جائے گا۔ موجودہ سمتی بُعد سے مطابقت سے محفوظ کرنے کے لئے، برابر ٹیکسٹ امبیڈنگ ماڈل استعمال کریں تاکہ ویکٹر بُعد کو یکسان بنایا جا سکے۔

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

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

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

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

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

واپسی فیلڈز کی مخصوص کرنا

جب get یا query کا استعمال ہو رہا ہو تو آپ include پیرامیٹر کا استعمال کرکے واپسی دی ہوئی ڈیٹا کی وضاحت کرنے کے لئے استعمال کرسکتے ہیں- embeddings, documents, یا metadatas، اور سوالات کے لئے دوری ڈیٹا واپس کیا جانا چاہئے۔ چروما، ڈستانس ڈیٹا کو واپس لائے جاتا ہے۔ ڈیفالٹ طور پر، چروما دستاویزات اور میٹا ڈیٹا واپس کرتا ہے، اور سوالات کے لئے ڈسٹینس ڈیٹا واپس کرتا ہے، جبکہ "ids" ہمیشہ واپس کرتا ہے۔ آپ طریقہ کار کے include پیرامیٹر میں فیلڈوں کو واپس کرانے کے لیے ایک فیلڈ ناموں کے ارے پاس کرکے واپس کرنے کا متاثر کرسکتے ہیں۔

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

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

استعمال کرنے کے فلٹرز

چروما مٹا ڈیٹا اور دستاویز کی بنیاد پر سوالات کو فلٹر کرنے کا حمایت کرتا ہے۔ فلٹر فلٹر کرنے کے لئے استعمال ہوتا ہے، اور where_document فلٹر دستاویز مواد کو فلٹر کرنے کے لئے استعمال ہوتا ہے، اور درج ذیل وضاحت کرتا ہے کہ کیسے فلٹر مواد کی حالت کو لکھا گیا ہے۔

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

میٹا ڈیٹا کو فلٹر کرنے کے لئے، آپ کو سوالات کے لئے ایک where فلٹر ڈکشنری فراہم کرنا ہوگا۔ اس ڈکشنری میں مندرجہ ذیل ساخت ہونی چاہئے:

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

میٹا ڈیٹا فلٹر کرنے کیلئے منفی کے لئے مندرجہ ذیل عمل کریں:

• $eq - برابر ہے (سٹرنگ، عدد صحیح، فلوٹ)
• $ne - برابر نہیں ہے (سٹرنگ، عدد صحیح، فلوٹ)
• $gt - سے بڑی ہے (عدد صحیح، فلوٹ)
• $gte - سے بڑی یا برابر ہے (عدد صحیح، فلوٹ)
• $lt - سے چھوٹی ہے (عدد صحیح، فلوٹ)
• $lte - سے چھوٹا یا برابر ہے (عدد صحیح، فلوٹ)

$eq عمل استعمال کرنے کا برابر ہے where فلٹر کرنے کے سے مترادف ہوتا ہے۔

{
    "metadata_field": "search_string"
}

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

دستاویز مواد کی صفحیات

ڈاکومنٹ کے مواد کو فلٹر کرنے کے لئےآپ کو سوال کرنے کے لئے ایک where_document فلٹر ڈکشنری فراہم کرنا ہوگا۔ اس ڈکشنری میں مندرجہ زیل ساخت ہونی چاہئے:

{
    "$contains": "search_string"
}

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

آپ مختلف فلٹرز کو مدد سے ملا سکتے ہیں جیسے کہ $and اور $or منطقی عملیات کے ساتھ۔

$and عملیات نتائج وہ ڈیٹا واپس کرے گی جو فلٹرز کی فہرست میں شامل ہوں۔

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

$or عملیات نتائج واپس کرے گی جو فلٹر کی شرائط میں سے کوئی ایک مطمئن کرتی ہو۔

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

کلیکشن میں ڈیٹا کو تازہ کرنا

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

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

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

اگر فراہم شدہ ویکٹر ڈیٹا کلیکشن کے مختلف وسعت کے ہوں تو ایک استثناء واقع ہوگا۔

کروما بھی اپ سرٹ عمل کی حمایت کرتا ہے جو موجودہ ڈیٹا کو اپ ڈیٹ کرتا ہے اور اگر وہ موجود نہیں ہو تو نیا ڈیٹا داخل کرتا ہے۔

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 کا استعمال کر کے کسی بھی کلیکشن سے ڈیٹا کو id کے ذریعے ہٹانا۔ ہر ڈیٹا کے ساتھ جڑی ہوئی ویکٹر، دستاویزات، اور میٹا ڈیٹا بھی حذف کر دی جائے گی۔

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

.delete بھی where فلٹر کی حمایت کرتا ہے۔ اگر کوئی id فراہم نہیں کیا گیا ہو تو وہ تمام اشیاء کو کلیکشن سے حذف کر دیتا ہے جو where فلٹر کو مطمئن کرتی ہو۔