API mit Tools aufrufen
Auf dieser Seite
Tools an die Mistral-API senden
Sie haben Ihre Funktionen und deren JSON-Spezifikationen definiert. Nun müssen Sie diese an die Mistral-API senden und, noch wichtiger, verstehen, was das Modell zurückgibt. Wir befinden uns nun bei Schritt 2 und 3 des Prozesses: Das Modell erhält die Benutzeranfrage zusammen mit den Tools und erzeugt einen Funktionsaufruf – oder lehnt ihn ab, was ebenso lehrreich ist.
Die erste Anfrage
import os
import json
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Tools aus der vorherigen Lektion definiert
tools = [
{
"type": "function",
"function": {
"name": "retrieve_payment_status",
"description": "Ruft den Status einer Zahlung basierend auf der Transaktions-ID ab.",
"parameters": {
"type": "object",
"properties": {
"transaction_id": {
"type": "string",
"description": "Einzigartige Transaktionskennung (z. B. T1001)"
}
},
"required": ["transaction_id"]
}
}
}
]
# Benutzer-Nachricht
messages = [
{"role": "user", "content": "Wie ist der Status der Zahlung T1001?"}
]
# API-Aufruf mit Tools
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=tools
)
Verständnis der Modellantwort
Die Antwort enthält ein message-Objekt, das zwei Formen annehmen kann. Ihr Code muss dies von Anfang an berücksichtigen. Im ersten Fall antwortet das Modell direkt, da keine Funktion benötigt wird: content enthält Text, und tool_calls ist None.
# response.choices[0].message.content enthält den Text der Antwort
# response.choices[0].message.tool_calls ist None
print(response.choices[0].message.content)
# → "Hallo! Wie kann ich Ihnen helfen?"
Im zweiten Fall möchte das Modell eine Funktion aufrufen. Die Situation kehrt sich um: content ist leer oder null, und tool_calls enthält die Nutzlast.
# response.choices[0].message.content ist None oder leer
# response.choices[0].message.tool_calls enthält die Aufrufe
message = response.choices[0].message
if message.tool_calls:
for tool_call in message.tool_calls:
print(f"Funktion: {tool_call.function.name}")
print(f"Argumente: {tool_call.function.arguments}")
print(f"ID: {tool_call.id}")
Typische Ausgabe:
Funktion: retrieve_payment_status
Argumente: {"transaction_id": "T1001"}
ID: call_abc123xyz
Parsen der Antwort und Extrahieren von tool_calls
Hier ist der vollständige Code, um Informationen aus einem Tool-Aufruf sauber zu extrahieren:
message = response.choices[0].message
if message.tool_calls and len(message.tool_calls) > 0:
tool_call = message.tool_calls[0]
# Funktionennamen extrahieren
function_name = tool_call.function.name
# JSON-Argumente in ein Python-Dictionary parsen
function_params = json.loads(tool_call.function.arguments)
# Die eindeutige Kennung des Aufrufs abrufen
tool_call_id = tool_call.id
print(f"Das Modell möchte aufrufen: {function_name}")
print(f"Mit Parametern: {function_params}")
print(f"Aufruf-ID: {tool_call_id}")
else:
# Das Modell hat direkt geantwortet
print(f"Antwort: {message.content}")
Aus diesem Block ergeben sich drei Informationen, und die dritte ist diejenige, die oft übersehen wird. Der Funktionsname dient zur Weiterleitung (Dispatch), die geparsenen Argumente werden für den Aufruf verwendet, aber die tool_call_id ermöglicht es dem Modell, Ihr Ergebnis beim Zurücksenden mit dem korrekten Aufruf zu verknüpfen. Verlieren Sie diese, wird der Gesprächswechsel unrettbar.
Wenn das Modell fehlende Informationen anfordert
Manchmal liefert der Benutzer nicht genügend Informationen. Das Modell verfügt über eine elegante Lösung: Es ruft keine Funktion auf, sondern stellt stattdessen eine klärende Frage.
messages = [
{"role": "user", "content": "Wie ist der Status meiner Zahlung?"}
]
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=tools
)
message = response.choices[0].message
print(message.content)
# → "Ich benötige die Transaktions-ID, um den Status zu prüfen.
# Könnten Sie mir bitte die Transaktionsnummer mitteilen?"
Dieses Verhalten ist genau das, was Sie wollen. Das Modell weiß, dass transaction_id in required aufgeführt ist; anstatt eine plausible ID zu erfinden und eine Anfrage für nicht existierende Daten auszulösen, gibt es das Wort an den Benutzer ab. Dies ist auch die beste Demonstration des Nutzens des required-Felds, das in der vorherigen Lektion behandelt wurde.
Handhabung der System-Nachricht
Die System-Nachricht ermöglicht es Ihnen, dieses Verhalten zu rahmen, anstatt darauf zu hoffen, dass es eintritt.
messages = [
{
"role": "system",
"content": "Sie sind ein Assistent zur Verfolgung von Zahlungen. "
"Antworten Sie auf Englisch. "
"Verwenden Sie die verfügbaren Tools, um Fragen zu Transaktionen zu beantworten. "
"Falls der Benutzer die Transaktions-ID nicht bereitstellt, bitten Sie höflich darum."
},
{
"role": "user",
"content": "Wie ist der Status der Zahlung T1001?"
}
]
Lesen Sie Zeile für Zeile: Der erste Satz setzt die Rolle, der zweite den Ton und die Sprache des Assistenten fest, der dritte gibt an, wann Funktionen zu verwenden sind, und der letzte gibt eine explizite Anweisung für einen Sonderfall – fehlende Informationen. Dies sind die drei Anwendungsfälle, für die eine System-Nachricht empfohlen wird, und sie reichen in den meisten Fällen aus.
Vollständiger Code für Schritte 2–3
Hier ist der vollständige, wiederverwendbare Code zum Senden einer Anfrage mit Tools. Er kapselt alles oben Genannte und normalisiert die Antwort in ein Dictionary mit zwei Formen, sodass Sie if message.tool_calls-Prüfungen nicht über Ihre gesamte Anwendung verstreuen müssen.
import os
import json
from mistralai.client import Mistral
def call_mistral_with_tools(
messages: list,
tools: list,
model: str = "mistral-large-latest",
tool_choice: str = "auto"
) -> dict:
"""Sendet eine Anfrage an Mistral mit Tools und gibt die geparte Antwort zurück."""
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
response = client.chat.complete(
model=model,
messages=messages,
tools=tools,
tool_choice=tool_choice
)
message = response.choices[0].message
if message.tool_calls and len(message.tool_calls) > 0:
return {
"type": "tool_call",
"message": message,
"tool_calls": [
{
"id": tc.id,
"function_name": tc.function.name,
"arguments": json.loads(tc.function.arguments)
}
for tc in message.tool_calls
]
}
return {
"type": "text",
"message": message,
"content": message.content
}
Beachten Sie, dass der List-Comprehension über alle tool_calls iteriert, nicht nur über den ersten. Das Modell kann mehrere auf einmal erzeugen; eine spätere Lektion wird dies behandeln, aber Ihre Hilfsfunktion ist bereits bereit, sie zu verarbeiten.
Kernaussagen
- Senden Sie
toolsundmessagesanclient.chat.complete(), um Funktionsaufrufe zu ermöglichen. - Prüfen Sie immer, ob
message.tool_callsexistiert, bevor Sie versuchen, diese zu parsen. - Die
tool_call_idist obligatorisch, um das Ergebnis an das Modell zurückzusenden. - Argumente sind eine JSON-String, die mit
json.loads()geparsed werden muss. - Das Modell kann entscheiden, direkt zu antworten, wenn es keine Funktion benötigt oder wenn Informationen fehlen.