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
| Besoin | API | Champs |
|---|---|---|
| Réponses sous forme d'objet JSON portable | /v1/chat/completions | response_format: {"type": "json_object"} |
| Appel de fonction compatible OpenAI | /v1/chat/completions | tools: [{ "type": "function", "function": ... }] |
| Outils de réponses OpenAI | /v1/responses | Champs tools, tool_choice et text des réponses |
| Utilisation d'outils ou réflexion native Claude | /v1/messages | Schéma d'outils Anthropic Messages |
| Déclarations de fonction ou outils intégrés Gemini | /v1beta/models/:model:generateContent | tools 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 :
- Envoyez les messages ainsi que les définitions d'outils.
- Lisez la réponse du modèle pour
tool_calls,function_call,tool_used'Anthropic, ou les parties d'appel de fonction Gemini. - Exécutez l'outil dans votre propre backend.
- Ajoutez le résultat de l'outil dans le même format d'API.
- 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
| Sujet | Référence |
|---|---|
| API multi-format | API multi-format |
| Créer une complétion de chat | Créer une complétion de chat |
| Créer une réponse | Créer une réponse |
| Créer un message | Créer un message |
| Générer du contenu Gemini | Générer du contenu Gemini |