Primer uporabe: Sledilnik plačil
Na tej strani
Celoten projekt od začetka do konca
Prejšnje lekcije so obravnavale vsak mehanizem posebej: definicije orodij, cikel klicev, obravnavo napak in varnost. Zdaj je čas, da jih združiš. Zgradil boš celovit pogovorni sledilnik plačil, kjer uporabniki postavljajo vprašanja v naravnem jeziku, sistem pa poizveduje po podatkovnem okvirju Pandas s pomočjo klicanja funkcij. Ta primer uporabe neposredno izhaja iz uradne dokumentacije Mistral. Prilega se v približno sto vrstic kode, hkrati pa razkriva pet gradnikov realne aplikacije: podatke, poslovne funkcije, specifikacije JSON, usmerjanje in pogovorno zanko.
Podatki
Podatkovni okvir s petimi transakcijami pokriva zanimive scenarije: stranko z več plačili, čakajoče plačilo in neuspelo plačilo.
import pandas as pd
import json
import os
from mistralai.client import Mistral
from functools import partial
# Transactions DataFrame
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)
Poslovne funkcije
Štiri funkcije pokrivajo tipične potrebe pri sledenju plačil. Prve tri delujejo na eni sami transakciji in se razlikujejo po granuliranosti: samo stanje, samo datum ali vsi podrobnosti. Ta navidezna redundanca je namerna – modelu omogoča, da zahteva le tisto, kar potrebuje, s čimer zmanjša količino nepotrebnih podatkov v kontekstu. Četrta funkcija spremeni perspektivo in deluje po strankah.
Opazi skupno pogodbo: vse vrnejo niz JSON, tudi ob napaki, in vse obravnavajo manjkajoče identifikatorje, namesto da bi pustile, da Pandas sproži izjemo zaradi praznega indeksa.
def retrieve_payment_status(df: pd.DataFrame, transaction_id: str) -> str:
"""Retrieves the status of a payment."""
if transaction_id in df["transaction_id"].values:
row = df[df["transaction_id"] == transaction_id].iloc[0]
return json.dumps({
"transaction_id": transaction_id,
"status": row["payment_status"]
})
return json.dumps({"error": f"Transaction {transaction_id} not found"})
def retrieve_payment_date(df: pd.DataFrame, transaction_id: str) -> str:
"""Retrieves the date of a payment."""
if transaction_id in df["transaction_id"].values:
row = df[df["transaction_id"] == transaction_id].iloc[0]
return json.dumps({
"transaction_id": transaction_id,
"date": row["payment_date"]
})
return json.dumps({"error": f"Transaction {transaction_id} not found"})
def retrieve_payment_details(df: pd.DataFrame, transaction_id: str) -> str:
"""Retrieves all details of a payment."""
if transaction_id in df["transaction_id"].values:
row = df[df["transaction_id"] == transaction_id].iloc[0]
return json.dumps({
"transaction_id": transaction_id,
"customer_id": row["customer_id"],
"amount": float(row["payment_amount"]),
"date": row["payment_date"],
"status": row["payment_status"]
})
return json.dumps({"error": f"Transaction {transaction_id} not found"})
def list_customer_transactions(df: pd.DataFrame, customer_id: str) -> str:
"""Lists all transactions for a given customer."""
customer_df = df[df["customer_id"] == customer_id]
if customer_df.empty:
return json.dumps({"error": f"Customer {customer_id} not found"})
transactions = []
for _, row in customer_df.iterrows():
transactions.append({
"transaction_id": row["transaction_id"],
"amount": float(row["payment_amount"]),
"date": row["payment_date"],
"status": row["payment_status"]
})
return json.dumps({"customer_id": customer_id, "transactions": transactions})
Pretvorba float(row["payment_amount"]) si zasluži drug pogled: brez nje json.dumps odpove pri tipih NumPy. To je tista vrsta podrobnosti, ki jo ujameš šele med izvajanjem.
Specifikacije JSON
Model ne vidi nobene od zgornjih kod. Pozna le te opise. Izrecno naštevanje možnih stanj v retrieve_payment_status in opominjanje modela na format T1001 v vsakem opisu parametra mu omogoča, da izbere pravo funkcijo in pravilno izvleče identifikator.
tools = [
{
"type": "function",
"function": {
"name": "retrieve_payment_status",
"description": "Retrieves the status of a payment (paid, pending, failed)",
"parameters": {
"type": "object",
"properties": {
"transaction_id": {
"type": "string",
"description": "Transaction identifier (e.g., T1001)"
}
},
"required": ["transaction_id"]
}
}
},
{
"type": "function",
"function": {
"name": "retrieve_payment_date",
"description": "Retrieves the date of a payment",
"parameters": {
"type": "object",
"properties": {
"transaction_id": {
"type": "string",
"description": "Transaction identifier (e.g., T1001)"
}
},
"required": ["transaction_id"]
}
}
},
{
"type": "function",
"function": {
"name": "retrieve_payment_details",
"description": "Retrieves all details of a payment: amount, date, status, customer",
"parameters": {
"type": "object",
"properties": {
"transaction_id": {
"type": "string",
"description": "Transaction identifier (e.g., T1001)"
}
},
"required": ["transaction_id"]
}
}
},
{
"type": "function",
"function": {
"name": "list_customer_transactions",
"description": "Lists all transactions for a given customer",
"parameters": {
"type": "object",
"properties": {
"customer_id": {
"type": "string",
"description": "Customer identifier (e.g., C001)"
}
},
"required": ["customer_id"]
}
}
}
]
Slovar za usmerjanje
Tukaj je catch: tvoje funkcije pričakujejo df kot prvi argument, model pa ga nikoli ne bo zagotovil – ne ve, da obstaja, in to je v redu. functools.partial to elegantno reši s predvezavo podatkovnega okvira, tako da vsak vnos v slovarju postane klicljiv le z argumenti, ki jih proizvede model.
available_functions = {
"retrieve_payment_status": partial(retrieve_payment_status, df),
"retrieve_payment_date": partial(retrieve_payment_date, df),
"retrieve_payment_details": partial(retrieve_payment_details, df),
"list_customer_transactions": partial(list_customer_transactions, df),
}
Pogovorna zanka
Sistemsko sporočilo določa vlogo, jezik in pričakovano oblikovanje zneskov. Funkcija chat usklajuje preostanek in njena struktura si zasluži posebno pozornost: zanka while message.tool_calls obravnava en klic, več vzporednih klicev ali verigo, kjer model zahteva drugo funkcijo po ogledu prvega rezultata. Notranja zanka izvrši vse klice za trenutni obrat; zunanja zanka ponovno prikliče model, dokler ta še naprej zahteva orodja.
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
model = "mistral-large-latest"
messages = [
{
"role": "system",
"content": "You are a payment tracking assistant. "
"Respond in English. Use the available tools "
"to answer questions about transactions. "
"Format amounts in euros with 2 decimal places."
}
]
def chat(user_input: str) -> str:
"""Complete conversation turn with tool_calls handling."""
messages.append({"role": "user", "content": user_input})
response = client.chat.complete(
model=model, messages=messages, tools=tools
)
message = response.choices[0].message
# Loop while the model wants to call functions
while message.tool_calls:
messages.append(message)
for tool_call in message.tool_calls:
fn_name = tool_call.function.name
fn_params = json.loads(tool_call.function.arguments)
if fn_name in available_functions:
result = available_functions[fn_name](**fn_params)
else:
result = json.dumps({"error": f"Unknown function {fn_name}"})
messages.append({
"role": "tool",
"name": fn_name,
"content": result,
"tool_call_id": tool_call.id
})
response = client.chat.complete(
model=model, messages=messages, tools=tools
)
message = response.choices[0].message
messages.append(message)
return message.content
Kaj razkriva pogovor
Preizkusi to s štirimi zaporednimi obrati. Drugi je najbolj poučen: „ta transakcija” ne vsebuje identifikatorja, vendar model pokliče retrieve_payment_details s T1001. Razrešil je anaforo z uporabo zgodovine, ohranjene v messages, kar bi bilo nemogoče, če bi seznam ob vsakem klicu ponastavil. Četrti obrat kaže drugo plat: nobena funkcija ne išče neuspelih plačil, vendar model poizveduje po ustrezni stranki in sam filtrira rezultat.
# Turn 1
print(chat("What is the status of payment T1001?"))
# -> "Payment T1001 has status: paid."
# Turn 2
print(chat("Give me all the details for this transaction."))
# -> "Here are the details for payment T1001:
# - Customer: C001
# - Amount: 125.50 euros
# - Date: March 15, 2026
# - Status: paid"
# Turn 3
print(chat("What are all the transactions for customer C002?"))
# -> "Customer C002 has 2 transactions:
# - T1002: 89.99 euros (paid, March 16, 2026)
# - T1004: 45.00 euros (paid, March 17, 2026)"
# Turn 4
print(chat("Are there any failed payments?"))
# -> "Yes, payment T1005 for customer C001 (210.75 euros) failed."
Oblikovanje zneskov z decimalno piko in datumov, zapisanih v celoti, ne izhaja iz nobene vrstice kode: sledi sistemskemu pozivu. To je najbolj uporabna ugotovitev tega poglavja – polovica zaznane kakovosti se zgodi v opisih in sistemskem sporočilu, ne v mehaniki klicanja.
Ključne ugotovitve
- Celovit sledilnik plačil zahteva 4 funkcije, ki pokrivajo glavne primere uporabe
functools.partialveže podatkovni okvir na funkcije za čisto usmerjanje- Zanka
while message.tool_callssamodejno obravnava zaporedne in vzporedne klice - Sistemsko sporočilo vodi model glede tona, jezika in oblikovanja
- Preizkusi z večobratnimi pogovori, da preveriš, ali model ohranja kontekst