MemPalace مع Milvus

MemPalace هي طبقة ذاكرة مخصصة لوكلاء البرمجة وسير عمل التطوير طويلة الأمد. وهي تنظم معارف المشروع إلى أجنحة وغرف وأدراج، ثم تجعل المحتوى الأصلي قابلاً للبحث عبر الجلسات.

في هذا البرنامج التعليمي، سنستخدم واجهة سطر الأوامر (CLI) لـ MemPalace لاستخراج مجموعة فرعية حقيقية من وثائق Milvus العامة وتخزينها في Milvus. يحتوي المجموع على وثائق حول أدوات التحليل وأدوات التقطيع وفلاتر الرموز. توفر هذه الصفحات المترابطة بشكل وثيق عوامل تشتيت كافية لجعل أمثلة الاسترجاع ذات مغزى.

يستخدم المثال Milvus Lite، لذا يعمل محليًّا دون الحاجة إلى Docker أو خادم قاعدة بيانات منفصل. يمكن أيضًا أن يشير نفس تكوين MemPalace إلى خادم Milvus أو Zilliz Cloud من أجل عمليات النشر المشتركة.

المتطلبات الأساسية

قم بتثبيت MemPalace مع تبعيات Milvus الاختيارية من PyPI. لا يحدد الأمر إصدارًا معينًا عن قصد، لذا فإن التثبيت الجديد سيحصل على أحدث إصدار متاح.

uv tool install "mempalace[milvus]"

تحتاج أيضًا إلى Git لتنزيل مجموعة الوثائق.

يستخدم هذا البرنامج التعليمي نموذج التضمين MiniLM المحلي الخاص بـ MemPalace، لذا فهو لا يتطلب مفتاح API لنموذج خارجي. قد يقوم أول أمر استخراج أو بحث بتنزيل نموذج تضمين ONNX صغير.

تكوين مساحة العمل

قم بإنشاء مساحة عمل تحتوي على دلائل منفصلة للوثائق وMemPalace:

mkdir -p mempalace-milvus-demo
cd mempalace-milvus-demo

export PALACE_DIR="$PWD/palace"
export DOCS_REPO="$PWD/milvus-docs"
export PROJECT_DIR="$PWD/milvus-analyzer-docs"
export MEMPALACE_EMBEDDING_MODEL="minilm"
export MEMPALACE_EMBEDDING_DEVICE="cpu"
export MEMPALACE_EMBEDDING_THREADS="2"

نقوم بتمرير --backend milvus إلى أوامر MemPalace أدناه. ونظرًا لعدم تكوين عنوان URI بعيد لـ Milvus، يقوم MemPalace بإنشاء قاعدة بيانات Milvus Lite محلية على $PALACE_DIR/milvus.db.

أما بالنسبة لحجة MilvusClient التي تستخدمها الخلفية:

• يُعد تعيين uri إلى مسار محلي، مثل ./milvus.db ، الخيار الأكثر ملاءمة. حيث يستخدم تلقائيًا Milvus Lite لتخزين البيانات محليًّا.
• بالنسبة للنشر الأكبر حجمًا، يمكنك استخدام خادم Milvus وتعيين URI إلى نقطة النهاية الخاصة به، مثل http://localhost:19530.
• لاستخدام Zilliz Cloud، قم بتعيين عنوان URI ورمز التوثيق (token) إلى نقطة النهاية العامة للمجموعة ومفتاح واجهة برمجة التطبيقات (API).

تنزيل مجموعة وثائق Milvus

مستودع وثائق Milvus أكبر بكثير مما يحتاجه هذا المثال. استخدم ميزة Git sparse checkout لتنزيل دليل وثائق Analyzer فقط من الفرع v3.0.x:

git clone \
  --depth 1 \
  --filter=blob:none \
  --sparse \
  --branch v3.0.x \
  https://github.com/milvus-io/milvus-docs.git \
  "$DOCS_REPO"

git -C "$DOCS_REPO" sparse-checkout set \
  site/en/userGuide/schema/analyzer

cp -R \
  "$DOCS_REPO/site/en/userGuide/schema/analyzer" \
  "$PROJECT_DIR"

