Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Volanie API pomocou nástrojov

Lekcia 5 z 14 Aktualizované 2. novembra 2026 Vývojár
Na tejto strane
  1. Odoslanie nástrojov do API Mistral
  2. Prvá požiadavka
  3. Pochopenie odpovede modelu
  4. Parsovanie odpovede a extrakcia tool_calls
  5. Keď model požiada o chýbajúce informácie
  6. Správa systémovej správy
  7. Kompletný kód pre kroky 2–3
  8. Kľúčové poznatky

Odoslanie nástrojov do API Mistral

Definoval si svoje funkcie a ich JSON špecifikácie. Teraz ich musíš odoslať do API Mistral a čo je dôležitejšie, pochopiť, čo model vráti. Práve sme v krokoch 2 a 3 procesu: model dostane požiadavku používateľa spolu s nástrojmi a vygeneruje volanie funkcie – alebo ho odmietne, čo je rovnako poučné.

Prvá požiadavka

import os
import json
from mistralai.client import Mistral

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

# Nástroje definované v predchádzajúcej lekcii
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"]
            }
        }
    }
]

# Správa používateľa
messages = [
    {"role": "user", "content": "What is the status of payment T1001?"}
]

# Volanie API s nástrojmi
response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools
)

Pochopenie odpovede modelu

Odpoveď obsahuje objekt message, ktorý môže mať dve formy a tvoj kód musí od prvého dňa zvládať obe. V prvom prípade model odpovedá priamo, pretože nie je potrebná žiadna funkcia: content obsahuje text a tool_calls je None.

# response.choices[0].message.content obsahuje textovú odpoveď
# response.choices[0].message.tool_calls je None
print(response.choices[0].message.content)
# → "Hello! How can I help you?"

V druhom prípade chce model zavolať funkciu. Situácia sa obráti: content je prázdne alebo null a tool_calls nesie dátový obsah.

# response.choices[0].message.content je None alebo prázdne
# response.choices[0].message.tool_calls obsahuje volania
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}")

Typický výstup:

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

Parsovanie odpovede a extrakcia tool_calls

Tu je kompletný kód na čisté extrahovanie informácií z volania nástroja:

message = response.choices[0].message

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

    # Extrahovanie názvu funkcie
    function_name = tool_call.function.name

    # Parsovanie JSON argumentov do Python slovníka
    function_params = json.loads(tool_call.function.arguments)

    # Získanie unikátneho identifikátora volania
    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:
    # Model odpovedal priamo
    print(f"Response: {message.content}")

Z tohto bloku vyplývajú tri kľúčové informácie a tá tretia je tá, na ktorú ľudia najčastejšie zabúdajú. Názov funkcie sa používa na smerovanie (dispatching), parsované argumenty na samotné volanie, ale tool_call_id je to, čo umožňuje modelu priradiť tvoj výsledok k správnemu volaniu, keď mu ho pošleš späť. Ak ho stratíš, celý krok konverzácie sa stane neobnoviteľným.

Keď model požiada o chýbajúce informácie

Niekedy používateľ neposkytne dostatok informácií. Model má elegantné riešenie: nezavolá žiadnu funkciu, ale namiesto toho položí objasňujúcu otázku.

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

Toto správanie je presne to, čo chceš. Model vie, že transaction_id je uvedené v required; namiesto toho, aby si vymyslel pravdepodobné ID a spustil požiadavku na neexistujúce údaje, prepustí slovo používateľovi. Je to tiež najlepšia ukážka užitočnosti poľa required, ktoré sme prebrali v predchádzajúcej lekcii.

Správa systémovej správy

Systémová správa ti umožňuje toto správanie rámovať, namiesto toho, aby si naň len dúfal.

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

Prečítaj si to riadok po riadku: prvá veta nastavuje rolu, druhá tón a jazyk asistenta, tretia špecifikuje, kedy používať funkcie, a posledná dáva explicitný pokyn pre hraničný prípad – chýbajúce informácie. Toto sú tri prípady použitia, pre ktoré sa systémová správa odporúča, a vo väčšine prípadov stačia.

Kompletný kód pre kroky 2–3

Tu je kompletný, opakovane použiteľný kód na odoslanie požiadavky s nástrojmi. Zapuzdruje všetko vyššie uvedené a normalizuje odpoveď do slovníka s dvoma formami, čím ťa ušetrí od roztrúsených kontrol if message.tool_calls v celej tvojej aplikácii.

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:
    """Odošle požiadavku do Mistral s nástrojmi a vráti parsovanú odpoveď."""
    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
    }

Všimni si, že list comprehension iteruje cez všetky tool_calls, nielen cez prvé. Model ich môže vygenerovať niekoľko naraz; neskoršia lekcia to pokryje, ale tvoja pomocná funkcia je už pripravená ich spracovať.

Kľúčové poznatky

  • Pošli tools a messages do client.chat.complete(), aby si povolil volanie funkcií
  • Vždy skontroluj, či message.tool_calls existuje, predtým než sa pokúsiš o parsovanie
  • tool_call_id je povinný na odoslanie výsledku späť modelu
  • Argumenty sú JSON reťazec, ktorý musíš parsovať pomocou json.loads()
  • Model sa môže rozhodnúť odpovedať priamo, ak nepotrebuje funkciu alebo ak chýbajú informácie