Exemplu practic: Urmăritor de plăți
Pe această pagină
Un proiect complet cap-la-cap
Lecțiile anterioare au izolat fiecare mecanism: definițiile instrumentelor, ciclul de apelare, gestionarea erorilor și securitatea. Acum este momentul să le asamblați. Veți construi un urmăritor de plăți conversațional complet, în care utilizatorii pun întrebări în limbaj natural, iar sistemul interoghează un DataFrame Pandas prin apelarea de funcții. Acest caz de utilizare provine direct din documentația oficială Mistral. Se încadrează în aproximativ o sută de linii, expunând cele cinci blocuri de construcție ale unei aplicații reale: date, funcții de business, specificații JSON, dispecerizare și bucla de conversație.
Datele
Un DataFrame cu cinci tranzacții acoperă scenariile interesante: un client cu multiple plăți, o plată în așteptare și o plată eșuată.
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)
Funcții de business
Patru funcții acoperă nevoile tipice de urmărire a plăților. Primele trei operează asupra unei singure tranzacții și diferă prin granularitate: doar statutul, doar data sau toate detaliile. Această redundanță aparentă este deliberată – permite modelului să solicite doar ceea ce are nevoie, reducând datele inutile din context. A patra funcție schimbă perspectiva și operează la nivel de client.
Rețineți contractul comun: toate returnează un șir JSON, chiar și în caz de eșec, și toate gestionează identificatorii lipsă în loc să permită Pandas să arunce o excepție pe un index gol.
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})
Conversia float(row["payment_amount"]) merită o a doua privire: fără ea, json.dumps eșuează pe tipurile NumPy. Acesta este genul de detaliu pe care îl prinzi doar la runtime.
Specificații JSON
Modelul nu vede niciun cod de mai sus. El cunoaște doar aceste descrieri. Listarea explicită a statusurilor posibile în retrieve_payment_status și reamintirea formatului T1001 în fiecare descriere de parametru îi permite să aleagă funcția corectă și să extragă identificatorul corect.
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"]
}
}
}
]
Dicționarul de dispecerizare
Iată capcana: funcțiile dumneavoastră se așteaptă ca df să fie primul argument, dar modelul nu îl va furniza niciodată – el nu știe că există, și asta este în regulă. functools.partial rezolvă acest lucru elegant prin pre-legarea DataFrame-ului, astfel încât fiecare intrare din dicționar devine apelabilă doar cu argumentele pe care le produce modelul.
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),
}
Bucla de conversație
Mesajul de sistem stabilește rolul, limba și formatarea așteptată pentru sume. Funcția chat orchestrează restul, iar structura sa merită o atenție deosebită: bucla while message.tool_calls gestionează un singur apel, multiple apeluri paralele sau un lanț în care modelul solicită o altă funcție după ce vede primul rezultat. Bucla interioară execută toate apelurile pentru tura curentă; bucla exterioară re-invocă modelul atâta timp cât acesta continuă să solicite instrumente.
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
Ce dezvăluie conversația
Testați acest lucru cu patru ture consecutive. A doua este cea mai instructivă: „această tranzacție“ nu conține niciun identificator, totuși modelul apelează retrieve_payment_details cu T1001. El a rezolvat anafora folosind istoricul păstrat în messages, ceea ce ar fi fost imposibil dacă ați fi resetat lista la fiecare apel. A patra tură arată cealaltă fațetă: nicio funcție nu caută plăți eșuate, dar modelul interoghează clientul relevant și filtrează rezultatul singur.
# 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."
Formatarea sumelor cu punct zecimal și a datelor scrise integral nu provine din nicio linie de cod: aceasta rezultă din promptul de sistem. Aceasta este cea mai utilă lecție din acest capitol – jumătate din calitatea percepută se întâmplă în descrieri și în mesajul de sistem, nu în mecanismele de apelare.
Puncte cheie
- Un urmăritor de plăți complet necesită 4 funcții care acoperă principalele cazuri de utilizare
functools.partialleagă DataFrame-ul de funcții pentru o dispecerizare curată- Bucla
while message.tool_callsgestionează automat apelurile secvențiale și paralele - Mesajul de sistem ghidează modelul privind tonul, limba și formatarea
- Testați cu conversații pe mai multe ture pentru a verifica dacă modelul menține contextul