Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

JSON sheme i opisi

Lekcija 2 od 14 Ažurirano 29. srpnja 2026. Programer
Na ovoj stranici
  1. Jezik alata: JSON shema
  2. Anatomija definicije alata
  3. Opisi parametara
  4. Napredni parametri
  5. Najbolje prakse za opise
  6. Ključne točke

Jezik alata: JSON shema

Da bi Grok mogao pozivati tvoje funkcije, mora znati što one rade i koje parametre očekuju. To je uloga JSON shema. Svaki alat opisan je strukturiranim objektom koji sadrži tri ključna dijela: naziv, opis i shemu parametara.

Anatomija definicije alata

Evo potpune strukture alata kakvu Grok API očekuje:

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

Rastavimo svako polje:

Polje type

Uvijek ima vrijednost "function" za prilagođene funkcije. Postoje i druge vrste za ugrađene alate (web_search, code_interpreter), ali za tvoje vlastite funkcije to je uvijek "function".

Polje name

Tehnički naziv tvoje funkcije. Mora biti:

  • Jedinstven među svim alatima u zahtjevu
  • Opisan: get_weather umjesto fn1
  • U snake_case formatu po konvenciji: search_products, create_ticket
  • Kratak, ali jasan: model koristi taj naziv kako bi odlučio koji alat pozvati

Polje description

Ovo je najvažnije polje za kvalitetu poziva. Model se prvenstveno oslanja na opis kako bi odlučio kada i kako koristiti alat. Dobar opis:

  • Objašnjava što funkcija radi u jednoj rečenici
  • Određuje kada je koristiti (ako nije očito)
  • Spominje rubne slučajeve ako je potrebno

Usporedi ova dva opisa:

❌ "Vrijeme"
✅ "Dohvati trenutno vrijeme za grad. Vraća temperaturu, vlažnost i uvjete."

Drugi opis modelu daje dovoljno konteksta da točno zna kada pozvati tu funkciju i što će zauzvrat dobiti.

Blok parameters

Parametri slijede format JSON sheme. Podržane vrste uključuju:

  • string — nizovi znakova
  • number / integer — brojevi
  • boolean — true/false
  • array — popisi
  • object — ugniježđeni objekti
  • enum — popis dopuštenih vrijednosti

Niz required navodi obavezne parametre. Ostali su opcionalni — model ih može izostaviti.

Opisi parametara

Svaki parametar trebao bi imati vlastiti description. To modelu omogućuje da razumije koju vrijednost proslijediti:

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

Bez opisa, model mora nagađati očekivani format — što dovodi do pogrešaka.

Napredni parametri

Enum za ograničavanje vrijednosti

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

Enum vrijednosti posebno su korisne: govore modelu točne vrijednosti koje smije koristiti, čime se eliminiraju pogreške u formatu.

Zadane vrijednosti

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

Model razumije da može izostaviti taj parametar ako mu zadana vrijednost odgovara.

Ugniježđeni objekti

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

Najbolje prakse za opise

Opis je jedini kanal kroz koji model razumije tvoj alat — svaka riječ tu ima težinu. Prvo specifičnost: „Pretraži proizvode po nazivu ili kategoriji u katalogu“ modelu točno govori kada se taj alat primjenjuje, dok „Pretraži proizvode“ ostavlja prostor za nagađanje. Zatim formati: navođenje „Datum u ISO 8601 formatu (YYYY-MM-DD)“ u opisu parametra eliminira polovicu pogrešaka u argumentima jer model replicira format koji mu pokažeš. Ograničenja su dio ugovora: „Maksimalno 50 rezultata po pozivu“ sprječava model da korisniku obeća potpunost koju alat ne može pružiti. A opis povratne vrijednosti — „Vraća objekt s cijenom, dostupnošću i opisom“ — pomaže modelu da unaprijed isplanira: zna što će imati na raspolaganju prije nego što uopće izvrši poziv.

Ključne točke

  • Svaki alat definiran je s name, description i parameters
  • Opis je faktor broj 1 za kvalitetu poziva — uloži vrijeme u njega
  • Nazivi moraju biti jedinstveni i u snake_case formatu
  • Koristi enum za ograničavanje mogućih vrijednosti
  • Svaki parametar trebao bi imati vlastiti opis s očekivanim formatom
  • Niz required razlikuje obavezne parametre od opcionalnih