Zum Inhalt springen
Trainingslager IT-Trainingslager

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 notes

Erwartet:

backup.md   k8s.md      oncall.md   python.md   vault.md

Tipp: all-minilm ist 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 .docsearch

Erwartet:

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 src

Erwartet:

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 1 findet den Abschnitt mit sk-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.json

Erwartet:

✔ 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.json mit ins Repo und lass docsearch eval in 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 src

Erwartet:

.....                                                                    [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 1

Erwartet (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 -q

Erwartet:

......                                                                   [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.