MemPalace mit Milvus

MemPalace ist eine Speicherschicht für Programmieragenten und lang andauernde Entwicklungsworkflows. Es organisiert Projektwissen in Flügeln, Räumen und Schubladen und macht die ursprünglichen Inhalte dann über mehrere Sitzungen hinweg durchsuchbar.

In diesem Tutorial werden wir die MemPalace-CLI verwenden, um einen echten Teil der öffentlichen Milvus-Dokumentation zu extrahieren und in Milvus zu speichern. Der Korpus enthält Dokumentation zu Analysatoren, Tokenisierern und Tokenfiltern. Diese eng miteinander verbundenen Seiten bieten genügend Ablenkungselemente, um die Beispiele für die Suche aussagekräftig zu machen.

Das Beispiel verwendet Milvus Lite, sodass es lokal ohne Docker oder einen separaten Datenbankserver ausgeführt wird. Die gleiche MemPalace-Konfiguration kann bei gemeinsam genutzten Bereitstellungen auch auf einen Milvus-Server oder die Zilliz Cloud verweisen.

Voraussetzungen

Installieren Sie MemPalace mit den optionalen Milvus-Abhängigkeiten von PyPI. Der Befehl legt bewusst keine bestimmte Version fest, sodass bei einer Neuinstallation die aktuellste verfügbare Version verwendet wird.

uv tool install "mempalace[milvus]"

Außerdem benötigen Sie Git, um den Dokumentationskorpus herunterzuladen.

Dieses Tutorial verwendet das lokale MiniLM-Embedding-Modell von MemPalace, sodass kein externer Modell-API-Schlüssel erforderlich ist. Der erste Mining- oder Suchbefehl lädt möglicherweise ein kleines ONNX-Embedding-Modell herunter.

Konfigurieren Sie den Arbeitsbereich

Erstellen Sie einen Arbeitsbereich mit separaten Verzeichnissen für die Dokumentation und den „Palace“:

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"

Wir übergeben „ --backend milvus “ an die unten aufgeführten MemPalace-Befehle. Da keine Remote-Milvus-URI konfiguriert ist, erstellt MemPalace eine lokale Milvus-Lite-Datenbank unter „ $PALACE_DIR/milvus.db “.

Was das vom Backend verwendete Argument „ MilvusClient “ betrifft:

• Die bequemste Option ist es, ` uri ` auf einen lokalen Pfad wie ./milvus.db zu setzen. Dadurch werden die Daten automatisch lokal mit Milvus Lite gespeichert.
• Für eine größere Bereitstellung können Sie einen Milvus-Server verwenden und die URI auf dessen Endpunkt setzen, z. B. http://localhost:19530.
• Um die Zilliz Cloud zu nutzen, legen Sie die URI und das Token auf den öffentlichen Endpunkt und den API-Schlüssel des Clusters fest.

Laden Sie den Milvus-Dokumentationskorpus herunter

Das Milvus-Dokumentations-Repository ist wesentlich umfangreicher, als für dieses Beispiel erforderlich. Verwenden Sie „Git sparse checkout“, um nur das Verzeichnis mit der Analyzer-Dokumentation aus dem Zweig „ v3.0.x “ herunterzuladen:

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"

Zum Zeitpunkt der Erstellung dieses Artikels enthält dieses Verzeichnis 31 Markdown-Seiten. Dazu gehören allgemeine Analyzer-Anleitungen sowie drei Gruppen eng miteinander verbundener Seiten:

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

Überprüfen Sie die Anzahl der Quellseiten:

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

Referenzausgabe:

31

Die genaue Anzahl kann sich ändern, sobald der Milvus-Dokumentationszweig aktualisiert wird.

Definieren der MemPalace-Räume

MemPalace kann Räume während des „ mempalace init “ erkennen, doch sein Initialisierungsablauf führt auch eine projektweite heuristische Entitätsklassifizierung durch und schreibt die akzeptierten Ergebnisse in ein Entitätsregister. Dieser Klassifizierungsschritt ist für die Definition dieses Dokumentationskorpus nicht erforderlich, daher stellen wir die kleine Taxonomie direkt zur Verfügung. Während des Mining-Vorgangs fügt MemPalace möglicherweise weiterhin deterministische heuristische Entitätsmetadaten hinzu und erstellt interne Verknüpfungen; diese Zuordnungen haben keinen Einfluss darauf, welcher Raum eine Datei erhält, und ändern auch nichts an den unten aufgeführten raumbezogenen Suchvorgängen.

Erstellen Sie die Datei „ $PROJECT_DIR/mempalace.yaml “ mit folgendem Inhalt:

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

Der „Flügel“ (wing) repräsentiert den gesamten Dokumentationskorpus. Ein „Raum“ (room) repräsentiert einen Themenbereich. MemPalace leitet eine Datei weiter, indem es zunächst das Verzeichnis, dann den Dateinamen und schließlich die Raum-Schlüsselwörter im Inhalt überprüft. Eine Datei unter filter/ gelangt beispielsweise direkt in den Raum „ filter “.

