Näidisprojekt: Maksete jälgija
Sellel lehel
Terviklik lõpuni viidud projekt
Eelmistes õppetundides käsitlesime iga mehhanismi eraldi: tööriistade määratlusi, väljakutse tsüklit, veahaldust ja turvalisust. Nüüd on aeg need kokku panna. Sa ehitad tervikliku vestluspõhise maksete jälgija, kus kasutajad esitavad küsimusi loomulikus keeles ja süsteem päringutab Pandas DataFrame’i funktsioonide kutsumise kaudu. See kasutusjuhtum põhineb otseselt Mistrali ametlikul dokumentatsioonil. See mahub umbes sajale reale, tuues samal ajal esile reaalse rakenduse viis ehitusplokki: andmed, ärifunktsioonid, JSON-spetsifikatsioonid, edastamine ja vestluse tsükkel.
Andmed
Viie tehinguga DataFrame katab huvitavad stsenaariumid: klient mitme maksega, ootel olev makse ja ebaõnnestunud makse.
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)
Ärifunktsioonid
Neli funktsiooni katavad tüüpilised maksete jälgimise vajadused. Esimesed kolm töötavad ühe tehinguga ja erinevad granulaarsuse poolest: ainult staatus, ainult kuupäev või kõik üksikasjad. See näiline liigsus on tahtlik – see võimaldab mudelil küsida ainult seda, mida ta vajab, vähendades kontekstis olevat tarbetut teavet. Neljas funktsioon muudab vaatenurka ja töötab kliendi põhjal.
Pane tähele ühist lepingut: kõik tagastavad JSON-stringi, isegi tõrke korral, ja kõik käsitlevad puuduvaid identifikaatoreid, selle asemel et lasta Pandas’il tühja indeksi korral erindit visata.
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})
Teisendus float(row["payment_amount"]) väärib teist pilku: ilma selleta nurjub json.dumps NumPy tüüpidega. Selliseid detaile märkad alles käivitamisel.
JSON-spetsifikatsioonid
Mudel ei näe ülaltoodud koodist midagi. Ta tunneb ainult neid kirjeldusi. Võimalike staatuste selge loetlemine funktsioonis retrieve_payment_status ja mudelile vormingu T1001 meeldetuletamine igas parameetri kirjelduses võimaldab tal valida õige funktsiooni ja ekstraheerida identifikaatori õigesti.
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"]
}
}
}
]
Edastamise sõnastik
Siin on konks: sinu funktsioonid eeldavad esimese argumendina df-i, kuid mudel seda kunagi ei paku – ta ei tea, et see eksisteerib, ja see on korras. functools.partial lahendab selle elegantselt, seostades DataFrame’i ette, nii et iga kirje sõnastikus muutub käivitatavaks ainult nende argumentidega, mida mudel toodab.
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),
}
Vestluse tsükkel
Süsteemi sõnum määrab rolli, keele ja summade oodatava vormingu. Funktsioon chat korraldab ülejäänu ja selle struktuur väärib tähelepanelikku uurimist: tsükkel while message.tool_calls käsitleb ühtikut väljakutset, mitut paralleelset väljakutset või ahelat, kus mudel küsib pärast esimese tulemuse nägemist teist funktsiooni. Sisemine tsükkel täidab kõik praeguse vooru väljakutsed; välimine tsükkel kutsub mudelit uuesti nii kaua, kuni see tööriistu nõuab.
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
Mida vestlus paljastab
Testi seda nelja järjestikuse vooruga. Teine on kõige õpetlikum: „see tehing“ ei sisalda identifikaatorit, ometi kutsub mudel retrieve_payment_details argumendiga T1001. Ta lahendas anafoori, kasutades muutujas messages säilitatud ajalugu, mis oleks võimatu, kui nulliksid loendi iga väljakutse korral. Neljas voor näitab teist poolt: ükski funktsioon ei otsi ebaõnnestunud makseid, kuid mudel päringutab asjakohast klienti ja filtreerib tulemuse ise.
# 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."
Summade vormindamine kümnendkohaga ja kuupäevade väljakirjutamine täies ulatuses ei tulene ühestki koodireast: see tuleneb süsteemi sõnumist. See on selle peatüki kõige kasulikum järeldus – pool tajutavast kvaliteedist sünnib kirjeldustes ja süsteemi sõnumis, mitte väljakutsemehaanikas.
Peamised punktid
- Terviklik maksete jälgija nõuab 4 funktsiooni, mis katavad peamised kasutusjuhtumid
functools.partialseob DataFrame’i funktsioonidega puhtaks edastamiseks- Tsükkel
while message.tool_callskäsitleb automaatselt järjestikuseid ja paralleelseid väljakutseid - Süsteemi sõnum juhendab mudelit tooni, keele ja vormingu osas
- Testi mitmevooruliste vestlustega, et veenduda mudeli konteksti säilitamises