Skip to content

Choose how a base searches#

A knowledge base searches in one of two ways:

Keywords only Hybrid (recommended)
Needs Nothing to deploy An Eos deployment of an embedding model
Finds Passages with the words you typed (BM25), accents ignored The same, and passages that say it in other words
Misses Synonyms and paraphrases: vacation does not find a page that says holiday; a question asked in other words than the document's —
Good for Names, error codes, IDs, a small machine Questions in plain language, several languages

You can start with keywords only and add a model later, change the model, or remove it — nothing is read again, and the base never stops answering. A reranker (optional) orders the best passages again, more precisely, and takes effect on the next search.

Before you begin#

  • To change a base: the workspace role editor or admin (knowledge-bases:update).
  • For hybrid search: an Eos deployment of an embedding model in the workspace, kept at one replica at least — or let the console deploy one for you (below). BGE-M3 and Qwen3 Embedding 0.6B run well on a CPU.

Create a base with keyword search only#

In Metis ▸ Knowledge bases ▸ New knowledge base, under Search, choose Keywords only (no model).

Leave out --embedding:

$ astra metis create handbook --drive docs:handbook

Leave spec.embedding out:

curl -s -X POST -H "Authorization: Bearer $ASTRALYX_TOKEN" -H "content-type: application/json" \
  -d '{"metadata": {"name": "handbook"}, "spec": {"sources": [{"drive": "docs", "path": "handbook"}]}}' \
  "$ASTRALYX_API/metis/knowledge-bases"

The base reads its documents and is searchable as soon as they are read. Its page says Embedding model: none — keywords only, and its state's reason ends with searched by keywords (no embedding model). A search that asks for mode: dense is refused with 400 NO_EMBEDDING_MODEL; the default mode answers by keywords.

Under Search, choose Hybrid (recommended) and pick the Embedding model deployment. No embedding deployment yet? Tick Deploy one for me: the console adds BGE-M3 from the library and deploys it on a CPU of the workspace (one replica, a few hundred MB to download) — and, if you tick it, the reranker BGE Reranker v2 M3 too — then creates the base. The base starts at once, searched by keywords while the model downloads, starts and embeds; its page shows each step.

$ astra metis create handbook --drive docs:handbook --embedding bge-m3 --reranker bge-reranker

{"metadata": {"name": "handbook"}, "spec": {"sources": [{"drive": "docs", "path": "handbook"}], "embedding": {"deployment": "bge-m3"}, "reranker": {"deployment": "bge-reranker"}}}

Follow the progress#

While a base's chunks are being embedded, it answers searches the whole time, and says what it uses meanwhile. The base's page shows one progress, on desktop and phone:

  1. The model: its weights downloading (a percentage), then starting — the deployment's own state and reason.
  2. Embedding: n of m chunks, with the rate and the time left; searches use keywords meanwhile (or the model before, when you changed it).
  3. Switching, then ready: searches are hybrid.

The same is in the base's state (Indexing with a reason such as embedding with bge-m3: 1200 of 5000 chunks, 14.0/s, about 5 min left; searched by keywords meanwhile), in astra metis get:

$ astra metis get handbook
handbook: Indexing — embedding with bge-m3: 1200 of 5000 chunks, 14.0/s, about 5 min left; 41 documents, 5000 chunks, searched by keywords meanwhile
search: embedding with bge-m3: 1200 of 5000 chunks (24%, about 5 min left); keywords meanwhile

and in the API, in observed.embedding:

{"step": "embedding", "deployment": "bge-m3", "model_state": "Ready", "done": 1200, "total": 5000, "rate": 14.0, "eta_seconds": 272, "serving": "keywords"}
step Meaning
model Waiting for the embedding deployment: download (0–1) while its weights are fetched, then its model_state and model_reason
embedding Chunks being embedded: done of total, rate per second, eta_seconds
waiting The model does not answer; embedding resumes when it does
switching Every chunk has its vector; searches move to them
ready Hybrid

serving says what searches use meanwhile: keywords, previous (the vectors of the model before) or hybrid.

Add, change or remove the embedding model#

Open the base, then Settings ▸ Change it: choose another Embedding model, none, or another Reranker. Before you save, the console says what will happen.

$ astra metis models handbook --embedding bge-m3
$ astra metis models handbook --embedding qwen3-embedding
$ astra metis models handbook --no-embedding
$ astra metis models handbook --reranker bge-reranker
$ astra metis models handbook --no-reranker

Change the base with its whole spec (PUT /metis/knowledge-bases/{name}), with spec.embedding set, changed or left out.

What happens:

Change While it happens After
Add a model to a keyword-only base Searched by keywords while every chunk is embedded Hybrid
Change the model The model before keeps answering (its vectors are used, questions are embedded by it) while every chunk is embedded with the new one Hybrid with the new model
Remove the model — Keywords only, at once; the vectors are deleted
Add, change or remove the reranker — From the next search

No document is read again for any of these. Changing the chunking still reads every document again.

Keep the model before running while you change

When you change the model, the base keeps answering with the model before only while that deployment is still running. Delete it after the base is ready on the new one; if it is gone sooner, searches use keywords until the new vectors are made, and say so in their warnings.

Next#