Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Schémata JSON a popisy

Lekce 2 z 14 Aktualizováno 29. července 2026 Vývojář
Na této stránce
  1. Jazyk nástrojů: Schéma JSON
  2. Anatomie definice nástroje
  3. Popisy parametrů
  4. Pokročilé parametry
  5. Osvědčené postupy pro popisy
  6. Klíčové poznatky

Jazyk nástrojů: Schéma JSON

Aby mohl Grok volat tvé funkce, musí vědět, co dělají a jaké parametry očekávají. To je úloha schémat JSON. Každý nástroj je popsán strukturovaným objektem obsahujícím tři zásadní informace: název, popis a schéma parametrů.

Anatomie definice nástroje

Zde je úplná struktura nástroje tak, jak ji očekává 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"]
  }
}

Pojďme si rozebrat každé pole:

Pole type

Pro vlastní funkce vždy "function". Existují i jiné typy pro vestavěné nástroje (web_search, code_interpreter), ale pro tvé vlastní funkce je to nezměnitelně "function".

Pole name

Technický název tvé funkce. Musí být:

  • Jedinečný mezi všemi nástroji v požadavku
  • Výstižný: get_weather místo fn1
  • Ve formátu snake_case podle konvence: search_products, create_ticket
  • Stručný, ale explicitní: model používá tento název k rozhodnutí, který nástroj zavolat

Pole description

Toto je nejdůležitější pole pro kvalitu volání. Model se při rozhodování, kdy a jak nástroj použít, spoléhá primárně na popis. Dobrý popis:

  • Vysvětluje co funkce dělá v jedné větě
  • Upřesňuje kdy ji použít (pokud to není zřejmé)
  • Zmiňuje hraniční případy, pokud je to nutné

Porovnej tyto dva popisy:

❌ "Počasí"
✅ "Získá aktuální počasí pro město. Vrací teplotu, vlhkost a podmínky."

Druhý popis dává modelu dostatek kontextu, aby přesně věděl, kdy tuto funkci zavolat a co dostane zpět.

Blok parameters

Parametry následují formát JSON Schema. Podporované typy zahrnují:

  • string — řetězce znaků
  • number / integer — čísla
  • boolean — pravda/nepravda
  • array — seznamy
  • object — vnořené objekty
  • enum — seznam povolených hodnot

Pole required uvádí povinné parametry. Ostatní jsou volitelné – model se může rozhodnout je vynechat.

Popisy parametrů

Každý parametr by měl mít vlastní description. To umožňuje modelu pochopit, jakou hodnotu předat:

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

Bez popisu musí model očekávaný formát hádat – což vede k chybám.

Pokročilé parametry

Enums pro omezení hodnot

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

Enums jsou obzvláště užitečné: říkají modelu přesné hodnoty, které může použít, čímž eliminují chyby formátu.

Výchozí hodnoty

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

Model pochopí, že může tento parametr vynechat, pokud mu vyhovuje výchozí hodnota.

Vnořené objekty

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

Osvědčené postupy pro popisy

Popis je jediným kanálem, skrze který model chápe tvůj nástroj – každé slovo zde hraje roli. Na prvním místě je specifičnost: „Vyhledat produkty podle názvu nebo kategorie v katalogu“ říká modelu přesně, kdy tento nástroj použít, zatímco „Vyhledat produkty“ ho nechává tápat. Dále formáty: upřesnění „Datum ve formátu ISO 8601 (RRRR-MM-DD)“ v popisu parametru eliminuje polovinu chyb v argumentech, protože model replikuje formát, který mu ukážeš. Limity jsou součástí smlouvy: „Maximálně 50 výsledků na volání“ zabrání modelu slibovat uživateli úplnost, kterou nástroj neposkytne. A popis návratové hodnoty – „Vrací objekt s cenou, dostupností a popisem“ – pomáhá modelu plánovat dopředu: ví, co bude mít k dispozici, ještě před samotným voláním.

Klíčové poznatky

  • Každý nástroj je definován pomocí name, description a parameters
  • Popis je faktorem číslo jedna pro kvalitu volání – věnuj mu čas
  • Názvy musí být jedinečné a ve formátu snake_case
  • Použij enum pro omezení možných hodnot
  • Každý parametr by měl mít vlastní popis s očekávaným formátem
  • Pole required rozlišuje povinné parametry od volitelných