MemPalace com Milvus

O MemPalace é uma camada de memória destinada a agentes de programação e fluxos de trabalho de desenvolvimento de longa duração. Organiza o conhecimento do projeto em alas, salas e gavetas, tornando o conteúdo original pesquisável entre sessões.

Neste tutorial, iremos utilizar a CLI do MemPalace para extrair um subconjunto real da documentação pública do Milvus e armazená-lo no Milvus. O corpus contém documentação sobre analisadores, tokenizadores e filtros de tokens. Estas páginas, intimamente relacionadas, fornecem distrações suficientes para tornar os exemplos de recuperação significativos.

O exemplo utiliza o Milvus Lite, pelo que é executado localmente sem necessidade do Docker ou de um servidor de base de dados separado. A mesma configuração do MemPalace também pode apontar para o servidor Milvus ou para a Zilliz Cloud, no caso de implementações partilhadas.

Pré-requisitos

Instale o MemPalace com as suas dependências opcionais do Milvus a partir do PyPI. O comando não especifica intencionalmente uma versão, pelo que uma nova instalação irá utilizar a versão mais recente disponível.

uv tool install "mempalace[milvus]"

Também é necessário o Git para descarregar o corpus de documentação.

Este tutorial utiliza o modelo de incorporação MiniLM local do MemPalace, pelo que não requer uma chave API de modelo externo. O primeiro comando de mineração ou pesquisa poderá descarregar um pequeno modelo de incorporação ONNX.

Configurar o espaço de trabalho

Crie um espaço de trabalho com diretórios separados para a documentação e para o 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"

Passamos --backend milvus aos comandos do MemPalace abaixo. Como não está configurado nenhum URI remoto do Milvus, o MemPalace cria uma base de dados local do Milvus Lite em $PALACE_DIR/milvus.db.

Quanto ao argumento de MilvusClient utilizado pelo backend:

• Definir o uri para um caminho local, como ./milvus.db, é a opção mais conveniente. Este utiliza automaticamente o Milvus Lite para armazenar dados localmente.
• Para uma implementação de maior dimensão, pode utilizar um servidor Milvus e definir o URI para o seu ponto de extremidade, como http://localhost:19530.
• Para utilizar o Zilliz Cloud, defina o URI e o token para o ponto de extremidade público e a chave API do cluster.

Descarregue o conjunto de documentação do Milvus

O repositório de documentação do Milvus é muito maior do que o necessário para este exemplo. Utilize o «sparse checkout» do Git para descarregar apenas o diretório de documentação do Analyzer a partir do ramo 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"

À data da redação deste artigo, este diretório contém 31 páginas em Markdown. Estas incluem guias gerais do Analyzer e três grupos de páginas intimamente relacionadas:

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

Confirme o número de páginas de origem:

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

Saída de referência:

31

A contagem exata pode variar à medida que o ramo da documentação do Milvus for atualizado.

Definir as salas do MemPalace

O MemPalace consegue detetar salas durante a « mempalace init », mas o seu fluxo de inicialização também realiza uma classificação heurística de entidades a nível do projeto e grava os resultados aceites num registo de entidades. Essa etapa de classificação não é necessária para definir este corpus de documentação, pelo que fornecemos diretamente a pequena taxonomia. Durante a mineração, o MemPalace pode ainda associar metadados heurísticos determinísticos às entidades e criar ligações internas; essas associações não determinam qual a sala que recebe um ficheiro nem alteram as pesquisas no âmbito da sala apresentadas abaixo.

Crie um ficheiro « $PROJECT_DIR/mempalace.yaml » com o seguinte conteúdo:

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

A ala representa todo o corpus de documentação. Uma sala representa uma área temática. O MemPalace encaminha um ficheiro verificando primeiro o seu diretório, depois o nome do ficheiro e, por fim, as palavras-chave da sala presentes no seu conteúdo. Um ficheiro localizado em filter/, por exemplo, vai diretamente para a sala « filter ».

Cada ficheiro é, em seguida, dividido em blocos de texto sobrepostos. Cada bloco torna-se uma gaveta que contém o Markdown literal e metadados como wing, room, source_file, chunk_index e os números das linhas de código de origem. As salas e as gavetas permanecem como metadados lógicos dentro das coleções Milvus do MemPalace; o MemPalace não cria uma coleção Milvus separada para cada sala.

