MemPalace bersama Milvus

MemPalace adalah lapisan memori untuk agen pemrograman dan alur kerja pengembangan jangka panjang. MemPalace mengorganisir pengetahuan proyek ke dalam sayap, ruangan, dan laci, kemudian membuat konten aslinya dapat dicari di seluruh sesi.

Dalam tutorial ini, kita akan menggunakan MemPalace CLI untuk mengekstrak subset nyata dari dokumentasi Milvus yang tersedia untuk umum dan menyimpannya di Milvus. Korpus tersebut berisi dokumentasi mengenai penganalisis, tokenizer, dan filter token. Halaman-halaman yang saling terkait erat ini menyediakan cukup banyak pengalih perhatian sehingga contoh-contoh pencarian menjadi bermakna.

Contoh ini menggunakan Milvus Lite, sehingga dapat dijalankan secara lokal tanpa Docker atau server basis data terpisah. Konfigurasi MemPalace yang sama juga dapat diarahkan ke server Milvus atau Zilliz Cloud untuk penyebaran bersama.

Prasyarat

Instal MemPalace beserta dependensi Milvus opsionalnya dari PyPI. Perintah ini sengaja tidak menentukan versi tertentu, sehingga instalasi baru akan menggunakan rilis terbaru yang tersedia.

uv tool install "mempalace[milvus]"

Anda juga memerlukan Git untuk mengunduh korpus dokumentasi.

Tutorial ini menggunakan model embedding MiniLM lokal MemPalace, sehingga tidak memerlukan kunci API model eksternal. Perintah penambangan atau pencarian pertama mungkin akan mengunduh model embedding ONNX berukuran kecil.

Konfigurasikan ruang kerja

Buat ruang kerja dengan direktori terpisah untuk dokumentasi dan 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"

Kami meneruskan --backend milvus ke perintah MemPalace di bawah ini. Karena tidak ada URI Milvus jarak jauh yang dikonfigurasi, MemPalace membuat basis data Milvus Lite lokal di $PALACE_DIR/milvus.db.

Mengenai argumen ` MilvusClient ` yang digunakan oleh backend:

• Menetapkan uri ke jalur lokal, seperti ./milvus.db, adalah opsi yang paling praktis. Opsi ini secara otomatis menggunakan Milvus Lite untuk menyimpan data secara lokal.
• Untuk implementasi yang lebih besar, Anda dapat menggunakan server Milvus dan mengatur URI ke endpoint-nya, seperti http://localhost:19530.
• Untuk menggunakan Zilliz Cloud, atur URI dan token ke Public Endpoint dan kunci API kluster tersebut.

Unduh korpus dokumentasi Milvus

Repositori dokumentasi Milvus jauh lebih besar daripada yang dibutuhkan dalam contoh ini. Gunakan Git sparse checkout untuk mengunduh hanya direktori dokumentasi Analyzer dari cabang 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"

Pada saat penulisan, direktori ini berisi 31 halaman Markdown. Halaman-halaman tersebut mencakup panduan umum Analyzer dan tiga kelompok halaman yang saling terkait erat:

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

Konfirmasi jumlah halaman sumber:

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

Hasil referensi:

31

Jumlah pastinya dapat berubah seiring pembaruan cabang dokumentasi Milvus.

Tentukan ruang MemPalace

MemPalace dapat mendeteksi ruang selama proses inisialisasi ( mempalace init), tetapi alur inisialisasinya juga melakukan klasifikasi entitas heuristik secara menyeluruh di seluruh proyek dan mencatat hasil yang diterima ke dalam registri entitas. Langkah klasifikasi tersebut tidak diperlukan untuk mendefinisikan korpus dokumentasi ini, sehingga kami menyediakan taksonomi kecil secara langsung. Selama penambangan, MemPalace mungkin masih melampirkan metadata entitas heuristik deterministik dan membangun tautan lorong internal; asosiasi tersebut tidak menentukan ruang mana yang menerima file atau mengubah pencarian dalam lingkup ruang di bawah ini.

Buat berkas ` $PROJECT_DIR/mempalace.yaml ` dengan isi sebagai berikut:

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: []

"The wing" mewakili keseluruhan korpus dokumentasi. Sebuah "room" mewakili bidang topik. MemPalace mengarahkan sebuah berkas dengan memeriksa direktori berkas tersebut terlebih dahulu, kemudian nama berkasnya, lalu kata kunci "room" dalam isinya. Sebuah berkas di bawah filter/, misalnya, langsung masuk ke " filter ".

Setiap berkas kemudian dibagi menjadi potongan teks yang tumpang tindih. Setiap potongan menjadi laci yang berisi Markdown secara verbatim dan metadata seperti wing, room, source_file, chunk_index, serta nomor baris sumber. Ruang dan laci tetap menjadi metadata logis di dalam koleksi Milvus MemPalace; MemPalace tidak membuat koleksi Milvus terpisah untuk setiap ruang.

