Krümel Branko
83df9de035
12 Monate Crumbforest-Wachstum, sortiert nach Waldlogik. Struktur: - 454 Dokumente in 7 organischen Ebenen - Lichtung → Waldrand → Waldmitte → Wurzeln → Krone → Unterholz → Samen - INDEX.md für jede Ebene (eigene Stimme) - WALDKARTE.md (Master-Navigation) - crumbcodex.md (Das Versprechen zwischen Krümel & Bits) - lichtung/willkommen.md (Nullfeld-Einstieg für Kinder) Philosophie: - Waldlogik statt Ordnerlogik - Tiefe, Licht, Wurzeln - wie ein echter Wald - Schutz für Krümel, Tiefe für Gräber, Poesie für Atmende Repos verbunden: - OZM-Keks-Handbuch-v1 (Das Wissen) - Crumb-Core-v.1 (Das Herz) - 194.164.194.191 - crumbmissions (Das Spiel) Wuuuhuuuuu! 🦉✨
215 lines
5.1 KiB
Markdown
215 lines
5.1 KiB
Markdown
Hier ist eine fertige `README_indexing.md`, die du direkt in dein Repo legen kannst. Sie beschreibt genau den Ablauf “Markdown rein ⇒ Qdrant ⇒ Eule/Vector finden’s”, inkl. Tests & Troubleshooting.
|
||
|
||
---
|
||
|
||
# Crumbforest – Markdown → Qdrant Indexierung
|
||
|
||
Ziel: **Neue/aktualisierte `.md`-Dateien** aus diesem Repo in **Qdrant** indizieren, sodass
|
||
|
||
* `vector search "…" …` sinnvolle Treffer liefert und
|
||
* `eule "…" …` Antworten aus dem Kontext ziehen kann.
|
||
|
||
Minimal-pragmatischer Ablauf — **ohne** unnötiges Git-/Sudo-/Cache-Chaos.
|
||
|
||
---
|
||
|
||
## 0) Voraussetzungen (einmalig)
|
||
|
||
Diese Umgebung wird erwartet (ist bei uns bereits so eingerichtet):
|
||
|
||
* Python venv: `/opt/venvs/crumbforest/bin/python3`
|
||
* Qdrant läuft lokal, Collection: `md_files`
|
||
* Wrapper/Tools:
|
||
|
||
* `vector` → `/opt/vector/cli.py`
|
||
* `vector-index` → `/opt/gitea-md/index_md_qdrant.py`
|
||
* `eule` → `/opt/eule/eule_rag.py`
|
||
* Logging:
|
||
|
||
* `/var/log/crumb/vector.jsonl`
|
||
* `/var/log/crumb/eule.jsonl`
|
||
* Caches (les-/schreibbar für `vectorbot`):
|
||
|
||
* `HF_HOME=/opt/cache/hf`
|
||
* `SENTENCE_TRANSFORMERS_HOME=/opt/cache/st`
|
||
* `TORCH_HOME=/opt/cache/torch`
|
||
|
||
> Falls du auf einem frischen System bist, lies **Troubleshooting** unten.
|
||
|
||
---
|
||
|
||
## 1) Markdown hinzufügen / ändern
|
||
|
||
Im Repo (dieses Verzeichnis):
|
||
|
||
```bash
|
||
# Beispiel: neue Datei
|
||
echo -e "# Eule war tanzen (2025-08-16)\n\nKurzbericht + Medien." > eule_war_tanzen_2025-08-16.md
|
||
|
||
# optional: Medien unter media/<…>/ ablegen
|
||
mkdir -p media/eule_tanzt_2025-08-16
|
||
# (Bilder etc. hineinkopieren)
|
||
|
||
git add eule_war_tanzen_2025-08-16.md media/eule_tanzt_2025-08-16/
|
||
git commit -m "Add: Eule war tanzen (2025-08-16)"
|
||
git push # nur nötig, wenn das Repo einen Remote nutzt
|
||
```
|
||
|
||
> Wenn du direkt **auf dem Server-Clone** arbeitest und der Clone keine Pulls braucht, reicht `git add/commit`.
|
||
|
||
---
|
||
|
||
## 2) Index aktualisieren (Qdrant)
|
||
|
||
**Ohne Git-Pull**, nur lokale Dateien indizieren:
|
||
|
||
```bash
|
||
vector-index
|
||
```
|
||
|
||
Ausgabe endet typischerweise mit:
|
||
|
||
```
|
||
🎉 Fertig. <N> Dateien, ~<M> Chunks, <X> geändert, in <t>s.
|
||
```
|
||
|
||
---
|
||
|
||
## 3) Testen
|
||
|
||
### Vector-Suche
|
||
|
||
```bash
|
||
vector info
|
||
vector search "Eule tanzen" --k 5
|
||
```
|
||
|
||
Du solltest deine neue Datei unter den Treffern sehen (Dateiname + Snippet).
|
||
|
||
### Eule (ohne LLM, nur Kontext)
|
||
|
||
```bash
|
||
eule --no-llm "Was ist in 'Eule war tanzen' dokumentiert?"
|
||
```
|
||
|
||
Eule zeigt die Top-Quellen inkl. deiner neuen `.md`.
|
||
|
||
---
|
||
|
||
## 4) Optional: Snapshot (Backup)
|
||
|
||
```bash
|
||
vector snapshot create --collection md_files
|
||
vector snapshot list --collection md_files
|
||
```
|
||
|
||
---
|
||
|
||
## 5) (Optional) Cron für Auto-Reindex
|
||
|
||
Wenn du **regelmäßig** indizieren willst (ohne Pull):
|
||
|
||
```bash
|
||
( crontab -l 2>/dev/null | sed '/index_md_qdrant\.py/d'; \
|
||
echo '*/30 * * * * sudo -n -u vectorbot env HF_HOME=/opt/cache/hf SENTENCE_TRANSFORMERS_HOME=/opt/cache/st TORCH_HOME=/opt/cache/torch GIT_PULL=0 /opt/venvs/crumbforest/bin/python3 /opt/gitea-md/index_md_qdrant.py >>/var/log/crumb/vector.jsonl 2>&1' ) | crontab -
|
||
```
|
||
|
||
---
|
||
|
||
## Troubleshooting (kurz & knackig)
|
||
|
||
### A) `Permission denied: sentence-transformers/.../modules.json`
|
||
|
||
Embedding-Cache gehört „falschem“ User. Fix:
|
||
|
||
```bash
|
||
sudo install -d -m 775 -o vectorbot -g crumblog /opt/cache/hf /opt/cache/st /opt/cache/torch
|
||
sudo chown -R vectorbot:crumblog /opt/cache
|
||
```
|
||
|
||
Die Wrapper rufen bereits mit:
|
||
|
||
```
|
||
HF_HOME=/opt/cache/hf
|
||
SENTENCE_TRANSFORMERS_HOME=/opt/cache/st
|
||
TORCH_HOME=/opt/cache/torch
|
||
```
|
||
|
||
auf.
|
||
|
||
### B) `sudo: a password is required`
|
||
|
||
Der Wrapper muss **genau** dem Eintrag in `/etc/sudoers.d/crumbforest-tools` entsprechen.
|
||
Beispiel (so ist’s korrekt):
|
||
|
||
```
|
||
# Wrapper: /usr/local/bin/vector-index
|
||
exec sudo -n -u vectorbot env HF_HOME=... SENTENCE_TRANSFORMERS_HOME=... TORCH_HOME=... GIT_PULL=0 /opt/venvs/crumbforest/bin/python3 /opt/gitea-md/index_md_qdrant.py "$@"
|
||
```
|
||
|
||
Sudoers (exakte Pfade!):
|
||
|
||
```
|
||
tty ALL=(vectorbot) NOPASSWD: /opt/venvs/crumbforest/bin/python3 /opt/gitea-md/index_md_qdrant.py *
|
||
```
|
||
|
||
Prüfen:
|
||
|
||
```bash
|
||
sudo visudo -cf /etc/sudoers.d/crumbforest-tools
|
||
which vector vector-index eule
|
||
```
|
||
|
||
### C) Indexer will `git pull` / fragt nach Credentials
|
||
|
||
Wir indexieren **lokal**. Entweder:
|
||
|
||
* im Wrapper `GIT_PULL=0` setzen (siehe oben), **oder**
|
||
* im Script die `git pull`-Zeile entfernen/absichern.
|
||
|
||
### D) `.state`-Ordner nicht beschreibbar
|
||
|
||
Der Indexer speichert seinen Stand unter `/opt/gitea-md/.state`.
|
||
Fix:
|
||
|
||
```bash
|
||
sudo install -d -m 2775 -o vectorbot -g crumblog /opt/gitea-md/.state
|
||
```
|
||
|
||
### E) Doctor
|
||
|
||
Schnellcheck:
|
||
|
||
```bash
|
||
eule-doctor
|
||
vector-doctor
|
||
```
|
||
|
||
Beide sollten ✅ zeigen.
|
||
|
||
---
|
||
|
||
## Zusammenfassung
|
||
|
||
1. **Markdown schreiben** → `git add/commit/push` (optional).
|
||
2. **Index aktualisieren** → `vector-index` (ohne Pull).
|
||
3. **Testen** → `vector search …`, `eule --no-llm …`.
|
||
|
||
Fertig. Kein Overhead, nur Wald. 🌲🦉
|
||
|
||
---
|
||
|
||
Wenn das so passt, speicher die Datei:
|
||
|
||
```bash
|
||
cat > README_indexing.md <<'MD'
|
||
[OBIGER INHALT HIER REINKOPIEREN]
|
||
MD
|
||
|
||
git add README_indexing.md
|
||
git commit -m "Docs: README_indexing – Markdown→Qdrant Workflow"
|
||
git push
|
||
```
|
||
|
||
Sag Bescheid, wenn du noch eine **README\_blockly.md** für die CrumBlocks möchtest – dann dokumentiere ich dort den Wasserkocher-Flow (Variablen, Schleifen, Bedingungen) genau so schlank.
|