--- okf: "0.1" type: session-log visibility: private status: active updated: 2026-07-30 links: [] --- # Sesja 2026-07-27 — KB faza 4: fallback embed SOLARIA→PIHA (krok 3, ostatni element rdzenia) > **Dopisek redakcyjny (2026-07-30, dedup — `docs/kb/modules/05-fallback-dedup-raport.md`):** > implementacja kodu z tej sesji (`app/fallback.py`, branch `task/kb-f4-fallback`, 3d4ee38) > została **porzucona** — do mastera weszła równoległa, szersza implementacja tego samego > kroku planu (e7625cd, `app/embed_router.py`, 2026-07-29) i to ona biega na PIHA. Ten log > wciągnięto do repo, bo dokumentuje fakty operacyjne niezależne od porzuconego kodu: > znalezisko i wyłączenie osieroconego natywnego `ollama.service` na PIHA (§3, z backlogiem > odinstalowania ≈2026-08-10), kalibrację live ollama-piha z werdyktem GO (§4 — konfiguracja > kontenera identyczna na masterze, pomiar przenosi się) oraz metodologię i baseline bramki > §9 (§5, Δ~3e-4). Wyniki bramki i testu sol-down dotyczyły kodu z brancha — na wdrożonym > masterze wymagają powtórki (raport dedup, follow-up (b)). Sekcje o deployu (§6) i > "Do zrobienia przez operatora" pkt 1–2 opisują stan sprzed merge'a e7625cd — historyczne. > Z delty brancha uratowano ponadto: `retrieval_eval.py --transport http` (plan §2 D6/§9) > i luki testowe T1/T2 przeniesione do `test_embed_router.py`. **Zakres**: `docs/kb/modules/05-faza4-plan.md` §2 decyzja 2 / §5 — aktywny fallback embedu, ostatni brakujący element rdzenia fazy 4 (frontend i ingress LIVE od 2026-07-22/23, `docs/sessions/2026-07-23-kb-f4-ingress.md`). Zero zmian w schemacie DB, zero zmian w `kb_retrieval`'s retrieval logice — wyłącznie warstwa embed + health. Praca wykonana w task worktree (`task/kb-f4-fallback`, `.claude/skills/worktree-aware`). Zgodnie z ustaleniem na starcie sesji (patrz "Ustalenia proceduralne" niżej): kod napisany i przetestowany lokalnie w worktree, produkcyjne kroki (kalibracja, deploy, live-test) wykonane po jawnej zgodzie operatora, z osobnym potwierdzeniem przed każdym kolejnym krokiem dotykającym PIHA/SOLARIĘ. ## Ustalenia proceduralne Zadanie wprost wymagało kroków produkcyjnych (kalibracja RAM/latencji na żywym PIHA, symulacja sol-down dotykająca SOLARII, deploy, push) — sprzeczne z ogólną dyscypliną `worktree-aware` ("nigdy nie uruchamiaj deployów/healthchecków przeciw produkcji z worktree"). Zamiast rozstrzygać to samodzielnie, zapytano operatora: 1. Recon read-only (bez zmian stanu) — zgoda bez pytania. 2. Właściwe kroki produkcyjne (kalibracja, deploy, live-test, push) — operator potwierdził jawnie ("Yes, proceed with all of it") po zobaczeniu pełnego zakresu. ## 1. Kod (warstwa embed + health, zero zmian retrievalu/DB) - **`packages/kb_retrieval/embed.py`**: `embed_chunk` dostał opcjonalny `timeout_s` (domyślnie `None`, zero zmiany zachowania istniejących wołań) — potrzebny do twardego 3 s timeoutu na nodze SOLARIA bez zmiany zachowania nogi PIHA. - **`services/kb-query/app/fallback.py`** (nowy): `SolCircuitBreaker` (cache 30 s, zegar wstrzykiwalny do testów) + `resolve_sol_status` (probe `/api/tags`, 500 ms) + `embed_with_fallback` (SOLARIA z twardym 3 s timeoutem → jednorazowe przełączenie na PIHA **w tym samym requeście** przy timeout/błędzie → PIHA bez dodatkowego timeoutu). Dokładnie maszyna stanów z planu §2 decyzja 2. - **`app/search.py`**: `run_search` liczy embedding raz przez `embed_with_fallback`, potem woła `flat_retrieve`/`cascade_retrieve`/`hybrid_retrieve` (niskopoziomowe funkcje `kb_retrieval`, biorą gotowy wektor) zamiast `flat_query`/`cascade_query`/ `hybrid_query` (które embedują same) — dzięki temu decyzja fallbacku żyje wyłącznie w warstwie HTTP kb-query, zero zmiany w `kb_retrieval`. `sol_status` w odpowiedzi to teraz realny wynik, nie zahardkodowane `"up"`. - **`app/main.py`**: `/healthz` i `/search` dzielą jeden `SolCircuitBreaker` (`app.state.sol_breaker`) — oba endpointy zawsze zgadzają się co do aktualnego stanu. Nowy env `OLLAMA_PIHA_URL` (domyślnie `http://localhost:11434` — celowo "inertny" placeholder, fail-closed, dopóki operator nie ustawi realnego adresu). - **Inwariant modelu**: **nie dodano** drugiego, per-request sprawdzenia w DB — `EMBED_MODEL` to jedna stała wątkowana przez obie nogi `embed_with_fallback`, więc startowy check (`app/startup.py`, niezmieniony) pokrywa obie ścieżki z konstrukcji. Dodanie drugiego DB-checka chroniłoby przed scenariuszem, który nie może wystąpić (CLAUDE.md: nie dodawaj walidacji dla scenariuszy, które nie mogą się zdarzyć) — zamiast tego nowy test (`test_both_legs_use_identical_embed_model`) strukturalnie dowodzi, że obie nogi w tym samym requeście dostają identyczny `embed_model`. - **`jobs/documents-ingest/eval/retrieval_eval.py`**: dodano `--transport {direct,http}` + `--base-url` (plan §2 decyzja 6 / §9) — dotąd nieistniejące (tylko ręczny smoke-test, `docs/sessions/2026-07-23-kb-f4-ingress.md` follow-up). Tryb `http` woła trzy `GET /search` (flat/cascade/hybrid) na żywym kb-query zamiast embedować+odpytywać lokalnie; `envelope.source` do kryterium 4 bierze się z pola `source` w odpowiedzi JSON, nie z osobnego zapytania do DB. Nie da się swipe'ować N przez HTTP (kb-query serwuje jeden N per request) — tryb http raportuje tylko przy `--gate-n`. ## 2. Nowy serwis `services/ollama-piha` Klon wzorca `services/ollama` (`owner_node: piha` zamiast `solaria`, bez rezerwacji GPU — PIHA to arm64 bez akceleracji), `OLLAMA_KEEP_ALIVE=0` (model ładowany tylko na czas requestu). `mem_limit: 2560m` (tentatywny wg planu, potwierdzony pomiarem — patrz §3). Wpisany do `hosts/piha/services.yaml` (`depends_on.local` kb-query → `[kb-postgres, ollama-piha]`, fallback nie jest twardą zależnością na starcie). ## 3. Znalezisko: osierocony natywny `ollama.service` na PIHA Podczas pierwszej próby deployu `ollama-piha` (bind `127.0.0.1:11434`) — konflikt portu. Okazało się, że PIHA ma **natywny (nie-Docker) systemd `ollama.service`** (v0.6.1, `enabled`, działający od 2026-06-22, PATH env wskazujący na użytkownika `/home/pi/...`), o którym nic nie wiadomo w repo — plan §1.2 wprost zakładał "PIHA: brak Ollamy", co okazało się nieaktualne/błędne. To realna sprzeczność planu z rzeczywistością → STOP, pytanie do operatora zamiast cichej decyzji. Weryfikacja przed jakąkolwiek akcją: `journalctl -u ollama --since "7 days ago"` — **tylko własne, właśnie wykonane** zapytania probe (`/api/version`, `/api/tags`), `total blobs: 0` od startu (nigdy nic nie pobrano). Operator potwierdził: martwy balast, `sudo systemctl disable --now ollama.service` (**disable, nie uninstall** — odwracalne). Port 11434 zwolniony, `ollama-piha` wystartował normalnie. **Backlog**: PIHA host-level shadow — natywny `ollama.service` wyłączony 2026-07-27; odinstalować binarkę/unit po ~2 tygodniach jeśli nic się nie posypie. ## 4. Kalibracja (plan §5, gate) — **werdykt: GO** Zmierzone na żywym PIHA pod normalnym obciążeniem (kb-postgres, paperless, Immich, HA, Forgejo działające, nie okno nocnej ciszy), 3 kolejne wywołania `/api/embeddings` po `ollama pull bge-m3`: | Wywołanie | Latencja | |---|---| | 1 (pierwsze, zimny start) | 5.25 s | | 2 | 4.41 s | | 3 | 4.16 s | Brak przyspieszenia między wywołaniami — zgodnie z projektem (`OLLAMA_KEEP_ALIVE=0` zwalnia model po każdym requeście, `ollama ps` pokazuje zero rezydentnych modeli między wywołaniami). RAM: baseline idle ~66 MiB, szczyt podczas burst ~983 MiB (`docker stats`, próbkowane co 0.3 s w trakcie 3 wywołań) — komfortowo w granicach ceilingu `2560m`. `free -h` systemowe: `available` nie spadło poniżej ~1.3 GiB w trakcie, osiadło na ~4.2 GiB po (dla porównania: przed startem eksperymentu `available` = 3.7 GiB). **Werdykt**: oba kryteria planu spełnione (latencja pojedyncze sekundy, nie dziesiątki; RAM ze sporym zapasem) → **włączony jako domyślny fallback**, bez flagi `KB_QUERY_LOCAL_FALLBACK_ENABLED`. ## 5. Bramka jakościowa (plan §9) Wszystko uruchomione z `~/kb/venv` na PIHA (istniejący venv z poprzednich sesji, `aiohttp`/`asyncpg`/`yaml` już obecne) przeciw żywej bazie + żywemu kb-query. **HTTP-equivalence** (`--transport http` vs `--transport direct`, SOLARIA up, ten sam `--gate-n 10`): oba PASS, **0 rozbieżności** w `dist` na wszystkich zapytaniach (`flat_top1_dist`, `hybrid_top1_dist`, `cascade[10].top1_dist`) — identyczne bit w bit, jak wymagał plan (nie ±epsilon, bo to ten sam kod, HTTP to tylko opakowanie). **Live sol-down fallback test**: symulacja przez `OLLAMA_URL=http://solaria:1` (zły port, zgodnie z rekomendacją planu — zero dotknięcia SOLARII/innych konsumentów Ollamy) w `.env` kb-query, restart kontenera. `/healthz` → `sol_status: "down"`. `/search` → 200, wyniki z PIHA, ~4.3 s (zgodnie z kalibracją). Pełna bramka `retrieval_eval.py --transport http` z SOLARIA-down: **PASS** — identyczny wzorzec hit@3 co na SOLARII, `dist` w granicach epsilon: | Zapytanie | dist (SOLARIA) | dist (PIHA fallback) | Δ | |---|---|---|---| | 1 | 0.341780 | 0.341509 | 0.000271 | | 2 | 0.324808 | 0.324858 | 0.00005 | | 3 | 0.428898 | 0.429184 | 0.000286 | | 4 | 0.448199 | 0.447903 | 0.000296 | | 5 | 0.386901 | 0.386816 | 0.000085 | | N (negative control) | 0.598301 | 0.598017 | 0.000283 | | N2 (negative control borderline) | 0.529772 | 0.529530 | 0.000242 | Maksymalna rozbieżność: **~3e-4** — rząd wielkości mniejszy niż oczekiwany przez plan (1e-3–1e-2), kolejność top-k identyczna, wynik bramki (`gate.passed`) identyczny. Kb-query przywrócony do normalnej konfiguracji po teście (`.env` z prawdziwym `OLLAMA_URL`, restart), `/healthz` z powrotem `sol_status: "up"`. ## 6. Deploy Kod nie był jeszcze zmergowany do `master` (dyscyplina worktree: agent nigdy nie mergeuje/pushuje `master`) — deploy przez standardowy `deploy-node.sh` niedostępny bez mastera. Zamiast tego: `rsync` zmienionych plików (`packages/kb-retrieval`, `services/kb-query`, `services/ollama-piha`, `hosts/piha/runtime/ollama-piha`, `hosts/piha/services.yaml`, `jobs/documents-ingest/eval/retrieval_eval.py` + README) do żywego checkoutu `~/homelab-codex-ws` na PIHA (bez zmiany brancha — working tree pozostaje na `master` z niescommitowanym diffem 1:1 identycznym z tą gałęzią), potem standardowy `docker compose ... up -d --build` z tego miejsca. Efekt: realny, działający deploy, ale **repo na PIHA ma dziś dirty working tree** — wymaga domknięcia (patrz "Do zrobienia przez operatora" niżej). Zweryfikowane: `kb-query` (healthy), `ollama-piha` (healthy, `bge-m3` w wolumenie), `curl https://kb.kapala.org/healthz` → `200 {"sol_status":"up"}`, `curl https://kb.kapala.org/search?q=test` → `200`. ## Stan na koniec sesji | Element | Status | |---|---| | `packages/kb-retrieval` — `embed_chunk(timeout_s=...)` | ✅ kod + testy | | `services/kb-query/app/fallback.py` — maszyna stanów | ✅ kod + testy (38/38 kb-query, 25/25 kb-retrieval) | | `services/ollama-piha` — nowy serwis GitOps | ✅ zdefiniowany, ✅ LIVE na PIHA | | Natywny `ollama.service` na PIHA (osierocony) | ✅ wyłączony (nie odinstalowany) | | Kalibracja RAM/latencja | ✅ zmierzone — werdykt GO | | `retrieval_eval.py --transport http` | ✅ zaimplementowane, ✅ PASS na żywo | | Live sol-down fallback test | ✅ PASS, Δ~3e-4 | | Deploy kb-query + ollama-piha na PIHA | ✅ LIVE, working tree PIHA dirty (patrz niżej) | | Merge do `master` | ⛔ nie wykonany (dyscyplina worktree — operator) | ## Do zrobienia przez operatora 1. **Merge** `task/kb-f4-fallback` → `master` (`scripts/dev/agent.sh merge` albo ręcznie) — branch popchnięty do `origin/task/kb-f4-fallback` (patrz commit poniżej). 2. Na PIHA: `cd ~/homelab-codex-ws && git status` będzie dirty (diff identyczny z tym commitem, bo już wdrożony ad-hoc przez `rsync` w tej sesji) — po mergu do mastera, `git checkout -- .` (working tree już ma dokładnie tę treść) albo zwyczajnie `git pull` po mergu powinien wylądować "already up to date"/no-op, bo pliki na dysku już są zgodne z tym co przyjdzie z mastera. **Zweryfikować** `git diff` jest puste po pull, nie zakładać. 3. Backlog: natywny `ollama.service` na PIHA wyłączony `systemctl disable --now` 2026-07-27 (§3 wyżej) — jeśli nic się nie posypie przez ~2 tygodnie, odinstalować binarkę/unit całkiem. 4. OIDC dla kb-query nadal odłożone (decyzja z 2026-07-23) — nie w zakresie tej sesji.