Függvények definiálása Pythonban
Ezen az oldalon
Elmélettől a kódig
Most már ismered az öt lépésből álló folyamatot és a JSON Schema szerkezetét. Ideje valódi Python kódot írni. Ebben a leckében függvényeket hozol létre, megtervezed a specifikációikat, és előkészítesz mindent a Mistral API számára – minden olyan elemet, amelynek léteznie kell az első hálózati hívás előtt.
A Mistral SDK telepítése
Kezdd a hivatalos csomag telepítésével:
pip install mistralai
Ezután állítsd be az API-kulcsodat. A legjobb gyakorlat azt diktálja, hogy soha ne építsd be közvetlenül (hardcode) a forráskódba. Ehelyett olvasd be egy környezeti változóból, így biztonságosan commitolhatod a kódodat a verziókezelőbe.
export MISTRAL_API_KEY="your-api-key"
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
Python függvények létrehozása
Nézzünk egy kidolgozott példát: egy Pandas DataFrame-re épülő fizetésnyilvántartó rendszert. Ez egy klasszikus példa a Mistral dokumentációjából, amely tökéletesen szemlélteti a koncepciót – itt a DataFrame azt a szerepet tölti be, amelyet éles környezetben egy adatbázis játszana.
import pandas as pd
import json
# Fizetési adatok
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)
Ezután jön a kód, amely ténylegesen hozzáfér ezekhez az adatokhoz. Ezek szabványos Python függvények; a megvalósításukban semmi utalás nincs arra, hogy egy LLM fogja vezérelni őket.
def retrieve_payment_status(df: pd.DataFrame, transaction_id: str) -> str:
"""Lekéri egy fizetés státuszát az azonosítója alapján."""
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:
"""Lekéri egy fizetés dátumát az azonosítója alapján."""
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"})
Két megvalósítási részletre érdemes figyelned. Először is, ezek a függvények mindig JSON sztringet adnak vissza, soha nem nyers Python objektumot. Ez az a formátum, amelyet a modell eszközeredményként vár, így a json.dumps() használata elengedhetetlen. Másodszor, explicit módon kezelik azt az esetet, amikor egy tranzakció nem található, ahelyett, hogy kivételt dobnának. Ez a JSON-ként formázott hiba ugyanúgy visszakerül a modellhez, mint bármely más eredmény, lehetővé téve számára, hogy udvariasan tájékoztassa a felhasználót arról, hogy a T9999-es tranzakció nem létezik. A kurzus későbbi részében látni fogod, miért létfontosságú ez a reflex.
JSON specifikációk írása
Minden függvényhez szükség van egy specifikációra, hogy a modell megérthesse azt. Itt alkalmazod az előző leckéből származó szerkezetet a fenti két függvényre – figyeld meg a szigorú megfelelést a name mezők és a tényleges Python függvénynevek között.
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"]
}
}
}
]
Függvények szervezése szótárba
A modell függvénynevet ad vissza sztringként. Szükséged van egy módszerre, hogy ezt a sztringet leképezd a megfelelő hívható objektumra anélkül, hogy az eval használatához vagy if utasítások hosszú láncolatához folyamodnál. Egy dispatch szótár három sorban megoldja ezt a problémát.
from functools import partial
# A DataFrame hozzárendelése minden függvényhez
available_functions = {
"retrieve_payment_status": partial(retrieve_payment_status, df),
"retrieve_payment_date": partial(retrieve_payment_date, df),
}
A functools.partial egy specifikus, valós nehézségre nyújt megoldást. A függvényeid két argumentumot várnak – a DataFrame-et és az azonosítót –, de a modell csak egyet szolgáltat. A modell nem tud a df-ről, és nem is kellene tudnia. A partial egyszer és mindenkorra előre kitölti ezt az első paramétert. Ugyanez a mechanizmus alkalmazható adatbázis-kapcsolatokra, HTTP kliensekre vagy hitelesítési tokenekre is. A dinamikus hívás ezután triviálissá válik.
function_name = "retrieve_payment_status"
function_params = {"transaction_id": "T1001"}
result = available_functions[function_name](**function_params)
# → '{"status": "paid"}'
A tool_choice opció
Amikor ezeket az eszközöket elküldöd az API-nak, a tool_choice paraméter dönti el, mennyi szabadságot adsz a modellnek. Három érték lehetséges.
# A modell dönti el, hogy használjon-e eszközt, vagy közvetlenül válaszoljon (alapértelmezett)
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=tools,
tool_choice="auto"
)
# A modell kényszerítése eszköz használatára
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=tools,
tool_choice="any"
)
# Az eszközhasználat megtiltása a modell számára
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=tools,
tool_choice="none"
)
Az "auto" mód a leggyakoribb éles környezetben, jó okkal: egy fizetésnyilvántartó asszisztensnek képesnek kell lennie „szia“-t mondani anélkül, hogy adatbázis-lekérdezést indítana. A modell közvetlenül válaszol az általános kérdésekre, és csak akkor használ függvényeket, ha azok relevánsak. A kurzus későbbi része egy teljes leckét szentel az any és a none konkrét használati eseteinek.
Főbb megállapítások
- A függvényeknek mindig JSON sztringet kell visszaadniuk – soha nem nyers Python objektumot
- Használj dispatch szótárat a függvénynevek és megvalósításaik közötti leképezéshez
- A
functools.partialideális paraméterek (pl. adatbázis-kapcsolatok vagy DataFrame-ek) előre kitöltésére - A
tool_choiceszabályozza, hogy a modell használhat-e vagy kell-e függvényeket használnia (auto,any,none) - Mindig kezeld a hibaeseteket a függvényeidben (érvénytelen paraméterek, hiányzó adatok)