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
askbauen · Dauer: ca. 120 min · Voraussetzung: Tag 9
Briefing
- Ollama spricht unter
/v1die OpenAI-kompatible API. Dasopenai-SDK mitbase_urlist damit dein Standard-Client – gegen Ollama, vLLM, Mistral oder OpenAI. - Ein Chat-Aufruf ist eine Liste von Messages
(
system,user,assistant) plus Parameter wietemperature. - 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 beicurlgar 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 überASK_API_KEYaus der Umgebung oder einem Secret-Store – nie in den Code, nie inpyproject.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 600gibt 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:
askführt Befehle niemals aus. Wer LLM-Ausgaben ansubprocessodersh -cgibt, 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.logErwartet (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_STDINbegrenzt 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 srcErwartet:
..... [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 -4Erwartet (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/nullErwartet (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/nullErwartet:
...... [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 listfesthalten) 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.