Дефиниране на функции в Python
На тази страница
От теория към код
Сега разбирате процеса от пет стъпки и структурата на 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е идеален за предварително попълване на параметри като връзки с бази данни или DataFramestool_choiceконтролира дали моделът може или трябва да използва функции (auto,any,none)- Винаги обработвайте случаите на грешки във вашите функции (невалидни параметри, липсващи данни)