في وقت كتابة هذا الدليل، يحتوي هذا الدليل على 31 صفحة Markdown. وتشمل هذه الصفحات أدلة عامة حول Analyzer وثلاث مجموعات من الصفحات ذات الصلة الوثيقة:

milvus-analyzer-docs/
├── analyzer/       # Built-in language analyzers
├── filter/         # Token filters
├── tokenizer/      # Tokenizers
└── *.md            # Analyzer overviews and selection guides

تأكد من عدد الصفحات المصدرية:

find "$PROJECT_DIR" -type f -name "*.md" | wc -l

مخرجات مرجعية:

31

قد يتغير العدد الدقيق مع تحديث فرع وثائق Milvus.

تحديد غرف MemPalace

يمكن لـ MemPalace اكتشاف الغرف أثناء عملية " mempalace init"، لكن تدفق التهيئة الخاص به يقوم أيضًا بتصنيف الكيانات الاستدلالي على مستوى المشروع بأكمله وكتابة النتائج المقبولة في سجل الكيانات. لا تُعد خطوة التصنيف هذه ضرورية لتعريف مجموعة الوثائق هذه، لذا نقدم التصنيف الصغير مباشرةً. أثناء الاستخراج، قد يستمر MemPalace في إرفاق بيانات وصفية للكيانات الاستدلالية الحتمية وإنشاء روابط داخلية؛ ولا تحدد هذه الارتباطات الغرفة التي تستقبل الملف أو تغير عمليات البحث على نطاق الغرفة الموضحة أدناه.

قم بإنشاء ملف « $PROJECT_DIR/mempalace.yaml » بالمحتوى التالي:

wing: milvus_analyzer_docs
rooms:
  - name: analyzer
    description: Built-in language analyzers and analyzer selection guides
    keywords:
      - analyzer
  - name: filter
    description: Token filters used in analyzer pipelines
    keywords:
      - filter
  - name: tokenizer
    description: Tokenizers and language identification
    keywords:
      - tokenizer
  - name: general
    description: Analyzer documentation that does not fit another room
    keywords: []

يمثل الجناح مجموعة الوثائق بأكملها. وتمثل الغرفة مجال موضوعًا. يقوم MemPalace بتوجيه الملف عن طريق التحقق أولاً من دليله، ثم اسم الملف، ثم الكلمات المفتاحية للغرفة في محتواه. على سبيل المثال، ينتقل الملف الموجود ضمن filter/ مباشرةً إلى غرفة filter.

ثم يتم تقسيم كل ملف إلى أجزاء نصية متداخلة. يصبح كل جزء درجًا يحتوي على نص Markdown الحرفي والبيانات الوصفية مثل wing و room و source_file و chunk_index وأرقام أسطر المصدر. تظل الغرف والأدراج بيانات وصفية منطقية داخل مجموعات Milvus في MemPalace؛ ولا ينشئ MemPalace مجموعة Milvus منفصلة لكل غرفة.

استخراج الوثائق إلى Milvus

استخراج المشروع باستخدام الخلفية البرمجية لـ Milvus:

mempalace \
  --palace "$PALACE_DIR" \
  mine "$PROJECT_DIR" \
  --backend milvus

المرجع الناتج من لقطة الوثائق التي تم التحقق من صحتها:

=======================================================
  Done.
  Files processed: 31
  Files skipped (already filed or other): 0
  Drawers filed: 473

  By room:
    filter               16 files
    analyzer              8 files
    tokenizer             7 files
=======================================================

يقرأ MemPalace لغة Markdown دون تلخيصها أو إعادة كتابتها، ويحسب التضمينات المحلية، ويخزن الأدراج في Milvus. في لقطة الوثائق التي تم اختبارها، أنتجت 31 ملفًا 473 درجًا.

تحقق من الغرف الناتجة وعدد الأدراج:

mempalace --palace "$PALACE_DIR" status --backend milvus

النتائج المرجعية:

=======================================================
  MemPalace Status -- 473 drawers
=======================================================

  WING: milvus_analyzer_docs
    ROOM: analyzer               212 drawers
    ROOM: filter                 156 drawers
    ROOM: tokenizer              105 drawers

=======================================================

