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.