API meghívása eszközökkel
Ezen az oldalon
Eszközök küldése a Mistral API-nak
Már definiáltad a függvényeidet és azok JSON specifikációit. Most el kell küldened ezeket a Mistral API-nak, és ami még fontosabb: meg kell értened, mit válaszol a modell. A folyamat 2. és 3. lépésénél tartunk: a modell megkapja a felhasználói kérést az eszközökkel együtt, és generál egy függvényhívást – vagy elutasítja azt, ami ugyanolyan tanulságos.
Az első kérés
import os
import json
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Az előző leckében definiált eszközök
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"]
}
}
}
]
# Felhasználói üzenet
messages = [
{"role": "user", "content": "What is the status of payment T1001?"}
]
# API hívás eszközökkel
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=tools
)
A modellválasz értelmezése
A válasz egy message objektumot tartalmaz, amely kétféle alakot ölthet, és a kódodnak eleve mindkettőt kezelnie kell. Az első esetben a modell közvetlenül válaszol, mert nincs szükség függvényhívásra: a content szöveget tartalmaz, a tool_calls pedig None.
# response.choices[0].message.content tartalmazza a szöveges választ
# response.choices[0].message.tool_calls értéke None
print(response.choices[0].message.content)
# → "Hello! How can I help you?"
A második esetben a modell függvényt szeretne hívni. A helyzet fordított: a content üres vagy null, a tool_calls pedig tartalmazza a hasznos adatot.
# response.choices[0].message.content értéke None vagy üres
# response.choices[0].message.tool_calls tartalmazza a hívásokat
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}")
Tipikus kimenet:
Function: retrieve_payment_status
Arguments: {"transaction_id": "T1001"}
ID: call_abc123xyz
A válasz feldolgozása és a tool_calls kinyerése
Íme a teljes kód, amellyel tisztán kinyerheted az információkat egy eszköz hívásából:
message = response.choices[0].message
if message.tool_calls and len(message.tool_calls) > 0:
tool_call = message.tool_calls[0]
# Függvénynév kinyerése
function_name = tool_call.function.name
# JSON argumentumok konvertálása Python szótárrá
function_params = json.loads(tool_call.function.arguments)
# Egyedi hívásazonosító lekérése
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:
# A modell közvetlenül válaszolt
print(f"Response: {message.content}")
Ebből a blokkból három információ származik, és a harmadikat szokták elfelejteni. A függvénynevet a dispatcheléshez használod, a parsolt argumentumokat a híváshoz, de a tool_call_id az, ami lehetővé teszi a modell számára, hogy az eredményt a megfelelő híváshoz rendelje, amikor visszaküldöd neki. Ha elveszíted, a beszélgetési kör helyrehozhatatlanná válik.
Amikor a modell hiányzó információt kér
Előfordul, hogy a felhasználó nem ad meg elég információt. Ilyenkor a modellnek van egy elegáns megoldása: egyáltalán nem hív meg függvényt, hanem tisztázó kérdést tesz fel helyette.
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?"
Ez pontosan az a viselkedés, amit szeretnél. A modell tudja, hogy a transaction_id szerepel a required listában; ahelyett, hogy kitalálna egy hihető azonosítót, és nem létező adatokon indítana kérést, átadja a szót a felhasználónak. Ez egyben a legjobb demonstrációja annak, miért hasznos a required mező, amit az előző leckében tárgyaltunk.
A rendszerüzenet kezelése
A rendszerüzenettel keretezheted ezt a viselkedést, ahelyett, hogy csak reménykednél benne.
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?"
}
]
Olvasd soronként: az első mondat beállítja a szerepet, a második a segéd hangnemét és nyelvét, a harmadik meghatározza, mikor használjon függvényeket, az utolsó pedig explicit utasítást ad egy peremeshetre – hiányzó információra. Ezek azok a három használati eset, amelyekre rendszerüzenet ajánlott, és legtöbb esetben elegendők is.
Teljes kód a 2–3. lépésekhez
Íme a teljes, újrahasználható kód eszközökkel történő kérés küldéséhez. Ez összefoglal mindent, amit fentebb láttál, és a választ egy kétféle alakot felvevő szótárba normalizálja, így nem kell szétszórtan if message.tool_calls ellenőrzéseket beépítened az alkalmazásodba.
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:
"""Kérést küld a Mistralnak eszközökkel, és visszaadja a feldolgozott választ."""
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
}
Vedd észre, hogy a listaértelmezés minden tool_calls elemén végigmegy, nem csak az elsőn. A modell egyszerre többet is generálhat; ezt egy későbbi lecke tárgyalja, de a segédfüggvényed már most képes kezelni őket.
Főbb megállapítások
- Küldd el a
toolsésmessagesparamétereket aclient.chat.complete()hívásnak a függvényhívás engedélyezéséhez - Mindig ellenőrizd, hogy létezik-e a
message.tool_calls, mielőtt megpróbálnád feldolgozni - A
tool_call_idkötelező az eredmény modellnek való visszaküldéséhez - Az argumentumok egy JSON sztring, amelyet a
json.loads()függvénnyel kell parsolni - A modell dönthet úgy, hogy közvetlenül válaszol, ha nincs szüksége függvényre, vagy ha hiányzik az információ