15 min de lecture

Objectifs d'apprentissage

À la fin de ce module, vous serez en mesure de:

  • Appeler l'API compatible OpenAI d'AI Model Hub depuis Python à l'aide d'un jeton bearer et d'un modèle choisi parmi `GET /v1/models`
  • Mettre en œuvre des complétions de discussion en streaming et non en streaming, avec des délais d'attente et une validation des réponses
  • Gérer les réponses `429`, `503` et `529` avec un retour en arrière basé sur `Retry-After` et des limites de débit par modèle
  • Intégrer l'inférence de manière synchrone et asynchrone via Kafka, avec les résultats mis en cache dans In-Memory DB
  • Configurer IONOS CLOUD MCP Server pour l'accès des agents à votre compte, en lecture seule par défaut

Unité 4.4 : Intégration d'AI Model Hub

Introduction

Les utilisateurs de TaskBoard rédigent de longues descriptions de tâches, et l'équipe souhaite un résumé en une ligne sur chaque carte de tâche. Vous ajoutez un point d'accès qui envoie la description à un grand modèle de langage (LLM) sur AI Model Hub et stocke le résumé dans PostgreSQL. L'inférence est exécutée en Allemagne, et vos invites ne sont pas utilisées pour l'entraînement, de sorte que le contenu des tâches reste dans le même environnement souverain que le reste de TaskBoard.

Dans cette unité, vous intégrez AI Model Hub dans le code applicatif. Vous vous authentifiez, sélectionnez un modèle, effectuez des complétions de chat avec et sans flux, et renforcez le client contre les limites de débit et la surcharge. Ensuite, vous déplacez la résumés en masse sur le pipeline Kafka de l'unité 4.3 et mettez les résultats en cache dans le cluster In-Memory DB de l'unité 4.1. Enfin, vous connectez des agents IA à votre compte IONOS CLOUD à l'aide du IONOS CLOUD MCP Server. Le Code Lab construit la fonctionnalité de résumés de bout en bout.

1. L'API AI Model Hub

AI Model Hub propose une API compatible avec OpenAI. Vous l'appelez à l'aide de la bibliothèque Python officielle openai en modifiant l'URL de base :

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)

L'URL de base est https://openai.inference.de-txl.ionos.com/v1. L'inférence s'exécute en Allemagne (Berlin), et l'API est accessible à l'échelle mondiale.

1.1 Authentification

La clé API est un jeton d'authentification IONOS CLOUD, envoyé en tant que Authorization: Bearer <token>. Les jetons sont des JSON Web Tokens (JWT) liés à un utilisateur d'un contrat IONOS Public Cloud ; l'utilisation est facturée au propriétaire du contrat. Vous générez un jeton dans le DCD sous Management > Token Manager ou avec l'API d'authentification de l'Unité 1.1 :

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

La durée de vie (TTL) d'un jeton se situe entre 1 heure et 365 jours dans le Token Manager, et entre 60 secondes et 365 jours avec l'API d'authentification. Sa valeur n'est affichée qu'une seule fois. Lorsque des appels qui fonctionnaient auparavant renvoient 401, vérifiez d'abord la revendication exp du jeton. Attribuez à TaskBoard son propre jeton et stockez-le dans le Secret Kubernetes taskboard-ai.

1.2 Modèles et points d'accès

Les chemins compatibles OpenAI sont POST /v1/chat/completions, POST /v1/responses, POST /v1/embeddings, POST /v1/images/generations, POST /v1/rerank et GET /v1/models. Le tableau suivant répertorie les modèles de texte et leurs capacités :

Nom du modèle Type Modalité d'entrée Modalité de sortie Diffusion en continu Appel d'outils Fenêtre de contexte Taille du modèle
Qwen3.5-9B Modèle de langage Texte, image et vidéo Texte ✅ ✅ 262k Petit
Mistral Small 24B Modèle de langage Texte, image Texte ✅ ✅ 128k Moyen
Qwen3.8-27B Modèle de langage Texte, image et vidéo (bêta) Texte ✅ ✅ 262k Moyen
Llama 3.3 70B Modèle de langage Texte Texte ✅ ✅ 128k Moyen
GPT-OSS 120B Modèle de langage Texte Texte ✅ ✅ 128k Moyen
Qwen3.5 397B A17B Modèle de langage Texte et image Texte ✅ ✅ 262k Grand
Qwen3-Coder-Next 80B Modèle de codage Texte Texte ✅ ✅ 256k Moyen

Comme indiqué ci-dessus, tous les modèles de texte prennent en charge la diffusion en continu et l'appel d'outils. Dans le code, vous utilisez l'identifiant du modèle, par exemple mistralai/Mistral-Small-24B-Instruct pour Mistral Small 24B. Lisez les identifiants depuis /v1/models au démarrage au lieu de coder une liste en dur, car le catalogue évolue.

2. Modèles d'inférence

2.1 Un résumé synchrone

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]

Validez chaque réponse avant de l'enregistrer : une réponse tronquée (finish_reason sur length), une chaîne vide ou un texte trop long ne doivent pas atteindre la carte de tâche. Le champ usage signale prompt_tokens et completion_tokens, que vous journalisez pour le suivi des coûts (section 4).

2.2 Diffusion en continu

Pour un panneau interactif « Expliquer cette tâche », diffusez les jetons vers le navigateur au fur et à mesure de leur arrivée :

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)

Avec le streaming, les statistiques d'utilisation ne sont pas incluses par défaut. Définissez "stream_options": {"include_usage": true} pour les obtenir dans le dernier bloc. Utilisez le streaming lorsqu'un utilisateur consulte la sortie, et une requête simple lorsque le code consomme le résultat.

3. Gestion des erreurs en production

3.1 Limites de débit et surcharge

La limite de débit par défaut est de 5 requêtes par seconde par modèle, avec des pics pouvant atteindre 10 requêtes sur une fenêtre de 2 secondes. Les limites s'appliquent par contrat et séparément pour chaque modèle, et votre contrat peut avoir des limites personnalisées. Chaque réponse comptée comporte des en-têtes sur lesquels vous pouvez réguler le débit :

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()
Statut Signification Réaction
429 RATE_LIMIT_EXCEEDED La limite de votre contrat pour ce modèle est atteinte Attendez Retry-After secondes, puis réessayez
503 SERVICE_OVERLOADED Trop de requêtes volumineuses en cours : les requêtes supérieures à 4 Mio sont limitées à six simultanées Attendez Retry-After secondes
529 user_overloaded Votre trafic contribue à une surcharge de la plateforme Attendez Retry-After, puis envoyez à un débit inférieur
529 server_overloaded Le modèle est à court de capacité, indépendamment de votre trafic Attendez Retry-After ; envisagez un autre modèle

La bibliothèque openai respecte Retry-After automatiquement dans max_retries. Ajoutez votre propre repli pour 529 server_overloaded :

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 Erreurs côté client

Les autres réponses d'erreur contiennent un corps JSON avec httpStatus et une liste messages d'entrées errorCode et message. Effectuez le branchement sur errorCode, et non sur le texte du message. Un 400 VALIDATION_ERROR identifie le champ invalide et échoue à nouveau de manière identique ; 404 MODEL_NOT_SUPPORTED signifie que le modèle n'existe pas ou ne peut pas servir ce point de terminaison ; 502 UPSTREAM_UNAVAILABLE mérite une nouvelle tentative après une brève attente. Ne réessayez pas les erreurs 4xx autres que 429.

4. Modèles d'intégration et coûts

4.1 Mise en cache des résultats dans In-Memory DB

Les LLM sont facturés par million de jetons d'entrée et par million de jetons de sortie, il ne faut donc jamais résumer deux fois la même description :

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

La clé inclut le modèle, de sorte qu'un changement de modèle génère de nouveaux résumés au lieu de mélanger les sorties. Vous consultez les coûts d'AI Model Hub par modèle et par unité dans la section Coûts et utilisation du DCD.

4.2 Inférence asynchrone via Kafka

Une importation en masse de 5 000 tâches dépasserait immédiatement la limite de débit par modèle. Mettez plutôt le travail en file d'attente : l'API produit des événements task.summarize vers un sujet task-summaries, créé de la même manière que les sujets de l'Unité 4.3, et un travailleur de résumés les consomme à un rythme constant.

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

Le chemin synchrone gère les tâches unitaires pour lesquelles un utilisateur attend ; le chemin Kafka gère des lots. Les deux partagent le cache, ainsi que la gestion des nouvelles tentatives et des messages en échec décrite dans l'unité 4.3, qui intercepte les descriptions que le modèle continue de rejeter.

5. Le IONOS CLOUD MCP Server

Le IONOS CLOUD MCP Server est un binaire local qui implémente le Model Context Protocol (MCP). Il fournit aux assistants et agents d'IA plus de 100 outils répartis sur sept produits : Compute Engine, IONOS Cloud Object Storage, Cloud DNS, Certificate Manager, Billing, Activity Log et Managed Kubernetes. Il constitue une alternative à l'écriture d'appels API ou SDK lorsqu'un agent doit inspecter ou modifier votre infrastructure.

5.1 Configuration

Le client IA lance le binaire et communique en JSON-RPC via stdio. Un .mcp.json à l'échelle du projet pour votre équipe :

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

IONOS_TOKEN est requis ; les outils Object Storage nécessitent également IONOS_S3_ACCESS_KEY et IONOS_S3_SECRET_KEY. Créez un jeton dédié avec les accès minimaux requis, et ne commitez jamais un jeton dans le fichier.

5.2 Lecture seule par défaut, écriture sur demande

Le serveur est en lecture seule par défaut. IONOS_MCP_TOOL_SCOPE=write enregistre les outils de création et de mise à jour, et destructive ajoute les outils de suppression et les actions perturbantes, telles que l'arrêt d'un serveur. Les outils d'écriture couvrent Compute Engine et Managed Kubernetes. Chaque action de création, de suppression ou perturbante nécessite une confirmation en deux étapes : un appel d'aperçu renvoie un confirmation_token, valable une seule fois pendant cinq minutes, et un second appel exécute l'opération. Ne commitez pas IONOS_MCP_TOOL_SCOPE dans un .mcp.json partagé, car cela active les outils d'écriture pour toute personne qui ouvre le dépôt.

Pour une instance partagée, exécutez le transport Streamable HTTP :

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

L'endpoint HTTP ne dispose ni de TLS ni d'authentification propre. Associez-le à 127.0.0.1, ou placez-le derrière un proxy inverse qui termine TLS et authentifie les appelants.

5.3 Un chemin pour un agent souverain

Le serveur MCP appelle directement l'API IONOS CLOUD. Le client IA, en revanche, envoie les invites et la sortie des outils à son propre backend de modèle. Pour maintenir l'ensemble de la boucle dans IONOS CLOUD, utilisez un client qui prend en charge à la fois MCP et une URL de base OpenAI compatible personnalisée, et pointez cette URL de base vers AI Model Hub. L'appel d'outils est un prérequis pour MCP, et les modèles de la section 1.2 le prennent en charge.

Fiche de référence rapide de l'API

Points de terminaison clés de AI Model Hub pour cette unité :

Méthode Point de terminaison Description
GET /v1/models Liste les identifiants de modèles disponibles
POST /v1/chat/completions Génération de texte, avec stream: true pour le flux continu
POST /v1/responses API de réponses avec des éléments de sortie typés
POST /v1/embeddings Vecteurs d'intégration pour la recherche sémantique
POST /v1/rerank Réordonnancement des documents pour une requête

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

Atelier de code

Objectif : Appeler AI Model Hub depuis TaskBoard pour générer des résumés de tâches, gérer les erreurs, mettre les résultats en cache dans In-Memory DB et les stocker dans PostgreSQL.

Prérequis :

  • Un jeton IONOS CLOUD dans IONOS_API_TOKEN
  • Les connexions PostgreSQL et cache de l'Unité 4.1 (engine, cache)
  • Python 3.12 avec openai, sqlalchemy et redis

Étape 1 : Lister les modèles

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

Sortie attendue :

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

Étape 2 : Ajouter la colonne de résumé

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

Sortie attendue :

ok

Étape 3 : Résumer une description

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))

Sortie attendue :

<one sentence of at most 20 words>

Étape 4 : Lire les en-têtes de limitation de débit

Exécutez l'extrait de code with_raw_response de la section 3.1. Sortie attendue :

4 200ms

Étape 5 : Mise en cache et stockage

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})

Sortie attendue :

0 <about a second>s
1 0.00s

Étape 6 : Forcer une erreur de validation

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

Sortie attendue :

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

Liste de contrôle de validation :

  • [ ] /v1/models renvoie des identifiants avec votre jeton d'authentification
  • [ ] Le résumé passe les vérifications de finish_reason et de longueur
  • [ ] Le second appel est servi depuis le cache sans requête au modèle
  • [ ] Le résumé est stocké dans la colonne tasks.summary

Nettoyage :

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

Erreurs courantes

Erreurs de développement à éviter concernant le sujet de cette unité :

  1. Erreur 401 soudaine après des semaines de succès

    • Problème : Chaque appel renvoie 401 bien que le code n'ait pas changé.
    • Cause : La durée de vie (TTL) du jeton a expiré.
    • Correction : Vérifier la revendication exp du JWT, générer un nouveau jeton, mettre à jour le Secret et émettre une alerte avant la date d'expiration.
  2. Tâches par lots qui déclenchent la limite de débit

    • Problème : Une tâche d'importation émet des centaines de requêtes parallèles et la plupart échouent avec 429.
    • Cause : Chaque modèle autorise 5 requêtes par seconde par contrat, avec de courtes rafales.
    • Correction : Mettre le travail en file d'attente via Kafka et réguler le consommateur (section 4.2) ; consulter X-RateLimit-Remaining-Requests.
  3. Stockage de sorties non validées

    • Problème : Les cartes de tâche affichent des phrases incomplètes ou des résumés vides.
    • Cause : La réponse a atteint max_tokens (finish_reason est length), ou le modèle n'a renvoyé aucun contenu.
    • Correction : Vérifier finish_reason et la longueur avant le stockage, et conserver l'ancien résumé en cas d'échec (section 2.1).

Résumé

Vous pouvez désormais ajouter des fonctionnalités IA à TaskBoard grâce à AI Model Hub. La bibliothèque openai fonctionne avec l'URL de base compatible OpenAI et un jeton bearer IONOS CLOUD. Vous validez les réponses, effectuez le streaming là où les utilisateurs observent, et gérez 429, 503 et 529 à l'aide de Retry-After. Les requêtes individuelles s'exécutent de manière synchrone, les lots transitent par Kafka à un rythme inférieur à la limite de débit, et le cache évite de payer deux fois pour les mêmes jetons. Pour les flux de travail des agents, le IONOS CLOUD MCP Server expose votre compte sous forme d'outils en lecture seule, les écritures n'étant autorisées qu'en cas d'opt-in explicite.

Points clés :

  • URL de base https://openai.inference.de-txl.ionos.com/v1, jeton bearer, identifiants de modèles issus de /v1/models
  • Limites par défaut : 5 requêtes par seconde par modèle, pics de jusqu'à 10, selon le contrat
  • Attendre le temps Retry-After en cas de 429, 503 et 529 ; baser la logique sur les codes d'erreur, non sur les messages
  • Mettre en cache les résultats par modèle et par entrée ; mettre en file d'attente le travail en masse via Kafka
  • Le MCP Server est en lecture seule par défaut ; les écritures nécessitent IONOS_MCP_TOOL_SCOPE, et les créations, suppressions et actions perturbatrices nécessitent une confirmation en deux étapes

Terminologie importante :

  • Identifiant de modèle : La chaîne transmise en tant que model, par exemple mistralai/Mistral-Small-24B-Instruct
  • Limite de pic : Les requêtes supplémentaires autorisées dans une fenêtre de 2 secondes au-dessus du débit de base
  • finish_reason : Le champ qui indique pourquoi la génération s'est arrêtée, par exemple stop ou length
  • MCP : Model Context Protocol, le protocole JSON-RPC par lequel les clients IA appellent les outils
  • Portée des outils : Le niveau IONOS_MCP_TOOL_SCOPE, read, write ou destructive, qui détermine les outils que le serveur enregistre

Prochaines étapes

Continuer l'apprentissage : Unité 4.5 : Vérification des connaissances - Intégration de service

Sujets connexes :