Funktsioonide defineerimine Pythonis
Sellel lehel
Teooriast koodini
Nüüd, kui mõistad viieastmelist protsessi ja JSON Schema struktuuri, on aeg kirjutada päris Pythoni kood. Selles õppetükis lood funktsioone, koostad nende spetsifikatsioonid ja valmistad kõik ette Mistral API jaoks – ehk kõik, mis peab olemas olema enne esimest võrgukutset.
Paigalda Mistral SDK
Alusta ametliku paketi paigaldamisest:
pip install mistralai
Järgmiseks seadista oma API võti. Parim tava dikteerib, et sa ei kodeeri seda kunagi otse lähtefailidesse. Loegi see keskkonnamuutujast, et saaksid oma koodi turvaliselt versioonihaldusse salvestada.
export MISTRAL_API_KEY="your-api-key"
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
Loo Pythoni funktsioonid
Vaatame läbi töötava näite: maksete jälgimise süsteem, mida toetab Pandas DataFrame. See on klassikaline näide Mistrali dokumentatsioonist ja illustreerib kontseptsiooni ideaalselt – siin mängib DataFrame seda rolli, mida tootmiskeskkonnas täidaks andmebaas.
import pandas as pd
import json
# Makseandmed
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)
Järgmisena tuleb kood, mis tegelikult neile andmetele ligi pääseb. Need on standardsed Pythoni funktsioonid; nende teostuses pole midagi, mis viitaks, et neid juhiks suur keelemudel (LLM).
def retrieve_payment_status(df: pd.DataFrame, transaction_id: str) -> str:
"""Toob välja makse staatuse selle ID järgi."""
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:
"""Toob välja makse kuupäeva selle ID järgi."""
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"})
Kaks teostusdetaili väärivad tähelepanu. Esiteks, need funktsioonid tagastavad alati JSON-stringi, mitte kunagi toorest Pythoni objekti. See on formaat, mida mudel eeldab tööriista tulemusena, seega on json.dumps() kohustuslik. Teiseks käsitlevad need selgelt juhtu, kui tehingut ei leita, selle asemel et visata erind. See veateade, vormistatud JSON-ina, naaseb mudelile nagu iga teine tulemus, võimaldades sellel viisakalt kasutajale teatada, et tehingut T9999 ei eksisteeri. Sa näed hiljem kursuse raames, miks see refleks on hädavajalik.
Kirjuta JSON-spetsifikatsioonid
Iga funktsioon vajab spetsifikatsiooni, et mudel saaks seda mõista. Siin rakendad eelmises õppetükis õpitud struktuuri kahele ülaltoodud funktsioonile – pane tähele ranget vastavust väljade name ja tegelike Pythoni funktsiooninimede vahel.
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"]
}
}
}
]
Korralda funktsioonid sõnastikus
Mudel tagastab funktsiooni nime stringina. Sul on vaja viisi, kuidas see string vastavaks käivitatavaks objektiks kaardistada, kasutamata eval-i või lõputut if-lauseid kaskaadi. Dispatch-sõnastik lahendab selle probleemi kolme reaga.
from functools import partial
# Seosta DataFrame iga funktsiooniga
available_functions = {
"retrieve_payment_status": partial(retrieve_payment_status, df),
"retrieve_payment_date": partial(retrieve_payment_date, df),
}
functools.partial lahendab spetsiifilise, reaalse probleemi. Sinu funktsioonid eeldavad kahte argumenti – DataFrame ja ID – kuid mudel annab ainult ühe. Mudel ei tea midagi df-ist ega peaks teadmagi. partial täidab selle esimese parameetri üks kord ja igaveseks. Sama mehhanism kehtib andmebaasiühenduste, HTTP-klientide või autentimistokenite puhul. Dünaamiline kutsumine muutub seejärel tühiseks.
function_name = "retrieve_payment_status"
function_params = {"transaction_id": "T1001"}
result = available_functions[function_name](**function_params)
# → '{"status": "paid"}'
Valik tool_choice
Nende tööriistade API-le saatmisel määrab parameeter tool_choice, kui palju vabadust mudelile annad. Võimalik on kolm väärtust.
# Mudel otsustab, kas kasutada tööriista või vastata otse (vaikimisi)
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=tools,
tool_choice="auto"
)
# Sunni mudelit kasutama tööriista
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=tools,
tool_choice="any"
)
# Keela mudelil kasutada tööriistu
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=tools,
tool_choice="none"
)
Režiim "auto" on tootmiskeskkonnas kõige levinum ja põhjusega: maksete jälgimise assistent peaks suutma öelda „tere“, käivitamata andmebaasipäringut. Mudel vastab üldistele küsimustele otse ja kasutab funktsioone ainult siis, kui see on asjakohane. Täielik õppetund hiljem kursuses käsitleb any ja none konkreetseid kasutusjuhte.
Peamised punktid
- Funktsioonid peavad tagastama JSON-stringe – mitte kunagi tooreid Pythoni objekte
- Kasuta dispatch-sõnastikku, et kaardistada funktsiooninimed nende teostustele
functools.partialon ideaalne parameetrite, nagu andmebaasiühendused või DataFrame’id, eeltäitmisekstool_choicekontrollib, kas mudel saab või peab kasutama funktsioone (auto,any,none)- Käitle oma funktsioonides alati veajuhte (vigased parameetrid, puuduvad andmed)