Sejjaħ l-API b'Tools
F'din il-paġna
Ibgħat it-Tools lill-API ta’ Mistral
Iddefinixxejt il-funzjonijiet tiegħek u l-ispeċifikazzjonijiet JSON tagħhom. Issa trid tibgħathom lill-API ta’ Mistral u, l-aktar importanti, tifhem x’jirritorna l-mudell. Qegħdin issa fil-passi 2 u 3 tal-proċess: il-mudell jirċievi t-talba tal-utent flimkien mat-tools u jipproduċi sejħa ta’ funzjoni—jew jiċħad li jagħmel waħda, li huwa wkoll informattiv daqstant.
L-Ewwel Talba
import os
import json
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Tools definiti fil-lezzjoni preċedenti
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"]
}
}
}
]
# Messaġġ tal-utent
messages = [
{"role": "user", "content": "What is the status of payment T1001?"}
]
# Sejħa tal-API b'tools
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=tools
)
Nifhmu r-Risposta tal-Mudell
Ir-risposta fiha oġġett message li jista’ jieħu żewġ forom, u l-kodiċi tiegħek irid jittratta t-tnejn mill-ewwel jum. Fl-ewwel każ, il-mudell iwieġeb direttament għax m’hemmx bżonn ta’ funzjoni: content fih test, u tool_calls huwa None.
# response.choices[0].message.content fih ir-risposta tat-test
# response.choices[0].message.tool_calls huwa None
print(response.choices[0].message.content)
# → "Hello! How can I help you?"
Fit-tieni każ, il-mudell irid isejaħ funzjoni. Is-sitwazzjoni tinverti: content huwa vojt jew null, u tool_calls iġorr id-data.
# response.choices[0].message.content huwa None jew vojt
# response.choices[0].message.tool_calls fih is-sejħiet
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}")
Output tipiku:
Function: retrieve_payment_status
Arguments: {"transaction_id": "T1001"}
ID: call_abc123xyz
Analiżi tar-Risposta u Estrazzjoni ta’ tool_calls
Hawnhekk hawn il-kodiċi sħiħ biex testraċċja l-informazzjoni minn sejħa ta’ tool b’mod nadif:
message = response.choices[0].message
if message.tool_calls and len(message.tool_calls) > 0:
tool_call = message.tool_calls[0]
# Estrai l-isem tal-funzjoni
function_name = tool_call.function.name
# Analizza l-argumenti JSON f'dizzjunarju Python
function_params = json.loads(tool_call.function.arguments)
# Irkupra l-identifikatur uniku tas-sejħa
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:
# Il-mudell wieġeb direttament
print(f"Response: {message.content}")
Tliet biċċiet ta’ informazzjoni joħorġu minn dan il-blokk, u t-tielet waħda hija dik li n-nies jinsu spiss. L-isem tal-funzjoni jintuża għad-dispaċċjar, l-argumenti analizzati jintużaw għas-sejħa, iżda t-tool_call_id huwa dak li jippermetti lill-mudell jassoċja r-riżultat tiegħek mas-sejħa korretta meta tibgħath lura. Titlifux, inkella d-dawra tal-konversazzjoni ssir irrikuperabbli.
Meta l-Mudell Jitlob Informazzjoni Nieqsa
Xi kultant l-utent ma jipprovdix biżżejjed informazzjoni. Il-mudell għandu mod eleganti biex joħroġ minnha: ma jsejjaħ l-ebda funzjoni affattu, u minflok jistaqsi mistoqsija ta’ ċarifikazzjoni.
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?"
Dan l-imġiba huwa eżattament dak li trid. Il-mudell jaf li transaction_id huwa elenkat f’required; minflok jinventa ID plawżibbli u jattiva talba fuq data li ma teżistix, iħalli l-post lill-utent. Din hija wkoll l-aħjar dimostrazzjoni tal-utilità tal-kamp required kopert fil-lezzjoni preċedenti.
Kif Tittratta l-Messaġġ tas-Sistema
Il-messaġġ tas-sistema jħallik tifforma dan l-imġiba minflok ma tittama biss għalih.
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?"
}
]
Aqrah linja b’linja: l-ewwel sentenza tistabbilixxi r-rwol, it-tieni tistabbilixxi t-ton u l-lingwa tal-assistent, it-tielet tispeċifika meta tuża l-funzjonijiet, u l-aħħar tagħti istruzzjoni espliċita għal każ marġinali—informazzjoni nieqsa. Dawn huma t-tliet każijiet ta’ użu li għalihom huwa rrakkomandat messaġġ tas-sistema, u dawn huma biżżejjed il-biċċa l-kbira tal-ħin.
Kodiċi Sħiħ għall-Passi 2–3
Hawnhekk hawn il-kodiċi sħiħ u riutilizzabbli biex tibgħat talba b’tools. Dan jinkapsula kollox hawn fuq u jinnormalizza r-risposta f’dizzjunarju b’żewġ forom, u jiffrankalek milli tferrax kontrolli if message.tool_calls mal-applikazzjoni tiegħek kollha.
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:
"""Jibgħat talba lil Mistral b'tools u jirritorna r-risposta analizzata."""
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
}
Innota li l-list comprehension tgħaddi fuq kull tool_calls, mhux biss l-ewwel wieħed. Il-mudell jista’ jipproduċi diversi f’daqqa; lezzjoni aktar tard se tkopri dan, iżda l-funzjoni ta’ utilità tiegħek diġà hija lesti biex tittrattahom.
Punti Ewlenin
- Ibghat
toolsumessageslilclient.chat.complete()biex tattivaw is-sejħa tal-funzjonijiet - Dejjem iċċekkja jekk
message.tool_callsjeżistix qabel ma tipprova tanalizza - It-
tool_call_idhuwa obbligatorju biex tibgħat ir-riżultat lura lill-mudell - L-argumenti huma stringa JSON li trid tiġi analizzata b’
json.loads() - Il-mudell jista’ jagħżel li jwieġeb direttament jekk ma jkollux bżonn ta’ funzjoni jew jekk tkun nieqsa informazzjoni