Klicanje API-ja z orodji
Na tej strani
Pošiljanje orodji API-ju Mistral
Definiral si svoje funkcije in njihove specifikacije JSON. Zdaj jih moraš poslati API-ju Mistral in, kar je še pomembneje, razumeti, kaj model vrne. Zdaj si pri korakih 2 in 3 procesa: model prejme uporabniško zahtevo skupaj z orodji in ustvari klic funkcije – ali pa ga zavrne, kar je enako poučno.
Prva zahteva
import os
import json
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Orodja, definirana v prejšnji lekciji
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"]
}
}
}
]
# Uporabniško sporočilo
messages = [
{"role": "user", "content": "What is the status of payment T1001?"}
]
# Klic API-ja z orodji
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=tools
)
Razumevanje odziva modela
Odziv vsebuje predmet message, ki ima lahko dve obliki, tvoja koda pa mora od prvega dne obravnavati obe. V prvem primeru model odgovori neposredno, ker funkcija ni potrebna: content vsebuje besedilo, tool_calls pa je None.
# response.choices[0].message.content vsebuje besedilni odgovor
# response.choices[0].message.tool_calls je None
print(response.choices[0].message.content)
# → "Hello! How can I help you?"
V drugem primeru model želi poklicati funkcijo. Situacija se obrne: content je prazen ali null, tool_calls pa nosi podatke.
# response.choices[0].message.content je None ali prazen
# response.choices[0].message.tool_calls vsebuje klice
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}")
Tipičen izpis:
Function: retrieve_payment_status
Arguments: {"transaction_id": "T1001"}
ID: call_abc123xyz
Razčlenjevanje odziva in ekstrakcija tool_calls
Tukaj je celotna koda za čisto ekstrakcijo informacij iz klica orodja:
message = response.choices[0].message
if message.tool_calls and len(message.tool_calls) > 0:
tool_call = message.tool_calls[0]
# Ekstrakcija imena funkcije
function_name = tool_call.function.name
# Razčlenjevanje argumentov JSON v slovar Python
function_params = json.loads(tool_call.function.arguments)
# Pridobitev edinstvenega identifikatorja klica
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 je odgovoril neposredno
print(f"Response: {message.content}")
Iz tega bloka izhajajo trije deli informacij, tretji pa je tisti, na katerega ljudje pozabijo. Ime funkcije se uporablja za usmerjanje, razčlenjeni argumenti za klic, vendar je tool_call_id tisto, kar modelu omogoča, da tvoj rezultat poveže s pravilnim klicem, ko ga pošlješ nazaj. Če ga izgubiš, postane zavoj pogovora neobnovljiv.
Ko model zahteva manjkajoče informacije
Včasih uporabnik ne navede dovolj informacij. Model ima eleganten izhod: funkcije sploh ne pokliče, ampak namesto tega postavi pojasnjevalno vprašanje.
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?"
To vedenje je točno tisto, kar želiš. Model ve, da je transaction_id naveden v required; namesto da bi izumil verjeten ID in sprožil zahtevo za neobstoječe podatke, prepusti besedo uporabniku. To je tudi najboljša demonstracija uporabnosti polja required, obravnavanega v prejšnji lekciji.
Obravnava sistemskega sporočila
Sistemsko sporočilo ti omogoča, da to vedenje okvirjaš, namesto da bi upal nanj.
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?"
}
]
Preberi ga vrstico za vrstico: prvi stavek določa vlogo, drugi ton in jezik asistenta, tretji določa, kdaj uporabiti funkcije, zadnji pa daje izrecno navodilo za robni primer – manjkajoče informacije. To so trije primeri uporabe, za katere je sistemsko sporočilo priporočljivo, in večinoma zadostujejo.
Celotna koda za koraka 2–3
Tukaj je celotna, ponovno uporabna koda za pošiljanje zahteve z orodji. Zajema vse zgoraj navedeno in normalizira odziv v slovar z dvema oblikama, kar te rešuje razpršenih preverjanj if message.tool_calls po tvoji aplikaciji.
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:
"""Pošlje zahtevo Mistralu z orodji in vrne razčlenjen odziv."""
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
}
Upoštevaj, da seznamsko razumevanje iterira čez vse tool_calls, ne le čez prvega. Model lahko ustvari več klicev hkrati; to bo obravnavano v kasnejši lekciji, vendar je tvoja pomožna funkcija že pripravljena za njihovo obravnavo.
Ključne ugotovitve
- Pošlji
toolsinmessagesvclient.chat.complete(), da omogočiš klicanje funkcij - Vedno preveri, ali
message.tool_callsobstaja, preden poskušaš razčleniti tool_call_idje obvezen za pošiljanje rezultata nazaj modelu- Argumenti so niz JSON, ki ga je treba razčleniti z
json.loads() - Model se lahko odloči za neposreden odgovor, če funkcije ne potrebuje ali če informacije manjkajo