Премини към основното съдържание
Български— Изберете език
Меню

Пример за реализация: Проследяване на плащания

Урок 12 от 14 Обновен 2 ноември 2026 г. Програмист
На тази страница
  1. Пълен проект от край до край
  2. Данните
  3. Бизнес функции
  4. JSON спецификации
  5. Речникът за диспечиране
  6. Цикълът на разговора
  7. Какво разкрива разговорът
  8. Ключови изводи

Пълен проект от край до край

Предишните уроци разглеждаха всеки механизъм поотделно: дефиниции на инструменти, цикъл на извикване, обработка на грешки и сигурност. Сега е време да ги обедините. Ще изградите цялостен конверсационен проследявач на плащания, където потребителите задават въпроси на естествен език, а системата прави заявки към 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 автоматично обработва последователни и паралелни извиквания
  • Системното съобщение насочва модела относно тона, езика и форматирането
  • Тествайте с многоходови разговори, за да проверите дали моделът запазва контекста