Jede Datei wird anschließend in überlappende Textblöcke aufgeteilt. Jeder Block wird zu einer Schublade, die den wörtlichen Markdown-Text und Metadaten wie „ wing “, „ room “, „ source_file “, „ chunk_index “ sowie Quellzeilennummern enthält. Die Räume und Schubladen bleiben logische Metadaten innerhalb der Milvus-Sammlungen von MemPalace; MemPalace erstellt nicht für jeden Raum eine separate Milvus-Sammlung.

Die Dokumentation in Milvus einlesen

Das Projekt mit dem Milvus-Backend extrahieren:

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

Referenzausgabe aus dem validierten Dokumentations-Snapshot:

=======================================================
  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 liest das Markdown, ohne es zusammenzufassen oder umzuschreiben, berechnet lokale Einbettungen und speichert die „Drawers“ in Milvus. Bei dem getesteten Dokumentations-Snapshot ergaben 31 Dateien 473 „Drawers“.

Überprüfen Sie die resultierenden Räume und die Anzahl der Ordner:

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

Referenzausgabe:

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

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

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

Die genaue Anzahl der „Drawer“ kann sich ändern, wenn sich die übergeordnete Dokumentation ändert, da längere Seiten mehr „Chunks“ erzeugen.

Semantische Suche

Verwenden Sie „ mempalace search “, um Dokumentation nach Bedeutung abzurufen. Die folgende Frage nennt keine bestimmte Datei oder Analyzer-Funktion:

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

Referenzausgabe (Ergebnisse können variieren):

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

Im validierten Durchlauf stammten alle drei Ergebnisse von „ multi-language-analyzers.md “, obwohl der Korpus auch Seiten zu einzelnen Sprachanalysatoren, Tokenizern und Filtern enthielt.

Suche innerhalb eines Raums

Raumfilter sind nützlich, wenn verwandte Konzepte im gesamten Korpus vorkommen. Die folgende Abfrage durchsucht nur den Raum „ filter “ nach einer Möglichkeit, gleichwertige Begriffe abzugleichen:

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

Referenzausgabe (Ergebnisse können variieren):

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

Das oberste Ergebnis sollte von synonym-filter.md stammen. Die Raum-Einschränkung wird vor der Vektorsuche über die Metadaten der Schubladen angewendet, sodass Schubladen mit Tokenizern und Sprachanalysatoren von dieser Suche ausgeschlossen sind.

Suche nach exakten Begriffen

Die MemPalace-CLI kombiniert bei der Rangfolge der Kandidaten der Vektorsuche semantische Ähnlichkeit mit BM25-Signalen. Exakte Konfigurations- und Merkmalsnamen können daher die Rangfolge verbessern, ohne dass in einen separaten CLI-Suchmodus gewechselt werden muss.

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

Beispielausgabe (Ergebnisse können variieren):

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

Die Ergebnisse sollten „ language-identifier.md “ bevorzugen, das den „ language_identifier “-Tokenizer dokumentiert, der zur Auswahl von Analysatoren auf Basis der erkannten Sprache verwendet wird.

Überprüfen Sie die Milvus-Sammlungen

MemPalace verwaltet sein Milvus-Schema automatisch. Um zu überprüfen, was gespeichert wurde, speichern Sie das folgende Skript unter inspect_milvus.py. Es öffnet dieselbe Milvus-Lite-Datenbank, überprüft die Sammlungen und zählt die Schubladen pro Raum:

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

Führen Sie das Skript mit demselben optionalen Abhängigkeitssatz aus, der auch von der CLI verwendet wird:

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

Beispielausgabe:

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}

Für den getesteten Dokumentations-Snapshot enthielt mempalace_drawers 473 Zeilen und mempalace_closets 74 interne Navigationsdatensätze. Die Anzahl der Schränke und Schubladen muss nicht übereinstimmen. Die Metadaten zu den Schubladen zeigten 212 Schubladen in analyzer, 156 in filter und 105 in tokenizer.

Diese Überprüfung läuft in einem neuen Prozess ab und öffnet die von der CLI erstellte Datenbank erneut, was ebenfalls bestätigt, dass die Daten über verschiedene Befehle hinweg erhalten bleiben.

Optional: Milvus-Server oder Zilliz Cloud verwenden

Für eine gemeinsam genutzte Bereitstellung legen Sie die Milvus-Verbindungsumgebungsvariablen fest, bevor Sie dieselben MemPalace-CLI-Befehle ausführen. Lassen Sie sie ungesetzt, um die oben gezeigte lokale Milvus-Lite-Datenbank zu verwenden.

Für den Milvus-Server:

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

Für die 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"

Die End-to-End-Befehle in diesem Tutorial wurden mit Milvus Lite validiert. Die oben genannten Server- und Cloud-Einstellungen sind optionale Bereitstellungskonfigurationen und waren für die lokale Validierung nicht erforderlich.

Fazit

MemPalace bietet Agenten eine strukturierte Möglichkeit, Projektwissen zu bewahren: Ein „Flügel“ unterteilt den Korpus, „Räume“ bieten einen Themenbereich und „Schubladen“ bewahren den ursprünglichen Quelltext. In diesem Beispiel werden 31 eng miteinander verbundene Milvus-Dokumentationsseiten zu Hunderten von durchsuchbaren Schubladen statt zu einigen wenigen handschriftlichen Einträgen. Milvus stellt hinter dieser Struktur eine dauerhafte Speicherung von Vektoren, spärlichen Daten, Text und Metadaten bereit.