Przejdź do głównej treści
Polski— Wybierz język
Menu

Schematy JSON i opisy

Lekcja 2 z 14 Zaktualizowano 29 lipca 2026 Programista
Na tej stronie
  1. Język narzędzi: Schemat JSON
  2. Anatomia definicji narzędzia
  3. Opisy parametrów
  4. Zaawansowane parametry
  5. Najlepsze praktyki dotyczące opisów
  6. Kluczowe wnioski

Język narzędzi: Schemat JSON

Aby Grok mógł wywołać Twoje funkcje, musi wiedzieć, co robią i jakich parametrów oczekują. Tę rolę pełnią schematy JSON. Każde narzędzie jest opisane za pomocą strukturalnego obiektu zawierającego trzy kluczowe elementy: nazwę, opis oraz schemat parametrów.

Anatomia definicji narzędzia

Oto kompletna struktura narzędzia, jakiej oczekuje 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"]
  }
}

Przeanalizujmy każde pole z osobna:

Pole type

Zawsze przyjmuje wartość "function" dla funkcji niestandardowych. Inne typy istnieją dla narzędzi wbudowanych (web_search, code_interpreter), ale w przypadku Twoich własnych funkcji jest to niezmiennie "function".

Pole name

Techniczna nazwa Twojej funkcji. Musi być:

  • Unikalna wśród wszystkich narzędzi w żądaniu
  • Opisowa: get_weather zamiast fn1
  • Zapisana w snake_case zgodnie z konwencją: search_products, create_ticket
  • Krótka, ale jednoznaczna: model używa tej nazwy, aby zdecydować, którego narzędzia użyć

Pole description

To najważniejsze pole wpływające na jakość wywołania. Model polega głównie na opisie, aby zdecydować, kiedy i jak użyć narzędzia. Dobry opis:

  • Wyjaśnia w jednym zdaniu, co robi funkcja
  • Określa, kiedy jej użyć (jeśli nie jest to oczywiste)
  • Wspomina o przypadkach brzegowych, jeśli to konieczne

Porównaj te dwa opisy:

❌ "Pogoda"
✅ "Pobierz aktualną pogodę dla miasta. Zwraca temperaturę, wilgotność i warunki atmosferyczne."

Drugi opis daje modelowi wystarczający kontekst, by wiedzieć dokładnie, kiedy wywołać tę funkcję i czego może się spodziewać w odpowiedzi.

Blok parameters

Parametry遵循 formatu JSON Schema. Obsługiwane typy to:

  • string — ciągi znaków
  • number / integer — liczby
  • boolean — prawda/fałsz
  • array — listy
  • object — zagnieżdżone obiekty
  • enum — lista dozwolonych wartości

Tablica required wymienia parametry obowiązkowe. Pozostałe są opcjonalne — model może zdecydować się na ich pominięcie.

Opisy parametrów

Każdy parametr powinien mieć własny description. To właśnie pozwala modelowi zrozumieć, jaką wartość przekazać:

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

Bez opisu model musi zgadywać oczekiwany format, co prowadzi do błędów.

Zaawansowane parametry

Enumy do ograniczania wartości

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

Enumy są szczególnie przydatne: informują model o dokładnych wartościach, jakich może użyć, eliminując błędy formatu.

Wartości domyślne

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

Model rozumie, że może pominąć ten parametr, jeśli domyślna wartość jest wystarczająca.

Zagnieżdżone obiekty

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

Najlepsze praktyki dotyczące opisów

Opis to jedyny kanał, dzięki któremu model rozumie Twoje narzędzie – każde słowo ma tu znaczenie. Przede wszystkim precyzja: „Wyszukaj produkty po nazwie lub kategorii w katalogu“ mówi modelowi dokładnie, kiedy zastosować to narzędzie, podczas gdy „Wyszukaj produkty“ pozostawia go z domysłami. Następnie formaty: określenie „Data w formacie ISO 8601 (RRRR-MM-DD)“ w opisie parametru eliminuje połowę błędów argumentów, ponieważ model replikuje pokazany mu format. Limity są częścią kontraktu: „Maksymalnie 50 wyników na wywołanie“ zapobiega obiecującemu użytkownikowi kompletności, której narzędzie nie zapewni. A opisanie zwrotu – „Zwraca obiekt z ceną, dostępnością i opisem“ – pomaga modelowi zaplanować działania z wyprzedzeniem: wie, czym będzie dysponował, zanim jeszcze wywoła funkcję.

Kluczowe wnioski

  • Każde narzędzie jest definiowane przez name, description i parameters
  • Opis jest czynnikiem nr 1 wpływającym na jakość wywołania – poświęć mu czas
  • Nazwy muszą być unikalne i zapisane w snake_case
  • Używaj enum, aby ograniczyć możliwe wartości
  • Każdy parametr powinien mieć własny opis z oczekiwanym formatem
  • Tablica required odróżnia parametry obowiązkowe od opcjonalnych