Extrair a documentação para o Milvus

Extrair o projeto com o backend do Milvus:

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

Referência à saída do instantâneo validado da documentação:

=======================================================
  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
=======================================================

O MemPalace lê o Markdown sem o resumir nem reescrever, calcula as incorporações locais e armazena as pastas no Milvus. No instantâneo da documentação testado, 31 ficheiros produziram 473 pastas.

Verifique as salas resultantes e o número de «drawers»:

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

Saída de referência:

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

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

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

A contagem exata de «drawers» pode variar quando a documentação de origem é alterada, uma vez que páginas mais longas produzem mais fragmentos.

Pesquisa semântica

Utilize mempalace search para recuperar documentação com base no significado. A seguinte pergunta não menciona um ficheiro específico nem uma funcionalidade do Analyzer:

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

Resultado de referência (as pontuações podem variar):

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

Na execução validada, os três resultados provieram de multi-language-analyzers.md, apesar de o corpus também conter páginas relativas a analisadores de linguagem, tokenizadores e filtros individuais.

Pesquisa dentro de uma sala

Os filtros de sala são úteis quando conceitos relacionados aparecem ao longo do corpus. A consulta seguinte pesquisa apenas na sala « filter » uma forma de fazer com que termos equivalentes correspondam:

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

Resultado de referência (as pontuações podem variar):

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

O resultado principal deve provir de synonym-filter.md. A restrição da sala é aplicada através dos metadados da gaveta antes da pesquisa vetorial, pelo que as gavetas do tokenizador e do analisador de língua são excluídas desta pesquisa.

Pesquisa de termos exatos

A CLI do MemPalace combina a semelhança semântica com sinais BM25 ao classificar os candidatos da pesquisa vetorial. Nomes exatos de configurações e de funcionalidades podem, portanto, melhorar a classificação sem necessidade de mudar para um modo de pesquisa separado na CLI.

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

Saída de referência (as pontuações podem variar):

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

Os resultados devem favorecer language-identifier.md, que documenta o tokenizador language_identifier utilizado para selecionar analisadores com base no idioma detetado.

Inspecionar as coleções do Milvus

O MemPalace gere o seu esquema Milvus automaticamente. Para confirmar o que foi armazenado, guarde o seguinte script como inspect_milvus.py. Este abre a mesma base de dados Milvus Lite, inspeciona as coleções e conta as gavetas por divisão:

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

Execute o script com o mesmo conjunto de dependências opcionais utilizado pela CLI:

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

Saída de referência:

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}

Para o instantâneo de documentação testado, mempalace_drawers continha 473 linhas e mempalace_closets continha 74 registos de navegação interna. As contagens de roupeiros e gavetas não precisam de coincidir. Os metadados das gavetas mostravam 212 gavetas em analyzer, 156 em filter e 105 em tokenizer.

Esta inspeção é executada num novo processo e reabre a base de dados criada pela CLI, o que também confirma que os dados persistem entre comandos.

Opcional: utilizar o servidor Milvus ou a Zilliz Cloud

Para uma implementação partilhada, defina as variáveis de ambiente de ligação ao Milvus antes de executar os mesmos comandos da CLI do MemPalace. Deixe-as sem definição para utilizar a base de dados local do Milvus Lite apresentada acima.

Para o servidor Milvus:

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

Para a 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"

Os comandos de ponta a ponta deste tutorial foram validados com o Milvus Lite. As definições de servidor e nuvem acima são configurações de implementação opcionais e não foram necessárias para a validação local.

Conclusão

O MemPalace oferece aos agentes uma forma estruturada de preservar o conhecimento do projeto: uma ala separa o corpus, as salas proporcionam um âmbito ao nível do tópico e as gavetas retêm o texto original da fonte. Neste exemplo, 31 páginas de documentação do Milvus intimamente relacionadas transformam-se em centenas de gavetas pesquisáveis, em vez de alguns registos escritos à mão. O Milvus fornece armazenamento persistente de vetores, dados esparsos, texto e metadados por trás dessa estrutura.