Iškviesti API naudojant įrankius
Šiame puslapyje
Siųsti įrankius į „Mistral“ API
Apibrėžei savo funkcijas ir jų JSON specifikacijas. Dabar turi jas išsiųsti į „Mistral“ API ir, svarbiausia, suprasti, ką grąžina modelis. Dabar esame 2 ir 3 proceso žingsniuose: modelis gauna naudotojo užklausą kartu su įrankiais ir sugeneruoja funkcijos iškvietimą – arba atsisako tai daryti, kas taip pat yra pamokoma.
Pirmoji užklausa
import os
import json
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Įrankiai, apibrėžti ankstesnėje pamokoje
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"]
}
}
}
]
# Naudotojo žinutė
messages = [
{"role": "user", "content": "What is the status of payment T1001?"}
]
# API iškvietimas su įrankiais
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=tools
)
Modelio atsako supratimas
Atsakyme yra message objektas, kuris gali įgyti dvi formas, ir tavo kodas turi jas abi apdoroti nuo pat pradžių. Pirmuoju atveju modelis atsako tiesiogiai, nes funkcija nereikalinga: content saugo tekstą, o tool_calls yra None.
# response.choices[0].message.content turi tekstinį atsakymą
# response.choices[0].message.tool_calls yra None
print(response.choices[0].message.content)
# → "Hello! How can I help you?"
Antruoju atveju modelis nori iškviesti funkciją. Situacija apsiverčia: content yra tuščias arba null, o tool_calls turi naudingąją informaciją.
# response.choices[0].message.content yra None arba tuščias
# response.choices[0].message.tool_calls turi iškvietimus
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ška išvestis:
Function: retrieve_payment_status
Arguments: {"transaction_id": "T1001"}
ID: call_abc123xyz
Atsako analizavimas ir tool_calls išgavimas
Štai visas kodas, kaip švariai išgauti informaciją iš įrankio iškvietimo:
message = response.choices[0].message
if message.tool_calls and len(message.tool_calls) > 0:
tool_call = message.tool_calls[0]
# Išgauti funkcijos pavadinimą
function_name = tool_call.function.name
# Išanalizuoti JSON argumentus į Python žodyną
function_params = json.loads(tool_call.function.arguments)
# Gauti unikalų iškvietimo identifikatorių
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:
# Modelis atsakė tiesiogiai
print(f"Response: {message.content}")
Iš šio bloko gaunami trys informacijos gabalai, ir trečiasis yra tas, kurį žmonės dažnai pamiršta. Funkcijos pavadinimas naudojamas nukreipimui, išanalizuoti argumentai – iškvietimui, tačiau tool_call_id yra tai, kas leidžia modeliui susieti tavo rezultatą su tinkamu iškvietimu, kai jį siunti atgal. Jį praradus, dialogo eigos atkurti nebeįmanoma.
Kai modelis prašo trūkstamos informacijos
Kartais naudotojas nepateikia pakankamai informacijos. Modelis turi elegantišką išeitį: visiškai nekviesti funkcijos, o užduoti patikslinamąjį klausimą.
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?"
Toks elgesys yra būtent tai, ko nori. Modelis žino, kad transaction_id yra išvardytas kaip required; vietoj to, kad sugalvotų tikėtiną ID ir inicijuotų užklausą dėl neegzistuojančių duomenų, jis perleidžia žodį naudotojui. Tai taip pat geriausiai parodo required lauko, nagrinėto ankstesnėje pamokoje, naudą.
Sistemos žinutės tvarkymas
Sistemos žinutė leidžia suformuoti šį elgesį, o ne tikėtis jo atsitiktinai.
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?"
}
]
Perskaityk tai eilutė po eilutės: pirmas sakinys nustato vaidmenį, antras – asistento toną ir kalbą, trečias nurodo, kada naudoti funkcijas, o paskutinis pateikia aiškų nurodymą kraštutiniam atvejui – trūkstamai informacijai. Tai trys naudojimo atvejai, kuriems rekomenduojama sistemos žinutė, ir jų dažniausiai pakanka.
Visas kodas 2–3 žingsniams
Štai visas, daugkartinio naudojimo kodas užklausai su įrankiais siųsti. Jis apima viską, kas išdėstyta aukščiau, ir normalizuoja atsakymą į žodyną su dviem formomis, taip sutaupydamas tau poreikio barstyti if message.tool_calls tikrinimus visoje tavo programoje.
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
}
Atkreipk dėmesį, kad sąrašo supratimas (list comprehension) iteruoja per visus tool_calls, o ne tik per pirmąjį. Modelis gali sugeneruoti kelis vienu metu; vėlesnė pamoka tai aptars, tačiau tavo pagalbinė funkcija jau yra paruošta juos apdoroti.
Svarbiausi punktai
- Siųsk
toolsirmessagesįclient.chat.complete(), kad įgalintum funkcijų iškvietimą - Visada patikrink, ar egzistuoja
message.tool_calls, prieš bandydamas analizuoti tool_call_idyra privalomas siunčiant rezultatą atgal modeliui- Argumentai yra JSON eilutė, kurią reikia išanalizuoti naudojant
json.loads() - Modelis gali pasirinkti atsakyti tiesiogiai, jei jam nereikia funkcijos arba jei trūksta informacijos