Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 10: LLM-APIs – der Terminal-Assistent ask

Ziel: Ein lokales LLM per Python ansprechen – Chat, Streaming, Temperatur, strukturierte Ausgabe, Messung – und daraus das CLI-Tool ask bauen · Dauer: ca. 120 min · Voraussetzung: Tag 9

Briefing

  • Ollama spricht unter /v1 die OpenAI-kompatible API. Das openai-SDK mit base_url ist damit dein Standard-Client – gegen Ollama, vLLM, Mistral oder OpenAI.
  • Ein Chat-Aufruf ist eine Liste von Messages (system, user, assistant) plus Parameter wie temperature.
  • Streaming = Server-Sent Events: Token kommen einzeln, die erste Ausgabe nach der TTFT.
  • Strukturierte Ausgabe: ein pydantic-Modell als JSON-Schema an das Modell geben und die Antwort validieren.
  • Ein 3B-Modell irrt sich oft. LLM-Ausgaben sind Daten, nie Befehle.
ask "Frage" ──> llm.py ──openai-SDK──> http://127.0.0.1:11434/v1 ──> ministral-3:3b
   ▲                                          │
   └────────── Text-Stücke (Stream) ◄─────────┘

Drill 1: Projekt anlegen und Ollama prüfen

cd ~/py-lab
uv init -q --package --name ask tag10-ask
cd tag10-ask
uv add -q openai pydantic typer httpx
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 'openai|pydantic|typer|httpx'
curl -s http://127.0.0.1:11434/v1/models | python3 -m json.tool | grep '"id"'

Erwartet (gekürzt, Versionen können abweichen):

├── httpx v0.28.1
├── openai v3.28.0
├── pydantic v2.14.0
├── typer v0.27.3
            "id": "ministral-3:3b",

Warum httpx extra? Das aktuelle openai-SDK bringt es nicht mehr zwingend mit; du brauchst es in Drill 4 direkt.

Tipp: Fehlt das Modell: ollama pull ministral-3:3b (3,0 GB). Läuft Ollama nicht, kommt bei curl gar nichts zurück.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Der erste Chat-Aufruf

Die gesamte LLM-Logik kommt in llm.py, das CLI später in cli.py. Erster Teil:

cat > src/ask/llm.py <<'EOF'
"""Dünne Schicht um den OpenAI-kompatiblen Client (Ollama lokal)."""

import os
import time
from collections.abc import Iterator
from dataclasses import dataclass

from openai import OpenAI
from openai.types.chat import ChatCompletionMessageParam
from pydantic import BaseModel

BASE_URL = os.environ.get("ASK_BASE_URL", "http://127.0.0.1:11434/v1")
MODEL = os.environ.get("ASK_MODEL", "ministral-3:3b")
SYSTEM = "Du bist ein knapper Linux-Assistent. Antworte auf Deutsch, max. 3 Sätze."


def make_client() -> OpenAI:
    # Ollama ignoriert den Key, das SDK verlangt aber einen.
    key = os.environ.get("ASK_API_KEY", "ollama")
    return OpenAI(base_url=BASE_URL, api_key=key, timeout=120, max_retries=1)


def build_messages(
    question: str, system: str = SYSTEM
) -> list[ChatCompletionMessageParam]:
    return [
        {"role": "system", "content": system},
        {"role": "user", "content": question},
    ]


def ask(
    client: OpenAI, question: str, *, system: str = SYSTEM, temperature: float = 0.2
) -> str:
    resp = client.chat.completions.create(
        model=MODEL,
        messages=build_messages(question, system),
        temperature=temperature,
    )
    return resp.choices[0].message.content or ""
EOF
uv run python -c "
from ask.llm import ask, make_client
print(ask(make_client(), 'Was ist ein Inode?'))
"

Erwartet (Text variiert):

Ein **Inode** ist eine numerische Datenstruktur in Unix/Linux, die **Datei- und
Verzeichnisinformationen** wie Größe, Zugriffsrechte oder Besitzer speichert. ...

