Tag 11: Embeddings und RAG – docsearch
befragt deine Notizen
Ziel: Markdown-Notizen in Chunks zerlegen, als Vektoren indizieren, semantisch suchen und Fragen mit Quellenangabe beantworten – plus messen, wie gut das klappt · Dauer: ca. 150 min · Voraussetzung: Tag 10
Briefing
- Ein Embedding ist ein Vektor (hier 384 Zahlen), der die Bedeutung eines Textes abbildet. Ähnliche Texte liegen nah beieinander.
- Kosinus-Ähnlichkeit misst den Winkel zwischen zwei Vektoren: 1 = gleich, 0 = unabhängig.
- RAG (Retrieval-Augmented Generation): erst passende Chunks suchen, dann nur diese dem LLM als Kontext geben – mit Quelle.
- qdrant speichert Vektoren und sucht schnell; im lokalen Modus ohne Server, nur ein Ordner.
- Ohne Evaluation ist jede RAG-Änderung Bauchgefühl.
notes/*.md ─chunk─> Chunks ─embed (all-minilm)─> Vektoren ─> qdrant (.docsearch/)
│
Frage ─embed─> Vektor ─────────── Top-k Suche ──────────────────┘
│
Treffer + Frage ─> ministral-3:3b ─> Antwort [datei.md#Abschnitt]
Drill 1: Projekt, Notizen und Embedding-Modell
cd ~/py-lab
uv init -q --package --name docsearch tag11-docsearch
cd tag11-docsearch
uv add -q openai numpy qdrant-client typer
uv add -q --dev pytest ruff
cat >> pyproject.toml <<'EOF'
[tool.ruff.lint]
extend-select = ["E501", "B", "UP", "SIM"]
[tool.pytest.ini_options]
testpaths = ["tests"]
EOF
uv tree --depth 1 | grep -E 'numpy|qdrant'
ollama pull all-minilm
ollama list | grep -E 'NAME|all-minilm'Erwartet (gekürzt, Versionen können abweichen):
├── numpy v2.5.3
├── qdrant-client v1.19.1
NAME ID SIZE MODIFIED
all-minilm:latest 1b226e2802db 45 MB 4 minutes ago
Jetzt fünf kleine Notizen als Testkorpus:
mkdir -p notes
cat > notes/vault.md <<'EOF'
# Vault Betrieb
## Entsiegeln
Nach einem Neustart ist Vault versiegelt. Drei von fünf Key-Shares eingeben:
`vault operator unseal` dreimal ausführen, Status mit `vault status` prüfen.
## Token erneuern
Lab-Token `sk-lab-master-1234` ist nur für das Lab. Eigene Tokens mit
`vault token renew` verlängern, TTL-Maximum beträgt 32 Tage.
EOF
cat > notes/k8s.md <<'EOF'
# Kubernetes Debugging
## CrashLoopBackOff
Ein Pod startet immer wieder neu. Erst `kubectl logs <pod> --previous`, dann
`kubectl describe pod <pod>` lesen. Häufig: falsches Secret oder OOMKilled.
## Pending Pods
Pod bleibt Pending: meist fehlen CPU/RAM-Ressourcen oder ein PVC ist nicht gebunden.
`kubectl get events --sort-by=.lastTimestamp` zeigt den Grund.
EOF
cat > notes/backup.md <<'EOF'
# Backup
## Zeitplan
Die Sicherung läuft jede Nacht um 02:00 Uhr per restic auf das NAS `nas01`.
Aufbewahrung: 7 tägliche, 4 wöchentliche, 12 monatliche Snapshots.
## Restore
Wiederherstellen mit `restic restore latest --target /tmp/restore`.
Vorher immer `restic snapshots` prüfen.
EOF
cat > notes/oncall.md <<'EOF'
# Rufbereitschaft
## Eskalation
Reagiert der Primary nicht innerhalb von 15 Minuten, eskaliert PagerDuty an
den Secondary. Nach 30 Minuten wird die Teamleitung angerufen.
## Übergabe
Übergabe jeden Montag 10:00 Uhr im Ops-Channel mit offenen Incidents.
EOF
cat > notes/python.md <<'EOF'
# Python Setup
## Neues Projekt
`uv init --package` legt ein Projekt mit src-Layout an, `uv add` fügt
Abhängigkeiten hinzu, `uv run` startet im Projekt-venv.
## Tests
Tests liegen unter `tests/` und laufen mit `uv run pytest -q`.
EOF
ls notesErwartet:
backup.md k8s.md oncall.md python.md vault.md
Tipp:
all-minilmist klein (45 MB) und schnell, aber auf Englisch trainiert. Für deutsche Texte sind mehrsprachige Modelle besser – die Folgen siehst du in Drill 7.
Fortschritt speichern? Kostenlos registrieren
Drill 2: Chunking an Überschriften
Ein Chunk pro ##-Abschnitt. Die Überschrift bleibt im
Text – sie trägt oft die meiste Bedeutung.
cat > src/docsearch/chunking.py <<'EOF'
"""Markdown-Dateien in Abschnitte (Chunks) zerlegen."""
from dataclasses import dataclass
from pathlib import Path
@dataclass(frozen=True)
class Chunk:
source: str # z. B. "vault.md#Entsiegeln"
text: str
def split_long(text: str, max_chars: int) -> list[str]:
"""Fasst Absätze zusammen, bis max_chars erreicht ist."""
parts: list[str] = []
current = ""
for para in text.split("\n\n"):
if current and len(current) + len(para) > max_chars:
parts.append(current)
current = ""
current = f"{current}\n\n{para}".strip()
if current:
parts.append(current)
return parts
def split_markdown(path: Path, max_chars: int = 800) -> list[Chunk]:
"""Ein Chunk pro Überschrift; die Überschrift bleibt als Kontext im Text."""
chunks: list[Chunk] = []
section = path.stem
lines: list[str] = []
def flush() -> None:
body = "\n".join(lines).strip()
for part in split_long(body, max_chars) if body else []:
chunks.append(Chunk(f"{path.name}#{section}", f"{section}\n{part}"))
lines.clear()
for line in path.read_text(encoding="utf-8").splitlines():
if line.startswith("#"):
flush()
section = line.lstrip("#").strip()
else:
lines.append(line)
flush()
return chunks
def load_notes(folder: Path) -> list[Chunk]:
return [c for p in sorted(folder.rglob("*.md")) for c in split_markdown(p)]
EOF
uv run python -c "
from pathlib import Path
from docsearch.chunking import load_notes
chunks = load_notes(Path('notes'))
print(len(chunks), 'Chunks')
for c in chunks[:3]:
print(c.source, '|', c.text.splitlines()[1][:50])
"Erwartet:
10 Chunks
backup.md#Zeitplan | Die Sicherung läuft jede Nacht um 02:00 Uhr per re
backup.md#Restore | Wiederherstellen mit `restic restore latest --targ
k8s.md#CrashLoopBackOff | Ein Pod startet immer wieder neu. Erst `kubectl lo
Warum 10 und nicht 15? Die #-Titelzeilen haben keinen
eigenen Text und erzeugen keinen Chunk. source wird später
zur Quellenangabe. Bei langen Abschnitten teilt split_long
an Absätzen statt mitten im Satz.
Fortschritt speichern? Kostenlos registrieren
Drill 3: Embeddings und Kosinus mit numpy
cat > src/docsearch/vectors.py <<'EOF'
"""Embeddings über Ollama, Kosinus-Ähnlichkeit mit numpy."""
import os
import numpy as np
from openai import OpenAI
BASE_URL = os.environ.get("DOCSEARCH_BASE_URL", "http://127.0.0.1:11434/v1")
EMBED_MODEL = os.environ.get("DOCSEARCH_EMBED_MODEL", "all-minilm")
def make_client() -> OpenAI:
key = os.environ.get("DOCSEARCH_API_KEY", "ollama")
return OpenAI(base_url=BASE_URL, api_key=key, timeout=120, max_retries=1)
def embed(client: OpenAI, texts: list[str]) -> np.ndarray:
"""Liefert eine (n, dim)-Matrix mit Länge 1 je Zeile."""
resp = client.embeddings.create(model=EMBED_MODEL, input=texts)
vecs = np.array([d.embedding for d in resp.data], dtype=np.float32)
return vecs / np.linalg.norm(vecs, axis=1, keepdims=True)
def top_k(query: np.ndarray, matrix: np.ndarray, k: int) -> list[tuple[int, float]]:
"""Kosinus = Skalarprodukt, weil alle Vektoren normiert sind."""
scores = matrix @ query
best = np.argsort(scores)[::-1][:k]
return [(int(i), float(scores[i])) for i in best]
EOF
uv run python -c "
from pathlib import Path
from docsearch.chunking import load_notes
from docsearch.vectors import embed, make_client, top_k
client = make_client()
chunks = load_notes(Path('notes'))
m = embed(client, [c.text for c in chunks])
print(m.shape, m.dtype, round(float((m[0] ** 2).sum()), 3))
for q in ['Wie entsiegle ich Vault?', 'Mein Pod startet ständig neu']:
print(q)
for i, score in top_k(embed(client, [q])[0], m, 2):
print(f' {score:.2f} {chunks[i].source}')
"Erwartet (Werte können leicht abweichen):
(10, 384) float32 1.0
Wie entsiegle ich Vault?
0.59 vault.md#Entsiegeln
0.45 vault.md#Token erneuern
Mein Pod startet ständig neu
0.56 k8s.md#CrashLoopBackOff
0.47 oncall.md#Übergabe
Warum normieren? Kosinus ist a·b / (|a|·|b|). Haben alle
Vektoren Länge 1, bleibt nur a·b – und
matrix @ query rechnet alle Skalarprodukte in einem Rutsch.
Ein Batch-Aufruf für alle Chunks ist viel schneller als einer pro
Chunk.
Fortschritt speichern? Kostenlos registrieren
Drill 4: Ein dauerhafter Index mit qdrant
numpy reicht für hundert Chunks im RAM. Für tausende Notizen, Persistenz und Filter nimmst du eine Vektor-DB. qdrant läuft hier eingebettet, ganz ohne Server.
cat > src/docsearch/store.py <<'EOF'
"""Persistenter Vektorindex mit qdrant im lokalen Modus (kein Server)."""
from dataclasses import dataclass
from pathlib import Path
import numpy as np
from qdrant_client import QdrantClient, models
from docsearch.chunking import Chunk
COLLECTION = "notes"
@dataclass
class Hit:
source: str
text: str
score: float
def open_store(path: Path) -> QdrantClient:
return QdrantClient(path=str(path))
def rebuild(store: QdrantClient, chunks: list[Chunk], vectors: np.ndarray) -> int:
if store.collection_exists(COLLECTION):
store.delete_collection(COLLECTION)
store.create_collection(
COLLECTION,
vectors_config=models.VectorParams(
size=vectors.shape[1], distance=models.Distance.COSINE
),
)
points = [
models.PointStruct(
id=i, vector=v.tolist(), payload={"source": c.source, "text": c.text}
)
for i, (c, v) in enumerate(zip(chunks, vectors, strict=True))
]
store.upsert(COLLECTION, points=points)
return store.count(COLLECTION).count
def search(store: QdrantClient, vector: np.ndarray, k: int = 3) -> list[Hit]:
res = store.query_points(COLLECTION, query=vector.tolist(), limit=k)
return [
Hit(p.payload["source"], p.payload["text"], p.score)
for p in res.points
if p.payload
]
EOF
uv run python -c "
from pathlib import Path
from docsearch.chunking import load_notes
from docsearch.store import open_store, rebuild, search
from docsearch.vectors import embed, make_client
client = make_client()
chunks = load_notes(Path('notes'))
store = open_store(Path('.docsearch'))
print('Punkte:', rebuild(store, chunks, embed(client, [c.text for c in chunks])))
for h in search(store, embed(client, ['Wann läuft die Sicherung?'])[0], k=2):
print(f'{h.score:.2f} {h.source}')
store.close()
"
ls .docsearchErwartet:
Punkte: 10
0.32 oncall.md#Übergabe
0.32 oncall.md#Eskalation
collection meta.json
Warum liegt Backup nicht vorn? Die Frage sagt „Sicherung”, die Notiz
auch – aber all-minilm versteht Deutsch nur grob. Niedrige
Scores um 0,3 sind ein Warnsignal: Das ist kein echter Treffer. Genau
dafür baust du in Drill 5 eine Schwelle ein.
Achtung: Der lokale Modus sperrt den Ordner für einen Prozess. Zwei gleichzeitige
docsearch-Aufrufe auf denselben.docsearch/scheitern – für mehrere Nutzer startest du den qdrant-Server.
Fortschritt speichern? Kostenlos registrieren
Drill 5: RAG – Antwort nur aus dem Kontext, mit Quelle
cat > src/docsearch/rag.py <<'EOF'
"""Retrieval-Augmented Generation: Treffer als Kontext an das Chat-Modell."""
import os
from openai import OpenAI
from docsearch.store import Hit
CHAT_MODEL = os.environ.get("DOCSEARCH_CHAT_MODEL", "ministral-3:3b")
MIN_SCORE = 0.35 # darunter gilt ein Treffer als Rauschen
NO_ANSWER = "Dazu finde ich nichts in deinen Notizen."
SYSTEM = (
"Beantworte die Frage NUR mit dem Kontext, auf Deutsch, in max. 3 Sätzen. "
"Nenne nach jeder Aussage die Quelle in eckigen Klammern, z. B. "
f"[vault.md#Entsiegeln]. Steht es nicht im Kontext, antworte: {NO_ANSWER}"
)
def build_prompt(question: str, hits: list[Hit]) -> str:
context = "\n\n".join(f"[{h.source}]\n{h.text}" for h in hits)
return f"Kontext:\n{context}\n\nFrage: {question}"
def answer(client: OpenAI, question: str, hits: list[Hit]) -> str:
relevant = [h for h in hits if h.score >= MIN_SCORE]
if not relevant:
return NO_ANSWER # spart den LLM-Aufruf und verhindert Halluzination
resp = client.chat.completions.create(
model=CHAT_MODEL,
messages=[
{"role": "system", "content": SYSTEM},
{"role": "user", "content": build_prompt(question, relevant)},
],
temperature=0,
)
return resp.choices[0].message.content or ""
EOF
uv run ruff check srcErwartet:
All checks passed!
Warum temperature=0? Bei RAG willst du Treue zum
Kontext, keine Kreativität. Und die Schwelle: Ohne
MIN_SCORE bekäme das Modell nur Rauschen als Kontext und
würde trotzdem etwas erfinden. „Weiß ich nicht” ist bei RAG eine gute
Antwort.
Fortschritt speichern? Kostenlos registrieren
Drill 6: Das CLI mit vier Befehlen
cat > src/docsearch/cli.py <<'EOF'
"""docsearch – eigene Markdown-Notizen durchsuchen und befragen."""
import json
from pathlib import Path
from typing import Annotated
import typer
from docsearch.chunking import load_notes
from docsearch.rag import answer
from docsearch.store import open_store, rebuild, search
from docsearch.vectors import embed, make_client
app = typer.Typer(add_completion=False, no_args_is_help=True)
DbOpt = Annotated[Path, typer.Option("--db", envvar="DOCSEARCH_DB")]
K = Annotated[int, typer.Option("-k", min=1, max=20)]
@app.command()
def index(folder: Path, db: DbOpt = Path(".docsearch")) -> None:
"""Liest alle *.md unter FOLDER und baut den Index neu."""
chunks = load_notes(folder)
if not chunks:
typer.secho(f"Keine Markdown-Abschnitte in {folder}", fg="red", err=True)
raise typer.Exit(1)
vectors = embed(make_client(), [c.text for c in chunks])
store = open_store(db)
count = rebuild(store, chunks, vectors)
store.close()
typer.echo(f"{count} Chunks aus {folder} indiziert ({vectors.shape[1]} Dim.)")
@app.command("search")
def search_cmd(query: str, k: K = 3, db: DbOpt = Path(".docsearch")) -> None:
"""Zeigt die k ähnlichsten Abschnitte."""
store = open_store(db)
for hit in search(store, embed(make_client(), [query])[0], k):
first = hit.text.splitlines()[1][:50]
typer.echo(f"{hit.score:.2f} {hit.source:28} {first}")
store.close()
@app.command()
def ask(question: str, k: K = 3, db: DbOpt = Path(".docsearch")) -> None:
"""Beantwortet QUESTION nur aus den Notizen, mit Quellen."""
client = make_client()
store = open_store(db)
hits = search(store, embed(client, [question])[0], k)
store.close()
typer.echo(answer(client, question, hits))
@app.command("eval")
def eval_cmd(cases: Path, k: K = 3, db: DbOpt = Path(".docsearch")) -> None:
"""Misst Hit@1 und Hit@k: Ist die erwartete Datei unter den Treffern?"""
data = json.loads(cases.read_text(encoding="utf-8"))
client = make_client()
store = open_store(db)
hit1 = hitk = 0
for case in data:
hits = search(store, embed(client, [case["question"]])[0], k)
files = [h.source.split("#")[0] for h in hits]
hit1 += files[:1] == [case["source"]]
hitk += case["source"] in files
mark = "✔" if case["source"] in files else "✘"
typer.echo(f"{mark} {case['question'][:40]:40} -> {files[0] if files else '-'}")
store.close()
n = len(data)
typer.echo(f"Hit@1: {hit1 / n:.2f} Hit@{k}: {hitk / n:.2f} (n={n})")
EOF
cat > src/docsearch/__init__.py <<'EOF'
"""docsearch – eigene Markdown-Notizen durchsuchen und befragen."""
import openai
import typer
from docsearch.cli import app
def main() -> None:
try:
app()
except openai.APIConnectionError:
typer.secho("Fehler: Ollama nicht erreichbar", fg="red", err=True)
raise SystemExit(1) from None
EOF
cat > src/docsearch/__main__.py <<'EOF'
from docsearch import main
main()
EOF
rm -rf .docsearch
uv run docsearch index notes
uv run docsearch search "Pod startet ständig neu"
uv run docsearch ask "Wer wird nach 30 Minuten angerufen?"
uv run docsearch ask "Wann läuft die Sicherung?"Erwartet (Text variiert, gekürzt):
10 Chunks aus notes indiziert (384 Dim.)
0.59 k8s.md#CrashLoopBackOff Ein Pod startet immer wieder neu. Erst `kubectl lo
0.45 k8s.md#Pending Pods Pod bleibt Pending: meist fehlen CPU/RAM-Ressource
0.45 oncall.md#Übergabe Übergabe jeden Montag 10:00 Uhr im Ops-Channel mit
Nach 30 Minuten wird die **Teamleitung** (meist der Oncall-Leiter oder Ops Manager)
per Telefon oder Notruf kontaktiert [oncall.md#Eskalation].
Die genaue Rolle variiert je nach Organisation, ... [oncall.md#Übergabe].
Dazu finde ich nichts in deinen Notizen.
Die Backup-Frage bleibt unbeantwortet, obwohl die Notiz existiert:
Alle Scores liegen unter MIN_SCORE (Drill 4). Das Retrieval
ist das Problem, nicht das LLM. Warum fängt main() in
__init__.py den Verbindungsfehler ab? Einmal zentral statt
in jedem der vier Befehle – mit Exit-Code 1 wie bei ask
(Tag 10).
Achtung: Lies die Antwort kritisch: „meist der Oncall-Leiter oder Ops Manager” steht in keiner Notiz, und
[oncall.md#Übergabe]belegt den zweiten Satz nicht. Eine Quellenangabe vom LLM ist eine Behauptung, kein Beweis – die Challenge prüft zumindest, ob zitierte Quellen überhaupt im Kontext standen.
Sicherheit:
docsearch search token -k 1findet den Abschnitt mitsk-lab-master-1234. Alles, was du indizierst, liegt im Klartext in.docsearch/und landet im Prompt. Secrets gehören nicht in Notizen, die du indizierst.
Fortschritt speichern? Kostenlos registrieren
Drill 7: Evaluation – Zahlen statt Bauchgefühl
Ein kleines Golden-Set: Frage plus die Datei, in der die Antwort steht.
cat > eval.json <<'EOF'
[
{"question": "Wie entsiegle ich Vault?", "source": "vault.md"},
{"question": "Pod startet immer wieder neu", "source": "k8s.md"},
{"question": "Wann läuft die Sicherung?", "source": "backup.md"},
{"question": "Wer wird nach 30 Minuten angerufen?", "source": "oncall.md"},
{"question": "Wie starte ich Tests?", "source": "python.md"},
{"question": "Warum bleibt mein Pod Pending?", "source": "k8s.md"},
{"question": "Wie hole ich Dateien aus dem Backup zurück?", "source": "backup.md"},
{"question": "Wie lange gilt ein Vault-Token maximal?", "source": "vault.md"}
]
EOF
uv run docsearch eval eval.jsonErwartet:
✔ Wie entsiegle ich Vault? -> vault.md
✔ Pod startet immer wieder neu -> k8s.md
✘ Wann läuft die Sicherung? -> oncall.md
✔ Wer wird nach 30 Minuten angerufen? -> oncall.md
✔ Wie starte ich Tests? -> python.md
✔ Warum bleibt mein Pod Pending? -> k8s.md
✔ Wie hole ich Dateien aus dem Backup zurü -> oncall.md
✔ Wie lange gilt ein Vault-Token maximal? -> vault.md
Hit@1: 0.75 Hit@3: 0.88 (n=8)
Warum zwei Zahlen? Hit@1 sagt, wie oft der beste
Treffer stimmt; Hit@3, ob die richtige Datei überhaupt
im Kontext landet – das ist für RAG entscheidend. Auffällig:
oncall.md#Übergabe taucht bei vielen Fragen vorn auf.
Kurze, generische Chunks werden so zu „Allzweck-Treffern”. Hebel, die du
jetzt messbar vergleichen kannst: mehrsprachiges Embedding-Modell
(DOCSEARCH_EMBED_MODEL), anderes Chunking, Hybrid-Suche mit
Schlüsselwörtern.
Tipp: Lege
eval.jsonmit ins Repo und lassdocsearch evalin CI laufen. Sinkt Hit@3 nach einer Änderung, weißt du es sofort.
Fortschritt speichern? Kostenlos registrieren
Drill 8: Tests ohne Modell
Embeddings und Chat werden gemockt; qdrant läuft echt, aber in
tmp_path mit 2-dimensionalen Vektoren.
mkdir -p tests
cat > tests/test_docsearch.py <<'EOF'
from pathlib import Path
from types import SimpleNamespace as NS
from unittest.mock import MagicMock
import numpy as np
from docsearch.chunking import Chunk, split_markdown
from docsearch.rag import NO_ANSWER, answer
from docsearch.store import Hit, open_store, rebuild, search
from docsearch.vectors import embed
def test_split_markdown_one_chunk_per_section(tmp_path: Path) -> None:
note = tmp_path / "ops.md"
note.write_text("# Ops\n\n## Restart\nsystemctl restart x\n\n## Logs\njournalctl\n")
chunks = split_markdown(note)
assert [c.source for c in chunks] == ["ops.md#Restart", "ops.md#Logs"]
assert chunks[0].text == "Restart\nsystemctl restart x"
def test_embed_normalizes() -> None:
client = MagicMock()
client.embeddings.create.return_value = NS(data=[NS(embedding=[3.0, 4.0])])
vec = embed(client, ["x"])
assert np.allclose(vec, [[0.6, 0.8]])
def test_store_roundtrip(tmp_path: Path) -> None:
chunks = [Chunk("a.md#A", "alpha"), Chunk("b.md#B", "beta")]
store = open_store(tmp_path / "db")
assert rebuild(store, chunks, np.array([[1.0, 0.0], [0.0, 1.0]])) == 2
hits = search(store, np.array([0.1, 0.9]), k=1)
store.close()
assert hits[0].source == "b.md#B"
def test_answer_skips_llm_when_scores_low() -> None:
client = MagicMock()
assert answer(client, "?", [Hit("a.md#A", "x", 0.1)]) == NO_ANSWER
client.chat.completions.create.assert_not_called()
def test_answer_sends_sources_in_prompt() -> None:
client = MagicMock()
client.chat.completions.create.return_value = NS(
choices=[NS(message=NS(content="ok [a.md#A]"))]
)
assert answer(client, "Frage?", [Hit("a.md#A", "Inhalt", 0.9)]) == "ok [a.md#A]"
prompt = client.chat.completions.create.call_args.kwargs["messages"][1]["content"]
assert "[a.md#A]" in prompt and "Frage?" in prompt
EOF
uv run pytest -q
uv run ruff check . && uv run --with mypy mypy --strict srcErwartet:
..... [100%]
5 passed in 0.44s
All checks passed!
Success: no issues found in 7 source files
Warum assert_not_called()? Der wichtigste Pfad ist der,
in dem das LLM nicht gefragt wird. Den beweist dir nur
ein Test.
Fortschritt speichern? Kostenlos registrieren
Drill 9: Das Tool ist fertig
uv tool install --editable .
export DOCSEARCH_DB=~/.cache/docsearch
docsearch index ~/py-lab/tag11-docsearch/notes
cd ~
docsearch ask "Wie lange gilt ein Vault-Token maximal?"
docsearch search "restic" -k 1Erwartet (Text variiert):
Installed 1 executable: docsearch
10 Chunks aus /Users/thomas/py-lab/tag11-docsearch/notes indiziert (384 Dim.)
Ein Vault-Token gilt maximal **32 Tage** [vault.md#Token erneuern].
Dazu finde ich nichts in deinen Notizen.
0.32 backup.md#Restore Wiederherstellen mit `restic restore latest --targ
Der angehängte „Dazu finde ich nichts”-Satz zeigt: Ein 3B-Modell
befolgt den System-Prompt wörtlich, aber nicht klug. Warum
DOCSEARCH_DB? Mit festem Index-Pfad funktioniert
docsearch aus jedem Verzeichnis. Hänge index
als Cronjob oder Git-Hook an deinen Notizen-Ordner, dann bleibt der
Index aktuell.
Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
cd ~/py-lab/tag11-docsearch
check() { if eval "$2" >/dev/null 2>&1; then echo "✔ $1"; else echo "✘ $1"; fi; }
DB=/tmp/ds-check
check "Embedding-Modell da" "ollama list | grep -q all-minilm"
check "Tests grün" "uv run pytest -q"
check "ruff sauber" "uv run ruff check ."
check "mypy --strict sauber" "uv run --with mypy mypy --strict src"
check "Index gebaut" "uv run docsearch index notes --db $DB | grep -q '10 Chunks'"
check "Hit@3 >= 0.8" \
"uv run docsearch eval eval.json --db $DB | grep -qE 'Hit@3: (0\.[89]|1\.00)'"
check "Antwort mit Quelle" \
"uv run docsearch ask 'Wann ist die Übergabe?' --db $DB | grep -q '\['"
rm -rf "$DB"Erwartet:
✔ Embedding-Modell da
✔ Tests grün
✔ ruff sauber
✔ mypy --strict sauber
✔ Index gebaut
✔ Hit@3 >= 0.8
✔ Antwort mit Quelle
Challenge
Das LLM erfindet manchmal Quellen. Ergänze
unknown_citations(text, hits), die alle zitierten
[datei.md#Abschnitt] zurückgibt, die nicht
unter den relevanten Treffern waren, und lass docsearch ask
dafür eine Warnung auf stderr ausgeben.
Hinweis: Ein regulärer Ausdruck auf
\[...\.md#...\] plus eine Mengendifferenz
(set - set) reicht.
Lösung
In cli.py den Import auf
from docsearch.rag import answer, unknown_citations ändern
und ask so enden lassen:
text = answer(client, question, hits)
typer.echo(text)
for source in unknown_citations(text, hits):
typer.secho(f"Warnung: Quelle {source} nicht im Kontext", fg="red", err=True)Dann Funktion und Test ergänzen:
cat >> src/docsearch/rag.py <<'EOF'
CITATION = re.compile(r"\[([^\[\]]+\.md#[^\[\]]+)\]")
def unknown_citations(text: str, hits: list[Hit]) -> list[str]:
"""Zitierte Quellen, die gar nicht im Kontext standen."""
allowed = {h.source for h in hits if h.score >= MIN_SCORE}
return sorted(set(CITATION.findall(text)) - allowed)
EOF
perl -pi -e 's/^import os$/import os\nimport re/' src/docsearch/rag.py
cat >> tests/test_docsearch.py <<'EOF'
def test_unknown_citations_flags_invented_sources() -> None:
from docsearch.rag import unknown_citations
hits = [Hit("a.md#A", "x", 0.9), Hit("b.md#B", "y", 0.1)]
text = "Eins [a.md#A]. Zwei [b.md#B]. Drei [c.md#C]."
assert unknown_citations(text, hits) == ["b.md#B", "c.md#C"]
EOF
uv run pytest -qErwartet:
...... [100%]
6 passed in 0.47s
Warum zählt b.md#B als unbekannt, obwohl es ein Treffer
war? Mit Score 0,1 lag es unter MIN_SCORE und stand gar
nicht im Prompt.
Fortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- Berechtigungen gehören in den Index: Jeder Chunk trägt ACL-Metadaten, die Suche filtert nach dem Nutzer – sonst beantwortet RAG Fragen aus Dokumenten, die der Fragende nie sehen durfte.
- Vor dem Indizieren Secrets und personenbezogene Daten scannen und entfernen (z. B. mit gitleaks-Regeln); der Vektorindex ist eine Kopie aller Daten.
- qdrant als Server (oder pgvector) mit Backup, TLS und API-Key; der lokale Modus ist nur für Einzelplatz-Tools.
- Embedding-Modell und Chunking versionieren: ein Modellwechsel erfordert Neu-Indizierung; Vektoren verschiedener Modelle sind nicht vergleichbar.
- Golden-Set pflegen und Hit@k, Antwortqualität (LLM-as-Judge oder Stichproben) und „Weiß ich nicht”-Quote als Metriken beobachten.