Volání API pomocí nástrojů
Na této stránce
Odeslání nástrojů do API Mistral
Definoval jsi své funkce a jejich specifikace ve formátu JSON. Nyní je musíš odeslat do API Mistral a co je důležitější, pochopit, co model vrátí. Právě teď se nacházíme ve krocích 2 a 3 celého procesu: model obdrží uživatelský požadavek spolu s nástroji a vytvoří volání funkce – nebo se rozhodne žádné neprovést, což je stejně poučné.
První požadavek
import os
import json
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Nástroje definované v předchozí lekci
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"]
}
}
}
]
# Zpráva od uživatele
messages = [
{"role": "user", "content": "What is the status of payment T1001?"}
]
# Volání API s nástroji
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=tools
)
Pochopení odpovědi modelu
Odpověď obsahuje objekt message, který může nabývat dvou forem, a tvůj kód musí od prvního dne umět zpracovat obě. V prvním případě model odpoví přímo, protože není potřeba žádná funkce: content obsahuje text a tool_calls má hodnotu None.
# response.choices[0].message.content obsahuje textovou odpověď
# response.choices[0].message.tool_calls je None
print(response.choices[0].message.content)
# → "Hello! How can I help you?"
Ve druhém případě chce model zavolat funkci. Situace se obrátí: content je prázdné nebo null a tool_calls nese datový obsah.
# response.choices[0].message.content je None nebo prázdné
# response.choices[0].message.tool_calls obsahuje volání
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
Parsování odpovědi a extrakce tool_calls
Zde je kompletní kód pro čistou extrakci informací z volání nástroje:
message = response.choices[0].message
if message.tool_calls and len(message.tool_calls) > 0:
tool_call = message.tool_calls[0]
# Extrahování názvu funkce
function_name = tool_call.function.name
# Parsování argumentů JSON do Python slovníku
function_params = json.loads(tool_call.function.arguments)
# Získání unikátního identifikátoru volání
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 odpověděl přímo
print(f"Response: {message.content}")
Z tohoto bloku vyplývají tři klíčové informace, přičemž na tu třetí lidé často zapomínají. Název funkce slouží k směrování (dispatching), parsované argumenty se použijí pro samotné volání, ale tool_call_id je to, co umožňuje modelu při zpětném odeslání výsledku přiřadit odpověď ke správnému volání. Pokud ho ztratíš, celý krok konverzace se stane neobnovitelným.
Když model požaduje chybějící informace
Někdy uživatel neposkytne dostatek informací. Model má elegantní řešení: nezavolá žádnou funkci, ale místo toho položí upřesňující 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 chování je přesně to, co chceš. Model ví, že transaction_id je uvedeno v poli required; místo aby si vymyslel pravděpodobné ID a spustil požadavek na neexistujících datech, přenechá slovo uživateli. Je to také nejlepší demonstrace užitečnosti pole required, které jsme probírali v předchozí lekci.
Zpracování systémové zprávy
Systémová zpráva ti umožňuje toto chování rámecovat, místo abys na něj jen doufal.
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?"
}
]
Přečti si to řádek po řádku: první věta nastavuje roli, druhá určuje tón a jazyk asistenta, třetí specifikuje, kdy používat funkce, a poslední dává explicitní instrukci pro okrajový případ – chybějící informace. To jsou tři hlavní případy použití, pro které se systémová zpráva doporučuje, a ve většině případů zcela stačí.
Kompletní kód pro kroky 2–3
Zde je kompletní, znovu použitelný kód pro odeslání požadavku s nástroji. Zapouzdřuje vše výše uvedené a normalizuje odpověď do slovníku se dvěma formami, což tě ušetří roztroušených kontrol if message.tool_calls v celé tvé aplikaci.
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:
"""Odešle požadavek do Mistral s nástroji a vrátí parsovanou odpověď."""
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 přes všechna tool_calls, nejen přes první. Model jich může najednou vygenerovat několik; pozdější lekce se tím bude zabývat, ale tvá pomocná funkce je již připravena je zpracovat.
Klíčové poznatky
- Odešli
toolsamessagesdoclient.chat.complete(), abys povolil volání funkcí. - Vždy zkontroluj, zda
message.tool_callsexistuje, než se pokusíš o parsování. tool_call_idje povinný pro odeslání výsledku zpět modelu.- Argumenty jsou JSON řetězec, který musíš parsovat pomocí
json.loads(). - Model se může rozhodnout odpovědět přímo, pokud nepotřebuje funkci nebo pokud chybí informace.