Salt la conținutul principal
Română— Alege o limbă
Meniu

Bune practici și producție

Lecția 14 din 14 Actualizată 29 iulie 2026 Dezvoltator
Pe această pagină
  1. De la Proof of Concept la Producție
  2. Lista de verificare pentru implementare
  3. Scrierea unor descrieri care fac modelul să funcționeze
  4. Alegerea modelului potrivit
  5. Structurarea mesajului de sistem
  6. Gestionarea costurilor în producție
  7. Testarea apelării de funcții
  8. Monitorizarea în producție
  9. Pașii următori
  10. Puncte cheie
  11. Testați-vă cunoștințele

De la Proof of Concept la Producție

Aveți acum toate componentele necesare pentru a construi sisteme de apelare de funcții cu Mistral. Ceea ce separă prototipul dumneavoastră de un serviciu gata de producție nu sunt funcționalitățile lipsă, ci o serie de verificări și etape de optimizare pe care le descoperiți de obicei în timpul unui incident. Această ultimă lecție reunește bunele practici, capcanele frecvente și o listă de verificare pentru a trece la producție cu încredere.

Lista de verificare pentru implementare

Acesta este singurul loc din acest curs unde un format de listă este obligatoriu: înainte de a intra în funcțiune, bifați căsuțele. Patru domenii trebuie acoperite, fiecare răspunzând la o întrebare diferită.

Arhitectura asigură că mecanismele rezistă. Returnarea șirurilor JSON în lanț și deținerea unui dicționar de dispatch complet sunt cele două cauze frecvente de erori critice la primul apel real.

  • Toate funcțiile returnează șiruri JSON (niciodată obiecte Python brute)
  • Dicționarul de dispatch este complet și actualizat
  • Funcțiile gestionează cazurile de eroare și returnează mesaje utilizabile
  • Mesajul de sistem este clar, precis și testat
  • Bucla de conversație gestionează apelurile secvențiale și paralele

Securitatea presupune că argumentele provin de la un utilizator, niciodată de la aplicația dumneavoastră.

  • Argumentele sunt validate înainte de executare (format, tip, valori)
  • Interogările SQL utilizează parametri (fără concatenare)
  • O listă albă limitează funcțiile disponibile
  • Acțiunile distructive necesită confirmare
  • Limitarea ratei (rate limiting) este implementată per funcție și per utilizator
  • Rezultatele sunt sanitizate (niciun date sensibil nu este returnat modelului)

Fiabilitatea gestionează ceea ce eșuează fără ca nimeni să fie vinovat.

  • Erorile sunt returnate modelului într-un format structurat
  • Reîncercarea cu backoff este implementată pentru erorile tranzitorii
  • Timeout-urile sunt configurate pentru fiecare funcție externă
  • Dimensiunea istoricului este limitată pentru a evita depășirea numărului de tokeni

Monitorizarea, în final, este ceea ce vă permite să diagnosticați fără a ghici.

  • Fiecare apel de funcție este jurnalizat (nume, argumente, rezultat, durată)
  • Erorile declanșează alerte (Slack, PagerDuty, etc.)
  • Metricile sunt colectate (rata de succes, latență, cost API)

Scrierea unor descrieri care fac modelul să funcționeze

Calitatea descrierii are un impact direct asupra preciziei și este adesea pârghia cea mai ieftină de acționat. Trei modele recurente apar la echipele cu rate ridicate de apeluri corecte. Primul ancorează descrierea în contextul de afaceri: în loc să parafrazați numele funcției, listați valorile posibile de returnare și precizați explicit când să fie apelată. Al doilea introduce exemple de format în descrierea parametrului, ceea ce rezolvă majoritatea erorilor de extragere a ID-urilor. Al treilea înlocuiește o instrucțiune în limbaj natural cu un enum, singura modalitate de a interzice cu adevărat o valoare din afara listei.

# Modelul 1: Descriere cu context de afaceri
{
    "description": "Retrieves payment status. "
                   "Possible statuses: paid, pending, failed, refunded. "
                   "Use this function when the user asks "
                   "about a payment's status or whether it was received."
}

