Skip to content

v0.2.0 — Stage 1: Indexierung + Retrieval (Breaking: armv7 weg)

Choose a tag to compare

View all tags
@dibi73 dibi73 released this 02 May 08:27
· 27 commits to main since this release
v0.2.0
6b5d1af
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

⚠️ Breaking-Changes ganz oben

armv7 (32-Bit ARM) wird nicht mehr unterstützt. Stage 1 zieht PyTorch transitiv mit (über sentence-transformers), und PyTorch hat keine offiziellen armv7-Wheels. Wer ein Pi 4 mit 32-Bit Raspberry Pi OS oder einen Pi 3 betreibt, kann dieses Release und alle folgenden nicht mehr installieren. Lösung: gleiche Hardware, anderes OS-Image — auf 64-Bit Raspberry Pi OS umsteigen (aarch64), dann läuft das Add-on wieder. amd64 (x86-NAS, Homelab) und aarch64 (Pi 4 64-Bit, neuere ARM-NAS) bleiben voll unterstützt.

Container-Base hat sich geändert. Nicht mehr ghcr.io/home-assistant/{arch}-base-python:3.12-alpine3.19, sondern python:3.12-slim-bookworm (debian/glibc). Grund: PyTorch und ONNX Runtime liefern in 2026 immer noch keine musllinux-Wheels — alpine war eine Sackgasse für die ML-Pipeline. Image ist ~150 MB größer, dafür installiert pip alle Wheels sauber ohne Source-Builds. Bashio wurde durch plain bash ersetzt; s6-overlay v3 wird im Dockerfile selbst aus den just-containers/s6-overlay-Releases gebootstrapped.

Stage 1 — Indexierung + Retrieval ist live

Was kommt rein:

  • File-Watcher auf <config>/bookstack_export/: erkannt durch watchdog, Events sind 500 ms debounced, jede Änderung läuft durch dieselbe Reconcile-Funktion wie der Initial-Scan beim Start und der manuelle /api/reindex-Endpoint (HARD RULE §3.7 — eine Logik in allen Entry-Points).
  • Lokales Embedding mit nomic-ai/nomic-embed-text-v1.5 (768 Dimensionen, MIT-Lizenz, ~500 MB). Im Container vorinstalliert — erster Start ist sofort einsatzbereit, kein Modell-Download zur Laufzeit.
  • Qdrant als Sidecar im selben Add-on-Container. Binary stammt aus qdrant/qdrant:v1.17.1 (passt zur qdrant-client-Version), bind auf localhost:6333, Persistenz unter /data/qdrant/storage/. Überlebt Restarts und Updates.
  • Idempotenz: SHA-256 jeder Markdown-Datei wird als Qdrant-Payload gespeichert. Beim Container-Restart werden nur geänderte Dateien neu eingebettet.
  • Soft-Delete: gelöschte Markdown-Dateien werden im Index als tombstoned: true markiert und aus Suchergebnissen ausgeschlossen, aber nicht hart entfernt.

Neue API-Endpoints:

Methode Pfad Zweck
GET /api/status Erweitert: liefert jetzt auch indexed (Count im Qdrant-Index).
POST /api/query Body: {text, top_k?}. Embeddet die Frage, gibt Top-K Treffer mit {doc_id, score, title, content_preview, bookstack_page_id}.
POST /api/reindex Manueller Reconcile-Sweep. Antwort: {indexed, unchanged, skipped, failed, total}.

Neue Konfigurations-Optionen (HA-Add-on-UI):

Option Default Beschreibung
embedding_model nomic-ai/nomic-embed-text-v1.5 Anderes Modell triggert einmaligen Download beim ersten Start.
top_k 5 (1-50) Default für /api/query wenn der Aufruf kein eigenes top_k mitliefert.

Update auf v0.2.0

Wer auf armv7 ist (Pi 3, Pi 4 mit 32-Bit-OS): zuerst 64-Bit Raspberry Pi OS installieren, dann das Add-on neu installieren.

Wer auf amd64 oder aarch64 ist: im HA-Add-on-Store auf "Update" klicken. Der erste Build des neuen Images dauert auf dem HA-Host ~5-10 Minuten (~700 MB PyTorch + 500 MB Embedding-Modell + Qdrant-Binary). Folgende Updates sind schneller, weil die heavy Layers cached sind. Persistierte Daten unter /data/qdrant/ bleiben erhalten.

Hardware-Empfehlung (aktualisiert)

Setup Stage 1
Pi 4 64-Bit (4 GB+) ✅ Embedding läuft, ~5-10 s pro Dokument
Pi 4 64-Bit (2 GB) ⚠️ grenzwertig, Modell allein braucht ~500 MB RAM
Pi 4 32-Bit oder Pi 3 ❌ nicht mehr unterstützt
Synology / x86 NAS ✅
Lokaler PC ✅

Mindest-RAM für das Add-on (ohne LLM): ~1.5-2 GB.

Was bewusst NICHT in v0.2.0 ist

  • Keine LLM-Integration — das ist Stage 2 / v0.3.0. Bis dahin liefert /api/query die passenden Dokumente, aber keine synthetisierte Antwort.
  • Keine Web-UI — Stage 3 / v0.4.0. Aktuell ist der Zugriff über HA-Ingress + API-Calls (z. B. via Developer Tools oder einem REST-Client).
  • Kein home-assistant/builder Multi-Arch-Publish — wir liefern keine Pre-Built-Images über ghcr.io aus. Der HA-Supervisor baut das Image lokal auf jedem User-Host (~5-10 Min Erstinstallation, danach gecacht).
  • Kein HACS-Validation-Workflow — gibt es für Add-ons nicht (HACS-Action validiert nur Integrations/Plugins/Themes). Add-on-Validation läuft beim Supervisor-Install.

Vollständiger Change-Log

CHANGELOG.md

Assets 2
Loading