ArrowSpace

Busca vetorial espectral que aprimora a busca por vizinhos mais próximos com recursos do Laplaciano de grafos. Calcula um Laplaciano sobre o grafo de itens e usa o quociente de Rayleigh para produzir uma pontuação λτ (lambda-tau) por item, permitindo buscas que respeitam tanto a similaridade semântica quanto o papel estrutural.

Quando Usar Esta Habilidade

• A similaridade Cosseno ou L2 não capta a estrutura latente em seus embeddings.
• Você deseja recuperação baseada em grafos com consciência espectral.
• Você precisa caracterizar as propriedades espectrais de um espaço de embeddings.
• Você está construindo pipelines RAG onde o papel contextual é importante, além do conteúdo semântico.

Como Funciona

Passo 1: Instalar e importar

python3 -m pip install "arrowspace==0.28.1" numpy  # review/pin remaining dependencies in an isolated environment

from arrowspace import ArrowSpaceBuilder
import numpy as np

Passo 2: Preparar seus dados

Passe um array NumPy (N, d) de float64 com os vetores de embedding:

rng = np.random.default_rng(7)
items = rng.normal(size=(32, 8)).astype(np.float64)
items /= np.linalg.norm(items, axis=1, keepdims=True)

Passo 3: Configurar parâmetros do grafo

graph_params = {"eps": 0.5, "k": 6, "topk": 3, "p": 2.0, "sigma": None}
aspace, graph = ArrowSpaceBuilder().build(graph_params, items)

Passo 4: Consultar

lambdas = aspace.lambdas()           # array indexed by insertion order
sorted_res = aspace.lambdas_sorted()  # (score, index) pairs ascending

Estas são assinaturas espectrais por item, não autovalores do grafo ou pontuações de relevância dependentes da consulta. Ordená-las isoladamente não é recuperação de vizinhos mais próximos; não infira proximidade a uma consulta ou centralidade do grafo a partir de uma assinatura grande.

Exemplos

Exemplo 1: Recuperação espectral básica

# Reuse the normalized corpus and graph above; verify degenerate scores first.
if np.any(np.abs(aspace.lambdas()) < 1e-12):
    raise ValueError("Tune graph parameters for this corpus before searching")
query = items[0].copy()
hits = aspace.search(query, graph, tau=0.7, k=5)
# hits contains query-dependent (item_index, score) pairs, not a lambda-only ranking.

Exemplo 2: Comparar ranking espectral vs. cosseno

from sklearn.metrics.pairwise import cosine_similarity
cos_sim = cosine_similarity(items)
cosine_order = np.argsort(cos_sim[0])[::-1][:5]
spectral_order = [index for index, score in aspace.search(items[0], graph, tau=0.7, k=5)]
# For retrieval evaluation, exclude self-matches and use held-out relevance labels.

Melhores Práticas

• ✅ Normalize os embeddings para norma unitária antes de passá-los para o ArrowSpace.
• ✅ Trate os parâmetros do grafo como dependentes do corpus; inspecione pontuações desconectadas/degeneradas e ajuste usando um objetivo explicitamente selecionado.
• ✅ Escolha k em relação ao corpus real e às restrições da biblioteca; N/50 não é uma garantia universal de qualidade.
• ✅ Na API revisada 0.28, sigma=None usa o padrão dependente de eps; não é ajuste automático de distribuição.
• ✅ Pequenos corpora podem ilustrar a API, mas a qualidade da recuperação requer avaliação apropriada ao corpus; dez itens não é um limite de validade matemática.
• ❌ Não use para dados de streaming em tempo real (ArrowSpace é orientado a lotes).

Limitações

• Os exemplos da API visam a interface revisada 0.28; habilidade upstream imutável documenta o construtor, o valor de retorno do grafo e a busca ciente da consulta. Estes exemplos foram verificados contra a documentação fonte, não executados aqui.
• Ajuste os parâmetros do grafo e tau com base em evidências de recuperação retidas; as assinaturas λτ sozinhas não provam melhor recall ou importância estrutural.
• ArrowSpace é orientado a lotes e não foi projetado para indexação em tempo real de dados de streaming.

Armadilhas Comuns

• Problema: eps é muito pequeno, produzindo um grafo desconectado. Solução: Inspecione a conectividade do grafo e as pontuações degeneradas, então ajuste eps contra os dados reais; nenhuma fórmula baseada apenas na dimensão é garantida.

• Problema: k é muito grande, produzindo um grafo denso com características espectrais "lavadas". Solução: Mantenha k ≤ 25 para a maioria dos conjuntos de dados.

Habilidades Relacionadas

• vector-database-engineer — Expertise geral em banco de dados vetorial.
• embedding-strategies — Seleção de modelo de embedding e chunking.
• similarity-search-patterns — Padrões de implementação de busca semântica.
• hybrid-search-implementation — Busca semântica + por palavra-chave combinada.