# Modelul 2: Parametri cu exemple
{
    "transaction_id": {
        "type": "string",
        "description": "Unique ID in format T followed by 4 digits (e.g., T1001, T2345)"
    }
}

# Modelul 3: Enum pentru valori limitate
{
    "status": {
        "type": "string",
        "enum": ["paid", "pending", "failed", "refunded"],
        "description": "Filter by payment status"
    }
}

Alegerea modelului potrivit

Alegerea modelului face un compromis între precizie și cost, iar răspunsul universal nu există: depinde de numărul de funcții expuse și de complexitatea schemelor lor. Un caz complex cu multe funcții și parametri imbricați justifică utilizarea Mistral Large 3, care este mai fiabil la selectarea funcțiilor, dar mai costisitor. Un caz standard cu câteva funcții simple într-o producție cu throughput ridicat rulează foarte bine pe Mistral Small 4, care este rapid și economic. Pentru prototipare și testare, Mistral Medium 3.5 oferă un compromis bun.

# Cazuri complexe: multe funcții, parametri imbricați
# -> Mistral Large 3 (mai fiabil, mai scump)
model = "mistral-large-latest"

# Cazuri standard: puține funcții simple, producție cu throughput ridicat
# -> Mistral Small 4 (rapid, economic)
model = "mistral-small-latest"

# Cazuri de dezvoltare: prototipare, testare
# -> Mistral Medium 3.5 (compromis bun)
model = "mistral-medium-latest"

Metoda contează la fel de mult ca rezultatul: în producție, începeți cu cel mai capabil model, măsurați rata de apeluri corecte, apoi coborâți treptat pentru a găsi cel mai bun raport cost/performanță. Inversul – începerea cu cel mai ieftin model – vă privează de linia de bază necesară pentru a ști dacă degradarea provine de la model sau de la descrierile dumneavoastră.

Structurarea mesajului de sistem

Un mesaj de sistem bun face diferența dintre un asistent mediocru și unul excelent. Acesta ilustrează o structură dovedită: o declarație de rol, un bloc de reguli imperative, apoi o reamintire a instrumentelor disponibile. Cele două reguli cu cel mai bun raport cost-eficacitate aici sunt „Dacă utilizatorul nu furnizează un ID necesar, întrebați politicos“ și „Nu ghiciți niciodată un ID de tranzacție“ – împreună, ele elimină cel mai dăunător comportament dintre toate: apelarea unei funcții cu un ID inventat.

system_message = {
    "role": "system",
    "content": """You are a payment management assistant for Acme Corporation.

Rules:
- Always respond in English
- Format amounts in euros with the symbol and 2 decimal places
- If the user doesn't provide a required ID, ask politely
- Never guess a transaction ID
- When a transaction fails, offer to check the details

Available tools:
- retrieve_payment_status: to check a payment's status
- retrieve_payment_date: to check a payment's date
- retrieve_payment_details: to get all details of a transaction
- list_customer_transactions: to view all transactions for a customer"""
}

Gestionarea costurilor în producție

Fiecare apel de funcție consumă tokeni, iar factura crește prin două canale subestimate: definițiile instrumentelor sunt trimise cu fiecare cerere, iar istoricul crește la fiecare tură. Filtrarea funcțiilor în funcție de context rezolvă primul punct – nu este nevoie să trimiteți toate cele douăsprezece instrumente când întrebarea este clar despre plăți. Trunchierea istoricului dincolo de un prag rezolvă al doilea. Și când toate datele necesare sunt deja în context, tool_choice="none" evită o rundă suplimentară.

# 1. Limitați numărul de funcții per cerere
# Trimiteți doar funcțiile relevante pentru context
def get_relevant_tools(user_input: str, all_tools: list) -> list:
    """Filters tools based on context."""
    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. Limitați dimensiunea istoricului
MAX_HISTORY = 20  # messages

# 3. Utilizați tool_choice="none" când datele sunt deja disponibile

Testarea apelării de funcții

