Pereiti prie pagrindinio turinio
Lietuvių— Pasirinkite kalbą
Meniu

Iškviesti API naudojant įrankius

Paskaita 5 iš 14 Atnaujinta 2026 m. lapkričio 2 d. Kūrėjas
Šiame puslapyje
  1. Siųsti įrankius į „Mistral“ API
  2. Pirmoji užklausa
  3. Modelio atsako supratimas
  4. Atsako analizavimas ir tool_calls išgavimas
  5. Kai modelis prašo trūkstamos informacijos
  6. Sistemos žinutės tvarkymas
  7. Visas kodas 2–3 žingsniams
  8. Svarbiausi punktai

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 tools ir messages į client.chat.complete(), kad įgalintum funkcijų iškvietimą
  • Visada patikrink, ar egzistuoja message.tool_calls, prieš bandydamas analizuoti
  • tool_call_id yra 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