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
/v1die OpenAI-API; derselbe Code läuft gegen vLLM oder Mistral (nurLLM_BASE_URL,LLM_API_KEY,LLM_MODELändern). - Kein SDK:
net/http,encoding/jsonund einbufio.Scannerfü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
EOFErwartet:
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.txtErwartet (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")
}
EOFDer 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/llmErwartet (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
}
EOFcat > 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 -2Erwartet:
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 }
EOFDie 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")
}
EOFDazu 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.Commandmit 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-minilmcat > 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.
EOFcat > 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)
}
}
EOFDer 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"undLLM_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.