Warum? Basis-URL, Modell und Key kommen aus Umgebungsvariablen. So zeigst du ask später ohne Codeänderung auf vLLM oder eine Cloud-API. ChatCompletionMessageParam macht die Message-Liste für mypy prüfbar.

Sicherheit: Echte Keys (z. B. MISTRAL_API_KEY) nur über ASK_API_KEY aus der Umgebung oder einem Secret-Store – nie in den Code, nie in pyproject.toml.

Fortschritt speichern? Kostenlos registrieren

Drill 3: System-Prompt und Temperatur

uv run python -c "
from ask.llm import ask, make_client
c = make_client()
q = 'Nenne einen Namen für einen Monitoring-Server. Nur das Wort.'
for t in (0, 0, 1.5, 1.5):
    print(t, ask(c, q, temperature=t))
print(ask(c, 'Was ist DNS?', system='Du bist ein Pirat. Ein Satz.'))
"

Erwartet (variiert, gekürzt):

0 **ServerWatch**
0 **ServerWatch**
1.5 **ServerOverwatch**
1.5 **"Promevo"** (Kurz für *Performance Monitor Evader Omen*)
*"Arrr, du fragst nach dem *Dee-En-See*-System, das wie 'ne geheime Kette ...

Warum? temperature=0 wählt fast immer das wahrscheinlichste Token – reproduzierbar, gut für Befehle und JSON. Hohe Werte streuen – gut für Ideen, schlecht für Fakten. Der System-Prompt setzt Rolle und Format, bevor die Frage kommt.

Fortschritt speichern? Kostenlos registrieren

Drill 4: Streaming – erst roh, dann bequem

Erst ohne SDK, damit du siehst, was über die Leitung geht:

cat > sse.py <<'EOF'
import json

import httpx

body = {
    "model": "ministral-3:3b",
    "stream": True,
    "messages": [{"role": "user", "content": "Sag hallo."}],
}
url = "http://127.0.0.1:11434/v1/chat/completions"
with httpx.stream("POST", url, json=body, timeout=60) as r:
    print(r.status_code, r.headers["content-type"])
    for line in r.iter_lines():
        if line.startswith("data: {"):
            chunk = json.loads(line.removeprefix("data: "))
            print(repr(chunk["choices"][0]["delta"].get("content")))
        elif line:
            print(line)
EOF
uv run python sse.py | sed -n '1,4p;$p'

Erwartet (gekürzt):

200 text/event-stream
'*S'
'chn'
'eller'
data: [DONE]

Warum? Jede data:-Zeile ist ein JSON-Chunk mit einem delta. [DONE] beendet den Stream. Genau das parst das SDK für dich.

Jetzt die SDK-Variante mit Messung. stream_answer ist ein Generator: Er liefert Text-Stücke und zum Schluss ein Stats-Objekt.

cat >> src/ask/llm.py <<'EOF'


@dataclass
class Stats:
    ttft_s: float
    total_s: float
    prompt_tokens: int
    completion_tokens: int

    @property
    def tokens_per_s(self) -> float:
        gen = self.total_s - self.ttft_s
        return self.completion_tokens / gen if gen > 0 else 0.0


def stream_answer(
    client: OpenAI, question: str, *, system: str = SYSTEM, temperature: float = 0.2
) -> Iterator[str | Stats]:
    """Liefert Text-Stücke und zum Schluss genau ein Stats-Objekt."""
    start = time.perf_counter()
    ttft = 0.0
    usage = None
    chunks = client.chat.completions.create(
        model=MODEL,
        messages=build_messages(question, system),
        temperature=temperature,
        stream=True,
        stream_options={"include_usage": True},
    )
    for chunk in chunks:
        if chunk.usage:
            usage = chunk.usage
        if chunk.choices and chunk.choices[0].delta.content:
            if not ttft:
                ttft = time.perf_counter() - start
            yield chunk.choices[0].delta.content
    total = time.perf_counter() - start
    p, c = (usage.prompt_tokens, usage.completion_tokens) if usage else (0, 0)
    yield Stats(ttft, total, p, c)
