Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Sheme JSON in opisi

Lekcija 2 od 14 Posodobljeno 29. julij 2026 Razvijalec
Na tej strani
  1. Jezik orodij: shema JSON
  2. Anatomija definicije orodja
  3. Opisi parametrov
  4. Napredni parametri
  5. Najboljše prakse za opise
  6. Ključne ugotovitve

Jezik orodij: shema JSON

Da lahko Grok kliče tvoje funkcije, mora vedeti, kaj počnejo in katere parametre pričakujejo. To je vloga shem JSON. Vsako orodje je opisano s strukturiranim objektom, ki vsebuje tri ključne dele informacij: ime, opis in shemo parametrov.

Anatomija definicije orodja

Tukaj je popolna struktura orodja, kot jo pričakuje 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"]
  }
}

Razčlenimo vsako polje:

Polje type

Za funkcije po meri je to vedno "function". Obstajajo tudi druge vrste za vgrajena orodja (web_search, code_interpreter), toda za tvoje lastne funkcije je to neizogibno "function".

Polje name

Tehnično ime tvoje funkcije. Biti mora:

  • Edinstveno med vsemi orodji v zahtevi
  • Opisno: get_weather namesto fn1
  • V zapisu snake_case po dogovoru: search_products, create_ticket
  • Kratko, a eksplicitno: model uporabi to ime za odločitev, katero orodje bo poklical

Polje description

To je najpomembnejše polje za kakovost klica. Model se pri odločanju, kdaj in kako uporabiti orodje, primarno zanaša na opis. Dober opis:

  • V enem stavku razloži, kaj funkcija počne
  • Določi, kdaj jo uporabiti (če ni očitno)
  • Po potrebi omeni robne primere

Primerjaj ta dva opisa:

❌ "Weather"
✅ "Get the current weather for a city. Returns temperature, humidity, and conditions."

Drugi opis modelu zagotovi dovolj konteksta, da točno ve, kdaj poklicati to funkcijo in kaj bo dobil v zameno.

Blok parameters

Parametri sledijo formatu JSON Schema. Podprte vrste vključujejo:

  • string — znakovni nizi
  • number / integer — števila
  • boolean – true/false
  • array — seznami
  • object — gnezdeni objekti
  • enum — seznam dovoljenih vrednosti

Polje required našteje obvezne parametre. Ostali so neobvezni – model se lahko odloči, da jih izpusti.

Opisi parametrov

Vsak parameter mora imeti svoj description. To modelu omogoča, da razume, katero vrednost naj posreduje:

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

Brez opisa mora model ugibati pričakovani format, kar vodi do napak.

Napredni parametri

Enums za omejevanje vrednosti

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

Enums so še posebej uporabni: modelu sporočijo točne vrednosti, ki jih lahko uporabi, s čimer odpravijo napake v formatu.

Privzete vrednosti

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

Model razume, da lahko ta parameter izpusti, če mu privzeta vrednost ustreza.

Gnezdeni objekti

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

Najboljše prakse za opise

Opis je edini kanal, prek katerega model razume tvoje orodje – vsaka beseda tu šteje. Najprej specifičnost: „Iskanje izdelkov po imenu ali kategoriji v katalogu” modelu točno pove, kdaj se to orodje uporablja, medtem ko „Iskanje izdelkov” pušča prostor za ugibanje. Nato formati: navedba „Datum v formatu ISO 8601 (LLLL-MM-DD)” v opisu parametra odpravi polovico napak pri argumentih, saj model replicira format, ki mu ga pokažeš. Omejitve so del pogodbe: „Največ 50 rezultatov na klic” prepreči, da bi modelu obljubil uporabniku popolnost, ki je orodje ne more zagotoviti. In opis vračene vrednosti – „Vrne objekt s ceno, razpoložljivostjo in opisom” – pomaga modelu pri načrtovanju vnaprej: ve, kaj bo imel na voljo, še preden pokliče funkcijo.

Ključne ugotovitve

  • Vsako orodje je definirano z name, description in parameters
  • Opis je dejavnik št. 1 za kakovost klica – vanj vloži čas
  • Imena morajo biti edinstvena in v zapisu snake_case
  • Uporabi enum za omejitev možnih vrednosti
  • Vsak parameter mora imeti svoj opis s pričakovanim formatom
  • Polje required loči obvezne parametre od neobveznih