
The day Arachne stopped thinking in English
The day Arachne stopped thinking in English
August 2, 2026. The Arachne RAG was already ingesting documents, generating embeddings and answering queries — but it embedded everything with all-MiniLM-L6-v2, a 384-dimensional model trained on English. The users’ corpus, of course, was Portuguese. The symptom was not a visible error: search worked, but the vector space where “nota fiscal” should live had been built in another language. A query written in colloquial Portuguese landed closer to generic English vocabulary than to the exact term that existed in the document.
That day the vector store migrated to pgvector on the local PostgreSQL: 4063 embeddings converted, with an ivfflat index. The next day, August 3, in came tardellirs/colibri-embed-ptbr — 768 dimensions, trained on Portuguese. The openai provider now pointed at a local Infinity instance serving the model, switched by a single env var: ARACHNE_EMBEDDING_PROVIDER=openai.
The tools I use on this project live in the skills store — the first one is free.
The part nobody tells you: 384 and 768 don’t coexist
Swapping the model is not swapping a config. The embedding column in the database has a fixed dimensionality — a 768-dimensional vector does not fit into a field expecting 384. That is why the migration script (scripts/reembed-colibri.py) starts by dropping the ivfflat index and the old column before rewriting everything:
# 384 -> 768 dimension migration, rag_chunk embeddings in pgvector
source .venv-linux/bin/activate && python3 scripts/reembed-colibri.py
The number nobody believes until they see it: 4063 chunks re-embedded in 46 seconds, on local GPU. On CPU, the same job would be the difference between a coffee break and lunch. The migration was fast, but the lesson stuck: embedding dimension is a contract, not a parameter. When the two sides disagree, the worst outcome is not the error — it is the silence.
The regression that showed up two months later
On October 17, 2026, commit f111c958aadb27031b20e362ae93ec342248dbcb (“fix(embedder): adapter respects the provider (openai->colibri 768, default->local 384)”) fixed exactly that divergence. The adapter in app/ingestion/embedder.py had baked the code: it always sent colibri (768d) every time, ignoring the configured provider. Anyone running without Infinity — default provider, local all-MiniLM-L6-v2, 384d — got 768-dimensional vectors from a backend that never served them, falling into a fallback path nobody had asked for.
The fix has three parts, none of them decorative:
# app/ingestion/embedder.py — after the fix
# openai -> core.embedder colibri (768d)
# default -> core.embedder local all-MiniLM (384d), DummyEmbedder fallback
- The adapter reads
ARACHNE_EMBEDDING_PROVIDERand respects what is configured instead of assuming colibri. embed/embed_batchwent back to returning plain lists via.tolist()— the contract the tests enforce, which the refactor had broken.- Empty env vars are now handled instead of turning into an empty string in the middle of the configuration.
Who paid for the regression was test_rag.py::TestEmbedder — red, pointing at the root cause. The suite api/tests/test_rag.py has 46 tests today, and it was what turned “works on my machine” into evidence.
The cost of mismatched dimensions is not corruption
There is a guard on this path: if the provider falls back to an embedding with a dimension incompatible with the store, the system raises a RuntimeError with a clear message instead of writing garbage. A chunk with the wrong dimension is not “half indexed” — it is a wrong neighbor forever in vector space. Fail loud, fail early.
Where the embedding meets the word
Hybrid search closes the loop. The SQLite backend (app/rag/stores/sqlite_store.py) keeps a virtual FTS5 table over the chunks — tokenize='porter unicode61', external content table, with insert/delete/update triggers so the index cannot drift out of sync. On query, FTS5 finds by keyword and the vector finds by meaning; the fusion is 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 — sums by rank position, not by score
The detail that matters: RRF sums rank position (1/(60+rank)), not score magnitude. After the 384→768 swap, the scale of the cosine scores changed — and RRF did not even notice. The decision to fuse by rank instead of by weight is what made the embedding swap painless for anyone already using search.
What comes next
Health check at boot: compare the dimension of the configured provider against the one in the column before serving traffic. Today the error surfaces on the first insert; tomorrow it should surface at startup, with the name of the wrong env var in the message. And when the GPU-less mirror shows up, the default provider already knows what to do — 384 honest dimensions, the same way 768 are.
Checking the active provider/dimension pair takes one environment variable and one suite: ARACHNE_EMBEDDING_PROVIDER says which provider is in use, and the tests in api/tests/test_rag.py::TestEmbedder confirm the returned dimension matches the column’s. Until the boot health check exists, that check is what keeps the error from surfacing only on the first insert.
Related entries
Same project, same ground — the stories connect.
Next step
If this was useful, there is more: I write about the same ground in the other projects, and the store holds the tools I use here.
Done — I will send the next article when it is out.
No spam, one-click unsubscribe. I am also here: Skills store · Portfolio