Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Sejjaħ l-API b'Tools

Lezzjoni 5 / 14 Aġġornat 2 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. Ibgħat it-Tools lill-API ta’ Mistral
  2. L-Ewwel Talba
  3. Nifhmu r-Risposta tal-Mudell
  4. Analiżi tar-Risposta u Estrazzjoni ta’ tool_calls
  5. Meta l-Mudell Jitlob Informazzjoni Nieqsa
  6. Kif Tittratta l-Messaġġ tas-Sistema
  7. Kodiċi Sħiħ għall-Passi 2–3
  8. Punti Ewlenin

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 tools u messages lil client.chat.complete() biex tattivaw is-sejħa tal-funzjonijiet
  • Dejjem iċċekkja jekk message.tool_calls jeżistix qabel ma tipprova tanalizza
  • It-tool_call_id huwa 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