Kutsu API-t tööriistadega
Sellel lehel
Saada tööriistad Mistrali API-le
Oled defineerinud oma funktsioonid ja nende JSON-spetsifikatsioonid. Nüüd tuleb need saata Mistrali API-le ja mis veelgi olulisem – mõista, mida mudel vastuseks tagastab. Oleme jõudnud protsessi 2. ja 3. sammuni: mudel saab kasutaja päringu koos tööriistadega ja genereerib funktsioonikutse või keeldub seda tegemast, mis on sama õpetlik.
Esimene päring
import os
import json
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Eelmises tunnis defineeritud tööriistad
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"]
}
}
}
]
# Kasutaja sõnum
messages = [
{"role": "user", "content": "What is the status of payment T1001?"}
]
# API väljakutse koos tööriistadega
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=tools
)
Mudeli vastuse mõistmine
Vastus sisaldab objekti message, mis võib võtta kaks kuju, ja sinu kood peab mõlemat esimesest päevast peale käsitlema. Esimesel juhul vastab mudel otse, kuna funktsiooni pole vaja: content sisaldab teksti ja tool_calls on None.
# response.choices[0].message.content sisaldab tekstivastust
# response.choices[0].message.tool_calls on None
print(response.choices[0].message.content)
# → "Hello! How can I help you?"
Teisel juhul soovib mudel funktsiooni kutsuda. Olukord on vastupidine: content on tühi või null ja tool_calls kannab kasulikku koormust.
# response.choices[0].message.content on None või tühi
# response.choices[0].message.tool_calls sisaldab kutseid
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}")
Tüüpiline väljund:
Function: retrieve_payment_status
Arguments: {"transaction_id": "T1001"}
ID: call_abc123xyz
Vastuse parsimine ja tool_calls-i eraldamine
Siin on täielik kood teabe puhtaks eraldamiseks tööriistakutsest:
message = response.choices[0].message
if message.tool_calls and len(message.tool_calls) > 0:
tool_call = message.tool_calls[0]
# Funktsiooni nime eraldamine
function_name = tool_call.function.name
# JSON-argumentide parsimine Pythoni sõnastikuks
function_params = json.loads(tool_call.function.arguments)
# Unikaalse kutse identifikaatori hankimine
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:
# Mudel vastas otse
print(f"Response: {message.content}")
Sellest plokist tuleb välja kolm teabekildu ja kolmas on see, mida inimesed unustavad. Funktsiooni nime kasutatakse marsruutimiseks, parsitud argumente kasutatakse väljakutseks, kuid tool_call_id on see, mis võimaldab mudelil seostada sinu tulemust õige kutsega, kui sa selle tagasi saadad. Kui kaotad selle, muutub vestluse voor taastamatuks.
Kui mudel küsib puuduvat teavet
Mõnikord ei anna kasutaja piisavalt teavet. Mudelil on elegantne väljapääs: ära kutsu üldse funktsiooni, vaid esita selgitav küsimus.
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?"
See käitumine on täpselt see, mida soovid. Mudel teab, et transaction_id on loetletud kui required; selle asemel, et leiutada usutav ID ja käivitada päring olematutele andmetele, annab ta sõna kasutajale. See on ka parim demonstratsioon eelmises tunnis käsitletud välja required kasulikkusest.
Süsteemsõnumi käsitlemine
Süsteemsõnum võimaldab sul seda käitumist raamistada, selle lootmise asemel.
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?"}
}
]
Loe seda rida realt: esimene lause määrab rolli, teine assistendi tooni ja keele, kolmas täpsustab, millal funktsioone kasutada, ja viimane annab selge juhise äärmusliku olukorra – puuduva teabe – jaoks. Need on kolm kasutusjuhtu, mille jaoks süsteemsõnumit soovitatakse, ja enamasti piisab neist.
Täielik kood sammudele 2–3
Siin on täielik, uuesti kasutatav kood tööriistadega päringu saatmiseks. See kapseldab kõik eelneva ja normaliseerib vastuse sõnastikuks kahe vormiga, säästes sind if message.tool_calls kontrollide laialilaotamisest üle kogu rakenduse.
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:
"""Saadab Mistralile päringu koos tööriistadega ja tagastab parsitud vastuse."""
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
}
Pane tähele, et loendi mõistmine iterreerib üle kõigi tool_calls, mitte ainult esimese. Mudel võib korraga genereerida mitu; hilisem tund käsitleb seda, kuid sinu utiliidifunktsioon on juba valmis neid käsitlema.
Peamised punktid
- Saada
toolsjamessagesfunktsioonileclient.chat.complete(), et võimaldada funktsioonide kutsumist - Alati kontrolli, kas
message.tool_callseksisteerib, enne kui püüad seda parsida tool_call_idon kohustuslik tulemuse mudelile tagasisaatmiseks- Argumendid on JSON-string, mis tuleb parsida funktsiooniga
json.loads() - Mudel võib valida otsese vastamise, kui ta ei vaja funktsiooni või kui teave puudub