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

Дефиниране на функции с JSON Schema

Урок 3 от 14 Обновен 29 юли 2026 г. Програмист
На тази страница
  1. Договорът между Вашия код и модела
  2. Анатомия на спецификацията на инструмент
  3. Поддържани типове в JSON Schema
  4. Пълен пример: две допълващи се функции
  5. Задължителни спрямо незадължителни параметри
  6. Най-добри практики за описания
  7. Ключови изводи

Договорът между Вашия код и модела

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

Имайте предвид едно нещо през целия урок: моделът никога не вижда Вашия Python код. Той вижда само тази спецификация. Ако Вашата функция обработва коректно ID с малки букви, но схемата не го уточнява, моделът ще игнорира тази възможност. Колкото по-прецизна и добре документирана е Вашата схема, толкова по-точни ще бъдат генерираните аргументи.

Анатомия на спецификацията на инструмент

Всеки инструмент, изпратен към API на Mistral, следва една и съща структура:

tool = {
    "type": "function",
    "function": {
        "name": "function_name",
        "description": "Clear description of what the function does",
        "parameters": {
            "type": "object",
            "properties": {
                "param1": {
                    "type": "string",
                    "description": "Parameter description"
                },
                "param2": {
                    "type": "integer",
                    "description": "Parameter description"
                }
            },
            "required": ["param1"]
        }
    }
}
ПолеРоля
typeВинаги "function" (други типове може да съществуват в бъдеще)
function.nameТочното име на Вашата Python функция – това е стойността, която моделът връща в tool_calls
function.descriptionЯсно изречение, което помага на модела да избере правилната функция
function.parametersJSON Schema обект, описващ очакваните параметри
requiredСписък със задължителните параметри

Поддържани типове в JSON Schema

Речникът от типове, наличен за описване на параметри, е умишлено ограничен и всеки тип насочва модела по различен начин. enum по-специално прави повече от просто документиране: той затваря вратата за измислени стойности.

# String — свободен текст или ограничен
{"type": "string", "description": "Transaction ID"}

# String с enum — ограничени стойности
{"type": "string", "enum": ["asc", "desc"], "description": "Sort order"}

# Integer — цяло число
{"type": "integer", "description": "Number of results to return"}

# Number — десетично число
{"type": "number", "description": "Amount in euros"}

# Boolean — true/false
{"type": "boolean", "description": "Include canceled transactions"}

# Array — списък от стойности
{
    "type": "array",
    "items": {"type": "string"},
    "description": "List of transaction IDs"
}

# Object — вложен обект
{
    "type": "object",
    "properties": {
        "city": {"type": "string"},
        "country": {"type": "string"}
    },
    "description": "Shipping address"
}

Правите ясна разлика между integer и number: сума в евро като 125.50 изисква number, докато бройката на резултатите за връщане е integer. Декларирането на сума като integer ще накара модела да я закръгли.

Пълен пример: две допълващи се функции

Ето един реалистичен пример с две функции, свързани с плащания, вдъхновен от официалната документация на Mistral:

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": "The unique transaction ID (e.g., T1001)"
                    }
                },
                "required": ["transaction_id"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "retrieve_payment_date",
            "description": "Retrieves the date when a payment was made "
                           "based on the transaction ID.",
            "parameters": {
                "type": "object",
                "properties": {
                    "transaction_id": {
                        "type": "string",
                        "description": "The unique transaction ID (e.g., T1001)"
                    }
                },
                "required": ["transaction_id"]
            }
        }
    }
]

И двете функции очакват точно един и същ параметър, transaction_id, но моделът трябва да избере между тях. Този избор разчита изцяло на описанието на функцията. „Премина ли това плащане?“ съответства на retrieve_payment_status; „Кога беше?“ съответства на retrieve_payment_date. Ако бяхте написали две неясни, взаимозаменяеми описания, моделът щеше да греши в половината случаи – и Вие щяхте да обвинявате модела, когато грешката е в схемата.

Задължителни спрямо незадължителни параметри

Разликата между задължителните и незадължителните параметри определя какво моделът има право да пропусне.

{
    "type": "function",
    "function": {
        "name": "search_transactions",
        "description": "Searches for transactions based on various criteria",
        "parameters": {
            "type": "object",
            "properties": {
                "status": {
                    "type": "string",
                    "enum": ["paid", "pending", "failed"],
                    "description": "Filter by payment status"
                },
                "date_from": {
                    "type": "string",
                    "description": "Start date in YYYY-MM-DD format"
                },
                "date_to": {
                    "type": "string",
                    "description": "End date in YYYY-MM-DD format"
                },
                "min_amount": {
                    "type": "number",
                    "description": "Minimum amount in euros"
                }
            },
            "required": ["status"]
        }
    }
}

Тук само status е задължителен; другите параметри се включват само ако потребителят ги спомене. Сравнете две формулировки. За „Покажи ми неуспешните плащания“ моделът генерира просто {"status": "failed"}. За „Покажи ми неуспешните плащания от март 2026 г.“ той добавя date_from и date_to самостоятелно. Ако бяхте направили тези дати задължителни, това щеше да разруши първата заявка или, още по-лошо, да принуди модела да измисли диапазон от дати.

Най-добри практики за описания

Качеството на описанието влияе директно върху точността на модела. Контрапримерите по-долу са по-поучителни от всяко абстрактно правило.

# Лошо — твърде неясно
{"description": "Retrieves data"}

# Добро — прецизно и контекстуално
{"description": "Retrieves the status of a payment (paid, pending, failed) "
                "based on the unique transaction ID"}

# Лошо — липсва описание за параметъра
{"transaction_id": {"type": "string"}}

# Добро — описание с пример
{"transaction_id": {
    "type": "string",
    "description": "Unique transaction ID (format: T followed by 4 digits, e.g., T1001)"
}}

Едно добро описание посочва в едно изречение какво прави функцията, уточнява очаквания формат за всеки параметър и предоставя пример, когато този формат не е очевиден – T1001 е по-добре от „transaction ID“. Когато възможните стойности са ограничени, не ги описвайте с проза: декларирайте ги с enum. Това е единственият начин да ги направите задължителни.

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

  • JSON Schema е договорът между Вашия код и модела – той описва Вашите функции, без да разкрива кода
  • Всеки инструмент има name, description и типизирани parameters
  • Поддържаните типове включват string, integer, number, boolean, array и object
  • Списъкът required разграничава задължителните параметри от незадължителните
  • Прецизните описания с примери значително подобряват точността на модела