Najlepsze praktyki i środowisko produkcyjne
Na tej stronie
- Od dowodu koncepcji do produkcji
- Lista kontrolna wdrożenia
- Pisanie opisów, które sprawiają, że model działa
- Wybór odpowiedniego modelu
- Strukturyzowanie wiadomości systemowej
- Zarządzanie kosztami w produkcji
- Testowanie wywoływania funkcji
- Monitorowanie w produkcji
- Następne kroki
- Kluczowe wnioski
- Sprawdź swoją wiedzę
Od dowodu koncepcji do produkcji
Masz już wszystkie elementy niezbędne do budowania systemów wywoływania funkcji z Mistral. Tym, co odróżnia Twój prototyp od gotowego do produkcji serwisu, nie są brakujące funkcje, lecz seria kontroli i kroków dostosowawczych, które zazwyczaj odkrywasz podczas incydentu. Ta ostatnia lekcja łączy najlepsze praktyki, częste pułapki oraz listę kontrolną, abyś mógł przejść do produkcji z pełnym przekonaniem.
Lista kontrolna wdrożenia
To jedyne miejsce w tym kursie, gdzie format listy jest obowiązkowy: przed uruchomieniem systemu odhaczasz kolejne punkty. Należy objąć cztery obszary, z których każdy odpowiada na inne pytanie.
Architektura zapewnia, że mechanizmy działają poprawnie. Zwracanie ciągów JSON w łańcuchu i posiadanie kompletnego słownika dyspozytorskiego to dwie najczęstsze przyczyny awarii przy pierwszym rzeczywistym wywołaniu.
- Wszystkie funkcje zwracają ciągi JSON (nigdy surowe obiekty Python)
- Słownik dyspozytorski jest kompletny i aktualny
- Funkcje obsługują przypadki błędów i zwracają użyteczne komunikaty
- Wiadomość systemowa jest jasna, precyzyjna i przetestowana
- Pętla konwersacji obsługuje wywołania sekwencyjne i równoległe
Bezpieczeństwo zakłada, że argumenty pochodzą od użytkownika, nigdy z Twojej aplikacji.
- Argumenty są walidowane przed wykonaniem (format, typ, wartości)
- Zapytania SQL używają parametrów (bez konkatenacji)
- Biała lista ogranicza dostępne funkcje
- Działania destrukcyjne wymagają potwierdzenia
- Wdrożono limitowanie częstotliwości (rate limiting) dla każdej funkcji i każdego użytkownika
- Wyniki są sanitizeowane (brak danych wrażliwych zwracanych do modelu)
Niezawodność zajmuje się sytuacjami, w których coś zawodzi bez czyjejkolwiek winy.
- Błędy są zwracane do modelu w ustrukturyzowanym formacie
- Zaimplementowano ponawianie z wycofaniem (retry with backoff) dla błędów przejściowych
- Skonfigurowano limity czasu (timeouts) dla każdej funkcji zewnętrznej
- Rozmiar historii jest ograniczony, aby uniknąć przekroczenia limitu tokenów
Monitorowanie wreszcie pozwala diagnozować problemy bez zgadywania.
- Każde wywołanie funkcji jest logowane (nazwa, argumenty, wynik, czas trwania)
- Błędy wyzwalają alerty (Slack, PagerDuty itp.)
- Gromadzone są metryki (wskaźnik sukcesu, opóźnienie, koszt API)
Pisanie opisów, które sprawiają, że model działa
Jakość opisów ma bezpośredni wpływ na dokładność i jest często najtańszym dźwignią do pociągnięcia. Wśród zespołów osiągających wysokie wskaźniki poprawnych wywołań powtarzają się trzy wzorce. Pierwszy osadza opis w kontekście biznesowym: zamiast parafrazować nazwę funkcji, wymień możliwe wartości zwracane i wyraźnie określ, kiedy jej użyć. Drugi wplata przykłady formatu w opis parametru, co naprawia większość błędów ekstrakcji identyfikatorów. Trzeci zastępuje instrukcję w języku naturalnym wartością enum, co jest jedynym sposobem na prawdziwe zablokowanie wartości spoza listy.
# Wzorzec 1: Opis z kontekstem biznesowym
{
"description": "Pobiera status płatności. "
"Możliwe statusy: paid, pending, failed, refunded. "
"Użyj tej funkcji, gdy użytkownik pyta "
"o status płatności lub czy została otrzymana."
}
# Wzorzec 2: Parametry z przykładami
{
"transaction_id": {
"type": "string",
"description": "Unikalny ID w formacie T followed by 4 digits (np. T1001, T2345)"
}
}
# Wzorzec 3: Enum dla ograniczonych wartości
{
"status": {
"type": "string",
"enum": ["paid", "pending", "failed", "refunded"],
"description": "Filtruj według statusu płatności"
}
}
Wybór odpowiedniego modelu
Wybór modelu to kompromis między dokładnością a kosztem i nie ma uniwersalnej odpowiedzi: zależy to od liczby udostępnionych funkcji oraz złożoności ich schematów. Złożony przypadek z wieloma funkcjami i zagnieżdżonymi parametrami uzasadnia użycie Mistral Large 3, który jest bardziej niezawodny w wyborze funkcji, ale droższy. Standardowy przypadek z kilkoma prostymi funkcjami w środowisku produkcyjnym o wysokim przepływie działa bardzo dobrze na Mistral Small 4, który jest szybki i ekonomiczny. Do prototypowania i testów Mistral Medium 3.5 oferuje dobry kompromis.
# Przypadki złożone: wiele funkcji, zagnieżdżone parametry
# -> Mistral Large 3 (bardziej niezawodny, droższy)
model = "mistral-large-latest"
# Przypadki standardowe: kilka prostych funkcji, produkcja o wysokim przepływie
# -> Mistral Small 4 (szybki, ekonomiczny)
model = "mistral-small-latest"
# Przypadki deweloperskie: prototypowanie, testy
# -> Mistral Medium 3.5 (dobry kompromis)
model = "mistral-medium-latest"
Metoda jest równie ważna co wynik: w produkcji zacznij od najbardziej zaawansowanego modelu, zmierz wskaźnik poprawnych wywołań, a następnie stopniowo schodź w dół, aby znaleźć najlepszy stosunek kosztu do wydajności. Odwrotna strategia – zaczynanie od najtańszego modelu – pozbawia Cię punktu odniesienia potrzebnego do stwierdzenia, czy degradacja wynika z modelu, czy z Twoich opisów.
Strukturyzowanie wiadomości systemowej
Dobra wiadomość systemowa decyduje o różnicy między przeciętnym asystentem a doskonałym. Poniższy przykład ilustruje sprawdzoną strukturę: stwierdzenie roli, blok imperatywnych reguł, a następnie przypomnienie dostępnych narzędzi. Dwie najbardziej opłacalne reguły to: „Jeśli użytkownik nie podał wymaganego ID, grzecznie o nie poproś“ oraz „Nigdy nie zgaduj ID transakcji“ – razem eliminują one najbardziej szkodliwe zachowanie, czyli wywoływanie funkcji z wymyślonym ID.
system_message = {
"role": "system",
"content": """Jesteś asystentem zarządzania płatnościami dla firmy Acme Corporation.
Zasady:
- Zawsze odpowiadaj w języku angielskim
- Formatuj kwoty w euro z symbolem i 2 miejscami po przecinku
- Jeśli użytkownik nie podał wymaganego ID, grzecznie o nie poproś
- Nigdy nie zgaduj ID transakcji
- Gdy transakcja nie powiedzie się, zaproponuj sprawdzenie szczegółów
Dostępne narzędzia:
- retrieve_payment_status: aby sprawdzić status płatności
- retrieve_payment_date: aby sprawdzić datę płatności
- retrieve_payment_details: aby uzyskać wszystkie szczegóły transakcji
- list_customer_transactions: aby wyświetlić wszystkie transakcje klienta"""
}
Zarządzanie kosztami w produkcji
Każde wywołanie funkcji zużywa tokeny, a rachunek rośnie przez dwa niedoceniane kanały: definicje narzędzi są wysyłane z każdym żądaniem, a historia rośnie z każdym obrotem. Filtrowanie funkcji według kontekstu rozwiązuje pierwszy problem – nie ma potrzeby wysyłania wszystkich dwunastu narzędzi, gdy pytanie dotyczy wyraźnie płatności. Skracanie historii poza określony próg rozwiązuje drugi. A gdy wszystkie niezbędne dane są już w kontekście, tool_choice="none" pozwala uniknąć dodatkowej rundy komunikacji.
# 1. Ogranicz liczbę funkcji na żądanie
# Przekaż tylko funkcje istotne dla kontekstu
def get_relevant_tools(user_input: str, all_tools: list) -> list:
"""Filtruje narzędzia na podstawie kontekstu."""
if "payment" in user_input.lower() or "transaction" in user_input.lower():
return [t for t in all_tools if "payment" in t["function"]["name"]]
if "contact" in user_input.lower() or "customer" in user_input.lower():
return [t for t in all_tools if "contact" in t["function"]["name"]]
return all_tools
# 2. Ogranicz rozmiar historii
MAX_HISTORY = 20 # wiadomości
# 3. Użyj tool_choice="none", gdy dane są już dostępne
Testowanie wywoływania funkcji
Testy są niezbędne, aby uniknąć regresji, a tutaj celują w nietypowy obiekt: nie sprawdzasz wartości zwracanej przez Twoją funkcję, lecz decyzję modelu. Dwie rodziny testów pokrywają essentials. Pierwsza weryfikuje, czy pytanie biznesowe wyzwala właściwą funkcję z poprawnie extracted argumentami. Druga, równie ważna i często zapominana, weryfikuje, czy powitanie nie wyzwala żadnego wywołania – ten test wyłapuje zbyt szerokie opisy, które skłaniają model do wywoływania funkcji w każdej sytuacji.
def test_payment_status():
"""Testuje, czy model wywołuje właściwą funkcję."""
messages = [{"role": "user", "content": "Status płatności T1001?"}]
response = client.chat.complete(
model=model, messages=messages, tools=tools
)
message = response.choices[0].message
assert message.tool_calls is not None
assert len(message.tool_calls) == 1
assert message.tool_calls[0].function.name == "retrieve_payment_status"
args = json.loads(message.tool_calls[0].function.arguments)
assert args["transaction_id"] == "T1001"
def test_no_function_for_greeting():
"""Testuje, czy model nie wywołuje funkcji dla powitania."""
messages = [{"role": "user", "content": "Cześć!"}]
response = client.chat.complete(
model=model, messages=messages, tools=tools
)
message = response.choices[0].message
assert message.tool_calls is None or len(message.tool_calls) == 0
assert message.content is not None
Monitorowanie w produkcji
Teraz musisz wiedzieć, co robi Twój system po wypuszczeniu go na wolność. Poniższa klasa agreguje trzy sygnały, które razem opowiadają prawie całą historię: ogólny wskaźnik sukcesu, średnie opóźnienie i podział na funkcje. Ten ostatni jest w praktyce najbardziej wymowny – funkcja, której licznik błędów rośnie w izolacji, wskazuje na konkretny problem, podczas gdy zdegradowany ogólny wskaźnik nic nie mówi o tym, gdzie szukać przyczyny.
import time
import logging
logger = logging.getLogger("fc_monitor")
class FunctionCallingMonitor:
def __init__(self):
self.metrics = {
"total_calls": 0,
"successful_calls": 0,
"failed_calls": 0,
"total_latency_ms": 0,
"calls_by_function": {}
}
def record(self, function_name: str, success: bool, latency_ms: float):
self.metrics["total_calls"] += 1
self.metrics["total_latency_ms"] += latency_ms
if success:
self.metrics["successful_calls"] += 1
else:
self.metrics["failed_calls"] += 1
if function_name not in self.metrics["calls_by_function"]:
self.metrics["calls_by_function"][function_name] = {
"count": 0, "errors": 0
}
self.metrics["calls_by_function"][function_name]["count"] += 1
if not success:
self.metrics["calls_by_function"][function_name]["errors"] += 1
def get_success_rate(self) -> float:
if self.metrics["total_calls"] == 0:
return 0.0
return self.metrics["successful_calls"] / self.metrics["total_calls"]
def get_avg_latency(self) -> float:
if self.metrics["total_calls"] == 0:
return 0.0
return self.metrics["total_latency_ms"] / self.metrics["total_calls"]
monitor = FunctionCallingMonitor()
Następne kroki
Teraz, gdy opanowałeś wywoływanie funkcji z Mistral, otwierają się przed Tobą różne kierunki. Najbardziej naturalnym jest budowanie autonomicznych agentów, łącząc wywoływanie funkcji z pętlą agenta, która planuje i wykonuje złożone zadania; Mistral Agents API i jego client.beta.agents.create() idą dalej, oferując persistent agents ze stanem. Innym osią jest połączenie RAG i wywoływania funkcji: model sam decyduje, kiedy odpytać bazę wektorową, zamiast wyszukiwania wyzwalanego systematycznie wcześniej. Po stronie doświadczenia użytkownika streaming pozwala wyświetlać odpowiedzi w czasie rzeczywistym podczas wykonywania funkcji, zmieniając percepcję opóźnienia w długich łańcuchach wywołań. Wreszcie, multimodalność otwiera wywoływanie funkcji na wizję komputerową do analizy dokumentów.
Kluczowe wnioski
- Lista kontrolna wdrożenia obejmuje architekturę, bezpieczeństwo, niezawodność i monitorowanie
- Precyzyjne opisy z przykładami i enumami poprawiają dokładność modelu
- Wybierz odpowiedni model w zależności od złożoności i budżetu (Large dla niezawodności, Small dla przepływu)
- Wiadomość systemowa to potężna dźwignia do kierowania zachowaniem
- Testuj wywołania funkcji i zachowanie „bez funkcji“ systematycznie
- Monitoruj wskaźnik sukcesu, opóźnienie i koszty w produkcji
Sprawdź swoją wiedzę
Wywoływanie funkcji end-to-end: pięć kontroli.
1. Jakie są pięć kroków wywoływania funkcji?
Odpowiedź: Zdefiniuj funkcje (schematy), przekaż je do API, model żąda wywołania ze swoimi argumentami, Twój kod wykonuje funkcję i zwraca wynik, model generuje końcową odpowiedź.
2. Co czyni dobry schemat funkcji?
Odpowiedź: Ścisłe typy i operacyjne opisy – jasna nazwa, kiedy jej użyć, format każdego parametru: to jest tekst, który model czyta, aby podjąć decyzję i wypełnić dane.
3. Co umożliwiają wywołania równoległe?
Odpowiedź: Model żąda wielu funkcji w jednej odpowiedzi, gdy są one niezależne – mniej rund komunikacji, pod warunkiem dopasowania każdego wyniku do jego wywołania.
4. Do czego służy tool_choice?
Odpowiedź: Do ustawienia swobody modelu: auto (on decyduje), any (musi użyć narzędzia) lub wymuszone narzędzie – to ostatnie jest kluczowe dla niezawodnej strukturyzowanej ekstrakcji.
5. Jakie zasady bezpieczeństwa dla udostępnionych funkcji?
Odpowiedź: Waliduj otrzymane argumenty, ogranicz zakres każdej funkcji, loguj wywołania i zachowaj walidację przez człowieka przy zatwierdzaniu działań – model proponuje, Twój kod rozporządza.
Dwa przykłady praktyczne w tym kursie (tracker płatności, CRM) stosują dokładnie te zasady – Twoje własne integracje będą podążać tym samym schematem.