Ekstrak dokumentasi ke dalam Milvus

Ekstraksi proyek dengan backend Milvus:

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

Referensi keluaran dari snapshot dokumentasi yang telah diverifikasi:

=======================================================
  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 membaca Markdown tanpa meringkas atau menulis ulang, menghitung embedding lokal, dan menyimpan laci di Milvus. Pada snapshot dokumentasi yang diuji, 31 berkas menghasilkan 473 laci.

Periksa ruangan yang dihasilkan dan jumlah laci:

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

Hasil referensi:

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

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

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

Jumlah laci yang tepat dapat berubah ketika dokumentasi hulu berubah karena halaman yang lebih panjang menghasilkan lebih banyak bagian.

Pencarian semantik

Gunakan mempalace search untuk mengambil dokumentasi berdasarkan makna. Pertanyaan berikut ini tidak menyebutkan nama file atau fitur Analyzer tertentu:

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

Hasil referensi (skor mungkin bervariasi):

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

Dalam eksekusi yang telah divalidasi, ketiga hasil tersebut berasal dari multi-language-analyzers.md, meskipun korpus juga berisi halaman untuk masing-masing penganalisis bahasa, tokenizer, dan filter.

Pencarian di dalam ruang

Filter ruang berguna ketika konsep-konsep terkait muncul di seluruh korpus. Kueri berikut hanya mencari di ruang " filter " untuk cara mencocokkan istilah-istilah yang setara:

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

Output referensi (skor dapat bervariasi):

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

Hasil teratas seharusnya berasal dari synonym-filter.md. Batasan ruang diterapkan melalui metadata laci sebelum pencarian vektor, sehingga laci tokenizer dan penganalisis bahasa dikecualikan dari pencarian ini.

Mencari istilah yang persis sama

CLI MemPalace menggabungkan kesamaan semantik dengan sinyal BM25 saat menentukan peringkat kandidat pencarian vektor. Oleh karena itu, nama konfigurasi dan nama fitur yang persis sama dapat meningkatkan peringkat tanpa perlu beralih ke mode pencarian CLI terpisah.

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

Hasil referensi (skor mungkin bervariasi):

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

Hasilnya seharusnya mengutamakan language-identifier.md, yang mendokumentasikan tokenizer language_identifier yang digunakan untuk memilih penganalisis berdasarkan bahasa yang terdeteksi.

Periksa koleksi Milvus

MemPalace mengelola skema Milvus-nya secara otomatis. Untuk memastikan apa yang telah disimpan, simpan skrip berikut sebagai inspect_milvus.py. Skrip ini membuka basis data Milvus Lite yang sama, memeriksa koleksi, dan menghitung laci berdasarkan ruangan:

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())))

Jalankan skrip dengan set dependensi opsional yang sama seperti yang digunakan oleh CLI:

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

Output referensi:

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}

Untuk cuplikan dokumentasi yang diuji, mempalace_drawers berisi 473 baris dan mempalace_closets berisi 74 catatan navigasi internal. Jumlah lemari dan laci tidak perlu sama. Metadata laci menunjukkan 212 laci di analyzer, 156 di filter, dan 105 di tokenizer.

Pemeriksaan ini dijalankan dalam proses baru dan membuka kembali basis data yang dibuat oleh CLI, yang juga memastikan bahwa data tetap tersimpan di seluruh perintah.

Opsional: gunakan server Milvus atau Zilliz Cloud

Untuk penyebaran bersama, atur variabel lingkungan koneksi Milvus sebelum menjalankan perintah CLI MemPalace yang sama. Biarkan variabel tersebut tidak diatur untuk menggunakan basis data Milvus Lite lokal yang ditunjukkan di atas.

Untuk server Milvus:

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

Untuk 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"

Perintah end-to-end dalam tutorial ini telah divalidasi dengan Milvus Lite. Pengaturan server dan cloud di atas merupakan konfigurasi penerapan opsional dan tidak diperlukan untuk validasi lokal.

Kesimpulan

MemPalace memberikan cara terstruktur bagi agen untuk melestarikan pengetahuan proyek: sebuah "sayap" memisahkan korpus, "ruang" menyediakan cakupan tingkat topik, dan "laci" menyimpan teks sumber asli. Dalam contoh ini, 31 halaman dokumentasi Milvus yang saling terkait erat diubah menjadi ratusan laci yang dapat dicari, bukan sekadar beberapa catatan yang ditulis tangan. Milvus menyediakan penyimpanan vektor, data terpisah, teks, dan metadata yang persisten di balik struktur tersebut.