Testele sunt esențiale pentru a evita regresii, iar aici ele vizează un obiect neobișnuit: nu verificați valoarea de returnare a funcției dumneavoastră, ci decizia modelului. Două familii de teste acoperă esențialul. Prima verifică faptul că o întrebare de afaceri declanșează funcția potrivită cu argumentele extrase corect. A doua, la fel de importantă și adesea uitată, verifică faptul că o salut nu declanșează niciun apel – acest test prinde descrierile prea largi care împing modelul să apeleze o funcție în orice circumstanță.

def test_payment_status():
    """Tests that the model calls the right function."""
    messages = [{"role": "user", "content": "Status of payment 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():
    """Tests that the model doesn't call a function for a greeting."""
    messages = [{"role": "user", "content": "Hello!"}]

    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

Monitorizarea în producție

Acum trebuie să știți ce face sistemul dumneavoastră odată lansat în mediul real. Clasa de mai jos agregă trei semnale care, împreună, spun aproape întreaga poveste: rata globală de succes, latența medie și defalcarea pe funcții. Ultima este cea mai revelatoare în practică – o funcție al cărei contor de erori derivează izolat indică o problemă specifică, în timp ce o rată globală degradată nu vă spune nimic despre unde să căutați.

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

Pașii următori

Acum că ați stăpânit apelarea de funcții cu Mistral, se deschid mai multe direcții. Cea mai naturală este construirea de agenți autonomi, combinând apelarea de funcții cu o buclă de agent care planifică și execută sarcini complexe; Mistral Agents API și metoda sa client.beta.agents.create() merg mai departe oferind agenți persistenți cu stare. O altă axă combină RAG și apelarea de funcții: modelul decide singur când să interogheze o bază de date vectorială, în loc ca căutarea să fie declanșată sistematic în amonte. Din perspectiva experienței utilizatorului, streaming-ul vă permite să afișați răspunsurile în timp real în timp ce funcțiile se execută, schimbând percepția latenței în lanțurile lungi de apeluri. În final, multimodalitatea deschide apelarea de funcții către viziune pentru analiza documentelor.

Puncte cheie

  • Lista de verificare pentru implementare acoperă arhitectura, securitatea, fiabilitatea și monitorizarea
  • Descrierile precise cu exemple și enum-uri îmbunătățesc precizia modelului
  • Alegeți modelul potrivit în funcție de complexitate și buget (Large pentru fiabilitate, Small pentru throughput)
  • Mesajul de sistem este o pârghie puternică pentru a ghida comportamentul
  • Testați sistematic apelurile de funcții și comportamentul fără funcții
  • Monitorizați rata de succes, latența și costurile în producție

Testați-vă cunoștințele

Apelarea de funcții end-to-end: cinci verificări.

1. Care sunt cei cinci pași ai apelării de funcții?

Răspuns: Definiți funcțiile (schemele), furnizați-le API-ului, modelul solicită un apel cu argumentele sale, codul dumneavoastră execută și returnează rezultatul, modelul produce răspunsul final.

2. Ce face o schemă de funcție bună?

Răspuns: Tipuri stricte și descrieri operaționale – nume clar, când să o utilizați, formatul fiecărui parametru: acesta este textul pe care modelul îl citește pentru a decide și completa.

3. Ce permit apelurile paralele?

Răspuns: Modelul solicită multiple funcții într-un singur răspuns când acestea sunt independente – mai puține runde de comunicare, cu condiția să potriviți fiecare rezultat cu apelul său.

4. La ce servește tool_choice?

Răspuns: Pentru a seta libertatea modelului: auto (decide el), any (trebuie să folosească un instrument) sau un instrument forțat – ultimul fiind cheia pentru extragerea structurată fiabilă.

5. Ce reguli de securitate pentru funcțiile expuse?

Răspuns: Validați argumentele primite, limitați domeniul de aplicare al fiecărei funcții, jurnalizați apelurile și mențineți validarea umană pentru acțiunile de commit – modelul propune, codul dumneavoastră dispune.

Cele două exemple lucrate în acest curs (tracker de plăți, CRM) aplică exact aceste reguli – integrările dumneavoastră proprii vor urma același tipar.