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

JSON схеми и описания

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

Езикът на инструментите: 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 разграничава задължителните параметри от незадължителните