Piemērs: Maksājumu izsekotājs
Šajā lapā
Pilns projekts no sākuma līdz beigām
Iepriekšējās nodarbībās aplūkojām katru mehānismu atsevišķi: rīku definīcijas, izsaukumu ciklu, kļūdu apstrādi un drošību. Tagad ir laiks tos apvienot. Tu izveidosi pilnu sarunu balstītu maksājumu izsekotāju, kur lietotāji uzdod jautājumus dabiskā valodā, bet sistēma, izmantojot funkciju izsaukumus, vaicā datus no Pandas DataFrame. Šis lietojums tieši balstās uz oficiālo Mistral dokumentāciju. Tas ietilpst aptuveni simts rindiņās, vienlaikus demonstrējot piecus reālas lietotnes būvblokus: datus, biznesa funkcijas, JSON specifikācijas, maršrutēšanu un sarunu ciklu.
Dati
DataFrame ar pieciem darījumiem aptver interesantākos scenārijus: klients ar vairākiem maksājumiem, gaidošs maksājums un neveiksmīgs maksājums.
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)
Biznesa funkcijas
Četras funkcijas sedz tipiskas maksājumu izsekošanas vajadzības. Pirmās trīs darbojas ar vienu darījumu un atšķiras pēc granularitātes: tikai statuss, tikai datums vai pilna informācija. Šī šķietamā liekība ir apzināta – tā ļauj modelim pieprasīt tikai to, kas nepieciešams, samazinot liekos datus kontekstā. Ceturtā maina perspektīvu un darbojas pēc klienta.
Ņem vērā kopīgo līgumu: visas funkcijas atgriež JSON virkni pat kļūdas gadījumā, un visas apstrādā trūkstošos identifikatorus, neļaujot Pandas izraisīt izņēmumu tukša indeksa dēļ.
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})
Konversija float(row["payment_amount"]) ir pelnījusi papildu uzmanību: bez tās json.dumps neizdodas ar NumPy tipiem. Šādas detaļas tu pamanīsi tikai izpildes laikā.
JSON specifikācijas
Modelis neredz nevienu no iepriekš minētā koda. Tas zina tikai šos aprakstus. Skaidri uzskaitot iespējamos statusus funkcijā retrieve_payment_status un atgādinot modelim par formātu T1001 katrā parametra aprakstā, tu ļauj tam izvēlēties pareizo funkciju un pareizi iegūt identifikatoru.
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"]
}
}
}
]
Maršrutēšanas vārdnīca
Šeit ir ķēriens: tavas funkcijas sagaida df kā pirmo argumentu, bet modelis to nekad nenodrošinās – tas nezina, ka tas eksistē, un tas ir labi. functools.partial to eleganti atrisina, iepriekš piesaistot DataFrame, tāpēc katrs ieraksts vārdnīcā kļūst izsaucams tikai ar tiem argumentiem, ko ģenerē modelis.
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),
}
Sarunu cikls
Sistēmas ziņojums nosaka lomu, valodu un sagaidāmo summu formatējumu. Funkcija chat organizē pārējo, un tās struktūra ir pelnījusi rūpīgu uzmanību: cikls while message.tool_calls apstrādā vienu izsaukumu, vairākus paralēlus izsaukumus vai ķēdi, kur modelis pieprasa citu funkciju pēc pirmā rezultāta saņemšanas. Iekšējais cikls izpilda visus pašreizējā gājiena izsaukumus; ārējais cikls atkārtoti izsauc modeli, kamēr tas turpina pieprasīt rīkus.
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
Ko atklāj saruna
Izmēģini to ar četriem secīgiem gājieniem. Otrais ir vispamācošākais: „šis darījums” nesatur identifikatoru, tomēr modelis izsauc retrieve_payment_details ar T1001. Tas atrisināja anaforu, izmantojot vēsturi, kas saglabāta mainīgajā messages, kas būtu neiespējami, ja katrā izsaukumā sarakstu notīrītu. Ceturtais gājiens parāda otru pusi: neviena funkcija nemeklē neveiksmīgus maksājumus, taču modelis pats vaicā attiecīgo klientu un filtrē rezultātu.
# 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."
Summu formatēšana ar decimālzīmi un datumu pierakstīšana pilnā formātā neizriet no nevienas koda rindiņas: tas izriet no sistēmas uzvednes. Šis ir šīs nodaļas vērtīgākais secinājums – puse no uztvertās kvalitātes rodas aprakstos un sistēmas ziņojumā, nevis izsaukumu mehānikā.
Galvenās atziņas
- Pilns maksājumu izsekotājs prasa 4 funkcijas, kas aptver galvenos lietojumus
functools.partialpiesaista DataFrame funkcijām tīrai maršrutēšanai- Cikls
while message.tool_callsautomātiski apstrādā secīgus un paralēlus izsaukumus - Sistēmas ziņojums vada modeli attiecībā uz toni, valodu un formatējumu
- Testē ar daudzu gājienu sarunām, lai pārliecinātos, ka modelis saglabā kontekstu