Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Näidisprojekt: Maksete jälgija

Õppetund 12 / 14 Värskendatud 2. november 2026 Arendajatele
Sellel lehel
  1. Terviklik lõpuni viidud projekt
  2. Andmed
  3. Ärifunktsioonid
  4. JSON-spetsifikatsioonid
  5. Edastamise sõnastik
  6. Vestluse tsükkel
  7. Mida vestlus paljastab
  8. Peamised punktid

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.partial seob DataFrame’i funktsioonidega puhtaks edastamiseks
  • Tsükkel while message.tool_calls kä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