Salt la conținutul principal
Română— Alege o limbă
Meniu

Schemele JSON și descrierile

Lecția 2 din 14 Actualizată 29 iulie 2026 Dezvoltator
Pe această pagină
  1. Limbajul instrumentelor: Schema JSON
  2. Anatomia unei definiții de instrument
  3. Descrierile parametrilor
  4. Parametri avansați
  5. Cele mai bune practici pentru descrieri
  6. Puncte cheie

Limbajul instrumentelor: Schema JSON

Pentru ca Grok să vă poată apela funcțiile, trebuie să știe ce fac acestea și ce parametri așteaptă. Acesta este rolul schemelor JSON. Fiecare instrument este descris printr-un obiect structurat care conține trei elemente esențiale: un nume, o descriere și o schemă de parametri.

Anatomia unei definiții de instrument

Iată structura completă a unui instrument așa cum o așteaptă API-ul 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"]
  }
}

Să analizăm fiecare câmp:

Câmpul type

Este întotdeauna "function" pentru funcțiile personalizate. Există alte tipuri pentru instrumentele integrate (web_search, code_interpreter), dar pentru propriile dumneavoastră funcții, valoarea este invariabil "function".

Câmpul name

Numele tehnic al funcției dumneavoastră. Acesta trebuie să fie:

  • Unic printre toate instrumentele din cerere
  • Descriptiv: get_weather în loc de fn1
  • În format snake_case conform convenției: search_products, create_ticket
  • Scurt, dar explicit: modelul folosește acest nume pentru a decide ce instrument să apeleze

Câmpul description

Acesta este cel mai important câmp pentru calitatea apelurilor. Modelul se bazează în primul rând pe descriere pentru a decide când și cum să utilizeze un instrument. O descriere bună:

  • Explică ce face funcția într-o singură propoziție
  • Specifică când să o utilizați (dacă nu este evident)
  • Menționează cazurile limită, dacă este necesar

Comparați aceste două descrieri:

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

A doua variantă oferă modelului suficient context pentru a ști exact când să apeleze această funcție și ce va primi în schimb.

Blocul parameters

Parametrii urmează formatul JSON Schema. Tipurile suportate includ:

  • string — șiruri de caractere
  • number / integer — numere
  • boolean — adevărat/fals
  • array — liste
  • object — obiecte imbricate
  • enum — listă de valori permise

Array-ul required listează parametrii obligatorii. Ceilalți sunt opționali — modelul poate alege să îi omită.

Descrierile parametrilor

Fiecare parametru ar trebui să aibă propria sa description. Acest lucru permite modelului să înțeleagă ce valoare să transmită:

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

Fără o descriere, modelul trebuie să ghicească formatul așteptat, ceea ce duce la erori.

Parametri avansați

Enumerări pentru constrângerea valorilor

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

Enumerările sunt deosebit de utile: ele indică modelului valorile exacte pe care le poate utiliza, eliminând erorile de format.

Valori implicite

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

Modelul înțelege că poate omite acest parametru dacă valoarea implicită este adecvată.

Obiecte imbricate

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

Cele mai bune practici pentru descrieri

Descrierea este singurul canal prin care modelul înțelege instrumentul dumneavoastră — fiecare cuvânt contează. Prioritizați specificitatea: „Caută produse după nume sau categorie în catalog“ îi spune modelului exact când se aplică acest instrument, în timp ce „Caută produse“ îl lasă să ghicească. Urmează formatele: specificarea „Dată în format ISO 8601 (YYYY-MM-DD)“ într-o descriere de parametru elimină jumătate din erorile de argumente, deoarece modelul replică formatul pe care i-l arătați. Limitele fac parte din contract: „Maximum 50 de rezultate per apel“ împiedică modelul să promită utilizatorului o exhaustivitate pe care instrumentul nu o poate oferi. Iar descrierea returnării — „Returnează un obiect cu preț, disponibilitate și descriere“ — ajută modelul să planifice dinainte: știe ce va avea la dispoziție chiar înainte de a face apelul.

Puncte cheie

  • Fiecare instrument este definit printr-un name, o description și parameters
  • Descrierea este factorul nr. 1 pentru calitatea apelurilor — investiți timp în ea
  • Numele trebuie să fie unice și în format snake_case
  • Utilizați enum pentru a constrânge valorile posibile
  • Fiecare parametru ar trebui să aibă propria descriere cu formatul așteptat
  • Array-ul required distinge parametrii obligatorii de cei opționali