Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 12: Go für KI – ask, docsearch und ops-mcp

Ziel: Ein lokales LLM per net/http ansprechen – gestreamt, als geprüftes JSON und mit Tool Calling –, Runbooks semantisch durchsuchen und Ops-Tools als MCP-Server bereitstellen · Dauer: ca. 180 min · Voraussetzung: Tag 11

Briefing

  • Ollama spricht unter /v1 die OpenAI-API; derselbe Code läuft gegen vLLM oder Mistral (nur LLM_BASE_URL, LLM_API_KEY, LLM_MODEL ändern).
  • Kein SDK: net/http, encoding/json und ein bufio.Scanner für Server-Sent Events reichen.
  • Strukturierte Ausgabe per JSON-Schema – und trotzdem selbst validieren.
  • Tool Calling: Das Modell wünscht einen Aufruf, dein Code entscheidet und führt aus.
  • MCP mit dem offiziellen Go-SDK macht dieselben Tools für jeden KI-Client nutzbar.
ask ---------> /v1/chat/completions (stream | json_schema | tools) --> ministral-3:3b
docsearch ---> /v1/embeddings --> Kosinus-Suche über docs/*.md       --> all-minilm
KI-Client <--stdio JSON-RPC--> ops-mcp --> internal/tools.DiskFree

Drill 1: Modul und HTTP-Client

Prüfe zuerst, ob Ollama läuft und das Modell da ist:

curl -s http://127.0.0.1:11434/v1/models | jq -r '.data[].id' | grep ministral
mkdir -p ~/go-lab/tag12-ask/{cmd/ask,cmd/docsearch,cmd/ops-mcp,docs}
mkdir -p ~/go-lab/tag12-ask/internal/{llm,search,tools}
cd ~/go-lab/tag12-ask
go mod init example.com/ask
cat > .golangci.yml <<'EOF'
version: "2"
linters:
  exclusions:
    presets: [std-error-handling] # fmt.Fprint*, Close & Co. nicht anmahnen
EOF

Erwartet:

ministral-3:3b
go: creating new go.mod: module example.com/ask
go: to add module requirements and sums:
    go mod tidy

Den Hinweis auf go mod tidy ignorierst du vorerst – bis Drill 6 brauchst du nur die Standardbibliothek. Die .golangci.yml kennst du aus Tag 5.

Die Typen bilden nur die Felder der OpenAI-API ab, die du brauchst. post kapselt JSON, Auth-Header und Statusprüfung.

cat > internal/llm/llm.go <<'EOF'
// Package llm spricht die OpenAI-kompatible API (Ollama, vLLM, Mistral) an.
package llm

import (
    "bytes"
    "context"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "os"
    "strings"
    "time"
)

type Message struct {
    Role       string     `json:"role"`
    Content    string     `json:"content"`
    ToolCalls  []ToolCall `json:"tool_calls,omitempty"`
    ToolCallID string     `json:"tool_call_id,omitempty"`
}

type ToolCall struct {
    ID       string `json:"id"`
    Type     string `json:"type"`
    Function struct {
        Name      string `json:"name"`
        Arguments string `json:"arguments"` // JSON als String
    } `json:"function"`
}

type Request struct {
    Model          string    `json:"model"`
    Messages       []Message `json:"messages"`
    Stream         bool      `json:"stream,omitempty"`
    Tools          []any     `json:"tools,omitempty"`
    ResponseFormat any       `json:"response_format,omitempty"`
}

type Client struct {
    BaseURL, Key, Model string
    HTTP                *http.Client
}

// FromEnv liest LLM_BASE_URL, LLM_API_KEY und LLM_MODEL (Defaults: Ollama).
func FromEnv() *Client {
    return &Client{
        BaseURL: env("LLM_BASE_URL", "http://127.0.0.1:11434/v1"),
        Key:     os.Getenv("LLM_API_KEY"),
        Model:   env("LLM_MODEL", "ministral-3:3b"),
        HTTP:    &http.Client{Timeout: 5 * time.Minute},
    }
}

func env(k, def string) string {
    if v := os.Getenv(k); v != "" {
        return v
    }
    return def
}

// post schickt JSON und liefert die Antwort nur bei Status 200.
func (c *Client) post(ctx context.Context, path string, body any) (
    *http.Response, error) {
    b, err := json.Marshal(body)
    if err != nil {
        return nil, err
    }
    req, err := http.NewRequestWithContext(ctx, http.MethodPost,
        c.BaseURL+path, bytes.NewReader(b))
    if err != nil {
        return nil, err
    }
    req.Header.Set("Content-Type", "application/json")
    if c.Key != "" {
        req.Header.Set("Authorization", "Bearer "+c.Key)
    }
    resp, err := c.HTTP.Do(req)
    if err != nil {
        return nil, err
    }
    if resp.StatusCode != http.StatusOK {
        defer resp.Body.Close()
        msg, _ := io.ReadAll(io.LimitReader(resp.Body, 512))
        return nil, fmt.Errorf("%s: %s: %s", path, resp.Status,
            strings.TrimSpace(string(msg)))
    }
    return resp, nil
}
EOF
go vet ./...

Erwartet: keine Ausgabe.

Warum? Ohne Key bleibt der Authorization-Header weg – Ollama braucht keinen, Cloud-APIs schon. Fehlerbodys werden auf 512 Byte begrenzt, damit dir kein HTML-Fehlerdokument das Terminal flutet.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Streaming mit Server-Sent Events

Bei "stream": true kommt die Antwort als Zeilen data: {...}. Schau dir das Rohformat einmal an:

curl -sN http://127.0.0.1:11434/v1/chat/completions -d '{"model":"ministral-3:3b",
  "stream":true,"messages":[{"role":"user","content":"Sag Hallo"}]}' > sse.txt
grep -o '"delta":{[^}]*}' sse.txt | head -3; grep DONE sse.txt; rm sse.txt

Erwartet (Text variiert):

"delta":{"role":"assistant","content":"**"}
"delta":{"content":"H"}
"delta":{"content":"allo"}
data: [DONE]

Genau das parst Stream: Präfix abschneiden, JSON lesen, delta.content weiterreichen, bei [DONE] aufhören.

cat > internal/llm/chat.go <<'EOF'
package llm

import (
    "bufio"
    "context"
    "encoding/json"
    "errors"
    "fmt"
    "strings"
)

// Chat schickt eine Anfrage ohne Streaming und liefert die Antwort.
func (c *Client) Chat(ctx context.Context, r Request) (Message, error) {
    r.Model, r.Stream = c.Model, false
    resp, err := c.post(ctx, "/chat/completions", r)
    if err != nil {
        return Message{}, err
    }
    defer resp.Body.Close()
    var out struct {
        Choices []struct{ Message Message } `json:"choices"`
    }
    if err := json.NewDecoder(resp.Body).Decode(&out); err != nil {
        return Message{}, fmt.Errorf("antwort lesen: %w", err)
    }
    if len(out.Choices) == 0 {
        return Message{}, errors.New("antwort ohne choices")
    }
    return out.Choices[0].Message, nil
}

// Stream ruft onDelta für jedes Textstück aus dem SSE-Stream auf.
func (c *Client) Stream(ctx context.Context, msgs []Message,
    onDelta func(string)) error {
    resp, err := c.post(ctx, "/chat/completions",
        Request{Model: c.Model, Messages: msgs, Stream: true})
    if err != nil {
        return err
    }
    defer resp.Body.Close()
    sc := bufio.NewScanner(resp.Body)
    for sc.Scan() {
        data, ok := strings.CutPrefix(sc.Text(), "data: ")
        if !ok {
            continue // Leerzeilen und Kommentare
        }
        if data == "[DONE]" {
            return nil
        }
        var chunk struct {
            Choices []struct {
                Delta struct{ Content string } `json:"delta"`
            } `json:"choices"`
        }
        if err := json.Unmarshal([]byte(data), &chunk); err != nil {
            return fmt.Errorf("sse-chunk: %w", err)
        }
        if len(chunk.Choices) > 0 {
            onDelta(chunk.Choices[0].Delta.Content)
        }
    }
    if err := sc.Err(); err != nil {
        return err
    }
    return errors.New("stream ohne [DONE] beendet")
}
EOF

Der Test simuliert den Server mit httptest – kein Modell nötig:

cat > internal/llm/llm_test.go <<'EOF'
package llm

import (
    "context"
    "fmt"
    "net/http"
    "net/http/httptest"
    "strings"
    "testing"
)

// fake prüft den Key und streamt drei Textstücke per SSE.
func fake(t *testing.T) *Client {
    srv := httptest.NewServer(http.HandlerFunc(
        func(w http.ResponseWriter, r *http.Request) {
            if r.Header.Get("Authorization") != "Bearer sk-lab-1234" {
                http.Error(w, "kein key", http.StatusUnauthorized)
                return
            }
            w.Header().Set("Content-Type", "text/event-stream")
            for _, s := range []string{"Hal", "lo", " Welt"} {
                fmt.Fprintf(w, "data: {\"choices\":[{\"delta\":"+
                    "{\"content\":%q}}]}\n\n", s)
            }
            fmt.Fprint(w, "data: [DONE]\n\n")
        }))
    t.Cleanup(srv.Close)
    return &Client{BaseURL: srv.URL, Key: "sk-lab-1234", HTTP: srv.Client()}
}

func TestStream(t *testing.T) {
    var got strings.Builder
    err := fake(t).Stream(context.Background(), nil,
        func(s string) { got.WriteString(s) })
    if err != nil || got.String() != "Hallo Welt" {
        t.Fatalf("got %q, err %v", got.String(), err)
    }
}

func TestStatusError(t *testing.T) {
    c := fake(t)
    c.Key = "falsch"
    _, err := c.Chat(context.Background(), Request{})
    if err == nil || !strings.Contains(err.Error(), "401") {
        t.Fatalf("erwartet 401, got %v", err)
    }
}
EOF
go test -v ./internal/llm

Erwartet (gekürzt):

--- PASS: TestStream (0.00s)
--- PASS: TestStatusError (0.00s)
ok      example.com/ask/internal/llm    0.164s

Warum? bufio.Scanner liest zeilenweise; Leerzeilen und Kommentare ohne data: überspringt der Code. Ein Stream ohne [DONE] ist abgerissen – das meldest du als Fehler statt eine halbe Antwort als ganze auszugeben.

Fortschritt speichern? Kostenlos registrieren

Drill 3: Strukturierte Ausgabe mit JSON-Schema

response_format mit json_schema zwingt das Modell in eine feste Form. Kleine Modelle halten sich meistens daran – „meistens” reicht nicht, also prüfst du selbst.

cat > cmd/ask/triage.go <<'EOF'
package main

import (
    "context"
    "encoding/json"
    "fmt"
    "os"
    "slices"

    "example.com/ask/internal/llm"
)

type Triage struct {
    Severity string `json:"severity"`
    Summary  string `json:"summary"`
    Action   string `json:"action"`
}

// triageSchema zwingt das Modell in genau diese JSON-Form.
var triageSchema = json.RawMessage(`{"type": "json_schema", "json_schema": {
  "name": "triage", "schema": {"type": "object",
    "properties": {
      "severity": {"type": "string", "enum": ["low", "medium", "high"]},
      "summary": {"type": "string"}, "action": {"type": "string"}},
    "required": ["severity", "summary", "action"]}}}`)

func runTriage(ctx context.Context, c *llm.Client, q string) error {
    m, err := c.Chat(ctx, llm.Request{
        Messages: []llm.Message{
            {Role: "system", Content: "Du bist SRE. Bewerte die Meldung knapp."},
            {Role: "user", Content: q},
        },
        ResponseFormat: triageSchema,
    })
    if err != nil {
        return err
    }
    t, err := parseTriage(m.Content)
    if err != nil {
        return err
    }
    enc := json.NewEncoder(os.Stdout)
    enc.SetIndent("", "  ")
    return enc.Encode(t)
}

// parseTriage traut dem Modell nicht: Schema ist Wunsch, Prüfung ist Pflicht.
func parseTriage(s string) (Triage, error) {
    var t Triage
    if err := json.Unmarshal([]byte(s), &t); err != nil {
        return t, fmt.Errorf("kein gültiges JSON: %w", err)
    }
    if !slices.Contains([]string{"low", "medium", "high"}, t.Severity) {
        return t, fmt.Errorf("ungültige severity %q", t.Severity)
    }
    return t, nil
}
EOF
cat > cmd/ask/triage_test.go <<'EOF'
package main

import "testing"

func TestParseTriage(t *testing.T) {
    tests := []struct {
        in      string
        wantErr bool
    }{
        {`{"severity":"high","summary":"Disk voll","action":"aufräumen"}`, false},
        {`{"severity":"kritisch","summary":"x","action":"y"}`, true},
        {"Klar, hier ist dein JSON: {", true},
    }
    for _, tt := range tests {
        if _, err := parseTriage(tt.in); (err != nil) != tt.wantErr {
            t.Errorf("%q: err=%v, wantErr=%v", tt.in, err, tt.wantErr)
        }
    }
}
EOF
go test -run TestParseTriage -v ./cmd/ask 2>&1 | tail -2

Erwartet:

PASS
ok      example.com/ask/cmd/ask 0.153s

Warum? json.RawMessage landet unverändert im Request – Schemas schreibst du so lesbar als JSON statt als verschachtelte map[string]any. Ein Enum im Schema plus slices.Contains im Code: doppelt hält besser.

Fortschritt speichern? Kostenlos registrieren

Drill 4: Tool Calling

Das Modell bekommt eine Tool-Beschreibung und antwortet statt mit Text mit tool_calls. Dein Code führt das Tool aus und schickt das Ergebnis als Rolle tool zurück. Das Tool selbst ist normales Go:

cat > internal/tools/disk.go <<'EOF'
// Package tools enthält lokale Funktionen, die ein Modell aufrufen darf.
package tools

import (
    "fmt"
    "math"
    "syscall"
)

// Disk ist das Ergebnis von DiskFree.
type Disk struct {
    Path    string  `json:"path"`
    FreeGiB float64 `json:"free_gib"`
    FreePct float64 `json:"free_pct"`
}

// DiskFree misst den freien Platz des Dateisystems unter path (Unix).
func DiskFree(path string) (Disk, error) {
    var st syscall.Statfs_t
    if err := syscall.Statfs(path, &st); err != nil {
        return Disk{}, fmt.Errorf("statfs %s: %w", path, err)
    }
    free := float64(st.Bavail) * float64(st.Bsize)
    total := float64(st.Blocks) * float64(st.Bsize)
    return Disk{path, round(free / (1 << 30)), round(100 * free / total)}, nil
}

func round(f float64) float64 { return math.Round(f*10) / 10 }
EOF

Die Schleife: fragen, Tools ausführen, Ergebnisse anhängen, erneut fragen – höchstens fünf Runden.

cat > cmd/ask/tools.go <<'EOF'
package main

import (
    "context"
    "encoding/json"
    "errors"
    "fmt"
    "os"

    "example.com/ask/internal/llm"
    "example.com/ask/internal/tools"
)

var toolDefs = []any{json.RawMessage(`{"type": "function", "function": {
  "name": "disk_free",
  "description": "Freier Speicherplatz eines Pfads auf diesem Rechner",
  "parameters": {"type": "object",
    "properties": {"path": {"type": "string"}}, "required": ["path"]}}}`)}

// callTool führt nur bekannte Tools aus; Argumente kommen vom Modell.
func callTool(name, args string) string {
    if name != "disk_free" {
        return `{"error":"unbekanntes tool"}`
    }
    var in struct{ Path string }
    if err := json.Unmarshal([]byte(args), &in); err != nil || in.Path == "" {
        return `{"error":"argument path fehlt"}`
    }
    d, err := tools.DiskFree(in.Path)
    if err != nil {
        return fmt.Sprintf(`{"error":%q}`, err.Error())
    }
    b, _ := json.Marshal(d)
    return string(b)
}

func runTools(ctx context.Context, c *llm.Client, q string) error {
    msgs := []llm.Message{
        {Role: "system", Content: "Nutze Tools für Fakten über diesen Rechner."},
        {Role: "user", Content: q},
    }
    for range 5 { // Obergrenze gegen Endlosschleifen
        m, err := c.Chat(ctx, llm.Request{Messages: msgs, Tools: toolDefs})
        if err != nil {
            return err
        }
        if len(m.ToolCalls) == 0 {
            fmt.Println(m.Content)
            return nil
        }
        msgs = append(msgs, m)
        for _, tc := range m.ToolCalls {
            out := callTool(tc.Function.Name, tc.Function.Arguments)
            fmt.Fprintf(os.Stderr, "-> %s(%s) = %s\n",
                tc.Function.Name, tc.Function.Arguments, out)
            msgs = append(msgs, llm.Message{Role: "tool",
                ToolCallID: tc.ID, Content: out})
        }
    }
    return errors.New("zu viele tool-runden")
}
EOF

Dazu main.go mit drei Modi: Streaming (Default), -triage und -tools.

cat > cmd/ask/main.go <<'EOF'
// ask: Fragen an ein lokales LLM – gestreamt, als JSON oder mit Tools.
package main

import (
    "context"
    "flag"
    "fmt"
    "os"
    "os/signal"
    "strings"

    "example.com/ask/internal/llm"
)

func main() {
    triage := flag.Bool("triage", false, "Antwort als JSON (severity, summary, action)")
    agent := flag.Bool("tools", false, "Modell darf lokale Tools aufrufen")
    flag.Parse()
    q := strings.Join(flag.Args(), " ")
    if q == "" {
        fmt.Fprintln(os.Stderr, "usage: ask [-triage|-tools] <frage>")
        os.Exit(2)
    }
    ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt)
    defer stop()
    c := llm.FromEnv()

    var err error
    switch {
    case *triage:
        err = runTriage(ctx, c, q)
    case *agent:
        err = runTools(ctx, c, q)
    default:
        msgs := []llm.Message{{Role: "user", Content: q}}
        err = c.Stream(ctx, msgs, func(s string) { fmt.Print(s) })
        fmt.Println() // Zeilenende nach dem Stream
    }
    if err != nil {
        fmt.Fprintln(os.Stderr, "ask:", err)
        os.Exit(1)
    }
}
EOF
go vet ./... && go build -o ask ./cmd/ask
./ask "Was ist ein Kubernetes-Pod? Antworte in einem Satz."
./ask -triage "kubelet: eviction manager: disk pressure on node worker-3, 97% used"
./ask -tools "Wie viel Speicher ist unter / frei?"

Erwartet (Text variiert, Werte hängen von deinem Mac ab):

Ein **Kubernetes-Pod** ist die kleinste, ausgeführte Einheit eines Kontainers,
die statisch oder dynamisch aus mehreren Containern besteht, ...
{
  "severity": "high",
  "summary": "Disk Pressure - Node Disk Full Risk",
  "action": "• Check root and tmpfs utilization on **worker-3** (~97% used). ..."
}
-> disk_free({"path":"/"}) = {"path":"/","free_gib":17.8,"free_pct":7.8}
Unter dem Pfad `/` sind etwa **17,8 Gigabyte** Speicherplatz frei. Das entspricht
rund **7,8 %** des genutzten Speicherplatzes.

Warum? Beim Streaming erscheinen die Wörter nacheinander statt nach Sekunden auf einmal. Die Zeile mit -> geht nach stderr: Du siehst, was das Modell aufruft, die eigentliche Antwort bleibt pipe-fähig auf stdout.

Sicherheit: Argumente von Tool Calls sind Benutzereingaben aus zweiter Hand (Prompt Injection). Nur Tools aus einer festen Liste, nur lesend, Parameter validieren – nie exec.Command mit Modell-Argumenten.

Fortschritt speichern? Kostenlos registrieren

Drill 5: Embeddings und Kosinus-Suche

Ein Embedding ist ein Vektor, der die Bedeutung eines Texts kodiert. Ähnliche Texte zeigen in ähnliche Richtungen. Lade das kleine Embedding-Modell (ca. 45 MB):

ollama pull all-minilm
cat > internal/llm/embed.go <<'EOF'
package llm

import (
    "context"
    "encoding/json"
    "fmt"
)

// Embed liefert pro Eingabetext einen Vektor (Reihenfolge wie input).
func (c *Client) Embed(ctx context.Context, model string, input []string) (
    [][]float64, error) {
    resp, err := c.post(ctx, "/embeddings",
        map[string]any{"model": model, "input": input})
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()
    var out struct {
        Data []struct {
            Index     int       `json:"index"`
            Embedding []float64 `json:"embedding"`
        } `json:"data"`
    }
    if err := json.NewDecoder(resp.Body).Decode(&out); err != nil {
        return nil, fmt.Errorf("embeddings lesen: %w", err)
    }
    if len(out.Data) != len(input) {
        return nil, fmt.Errorf("%d vektoren für %d texte", len(out.Data), len(input))
    }
    vecs := make([][]float64, len(input))
    for _, d := range out.Data {
        vecs[d.Index] = d.Embedding
    }
    return vecs, nil
}
EOF
cat > internal/search/search.go <<'EOF'
// Package search findet die ähnlichsten Texte per Kosinus-Ähnlichkeit.
package search

import (
    "math"
    "sort"
)

type Doc struct {
    Source, Text string
    Vec          []float64
}

type Hit struct {
    Doc
    Score float64
}

// Cosine liefert 1 für gleiche Richtung, 0 für orthogonale Vektoren.
func Cosine(a, b []float64) float64 {
    var dot, na, nb float64
    for i := range a {
        dot += a[i] * b[i]
        na += a[i] * a[i]
        nb += b[i] * b[i]
    }
    if na == 0 || nb == 0 {
        return 0
    }
    return dot / (math.Sqrt(na) * math.Sqrt(nb))
}

// TopK liefert die k Dokumente mit der höchsten Ähnlichkeit zu q.
func TopK(docs []Doc, q []float64, k int) []Hit {
    hits := make([]Hit, 0, len(docs))
    for _, d := range docs {
        hits = append(hits, Hit{d, Cosine(d.Vec, q)})
    }
    sort.Slice(hits, func(i, j int) bool { return hits[i].Score > hits[j].Score })
    return hits[:min(k, len(hits))]
}
EOF
cat > internal/search/search_test.go <<'EOF'
package search

import (
    "math"
    "testing"
)

func TestTopK(t *testing.T) {
    docs := []Doc{{Source: "a", Vec: []float64{1, 0}},
        {Source: "b", Vec: []float64{0.7, 0.7}}, {Source: "c", Vec: []float64{0, 1}}}
    got := TopK(docs, []float64{0, 2}, 2)
    if len(got) != 2 || got[0].Source != "c" || got[1].Source != "b" {
        t.Fatalf("got %+v", got)
    }
    if math.Abs(got[0].Score-1) > 1e-9 {
        t.Errorf("gleiche Richtung: Score %v, want 1", got[0].Score)
    }
    if Cosine([]float64{0, 0}, []float64{1, 1}) != 0 {
        t.Error("Nullvektor muss 0 liefern")
    }
}
EOF
go test ./internal/...

Erwartet:

ok      example.com/ask/internal/llm    0.208s
ok      example.com/ask/internal/search 0.142s
?       example.com/ask/internal/tools  [no test files]

Vier Mini-Runbooks als Suchbestand:

cat > docs/disk-voll.md <<'EOF'
# Runbook: Disk voll
Wenn ein Node DiskPressure meldet, zuerst ungenutzte Images löschen:
crictl rmi --prune. Danach Logs unter /var/log prüfen und rotieren.
EOF
cat > docs/crashloop.md <<'EOF'
# Runbook: CrashLoopBackOff
Startet ein Container immer wieder neu, die Logs des vorherigen Laufs lesen:
kubectl logs <pod> --previous. Häufige Ursachen: fehlende Env-Variable,
falsches Secret, Liveness-Probe zu streng.
EOF
cat > docs/zertifikat.md <<'EOF'
# Runbook: Zertifikat abgelaufen
Bei TLS-Fehlern "certificate has expired" das Ablaufdatum prüfen:
openssl x509 -enddate -noout -in tls.crt. cert-manager erneuert per
kubectl annotate certificate <name> cert-manager.io/issue-temporary-certificate.
EOF
cat > docs/vault-sealed.md <<'EOF'
# Runbook: OpenBao/Vault sealed
Nach einem Neustart ist der Server versiegelt. Status mit bao status prüfen,
dann mit den Unseal-Keys entsiegeln oder Auto-Unseal (KMS/Transit) einrichten.
EOF
cat > cmd/docsearch/main.go <<'EOF'
// docsearch: semantische Suche über Markdown-Runbooks mit Embeddings.
package main

import (
    "context"
    "flag"
    "fmt"
    "os"
    "path/filepath"
    "strings"

    "example.com/ask/internal/llm"
    "example.com/ask/internal/search"
)

func main() {
    dir := flag.String("dir", "docs", "Verzeichnis mit *.md")
    model := flag.String("model", "all-minilm", "Embedding-Modell")
    k := flag.Int("k", 2, "Anzahl Treffer")
    flag.Parse()
    q := strings.Join(flag.Args(), " ")
    if q == "" {
        fmt.Fprintln(os.Stderr, "usage: docsearch [-dir docs] [-k 2] <frage>")
        os.Exit(2)
    }
    ctx, c := context.Background(), llm.FromEnv()
    hits, err := find(ctx, c, *dir, *model, q, *k)
    if err != nil {
        fmt.Fprintln(os.Stderr, "docsearch:", err)
        os.Exit(1)
    }
    for _, h := range hits {
        title, _, _ := strings.Cut(h.Text, "\n")
        fmt.Printf("%.3f  %-16s %s\n", h.Score, h.Source, title)
    }
}

// find bettet Frage und Dokumente ein und liefert die k besten Treffer.
func find(ctx context.Context, c *llm.Client, dir, model, q string, k int) (
    []search.Hit, error) {
    files, err := filepath.Glob(filepath.Join(dir, "*.md"))
    if err != nil || len(files) == 0 {
        return nil, fmt.Errorf("keine *.md in %s", dir)
    }
    var docs []search.Doc
    texts := []string{q} // Frage zuerst: ein einziger Embedding-Aufruf
    for _, f := range files {
        b, err := os.ReadFile(f)
        if err != nil {
            return nil, err
        }
        docs = append(docs, search.Doc{Source: filepath.Base(f), Text: string(b)})
        texts = append(texts, string(b))
    }
    vecs, err := c.Embed(ctx, model, texts)
    if err != nil {
        return nil, err
    }
    for i := range docs {
        docs[i].Vec = vecs[i+1]
    }
    return search.TopK(docs, vecs[0], k), nil
}
EOF
go build -o docsearch ./cmd/docsearch
./docsearch "pod startet ständig neu"
./docsearch -k 1 "TLS certificate expired"

Erwartet (Scores variieren leicht):

0.499  crashloop.md     # Runbook: CrashLoopBackOff
0.316  vault-sealed.md  # Runbook: OpenBao/Vault sealed
0.738  zertifikat.md    # Runbook: Zertifikat abgelaufen

Warum? Kein Wort aus „pod startet ständig neu” steht so im Runbook – die Suche findet es über die Bedeutung. all-minilm ist auf Englisch trainiert; für deutsche Texte lohnt ein mehrsprachiges Modell (z. B. bge-m3). Ab einigen Tausend Dokumenten gehören die Vektoren in eine Datenbank (z. B. PostgreSQL mit pgvector).

Fortschritt speichern? Kostenlos registrieren

Drill 6: MCP-Server mit dem Go-SDK

MCP (Model Context Protocol) ist JSON-RPC über stdio oder HTTP. Das SDK erzeugt das JSON-Schema aus deinen Go-Structs.

go get github.com/modelcontextprotocol/[email protected]
cat > cmd/ops-mcp/main.go <<'EOF'
// ops-mcp: MCP-Server (stdio) mit Ops-Tools für KI-Assistenten.
package main

import (
    "context"
    "log"
    "os"

    "example.com/ask/internal/tools"
    "github.com/modelcontextprotocol/go-sdk/mcp"
)

type diskIn struct {
    Path string `json:"path" jsonschema:"Pfad, z. B. / oder /var"`
}

func diskFree(_ context.Context, _ *mcp.CallToolRequest, in diskIn) (
    *mcp.CallToolResult, tools.Disk, error) {
    d, err := tools.DiskFree(in.Path)
    return nil, d, err // Fehler landen als isError beim Client
}

func newServer() *mcp.Server {
    s := mcp.NewServer(&mcp.Implementation{Name: "ops-mcp", Version: "v0.1.0"}, nil)
    mcp.AddTool(s, &mcp.Tool{
        Name:        "disk_free",
        Description: "Freier Speicherplatz eines Pfads auf diesem Rechner",
    }, diskFree)
    return s
}

func main() {
    log.SetOutput(os.Stderr) // stdout gehört dem JSON-RPC-Protokoll
    if err := newServer().Run(context.Background(), &mcp.StdioTransport{}); err != nil {
        log.Fatal(err)
    }
}
EOF

Der Test verbindet Client und Server im Speicher – ohne Prozess, ohne Pipes:

cat > cmd/ops-mcp/main_test.go <<'EOF'
package main

import (
    "context"
    "testing"

    "github.com/modelcontextprotocol/go-sdk/mcp"
)

func TestDiskFreeTool(t *testing.T) {
    ctx := context.Background()
    st, ct := mcp.NewInMemoryTransports()
    if _, err := newServer().Connect(ctx, st, nil); err != nil {
        t.Fatal(err)
    }
    c := mcp.NewClient(&mcp.Implementation{Name: "test", Version: "v0"}, nil)
    cs, err := c.Connect(ctx, ct, nil)
    if err != nil {
        t.Fatal(err)
    }
    defer cs.Close()

    tests := []struct {
        path    string
        wantErr bool
    }{{"/", false}, {"/gibt/es/nicht", true}}
    for _, tt := range tests {
        res, err := cs.CallTool(ctx, &mcp.CallToolParams{
            Name: "disk_free", Arguments: map[string]any{"path": tt.path}})
        if err != nil {
            t.Fatal(err)
        }
        if res.IsError != tt.wantErr {
            t.Errorf("%s: IsError=%v", tt.path, res.IsError)
        }
        t.Logf("%s -> %v", tt.path, res.Content[0].(*mcp.TextContent).Text)
    }
}
EOF
go mod tidy
go test -v ./cmd/ops-mcp 2>&1 | grep -E 'main_test|ok'

Erwartet (Werte hängen von deinem Mac ab):

    main_test.go:36: / -> {"free_gib":17.3,"free_pct":7.6,"path":"/"}
    main_test.go:36: /gibt/es/nicht -> statfs /gibt/es/nicht: no such file or directory
ok      example.com/ask/cmd/ops-mcp 0.163s

Und live über stdio, so wie ein KI-Client den Server startet:

go build -o ops-mcp ./cmd/ops-mcp
rpc() { jq -nc --argjson id "$1" --arg m "$2" --argjson p "$3" \
  '{jsonrpc:"2.0", id:$id, method:$m, params:$p}'; }
{
  rpc 1 initialize '{"protocolVersion":"2025-06-18","capabilities":{},
    "clientInfo":{"name":"bash","version":"0"}}'
  echo '{"jsonrpc":"2.0","method":"notifications/initialized"}'
  rpc 2 tools/list '{}'
  rpc 3 tools/call '{"name":"disk_free","arguments":{"path":"/"}}'
  sleep 1
} | ./ops-mcp | jq -c '.result.serverInfo
  // .result.tools[0].inputSchema.properties // .result.structuredContent'

Erwartet:

{"name":"ops-mcp","version":"v0.1.0"}
{"path":{"type":"string","description":"Pfad, z. B. / oder /var"}}
{"free_gib":17.8,"free_pct":7.8,"path":"/"}

Warum? Auf stdout darf nur JSON-RPC stehen – deshalb loggt der Server nach stderr. Das sleep 1 hält stdin offen, bis die Antworten da sind; schließt stdin, beendet sich der Server sauber.

Fortschritt speichern? Kostenlos registrieren

Drill 7: Die Tools sind fertig

go build -o bin/ ./cmd/...
ls bin
./bin/ask "Nenne drei kubectl-Befehle zur Fehlersuche als nummerierte Liste, \
ohne Erklärung, ohne Markdown."
LLM_MODEL=gibtsnicht ./bin/ask hallo; echo "exit=$?"

Erwartet (Text variiert, lange Zeile umbrochen):

ask
docsearch
ops-mcp
1. kubectl logs <pod-identifikator> --previous
2. kubectl describe pod <pod-identifikator>
3. kubectl get events --sort-by='.metadata.creationTimestamp'

ask: /chat/completions: 404 Not Found: {"error":{"message":"model 'gibtsnicht'
  not found","type":"not_found_error","param":null,"code":null}}
exit=1

Warum? go build -o bin/ ./cmd/... baut alle drei Binaries auf einmal. Die Fehlermeldung des Servers reicht post unverändert durch – so siehst du sofort, dass das Modell fehlt. Antworten eines 3B-Modells sind Vorschläge, keine Befehle: Mal heißt es Kontainer, mal erfindet es Flags.

Den MCP-Server trägst du in deinem KI-Client ein; die meisten Clients nutzen dieses Format (Pfad anpassen):

{
  "mcpServers": {
    "ops-mcp": { "command": "/Users/DU/go-lab/tag12-ask/bin/ops-mcp" }
  }
}

Tipp: Gegen eine Cloud-API wechselst du nur die Umgebung, z. B. LLM_BASE_URL=https://api.mistral.ai/v1, LLM_API_KEY="$MISTRAL_API_KEY" und LLM_MODEL=mistral-small-latest – der Key kommt aus deiner Shell, nie aus dem Code.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

#!/usr/bin/env bash
check() { if eval "$2" >/dev/null 2>&1; then echo "✔ $1"; else echo "✘ $1"; fi; }
cd ~/go-lab/tag12-ask
check "gofmt sauber" "test -z \"\$(gofmt -l .)\""
check "go vet" "go vet ./..."
check "golangci-lint" "~/go-lab/bin/lint run ./..."
check "Tests mit -race" "go test -race -count=1 ./..."
check "drei Binaries" "test -x bin/ask -a -x bin/docsearch -a -x bin/ops-mcp"
check "Streaming live" "./bin/ask 'Antworte nur mit OK' | grep -qi ok"
check "Triage ist JSON" "./bin/ask -triage 'disk 99% voll' | jq -e .severity"
check "docsearch findet Runbook" \
  "./bin/docsearch -k 1 'certificate expired' | grep -q zertifikat"
check "kein Key im Code" "! grep -rn 'sk-[A-Za-z0-9]\{20,\}' --include=*.go ."

Erwartet:

✔ gofmt sauber
✔ go vet
✔ golangci-lint
✔ Tests mit -race
✔ drei Binaries
✔ Streaming live
✔ Triage ist JSON
✔ docsearch findet Runbook
✔ kein Key im Code

Challenge

Baue aus docsearch ein kleines RAG: Mit -answer soll das Chat-Modell die Frage beantworten – ausschließlich mit den gefundenen Runbooks als Kontext.

Hinweis: find liefert die Treffer schon; schicke ihre Texte als System-Nachricht über c.Chat mit.

Lösung

In cmd/docsearch/main.go nach dem Flag k ergänzen:

    answer := flag.Bool("answer", false, "Antwort aus den Treffern erzeugen")

Am Ende von main nach der Ausgabeschleife:

    if *answer {
        if err := rag(ctx, c, q, hits); err != nil {
            fmt.Fprintln(os.Stderr, "docsearch:", err)
            os.Exit(1)
        }
    }

Und die neue Funktion:

// rag lässt das Modell nur mit den gefundenen Runbooks antworten.
func rag(ctx context.Context, c *llm.Client, q string, hits []search.Hit) error {
    var sb strings.Builder
    for _, h := range hits {
        sb.WriteString(h.Text + "\n")
    }
    m, err := c.Chat(ctx, llm.Request{Messages: []llm.Message{
        {Role: "system", Content: "Antworte knapp in 2 Sätzen, nur mit " +
            "diesen Runbooks:\n" + sb.String()},
        {Role: "user", Content: q},
    }})
    if err != nil {
        return err
    }
    fmt.Println("\n" + m.Content)
    return nil
}
go build -o bin/ ./cmd/... && ./bin/docsearch -k 1 -answer \
  "pod startet ständig neu, was tun?"

Erwartet (Text variiert):

0.409  crashloop.md     # Runbook: CrashLoopBackOff

Prüfe zuerst die fehlenden oder falschen **Env-Variablen/Secrets** im Pod oder
Container (z. B. mit `kubectl describe pod`). Lies die Logs des **vorherigen
Laufs** mit: `kubectl logs <pod> --previous`.

Aufräumen, wenn du die Embeddings nicht mehr brauchst: ollama rm all-minilm.

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Keys aus Secret-Store bzw. OpenBao, nie in Env-Dateien im Repo; ausgehenden Traffic zu Cloud-LLMs über einen Gateway mit Mandanten, Rate-Limit und Audit-Log führen.
  • Streaming braucht Timeouts pro Lesevorgang und Abbruch per context; Proxies (nginx, Ingress) dürfen SSE nicht puffern.
  • Strukturierte Ausgaben immer validieren und Fehlversuche zählen (Metrik); bei kritischen Abläufen ein Mensch im Loop.
  • MCP-Server laufen mit den Rechten des Clients: nur lesende Tools, Allowlists, keine Shell; über HTTP nur mit Auth (OAuth) und TLS.
  • RAG im Betrieb: Vektoren persistieren (z. B. pgvector), Dokumente versionieren, Zugriffsrechte der Quelle auf die Suche übertragen.