Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Schémy JSON a popisy

Lekcia 2 z 14 Aktualizované 29. júla 2026 Vývojár
Na tejto strane
  1. Jazyk nástrojov: Schéma JSON
  2. Anatómia definície nástroja
  3. Popisy parametrov
  4. Pokročilé parametre
  5. Osvedčené postupy pre popisy
  6. Kľúčové poznatky

Jazyk nástrojov: Schéma JSON

Aby mohol Grok volať tvoje funkcie, potrebuje vedieť, čo robia a aké parametre očakávajú. To je úlohou schém JSON. Každý nástroj je opísaný štruktúrovaným objektom obsahujúcim tri základné časti: názov, popis a schému parametrov.

Anatómia definície nástroja

Tu je kompletná štruktúra nástroja tak, ako ju očakáva API Grok:

{
  "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"]
  }
}

Poďme si rozobrať každé pole:

Pole type

Pre vlastné funkcie má vždy hodnotu "function". Existujú aj iné typy pre vstavané nástroje (web_search, code_interpreter), ale pre tvoje vlastné funkcie je to vždy "function".

Pole name

Technický názov tvojej funkcie. Musí byť:

  • Jedinečný medzi všetkými nástrojmi v požiadavke
  • Výstižný: get_weather namiesto fn1
  • V tvare snake_case podľa konvencie: search_products, create_ticket
  • Stručný, no explicitný: model používa tento názov na rozhodovanie, ktorý nástroj zavolať

Pole description

Toto je najdôležitejšie pole pre kvalitu volania. Model sa pri rozhodovaní, kedy a ako nástroj použiť, spolieha primárne na popis. Dobrý popis:

  • V jednej vete vysvetľuje, čo funkcia robí
  • Špecifikuje, kedy ju použiť (ak to nie je zrejmé)
  • Spomína hraničné prípady, ak je to potrebné

Porovnaj tieto dva popisy:

❌ "Počasie"
✅ "Získa aktuálne počasie pre mesto. Vracia teplotu, vlhkosť a podmienky."

Druhý popis dáva modelu dostatok kontextu, aby presne vedel, kedy túto funkciu zavolať a čo dostane späť.

Blok parameters

Parametre nasledujú formát JSON Schema. Podporované typy zahŕňajú:

  • string — reťazce znakov
  • number / integer — čísla
  • boolean — pravda/nepravda
  • array — zoznamy
  • object — vnorené objekty
  • enum — zoznam povolených hodnôt

Pole required obsahuje zoznam povinných parametrov. Ostatné sú voliteľné – model sa môže rozhodnúť ich vynechať.

Popisy parametrov

Každý parameter by mal mať vlastný description. To umožňuje modelu pochopiť, akú hodnotu má odovzdať:

{
  "date": {
    "type": "string",
    "description": "Date in YYYY-MM-DD format. If omitted, uses today's date."
  }
}

Bez popisu musí model formát hádať – čo vedie k chybám.

Pokročilé parametre

Enumy na obmedzenie hodnôt

{
  "priority": {
    "type": "string",
    "enum": ["low", "medium", "high", "critical"],
    "description": "Ticket priority level"
  }
}

Enumy sú obzvlášť užitočné: hovoria modelu presné hodnoty, ktoré môže použiť, čím eliminujú chyby vo formáte.

Predvolené hodnoty

{
  "limit": {
    "type": "integer",
    "default": 10,
    "description": "Maximum number of results to return"
  }
}

Model pochopí, že tento parameter môže vynechať, ak mu vyhovuje predvolená hodnota.

Vnorené objekty

{
  "address": {
    "type": "object",
    "properties": {
      "street": { "type": "string" },
      "city": { "type": "string" },
      "zip": { "type": "string" }
    },
    "required": ["city"]
  }
}

Osvedčené postupy pre popisy

Popis je jediným kanálom, cez ktorý model chápe tvoj nástroj – každé slovo tu hrá rolu. Na prvom mieste je špecifickosť: „Vyhľadaj produkty podľa názvu alebo kategórie v katalógu“ modelu presne povie, kedy sa tento nástroj použije, zatiaľ čo „Vyhľadaj produkty“ ho nechá tápať. Ďalej sú to formáty: špecifikácia „Dátum vo formáte ISO 8601 (RRRR-MM-DD)“ v popise parametra eliminuje polovicu chýb v argumentoch, pretože model replikuje formát, ktorý mu ukážeš. Limity sú súčasťou zmluvy: „Maximálne 50 výsledkov na volanie“ zabráni modelu sľubovať používateľovi úplnosť, ktorú nástroj neposkytne. A popis návratovej hodnoty – „Vracia objekt s cenou, dostupnosťou a popisom“ – pomáha modelu plánovať dopredu: vie, čo bude mať k dispozícii ešte pred samotným volaním.

Kľúčové poznatky

  • Každý nástroj je definovaný pomocou name, description a parameters
  • Popis je faktorom číslo jedna pre kvalitu volania – venuj mu čas
  • Názvy musia byť jedinečné a v tvare snake_case
  • Použi enum na obmedzenie možných hodnôt
  • Každý parameter by mal mať vlastný popis s očakávaným formátom
  • Pole required odlišuje povinné parametre od voliteľných