diff --git a/README.md b/README.md index a6b5382..a8583b7 100644 --- 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:** -> -> 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) |