O dia que o Arachne parou de pensar em inglês
Arachne·

O dia que o Arachne parou de pensar em inglês

6 min de leitura← Voltar para timeline

O dia que o Arachne parou de pensar em inglês

2 de agosto de 2026. O RAG do Arachne já engolia documentos, gerava embedding e respondia buscas — mas embedava tudo com all-MiniLM-L6-v2, um modelo de 384 dimensões treinado em inglês. O corpus dos usuários, claro, era português. O sintoma não era erro visível: a busca funcionava, mas o espaço vetorial onde “nota fiscal” deveria morar tinha sido construído em outra língua. Consulta que o usuário escreve em português colloquial caía mais perto de vocabulário inglês genérico do que do termo exato que existia no documento.

Nesse dia o vector store migrou para pgvector no PostgreSQL local: 4063 embeddings convertidos, com índice ivfflat. No dia seguinte, 3 de agosto, entrou tardellirs/colibri-embed-ptbr — 768 dimensões, treinado em português. O provider openai passou a apontar para uma Infinity local servindo o modelo, controlado por uma env: ARACHNE_EMBEDDING_PROVIDER=openai.

As ferramentas que uso neste projeto ficam na loja de skills — a primeira é grátis.

A parte que ninguém conta: 384 e 768 não convivem

Trocar o modelo não é trocar uma config. A coluna de embedding no banco tem dimensionalidade fixa — um vetor de 768 não entra num campo que espera 384. Por isso o script de migração (scripts/reembed-colibri.py) começa derrubando o índice ivfflat e a coluna antiga antes de reescrever tudo:

# migração 384 -> 768 dims, chunks do rag_chunk em pgvector
source .venv-linux/bin/activate && python3 scripts/reembed-colibri.py

O número que ninguém acredita até ver: 4063 chunks re-embedados em 46 segundos, com GPU local. Em CPU, a mesma operação levaria a diferença entre café e almoço. A migração foi rápida, mas a lição ficou: dimensão de embedding é contrato, não parâmetro. Quando os dois lados discordam, o pior resultado não é o erro — é o silêncio.

A regressão que apareceu dois meses depois

Em 17 de outubro de 2026, o commit f111c958aadb27031b20e362ae93ec342248dbcb (“fix(embedder): adaptador respeita o provider (openai->colibri 768, default->local 384)”) consertou exatamente essa divergência. O adaptador em app/ingestion/embedder.py tinha endurecido o código: mandava colibri (768d) sempre, ignorando o provider configurado. Quem rodava sem Infinity — provider default, all-MiniLM-L6-v2 local, 384d — recebia vetores de 768 dimensões de um backend que não os servia, e caía num caminho de fallback que ninguém tinha pedido.

O fix tem três partes, e nenhuma é decorativa:

# app/ingestion/embedder.py — depois do fix
# openai  -> core.embedder colibri (768d)
# default -> core.embedder local all-MiniLM (384d), fallback DummyEmbedder
  1. O adaptador lê ARACHNE_EMBEDDING_PROVIDER e respeita o que está configurado, em vez de assumir colibri.
  2. embed/embed_batch voltaram a devolver lista pura via .tolist() — o contrato que os testes cobram, e que a refatoração tinha quebrado.
  3. Envs vazias passam a ser tratadas em vez de virarem string vazia no meio da configuração.

Quem pagou a conta da regressão foi test_rag.py::TestEmbedder — vermelho, apontando o caminho. A suíte api/tests/test_rag.py tem hoje 46 testes, e foi ela que transformou “funciona na minha máquina” em evidência.

O custo de dimensão diferente não é corrupção

Existe um guard nesse caminho: se o provider cai num embedding de dimensão incompatível com a da store, o sistema levanta RuntimeError com mensagem clara em vez de gravar lixo. Um chunk com dimensão errada não é “meio indexado” — é um vizinho errado pra sempre no espaço vetorial. Falhar alto, falhar cedo.

Onde o embedding encontra a palavra

A busca híbrida fecha o ciclo. O backend SQLite (app/rag/stores/sqlite_store.py) mantém uma tabela virtual FTS5 sobre os chunks — tokenize='porter unicode61', external content table, com triggers de insert/delete/update para o índice não sair de sincronia. Na consulta, o FTS5 acha por palavra e o vetor acha por sentido; a fusão é RRF (Reciprocal Rank Fusion):

def search_hybrid(self, query_text, query_vector, kb_id, top_k=10, min_score=0.3):
    fts_results = _fts_search(kb_id, query_text, limit=top_k * 2)
    vec_results = self.search(query_vector, kb_id, top_k=top_k * 2, min_score=min_score)
    K_RRF = 60  # RRF constant — soma por posição de rank, não por score

O detalhe que importa: o RRF soma posição de rank (1/(60+rank)), não magnitude de score. Depois da troca 384→768, a escala dos scores de cosseno mudou — e o RRF nem percebeu. A decisão de fundir por rank, e não por peso, é o que tornou a troca de embedding indolor para quem já usava a busca.

O que vem a seguir

Health check no boot: comparar a dimensão do provider configurado com a da coluna antes de servir tráfego. Hoje o erro aparece na primeira inserção; amanhã ele deve aparecer no startup, com o nome da env errada na mensagem. E quando o espelho sem GPU aparecer, o provider default já sabe o que fazer — 384 dimensões, honestas, do mesmo jeito que 768.

Conferir o par provider/dimensão em uso é uma variável de ambiente e uma suíte: ARACHNE_EMBEDDING_PROVIDER diz qual provider está ativo e os testes de api/tests/test_rag.py::TestEmbedder conferem que a dimensão devolvida bate com a da coluna. Enquanto o health check no boot não existe, é essa a checagem que evita o erro só aparecer na primeira inserção.

Leia também

Mesmo projeto, mesma trilha — as histórias se conectam.

Próximo passo

Se isto te serviu, tem mais: escrevo sobre o mesmo assunto nos outros projetos, e a loja tem as ferramentas que eu uso aqui.

Sem spam, descadastro de um clique. Também estou aqui: Loja de skills · Portfólio