Skip to content

Embeddings (TEI)

In-cluster text-embeddings-inference server hosting Qwen3-Embedding-0.6B (multilingual, 1024-dim) for the backend's semantic location search. Manifests: k8s/envs/platform/embeddings/.

What it does

The backend embeds each place on write (via the enrichment worker) and embeds a search query when lexical results are thin, then does an HNSW cosine lookup over the locations.embedding halfvec column. The service is best-effort: if it's down, search silently falls back to lexical-only.

Shape

Piece Value
Image ghcr.io/huggingface/text-embeddings-inference:cpu-1.9.4 (x86, digest-pinned)
Model Qwen/Qwen3-Embedding-0.6B (1024-dim); CPU inference
Service embeddings.platform.svc.cluster.local:80 (ClusterIP)
Storage embeddings-model-pvc (10Gi, model cache)
Resources 1 CPU / 3Gi request, 3 CPU / 6Gi limit (a 4Gi limit OOMed on model load)
Batching --max-batch-tokens 2048, --max-client-batch-size 64, --auto-truncate. TEI's default 16384-token batch makes the CPU warmup exceed the 6Gi limit; place and query texts are short, so a smaller batch costs nothing.
Health GET /health; a startup probe (up to 10 min) gates the readiness and liveness probes, so traffic arrives only once the model is loaded

The x86 CPU image matches the bare-metal server.

Backend wiring

The API and async pools set EMBEDDINGS_* in the tomoda base deployments, so dev and prod both use it (see the app repo's env-vars reference): EMBEDDINGS_ENABLED=true, EMBEDDINGS_BASE_URL=http://embeddings.platform.svc.cluster.local, EMBEDDINGS_DIMENSIONS=1024, EMBEDDINGS_SEARCH_DIMENSIONS=512, EMBEDDINGS_ALLOW_PRIVATE=true.

Model dimensions

EMBEDDINGS_DIMENSIONS and the locations.embedding halfvec(N) column must match the model output (1024 for Qwen3-Embedding-0.6B). The HNSW index and queries use only the first EMBEDDINGS_SEARCH_DIMENSIONS (512) components, so widening search is an index rebuild, not a re-embed. Changing the model or length means a schema change + a re-embed of the catalog.