Volanie API pomocou nástrojov
Na tejto strane
Odoslanie nástrojov do API Mistral
Definoval si svoje funkcie a ich JSON špecifikácie. Teraz ich musíš odoslať do API Mistral a čo je dôležitejšie, pochopiť, čo model vráti. Práve sme v krokoch 2 a 3 procesu: model dostane požiadavku používateľa spolu s nástrojmi a vygeneruje volanie funkcie – alebo ho odmietne, čo je rovnako poučné.
Prvá požiadavka
import os
import json
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Nástroje definované v predchádzajúcej lekcii
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"]
}
}
}
]
# Správa používateľa
messages = [
{"role": "user", "content": "What is the status of payment T1001?"}
]
# Volanie API s nástrojmi
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=tools
)
Pochopenie odpovede modelu
Odpoveď obsahuje objekt message, ktorý môže mať dve formy a tvoj kód musí od prvého dňa zvládať obe. V prvom prípade model odpovedá priamo, pretože nie je potrebná žiadna funkcia: content obsahuje text a tool_calls je None.
# response.choices[0].message.content obsahuje textovú odpoveď
# response.choices[0].message.tool_calls je None
print(response.choices[0].message.content)
# → "Hello! How can I help you?"
V druhom prípade chce model zavolať funkciu. Situácia sa obráti: content je prázdne alebo null a tool_calls nesie dátový obsah.
# response.choices[0].message.content je None alebo prázdne
# response.choices[0].message.tool_calls obsahuje volania
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}")
Typický výstup:
Function: retrieve_payment_status
Arguments: {"transaction_id": "T1001"}
ID: call_abc123xyz
Parsovanie odpovede a extrakcia tool_calls
Tu je kompletný kód na čisté extrahovanie informácií z volania nástroja:
message = response.choices[0].message
if message.tool_calls and len(message.tool_calls) > 0:
tool_call = message.tool_calls[0]
# Extrahovanie názvu funkcie
function_name = tool_call.function.name
# Parsovanie JSON argumentov do Python slovníka
function_params = json.loads(tool_call.function.arguments)
# Získanie unikátneho identifikátora volania
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 odpovedal priamo
print(f"Response: {message.content}")
Z tohto bloku vyplývajú tri kľúčové informácie a tá tretia je tá, na ktorú ľudia najčastejšie zabúdajú. Názov funkcie sa používa na smerovanie (dispatching), parsované argumenty na samotné volanie, ale tool_call_id je to, čo umožňuje modelu priradiť tvoj výsledok k správnemu volaniu, keď mu ho pošleš späť. Ak ho stratíš, celý krok konverzácie sa stane neobnoviteľným.
Keď model požiada o chýbajúce informácie
Niekedy používateľ neposkytne dostatok informácií. Model má elegantné riešenie: nezavolá žiadnu funkciu, ale namiesto toho položí objasňujúcu otázku.
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?"
Toto správanie je presne to, čo chceš. Model vie, že transaction_id je uvedené v required; namiesto toho, aby si vymyslel pravdepodobné ID a spustil požiadavku na neexistujúce údaje, prepustí slovo používateľovi. Je to tiež najlepšia ukážka užitočnosti poľa required, ktoré sme prebrali v predchádzajúcej lekcii.
Správa systémovej správy
Systémová správa ti umožňuje toto správanie rámovať, namiesto toho, aby si naň len dúfal.
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?"}
}
]
Prečítaj si to riadok po riadku: prvá veta nastavuje rolu, druhá tón a jazyk asistenta, tretia špecifikuje, kedy používať funkcie, a posledná dáva explicitný pokyn pre hraničný prípad – chýbajúce informácie. Toto sú tri prípady použitia, pre ktoré sa systémová správa odporúča, a vo väčšine prípadov stačia.
Kompletný kód pre kroky 2–3
Tu je kompletný, opakovane použiteľný kód na odoslanie požiadavky s nástrojmi. Zapuzdruje všetko vyššie uvedené a normalizuje odpoveď do slovníka s dvoma formami, čím ťa ušetrí od roztrúsených kontrol if message.tool_calls v celej tvojej aplikácii.
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:
"""Odošle požiadavku do Mistral s nástrojmi a vráti parsovanú odpoveď."""
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
}
Všimni si, že list comprehension iteruje cez všetky tool_calls, nielen cez prvé. Model ich môže vygenerovať niekoľko naraz; neskoršia lekcia to pokryje, ale tvoja pomocná funkcia je už pripravená ich spracovať.
Kľúčové poznatky
- Pošli
toolsamessagesdoclient.chat.complete(), aby si povolil volanie funkcií - Vždy skontroluj, či
message.tool_callsexistuje, predtým než sa pokúsiš o parsovanie tool_call_idje povinný na odoslanie výsledku späť modelu- Argumenty sú JSON reťazec, ktorý musíš parsovať pomocou
json.loads() - Model sa môže rozhodnúť odpovedať priamo, ak nepotrebuje funkciu alebo ak chýbajú informácie