Ograniczenia i najlepsze praktyki
Na tej stronie
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 jestinteger - 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