Gennemarbejdet eksempel: Betalingssporing
På denne side
Et komplet end-to-end-projekt
Tidligere lektioner har isoleret hver mekanisme: værktøjsdefinitioner, kaldcyklus, fejlhåndtering og sikkerhed. Nu er det tid til at samle det hele. Du skal bygge en komplet konversationsbaseret betalingssporing, hvor brugere stiller spørgsmål på naturligt sprog, og systemet spørger en Pandas DataFrame via funktionskald. Dette usecase trækker direkte på den officielle Mistral-dokumentation. Det passer ind på omkring hundrede linjer, mens det blotlægger de fem byggesten i en rigtig applikation: data, forretningsfunktioner, JSON-specifikationer, dispatch og samtaleløkken.
Dataene
En DataFrame med fem transaktioner dækker de interessante scenarier: en kunde med flere betalinger, en afventende betaling og en mislykket betaling.
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)
Forretningsfunktioner
Fire funktioner dækker typiske behov for betalingssporing. De første tre opererer på en enkelt transaktion og adskiller sig ved granularitet: kun status, kun dato eller alle detaljer. Denne tilsyneladende redundans er bevidst – den lader modellen anmode kun om det, den har brug for, hvilket reducerer unødvendige data i konteksten. Den fjerde skifter perspektiv og opererer pr. kunde.
Bemærk den fælles kontrakt: alle returnerer en JSON-streng, selv ved fejl, og alle håndterer manglende identifikatorer i stedet for at lade Pandas rejse en undtagelse på et tomt indeks.
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})
Konverteringen float(row["payment_amount"]) fortjener et ekstra kig: uden den vil json.dumps fejle på NumPy-typer. Det er den slags detaljer, du først fanger ved runtime.
JSON-specifikationer
Modellen ser ingen af koden ovenfor. Den kender kun disse beskrivelser. Ved eksplicit at liste de mulige statusser i retrieve_payment_status og minde modellen om formatet T1001 i hver parameterbeskrivelse, gør du det muligt for den at vælge den rigtige funktion og udtrække identifikatoren korrekt.
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"]
}
}
}
]
Dispatch-ordbogen
Her er hagen: dine funktioner forventer df som første argument, men modellen vil aldrig levere det – den ved ikke, det eksisterer, og det er fint. functools.partial løser dette elegant ved at præ-binde DataFrame’en, så hvert element i ordbogen bliver kaldbar med kun de argumenter, modellen producerer.
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),
}
Samtaleløkken
Systembeskeden fastsætter rollen, sproget og det forventede format for beløb. Funktionen chat orchestrerer resten, og dens struktur fortjener tæt opmærksomhed: løkken while message.tool_calls håndterer et enkelt kald, flere parallelle kald eller en kæde, hvor modellen anmoder om en anden funktion efter at have set det første resultat. Den indre løkke udfører alle kald for den aktuelle tur; den ydre løkke geninvokerer modellen, så længe den fortsætter med at anmode om værktøjer.
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
Hvad samtalen afslører
Test dette med fire på hinanden følgende ture. Den anden er mest instruktiv: „denne transaktion” indeholder ingen identifikator, alligevel kalder modellen retrieve_payment_details med T1001. Den løste anaforen ved hjælp af historikken bevaret i messages, hvilket ville være umuligt, hvis du nulstillede listen ved hvert kald. Den fjerde tur viser den anden side: ingen funktion søger efter mislykkede betalinger, men modellen spørger den relevante kunde og filtrerer resultatet selv.
# 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."
Formatering af beløb med decimalpunktum og datoer skrevet fuldt ud kommer fra ingen kodelinje: det følger af systemprompten. Dette er det mest nyttige takeaway fra dette kapitel – halvdelen af den oplevede kvalitet sker i beskrivelserne og systembeskeden, ikke i kaldmekanikken.
Vigtige pointer
- En komplet betalingssporing kræver 4 funktioner, der dækker hovedusecases
functools.partialbinder DataFrame’en til funktionerne for ren dispatch- Løkken
while message.tool_callshåndterer automatisk sekventielle og parallelle kald - Systembeskeden guider modellen omkring tone, sprog og formatering
- Test med flerstrengete samtaler for at verificere, at modellen bevarer konteksten