Zum Hauptinhalt springen
Deutsch— Sprache auswählen
Menü

Beispiel: Zahlungsverfolgung

Lektion 12 von 14 Aktualisiert am 2. November 2026 Entwickler
Auf dieser Seite
  1. Ein vollständiges Projekt von Ende zu Ende
  2. Die Daten
  3. Geschäftliche Funktionen
  4. JSON-Spezifikationen
  5. Das Dispatch-Wörterbuch
  6. Der Gesprächsloop
  7. Was das Gespräch enthüllt
  8. Wichtige Erkenntnisse

Ein vollständiges Projekt von Ende zu Ende

In den vorherigen Lektionen wurden die einzelnen Mechanismen isoliert betrachtet: Tool-Definitionen, der Aufrufzyklus, Fehlerbehandlung und Sicherheit. Jetzt ist es an der Zeit, diese zu verbinden. Sie werden einen vollständigen konversationellen Zahlungsverfolger erstellen, bei dem Nutzer Fragen in natürlicher Sprache stellen und das System über Function Calling einen Pandas DataFrame abfragt. Dieser Anwendungsfall basiert direkt auf der offiziellen Mistral-Dokumentation. Das Projekt umfasst etwa hundert Zeilen und offenbart die fünf Bausteine einer echten Anwendung: Daten, geschäftliche Funktionen, JSON-Spezifikationen, Dispatch und den Gesprächsloop.

Die Daten

Ein DataFrame mit fünf Transaktionen deckt die interessanten Szenarien ab: ein Kunde mit mehreren Zahlungen, eine ausstehende Zahlung und eine fehlgeschlagene Zahlung.

import pandas as pd
import json
import os
from mistralai.client import Mistral
from functools import partial

# Transaktions-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)

Geschäftliche Funktionen

Vier Funktionen decken typische Anforderungen zur Zahlungsverfolgung ab. Die ersten drei arbeiten auf einer einzelnen Transaktion und unterscheiden sich durch das Detailniveau: nur Status, nur Datum oder vollständige Details. Diese scheinbare Redundanz ist absichtlich gewählt – sie ermöglicht es dem Modell, nur die benötigten Informationen abzurufen und unnötige Daten im Kontext zu reduzieren. Die vierte Funktion ändert die Perspektive und arbeitet nach Kunde.

Beachten Sie den gemeinsamen Vertrag: alle Funktionen geben ein JSON-String zurück, auch bei Fehlern, und alle behandeln fehlende Identifikatoren, anstatt dass Pandas eine Ausnahme bei einem leeren Index wirft.

def retrieve_payment_status(df: pd.DataFrame, transaction_id: str) -> str:
    """Ruft den Status einer Zahlung ab."""
    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"Transaktion {transaction_id} nicht gefunden"})


def retrieve_payment_date(df: pd.DataFrame, transaction_id: str) -> str:
    """Ruft das Datum einer Zahlung ab."""
    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"Transaktion {transaction_id} nicht gefunden"})


def retrieve_payment_details(df: pd.DataFrame, transaction_id: str) -> str:
    """Ruft alle Details einer Zahlung ab."""
    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"Transaktion {transaction_id} nicht gefunden"})


def list_customer_transactions(df: pd.DataFrame, customer_id: str) -> str:
    """Listet alle Transaktionen für einen bestimmten Kunden auf."""
    customer_df = df[df["customer_id"] == customer_id]
    if customer_df.empty:
        return json.dumps({"error": f"Kunde {customer_id} nicht gefunden"})

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

Die Umwandlung float(row["payment_amount"]) verdient einen zweiten Blick: Ohne diese würde json.dumps bei NumPy-Typen fehlschlagen. Dies ist die Art von Detail, die man erst zur Laufzeit erkennt.

JSON-Spezifikationen

Das Modell sieht keinen der obigen Code. Es kennt nur diese Beschreibungen. Das explizite Auflisten der möglichen Status in retrieve_payment_status und das Erinnern des Modells an das Format T1001 in jeder Parameterbeschreibung ermöglichen es ihm, die richtige Funktion zu wählen und den Identifikator korrekt zu extrahieren.

