Määritä funktiot Pythonissa
Tällä sivulla
Teoriasta koodiin
Ymmärrät nyt viisivaiheisen prosessin ja JSON Schema -rakenteen. On aika kirjoittaa oikeaa Python-koodia. Tässä oppitunnissa luot funktioita, laadit niiden määritykset ja valmistele kaiken Mistral API:a varten – eli kaiken, mitä tarvitaan ennen ensimmäistä verkkopyyntöä.
Asenna Mistral SDK
Aloita asentamalla virallinen paketti:
pip install mistralai
Seuraavaksi määritä API-avaimesi. Paras käytäntö on olla koskaan kovakoodaamatta sitä lähdekooditiedostoihisi. Lue se sen sijaan ympäristömuuttujasta, jotta voit turvallisesti lisätä koodisi versionhallintaan.
export MISTRAL_API_KEY="your-api-key"
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
Luo Python-funktioita
Tarkastellaan toimivaa esimerkkiä: maksujen seurantajärjestelmää, jota tukee Pandas DataFrame. Tämä on klassinen esimerkki Mistralin dokumentaatiosta, ja se havainnollistaa käsitettä täydellisesti – tässä DataFrame toimii samassa roolissa kuin tietokanta tuotantoympäristössä.
import pandas as pd
import json
# Maksutiedot
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)
Seuraavaksi tulee koodi, joka itse asiassa käyttää näitä tietoja. Nämä ovat tavallisia Python-funktioita; niiden toteutuksessa ei ole mitään, mikä vihjaisi, että LLM ohjaa niitä.
def retrieve_payment_status(df: pd.DataFrame, transaction_id: str) -> str:
"""Hakee maksun tilan sen ID:n perusteella."""
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:
"""Hakee maksun päivämäärän sen ID:n perusteella."""
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"})
Kaksi toteutusyksityiskohtaa ansaitsevat huomiosi. Ensinnäkin nämä funktiot palauttavat aina JSON-merkkijonon, eivät koskaan raakaa Python-oliota. Tämä on muoto, jonka malli odottaa työkalun tulokseksi, joten json.dumps() on ehdoton. Toiseksi ne käsittelevät nimenomaisesti tilanteen, jossa transaktiota ei löydy, sen sijaan että heittäisivät poikkeuksen. Tämä virhe, joka on muotoiltu JSONiksi, palautuu mallille aivan kuten mikä tahansa muukin tulos, jolloin se voi kohteliaasti ilmoittaa käyttäjälle, että transaktiota T9999 ei ole olemassa. Näet myöhemmin kurssilla, miksi tämä reflexi on välttämätön.
Kirjoita JSON-määritykset
Jokainen funktio tarvitsee määrityksen, jotta malli voi ymmärtää sen. Tässä sovellat edellisen oppitunnin rakennetta kahteen yllä olevaan funktioon – huomaa tiukka vastaavuus name-kenttien ja todellisten Python-funktioiden nimien välillä.
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"]
}
}
}
]
Järjestä funktiot sanakirjaan
Malli palauttaa funktion nimen merkkijonona. Tarvitset tavan kuvata tämä merkkijono vastaavaan kutsuttavaan objektiin turvautumatta eval-funktioon tai pitkään if-lausekkeiden ketjuun. Dispatch-sanakirja ratkaisee tämän ongelman kolmella rivillä.
from functools import partial
# Sido DataFrame jokaiseen funktioon
available_functions = {
"retrieve_payment_status": partial(retrieve_payment_status, df),
"retrieve_payment_date": partial(retrieve_payment_date, df),
}
functools.partial ratkaisee tietyn, todellisen maailman ongelman. Funktiosi odottavat kahta argumenttia – DataFrame ja ID – mutta malli tarjoaa vain yhden. Malli ei tiedä mitään df:stä, eikä sen pitäisikään. partial esitäyttää tämän ensimmäisen parametrin kerran ja kaikkia varten. Sama mekanismi pätee tietokantayhteyksiin, HTTP-asiakkaisiin tai tunnistautumistokeneihin. Dynaamisesta kutsumisesta tulee tämän ansiosta triviaalia.
function_name = "retrieve_payment_status"
function_params = {"transaction_id": "T1001"}
result = available_functions[function_name](**function_params)
# → '{"status": "paid"}'
tool_choice-vaihtoehto
Kun lähetät nämä työkalut API:lle, tool_choice-parametri päättää, kuinka paljon vapautta annat mallille. Kolme arvoa on mahdollista.
# Malli päättää, käyttääkö työkalua vai vastataanko suoraan (oletus)
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=tools,
tool_choice="auto"
)
# Pakota malli käyttämään työkalua
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=tools,
tool_choice="any"
)
# Estä mallia käyttämästä työkaluja
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=tools,
tool_choice="none"
)
"auto"-tila on yleisin tuotannossa hyvästä syystä: maksujen seuranta-assistentin pitäisi pystyä sanomaan “hei” laukaisematta tietokantakyselyä. Malli vastaa suoraan yleisiin kysymyksiin ja käyttää funktioita vain silloin, kun se on aiheellista. Myöhemmin kurssilla on kokonainen oppitunti, joka käsittelee any- ja none-vaihtoehtojen erityisiä käyttötapauksia.
Keskeiset asiat
- Funktioiden on palautettava JSON-merkkijonoja – ei koskaan raakoja Python-olioita
- Käytä dispatch-sanakirjaa kuvataksesi funktionimet niiden toteutuksiin
functools.partialon ihanteellinen parametrien, kuten tietokantayhteyksien tai DataFramejen, esitäyttööntool_choiceohjaa, voiko tai täytyykö mallin käyttää funktioita (auto,any,none)- Käsittele aina virhetilanteet funktioissasi (virheelliset parametrit, puuttuvat tiedot)