Czym jest parametr guidelines w Grok API? Niestandardowa moderacja treści, wyjaśniona

xAI dodało parametr guidelines do tekstowego API Grok, umożliwiając wskazanie modelowi, aby bardziej rygorystycznie moderował określone kategorie treści podczas generowania odpowiedzi. Jeśli budujesz na Grok i potrzebujesz ściślejszej kontroli nad wrażliwymi wynikami, jest to pierwsza kontrola treści w żądaniu, jaką xAI udostępnia dla tekstu. Oto dokładnie, co robi parametr guidelines w Grok API, jakie kategorie obejmuje, jak go ustawić oraz jakich limitów żądań i błędów należy się spodziewać.

Co robi parametr guidelines

Parametr guidelines to tablica, którą dodajesz do żądania tekstowego API Grok, aby zmienić sposób obsługi przez model określonych kategorii treści. Dla każdej wymienionej kategorii wybierasz rozszerzone zachowanie; Grok następnie stosuje wytyczne podczas pisania odpowiedzi, własnymi słowami. Odpowiedź ma taki sam kształt jak normalna odpowiedź — nie ma żadnego dodatkowego opakowania do parsowania.

Dwie rzeczy są tu istotne:

• Opt-in per kategorię. Każda kategoria, którą pominiesz, zachowuje domyślne zachowanie moderacji modelu, więc wymieniasz tylko te kategorie, które faktycznie chcesz zmienić.
• Per żądanie. Wytyczne obowiązują tylko dla żądania, które je zawiera. Aby objąć nimi całą rozmowę, wysyłasz je przy każdym żądaniu w tej rozmowie.

Funkcja została udokumentowana w notatkach o wydaniu Grok API w październiku i zgodnie z ogłoszeniem xAI jest dostępna dla wszystkich klientów API.

Które kategorie i zachowania są obsługiwane

Każdy wpis w guidelines ma trzy pola: type (zawsze "policy"), category oraz behavior, który chcesz dla niej ustawić. Obecnie jedynym zachowaniem jest decline.

Dokumentacja opisuje te zachowania na wysokim poziomie i zaznacza, że xAI może z czasem doprecyzować szczegóły. Praktyczny wniosek: decline to łagodniejsze sterowanie w odpowiedzi, a nie twardy klasyfikator zwracający błąd — Grok przekształca własną odpowiedź, aby pozostać w granicach wskazanej kategorii.

Jak ustawić guidelines w żądaniu

Przekazujesz guidelines jako tablicę najwyższego poziomu. W Responses API znajduje się obok innych parametrów; w Chat Completions trafia na ten sam poziom co messages. Oto żądanie ustawiające zarówno violence, jak i nsfw na decline:

curl https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.7",
    "input": "Write a short story about a knight.",
    "guidelines": [
      { "type": "policy", "category": "violence", "behavior": "decline" },
      { "type": "policy", "category": "nsfw", "behavior": "decline" }
    ]
  }'

Uwagi dotyczące SDK, które często sprawiają problemy:

• OpenAI Python SDK: pole nie jest zdefiniowane, więc przekaż je przez extra_body.
• OpenAI JavaScript SDK: wyślij guidelines razem z innymi parametrami żądania.
• xAI Python SDK: chat.create przechowuje wytyczne w czacie, więc każde wywołanie sample() wysyła je automatycznie — nie musisz ich powtarzać samodzielnie.

Które API to obsługują — a które nie

guidelines jest akceptowane w Chat Completions, Responses API oraz chat.create w xAI Python SDK. Nie działa w kilku przypadkach, a API odrzuca te żądania z błędem 400 przed uruchomieniem modelu:

• Modele wieloagentowe, takie jak grok-4.20-multi-agent.
• Odroczone uzupełnienia (deferred completions).
• Żądanie bez narzędzi po stronie serwera i bez załączników plików, które jednocześnie ustawia stop lub ustawia n większe niż 1.

Ponieważ sprawdzenie odbywa się z góry, odrzucone żądanie nie kosztuje Cię żadnego wnioskowania modelu — ale oznacza to, że musisz obsługiwać te błędy w kodzie.

Błędy, których należy się spodziewać

API waliduje guidelines przed uruchomieniem modelu i zwraca błąd, jeśli nie może ich zastosować:

W xAI Python SDK nieznana kategoria lub zachowanie zgłasza ValueError jeszcze przed wysłaniem żądania; pozostałe błędy wracają jako status gRPC INVALID_ARGUMENT.

Dlaczego ma to znaczenie dla deweloperów

Grok był historycznie pozycjonowany jako bardziej permisywny model, a wywołania tekstowego API wcześniej nie miały żadnych kontroli moderacji w żądaniu — korzystałeś z domyślnego zachowania modelu lub filtrowałeś wyniki samodzielnie. Parametr guidelines to środkowa droga: sterowanie na poziomie kategorii deklarowane inline, bez osobnego wywołania moderacji i bez logiki progowej we własnym kodzie.

Jest celowo wąski w tej chwili — trzy kategorie, jedno zachowanie (decline), tylko tekst. W przypadku chatbota skierowanego do klientów, gdzie nie możesz ryzykować zseksualizowanych lub drastycznie brutalnych wyników, zadeklarowanie nsfw i violence jako decline to jednolinijkowe zabezpieczenie. W przypadku czegokolwiek bardziej rygorystycznego lub wymagającego audytu nadal będziesz chciał własnych kontroli wyników, ponieważ decline przekształca odpowiedź zamiast ją twardo blokować — i nadal powinieneś obsługiwać odrzucenia 400/422 opisane powyżej.

Buduj moderowane przepływy pracy AI z własnymi agentami

Kontrole treści, takie jak parametr guidelines Grok, to jeden element bezpiecznego uruchamiania AI w środowisku produkcyjnym — trudniejszą częścią jest podłączenie wyników modelu do rzeczywistych zadań, zatwierdzeń i narzędzi. Eigent to open-source'owa aplikacja wieloagentowa „Cowork", która uruchamia siłę roboczą AI lokalnie, dzięki czemu możesz przechowywać wrażliwe prompty i dane na własnym komputerze, podczas gdy agenty obsługują przepływ pracy z punktami kontrolnymi z udziałem człowieka. Zobacz, jak to pasuje do szczupłego zespołu w artykule prowadzenie jednoosobowej firmy z agentami AI lub pobierz Eigent, aby to wypróbować.