JSON схеми и описания
На тази страница
Езикът на инструментите: JSON схема
За да може Grok да извиква Вашите функции, той трябва да знае какво правят те и какви параметри очакват. Това е ролята на JSON схемите. Всеки инструмент се описва чрез структуриран обект, съдържащ три основни части: име, описание и схема на параметрите.
Анатомия на дефиницията на инструмент
Ето пълната структура на един инструмент, така както я очаква Grok API:
{
"type": "function",
"name": "get_weather",
"description": "Get the current weather for a given city",
"parameters": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "The city name (e.g., Paris, Lyon)"
},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"],
"default": "celsius"
}
},
"required": ["city"]
}
}
Нека разгледаме всяко поле поотделно:
Полето type
Винаги е "function" за потребителски функции. Съществуват други типове за вградени инструменти (web_search, code_interpreter), но за Вашите собствени функции то винаги е "function".
Полето name
Техническото име на Вашата функция. То трябва да бъде:
- Уникално сред всички инструменти в заявката
- Описателно:
get_weather, а неfn1 - В snake_case по конвенция:
search_products,create_ticket - Кратко, но ясно: моделът използва това име, за да реши кой инструмент да извика
Полето description
Това е най-важното поле за качеството на извикването. Моделът разчита основно на описанието, за да реши кога и как да използва даден инструмент. Едно добро описание:
- Обяснява какво прави функцията в едно изречение
- Посочва кога да се използва (ако не е очевидно)
- Споменава специфични случаи, ако е необходимо
Сравнете тези две описания:
❌ "Weather"
✅ "Get the current weather for a city. Returns temperature, humidity, and conditions."
Второто предоставя на модела достатъчно контекст, за да знае точно кога да извика тази функция и какво ще получи в замяна.
Блокът parameters
Параметрите следват формата на JSON Schema. Поддържаните типове включват:
string— текстови низовеnumber/integer— числаboolean— истина/лъжаarray— списъциobject— вложени обектиenum— списък с позволени стойности
Масивът required изброява задължителните параметри. Останалите са незадължителни — моделът може да реши да ги пропусне.
Описания на параметрите
Всеки параметър трябва да има свое собствено description. Това позволява на модела да разбере каква стойност да предаде:
{
"date": {
"type": "string",
"description": "Date in YYYY-MM-DD format. If omitted, uses today's date."
}
}
Без описание моделът трябва да guessed очаквания формат — което води до грешки.
Разширени параметри
Enums за ограничаване на стойностите
{
"priority": {
"type": "string",
"enum": ["low", "medium", "high", "critical"],
"description": "Ticket priority level"
}
}
Enums са особено полезни: те казват на модела точните стойности, които може да използва, елиминирайки грешки във формата.
Стойности по подразбиране
{
"limit": {
"type": "integer",
"default": 10,
"description": "Maximum number of results to return"
}
}
Моделът разбира, че може да пропусне този параметър, ако стойността по подразбиране е подходяща.
Вложени обекти
{
"address": {
"type": "object",
"properties": {
"street": { "type": "string" },
"city": { "type": "string" },
"zip": { "type": "string" }
},
"required": ["city"]
}
}
Най-добри практики за описанията
Описанието е единственият канал, чрез който моделът разбира Вашия инструмент — всяка дума има значение. На първо място е специфичността: „Търсене на продукти по име или категория в каталога“ казва на модела точно кога се прилага този инструмент, докато „Търсене на продукти“ го оставя да гадае. Следват форматите: посочването на „Дата във формат ISO 8601 (ГГГГ-ММ-ДД)“ в описанието на параметър елиминира половината грешки в аргументите, защото моделът възпроизвежда формата, който му показвате. Ограниченията са част от договора: „Максимум 50 резултата на извикване“ предотвратява обещанията на модела към потребителя за пълнота, която инструментът не може да осигури. И накрая, описанието на връщаната стойност — „Връща обект с цена, наличност и описание“ — помага на модела да планира предварително: той знае с какво ще разполага, преди дори да извика функцията.
Ключови изводи
- Всеки инструмент се дефинира чрез
name,descriptionиparameters - Описанието е фактор №1 за качеството на извикването — отделете време за него
- Имената трябва да са уникални и в snake_case
- Използвайте
enum, за да ограничите възможните стойности - Всеки параметър трябва да има свое описание с очаквания формат
- Масивът
requiredразграничава задължителните параметри от незадължителните