Produire du JSON structuré avec le SDK Python et des préréglages

​

Objectif

• limiter la taille du code Python appelant
• router à l’aide d’un slug de préréglage plutôt que d’un modèle codé en dur
• demander une sortie JSON stricte et structurée
• conserver suffisamment de métadonnées de réponse pour déboguer le routage ou le comportement des plugins

​

1. Commencer avec un client partagé

import os

from phaseo import Phaseo

gateway = Phaseo(api_key=os.environ["PHASEO_API_KEY"])

​

2. Placer les valeurs par défaut stables dans un préréglage

• le prompt système
• le modèle ou la liste de modèles autorisés
• les préférences de fournisseur
• la configuration du raisonnement
• la température et les paramètres de génération associés
• la politique de mise en cache des réponses si la répétition déterministe est importante

​

3. Demander une forme JSON stricte

response = gateway.generate_response(
    {
        "preset": "release-summary",
        "input": "Summarize the last 24 hours of deployment activity.",
        "response_format": {
            "type": "json_schema",
            "name": "release_summary",
            "schema": {
                "type": "object",
                "required": ["summary", "risk_level"],
                "properties": {
                    "summary": {"type": "string"},
                    "risk_level": {
                        "type": "string",
                        "enum": ["low", "medium", "high"],
                    },
                },
                "additionalProperties": False,
            },
        },
        "plugins": [{"id": "response-healing"}],
        "meta": True,
    }
)

• preset garde le routage et les prompts par défaut hors du code de l’application
• response_format rend le contrat explicite
• plugins peut récupérer un JSON mal formé mais presque valide si le flux de travail le permet
• meta conserve les détails de routage et d’exécution des plugins pour le débogage

​

4. Analyser le JSON et enregistrer les identifiants opérationnels

import json

message_text = ""
for item in response.get("output", []):
    if item.get("type") != "message":
        continue
    for part in item.get("content", []):
        if part.get("type") == "output_text":
            message_text = part.get("text", "")
            break

payload = json.loads(message_text)

print("response_id:", response.get("id"))
print("selected_provider:", response.get("meta", {}).get("routing", {}).get("selected_provider"))
print("plugin_executions:", response.get("meta", {}).get("plugin_executions"))
print(payload)

• la fenêtre des détails de la requête dans le tableau de bord
• les diagnostics de routage
• les métadonnées d’exécution des plugins

​

5. Déboguer avant d’ajouter des exceptions

1. ouvrez la requête sous Gateway -> Utilisation
2. consultez les diagnostics de routage et les fournisseurs candidats
3. examinez les métadonnées d’exécution des plugins si la requête utilisait du JSON structuré
4. ne modifiez le préréglage qu’après avoir compris ce qui s’est passé dans les journaux

​

6. Préserver la compatibilité du cache pour réutiliser les résultats

• gardez le prompt stable
• gardez le schéma de réponse stable
• évitez les remplacements de fournisseur inutiles par requête
• évitez les listes d’outils qui changent souvent

​

Guides associés

• Déployer des préréglages et déboguer le routage
• Utiliser le cache de réponses avec des préréglages
• Réparer les réponses JSON structurées
• Présentation du SDK Python