TokenLab

Guides essentiels

Sorties structurées et appel d'outils

Retournez du JSON ou laissez un modèle appeler des fonctions dans votre application

La sortie structurée demande au modèle de fournir du JSON. L'appel d'outils permet au modèle de demander l'exécution d'une fonction par votre application. Les champs disponibles dépendent du format de l'API et du modèle ; conservez donc le même format tout au long de la conversation et validez chaque valeur produite par le modèle dans votre application.

Choisir un format d'API

BesoinAPIChamps
Réponses sous forme d'objet JSON portable/v1/chat/completionsresponse_format: {"type": "json_object"}
Appel de fonction compatible OpenAI/v1/chat/completionstools: [{ "type": "function", "function": ... }]
Outils de réponses OpenAI/v1/responsesChamps tools, tool_choice et text des réponses
Utilisation d'outils ou réflexion native Claude/v1/messagesSchéma d'outils Anthropic Messages
Déclarations de fonction ou outils intégrés Gemini/v1beta/models/:model:generateContenttools et parties de contenu natives Gemini

Utilisez les outils intégrés uniquement avec le format d'API qui les documente ; TokenLab ne convertit pas ces outils entre les différents formats.

Mode JSON

Pour un objet JSON fonctionnant avec de nombreux modèles de chat, utilisez le mode JSON de Chat Completions :

{
  "model": "gpt-5.6-terra",
  "messages": [
    {
      "role": "user",
      "content": "Return a JSON object with city and weather."
    }
  ],
  "response_format": { "type": "json_object" }
}

Les modèles prenant en charge le mode JSON listent json-mode dans les capabilities via GET /v1/models. Chat Completions accepte text et json_object. json_schema et strict sont spécifiques au modèle et au format ; utilisez-les uniquement lorsque le modèle sélectionné documente leur prise en charge.

Analysez et validez toujours le JSON retourné sur votre serveur. Le mode JSON ne remplace pas la validation de schéma au niveau de l'application.

Effectuer un appel d'outil

TokenLab retourne le nom de la fonction et les arguments ; votre application les exécute :

  1. Envoyez les messages ainsi que les définitions d'outils.
  2. Lisez la réponse du modèle pour tool_calls, function_call, tool_use d'Anthropic, ou les parties d'appel de fonction Gemini.
  3. Exécutez l'outil dans votre propre backend.
  4. Ajoutez le résultat de l'outil dans le même format d'API.
  5. Poursuivez la conversation jusqu'à ce que le modèle retourne une réponse finale.

Conservez le même format d'API jusqu'à ce que l'appel d'outil et la réponse finale soient terminés. Les quatre formats représentent l'état de l'outil de manières différentes.

Exemple de Chat Completions

curl https://api.tokenlab.sh/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra",
    "messages": [
      {
        "role": "user",
        "content": "Extract name and email as JSON. If needed, look up the customer."
      }
    ],
    "response_format": { "type": "json_object" },
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "lookup_customer",
          "description": "Look up a customer by email",
          "parameters": {
            "type": "object",
            "properties": {
              "email": { "type": "string" }
            },
            "required": ["email"]
          }
        }
      }
    ]
  }'

Rédiger un schéma utile

  • Gardez les schémas simples et explicites. Les schémas imbriqués volumineux ajoutent des tokens et réduisent la fiabilité.
  • Privilégiez les champs obligatoires pour les valeurs dont votre produit ne peut se passer.
  • Utilisez des enums pour les ensembles fermés dont dépendent votre interface ou votre backend.
  • Incluez des exemples dans le prompt lorsque le modèle a des difficultés avec une structure.
  • Si un champ n'est pas pris en charge, supprimez-le ou utilisez un format d'API qui le documente.

Avant d'exécuter un outil

  • Enregistrez le format d'API, le modèle, les noms des outils et les noms des champs du schéma.
  • Validez les arguments de l'outil avant d'exécuter tout effet de bord.
  • Appliquez vos propres contrôles d'autorisation avant l'exécution de l'outil.
  • Rendez l'exécution de l'outil idempotente lorsqu'une nouvelle tentative du client peut répéter le même appel d'outil.
  • Ne consignez pas les secrets retournés par les outils dans les messages visibles par le modèle.

Référence API

SujetRéférence
API multi-formatAPI multi-format
Créer une complétion de chatCréer une complétion de chat
Créer une réponseCréer une réponse
Créer un messageCréer un message
Générer du contenu GeminiGénérer du contenu Gemini

Sur cette page