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"

В приведенных ниже командах MemPalace мы передаем --backend milvus. Поскольку удаленный URI Milvus не настроен, MemPalace создает локальную базу данных Milvus Lite по адресу $PALACE_DIR/milvus.db.

Что касается аргумента MilvusClient, используемого бэкендом:

• Наиболее удобным вариантом является указание uri в виде локального пути, например ./milvus.db. В этом случае Milvus Lite автоматически используется для локального хранения данных.
• Для более крупного развертывания можно использовать сервер Milvus и установить в качестве URI его конечную точку, например http://localhost:19530.
• Чтобы использовать Zilliz Cloud, установите в качестве URI и токена публичный конечный пункт кластера и ключ API.

Загрузка корпуса документации Milvus

Репозиторий документации Milvus намного больше, чем требуется для данного примера. Воспользуйтесь функцией «разреженной проверки» Git, чтобы загрузить только каталог документации по анализаторам из ветки 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. Ограничение по комнате применяется через метаданные ящиков перед векторным поиском, поэтому ящики токенизаторов и языковых анализаторов исключаются из этого поиска.

Поиск точных терминов

CLI MemPalace сочетает семантическое сходство с сигналами 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 обеспечивает постоянное хранение векторных данных, разреженных массивов, текста и метаданных, лежащее в основе этой структуры.