13 Min. Lesezeit

Lernziele

Am Ende dieses Moduls werden Sie in der Lage sein:

  • Die OpenAI-kompatible API des AI Model Hub aus Python mit einem Bearer-Token und einem aus `GET /v1/models` gewählten Modell aufrufen
  • Streaming- und Nicht-Streaming-Chat-Vervollständigungen mit Timeouts und Antwortvalidierung implementieren
  • Antworten von `429`, `503` und `529` mit `Retry-After`-basiertem Back-off und modellbezogenen Ratenlimits behandeln
  • Inferenz synchron und asynchron über Kafka integrieren, wobei die Ergebnisse in der In-Memory DB zwischengespeichert werden
  • Den IONOS CLOUD MCP Server für den Agentenzugriff auf Ihr Konto konfigurieren, standardmäßig nur lesend

Einheit 4.4: Integration des AI Model Hub

Einführung

Nutzer von TaskBoard verfassen lange Aufgabenbeschreibungen, und das Team möchte auf jeder Task-Karte eine einzeilige Zusammenfassung. Sie fügen einen Endpunkt hinzu, der die Beschreibung an ein großes Sprachmodell (LLM) auf AI Model Hub sendet und die Zusammenfassung in PostgreSQL speichert. Die Inferenz wird in Deutschland ausgeführt, und Ihre Prompts werden nicht für das Training verwendet, sodass der Aufgabeninhalt im selben souveränen Setup verbleibt wie der Rest von TaskBoard.

In dieser Einheit integrieren Sie AI Model Hub in den Anwendungscode. Sie authentifizieren sich, wählen ein Modell aus, rufen Chat-Completions mit und ohne Streaming auf und härten den Client gegen Ratenlimits und Überlastung ab. Anschließend verlagern Sie die Zusammenfassung in Massen auf die Kafka-Pipeline aus Einheit 4.3 und cachen die Ergebnisse im In-Memory DB-Cluster aus Einheit 4.1. Schließlich verbinden Sie KI-Agenten mit Ihrem IONOS CLOUD-Konto über den IONOS CLOUD MCP Server. Das Code Lab baut die Zusammenfassungsfunktion von Anfang bis Ende auf.

1. Die AI Model Hub API

AI Model Hub bietet eine OpenAI-kompatible API. Sie rufen sie mit der offiziellen openai Python-Bibliothek auf, indem Sie die Basis-URL ändern:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["IONOS_API_TOKEN"],
    base_url="https://openai.inference.de-txl.ionos.com/v1",
    timeout=30.0,
    max_retries=3,
)
for m in client.models.list():
    print(m.id)

Die Basis-URL lautet https://openai.inference.de-txl.ionos.com/v1. Die Inferenz wird in Deutschland (Berlin) ausgeführt, und die API ist global erreichbar.

1.1 Authentifizierung

Der API-Schlüssel ist ein IONOS CLOUD Authentifizierungstoken, das als Authorization: Bearer <token> gesendet wird. Tokens sind JSON Web Tokens (JWTs), die an einen Benutzer eines IONOS Public Cloud Vertrags gebunden sind; die Nutzung wird dem Vertragsinhaber in Rechnung gestellt. Sie erzeugen ein Token im DCD unter Management > Token Manager oder mit der Authentifizierungs-API aus Einheit 1.1:

curl -s -H "Authorization: Bearer $IONOS_API_TOKEN" \
  https://openai.inference.de-txl.ionos.com/v1/models | jq -r '.data[].id'

Die Gültigkeitsdauer (TTL) eines Tokens liegt im Token Manager zwischen 1 Stunde und 365 Tagen und mit der Authentifizierungs-API zwischen 60 Sekunden und 365 Tagen. Sein Wert wird nur einmal angezeigt. Wenn Aufrufe, die zuvor funktioniert haben, 401 zurückgeben, prüfen Sie zuerst den exp-Claim des Tokens. Vergeben Sie TaskBoard ein eigenes Token und speichern Sie es im taskboard-ai Kubernetes Secret.