قد يتغير العدد الدقيق للأدراج عند تغيير الوثائق الأصلية، لأن الصفحات الأطول تنتج مقاطع أكثر.

البحث الدلالي

استخدم mempalace search لاسترداد الوثائق حسب المعنى. لا يذكر السؤال التالي اسم ملف معين أو ميزة معينة في Analyzer:

mempalace \
  --palace "$PALACE_DIR" \
  search "How should I analyze documents that mix several languages?" \
  --backend milvus \
  --wing milvus_analyzer_docs \
  --results 3

النتائج المرجعية (قد تختلف النتائج):

Results for: "How should I analyze documents that mix several languages?"
Wing: milvus_analyzer_docs

[1] milvus_analyzer_docs / analyzer
    Source: multi-language-analyzers.md
    Match: cosine_sim=0.334 bm25=2.469
[2] milvus_analyzer_docs / analyzer
    Source: multi-language-analyzers.md
[3] milvus_analyzer_docs / analyzer
    Source: multi-language-analyzers.md

في التشغيل الذي تم التحقق من صحته، جاءت النتائج الثلاث جميعها من multi-language-analyzers.md ، على الرغم من أن المجموعة النصية احتوت أيضًا على صفحات خاصة بمحللات اللغات الفردية، وأدوات تقطيع الكلمات، والمرشحات.

البحث داخل غرفة

تُعد مرشحات الغرف مفيدة عندما تظهر المفاهيم ذات الصلة في جميع أنحاء المجموعة النصية. يبحث الاستعلام التالي في غرفة filter فقط عن طريقة لمطابقة المصطلحات المكافئة:

mempalace \
  --palace "$PALACE_DIR" \
  search "How can equivalent terms such as USA and United States match one another?" \
  --backend milvus \
  --wing milvus_analyzer_docs \
  --room filter \
  --results 3

مخرجات مرجعية (قد تختلف النتائج):

Results for: "How can equivalent terms such as USA and United States match one another?"
Wing: milvus_analyzer_docs
Room: filter

[1] milvus_analyzer_docs / filter
    Source: synonym-filter.md
    Match: cosine_sim=0.765 bm25=2.573
[2] milvus_analyzer_docs / filter
    Source: stemmer-filter.md
[3] milvus_analyzer_docs / filter
    Source: stop-filter.md

يجب أن تأتي النتيجة الأولى من synonym-filter.md. يتم تطبيق قيد الغرفة من خلال بيانات تعريف الأدراج قبل البحث المتجهي، لذا يتم استبعاد أدراج أدوات التقطيع وأدوات تحليل اللغة من هذا البحث.

البحث عن المصطلحات الدقيقة

تجمع واجهة MemPalace CLI بين التشابه الدلالي وإشارات BM25 عند ترتيب المرشحين للبحث المتجهي. وبالتالي، يمكن لأسماء التكوينات وأسماء الميزات الدقيقة تحسين الترتيب دون الحاجة إلى التبديل إلى وضع بحث CLI منفصل.

mempalace \
  --palace "$PALACE_DIR" \
  search "language_identifier tokenizer" \
  --backend milvus \
  --wing milvus_analyzer_docs \
  --room tokenizer \
  --results 3

إخراج مرجعي (قد تختلف الدرجات):

Results for: "language_identifier tokenizer"
Wing: milvus_analyzer_docs
Room: tokenizer

[1] milvus_analyzer_docs / tokenizer
    Source: language-identifier.md
    Match: cosine_sim=0.420 bm25=0.969
[2] milvus_analyzer_docs / tokenizer
    Source: language-identifier.md
[3] milvus_analyzer_docs / tokenizer
    Source: lindera-tokenizer.md

ينبغي أن تفضل النتائج language-identifier.md ، الذي يوثق أداة التقطيع language_identifier المستخدمة لاختيار أدوات التحليل بناءً على اللغة المكتشفة.

فحص مجموعات Milvus

يدير MemPalace مخطط Milvus الخاص به تلقائيًا. للتأكد مما تم تخزينه، احفظ البرنامج النصي التالي باسم inspect_milvus.py. يفتح هذا البرنامج النصي قاعدة بيانات Milvus Lite نفسها، ويفحص المجموعات، ويحسب عدد الأدراج حسب الغرفة:

import os
from collections import Counter

from pymilvus import MilvusClient


client = MilvusClient(uri=os.environ["MEMPALACE_MILVUS_LITE_PATH"])

for collection_name in sorted(client.list_collections()):
    stats = client.get_collection_stats(collection_name)
    schema = client.describe_collection(collection_name)
    fields = [field["name"] for field in schema["fields"]]
    print(f"{collection_name}: rows={stats['row_count']}, fields={fields}")

client.load_collection("mempalace_drawers")
rows = client.query(
    collection_name="mempalace_drawers",
    filter='metadata["wing"] == "milvus_analyzer_docs"',
    limit=2000,
    output_fields=["metadata"],
)
room_counts = Counter(row["metadata"]["room"] for row in rows)
print("Drawers by room:", dict(sorted(room_counts.items())))

قم بتشغيل البرنامج النصي باستخدام نفس مجموعة التبعيات الاختيارية التي تستخدمها واجهة سطر الأوامر (CLI):

export MEMPALACE_MILVUS_LITE_PATH="$PALACE_DIR/milvus.db"
uv run --with "mempalace[milvus]" inspect_milvus.py

إخراج مرجعي:

mempalace_closets: rows=74, fields=['id', 'document', 'metadata', 'vector', 'sparse']
mempalace_drawers: rows=473, fields=['id', 'document', 'metadata', 'vector', 'sparse']
Drawers by room: {'analyzer': 212, 'filter': 156, 'tokenizer': 105}

بالنسبة لمقتطف الوثائق الذي تم اختباره، احتوى الملف mempalace_drawers على 473 صفًا، واحتوى الملف mempalace_closets على 74 سجلًا للتنقل الداخلي. لا يلزم أن يتطابق عدد الخزائن مع عدد الأدراج. أظهرت بيانات تعريف الأدراج وجود 212 درجًا في analyzer ، و156 درجًا في filter ، و105 أدراج في tokenizer.

يتم تشغيل هذا الفحص في عملية جديدة ويعيد فتح قاعدة البيانات التي أنشأتها واجهة سطر الأوامر (CLI)، مما يؤكد أيضًا أن البيانات تبقى محفوظة عبر الأوامر المختلفة.

اختياري: استخدم خادم Milvus أو Zilliz Cloud

بالنسبة للنشر المشترك، قم بتعيين متغيرات بيئة اتصال Milvus قبل تشغيل نفس أوامر MemPalace CLI. اتركها غير معينة لاستخدام قاعدة بيانات Milvus Lite المحلية الموضحة أعلاه.

بالنسبة لخادم Milvus:

export MEMPALACE_MILVUS_URI="http://localhost:19530"
export MEMPALACE_MILVUS_DB_NAME="default"
export MEMPALACE_MILVUS_NAMESPACE="team-memory"

بالنسبة لـ Zilliz Cloud:

export MEMPALACE_MILVUS_URI="https://your-cluster.api.region.zillizcloud.com"
export MEMPALACE_MILVUS_TOKEN="your-api-key"
export MEMPALACE_MILVUS_DB_NAME="default"
export MEMPALACE_MILVUS_NAMESPACE="team-memory"

تم التحقق من صحة الأوامر من البداية إلى النهاية في هذا البرنامج التعليمي باستخدام Milvus Lite. تعد إعدادات الخادم والسحابة المذكورة أعلاه تكوينات نشر اختيارية ولم تكن مطلوبة للتحقق من الصحة محليًا.

الخلاصة

يوفر MemPalace للوكلاء طريقة منظمة للحفاظ على معرفة المشروع: حيث يفصل «الجناح» المجموعة النصية، وتوفر «الغرف» نطاقًا على مستوى الموضوع، وتحتفظ «الأدراج» بالنص المصدر الأصلي. في هذا المثال، تتحول 31 صفحة من وثائق Milvus المترابطة بشكل وثيق إلى مئات الأدراج القابلة للبحث بدلاً من بضعة سجلات مكتوبة بخط اليد. يوفر Milvus تخزينًا دائمًا للمتجهات، والبيانات المتفرقة، والنصوص، والبيانات الوصفية خلف تلك البنية.