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

Ograniczenia i najlepsze praktyki

Lekcja 3 z 14 Zaktualizowano 29 lipca 2026 Programista
Na tej stronie
  1. Ograniczenia techniczne wywoływania funkcji
  2. Maksymalnie 200 narzędzi na żądanie
  3. Model nie gwarantuje poprawności argumentów
  4. Obsługa błędów
  5. Unikalne i jednoznaczne nazwy
  6. Opisy: czynnik jakości nr 1
  7. Optymalizacja liczby narzędzi
  8. Bezpieczeństwo: nigdy nie ufaj modelowi
  9. Kluczowe wnioski

Ograniczenia techniczne wywoływania funkcji

Zanim przejdziesz do implementacji, musisz zrozumieć ograniczenia systemu. Wywoływanie funkcji w modelu Grok jest potężne, ale działa w ramach określonych ograniczeń, które musisz opanować, aby budować niezawodne aplikacje.

Maksymalnie 200 narzędzi na żądanie

API Grok akceptuje do 200 definicji narzędzi w pojedynczym żądaniu. Limit ten jest hojny – większość aplikacji korzysta tylko z 5 do 20 narzędzi. Jeśli jednak budujesz skalowalny system (wtyczki, rynek narzędzi), musisz to uwzględnić.

Każda definicja narzędzia zajmuje miejsce w oknie kontekstowym. Konkretne wartości wyglądają następująco:

  • Proste narzędzie (2-3 parametry) zużywa około 50-100 tokenów
  • Złożone narzędzie (10+ parametrów, szczegółowe opisy) może przekroczyć 300 tokenów
  • 200 złożonych narzędzi = 60 000 tokenów wyłącznie na definicje

Dlatego musisz działać strategicznie: deklaruj tylko narzędzia istotne dla bieżącego żądania.

Model nie gwarantuje poprawności argumentów

Grok stara się generować argumenty zgodne ze schematem, ale nie jest nieomylny. Model może:

  • Wygenerować nieprawidłowy format daty
  • Przekazać string, gdy oczekiwany jest integer
  • Pominąć wymagane pole w rzadkich przypadkach
  • Halucynować wartości enum, które nie istnieją

Twój kod po stronie klienta musi zawsze walidować otrzymane argumenty przed wykonaniem funkcji.

import json

def handle_tool_call(tool_call):
    args = json.loads(tool_call.function.arguments)

    # Walidacja przed wykonaniem
    if "city" not in args:
        return {"error": "Parametr city jest wymagany"}

    if not isinstance(args["city"], str):
        return {"error": "city musi być ciągiem znaków"}

    return get_weather(args["city"], args.get("unit", "celsius"))

Obsługa błędów

Gdy funkcja zakończy się niepowodzeniem, musisz zwrócić błąd do modelu, zamiast cicho przerywać działanie. Model może wtedy:

  • Przeformułować swoje żądanie z poprawionymi parametrami
  • Poinformować użytkownika o problemie
  • Spróbować użyć alternatywnego narzędzia
try:
    result = search_database(query=args["query"])
    return json.dumps(result)
except ConnectionError:
    return json.dumps({
        "error": "Baza danych niedostępna",
        "suggestion": "Spróbuj ponownie za kilka sekund"
    })

Zawsze zwracaj ustrukturyzowany JSON, nawet w przypadku błędu. Model rozumie komunikaty o błędach i odpowiednio dostosowuje swoją odpowiedź.

Unikalne i jednoznaczne nazwy

Nazwy funkcji muszą być unikalne na liście narzędzi. Jeśli dwa narzędzia mają tę samą nazwę, zachowanie jest niezdefiniowane – API może odrzucić żądanie lub zignorować jedno z nich.

Przyjmij spójną konwencję nazewnictwa:

✅ Najlepsze praktyki:
   get_weather          → pobieranie danych
   search_products      → wyszukiwanie
   create_ticket        → tworzenie
   update_order_status  → aktualizacja
   delete_draft         → usuwanie

❌ Unikaj:
   fn1, fn2             → niezrozumiałe
   doStuff              → zbyt ogólne
   getWeatherData       → camelCase (preferuj snake_case)

Opisy: czynnik jakości nr 1

Jakość opisów bezpośrednio wpływa na niezawodność wywoływania funkcji. Oto tabela porównawcza:

Słaby opis Skuteczny opis
"Szukaj" "Wyszukaj produkty po nazwie, kategorii lub zakresie cen w katalogu e-commerce"
"Wyślij wiadomość" "Wyślij e-mail do odbiorcy. Wymaga tematu i treści wiadomości. Nie obsługuje załączników."
"Oblicz" "Oblicz całkowitą cenę wraz z podatkiem na podstawie ceny netto i stawki VAT. Zwraca kwotę w euro z dokładnością do 2 miejsc po przecinku."

Optymalizacja liczby narzędzi

Zamiast deklarować 200 narzędzi w każdym żądaniu, dynamicznie wybieraj te, które mają rzeczywiste znaczenie. Pierwszym filtrem jest kontekst: jeśli użytkownik rozmawia o pogodzie, ładowanie narzędzi rozliczeniowych tylko wprowadza szum – wystarczy lekkie routowanie wstępne (po słowach kluczowych lub pierwsze wywołanie klasyfikujące), aby przedstawić tylko odpowiednią rodzinę narzędzi. Drugim filtrem jest rola: agent wsparcia nie potrzebuje narzędzi administracyjnych, a ich usunięcie to kwestia zarówno precyzji, jak i bezpieczeństwa. Trzecim czynnikiem jest etap: w wieloetapowym przepływie pracy każda faza ma swoje własne narzędzia – ładowanie ich w miarę postępu utrzymuje skupienie modelu na tym, co musi zrobić teraz.

Korzyści są podwójne i natychmiastowe: mniej tokenów wejściowych na żądanie (definicje narzędzi kosztują przy każdym wywołaniu) oraz lepsza dokładność wyboru – model wybierający spośród sześciu dobrze opisanych narzędzi rzadko popełnia błędy, podczas gdy ten sam model面对jący się z dwustoma definicjami zaczyna mylić podobne warianty.

Bezpieczeństwo: nigdy nie ufaj modelowi

Wywoływanie funkcji to potencjalny wektor ataku typu injection. Złośliwy użytkownik może sformułować swoje żądanie tak, aby manipulować argumentami przekazywanymi do funkcji. Zasady bezpieczeństwa:

  • Waliduj wszystkie argumenty po stronie serwera
  • Ogranicz uprawnienia: funkcja tylko do odczytu nie powinna móc zapisywać danych
  • Loguj wywołania: śledź każde wywołanie funkcji w celach audytowych
  • Sanityzuj dane wejściowe: escapuj znaki specjalne przed zapytaniami SQL/powłoki

Kluczowe wnioski

  • Maksymalnie 200 narzędzi na żądanie – ale celuj w 5-20 dla efektywności
  • Zawsze waliduj argumenty po stronie klienta przed wykonaniem
  • Zwracaj błędy do modelu w ustrukturyzowanym formacie JSON
  • Nazwy muszą być unikalne, stosować snake_case i być jednoznaczne
  • Szczegółowe opisy drastycznie poprawiają niezawodność
  • Dynamicznie wybieraj odpowiednie narzędzia dla każdego żądania
  • Nigdy nie ufaj argumentom bez walidacji