Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Kutsu API-t tööriistadega

Õppetund 5 / 14 Värskendatud 2. november 2026 Arendajatele
Sellel lehel
  1. Saada tööriistad Mistrali API-le
  2. Esimene päring
  3. Mudeli vastuse mõistmine
  4. Vastuse parsimine ja tool_calls-i eraldamine
  5. Kui mudel küsib puuduvat teavet
  6. Süsteemsõnumi käsitlemine
  7. Täielik kood sammudele 2–3
  8. Peamised punktid

Saada tööriistad Mistrali API-le

Oled defineerinud oma funktsioonid ja nende JSON-spetsifikatsioonid. Nüüd tuleb need saata Mistrali API-le ja mis veelgi olulisem – mõista, mida mudel vastuseks tagastab. Oleme jõudnud protsessi 2. ja 3. sammuni: mudel saab kasutaja päringu koos tööriistadega ja genereerib funktsioonikutse või keeldub seda tegemast, mis on sama õpetlik.

Esimene päring

import os
import json
from mistralai.client import Mistral

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

# Eelmises tunnis defineeritud tööriistad
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"]
            }
        }
    }
]

# Kasutaja sõnum
messages = [
    {"role": "user", "content": "What is the status of payment T1001?"}
]

# API väljakutse koos tööriistadega
response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools
)

Mudeli vastuse mõistmine

Vastus sisaldab objekti message, mis võib võtta kaks kuju, ja sinu kood peab mõlemat esimesest päevast peale käsitlema. Esimesel juhul vastab mudel otse, kuna funktsiooni pole vaja: content sisaldab teksti ja tool_calls on None.

# response.choices[0].message.content sisaldab tekstivastust
# response.choices[0].message.tool_calls on None
print(response.choices[0].message.content)
# → "Hello! How can I help you?"

Teisel juhul soovib mudel funktsiooni kutsuda. Olukord on vastupidine: content on tühi või null ja tool_calls kannab kasulikku koormust.

# response.choices[0].message.content on None või tühi
# response.choices[0].message.tool_calls sisaldab kutseid
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}")

Tüüpiline väljund:

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

Vastuse parsimine ja tool_calls-i eraldamine

Siin on täielik kood teabe puhtaks eraldamiseks tööriistakutsest:

message = response.choices[0].message

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

    # Funktsiooni nime eraldamine
    function_name = tool_call.function.name

    # JSON-argumentide parsimine Pythoni sõnastikuks
    function_params = json.loads(tool_call.function.arguments)

    # Unikaalse kutse identifikaatori hankimine
    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:
    # Mudel vastas otse
    print(f"Response: {message.content}")

Sellest plokist tuleb välja kolm teabekildu ja kolmas on see, mida inimesed unustavad. Funktsiooni nime kasutatakse marsruutimiseks, parsitud argumente kasutatakse väljakutseks, kuid tool_call_id on see, mis võimaldab mudelil seostada sinu tulemust õige kutsega, kui sa selle tagasi saadad. Kui kaotad selle, muutub vestluse voor taastamatuks.

Kui mudel küsib puuduvat teavet

Mõnikord ei anna kasutaja piisavalt teavet. Mudelil on elegantne väljapääs: ära kutsu üldse funktsiooni, vaid esita selgitav küsimus.

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

See käitumine on täpselt see, mida soovid. Mudel teab, et transaction_id on loetletud kui required; selle asemel, et leiutada usutav ID ja käivitada päring olematutele andmetele, annab ta sõna kasutajale. See on ka parim demonstratsioon eelmises tunnis käsitletud välja required kasulikkusest.

Süsteemsõnumi käsitlemine

Süsteemsõnum võimaldab sul seda käitumist raamistada, selle lootmise asemel.

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

Loe seda rida realt: esimene lause määrab rolli, teine assistendi tooni ja keele, kolmas täpsustab, millal funktsioone kasutada, ja viimane annab selge juhise äärmusliku olukorra – puuduva teabe – jaoks. Need on kolm kasutusjuhtu, mille jaoks süsteemsõnumit soovitatakse, ja enamasti piisab neist.

Täielik kood sammudele 2–3

Siin on täielik, uuesti kasutatav kood tööriistadega päringu saatmiseks. See kapseldab kõik eelneva ja normaliseerib vastuse sõnastikuks kahe vormiga, säästes sind if message.tool_calls kontrollide laialilaotamisest üle kogu rakenduse.

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:
    """Saadab Mistralile päringu koos tööriistadega ja tagastab parsitud vastuse."""
    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
    }

Pane tähele, et loendi mõistmine iterreerib üle kõigi tool_calls, mitte ainult esimese. Mudel võib korraga genereerida mitu; hilisem tund käsitleb seda, kuid sinu utiliidifunktsioon on juba valmis neid käsitlema.

Peamised punktid

  • Saada tools ja messages funktsioonile client.chat.complete(), et võimaldada funktsioonide kutsumist
  • Alati kontrolli, kas message.tool_calls eksisteerib, enne kui püüad seda parsida
  • tool_call_id on kohustuslik tulemuse mudelile tagasisaatmiseks
  • Argumendid on JSON-string, mis tuleb parsida funktsiooniga json.loads()
  • Mudel võib valida otsese vastamise, kui ta ei vaja funktsiooni või kui teave puudub