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):

# 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:

vector-index

Ausgabe endet typischerweise mit:

🎉 Fertig. <N> Dateien, ~<M> Chunks, <X> geĂ€ndert, in <t>s.

3) Testen

Vector-Suche

vector info
vector search "Eule tanzen" --k 5

Du solltest deine neue Datei unter den Treffern sehen (Dateiname + Snippet).

Eule (ohne LLM, nur Kontext)

eule --no-llm "Was ist in 'Eule war tanzen' dokumentiert?"

Eule zeigt die Top-Quellen inkl. deiner neuen .md.

4) Optional: Snapshot (Backup)

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):

( 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:

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:

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:

sudo install -d -m 2775 -o vectorbot -g crumblog /opt/gitea-md/.state

E) Doctor

Schnellcheck:

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:

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.