Grok API guidelines 파라미터란? 커스텀 콘텐츠 모더레이션 완벽 가이드

xAI가 Grok 텍스트 API에 guidelines 파라미터를 추가했습니다. 이를 통해 모델이 글을 작성할 때 특정 콘텐츠 카테고리를 추가로 모더레이션하도록 지시할 수 있습니다. Grok 기반으로 개발하면서 민감한 출력에 대한 더 엄격한 제어가 필요하다면, 이것이 xAI가 텍스트용으로 제공하는 최초의 요청 내 콘텐츠 제어 기능입니다. Grok API guidelines 파라미터의 정확한 기능, 적용 카테고리, 설정 방법, 그리고 계획해야 할 요청 제한 및 오류에 대해 자세히 알아보겠습니다.

guidelines 파라미터의 기능

guidelines 파라미터는 Grok 텍스트 API 요청에 추가하는 배열로, 모델이 특정 콘텐츠 카테고리를 처리하는 방식을 변경합니다. 나열한 각 카테고리에 대해 향상된 동작을 선택하면, Grok은 응답을 작성할 때 자체적인 방식으로 guidelines를 따릅니다. 응답의 형태는 일반 응답과 동일하며, 별도로 파싱해야 할 추가 래퍼가 없습니다.

두 가지 중요한 사항이 있습니다:

• 카테고리별 옵트인 방식입니다. 목록에서 제외한 카테고리는 모델의 기본 모더레이션 동작을 유지하므로, 실제로 변경하려는 카테고리만 나열하면 됩니다.
• 요청별로 적용됩니다. Guidelines는 해당 guidelines를 포함한 요청에만 적용됩니다. 전체 대화에 적용하려면 해당 대화의 모든 요청에 guidelines를 포함해야 합니다.

이 기능은 10월에 Grok API 릴리스 노트에 문서화되었으며, xAI의 공지에 따르면 모든 API 고객이 사용할 수 있습니다.

지원되는 카테고리 및 동작

guidelines의 각 항목에는 세 가지 필드가 있습니다: type(항상 "policy"), category, 그리고 원하는 behavior입니다. 현재 유일한 동작은 decline입니다.

문서에서는 이러한 동작을 높은 수준에서 설명하며, xAI가 시간이 지남에 따라 세부 사항을 개선할 수 있다고 명시합니다. 실질적인 핵심은 decline이 오류를 반환하는 엄격한 분류기가 아니라 응답 내에서 부드럽게 방향을 조정하는 방식이라는 점입니다. Grok은 지정한 카테고리 범위 내에서 유지되도록 자체적으로 답변을 재구성합니다.

요청에 guidelines 설정하는 방법

guidelines는 최상위 배열로 전달합니다. Responses API에서는 다른 파라미터와 함께 위치하며, Chat Completions에서는 messages와 동일한 레벨에 위치합니다. 다음은 violence와 nsfw 모두를 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" }
    ]
  }'

자주 혼동되는 SDK 관련 사항:

• OpenAI Python SDK: 해당 필드가 정의되어 있지 않으므로 extra_body를 통해 전달하세요.
• OpenAI JavaScript SDK: 다른 요청 파라미터와 함께 guidelines를 전송하세요.
• xAI Python SDK: chat.create가 채팅에 guidelines를 저장하므로, 모든 sample() 호출 시 자동으로 전송됩니다. 직접 반복할 필요가 없습니다.

지원되는 API와 지원되지 않는 API

guidelines는 Chat Completions, Responses API, xAI Python SDK의 chat.create에서 허용됩니다. 그러나 몇 가지 경우에는 작동하지 않으며, API는 모델 실행 전에 400 오류로 해당 요청을 거부합니다:

• grok-4.20-multi-agent와 같은 멀티 에이전트 모델.
• 지연된 완성(Deferred completions).
• 서버 측 도구와 파일 첨부가 없는 요청에서 stop을 설정하거나 n을 1보다 크게 설정한 경우.

검사가 사전에 이루어지기 때문에 거부된 요청에는 모델 추론 비용이 발생하지 않습니다. 하지만 코드에서 이러한 오류를 처리해야 한다는 점을 의미합니다.

예상되는 오류

API는 모델 실행 전에 guidelines를 검증하며, 적용할 수 없는 경우 오류를 반환합니다:

xAI Python SDK에서는 알 수 없는 카테고리나 동작이 요청 전송 전에 ValueError를 발생시키며, 다른 오류는 gRPC INVALID_ARGUMENT 상태로 반환됩니다.

개발자에게 이것이 중요한 이유

Grok은 역사적으로 더 허용적인 모델로 포지셔닝되어 왔으며, 텍스트 API 호출에는 이전에 요청 내 모더레이션 제어가 없었습니다. 모델의 기본 동작을 그대로 사용하거나 출력을 직접 필터링해야 했습니다. guidelines 파라미터는 중간 경로를 제공합니다. 별도의 모더레이션 호출이나 자체 코드의 임계값 로직 없이 인라인으로 선언하는 카테고리 수준의 조정 기능입니다.

현재는 의도적으로 범위가 좁습니다. 세 가지 카테고리, 하나의 동작(decline), 텍스트 전용입니다. 성적이거나 노골적으로 폭력적인 출력을 허용할 수 없는 고객 대면 챗봇의 경우, nsfw와 violence를 decline으로 선언하는 것이 한 줄짜리 가드레일이 됩니다. 더 엄격하거나 감사 가능한 요구 사항에는 여전히 자체 출력 검사가 필요합니다. decline은 응답을 완전히 차단하는 것이 아니라 재구성하기 때문입니다. 또한 위의 400/422 거부 오류도 여전히 처리해야 합니다.

자체 에이전트로 모더레이션된 AI 워크플로우 구축하기

Grok의 guidelines 파라미터와 같은 콘텐츠 제어는 AI를 프로덕션에서 안전하게 운영하기 위한 한 가지 요소입니다. 더 어려운 부분은 모델의 출력을 실제 작업, 승인, 도구와 연결하는 것입니다. Eigent는 오픈소스 멀티 에이전트 "Cowork" 앱으로, AI 인력을 로컬에서 실행하여 민감한 프롬프트와 데이터를 자신의 머신에 보관하면서 에이전트가 인간 참여 체크포인트와 함께 워크플로우를 처리할 수 있습니다. 이것이 소규모 팀에 어떻게 적합한지 AI 에이전트로 1인 기업 운영하기에서 확인하거나, Eigent를 다운로드하여 직접 체험해 보세요.