docs: README als Architektur- und Betriebskonzept

Ersetzt den 'archiviert/nie gebaut'-Aufmacher durch eine Darstellung des laufenden Systems: Modellprofile, Optimierungen, ADR-Uebersicht sowie Betriebs- und Sicherheitskonzept. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-31 00:34:24 +02:00
parent 5f3c613f9f
commit b800582b9a
1 changed files with 62 additions and 51 deletions
--- a/README.md
+++ b/README.md
@@ -1,67 +1,78 @@
-# ⚠️ ARCHIVIERT — abgelöst durch `ansible-eulernest`
+# Jetson AI / Ollama — Design & Betriebskonzept

-> **Dieses Repo war die _Planungsphase_ für den Jetson-AI/Ollama-Host und wurde nie
-> gebaut.** Die Implementierung ist direkt im Schwester-Repo **`ansible-eulernest`**
-> entstanden — dort liegen jetzt Code **und** Doku (Single Source of Truth):
->
-> - **Implementierung:** `group_vars/jetson/vars.yml`,
->   `roles/{jetson_bootstrap,ollama,ollama_exporter}`, `jetson.yml`
-> - **Doku:** README §„Jetson AI / Ollama" + `docs/jetson-quickstart.md`
-> - **Repo:** <https://git.eulernest.eu/user2595/ansible-eulernest>
->
-> Der „Projekt-Vertrag" (Profile, Pfade, Daemon-Env, `num_ctx`) und die
-> Designentscheidung aus [`docs/adr/0002-ollama-native.md`](docs/adr/0002-ollama-native.md)
-> wurden dorthin portiert. Die reale Box läuft inzwischen auf JetPack 7.2 mit einem
-> vierten Profil (`coder`, für den ci-ai-Bot) — Details nur noch in `ansible-eulernest`.
->
-> Dieses Repo ist **veraltet, read-only archiviert** und wird nicht mehr gepflegt.
-> Der Inhalt unten ist der historische Planungsstand (agent-swarm-Bootstrap, Stand 2026-06).
+Selbst gehostetes **LLM-System auf einem Jetson Orin Nano Super (8 GB)**: Der
+Ollama-Daemon serviert mehrere Modellprofile über eine OpenAI-kompatible API, ein
+schlanker Exporter-Sidecar exponiert `/metrics` für Prometheus. Der Modellwechsel
+passiert **nativ über den Modellnamen** — bewusst ohne eigenen Swapper und ohne
+API-Gateway.
+
+Dieses Repo enthält **Architektur, Betriebsvertrag und Designentscheidungen** des
+Systems. Die Ansible-Implementierung lebt im Schwester-Repo `ansible-eulernest`
+(Rollen `jetson_bootstrap`, `ollama`, `ollama_exporter`) — die Box läuft dort
+produktiv auf JetPack 7.2.

 ---

-# Jetson AI / Ollama (MLOps)
+## Modellprofile

-Lokal laufendes **Single-User-AI-System** auf einem **Jetson Orin Nano Super (8 GB)**:
-Ollama-Daemon serviert drei Modell-Profile (OpenAI-kompatibel), ein schlanker
-Exporter-Sidecar exponiert `/metrics`. Modellwechsel passiert **nativ über den
-Modellnamen** — kein eigener Swapper, kein Gateway (siehe `docs/adr/0002-ollama-native.md`).
+Vier Profile, aber nie zwei gleichzeitig resident — das ist der Kern des
+8-GB-Konzepts (~7,4 GB nutzbar):

- **Profile:** `qwen-light` (Daily-Driver) · `gemma` (Creative/Chat, multimodal) ·
-  `qwen-heavy` (harte Reasoning-Fälle). `OLLAMA_MAX_LOADED_MODELS=1` hält genau ein
-  Modell resident → drei Profile sind quasi gratis.
- **Optimierung:** `q8_0`-KV-Cache + Flash Attention, `num_ctx` je Profil explizit.
- **Daten:** DVC ist Modell-Source-of-Truth; Ollamas Blob-Store nur Laufzeit-Cache.
+| Profil | Basismodell | `num_ctx` | Zweck |
+|---|---|---|---|
+| `qwen-light` | `qwen2.5:7b` | 16384 | Daily Driver, Chat |
+| `gemma` | `gemma3:4b` | 16384 | Kreativ, multimodal |
+| `qwen-heavy` | `deepseek-r1:7b` | 8192 | Harte Reasoning-Fälle |
+| `coder` | `qwen2.5-coder:7b` | 16384 | CI-Bot, PR-Review |

