Definiowanie funkcji w Pythonie
Na tej stronie
Od teorii do kodu
Znasz już proces pięcioetapowy i strukturę schematu JSON. Czas napisać prawdziwy kod w Pythonie. W tej lekcji stworzysz funkcje, opracujesz ich specyfikacje i przygotujesz wszystko pod API Mistrala – czyli wszystko, co musi istnieć przed wykonaniem pierwszego wywołania sieciowego.
Instalacja SDK Mistral
Zacznij od zainstalowania oficjalnego pakietu:
pip install mistralai
Następnie skonfiguruj swój klucz API. Dobra praktyka nakazuje, aby nigdy nie umieszczać go na sztywno w plikach źródłowych. Zamiast tego odczytaj go ze zmiennej środowiskowej, dzięki czemu będziesz mógł bezpiecznie commitować kod do systemu kontroli wersji.
export MISTRAL_API_KEY="your-api-key"
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
Tworzenie funkcji w Pythonie
Spójrzmy na konkretny przykład: system śledzenia płatności oparty na DataFrame z biblioteki Pandas. To klasyczny przykład z dokumentacji Mistrala, który doskonale ilustruje tę koncepcję – tutaj DataFrame pełni rolę, jaką w środowisku produkcyjnym pełniłaby baza danych.
import pandas as pd
import json
# Dane dotyczące płatności
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)
Kolejny krok to kod faktycznie uzyskujący dostęp do tych danych. Są to standardowe funkcje Pythona; nic w ich implementacji nie sugeruje, że będzie nimi sterował model LLM.
def retrieve_payment_status(df: pd.DataFrame, transaction_id: str) -> str:
"""Pobiera status płatności na podstawie jej identyfikatora."""
if transaction_id in df["transaction_id"].values:
status = df[df["transaction_id"] == transaction_id]["payment_status"].values[0]
return json.dumps({"status": status})
return json.dumps({"error": f"Transaction {transaction_id} not found"})
def retrieve_payment_date(df: pd.DataFrame, transaction_id: str) -> str:
"""Pobiera datę płatności na podstawie jej identyfikatora."""
if transaction_id in df["transaction_id"].values:
date = df[df["transaction_id"] == transaction_id]["payment_date"].values[0]
return json.dumps({"date": date})
return json.dumps({"error": f"Transaction {transaction_id} not found"})
Dwa szczegóły implementacyjne zasługują na Twoją uwagę. Po pierwsze, funkcje te zawsze zwracają ciąg JSON, a nigdy surowy obiekt Pythona. Jest to format oczekiwany przez model jako wynik działania narzędzia, więc użycie json.dumps() jest niezbędne. Po drugie, funkcje jawnie obsługują przypadek, gdy transakcja nie zostanie znaleziona, zamiast zgłaszać wyjątek. Ten błąd, sformatowany jako JSON, wraca do modelu tak samo jak każdy inny wynik, co pozwala mu uprzejmie poinformować użytkownika, że transakcja T9999 nie istnieje. Później w kursie zobaczysz, dlaczego ten odruch jest kluczowy.
Pisanie specyfikacji JSON
Każda funkcja potrzebuje specyfikacji, aby model mógł ją zrozumieć. Tutaj zastosujesz strukturę z poprzedniej lekcji do dwóch powyższych funkcji – zwróć uwagę na ścisłą zgodność między polami name a rzeczywistymi nazwami funkcji w Pythonie.
tools = [
{
"type": "function",
"function": {
"name": "retrieve_payment_status",
"description": "Retrieves the status of a payment (paid, pending, failed) "
"based on the transaction ID.",
"parameters": {
"type": "object",
"properties": {
"transaction_id": {
"type": "string",
"description": "Unique transaction identifier (e.g., T1001)"
}
},
"required": ["transaction_id"]
}
}
},
{
"type": "function",
"function": {
"name": "retrieve_payment_date",
"description": "Retrieves the date a payment was made "
"based on the transaction ID.",
"parameters": {
"type": "object",
"properties": {
"transaction_id": {
"type": "string",
"description": "Unique transaction identifier (e.g., T1001)"
}
},
"required": ["transaction_id"]
}
}
}
]
Organizacja funkcji w słowniku
Model zwraca nazwę funkcji jako ciąg znaków. Potrzebujesz sposobu na odwzorowanie tego ciągu na odpowiedni obiekt wywoływalny, bez uciekania się do eval lub kaskady instrukcji if. Słownik dyspozytorski rozwiązuje ten problem w trzech liniach kodu.
from functools import partial
# Powiąż DataFrame z każdą funkcją
available_functions = {
"retrieve_payment_status": partial(retrieve_payment_status, df),
"retrieve_payment_date": partial(retrieve_payment_date, df),
}
functools.partial rozwiązuje konkretny, rzeczywisty problem. Twoje funkcje oczekują dwóch argumentów – DataFrame i identyfikatora – ale model dostarcza tylko jeden. Model nie wie nic o df i nie powinien wiedzieć. partial wypełnia ten pierwszy parametr raz na zawsze. Ten sam mechanizm dotyczy połączeń z bazą danych, klientów HTTP czy tokenów uwierzytelniających. Dynamiczne wywoływanie staje się wtedy trywialne.
function_name = "retrieve_payment_status"
function_params = {"transaction_id": "T1001"}
result = available_functions[function_name](**function_params)
# → '{"status": "paid"}'
Opcja tool_choice
Podczas wysyłania tych narzędzi do API, parametr tool_choice decyduje o tym, ile swobody przyznajesz modelowi. Możliwe są trzy wartości.
# Model decyduje, czy użyć narzędzia, czy odpowiedzieć bezpośrednio (domyślnie)
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=tools,
tool_choice="auto"
)
# Wymuś na modelu użycie narzędzia
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=tools,
tool_choice="any"
)
# Zablokuj modelowi możliwość używania narzędzi
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=tools,
tool_choice="none"
)
Tryb "auto" jest najczęściej stosowany w środowisku produkcyjnym z dobrego powodu: asystent ds. śledzenia płatności powinien móc powiedzieć „cześć“, nie uruchamiając przy tym zapytania do bazy danych. Model odpowiada bezpośrednio na ogólne pytania i używa funkcji tylko wtedy, gdy jest to istotne. Pełna lekcja poświęcona konkretnym przypadkom użycia any i none pojawi się później w kursie.
Kluczowe wnioski
- Funkcje muszą zwracać ciągi JSON – nigdy surowe obiekty Pythona
- Użyj słownika dyspozytorskiego, aby odwzorować nazwy funkcji na ich implementacje
functools.partialidealnie nadaje się do wstępnego wypełniania parametrów, takich jak połączenia z bazą danych czy DataFrametool_choicekontroluje, czy model może, czy musi używać funkcji (auto,any,none)- Zawsze obsługuj przypadki błędów w swoich funkcjach (nieprawidłowe parametry, brakujące dane)