Apelarea API-ului cu Instrumente
Pe această pagină
Trimiterea instrumentelor către API-ul Mistral
Ați definit funcțiile și specificațiile lor JSON. Acum trebuie să le trimiteți către API-ul Mistral și, mai important, să înțelegeți ce returnează modelul. Ne aflăm acum la pașii 2 și 3 ai procesului: modelul primește cererea utilizatorului împreună cu instrumentele și produce un apel de funcție – sau refuză să facă unul, ceea ce este la fel de instructiv.
Prima cerere
import os
import json
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Tools defined in the previous lesson
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"]
}
}
}
]
# User message
messages = [
{"role": "user", "content": "What is the status of payment T1001?"}
]
# API call with tools
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=tools
)
Înțelegerea răspunsului modelului
Răspunsul conține un obiect message care poate lua două forme, iar codul dumneavoastră trebuie să le gestioneze pe ambele încă de la început. În primul caz, modelul răspunde direct deoarece nu este necesară nicio funcție: content conține text, iar tool_calls este None.
# response.choices[0].message.content contains the text response
# response.choices[0].message.tool_calls is None
print(response.choices[0].message.content)
# → "Hello! How can I help you?"
În al doilea caz, modelul dorește să apeleze o funcție. Situația se inversează: content este gol sau null, iar tool_calls conține datele utile.
# response.choices[0].message.content is None or empty
# response.choices[0].message.tool_calls contains the calls
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}")
Ieșire tipică:
Function: retrieve_payment_status
Arguments: {"transaction_id": "T1001"}
ID: call_abc123xyz
Analiza răspunsului și extragerea tool_calls
Iată codul complet pentru a extrage corect informațiile dintr-un apel de instrument:
message = response.choices[0].message
if message.tool_calls and len(message.tool_calls) > 0:
tool_call = message.tool_calls[0]
# Extract the function name
function_name = tool_call.function.name
# Parse JSON arguments into a Python dictionary
function_params = json.loads(tool_call.function.arguments)
# Retrieve the unique call identifier
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:
# The model responded directly
print(f"Response: {message.content}")
Din acest bloc rezultă trei informații, iar a treia este cea pe care oamenii o uită adesea. Numele funcției este utilizat pentru direcționare, argumentele analizate sunt folosite pentru apel, dar tool_call_id este ceea ce permite modelului să asocieze rezultatul dumneavoastră cu apelul corect atunci când îl trimiteți înapoi. Dacă îl pierdeți, turul de conversație devine irecuperabil.
Când modelul solicită informații lipsă
Uneori, utilizatorul nu furnizează suficiente informații. Modelul are o soluție elegantă: să nu apeleze deloc o funcție și, în schimb, să pună o întrebare de clarificare.
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?"
Acest comportament este exact ceea ce doriți. Modelul știe că transaction_id este listat în required; în loc să inventeze un ID plauzibil și să declanșeze o cerere pe date inexistente, cedează inițiativa utilizatorului. Aceasta este, de asemenea, cea mai bună demonstrație a utilității câmpului required abordat în lecția anterioară.
Gestionarea mesajului de sistem
Mesajul de sistem vă permite să încadrați acest comportament, în loc să sperați că va apărea natural.
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?"
}
]
Citiți-l linie cu linie: prima propoziție stabilește rolul, a doua stabilește tonul și limba asistentului, a treia specifică când să se utilizeze funcțiile, iar ultima oferă o instrucțiune explicită pentru un caz limită – informații lipsă. Acestea sunt cele trei cazuri de utilizare pentru care se recomandă un mesaj de sistem și sunt suficiente în majoritatea situațiilor.
Cod complet pentru pașii 2–3
Iată codul complet și reutilizabil pentru trimiterea unei cereri cu instrumente. Acesta încapsulează tot ce am văzut mai sus și normalizează răspunsul într-un dicționar cu două forme, scutindu-vă de necesitatea de a împrăștia verificări if message.tool_calls în întreaga aplicație.
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
}
Rețineți că lista comprehensivă iterează peste toate tool_calls, nu doar peste primul. Modelul poate produce mai multe simultan; o lecție viitoare va aborda acest aspect, dar funcția utilitară este deja pregătită să le gestioneze.
Puncte cheie
- Trimiteți
toolsșimessagescătreclient.chat.complete()pentru a activa apelarea funcțiilor - Verificați întotdeauna dacă
message.tool_callsexistă înainte de a încerca analiza tool_call_ideste obligatoriu pentru a trimite rezultatul înapoi modelului- Argumentele sunt un șir JSON care trebuie analizat cu
json.loads() - Modelul poate alege să răspundă direct dacă nu are nevoie de o funcție sau dacă informațiile lipsesc