L'appel d'outils dans l'API DipoleML : laissez Raven appeler vos fonctions

Le jour du lancement, le 1er octobre, l'API DipoleML est entrée en service avec Chat Completions, compatible avec OpenAI, la diffusion en continu, la vision et l'usage d'outils. Cette démonstration porte sur l'usage d'outils, aussi appelé appel d'outils ou appel de fonctions : comment donner une fonction à Raven, lire l'appel qu'il fait et renvoyer le résultat. Tout se fait ici avec le SDK Python d'OpenAI, pointé vers notre URL de base.

Qu'est-ce que l'appel d'outils?

Seul, un modèle ne peut qu'écrire du texte. L'appel d'outils lui permet de demander à votre code de faire quelque chose : retrouver une commande, interroger une base de données, consulter la météo. Vous énumérez les fonctions qu'il peut utiliser. Quand une question en exige une, Raven répond par un appel d'outil qui nomme la fonction et donne ses arguments. Votre code l'exécute et renvoie le résultat, et Raven rédige la réponse à partir de ce que votre fonction a retourné.

Comment pointer le SDK d'OpenAI vers l'API DipoleML?

Créez une clé d'API dans votre tableau de bord, ajoutez des crédits et gardez la clé dans une variable d'environnement. Réglez ensuite l'URL de base du client sur la nôtre. Le nom du modèle est Raven Flash ou Raven Max, avec l'espace.

import json, os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.dipoleml.com/v1",
    api_key=os.environ["RAVEN_API_KEY"],
)

Comment décrire une fonction?

Chaque outil est une fonction avec un nom, une description et ses paramètres en JSON Schema. La description est ce que lit le modèle pour décider quand utiliser l'outil : rédigez-la comme vous expliqueriez la fonction à un collègue. Voici une consultation de la météo, avec un substitut à la place du vrai appel :

def get_weather(city):
    return {"city": city, "sky": "clear", "celsius": 4}

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Météo actuelle d'une ville",
        "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"],
        },
    },
}]

Que renvoie Raven?

Quand Raven décide d'utiliser un outil, le finish_reason de la réponse vaut tool_calls, et le message contient les appels plutôt que du texte. Chaque appel a un identifiant, le nom de la fonction et ses arguments sous forme de chaîne JSON :

{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": null,
      "tool_calls": [{
        "id": "<call id>",
        "type": "function",
        "function": {
          "name": "get_weather",
          "arguments": "{\"city\": \"Toronto\"}"
        }
      }]
    },
    "finish_reason": "tool_calls"
  }]
}

Comment renvoyer le résultat?

Ajoutez le message de Raven à la conversation tel quel, puis un message tool par appel, avec le tool_call_id de l'appel et votre résultat comme contenu. Renvoyez la conversation avec les mêmes outils, et recommencez jusqu'à ce que finish_reason vaille stop. Le dernier message est la réponse de Raven :

question = "Ai-je besoin d'un manteau à Toronto aujourd'hui?"
messages = [{"role": "user", "content": question}]
while True:
    resp = client.chat.completions.create(
        model="Raven Flash", messages=messages, tools=tools,
    )
    msg = resp.choices[0].message
    if resp.choices[0].finish_reason != "tool_calls":
        print(msg.content)
        break
    messages.append(msg)
    for call in msg.tool_calls:
        result = get_weather(**json.loads(call.function.arguments))
        messages.append({"role": "tool", "tool_call_id": call.id,
                         "content": json.dumps(result)})

La boucle compte. Une question peut demander plus d'un tour, et une seule réponse peut contenir plusieurs appels à la fois; répondez à chacun avant de renvoyer la conversation.

Puis-je décider quand Raven appelle un outil?

Oui, avec deux champs de la requête :

• tool_choice : "auto" laisse le modèle décider, "none" désactive les appels, "required" demande au moins un appel, et {"type": "function", "function": {"name": "get_weather"}} demande cette fonction-là.
• parallel_tool_calls : false demande au plus un appel par réponse.

Raven n'exécute jamais rien lui-même. Il demande; c'est votre code qui décide quoi exécuter et quoi renvoyer.

Combien coûte l'appel d'outils?

Les définitions d'outils font partie de la requête : elles comptent comme jetons d'entrée à chaque appel qui les envoie, tout comme les résultats que vous renvoyez. Raven Flash coûte 0,50 $ US par million de jetons d'entrée et 2,50 $ US par million de jetons de sortie; Raven Max coûte 1,25 $ US et 6,25 $ US. Les appels sont payés à même des crédits prépayés qui n'expirent jamais, et tous les prix sont sur la page des tarifs.

Où aller ensuite?

La page de l'API présente ce que l'API DipoleML prend en charge. Pour choisir un modèle, consultez les modèles Raven; pour les essayer avant d'écrire du code, ouvrez le bac à sable.