---
okf: "0.1"
type: service
visibility: private
status: active
updated: 2026-07-30
links:
  - ../runbooks/ollama-piha-deploy.md
---

# ollama-piha

Local CPU Ollama on **PIHA**, serving exactly one purpose: the **fallback embed
backend** for `kb-query` while SOLARIA (the GPU node, ~16 h/day powered off)
sleeps. Model: `bge-m3` — the **same** model as SOLARIA's Ollama, because query
embeddings must live in the same vector space as the pgvector index
(`document_chunk.embedding VECTOR(1024)`); a different/smaller model is not an
option (module 5 phase 4 plan §2 decision 2).

Expected latency: bge-m3 embeds in ~207 ms on SOLARIA's GPU vs ~790 ms on x86
CPU; on the Pi 5 expect single seconds per query (plus model load, since the
model is never resident — see below). Slower but alive beats fast but dead.

## Design constraints

- **`OLLAMA_KEEP_ALIVE=0`** (pinned in compose): PIHA is the RAM-bound 8 GB box
  shared with Home Assistant. The model is unloaded immediately after every
  call — a transient ~1.5–2 GB spike per embed, ~100 MB idle daemon, never a
  resident cost.
- **`mem_limit: 2560m`** (host override, `hosts/piha/runtime/ollama-piha/`):
  hard cgroup ceiling, plan §2 D2 starting value. The cgroup OOM killer
  restarts this container instead of the host OOM killer picking a victim
  (which could be Home Assistant). Confirm/trim after live calibration.
- **Bind**: `127.0.0.1` + `LAN_BIND_IP` (192.168.31.5) only — kb-query calls it
  over the host LAN interface (same pattern as kb-query → kb-postgres:5433).
  Never `0.0.0.0`, never a Tailscale bind, no public ingress.
- **Storage**: Docker named volume `ollama_piha_models` (NVMe data-root), not a
  bind mount — the ollama image runs as in-container root and would break
  PIHA's uid pattern (host oskar=1004, containers uid 1000, setgid group pi)
  if it wrote to a shared bind directory.

## Relation to kb-query

kb-query's router (`services/kb-query/app/embed_router.py`) health-checks
SOLARIA with a ~30 s cache and only sends embeds here while SOLARIA is down.
kb-query verifies at first use that this backend actually serves `bge-m3`
(`/api/tags`) and refuses to embed against a mismatched model. Configuration:
`EMBED_FALLBACK_URL=http://192.168.31.5:11434` in `services/kb-query/.env`.
See `services/kb-query/README.md` for the fallback verification plan (tests
A/B/C).