tools = [
    {
        "type": "function",
        "function": {
            "name": "retrieve_payment_status",
            "description": "Ruft den Status einer Zahlung ab (paid, pending, failed)",
            "parameters": {
                "type": "object",
                "properties": {
                    "transaction_id": {
                        "type": "string",
                        "description": "Transaktions-Identifikator (z. B. T1001)"
                    }
                },
                "required": ["transaction_id"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "retrieve_payment_date",
            "description": "Ruft das Datum einer Zahlung ab",
            "parameters": {
                "type": "object",
                "properties": {
                    "transaction_id": {
                        "type": "string",
                        "description": "Transaktions-Identifikator (z. B. T1001)"
                    }
                },
                "required": ["transaction_id"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "retrieve_payment_details",
            "description": "Ruft alle Details einer Zahlung ab: Betrag, Datum, Status, Kunde",
            "parameters": {
                "type": "object",
                "properties": {
                    "transaction_id": {
                        "type": "string",
                        "description": "Transaktions-Identifikator (z. B. T1001)"
                    }
                },
                "required": ["transaction_id"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "list_customer_transactions",
            "description": "Listet alle Transaktionen für einen bestimmten Kunden auf",
            "parameters": {
                "type": "object",
                "properties": {
                    "customer_id": {
                        "type": "string",
                        "description": "Kunden-Identifikator (z. B. C001)"
                    }
                },
                "required": ["customer_id"]
            }
        }
    }
]

Das Dispatch-Wörterbuch

Hier liegt der Haken: Ihre Funktionen erwarten df als erstes Argument, aber das Modell wird es niemals bereitstellen – es weiß nicht, dass es existiert, und das ist in Ordnung. functools.partial löst dies elegant, indem es den DataFrame vorab bindet, sodass jeder Eintrag im Wörterbuch mit nur den Argumenten aufrufbar ist, die das Modell liefert.

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

Der Gesprächsloop

Die Systemnachricht legt die Rolle, die Sprache und das erwartete Format für Beträge fest. Die chat-Funktion orchestriert den Rest, und ihre Struktur verdient eine genaue Betrachtung: Der while message.tool_calls-Loop verarbeitet einen einzelnen Aufruf, mehrere parallele Aufrufe oder eine Kette, bei der das Modell nach dem ersten Ergebnis eine weitere Funktion anfordert. Der innere Loop führt alle Aufrufe für die aktuelle Runde aus; der äußere Loop ruft das Modell erneut auf, solange es weiterhin Tools anfordert.

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
model = "mistral-large-latest"

messages = [
    {
        "role": "system",
        "content": "Sie sind ein Assistent zur Zahlungsverfolgung. "
                   "Antworten Sie auf Englisch. Verwenden Sie die verfügbaren Tools, "
                   "um Fragen zu Transaktionen zu beantworten. "
                   "Formatieren Sie Beträge in Euro mit zwei Dezimalstellen."
    }
]


def chat(user_input: str) -> str:
    """Vollständiger Gesprächswechsel mit Handhabung von tool_calls."""
    messages.append({"role": "user", "content": user_input})

    response = client.chat.complete(
        model=model, messages=messages, tools=tools
    )
    message = response.choices[0].message

    # Loop, solange das Modell Funktionen aufrufen möchte
    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"Unbekannte Funktion {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

Was das Gespräch enthüllt

Testen Sie dies mit vier aufeinanderfolgenden Wechseln. Der zweite ist am lehrreichsten: “diese Transaktion” enthält keinen Identifikator, doch das Modell ruft retrieve_payment_details mit T1001 auf. Es hat die Anapher mithilfe der im messages-Liste gespeicherten Historie aufgelöst, was unmöglich wäre, wenn die Liste bei jedem Aufruf zurückgesetzt würde. Der vierte Wechsel zeigt die andere Seite: Keine Funktion sucht nach fehlgeschlagenen Zahlungen, doch das Modell fragt den relevanten Kunden ab und filtert das Ergebnis selbst.

# Wechsel 1
print(chat("Was ist der Status der Zahlung T1001?"))
# -> "Die Zahlung T1001 hat den Status: paid."

# Wechsel 2
print(chat("Geben Sie mir alle Details für diese Transaktion."))
# -> "Hier sind die Details für die Zahlung T1001:
#     - Kunde: C001
#     - Betrag: 125.50 Euro
#     - Datum: 15. März 2026
#     - Status: paid"

# Wechsel 3
print(chat("Welche Transaktionen hat der Kunde C002?"))
# -> "Der Kunde C002 hat 2 Transaktionen:
#     - T1002: 89.99 Euro (paid, 16. März 2026)
#     - T1004: 45.00 Euro (paid, 17. März 2026)"

# Wechsel 4
print(chat("Gibt es fehlgeschlagene Zahlungen?"))
# -> "Ja, die Zahlung T1005 für den Kunden C001 (210.75 Euro) ist fehlgeschlagen."

Das Formatierung der Beträge mit einem Dezimalpunkt und das vollständige Schreiben der Daten kommt von keiner Zeile Code: Es folgt aus der Systemnachricht. Dies ist der nützlichste Erkenntnisgewinn dieses Kapitels – die Hälfte der wahrgenommenen Qualität entsteht in den Beschreibungen und der Systemnachricht, nicht in den Mechanismen des Aufrufs.

Wichtige Erkenntnisse

  • Ein vollständiger Zahlungsverfolger erfordert 4 Funktionen, die die Hauptanwendungsfälle abdecken
  • functools.partial bindet den DataFrame an die Funktionen für eine saubere Dispatch-Logik
  • Der while message.tool_calls-Loop verarbeitet automatisch sequenzielle und parallele Aufrufe
  • Die Systemnachricht leitet das Modell hinsichtlich Ton, Sprache und Formatierung
  • Testen Sie mit mehrstufigen Gesprächen, um zu überprüfen, ob das Modell den Kontext beibehält