Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Klicanje API-ja z orodji

Lekcija 5 od 14 Posodobljeno 2. november 2026 Razvijalec
Na tej strani
  1. Pošiljanje orodji API-ju Mistral
  2. Prva zahteva
  3. Razumevanje odziva modela
  4. Razčlenjevanje odziva in ekstrakcija tool_calls
  5. Ko model zahteva manjkajoče informacije
  6. Obravnava sistemskega sporočila
  7. Celotna koda za koraka 2–3
  8. Ključne ugotovitve

Pošiljanje orodji API-ju Mistral

Definiral si svoje funkcije in njihove specifikacije JSON. Zdaj jih moraš poslati API-ju Mistral in, kar je še pomembneje, razumeti, kaj model vrne. Zdaj si pri korakih 2 in 3 procesa: model prejme uporabniško zahtevo skupaj z orodji in ustvari klic funkcije – ali pa ga zavrne, kar je enako poučno.

Prva zahteva

import os
import json
from mistralai.client import Mistral

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

# Orodja, definirana v prejšnji lekciji
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"]
            }
        }
    }
]

# Uporabniško sporočilo
messages = [
    {"role": "user", "content": "What is the status of payment T1001?"}
]

# Klic API-ja z orodji
response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools
)

Razumevanje odziva modela

Odziv vsebuje predmet message, ki ima lahko dve obliki, tvoja koda pa mora od prvega dne obravnavati obe. V prvem primeru model odgovori neposredno, ker funkcija ni potrebna: content vsebuje besedilo, tool_calls pa je None.

# response.choices[0].message.content vsebuje besedilni odgovor
# response.choices[0].message.tool_calls je None
print(response.choices[0].message.content)
# → "Hello! How can I help you?"

V drugem primeru model želi poklicati funkcijo. Situacija se obrne: content je prazen ali null, tool_calls pa nosi podatke.

# response.choices[0].message.content je None ali prazen
# response.choices[0].message.tool_calls vsebuje klice
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čen izpis:

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

Razčlenjevanje odziva in ekstrakcija tool_calls

Tukaj je celotna koda za čisto ekstrakcijo informacij iz klica orodja:

message = response.choices[0].message

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

    # Ekstrakcija imena funkcije
    function_name = tool_call.function.name

    # Razčlenjevanje argumentov JSON v slovar Python
    function_params = json.loads(tool_call.function.arguments)

    # Pridobitev edinstvenega identifikatorja klica
    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 je odgovoril neposredno
    print(f"Response: {message.content}")

Iz tega bloka izhajajo trije deli informacij, tretji pa je tisti, na katerega ljudje pozabijo. Ime funkcije se uporablja za usmerjanje, razčlenjeni argumenti za klic, vendar je tool_call_id tisto, kar modelu omogoča, da tvoj rezultat poveže s pravilnim klicem, ko ga pošlješ nazaj. Če ga izgubiš, postane zavoj pogovora neobnovljiv.

Ko model zahteva manjkajoče informacije

Včasih uporabnik ne navede dovolj informacij. Model ima eleganten izhod: funkcije sploh ne pokliče, ampak namesto tega postavi pojasnjevalno vprašanje.

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

To vedenje je točno tisto, kar želiš. Model ve, da je transaction_id naveden v required; namesto da bi izumil verjeten ID in sprožil zahtevo za neobstoječe podatke, prepusti besedo uporabniku. To je tudi najboljša demonstracija uporabnosti polja required, obravnavanega v prejšnji lekciji.

Obravnava sistemskega sporočila

Sistemsko sporočilo ti omogoča, da to vedenje okvirjaš, namesto da bi upal nanj.

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

Preberi ga vrstico za vrstico: prvi stavek določa vlogo, drugi ton in jezik asistenta, tretji določa, kdaj uporabiti funkcije, zadnji pa daje izrecno navodilo za robni primer – manjkajoče informacije. To so trije primeri uporabe, za katere je sistemsko sporočilo priporočljivo, in večinoma zadostujejo.

Celotna koda za koraka 2–3

Tukaj je celotna, ponovno uporabna koda za pošiljanje zahteve z orodji. Zajema vse zgoraj navedeno in normalizira odziv v slovar z dvema oblikama, kar te rešuje razpršenih preverjanj if message.tool_calls po tvoji aplikaciji.

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:
    """Pošlje zahtevo Mistralu z orodji in vrne razčlenjen odziv."""
    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
    }

Upoštevaj, da seznamsko razumevanje iterira čez vse tool_calls, ne le čez prvega. Model lahko ustvari več klicev hkrati; to bo obravnavano v kasnejši lekciji, vendar je tvoja pomožna funkcija že pripravljena za njihovo obravnavo.

Ključne ugotovitve

  • Pošlji tools in messages v client.chat.complete(), da omogočiš klicanje funkcij
  • Vedno preveri, ali message.tool_calls obstaja, preden poskušaš razčleniti
  • tool_call_id je obvezen za pošiljanje rezultata nazaj modelu
  • Argumenti so niz JSON, ki ga je treba razčleniti z json.loads()
  • Model se lahko odloči za neposreden odgovor, če funkcije ne potrebuje ali če informacije manjkajo