Дефиниране на функции с JSON Schema
На тази страница
Договорът между Вашия код и модела
За да може моделът 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.parameters | JSON 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разграничава задължителните параметри от незадължителните - Прецизните описания с примери значително подобряват точността на модела