Léim go dtí an príomhábhar
Gaeilge— Roghnaigh teanga
Roghchlár

Sampla Oibre: Rianaire Íocaíochtaí

Ceacht 12 as 14 Nuashonraithe 2 Samhain 2026 Forbróir
Ar an leathanach seo
  1. Tionscadal Iomlán ó Thús go Deireadh
  2. Na Sonraí
  3. Feidhmeanna Gnó
  4. Sonruithe JSON
  5. An Foclóir Seolta
  6. An Lúb Chomhrá
  7. Cad a Nochtann an Comhrá
  8. Príomhphointí

Tionscadal Iomlán ó Thús go Deireadh

I gcúrsaí roimhe seo, d’fhágamar gach meicníocht ar leithligh: sainmhínithe uirlisí, an timthriall glaonna, láimhseáil earráidí, agus slándáil. Anois, tá sé in am iad a chur le chéile. Tógfaidh tú rianaire íocaíochta comhráite iomlán ina gcuireann úsáideoirí ceisteanna i ngnáththeanga agus ina ndéanann an córas ceisteanna ar DataFrame Pandas trí ghlao feidhme. Tagann an cás úsáide seo go díreach ó dhoiciméadacht oifigiúil Mistral. Oiriúnann sé do thart ar chéad líne cód agus nochtann sé na cúig bhloc tógála d’fheidhmchlár fíor: sonraí, feidhmeanna gnó, sonruithe JSON, seoladh, agus an lúb chomhrá.

Na Sonraí

Clúdaíonn DataFrame le cúig idirbheart na cásanna suimiúla: custaiméir le híocaíochtaí iolracha, íocaíocht ar feitheamh, agus íocaíocht theipthe.

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)

Feidhmeanna Gnó

Clúdaíonn ceithre fheidhm riachtanacha tipiciúla rianaithe íocaíochtaí. Baineann na chéad trí cinn le hidirbheart amháin agus difríonn siad de réir gráinneachta: stádas amháin, dáta amháin, nó sonraí iomlána. Tá an barrachas dealraitheach seo d’aon turas – ligeann sé don mhúnla ach an méid atá uaidh a iarraidh, rud a laghdaíonn sonraí nach bhfuil gá leo sa chomhthéacs. Aistríonn an ceathrú feidhm an peirspictíocht agus oibríonn sí de réir custaiméara.

Tabhair faoi deara an conradh coiteann: filleann siad uile teaghrán JSON, fiú ar theip, agus láimhseálann siad uimhreacha aitheantais atá in easnamh in ionad ligean do Pandas eisceacht a ardú ar innéacs folamh.

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

Is fiú breathnú arís ar an tiontú float(row["payment_amount"]): gan é, teipeann ar json.dumps ar chineálacha NumPy. Seo an cineál mionsonra nach mbíonn le fáil ach ag am rith.

Sonruithe JSON

Ní fheiceann an múnla aon chuid den chód thuas. Níl a fhios aige ach na cur síos seo. Trí na stádais fhéideartha a liostú go soiléir in retrieve_payment_status agus cuimhneamh don mhúnla ar fhormáid T1001 i ngach cur síos paraiméadair, cumasaítear dó an fheidhm cheart a roghnú agus an t-aitheantóir a bhaint amach i gceart.

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"]
            }
        }
    }
]

An Foclóir Seolta

Seo an fhadhb: tá súil ag do chuid feidhmeanna le df mar an chéad argóint, ach ní sholáthróidh an múnla é riamh – níl a fhios aige go bhfuil sé ann, agus tá sé sin ceart go leor. Réitíonn functools.partial é seo go galánta tríd an DataFrame a cheangal roimh ré, ionas go mbíonn gach iontráil sa fhoclóir inghlaoite leis na hargóintí a tháirgeann an múnla amháin.

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

An Lúb Chomhrá

Socraíonn an teachtaireacht chórais an ról, an teanga, agus an formáidiú atá ag teastáil do mhéideanna. Déanann an fheidhm chat comhordú ar an gcuid eile, agus tá sé tábhachtach breathnú go géar ar a struchtúr: láimhseálann an lúb while message.tool_calls glao amháin, glaonna iolracha comhthreomhara, nó slabhra ina n-iarrann an múnla feidhm eile tar éis an chéad toradh a fheiceáil. Déanann an lúb inmheánach gach glao don timthriall reatha a fhorghníomhú; athghlaonn an lúb sheachtrach an múnla fad is a leanann sé ag iarraidh uirlisí.

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

Cad a Nochtann an Comhrá

Déan tástáil air seo le ceithre thimthriall as a chéile. Is é an dara ceann an ceann is oideachasúla: níl aon aitheantóir in “this transaction” (an t-idirbheart seo), ach glaonn an múnla retrieve_payment_details le T1001. Réitigh sé an anafora ag baint úsáide as an stair a coinníodh i messages, rud a bheadh dodhéanta dá gcuirfeá an liosta ar athshocrú ar gach glao. Taispeánann an ceathrú timthriall an taobh eile: níl aon fheidhm ag cuardach íocaíochtaí teipthe, ach déanann an múnla ceist ar an gcustaiméir ábhartha agus scagann sé an toradh é féin.

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

Tagann formáidiú na méideanna le pointe deachúil agus dátaí scríofa amach go hiomlán ó aon líne cóid: eascraíonn sé as an leid chórais. Seo an t-eachtra is úsáidí ón gcaibidil seo – tarlaíonn leath den cháilíocht mheasta sna cur síos agus sa teachtaireacht chórais, seachas sna meicníochtaí glaonna.

Príomhphointí

  • Éilíonn rianaire íocaíochtaí iomlán 4 fheidhm a chlúdaíonn na príomhchásanna úsáide
  • Ceanglaíonn functools.partial an DataFrame leis na feidhmeanna le haghaidh seolta glain
  • Láimhseálann an lúb while message.tool_calls glaonna seicheamhacha agus comhthreomhara go huathoibríoch
  • Treoraíonn an teachtaireacht chórais an múnla maidir le ton, teanga, agus formáidiú
  • Déan tástáil le comhráite il-thimthriallta chun a fhíorú go gcoinníonn an múnla an comhthéacs