Pāriet uz galveno saturu
Latviešu— Izvēlēties valodu
Izvēlne

Izsaukt API, izmantojot rīkus

Nodarbība 5 no 14 Atjaunota 2026. gada 2. novembris Programmētājs
Šajā lapā
  1. Nosūti rīkus Mistral API
  2. Pirmais pieprasījums
  3. Modeļa atbildes izpratne
  4. Atbildes parsēšana un tool_calls iegūšana
  5. Kad modelis pieprasa trūkstošo informāciju
  6. Sistēmas ziņojuma apstrāde
  7. Pilns kods 2.–3. solim
  8. Galvenās atziņas

Nosūti rīkus Mistral API

Tu esi definējis savas funkcijas un to JSON specifikācijas. Tagad tās ir jānosūta Mistral API, un, kas ir vēl svarīgāk, jāsaprot, ko modelis atgriež. Mēs esam nonākuši pie procesa 2. un 3. soļa: modelis saņem lietotāja pieprasījumu kopā ar rīkiem un ģenerē funkcijas izsaukumu — vai arī atsakās to darīt, kas ir tikpat vērtīgi.

Pirmais pieprasījums

import os
import json
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

# Tools defined in the previous lesson
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"]
            }
        }
    }
]

# User message
messages = [
    {"role": "user", "content": "What is the status of payment T1001?"}
]

# API call with tools
response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools
)

Modeļa atbildes izpratne

Atbilde satur message objektu, kas var pieņemt divas formas, un tavam kodam ir jāspēj apstrādāt abas jau no paša sākuma. Pirmajā gadījumā modelis atbild tieši, jo funkcija nav nepieciešama: content satur tekstu, bet tool_calls ir None.

# response.choices[0].message.content contains the text response
# response.choices[0].message.tool_calls is None
print(response.choices[0].message.content)
# → "Hello! How can I help you?"

Otrajā gadījumā modelis vēlas izsaukt funkciju. Situācija ir apgriezta: content ir tukšs vai null, bet tool_calls satur noderīgo informāciju.

# response.choices[0].message.content is None or empty
# response.choices[0].message.tool_calls contains the calls
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}")

Tipiska izvade:

Function: retrieve_payment_status
Arguments: {"transaction_id": "T1001"}
ID: call_abc123xyz

Atbildes parsēšana un tool_calls iegūšana

Lūk, pilns kods, lai tīri iegūtu informāciju no rīka izsaukuma:

message = response.choices[0].message

if message.tool_calls and len(message.tool_calls) > 0:
    tool_call = message.tool_calls[0]

    # Extract the function name
    function_name = tool_call.function.name

    # Parse JSON arguments into a Python dictionary
    function_params = json.loads(tool_call.function.arguments)

    # Retrieve the unique call identifier
    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:
    # The model responded directly
    print(f"Response: {message.content}")

No šī bloka izriet trīs informācijas vienības, un trešā ir tā, ko cilvēki bieži aizmirst. Funkcijas nosaukums tiek izmantots maršrutēšanai, parsētie argumenti — izsaukuma veikšanai, bet tool_call_id ir tas, kas ļauj modelim sasaistīt tavu rezultātu ar pareizo izsaukumu, kad to nosūti atpakaļ. Ja to pazaudēsi, sarunas gaita kļūs neatjaunojama.

Kad modelis pieprasa trūkstošo informāciju

Dažreiz lietotājs nesniedz pietiekami daudz informācijas. Modelim ir elegants risinājums: neizsaukt funkciju vispār, bet tā vietā uzdot precizējošu jautājumu.

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?"

Šī uzvedība ir tieši tāda, kādu tu vēlies. Modelis zina, ka transaction_id ir norādīts kā required; tā vietā, lai izgudrotu ticamu ID un izraisītu pieprasījumu uz neeksistējošiem datiem, tas nodod vārdu lietotājam. Tas ir arī labākais pierādījums required lauka lietderībai, ko aplūkojām iepriekšējā nodarbībā.

Sistēmas ziņojuma apstrāde

Sistēmas ziņojums ļauj tev ierāmēt šo uzvedību, nevis cerēt uz to.

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?"
    }
]

Izlasi to rindu pa rindai: pirmais teikums nosaka lomu, otrais — asistenta toni un valodu, trešais precizē, kad izmantot funkcijas, bet pēdējais sniedz tiešu norādījumu robežgadījumam — trūkstošai informācijai. Tie ir trīs lietojuma gadījumi, kuros sistēmas ziņojums ir ieteicams, un vairumā gadījumu ar to pietiek.

Pilns kods 2.–3. solim

Lūk, pilns, atkārtoti izmantojams kods pieprasījuma nosūtīšanai ar rīkiem. Tas apkopo visu iepriekš minēto un normalizē atbildi vārdnīcā ar divām formām, atbrīvojot tevi no nepieciešamības izkaisīt if message.tool_calls pārbaudes visā lietotnē.

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
    }

Ņem vērā, ka saraksta izpratne iterē cauri visiem tool_calls, ne tikai pirmajam. Modelis var ģenerēt vairākus vienlaicīgi; vēlākā nodarbībā to aplūkosim, bet tava utilītfunkcija jau ir gatava tos apstrādāt.

Galvenās atziņas

  • Nosūti tools un messages uz client.chat.complete(), lai aktivizētu funkciju izsaukšanu
  • Vienmēr pārbaudi, vai eksistē message.tool_calls, pirms mēģini veikt parsēšanu
  • tool_call_id ir obligāts, lai nosūtītu rezultātu atpakaļ modelim
  • Argumenti ir JSON virkne, kas jāparsē, izmantojot json.loads()
  • Modelis var izvēlēties atbildēt tieši, ja tam nav nepieciešama funkcija vai ja trūkst informācijas