Премини към основното съдържание
Български— Изберете език
Меню

Дефиниране на функции в Python

Урок 4 от 14 Обновен 2 ноември 2026 г. Програмист
На тази страница
  1. От теория към код
  2. Инсталиране на Mistral SDK
  3. Създаване на Python функции
  4. Написване на JSON спецификации
  5. Организиране на функции в речник
  6. Опцията tool_choice
  7. Ключови изводи

От теория към код

Сега разбирате процеса от пет стъпки и структурата на JSON Schema. Време е да напишете реален Python код. В този урок ще създадете функции, ще изготвите техните спецификации и ще подготвите всичко за Mistral API – всичко, което трябва да съществува, преди да направите първото мрежово обаждане.

Инсталиране на Mistral SDK

Започнете с инсталирането на официалния пакет:

pip install mistralai

След това конфигурирайте своя API ключ. Добрата практика диктува никога да не го вграждате директно във вашите изходни файлове. Вместо това го прочетете от променлива на средата, за да можете безопасно да качите кода си в системата за контрол на версиите.

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

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

Създаване на Python функции

Нека разгледаме един работещ пример: система за проследяване на плащания, базирана на Pandas DataFrame. Това е класически пример от документацията на Mistral и илюстрира перфектно концепцията – тук DataFrame играе ролята, която базата данни би имала в продукционна среда.

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)

Следва кодът, който всъщност достъпва тези данни. Това са стандартни Python функции; нищо в тяхната реализация не подсказва, че LLM ще ги управлява.

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

Два детайла от реализацията заслужават вниманието Ви. Първо, тези функции винаги връщат JSON низ, никога суров Python обект. Това е форматът, който моделът очаква като резултат от инструмент, така че json.dumps() е задължителен. Второ, те изрично обработват случая, когато транзакция не е намерена, вместо да хвърлят изключение. Тази грешка, форматирана като JSON, се връща на модела точно както всеки друг резултат, позволявайки му любезно да информира потребителя, че транзакция T9999 не съществува. По-късно в курса ще видите защо този рефлекс е от съществено значение.

Написване на JSON спецификации

Всяка функция се нуждае от спецификация, за да може моделът да я разбере. Тук прилагате структурата от предишния урок към двете функции по-горе – обърнете внимание на стриктното съответствие между полетата name и действителните имена на 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"]
            }
        }
    }
]

Организиране на функции в речник

Моделът връща името на функцията като низ. Трябва Ви начин да картографирате този низ към съответния извикваем обект, без да прибягвате до eval или каскада от if инструкции. Речникът за диспечиране решава този проблем в три реда.

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 адресира специфична, реална трудност. Вашите функции очакват два аргумента – DataFrame и ID – но моделът предоставя само един. Моделът не знае нищо за df, нито трябва да знае. partial попълва предварително този първи параметър веднъж завинаги. Същият механизъм се прилага за връзки с бази данни, HTTP клиенти или токени за автентикация. Динамичното извикване след това става тривиално.

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

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

Опцията tool_choice

Когато изпращате тези инструменти към API, параметърът tool_choice решава колко свобода давате на модела. Възможни са три стойности.

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

Режимът "auto" е най-често срещан в продукционна среда с добра причина: асистентът за проследяване на плащания трябва да може да каже „здравей“, без да задейства заявка към базата данни. Моделът отговаря директно на общи въпроси и използва функции само когато е уместно. Цял урок по-късно в курса обхваща конкретни случаи на употреба за any и none.

Ключови изводи

  • Функциите трябва да връщат JSON низове – никога сурови Python обекти
  • Използвайте речник за диспечиране, за да картографирате имената на функциите към техните реализации
  • functools.partial е идеален за предварително попълване на параметри като връзки с бази данни или DataFrames
  • tool_choice контролира дали моделът може или трябва да използва функции (auto, any, none)
  • Винаги обработвайте случаите на грешки във вашите функции (невалидни параметри, липсващи данни)