Пример за реализация: Проследяване на плащания
На тази страница
Пълен проект от край до край
Предишните уроци разглеждаха всеки механизъм поотделно: дефиниции на инструменти, цикъл на извикване, обработка на грешки и сигурност. Сега е време да ги обедините. Ще изградите цялостен конверсационен проследявач на плащания, където потребителите задават въпроси на естествен език, а системата прави заявки към Pandas DataFrame чрез извикване на функции. Този случай на употреба е взет директно от официалната документация на Mistral. Той се събира в около сто реда код, като същевременно демонстрира петте основни градивни елемента на едно реално приложение: данни, бизнес функции, JSON спецификации, диспечиране и цикъл на разговора.
Данните
DataFrame с пет транзакции покрива интересните сценарии: клиент с множество плащания, плащане в изчакване и неуспешно плащане.
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)
Бизнес функции
Четири функции покриват типичните нужди за проследяване на плащания. Първите три оперират върху една единствена транзакция и се различават по гранулярност: само статус, само дата или пълни детайли. Тази привидна излишност е умишлена – тя позволява на модела да поиска само онова, от което има нужда, намалявайки ненужните данни в контекста. Четвъртата функция променя перспективата и оперира по клиент.
Обърнете внимание на общия договор: всички връщат JSON низ, дори при грешка, и всички обработват липсващи идентификатори, вместо да позволяват на Pandas да генерира изключение при празен индекс.
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})
Конвертирането float(row["payment_amount"]) заслужава втори поглед: без него json.dumps се проваля при типове на NumPy. Това е видът детайл, който откривате единствено по време на изпълнение.
JSON спецификации
Моделът не вижда нито ред от горния код. Той познава само тези описания. Изричното изброяване на възможните статуси в retrieve_payment_status и напомнянето на модела за формата T1001 във всяко описание на параметър му позволява да избере правилната функция и да извлече идентификатора коректно.
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"]
}
}
}
]
Речникът за диспечиране
Ето уловката: Вашите функции очакват df като първи аргумент, но моделът никога няма да го предостави – той не знае, че съществува, и това е наред. functools.partial решава това елегантно, като предварително свързва DataFrame, така че всеки запис в речника да стане извикваем само с аргументите, които моделът генерира.
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),
}
Цикълът на разговора
Системното съобщение задава ролята, езика и очакваното форматиране за сумите. Функцията chat организира останалото и нейната структура заслужава внимателно разглеждане: цикълът while message.tool_calls обработва едно единствено извикване, множество паралелни извиквания или верига, в която моделът иска друга функция, след като види първия резултат. Вътрешният цикъл изпълнява всички извиквания за текущия ход; външният цикъл повторно извиква модела, стига той да продължава да иска инструменти.
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
Какво разкрива разговорът
Тествайте това с четири последователни хода. Вторият е най-поучителен: „тази транзакция“ не съдържа идентификатор, но моделът извиква retrieve_payment_details с T1001. Той е разрешил анафората, използвайки историята, запазена в messages, което би било невъзможно, ако нулирахте списъка при всяко извикване. Четвъртият ход показва обратната страна: няма функция, която да търси неуспешни плащания, но моделът прави заявка към съответния клиент и филтрира резултата самостоятелно.
# 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."
Форматирането на сумите с десетична точка и датите, изписани изцяло с думи, не идва от нито един ред код: то следва от системния промпт. Това е най-полезният извод от тази глава – половината от възприеманото качество се случва в описанията и системното съобщение, а не в механиката на извикване.
Ключови изводи
- Един завършен проследявач на плащания изисква 4 функции, покриващи основните случаи на употреба
functools.partialсвързва DataFrame към функциите за чисто диспечиране- Цикълът
while message.tool_callsавтоматично обработва последователни и паралелни извиквания - Системното съобщение насочва модела относно тона, езика и форматирането
- Тествайте с многоходови разговори, за да проверите дали моделът запазва контекста