Pereiti prie pagrindinio turinio
Lietuvių— Pasirinkite kalbą
Meniu

Pavyzdys: Mokėjimų sekimo sistema

Paskaita 12 iš 14 Atnaujinta 2026 m. lapkričio 2 d. Kūrėjas
Šiame puslapyje
  1. Visas projektas nuo pradžių iki galo
  2. Duomenys
  3. Verslo funkcijos
  4. JSON specifikacijos
  5. Maršrutizavimo žodynas
  6. Pokalbių ciklas
  7. Ką atskleidžia pokalbis
  8. Svarbiausi punktai

Visas projektas nuo pradžių iki galo

Ankstesnėse pamokose nagrinėjome kiekvieną mechanizmą atskirai: įrankių apibrėžimus, kvietimo ciklą, klaidų valdymą ir saugumą. Dabar metas juos sujungti. Sukursi visapusišką konversacinę mokėjimų sekimo sistemą, kurioje vartotojai užduoda klausimus natūralia kalba, o sistema užklausia „Pandas“ duomenų lentelę naudodama funkcijų kvietimą. Šis atvejis tiesiogiai remiasi oficialia „Mistral“ dokumentacija. Jis telpa į maždaug šimtą eilučių ir atskleidžia penkis realios programos statybinius blokus: duomenis, verslo funkcijas, JSON specifikacijas, maršrutizavimą ir pokalbių ciklą.

Duomenys

Duomenų lentelė su penkiomis operacijomis apima įdomiausius scenarijus: klientą su keliais mokėjimais, laukiantį mokėjimą ir nepavykusį mokėjimą.

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)

Verslo funkcijos

Keturi funkcijos padengia tipinius mokėjimų sekimo poreikius. Pirmosios trys veikia su viena operacija ir skiriasi detalumo lygiu: tik būsena, tik data arba visi duomenys. Šis akivaizdus perteklius yra tyčinis – jis leidžia modeliui prašyti tik to, ko jam reikia, taip sumažinant nereikalingų duomenų kiekį kontekste. Ketvirtoji funkcija keičia perspektyvą ir veikia pagal klientą.

Atkreipk dėmesį į bendrą sutartį: visos grąžina JSON eilutę net ir nesėkmės atveju, bei visos tvarko trūkstamus identifikatorius, neleisdamos „Pandas“ išmesti išimties dėl tuščio indekso.

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})

Konvertavimas float(row["payment_amount"]) nusipelno antro žvilgsnio: be jo, json.dumps nepavyktų su „NumPy“ tipais. Tai tokia detalė, kurią pastebi tik vykdymo metu.

JSON specifikacijos

Modelis nemato nė vienos aukščiau pateiktos kodo eilutės. Jis žino tik šiuos aprašymus. Aiškus galimų būsenų išvardijimas funkcijoje retrieve_payment_status ir modelio priminimas apie T1001 formatą kiekviename parametro aprašyme leidžia jam pasirinkti tinkamą funkciją ir teisingai išgauti identifikatorių.

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šrutizavimo žodynas

Štai kur slypi gudrybė: tavo funkcijos tikisi df kaip pirmojo argumento, tačiau modelis jo niekada nepateiks – jis nežino, kad toks egzistuoja, ir tai yra gerai. functools.partial tai elegantiškai išsprendžia iš anksto susiejant duomenų lentelę, todėl kiekvienas žodyno įrašas tampa iškviečiamas tik su tais argumentais, kuriuos pateikia 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),
}

Pokalbių ciklas

Sistemos žinutė nustato vaidmenį, kalbą ir tikėtiną sumų formatavimą. Funkcija chat organizuoja visą procesą, o jos struktūra nusipelno atidaus dėmesio: ciklas while message.tool_calls tvarko vieną kvietimą, kelis lygiagrečius kvietimus arba grandinę, kai modelis prašo kitos funkcijos pamatęs pirmąjį rezultatą. Vidinis ciklas įvykdo visus einamojo ėjimo kvietimus; išorinis ciklas iš naujo iškviečia modelį tol, kol jis toliau prašo įrankių.

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

Ką atskleidžia pokalbis

Išbandyk tai keturiais iš eilės einančiais ėjimais. Antrasis yra pats informatyviausias: frazėje „ši operacija“ nėra identifikatoriaus, tačiau modelis iškviečia retrieve_payment_details su T1001. Jis išsprendė anaforą naudodamas istoriją, saugomą messages, kas būtų neįmanoma, jei sąrašą kiekvieno kvietimo metu iš naujo nustatytum. Ketvirtasis ėjimas rodo kitą pusę: nėra funkcijos, ieškančios nepavykusių mokėjimų, tačiau modelis užklausia atitinkamą klientą ir pats filtruoja rezultatą.

# 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."

Sumų formatavimas su dešimtaine dalimi ir datų rašymas pilnu tekstu nekyla iš jokios kodo eilutės: tai išplaukia iš sistemos prompto. Tai yra naudingiausia šio skyriaus išvada – pusė suvokiamos kokybės atsiranda dėl aprašymų ir sistemos žinutės, o ne dėl pačių kvietimo mechanizmų.

Svarbiausi punktai

  • Visavertei mokėjimų sekimo sistemai reikia 4 funkcijų, apimančių pagrindinius naudojimo atvejus
  • functools.partial susieja duomenų lentelę su funkcijomis švariam maršrutizavimui
  • Ciklas while message.tool_calls automatiškai tvarko nuoseklius ir lygiagrečius kvietimus
  • Sistemos žinutė nukreipia modelį dėl tono, kalbos ir formatavimo
  • Testuok su daugiažingsniais pokalbiais, kad įsitikintum, jog modelis išlaiko kontekstą