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

Definirea funcțiilor în Python

Lecția 4 din 14 Actualizată 2 noiembrie 2026 Dezvoltator
Pe această pagină
  1. De la teorie la cod
  2. Instalarea SDK-ului Mistral
  3. Crearea funcțiilor Python
  4. Scrierea specificațiilor JSON
  5. Organizarea funcțiilor într-un dicționar
  6. Opțiunea tool_choice
  7. Puncte cheie

De la teorie la cod

Ați înțeles acum procesul în cinci pași și structura JSON Schema. Este momentul să scrieți cod Python real. În această lecție, veți crea funcții, veți redacta specificațiile acestora și veți pregăti totul pentru API-ul Mistral – tot ce trebuie să existe înainte de a face prima apel de rețea.

Instalarea SDK-ului Mistral

Începeți prin instalarea pachetului oficial:

pip install mistralai

Apoi, configurați cheia dvs. API. Cele mai bune practici dictează să nu o codificați niciodată direct în fișierele sursă. În schimb, citiți-o dintr-o variabilă de mediu, astfel încât să puteți face commit la codul dvs. în controlul versiunilor în siguranță.

export MISTRAL_API_KEY="your-api-key"
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

Crearea funcțiilor Python

Să analizăm un exemplu concret: un sistem de urmărire a plăților susținut de un DataFrame Pandas. Acesta este un exemplu clasic din documentația Mistral și ilustrează perfect conceptul – aici, DataFrame-ul joacă rolul pe care l-ar avea o bază de date în producție.

import pandas as pd
import json

# Payment data
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)

Urmează codul care accesează efectiv aceste date. Acestea sunt funcții Python standard; nimic din implementarea lor nu sugerează că un LLM le va pilota.

def retrieve_payment_status(df: pd.DataFrame, transaction_id: str) -> str:
    """Retrieves the status of a payment by its ID."""
    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:
    """Retrieves the date of a payment by its ID."""
    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"})

Două detalii de implementare merită atenția dumneavoastră. În primul rând, aceste funcții returnează întotdeauna un șir JSON, niciodată un obiect Python brut. Acesta este formatul pe care modelul îl așteaptă ca rezultat al unui instrument, deci json.dumps() este obligatoriu. În al doilea rând, ele gestionează explicit cazul în care o tranzacție nu este găsită, în loc să arunce o excepție. Această eroare, formatată ca JSON, se întoarce la model la fel ca orice alt rezultat, permițându-i să informeze politicos utilizatorul că tranzacția T9999 nu există. Veți vedea mai târziu în curs de ce acest reflex este esențial.

Scrierea specificațiilor JSON

Fiecare funcție are nevoie de o specificație pentru ca modelul să o poată înțelege. Aici aplicați structura din lecția anterioară celor două funcții de mai sus – observați corespondența strictă dintre câmpurile name și numele reale ale funcțiilor Python.

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

Organizarea funcțiilor într-un dicționar

Modelul returnează un nume de funcție sub formă de șir de caractere. Aveți nevoie de o modalitate de a mapa acel șir la obiectul apelabil corespunzător, fără a recurge la eval sau la o cascadă de instrucțiuni if. Un dicționar de dispecerizare rezolvă această problemă în trei linii.

from functools import partial

# Bind the DataFrame to each function
available_functions = {
    "retrieve_payment_status": partial(retrieve_payment_status, df),
    "retrieve_payment_date": partial(retrieve_payment_date, df),
}

functools.partial abordează o dificultate specifică, din lumea reală. Funcțiile dumneavoastră se așteaptă la două argumente – DataFrame-ul și ID-ul – dar modelul furnizează doar unul. Modelul nu știe nimic despre df, nici nu ar trebui. partial pre-completează acel prim parametru o dată pentru totdeauna. Același mecanism se aplică conexiunilor la baze de date, clienților HTTP sau token-urilor de autentificare. Invocarea dinamică devine apoi trivială.

function_name = "retrieve_payment_status"
function_params = {"transaction_id": "T1001"}

result = available_functions[function_name](**function_params)
# → '{"status": "paid"}'

Opțiunea tool_choice

Atunci când trimiteți aceste instrumente către API, parametrul tool_choice decide câtă libertate acordați modelului. Sunt posibile trei valori.

# The model decides whether to use a tool or respond directly (default)
response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="auto"
)

# Force the model to use a tool
response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="any"
)

# Prevent the model from using tools
response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="none"
)

Modul "auto" este cel mai frecvent în producție dintr-un motiv întemeiat: un asistent de urmărire a plăților ar trebui să poată spune „bonjour“ fără a declanșa o interogare a bazei de date. Modelul răspunde direct la întrebările generale și utilizează funcțiile doar atunci când este relevant. O lecție întreagă mai târziu în curs acoperă cazurile de utilizare specifice pentru any și none.

Puncte cheie

  • Funcțiile trebuie să returneze șiruri JSON – niciodată obiecte Python brute
  • Utilizați un dicționar de dispecerizare pentru a mapa numele funcțiilor la implementările lor
  • functools.partial este ideal pentru pre-completarea parametrilor precum conexiunile la baza de date sau DataFrame-urile
  • tool_choice controlează dacă modelul poate sau trebuie să utilizeze funcții (auto, any, none)
  • Gestionați întotdeauna cazurile de eroare în funcțiile dumneavoastră (parametri invalidi, date lipsă)