-> **Scope:** Dieses Repo deckt **nur den Jetson** ab. nginx (TLS + OAuth) und
-> Prometheus/Grafana laufen off-box. Ollama hat keine eigene Auth → nur ans LAN
-> binden, Firewall auf den Proxy. Voller Vertrag: [`CONVENTIONS.md`](CONVENTIONS.md).
+`OLLAMA_MAX_LOADED_MODELS=1` hält genau ein Modell im Speicher; weitere Profile
+laden on-demand. Dadurch sind vier Profile auf 8 GB praktisch kostenlos.
+
+## Optimierung
+
+- **`q8_0`-KV-Cache + Flash Attention** — deutlich geringerer Speicherbedarf pro
+  Kontextfenster.
+- **`num_ctx` je Profil explizit gesetzt**, da Ollama den Kontext sonst still kürzt.
+- **`OLLAMA_KEEP_ALIVE=30s`** — bewusster Trade-off: kurze Ladezeit beim
+  Profilwechsel gegen dauerhaft freien Speicher (Single-User, keine fremden
+  Sessions werden unterbrochen).
+
+## Architekturentscheidungen (ADRs)
+
+Jede wesentliche Entscheidung ist als ADR mit Kontext, Entscheidung und Konsequenz
+dokumentiert — inklusive der bewusst *nicht* gewählten Alternativen:
+
+| ADR | Entscheidung |
+|---|---|
+| [0001](docs/adr/0001-record-architecture-decisions.md) | Architekturentscheidungen als ADRs festhalten |
+| [0002](docs/adr/0002-ollama-native.md) | Ollama-natives Modell-Management statt eigenem Swapper/Gateway |
+| [0003](docs/adr/0003-registry-pull-over-gguf.md) | Registry-Pull statt manueller GGUF-Verwaltung |
+
+## Betrieb, Daten & Sicherheit
+
+- **Observability:** Exporter-Sidecar liefert `/metrics`; Aggregation in
+  Prometheus/Grafana läuft bewusst off-box.
+- **Modell-Daten:** DVC ist Source of Truth, Ollamas Blob-Store nur Laufzeit-Cache.
+- **Zugriff:** Ollama bringt keine eigene Authentifizierung mit → Bind nur ans LAN,
+  vorgelagerter nginx-Reverse-Proxy mit TLS und OAuth, Firewall auf den Proxy.
+- **Secrets:** ausschließlich über Ansible-Vault, nie im Klartext im Repo.
+
+Die vollständige Schnittstelle zwischen den Komponenten steht in
+[`CONVENTIONS.md`](CONVENTIONS.md).

 ---

-## Arbeitsmodell (agent-swarm)
-Dieses Repo wurde aus dem **agent-swarm-Template** gebootstrapt: ein Leader/Worker-
-Agentensystem, dessen Stand komplett auf Disk lebt — kalt lesbar ohne Vorkontext.
-Methodik: [`docs/methodology.md`](docs/methodology.md) · Herkunft:
-[`docs/about-template.md`](docs/about-template.md).
+## Arbeitsmodell
+
+Das Repo wurde aus einem **agent-swarm-Template** gebootstrapt: ein Leader/Worker-
+Modell für KI-gestützte Entwicklung, dessen Stand vollständig auf Disk lebt und
+damit ohne Vorkontext kalt lesbar ist. Automatische Gates (`scripts/gate-*.sh`)
+prüfen Datei-Ownership, Repo-Hygiene und Doku-Drift bei jedem Schritt.

 | Wo | Datei |
 |---|---|
 | Stand & nächster Schritt | [`STATE.md`](STATE.md) |
-| Plan / Board / Ready-Set (DAG) | [`ROADMAP.md`](ROADMAP.md) |
+| Plan / Board (DAG) | [`ROADMAP.md`](ROADMAP.md) |
 | Gemeinsamer Vertrag | [`CONVENTIONS.md`](CONVENTIONS.md) |
 | Kalt-Review-Einstieg | [`REVIEW.md`](REVIEW.md) |
-| Dispatch-fertige Worker-Prompts | [`session-prompts/`](session-prompts/) |
-
-## Sofort bauen
-Die Planung ist fertig (W1–W6 im Board). So baust du es:
-
-1. **W1 zuerst** — frische Session öffnen, Modell **Sonnet**, Inhalt von
-   [`session-prompts/W1.md`](session-prompts/W1.md) einfügen → legt das Grundgerüst an.
-2. **Review-Gate** (Opus, kalt) → mergen → W1 im Board auf `✅`.
-3. **W2–W5 parallel** — je eigene Session (`session-prompts/W2.md` … `W5.md`),
-   disjunkte Datei-Ownership, laufen unabhängig.
-4. **W6 zuletzt** — Docs, integriert die Realität der anderen Pakete.
-
-Jeder Worker-Prompt ist self-contained (Modell, Branch, Dateien, Akzeptanzkriterien,
-Abschluss-Gates). Die Gates (`scripts/gate-*.sh`) sind aktiv und prüfen Ownership,
-Hygiene und Doku-Drift bei jedem Schritt.
+| Methodik | [`docs/methodology.md`](docs/methodology.md) |