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

Definiranje funkcij v Pythonu

Lekcija 4 od 14 Posodobljeno 2. november 2026 Razvijalec
Na tej strani
  1. Od teorije do kode
  2. Namestitev SDK-ja Mistral
  3. Ustvarjanje funkcij v Pythonu
  4. Pisanje specifikacij JSON
  5. Organizacija funkcij v slovarju
  6. Možnost tool_choice
  7. Ključne ugotovitve

Od teorije do kode

Zdaj razumeš petstopenjski proces in strukturo sheme JSON. Čas je, da napišeš pravo kodo v Pythonu. V tej lekciji boš ustvaril funkcije, pripravil njihove specifikacije in vse uredil za API Mistral – vse, kar mora obstajati, preden opraviš prvi omrežni klic.

Namestitev SDK-ja Mistral

Začni z namestitvijo uradnega paketa:

pip install mistralai

Nato konfiguriraj svoj ključ API. Najboljša praksa narekuje, da ga nikoli ne vgradiš neposredno v izvorne datoteke. Namesto tega ga preberi iz spremenljivke okolja, tako da lahko svojo kodo varno potisneš v nadzor različic.

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

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

Ustvarjanje funkcij v Pythonu

Oglejmo si delujoč primer: sistem za sledenje plačilom, ki temelji na podatkovnem okvirju Pandas. To je klasičen primer iz dokumentacije Mistral in popolnoma ponazarja koncept – tukaj podatkovni okvir igra vlogo, ki bi jo v proizvodnem okolju imela baza podatkov.

import pandas as pd
import json

# Podatki o plačilih
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)

Sledi koda, ki dejansko dostopa do teh podatkov. To so standardne funkcije Python; nič v njihovi implementaciji ne nakazuje, da jih bo poganjal LLM.

def retrieve_payment_status(df: pd.DataFrame, transaction_id: str) -> str:
    """Pridobi status plačila glede na njegov 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:
    """Pridobi datum plačila glede na njegov 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"})

Dve podrobnosti pri implementaciji zaslužita tvojo pozornost. Prvič, te funkcije vedno vrnejo niz JSON, nikoli surovega objekta Python. To je format, ki ga model pričakuje kot rezultat orodja, zato je json.dumps() nujen. Drugič, izrecno obravnavajo primer, ko transakcije ni mogoče najti, namesto da bi sprožile izjemo. Ta napaka, oblikovana kot JSON, se vrne modelu tako kot vsak drug rezultat, kar mu omogoča, da uporabnika vljudno obvesti, da transakcija T9999 ne obstaja. Kasneje v tečaju boš videl, zakaj je ta refleks bistven.

Pisanje specifikacij JSON

Vsaka funkcija potrebuje specifikacijo, da jo model lahko razume. Tukaj uporabiš strukturo iz prejšnje lekcije za zgornji dve funkciji – upoštevaj strogo ujemanje med polji name in dejanskimi imeni funkcij v Pythonu.

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

Organizacija funkcij v slovarju

Model vrne ime funkcije kot niz. Potrebuješ način, da ta niz preslikaš v ustrezen klicljiv objekt, ne da bi se zatekel k eval ali veriži stavkov if. Slovar za razpošiljanje (dispatch dictionary) ta problem reši v treh vrsticah.

from functools import partial

# Poveži podatkovni okvir s vsako funkcijo
available_functions = {
    "retrieve_payment_status": partial(retrieve_payment_status, df),
    "retrieve_payment_date": partial(retrieve_payment_date, df),
}

functools.partial naslavlja specifično, realno težavo. Tvoje funkcije pričakujejo dva argumenta – podatkovni okvir in ID –, model pa zagotovi le enega. Model ne ve ničesar o df, niti ne bi smel. partial enkrat za vselej predizpolni ta prvi parameter. Ta isti mehanizem velja za povezave z bazami podatkov, odjemalce HTTP ali žetone za avtentikacijo. Dinamično klicanje nato postane trivialno.

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

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

Možnost tool_choice

Ko ta orodja pošlješ API-ju, parameter tool_choice določa, koliko svobode daš modelu. Možne so tri vrednosti.

# Model se sam odloči, ali bo uporabil orodje ali odgovoril neposredno (privzeto)
response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="auto"
)

# Prisili model, da uporabi orodje
response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="any"
)

# Prepreči modelu uporabo orodij
response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="none"
)

Način "auto" je v proizvodnem okolju najpogostejši z dobrim razlogom: asistent za sledenje plačilom mora biti zmožen reči „živo”, ne da bi sprožil poizvedbo v bazi podatkov. Model neposredno odgovori na splošna vprašanja in uporabi funkcije le, ko so relevantne. Celotna lekcija kasneje v tečaju pokriva specifične primere uporabe za any in none.

Ključne ugotovitve

  • Funkcije morajo vrniti nize JSON – nikoli surovih objektov Python
  • Uporabi slovar za razpošiljanje za preslikavo imen funkcij na njihove implementacije
  • functools.partial je idealen za predizpolnjevanje parametrov, kot so povezave z bazami podatkov ali podatkovni okviri
  • tool_choice nadzira, ali model lahko ali mora uporabiti funkcije (auto, any, none)
  • V svojih funkcijah vedno obravnavaj primere napak (neveljavni parametri, manjkajoči podatki)