EOF
uv run python -c "
from ask.llm import make_client, stream_answer
for x in stream_answer(make_client(), 'Was macht chmod 600?'):
    print(repr(x), end=' ')
"

Erwartet (gekürzt, Werte variieren):

'`' 'ch' 'mod' ' 6' '0' '0' '`' ' gibt' ' dem' ' Besitzer' ' **' 'L' 'ese' '-/'
'Sch' 'reib' '-/' 'Aus' 'führ' 'ungs' 'rechte' '**' ... ' darf' '.'
Stats(ttft_s=0.24462983300327323, total_s=1.9518006660218816, prompt_tokens=37,
completion_tokens=59)

Warum stream_options? Ohne include_usage schickt der Server beim Streaming keine Token-Zahlen. Der letzte Chunk hat dann leere choices und nur usage.

Achtung: Lies die Antwort genau: chmod 600 gibt keine Ausführungsrechte. Ein 3B-Modell klingt sicher und liegt trotzdem daneben. TTFT 0,24 s und rund 35–40 Tokens/s sind typisch für Apple Silicon.

Fortschritt speichern? Kostenlos registrieren

Drill 5: Strukturierte Ausgabe mit pydantic

ask --cmd soll keinen Fließtext liefern, sondern ein prüfbares Objekt.

cat >> src/ask/llm.py <<'EOF'


class Command(BaseModel):
    command: str
    explanation: str
    dangerous: bool


CMD_SYSTEM = (
    "Du schlägst genau EINEN vollständigen Shell-Befehl (macOS/Linux) mit allen "
    "Argumenten vor, explanation in einem Satz. dangerous=true, wenn er Daten "
    "löscht oder Rechte ändert."
)


def suggest_command(client: OpenAI, task: str) -> Command:
    resp = client.chat.completions.parse(
        model=MODEL,
        messages=build_messages(task, CMD_SYSTEM),
        response_format=Command,
        temperature=0,
    )
    parsed = resp.choices[0].message.parsed
    if parsed is None:
        raise ValueError("Modell lieferte kein gültiges JSON")
    return parsed
EOF
uv run python -c "
from ask.llm import make_client, suggest_command
print(suggest_command(make_client(), 'zeige die 5 größten Ordner in ~/Downloads'))
"

Erwartet (variiert):

command='du -h -max-depth 1 ~/Downloads | sort -rh | head -n 6' explanation='Listet
die fünf größten Ordner im `~/Downloads`-Verzeichnis ...' dangerous=False

Warum? parse() schickt das JSON-Schema von Command als response_format. Ollama zwingt das Modell per Grammatik in dieses Schema, pydantic validiert das Ergebnis. Die Form stimmt also garantiert – der Inhalt nicht: -max-depth gibt es so weder unter macOS (-d 1) noch unter Linux (--max-depth=1).

Sicherheit: ask führt Befehle niemals aus. Wer LLM-Ausgaben an subprocess oder sh -c gibt, baut eine Remote-Code-Execution mit Zufallsgenerator.

Fortschritt speichern? Kostenlos registrieren

Drill 6: Das CLI mit typer

cat > src/ask/cli.py <<'EOF'
"""ask – Terminal-Assistent gegen ein lokales LLM."""

import sys
from typing import Annotated

import openai
import typer

from ask.llm import SYSTEM, Stats, make_client, stream_answer, suggest_command

app = typer.Typer(add_completion=False)
MAX_STDIN = 8000  # Zeichen; schützt das kleine Kontextfenster