1.2 Modelle und Endpunkte

Die OpenAI-kompatiblen Pfade sind POST /v1/chat/completions, POST /v1/responses, POST /v1/embeddings, POST /v1/images/generations, POST /v1/rerank und GET /v1/models. Die folgende Tabelle listet die Textmodelle und ihre Funktionen auf:

Modellname Typ Eingabe-Modalität Ausgabe-Modalität Streaming Tool Calling Kontextfenster Modellgröße
Qwen3.5-9B Sprachmodell Text, Bild und Video Text ✅ ✅ 262k Klein
Mistral Small 24B Sprachmodell Text, Bild Text ✅ ✅ 128k Mittel
Qwen3.8-27B Sprachmodell Text, Bild und Video (Beta) Text ✅ ✅ 262k Mittel
Llama 3.3 70B Sprachmodell Text Text ✅ ✅ 128k Mittel
GPT-OSS 120B Sprachmodell Text Text ✅ ✅ 128k Mittel
Qwen3.5 397B A17B Sprachmodell Text und Bild Text ✅ ✅ 262k Groß
Qwen3-Coder-Next 80B Coding-Modell Text Text ✅ ✅ 256k Mittel

Wie oben gezeigt, unterstützen alle Textmodelle Streaming und Tool Calling. Im Code verwenden Sie die Modellkennung, beispielsweise mistralai/Mistral-Small-24B-Instruct für Mistral Small 24B. Lesen Sie die Kennungen bei der Initialisierung aus /v1/models, anstatt eine Liste hart zu codieren, da sich das Katalogangebot ändert.

2. Inferenzmuster

2.1 Eine synchrone Zusammenfassung

MODEL = os.environ.get("SUMMARY_MODEL", "mistralai/Mistral-Small-24B-Instruct")

def summarize(description: str, model: str = MODEL) -> str:
    resp = client.chat.completions.create(
        model=model,
        messages=[
            {"role": "system", "content": "Summarize the task in one sentence of at most 20 words."},
            {"role": "user", "content": description},
        ],
        max_tokens=60,
        temperature=0.2,
    )
    choice = resp.choices[0]
    summary = (choice.message.content or "").strip()
    if choice.finish_reason != "stop" or not summary:
        raise ValueError(f"unusable summary, finish_reason={choice.finish_reason}")
    return summary[:200]

Prüfen Sie jede Antwort, bevor Sie sie speichern: Eine abgeschnittene Antwort (finish_reason von length), eine leere Zeichenfolge oder ein zu langer Text darf die Aufgabenkarte nicht erreichen. Das Feld usage meldet prompt_tokens und completion_tokens, die Sie zur Kostenverfolgung protokollieren (Abschnitt 4).

2.2 Streaming

Für ein interaktives „Erkläre diese Aufgabe"-Panel streamen Sie die Token zum Browser, sobald sie eintreffen:

stream = client.chat.completions.create(
    model=MODEL,
    messages=[{"role": "user", "content": f"Explain the next steps for: {description}"}],
    stream=True,
    stream_options={"include_usage": True},
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        yield chunk.choices[0].delta.content
    if chunk.usage:
        log.info("tokens in=%s out=%s", chunk.usage.prompt_tokens, chunk.usage.completion_tokens)

Bei Streaming sind Nutzungsstatistiken standardmäßig nicht enthalten. Setzen Sie "stream_options": {"include_usage": true}, um sie im letzten Chunk zu erhalten. Verwenden Sie Streaming, wenn ein Benutzer die Ausgabe beobachtet, und eine normale Anfrage, wenn Code das Ergebnis verarbeitet.

3. Fehlerbehandlung in der Produktion

3.1 Ratenlimits und Überlastung

Das Standard-Ratenlimit beträgt 5 Anfragen pro Sekunde pro Modell, mit Spitzen von bis zu 10 Anfragen in einem Zeitfenster von 2 Sekunden. Die Limits gelten pro Vertrag und separat für jedes Modell, und Ihr Vertrag kann individuelle Limits haben. Jede gezählte Antwort enthält Header, anhand derer Sie die Rate drosseln können:

raw = client.chat.completions.with_raw_response.create(
    model=MODEL, messages=[{"role": "user", "content": "ping"}], max_tokens=1)
print(raw.headers.get("x-ratelimit-remaining-requests"),
      raw.headers.get("x-ratelimit-reset-requests"))
completion = raw.parse()
Status Bedeutung Reaktion
429 RATE_LIMIT_EXCEEDED Das Vertragslimit für dieses Modell ist erschöpft Retry-After Sekunden warten, dann erneut versuchen
503 SERVICE_OVERLOADED Zu viele große Anfragen in Bearbeitung: Anfragen über 4 MiB sind auf sechs gleichzeitige begrenzt Retry-After Sekunden warten
529 user_overloaded Ihr Traffic trägt zu einer Plattformüberlastung bei Retry-After warten, dann mit einer geringeren Rate senden
529 server_overloaded Das Modell hat keine Kapazität mehr, unabhängig von Ihrem Traffic Retry-After warten; ein anderes Modell in Betracht ziehen

Die openai-Bibliothek respektiert Retry-After automatisch innerhalb von max_retries. Fügen Sie für 529 server_overloaded einen eigenen Fallback hinzu:

import openai

FALLBACK = "meta-llama/Llama-3.3-70B-Instruct"

def summarize_resilient(description: str) -> str:
    try:
        return summarize(description)
    except openai.APIStatusError as e:
        body = e.body if isinstance(e.body, dict) else {}
        code = body.get("code") or (body.get("error") or {}).get("code")
        if e.status_code == 529 and code == "server_overloaded":
            return summarize(description, model=FALLBACK)   # same prompt, other model
        raise

3.2 Client-Fehler

Andere Fehlerantworten enthalten einen JSON-Body mit httpStatus und einer messages-Liste von errorCode- und message-Einträgen. Verzweigen Sie anhand von errorCode, nicht anhand des Nachrichtentextes. Ein 400 VALIDATION_ERROR benennt das fehlerhafte Feld und schlägt unverändert erneut fehl; 404 MODEL_NOT_SUPPORTED bedeutet, dass das Modell nicht existiert oder diesen Endpunkt nicht bedienen kann; 502 UPSTREAM_UNAVAILABLE lohnt einen erneuten Versuch nach einer kurzen Wartezeit. Versuchen Sie 4xx-Fehler nicht erneut, mit Ausnahme von 429.

4. Integrationsmuster und Kosten

4.1 Ergebnisse in In-Memory DB cachen

LLMs werden pro Million Eingabetokens und pro Million Ausgabetokens abgerechnet, daher darf dieselbe Beschreibung niemals zweimal zusammengefasst werden:

import hashlib

def cached_summary(description: str) -> str:
    key = "ai:summary:" + hashlib.sha256(f"{MODEL}\n{description}".encode()).hexdigest()
    hit = cache.get(key)                      # the redis client from Unit 4.1
    if hit:
        return hit
    summary = summarize_resilient(description)
    cache.set(key, summary, ex=7 * 24 * 3600)
    return summary

Der Schlüssel enthält das Modell, sodass eine Modelländerung neue Zusammenfassungen erzeugt, anstatt die Ausgaben zu vermischen. Die Kosten des AI Model Hub pro Modell und Einheit werden im Bereich Cost & Usage des DCD angezeigt.

4.2 Asynchrone Inferenz über Kafka

Ein Massenimport von 5.000 Aufgaben würde das Ratenlimit pro Modell auf einmal überschreiten. Die Arbeit wird stattdessen in einer Warteschlange abgewickelt: Die API erzeugt task.summarize-Ereignisse für ein task-summaries-Thema, das wie die Themen in Einheit 4.3 erstellt wird, und ein Summarizer-Worker verarbeitet sie mit einer konstanten Rate.

import time

def run_summarizer():
    consumer.subscribe(["task-summaries"])
    while running:
        msg = consumer.poll(1.0)
        if msg is None or msg.error():
            continue
        event = json.loads(msg.value())
        summary = cached_summary(event["data"]["description"])
        with engine.begin() as c:
            c.execute(text("update tasks set summary = :s where id = :i"),
                      {"s": summary, "i": event["task_id"]})
        consumer.commit(message=msg, asynchronous=False)
        time.sleep(0.25)          # about 4 requests/s, below the base limit

Der synchrone Pfad verarbeitet einzelne Aufgaben, auf die ein Benutzer wartet; der Kafka-Pfad verarbeitet Stapel. Beide nutzen denselben Cache, und die Wiederholungs- und Dead-Letter-Verarbeitung aus Einheit 4.3 erfasst Beschreibungen, die das Modell weiterhin ablehnt.

5. Der IONOS CLOUD MCP Server

Der IONOS CLOUD MCP Server ist ein lokales Binary, das das Model Context Protocol (MCP) implementiert. Er stellt KI-Assistenten und Agenten über 100 Tools für sieben Produkte zur Verfügung: Compute Engine, IONOS Cloud Object Storage, Cloud DNS, Certificate Manager, Billing, Activity Log und Managed Kubernetes. Er ist eine Alternative zum Schreiben von API- oder SDK-Aufrufen, wenn ein Agent Ihre Infrastruktur inspizieren oder ändern soll.

5.1 Konfiguration

Der KI-Client startet das Binary und kommuniziert über stdio mit JSON-RPC. Ein projektbezogenes .mcp.json für Ihr Team:

{
  "mcpServers": {
    "ionoscloud": {
      "command": "/usr/local/bin/ionoscloud-mcp",
      "env": {
        "IONOS_TOKEN": "${env:IONOS_TOKEN}"
      }
    }
  }
}

IONOS_TOKEN ist erforderlich; Object Storage-Werkzeuge benötigen zusätzlich IONOS_S3_ACCESS_KEY und IONOS_S3_SECRET_KEY. Erstellen Sie ein dediziertes Token mit dem minimal erforderlichen Zugriff und commiten Sie niemals ein Token in die Datei.

5.2 Nur Lesen standardmäßig, Schreibzugriff auf Opt-in-Basis

Der Server ist standardmäßig schreibgeschützt. IONOS_MCP_TOOL_SCOPE=write registriert Werkzeuge zum Erstellen und Aktualisieren, und destructive fügt Werkzeuge zum Löschen sowie störende Aktionen wie das Stoppen eines Servers hinzu. Die Schreibwerkzeuge umfassen Compute Engine und Managed Kubernetes. Jede Aktion zum Erstellen, Löschen oder jede störende Aktion erfordert eine zweistufige Bestätigung: Ein Aufruf zur Vorschau gibt ein confirmation_token zurück, das einmalig für fünf Minuten gültig ist, und ein zweiter Aufruf führt die Operation aus. Commiten Sie IONOS_MCP_TOOL_SCOPE nicht in ein geteiltes .mcp.json, da dies die Schreibwerkzeuge für alle aktiviert, die das Repository öffnen.

Für eine geteilte Instanz führen Sie den Streamable HTTP-Transport aus:

export IONOS_TOKEN="$MCP_READONLY_TOKEN"
ionoscloud-mcp --transport http --http-addr 127.0.0.1:8080

Der HTTP-Endpunkt verfügt über kein TLS und keine eigene Authentifizierung. Binden Sie ihn an 127.0.0.1 oder setzen Sie ihn hinter einen Reverse Proxy, der TLS terminiert und Aufrufende authentifiziert.

5.3 Ein souveräner Agent-Pfad

Der MCP-Server ruft die IONOS CLOUD API direkt auf. Der AI-Client sendet jedoch Prompts und Tool-Ausgaben an sein eigenes Modell-Backend. Um die gesamte Rundreise in IONOS CLOUD zu halten, verwenden Sie einen Client, der sowohl MCP als auch eine benutzerdefinierte, OpenAI-kompatible Basis-URL unterstützt, und richten Sie diese Basis-URL auf AI Model Hub aus. Tool Calling ist eine Voraussetzung für MCP, und die Modelle in Abschnitt 1.2 unterstützen es.

API-Referenz Schnellkarte

Wichtige AI Model Hub-Endpunkte für diese Einheit:

Methode Endpunkt Beschreibung
GET /v1/models Verfügbare Modellkennungen auflisten
POST /v1/chat/completions Textgenerierung, mit stream: true für Streaming
POST /v1/responses Responses API mit typisierten Ausgabedaten
POST /v1/embeddings Embedding-Vektoren für semantische Suche
POST /v1/rerank Dokumente für eine Abfrage neu gewichten

Basis-URL: https://openai.inference.de-txl.ionos.com/v1 Authentifizierung: Authorization: Bearer <token>

Code-Labor

Ziel: Rufen Sie AI Model Hub aus TaskBoard auf, um Aufgabenübersichten zu generieren, Fehler zu behandeln, Ergebnisse in In-Memory DB zu cachen und sie in PostgreSQL zu speichern.

Voraussetzungen:

  • Ein IONOS CLOUD-Token in IONOS_API_TOKEN
  • Die PostgreSQL- und Cache-Verbindungen aus Einheit 4.1 (engine, cache)
  • Python 3.12 mit openai, sqlalchemy und redis

Schritt 1: Modelle auflisten

curl -s -H "Authorization: Bearer $IONOS_API_TOKEN" \
  https://openai.inference.de-txl.ionos.com/v1/models | jq -r '.data[].id' | head -5

Erwartete Ausgabe:

<model identifiers, for example mistralai/Mistral-Small-24B-Instruct>

Schritt 2: Die Spalte "Zusammenfassung" hinzufügen

with engine.begin() as c:
    c.execute(text("alter table tasks add column if not exists summary text"))
print("ok")

Erwartete Ausgabe:

ok

Schritt 3: Eine Beschreibung zusammenfassen

d = "Migrate the attachment upload from API proxying to presigned PUT URLs, add CORS, and remove the old endpoint after one release."
print(summarize(d))

Erwartete Ausgabe:

<one sentence of at most 20 words>

Schritt 4: Die Rate-Limit-Header lesen

Führen Sie das Snippet with_raw_response aus Abschnitt 3.1 aus. Erwartete Ausgabe:

4 200ms

Schritt 5: Cachen und Speichern

import time
for i in range(2):
    t = time.perf_counter(); s = cached_summary(d)
    print(i, f"{time.perf_counter() - t:.2f}s")
with engine.begin() as c:
    c.execute(text("update tasks set summary = :s where id = 1"), {"s": s})

Erwartete Ausgabe:

0 <about a second>s
1 0.00s

Schritt 6: Erzwinge einen Validierungsfehler

try:
    client.chat.completions.create(model=MODEL, messages=[])
except openai.BadRequestError as e:
    print(e.status_code, e.body)

Erwartete Ausgabe:

400 {... 'errorCode': 'VALIDATION_ERROR', ...}

Prüfliste:

  • [ ] /v1/models gibt Kennungen mit Ihrem Bearer-Token zurück
  • [ ] Die Zusammenfassung besteht die finish_reason- und Längentests
  • [ ] Der zweite Aufruf wird aus dem Cache bedient, ohne einen Modellaufruf
  • [ ] Die Zusammenfassung wird in der tasks.summary-Spalte gespeichert

Aufräumarbeiten:

for k in cache.scan_iter("ai:summary:*"):
    cache.delete(k)

Häufige Fehler

Fehler von Entwicklerinnen und Entwicklern, die bei dem Thema dieser Einheit zu vermeiden sind:

  1. Plötzlicher 401 nach Wochen ohne Probleme

    • Problem: Jeder Aufruf liefert 401, obwohl sich der Code nicht geändert hat.
    • Ursache: Die TTL des Tokens ist abgelaufen.
    • Lösung: Den JWT-exp-Claim prüfen, ein neues Token generieren, das Secret aktualisieren und vor dem Ablaufdatum eine Warnung auslösen.
  2. Massenjobs, die die Ratenbeschränkung auslösen

    • Problem: Ein Importjob sendet Hunderte paralleler Anfragen, von denen die meisten mit 429 fehlschlagen.
    • Ursache: Jedes Modell erlaubt 5 Anfragen pro Sekunde pro Vertrag, mit kurzen Spitzen.
    • Lösung: Die Arbeit über Kafka in eine Warteschlange stellen und den Consumer drosseln (Abschnitt 4.2); X-RateLimit-Remaining-Requests lesen.
  3. Speichern nicht validierter Ausgaben

    • Problem: Aufgabenkarten zeigen halbe Sätze oder leere Zusammenfassungen.
    • Ursache: Die Antwort hat max_tokens ausgelöst (finish_reason ist length), oder das Modell hat keinen Inhalt zurückgegeben.
    • Lösung: finish_reason und die Länge vor dem Speichern prüfen und bei einem Fehler die alte Zusammenfassung beibehalten (Abschnitt 2.1).

Zusammenfassung

Sie können TaskBoard nun mit AI Model Hub um KI-Funktionen erweitern. Die openai-Bibliothek arbeitet mit der OpenAI-kompatiblen Basis-URL und einem IONOS CLOUD Bearer-Token. Sie validieren Antworten, streamen dort, wo Nutzer zuhören, und behandeln 429, 503 und 529 mit Retry-After. Einzelanfragen werden synchron ausgeführt, Stapel laufen über Kafka mit einem Tempo unterhalb der Ratenbeschränkung, und der Cache verhindert, dass für dieselben Token zweimal bezahlt wird. Für Agenten-Workflows stellt der IONOS CLOUD MCP Server Ihr Konto als schreibgeschützte Tools bereit, wobei Schreibvorgänge nur bei expliziter Opt-in-Option möglich sind.

Wichtige Punkte:

  • Basis-URL https://openai.inference.de-txl.ionos.com/v1, Bearer-Token, Modell-IDs aus /v1/models
  • Standardlimits: 5 Anfragen pro Sekunde pro Modell, Burst-Frequenzen von bis zu 10, je nach Vertrag
  • Warten Sie die Retry-After-Zeit bei 429, 503 und 529; verzweigen Sie anhand von Fehlercodes, nicht anhand von Meldungen
  • Cachen Sie Ergebnisse nach Modell und Eingabe; leiten Sie Massenarbeit über Kafka
  • Der MCP Server ist standardmäßig schreibgeschützt; Schreibvorgänge erfordern IONOS_MCP_TOOL_SCOPE, und Erstellen, Löschen sowie störende Aktionen erfordern eine zweistufige Bestätigung

Wichtige Begriffe:

  • Modellkennung: Die Zeichenfolge, die Sie als model übergeben, beispielsweise mistralai/Mistral-Small-24B-Instruct
  • Burst-Limit: Die zusätzlichen Anfragen, die innerhalb eines 2-Sekunden-Fensters über der Grundrate erlaubt sind
  • finish_reason: Das Feld, das angibt, warum die Generierung gestoppt wurde, beispielsweise stop oder length
  • MCP: Model Context Protocol, das JSON-RPC-Protokoll, über das KI-Clients Tools aufrufen
  • Tool-Scope: Die IONOS_MCP_TOOL_SCOPE-Ebene, read, write oder destructive, die bestimmt, welche Tools der Server registriert

Nächste Schritte

Weiter lernen: Einheit 4.5: Wissensprüfung - Service-Integration

Verwandte Themen: