Apibrėžti funkcijas Python kalba
Šiame puslapyje
Nuo teorijos prie kodo
Dabar jau supranti penkių žingsnių procesą ir JSON schemos struktūrą. Metas rašyti tikrą Python kodą. Šioje pamokoje sukursi funkcijas, parengsi jų specifikacijas ir paruoši viską Mistral API – tai viskas, kas turi egzistuoti prieš atliekant pirmąjį tinklo užklausimą.
Įdiekite Mistral SDK
Pradėk nuo oficialaus paketo įdiegimo:
pip install mistralai
Toliau sukonfigūruok savo API raktą. Geriausia praktika diktuoja, kad jo niekada nereikėtų įrašyti tiesiai į源代码 failus. Užuot tai daręs, nuskaityk jį iš aplinkos kintamojo, kad galėtum saugiai įkelti savo kodą į versijų valdymo sistemą.
export MISTRAL_API_KEY="your-api-key"
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
Sukurkite Python funkcijas
Pažvelkime į pavyzdį: mokėjimų stebėjimo sistema, paremta Pandas DataFrame. Tai klasikinis pavyzdys iš Mistral dokumentacijos, puikiai iliustruojantis koncepciją – čia DataFrame atlieka tą vaidmenį, kurį gamybinėje aplinkoje atliktų duomenų bazė.
import pandas as pd
import json
# Mokėjimų duomenys
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)
Toliau eina kodas, kuris iš tikrųjų pasiekia šiuos duomenis. Tai standartinės Python funkcijos; jų įgyvendinime nėra nieko, kas rodytų, kad jas valdys didžioji kalbos modelis (LLM).
def retrieve_payment_status(df: pd.DataFrame, transaction_id: str) -> str:
"""Gauna mokėjimo būseną pagal jo 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:
"""Gauna mokėjimo datą pagal jo 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"})
Du įgyvendinimo aspektai nusipelno tavo dėmesio. Pirma, šios funkcijos visada grąžina JSON eilutę, o ne „žalią“ Python objektą. Tai formatas, kurio modelis tikisi kaip įrankio atsakymo, todėl json.dumps() yra privalomas. Antra, jos aiškiai apdoroja atvejį, kai sandoris nerastas, užuot išmetusios išimtį (exception). Ši klaida, suformatuota kaip JSON, grąžinama modeliui taip pat kaip ir bet kuris kitas rezultatas, leisdamas jam mandagiai informuoti vartotoją, kad sandoris T9999 neegzistuoja. Vėliau kurse pamatysi, kodėl šis refleksas yra būtinas.
Parašykite JSON specifikacijas
Kiekviena funkcija turi turėti specifikaciją, kad modelis galėtų ją suprasti. Čia taikai ankstesnėje pamokoje nagrinėtą struktūrą dviem aukščiau pateiktoms funkcijoms – atkreipk dėmesį į griežtą atitikimą tarp laukų name ir tikrųjų Python funkcijų pavadinimų.
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"]
}
}
}
]
Sutvarkykite funkcijas žodyne
Modelis grąžina funkcijos pavadinimą kaip eilutę. Tau reikia būdo susieti tą eilutę su atitinkamu vykdomuoju objektu nenaudojant eval arba begalinės if sakinių grandinės. Išsiuntimo (dispatch) žodynas išsprendžia šią problemą trimis eilutėmis.
from functools import partial
# Priskiriame DataFrame kiekvienai funkcijai
available_functions = {
"retrieve_payment_status": partial(retrieve_payment_status, df),
"retrieve_payment_date": partial(retrieve_payment_date, df),
}
functools.partial sprendžia specifinį, realaus pasaulio sunkumą. Tavo funkcijos tikisi dviejų argumentų – DataFrame ir ID, – tačiau modelis pateikia tik vieną. Modelis nieko nežino apie df, ir taip turi būti. partial vieną kartą visiems laikams užpildo tą pirmąjį parametrą. Tas pats mechanizmas taikomas duomenų bazių ryšiams, HTTP klientams arba autentifikavimo tokenams. Dinaminis iškvietimas tada tampa trivialiu uždaviniu.
function_name = "retrieve_payment_status"
function_params = {"transaction_id": "T1001"}
result = available_functions[function_name](**function_params)
# → '{"status": "paid"}'
Parametras tool_choice
Siunčiant šiuos įrankius API, parametras tool_choice nusprendžia, kiek laisvės suteiki modeliui. Galimos trys reikšmės.
# Modelis pats sprendžia, ar naudoti įrankį, ar atsakyti tiesiogiai (numatytoji reikšmė)
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=tools,
tool_choice="auto"
)
# Priversti modelį naudoti įrankį
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=tools,
tool_choice="any"
)
# Užkirsti kelią modeliui naudoti įrankius
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=tools,
tool_choice="none"
)
Režimas "auto" gamybinėje aplinkoje yra dažniausias dėl geros priežasties: mokėjimų stebėjimo asistentas turėtų gebėti pasakyti „labas“ neiškviesdamas duomenų bazės užklausos. Modelis tiesiogiai atsako į bendrus klausimus ir naudoja funkcijas tik tada, kai tai aktualu. Vėlesnėje kurso dalyje skirta visa pamoka konkrečioms any ir none naudojimo situacijams aptarti.
Svarbiausi punktai
- Funkcijos turi grąžinti JSON eilutes – niekada ne „žalius“ Python objektus
- Naudok išsiuntimo žodyną, kad susietum funkcijų pavadinimus su jų įgyvendinimais
functools.partialidealiai tinka iš anksto užpildyti tokius parametrus kaip DB ryšiai ar DataFrametool_choicevaldo, ar modelis gali, ar privalo naudoti funkcijas (auto,any,none)- Visada apdorok klaidų atvejus savo funkcijose (neteisingi parametrai, trūkstami duomenys)