@app.command()
def main(
    question: str,
    system: Annotated[str, typer.Option("--system", "-s")] = SYSTEM,
    temperature: Annotated[float, typer.Option("--temperature", "-t")] = 0.2,
    stats: Annotated[bool, typer.Option(help="TTFT und Tokens/s anzeigen")] = False,
    cmd: Annotated[bool, typer.Option(help="Shell-Befehl als JSON")] = False,
) -> None:
    """Stellt QUESTION an das Modell. Text von stdin wird als Kontext angehängt."""
    if not sys.stdin.isatty():
        context = sys.stdin.read()[:MAX_STDIN]
        if context.strip():
            question = f"{question}\n\n---\n{context}"
    client = make_client()
    try:
        if cmd:
            result = suggest_command(client, question)
            typer.echo(result.model_dump_json(indent=2))
            if result.dangerous:
                typer.secho("Achtung: gefährlicher Befehl!", fg="red", err=True)
            return
        for part in stream_answer(
            client, question, system=system, temperature=temperature
        ):
            if isinstance(part, Stats):
                typer.echo()
                if stats:
                    s = part
                    msg = f"[ttft {s.ttft_s:.2f}s · {s.prompt_tokens} in / "
                    msg += f"{s.completion_tokens} out · {s.tokens_per_s:.0f} tok/s]"
                    typer.secho(msg, fg="cyan", err=True)
            else:
                typer.echo(part, nl=False)
    except openai.APIConnectionError:
        typer.secho("Fehler: LLM nicht erreichbar (läuft Ollama?)", fg="red", err=True)
        raise typer.Exit(code=1) from None
    except (openai.APIStatusError, ValueError) as exc:
        typer.secho(f"Fehler: {exc}", fg="red", err=True)
        raise typer.Exit(code=1) from exc
EOF
cat > src/ask/__init__.py <<'EOF'
"""ask – Terminal-Assistent gegen ein lokales LLM."""

from ask.cli import app


def main() -> None:
    app()
EOF
cat > src/ask/__main__.py <<'EOF'
from ask import main

main()
EOF
uv run ask "Was ist ein Zombie-Prozess?" --stats < /dev/null
uv run ask --cmd "alle Dateien größer 100 MB im Home finden" < /dev/null
ASK_BASE_URL=http://127.0.0.1:9/v1 uv run ask hallo < /dev/null; echo "exit=$?"

Erwartet (Text variiert, gekürzt):

Ein Zombie-Prozess (auch *Orphan Process* genannt) ist ein abgestellter Prozess,
dessen Elternprozess gestorben ist, aber dessen Kern noch läuft. ...
[ttft 0.17s · 36 in / 87 out · 38 tok/s]
{
  "command": "find ~/ -type f -size +100M -exec rm -f {} +",
  "explanation": "Löscht alle Dateien im Home-Verzeichnis größer als 100 MB ...",
  "dangerous": true
}
Achtung: gefährlicher Befehl!
Fehler: LLM nicht erreichbar (läuft Ollama?)
exit=1

Warum < /dev/null? Ohne Terminal an stdin (Skripte, CI) würde ask sonst auf Eingabe warten. Und schau genau hin: Gefragt war finden, das Modell schlägt löschen vor – das dangerous-Flag fängt es, ein Mensch muss trotzdem lesen. Auch die Zombie-Erklärung ist falsch (ein Zombie ist beendet und wartet nur auf wait() des Elternprozesses).

Kontext per Pipe – das macht ask im Alltag nützlich:

printf '%s\n' \
  'Oct 10 08:12:01 web1 sshd[812]: Failed password for root from 203.0.113.7' \
  'Oct 10 08:12:03 web1 sshd[812]: Failed password for root from 203.0.113.7' \
  > auth.log
uv run ask "Was passiert hier? Ein Satz." --stats < auth.log

Erwartet (variiert):

Ein Angreifer versucht sich mit falschen Passwörtern als **Root** zu
authentifizieren – ... die IP (`203.0.113.7`) wird als verdächtig markiert.
[ttft 0.39s · 130 in / 54 out · 40 tok/s]

Achtung: Was du pipest, geht ans Modell. Lokal ist das unkritisch – bei einer Cloud-API landen Logs mit IPs, Usernamen oder Tokens beim Anbieter. MAX_STDIN begrenzt nur die Länge, nicht den Inhalt.

Fortschritt speichern? Kostenlos registrieren

Drill 7: Tests mit gemocktem LLM

