Pereiti prie pagrindinio turinio
Lietuvių— Pasirinkite kalbą
Meniu

JSON schemos ir aprašymai

Paskaita 2 iš 14 Atnaujinta 2026 m. liepos 29 d. Kūrėjas
Šiame puslapyje
  1. Įrankių kalba: JSON schema
  2. Įrankio apibrėžimo sandara
  3. Parametrų aprašymai
  4. Išplėstiniai parametrai
  5. Geriausios aprašymų kūrimo praktikos
  6. Svarbiausi punktai

Įrankių kalba: JSON schema

Kad „Grok“ galėtų iškviesti tavo funkcijas, jis turi žinoti, ką jos daro ir kokių parametrų tikisi. Būtent tam skirtos JSON schemos. Kiekvienas įrankis aprašomas struktūruotu objektu, kuriame yra trys esminės dalys: pavadinimas, aprašymas ir parametrų schema.

Įrankio apibrėžimo sandara

Štai pilna įrankio struktūra, kokios tikisi „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"]
  }
}

Panagrinėkime kiekvieną laukelį atskirai:

Laukelis type

Tavo pačių kūriamoms funkcijoms visada nustatyk reikšmę "function". Egzistuoja ir kitų tipų integruotiems įrankiams (pvz., web_search, code_interpreter"), tačiau tavo funkcijoms tai visada bus ”function”`.

Laukelis name

Tai techninis tavo funkcijos pavadinimas. Jis privalo būti:

  • Unikalus visų užklausoje esančių įrankių atžvilgiu
  • Aprašomasis: naudok get_weather, o ne fn1
  • Rašomas snake_case formatu (pagal susitarimą): search_products, create_ticket
  • Trumpas, bet aiškus: modelis naudoja šį pavadinimą spręsdamas, kurį įrankį iškviesti

Laukelis description

Tai svarbiausias laukelis kvietimų kokybei. Modelis pirmiausia remiasi aprašymu, kad nuspręstų, kada ir kaip naudoti įrankį. Geras aprašymas:

  • Vienu sakiniu paaiškina, ką funkcija daro
  • Nurodo, kada ją naudoti (jei tai nėra akivaizdu)
  • Prireikus paminimi ribiniai atvejai

Palygink šiuos du aprašymus:

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

Antrasis variantas suteikia modeliui pakankamai konteksto, kad jis tiksliai žinotų, kada iškviesti šią funkciją ir ko tikėtis atsakyme.

Blokas parameters

Parametrai turi atitikti JSON Schema formatą. Palaikomi tipai:

  • string – teksto eilutės
  • number / integer – skaičiai
  • boolean – true/false reikšmės
  • array – sąrašai
  • object – įdėtieji objektai
  • enum – leistinų reikšmių sąrašas

Masyvas required išvardija privalomus parametrus. Kiti yra neprivalomi – modelis gali nuspręsti jų nepateikti.

Parametrų aprašymai

Kiekvienas parametras turėtų turėti savo description. Būtent tai leidžia modeliui suprasti, kokią reikšmę perduoti:

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

Be aprašymo modelis turi spėlioti tikėtiną formatą, o tai dažnai lemia klaidas.

Išplėstiniai parametrai

Enum reikšmėms apriboti

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

enum yra ypač naudingas: jis nurodo modeliui tikslias leistinas reikšmes, taip pašalindamas formato klaidas.

Numatytosios reikšmės

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

Modelis supranta, kad šį parametrą gali praleisti, jei tinka numatytoji reikšmė.

Įdėtieji objektai

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

Geriausios aprašymų kūrimo praktikos

Aprašymas yra vienintelis kanalas, kuriuo modelis supranta tavo įrankį – čia svarbus kiekvienas žodis. Pirmenybę teik specifiškumui: frazė „Search for products by name or category in the catalog“ modeliui tiksliai nurodo, kada taikyti šį įrankį, tuo tarpu „Search for products“ palieka jį spėlioti. Toliau – formatai: nurodymas „Date in ISO 8601 format (YYYY-MM-DD)“ parametro aprašyme pašalina pusę argumentų klaidų, nes modelis tiesiog atkartoja parodytą formatą. Ribos yra sutarties dalis: „Maximum 50 results per call“ neleidžia modeliui pažadėti naudotojui išsamumo, kurio įrankis negali suteikti. O grąžinamų duomenų aprašymas – „Returns an object with price, availability, and description“ – padeda modeliui planuoti iš anksto: jis žino, ką turės prieš netgi iškviesdamas funkciją.

Svarbiausi punktai

  • Kiekvienas įrankis apibrėžiamas naudojant name, description ir parameters
  • Aprašymas yra svarbiausias veiksnys kvietimų kokybei – skirk jam laiko
  • Pavadinimai privalo būti unikalūs ir rašomi snake_case formatu
  • Naudok enum, kad apribotum galimas reikšmes
  • Kiekvienas parametras turėtų turėti savo aprašymą su numatomu formatu
  • Masyvas required atskiria privalomus parametrus nuo neprivalomų