Documentation Officielle de l'API d'Appel de Fonction (Function Calling)

Cette interface est utilisée pour créer une complétion de chat (Chat Completion). En fournissant une liste de messages et une liste d'outils optionnels (Functions), le modèle peut générer une réponse textuelle ou générer des paramètres conformes à un schéma JSON spécifique pour appeler une fonction externe.

1. Informations de l'API

Point de terminaison (Endpoint) : https://api.codingplanx.ai/v1/chat/completions
Méthode de requête : POST
Type de contenu : application/json
Méthode d'authentification : Authorization: Bearer {{YOUR_API_KEY}}

2. Paramètres de Requête

2.1 En-têtes de Requête (Headers)

Nom du paramètre	Type	Requis	Exemple	Description
Content-Type	string	Oui	`application/json`	Fixé à `application/json`
Accept	string	Oui	`application/json`	Recommandé d'être fixé à `application/json`
Authorization	string	Oui	`Bearer sk-xxxxxx`	Authentification par clé API

2.2 Corps de la Requête (Body)

Nom du paramètre	Type	Requis	Valeur par défaut	Description
model	string	Oui	-	L'ID du modèle à utiliser (ex. `gpt-4o`, `gpt-3.5-turbo`, etc.).
messages	array	Oui	-	Liste des messages de la conversation jusqu'à présent. Chaque objet contient un `role` ("system", "user", "assistant", "tool") et un `content`.
tools	array	Oui	-	Liste des outils que le modèle peut appeler. Actuellement, seul `type: "function"` est pris en charge. Utilisé pour définir le nom de la fonction, sa description et ses paramètres.
tool_choice	object/str	Non	`auto`	Contrôle quelle fonction le modèle appelle. `none` : aucun appel ; `auto` : sélection automatique ; `{"type": "function", "function": {"name": "xxx"}}` : force l'appel d'une fonction spécifique.
temperature	number	Non	1	Température d'échantillonnage (0-2). Plus elle est élevée, plus le résultat est aléatoire ; plus elle est basse, plus il est déterministe.
top_p	number	Non	1	Probabilité d'échantillonnage par noyau (nucleus sampling).
n	integer	Non	1	Nombre de choix de complétions de chat à générer pour chaque message d'entrée.
stream	boolean	Non	false	Si la diffusion (streaming) est activée. S'il est défini sur `true`, les jetons (tokens) seront envoyés sous forme d'événements envoyés par le serveur (SSE).
stop	string/array	Non	null	Séquence d'arrêt où l'API cessera de générer de nouveaux jetons.
max_tokens	integer	Non	inf	Nombre maximum de jetons (tokens) à générer.
presence_penalty	number	Non	0	Compris entre -2.0 et 2.0. Augmente la probabilité que le modèle aborde de nouveaux sujets.
frequency_penalty	number	Non	0	Compris entre -2.0 et 2.0. Réduit la probabilité que le modèle répète le même contenu.
response_format	object	Non	-	Spécifie le format de sortie. Par exemple, `{"type": "json_object"}` active le mode JSON.
seed	integer	Non	-	Si spécifié, le système fera de son mieux pour échantillonner de manière déterministe, de sorte que les requêtes avec la même graine (seed) et les mêmes paramètres renvoient les mêmes résultats.
user	string	Non	-	Identifiant unique représentant l'utilisateur final, utilisé pour surveiller les abus.

3. Exemple de Requête

{
    "model": "gpt-4o",
    "messages": [
        {
            "role": "user",
            "content": "Quel temps fait-il à Pékin aujourd'hui ?"
        }
    ],
    "tools": [
        {
            "type": "function",
            "function": {
                "name": "get_current_weather",
                "description": "Obtenir la météo actuelle pour un emplacement spécifique",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "location": {
                            "type": "string",
                            "description": "Nom de la ville, par exemple : Pékin"
                        },
                        "unit": {
                            "type": "string",
                            "enum": ["celsius", "fahrenheit"]
                        }
                    },
                    "required": ["location"]
                }
            }
        }
    ],
    "tool_choice": "auto",
    "temperature": 0.8
}

4. Paramètres de Réponse

4.1 Structure du Corps de la Réponse

Nom du paramètre	Type	Description
id	string	Identifiant unique de cette requête.
object	string	Type d'objet, généralement `chat.completion`.
created	integer	Horodatage Unix (en secondes).
choices	array	Contient la liste des réponses générées.
└ message	object	Contient `role`, `content` et potentiellement `tool_calls`.
└ finish_reason	string	Raison de l'arrêt. `stop` (arrêt naturel), `length` (a atteint max_tokens), `tool_calls` (nécessite l'appel d'un outil).
usage	object	Statistiques d'utilisation : `prompt_tokens`, `completion_tokens`, `total_tokens`.

4.2 Exemple de Réponse (Texte Normal)

{
    "id": "chatcmpl-123",
    "object": "chat.completion",
    "created": 1677652288,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "Il fait beau à Pékin aujourd'hui, la température est de 25 degrés Celsius."
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 9,
        "completion_tokens": 14,
        "total_tokens": 23
    }
}

5. FAQ (Foire Aux Questions)

Q1 : Qu'est-ce que l'Appel de Fonction (Function Calling) ? R : Il s'agit d'un moyen de donner au modèle la capacité de faire appel à des fonctionnalités externes. Le modèle n'exécute pas le code directement. Au lieu de cela, sur la base de votre description, il génère un objet JSON contenant le nom de la fonction et les paramètres requis. Vous devez extraire ce JSON, exécuter la fonction localement ou sur votre serveur, puis renvoyer le résultat au modèle.

Q2 : Pourquoi le modèle ne renvoie-t-il pas tool_calls alors que j'ai configuré tools ? R : Il peut y avoir plusieurs raisons :

Le modèle considère que la question de l'utilisateur ne nécessite pas l'appel de cette fonction.
La description de votre fonction (description) n'est pas assez claire, empêchant le modèle de faire correspondre l'intention.
tool_choice a été explicitement défini sur none.
Limitations des capacités du modèle (il est recommandé d'utiliser en priorité des modèles qui prennent bien en charge les appels d'outils, tels que gpt-4o ou gpt-3.5-turbo).

Q3 : Comment forcer le modèle à appeler une fonction spécifique ? R : Vous pouvez définir tool_choice sur un objet spécifique, par exemple : "tool_choice": {"type": "function", "function": {"name": "get_current_weather"}}. De cette façon, même si le modèle ne le juge pas nécessaire, il essaiera de générer les paramètres pour cette fonction.

Q4 : Que dois-je faire si la raison de l'arrêt (finish_reason) est length ? R : Cela signifie que la réponse générée a dépassé la limite de max_tokens ou la limite de la fenêtre de contexte du modèle. Vous pouvez essayer d'augmenter le paramètre max_tokens ou de réduire la longueur de l'historique des messages.

Q5 : Quelles sont les précautions à prendre lors de l'utilisation du mode JSON (JSON Mode) ? R : Lors de la configuration de response_format: { "type": "json_object" }, il est obligatoire de demander explicitement au modèle de produire du contenu au format JSON dans le message Système ou Utilisateur (par exemple, en incluant "répondre au format JSON"). Sinon, le modèle risque de se bloquer dans une boucle infinie générant des espaces.

Q6 : Comment gérer plusieurs appels d'outils en même temps ? R : Lors d'une seule requête, le modèle peut générer plusieurs appels d'outils simultanément (par exemple, pour vérifier la météo à Pékin et à Shanghai en même temps). Vous devez parcourir le tableau choices[0].message.tool_calls et exécuter la logique locale correspondante pour chaque appel.