Unit-Tests dürfen kein echtes Modell brauchen: langsam, nicht deterministisch, in CI nicht vorhanden. Ein MagicMock spielt den Client, SimpleNamespace die Chunks.

mkdir -p tests
cat > tests/test_ask.py <<'EOF'
from types import SimpleNamespace as NS
from unittest.mock import MagicMock

import pytest
from typer.testing import CliRunner

from ask import cli
from ask.llm import Command, Stats, build_messages, stream_answer, suggest_command


def fake_chunk(text: str | None, usage: object = None) -> NS:
    choices = [NS(delta=NS(content=text))] if text is not None else []
    return NS(choices=choices, usage=usage)


@pytest.fixture
def client() -> MagicMock:
    c = MagicMock()
    c.chat.completions.create.return_value = iter(
        [
            fake_chunk("Hal"),
            fake_chunk("lo"),
            fake_chunk(None, NS(prompt_tokens=5, completion_tokens=2)),
        ]
    )
    return c


def test_build_messages_has_system_first() -> None:
    msgs = build_messages("Frage", "Sys")
    assert [m["role"] for m in msgs] == ["system", "user"]


def test_stream_yields_text_then_stats(client: MagicMock) -> None:
    parts = list(stream_answer(client, "Hi"))
    assert parts[:2] == ["Hal", "lo"]
    assert isinstance(parts[-1], Stats)
    assert parts[-1].completion_tokens == 2
    kwargs = client.chat.completions.create.call_args.kwargs
    assert kwargs["stream"] is True


def test_suggest_command_raises_on_empty_parse() -> None:
    c = MagicMock()
    c.chat.completions.parse.return_value = NS(choices=[NS(message=NS(parsed=None))])
    with pytest.raises(ValueError):
        suggest_command(c, "irgendwas")


def test_cli_cmd_warns_on_dangerous(monkeypatch: pytest.MonkeyPatch) -> None:
    cmd = Command(command="rm -rf /tmp/x", explanation="löscht", dangerous=True)
    monkeypatch.setattr(cli, "make_client", MagicMock())
    monkeypatch.setattr(cli, "suggest_command", lambda client, task: cmd)
    result = CliRunner().invoke(cli.app, ["--cmd", "aufräumen"])
    assert result.exit_code == 0
    assert '"dangerous": true' in result.output
    assert "gefährlich" in result.output


def test_cli_streams_answer(monkeypatch: pytest.MonkeyPatch, client: MagicMock) -> None:
    monkeypatch.setattr(cli, "make_client", lambda: client)
    result = CliRunner().invoke(cli.app, ["Hi"])
    assert result.exit_code == 0
    assert result.output.strip() == "Hallo"
EOF
uv run pytest -q
uv run ruff format . && uv run ruff check .
uv run --with mypy mypy --strict src

Erwartet:

.....                                                                    [100%]
5 passed in 0.27s
7 files left unchanged
All checks passed!
Success: no issues found in 4 source files

Warum monkeypatch.setattr(cli, "make_client", ...)? Das CLI hat make_client per from … import in seinen eigenen Namensraum geholt. Du patchst den Namen dort, wo er benutzt wird, nicht dort, wo er definiert ist.

Fortschritt speichern? Kostenlos registrieren

Drill 8: Das Tool ist fertig

uv tool install --editable .
cd ~
echo 'df -h zeigt 97% auf /' | ask "Was soll ich tun? Zwei Sätze." --stats
ask --help | head -4

Erwartet (Text variiert):

Installed 1 executable: ask
Lösche temporäre Dateien mit `sudo journalctl --vacuum-size=100M` oder `sudo apt
clean` (Debian/Ubuntu).
Prüfe Speicherplatz mit `du -sh /` und lösche unnötige Pakete (`apt autoremove`).
[ttft 0.33s · 48 in / 65 out · 39 tok/s]

 Usage: ask [OPTIONS] {question}

 Stellt QUESTION an das Modell. Text von stdin wird als Kontext angehängt.

