Pozivanje API-ja s alatima
Na ovoj stranici
Slanje alata Mistral API-ju
Definirao si svoje funkcije i njihove JSON specifikacije. Sada ih trebaš poslati Mistral API-ju i, što je još važnije, razumjeti što model vraća. Sada smo na koracima 2 i 3 procesa: model prima korisnički zahtjev zajedno s alatima i proizvodi poziv funkcije – ili odbija izvršiti ga, što je jednako poučno.
Prvi zahtjev
import os
import json
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Alati definirani u prethodnoj lekciji
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"]
}
}
}
]
# Korisnička poruka
messages = [
{"role": "user", "content": "What is the status of payment T1001?"}
]
# API poziv s alatima
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=tools
)
Razumijevanje odgovora modela
Odgovor sadrži objekt message koji može imati dva oblika, a tvoj kod mora od prvog dana rukovati obama. U prvom slučaju, model odgovara izravno jer funkcija nije potrebna: content sadrži tekst, a tool_calls je None.
# response.choices[0].message.content sadrži tekstualni odgovor
# response.choices[0].message.tool_calls je None
print(response.choices[0].message.content)
# → "Hello! How can I help you?"
U drugom slučaju, model želi pozvati funkciju. Situacija je obrnuta: content je prazan ili null, a tool_calls nosi podatke.
# response.choices[0].message.content je None ili prazan
# response.choices[0].message.tool_calls sadrži pozive
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}")
Tipičan ispis:
Function: retrieve_payment_status
Arguments: {"transaction_id": "T1001"}
ID: call_abc123xyz
Raščlanjivanje odgovora i izdvajanje tool_calls
Evo cjelovitog koda za čisto izdvajanje informacija iz poziva alata:
message = response.choices[0].message
if message.tool_calls and len(message.tool_calls) > 0:
tool_call = message.tool_calls[0]
# Izdvajanje naziva funkcije
function_name = tool_call.function.name
# Raščlanjivanje JSON argumenata u Python rječnik
function_params = json.loads(tool_call.function.arguments)
# Dohvaćanje jedinstvenog identifikatora poziva
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:
# Model je odgovorio izravno
print(f"Response: {message.content}")
Iz ovog bloka proizlaze tri podatka, a treći je onaj koji ljudi često zaborave. Naziv funkcije koristi se za usmjeravanje, raščlanjeni argumenti za poziv, ali tool_call_id je ono što modelu omogućuje povezivanje tvog rezultata s ispravnim pozivom kada ga pošalješ natrag. Ako ga izgubiš, taj okret razgovora postaje neopoziv.
Kada model zatraži nedostajuće informacije
Ponekad korisnik ne pruži dovoljno informacija. Model ima elegantan izlaz: uopće ne poziva funkciju, već postavlja razjašnjavajuće pitanje.
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?"
Ovo ponašanje je točno ono što želiš. Model zna da je transaction_id naveden u required; umjesto da izmisli uvjerljiv ID i pokrene zahtjev za nepostojećim podacima, prepusta riječ korisniku. Ovo je također najbolja demonstracija korisnosti polja required obrađenog u prethodnoj lekciji.
Rukovanje sistemskom porukom
Sistemska poruka omogućuje ti da okvirno odrediš ovo ponašanje umjesto da se nadaš da će se dogoditi samo od sebe.
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?"
}
]
Pročitaj red po red: prva rečenica postavlja ulogu, druga ton i jezik asistenta, treća specificira kada koristiti funkcije, a zadnja daje eksplicitnu uputu za rubni slučaj – nedostatak informacija. To su tri slučaja upotrebe za koje se preporučuje sistemska poruka i oni u većini slučajeva sufficeiraju.
Cjeloviti kod za korake 2–3
Evo cjelovitog, višekratno upotrebljivog koda za slanje zahtjeva s alatima. On obuhvaća sve gore navedeno i normalizira odgovor u rječnik s dva oblika, štedeći ti raspršivanje provjera if message.tool_calls kroz cijelu aplikaciju.
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
}
Imaj na umu da lista komprehenzije iterira kroz sve tool_calls, a ne samo kroz prvi. Model može proizvesti nekoliko odjednom; kasnija lekcija će to pokriti, ali tvoja pomoćna funkcija već je spremna rukovati njima.
Ključne točke
- Pošalji
toolsimessagesuclient.chat.complete()kako bi omogućio pozivanje funkcija - Uvijek provjeri postoji li
message.tool_callsprije pokušaja raščlanjivanja tool_call_idje obavezan za slanje rezultata natrag modelu- Argumenti su JSON niz koji se mora raščlaniti s
json.loads() - Model može odlučiti odgovoriti izravno ako ne treba funkciju ili ako nedostaju informacije