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

Definovanie funkcií v Pythone

Lekcia 4 z 14 Aktualizované 2. novembra 2026 Vývojár
Na tejto strane
  1. Od teórie ku kódu
  2. Inštalácia Mistral SDK
  3. Vytváranie funkcií v Pythone
  4. Písanie špecifikácií JSON
  5. Organizácia funkcií v slovníku
  6. Možnosť tool_choice
  7. Kľúčové poznatky

Od teórie ku kódu

Teraz už poznáš päťkrokový proces a štruktúru JSON Schema. Je čas napísať skutočný kód v Pythone. V tejto lekcii vytvoríš funkcie, navrhneš ich špecifikácie a pripravíš všetko potrebné pre API Mistral – teda všetko, čo musí existovať pred prvým sieťovým volaním.

Inštalácia Mistral SDK

Začni inštaláciou oficiálneho balíka:

pip install mistralai

Ďalej nakonfiguruj svoj API kľúč. Najlepšia prax diktuje, aby si ho nikdy neukladal priamo do zdrojových súborov. Namiesto toho si ho načítaj z premennej prostredia, aby si mohol svoj kód bezpečne commitovať do systému riadenia verzií.

export MISTRAL_API_KEY="your-api-key"
import os
from mistralai.client import Mistral

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

Vytváranie funkcií v Pythone

Pozrime sa na konkrétny príklad: systém sledovania platieb založený na dátovom rámci Pandas DataFrame. Ide o klasický príklad z dokumentácie Mistral, ktorý dokonale ilustruje túto koncepciu – v tomto prípade hrá DataFrame úlohu, ktorú by v produkčnom prostredí zastupovala databáza.

import pandas as pd
import json

# Údaje o platbách
data = {
    "transaction_id": ["T1001", "T1002", "T1003", "T1004", "T1005"],
    "customer_id": ["C001", "C002", "C003", "C002", "C001"],
    "payment_amount": [125.50, 89.99, 350.00, 45.00, 210.75],
    "payment_date": ["2026-03-15", "2026-03-16", "2026-03-17", "2026-03-17", "2026-03-18"],
    "payment_status": ["paid", "paid", "pending", "paid", "failed"]
}
df = pd.DataFrame(data)

Nasleduje kód, ktorý tieto údaje skutočne sprístupňuje. Ide o štandardné funkcie v Pythone; nič v ich implementácii nenaznačuje, že ich bude riadiť LLM.

def retrieve_payment_status(df: pd.DataFrame, transaction_id: str) -> str:
    """Získa stav platby podľa jej ID."""
    if transaction_id in df["transaction_id"].values:
        status = df[df["transaction_id"] == transaction_id]["payment_status"].values[0]
        return json.dumps({"status": status})
    return json.dumps({"error": f"Transaction {transaction_id} not found"})


def retrieve_payment_date(df: pd.DataFrame, transaction_id: str) -> str:
    """Získa dátum platby podľa jej ID."""
    if transaction_id in df["transaction_id"].values:
        date = df[df["transaction_id"] == transaction_id]["payment_date"].values[0]
        return json.dumps({"date": date})
    return json.dumps({"error": f"Transaction {transaction_id} not found"})

Dva detaily implementácie si zaslúžia tvoju pozornosť. Po prvé, tieto funkcie vždy vracajú reťazec JSON, nikdy nie surový Python objekt. Toto je formát, ktorý model očakáva ako výsledok nástroja, takže json.dumps() je nevyhnutnosť. Po druhé, explicitne ošetrujú prípad, keď sa transakcia nenájde, namiesto vyvolania výnimky. Táto chyba, naformátovaná ako JSON, sa vráti modelu rovnako ako akýkoľvek iný výsledok, čo mu umožní zdvorilo informovať používateľa, že transakcia T9999 neexistuje. Neskôr v kurze uvidíš, prečo je tento reflex nevyhnutný.

Písanie špecifikácií JSON

Každá funkcia potrebuje špecifikáciu, aby ju model mohol pochopiť. Tu aplikuješ štruktúru z predchádzajúcej lekcie na dve vyššie uvedené funkcie – všimni si prísnu zhodu medzi poľami name a skutočnými názvami funkcií v Pythone.

tools = [
    {
        "type": "function",
        "function": {
            "name": "retrieve_payment_status",
            "description": "Retrieves the status of a payment (paid, pending, failed) "
                           "based on the transaction ID.",
            "parameters": {
                "type": "object",
                "properties": {
                    "transaction_id": {
                        "type": "string",
                        "description": "Unique transaction identifier (e.g., T1001)"
                    }
                },
                "required": ["transaction_id"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "retrieve_payment_date",
            "description": "Retrieves the date a payment was made "
                           "based on the transaction ID.",
            "parameters": {
                "type": "object",
                "properties": {
                    "transaction_id": {
                        "type": "string",
                        "description": "Unique transaction identifier (e.g., T1001)"
                    }
                },
                "required": ["transaction_id"]
            }
        }
    }
]

Organizácia funkcií v slovníku

Model vráti názov funkcie ako reťazec. Potrebuješ spôsob, ako tento reťazec namapovať na zodpovedajúci volateľný objekt bez použitia eval alebo kaskády príkazov if. Slovník na smerovanie (dispatch dictionary) vyrieši tento problém na tri riadky.

from functools import partial

# Viažeme DataFrame na každú funkciu
available_functions = {
    "retrieve_payment_status": partial(retrieve_payment_status, df),
    "retrieve_payment_date": partial(retrieve_payment_date, df),
}

functools.partial rieši špecifický, reálny problém. Tvoje funkcie očakávajú dva argumenty – DataFrame a ID –, ale model poskytuje iba jeden. Model nič nevie o df, ani by nemal vedieť. partial vopred vyplní tento prvý parameter raz a navždy. Tento istý mechanizmus platí pre pripojenia k databáze, HTTP klientov alebo autentikačné tokeny. Dynamické volanie sa potom stáva triviálnym.

function_name = "retrieve_payment_status"
function_params = {"transaction_id": "T1001"}

result = available_functions[function_name](**function_params)
# → '{"status": "paid"}'

Možnosť tool_choice

Pri odosielaní týchto nástrojov do API parameter tool_choice rozhoduje o tom, akú veľkú voľnosť dáš modelu. Možné sú tri hodnoty.

# Model sa sám rozhodne, či použije nástroj, alebo odpovie priamo (predvolené)
response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="auto"
)

# Prinúti model použiť nástroj
response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="any"
)

# Zabráni modelu používať nástroje
response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="none"
)

Režim "auto" je v produkčnom prostredí najbežnejší z dobrého dôvodu: asistent na sledovanie platieb by mal byť schopný povedať „ahoj“ bez spustenia dotazu do databázy. Model odpovedá priamo na všeobecné otázky a funkcie používa len vtedy, keď je to relevantné. Celá lekcia neskôr v kurze pokrýva špecifické prípady použitia pre any a none.

Kľúčové poznatky

  • Funkcie musia vracať reťazce JSON – nikdy nie surové Python objekty
  • Na mapovanie názvov funkcií na ich implementácie používaj slovník na smerovanie
  • functools.partial je ideálny na vopred vyplnenie parametrov, ako sú pripojenia k DB alebo DataFrames
  • tool_choice riadi, či model môže alebo musí používať funkcie (auto, any, none)
  • Vždy ošetruj prípady chýb vo svojich funkciách (neplatné parametre, chýbajúce údaje)