Warum --editable? Änderungen in ~/py-lab/tag10-ask/src wirken sofort, ohne Neuinstallation (Tag 5). Entfernen mit uv tool uninstall ask.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

cd ~/py-lab/tag10-ask
check() { if eval "$2" >/dev/null 2>&1; then echo "✔ $1"; else echo "✘ $1"; fi; }
check "Module da" "test -f src/ask/llm.py -a -f src/ask/cli.py"
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 "Ollama läuft" "curl -sf http://127.0.0.1:11434/v1/models"
check "ask antwortet" "uv run ask -t 0 'Sag OK' < /dev/null | grep -q ."
check "Exit 1 ohne LLM" \
  "! ASK_BASE_URL=http://127.0.0.1:9/v1 uv run ask x < /dev/null"
uv run ask -t 0 "Antworte nur mit: OK" < /dev/null

Erwartet (letzte Zeile variiert):

✔ Module da
✔ Tests grün
✔ ruff sauber
✔ mypy --strict sauber
✔ Ollama läuft
✔ ask antwortet
✔ Exit 1 ohne LLM
Verstanden. Was brauchst du genau?

Warum antwortet ask nicht mit „OK”? Der System-Prompt aus SYSTEM gewinnt gegen die Bitte im User-Prompt – kleine Modelle folgen Formatwünschen unzuverlässig.

Challenge

Gib ask eine Option --max-tokens N, die die Antwortlänge hart begrenzt, und schreibe einen Test, der prüft, dass der Wert beim Client ankommt.

Hinweis: Der Chat-Endpunkt kennt den Parameter max_tokens; None heißt „kein Limit”.

Lösung

In src/ask/llm.py Signatur und Aufruf von stream_answer erweitern:

def stream_answer(
    client: OpenAI,
    question: str,
    *,
    system: str = SYSTEM,
    temperature: float = 0.2,
    max_tokens: int | None = None,
) -> Iterator[str | Stats]:
    ...
    chunks = client.chat.completions.create(
        model=MODEL,
        messages=build_messages(question, system),
        temperature=temperature,
        max_tokens=max_tokens,
        stream=True,
        stream_options={"include_usage": True},
    )

In src/ask/cli.py die Option ergänzen und durchreichen:

    max_tokens: Annotated[int | None, typer.Option(min=1)] = None,
    ...
        for part in stream_answer(
            client,
            question,
            system=system,
            temperature=temperature,
            max_tokens=max_tokens,
        ):

Test anhängen und prüfen:

cat >> tests/test_ask.py <<'EOF'


def test_max_tokens_is_passed(client: MagicMock) -> None:
    list(stream_answer(client, "Hi", max_tokens=50))
    assert client.chat.completions.create.call_args.kwargs["max_tokens"] == 50
EOF
uv run pytest -q
uv run ask --max-tokens 10 "Erkläre TCP ausführlich." --stats < /dev/null

Erwartet:

......                                                                   [100%]
6 passed in 0.73s
TCP (Transmission Control Protocol) ist ein **
[ttft 0.29s · 36 in / 10 out · 41 tok/s]

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Modell, URL und Key kommen aus Konfiguration oder Secret-Store (Vault/OpenBao), nie aus dem Code; vor die Modelle gehört ein Gateway mit Auth, Rate-Limit und Audit-Log.
  • Daten-Klassifizierung vor jedem Aufruf: Logs mit personenbezogenen Daten oder Secrets dürfen nicht an externe APIs – Redaction vor dem Senden.
  • Modell-Version pinnen (Tag plus Digest aus ollama list festhalten) und Prompts versionieren; jede Änderung braucht einen Eval-Lauf, nicht nur grüne Unit-Tests.
  • TTFT, Tokens/s und Fehlerquote als Metriken exportieren (OpenTelemetry); Timeouts und Retries bewusst setzen.
  • LLM-Ausgaben nie automatisch ausführen; strukturierte Ausgaben immer validieren und Grenzen (Länge, erlaubte Befehle) im Code prüfen.