Kald API'en med værktøjer
På denne side
Send værktøjer til Mistral API
Du har defineret dine funktioner og deres JSON-specifikationer. Nu skal du sende dem til Mistral API og – endnu vigtigere – forstå, hvad modellen returnerer. Vi er nu ved trin 2 og 3 i processen: Modellen modtager brugerens anmodning sammen med værktøjerne og producerer et funktionskald – eller afviser at foretage et, hvilket er lige så lærerigt.
Den første anmodning
import os
import json
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Værktøjer defineret i den tidligere lektion
tools = [
{
"type": "function",
"function": {
"name": "retrieve_payment_status",
"description": "Retrieves the status of a payment based on the transaction ID.",
"parameters": {
"type": "object",
"properties": {
"transaction_id": {
"type": "string",
"description": "Unique transaction identifier (e.g., T1001)"
}
},
"required": ["transaction_id"]
}
}
}
]
# Brugerbemeddelelse
messages = [
{"role": "user", "content": "What is the status of payment T1001?"}
]
# API-kald med værktøjer
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=tools
)
Forståelse af modelsvaret
Svaret indeholder et message-objekt, der kan tage to former, og din kode skal kunne håndtere begge fra dag ét. I det første tilfælde svarer modellen direkte, fordi ingen funktion er nødvendig: content indeholder tekst, og tool_calls er None.
# response.choices[0].message.content indeholder tekstsvar
# response.choices[0].message.tool_calls er None
print(response.choices[0].message.content)
# → "Hello! How can I help you?"
I det andet tilfælde ønsker modellen at kalde en funktion. Situationen vender sig: content er tom eller null, og tool_calls indeholder payloaden.
# response.choices[0].message.content er None eller tom
# response.choices[0].message.tool_calls indeholder kaldene
message = response.choices[0].message
if message.tool_calls:
for tool_call in message.tool_calls:
print(f"Function: {tool_call.function.name}")
print(f"Arguments: {tool_call.function.arguments}")
print(f"ID: {tool_call.id}")
Typisk output:
Function: retrieve_payment_status
Arguments: {"transaction_id": "T1001"}
ID: call_abc123xyz
Parsning af svaret og udtrækning af tool_calls
Her er den komplette kode til rent at udtrække information fra et værktøjskald:
message = response.choices[0].message
if message.tool_calls and len(message.tool_calls) > 0:
tool_call = message.tool_calls[0]
# Udtræk funktionsnavnet
function_name = tool_call.function.name
# Pars JSON-argumenter til en Python-dictionary
function_params = json.loads(tool_call.function.arguments)
# Hent det unikke kald-ID
tool_call_id = tool_call.id
print(f"The model wants to call: {function_name}")
print(f"With parameters: {function_params}")
print(f"Call ID: {tool_call_id}")
else:
# Modellen svarede direkte
print(f"Response: {message.content}")
Tre informationer kommer ud af denne blok, og den tredje er den, folk glemmer. Funktionsnavnet bruges til dispatching, de parsede argumenter bruges til selve kaldet, men tool_call_id er det, der gør det muligt for modellen at knytte dit resultat til det korrekte kald, når du sender det tilbage. Mister du det, bliver samtaleomgangen uoprettelig.
Når modellen anmoder om manglende information
Nogle gange giver brugeren ikke nok information. Modellen har en elegant udvej: Kald slet ingen funktion, og stil i stedet et afklarende spørgsmål.
messages = [
{"role": "user", "content": "What is the status of my payment?"}
]
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=tools
)
message = response.choices[0].message
print(message.content)
# → "I need the transaction ID to check the status.
# Could you please provide the transaction number?"
Denne adfærd er præcis, hvad du ønsker. Modellen ved, at transaction_id er angivet under required; i stedet for at opfinde et sandsynligt ID og udløse en anmodning om ikke-eksisterende data, overlader den ordet til brugeren. Dette er også den bedste demonstration af nytten ved feltet required, som blev dækket i den foregående lektion.
Håndtering af systembeskeden
Systembeskeden giver dig mulighed for at styre denne adfærd, i stedet for blot at håbe på den.
messages = [
{
"role": "system",
"content": "You are a payment tracking assistant. "
"Respond in English. "
"Use the available tools to answer questions "
"about transactions. If the user does not provide "
"the transaction ID, ask for it politely."
},
{
"role": "user",
"content": "What is the status of payment T1001?"
}
]
Læs det linje for linje: Den første sætning fastsætter rollen, den anden fastsætter tonen og sproget for assistenten, den tredje specificerer, hvornår funktioner skal bruges, og den sidste giver en eksplicit instruktion for et specialtilfælde – manglende information. Dette er de tre brugstilfælde, hvor en systembesked anbefales, og de er tilstrækkelige i de fleste tilfælde.
Komplet kode til trin 2–3
Her er den komplette, genanvendelige kode til at sende en anmodning med værktøjer. Den kapsler alt ovenstående ind og normaliserer svaret til en ordbog med to former, hvilket sparer dig for at sprede if message.tool_calls-tjek gennem hele din applikation.
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:
"""Sends a request to Mistral with tools and returns the parsed response."""
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
}
Bemærk, at listekomprehensionen itererer over alle tool_calls, ikke kun det første. Modellen kan producere flere på én gang; en senere lektion vil dække dette, men din hjælpefunktion er allerede klar til at håndtere dem.
Vigtige pointer
- Send
toolsogmessagestilclient.chat.complete()for at aktivere funktionskald - Tjek altid, om
message.tool_callseksisterer, før du forsøger at parse tool_call_ider obligatorisk for at sende resultatet tilbage til modellen- Argumenter er en JSON-streng, der skal parses med
json.loads() - Modellen kan vælge at svare direkte, hvis den ikke har brug for en funktion, eller hvis information mangler