가드레일 공급자: Gray Swan Cygnal Guardrail

가드레일 공급자: Gray Swan Cygnal Guardrail

Gray Swan Cygnal을 사용해 정책 위반, 간접 프롬프트 인젝션(IPI), 젤브레이크 시도, 기타 안전 위험에 대해 대화를 지속적으로 모니터링해요.

출처: 문서

본문

Cygnal은 0과 1 사이의 위반 점수(높을수록 정책을 위반할 가능성이 높음)와 위반된 규칙 인덱스, 돌연변이 감지, IPI 플래그 같은 메타데이터를 반환해요. LiteLLM은 이 신호에 따라 요청을 자동으로 차단하거나 모니터링할 수 있어요.

빠른 시작 (Quick Start)

1. 자격 증명 얻기

Gray Swan 플랫폼에 로그인하고 Cygnal API 키를 생성하세요.

기존 고객이라면 플랫폼에 이미 액세스할 수 있을 거예요. 신규 사용자는 이 페이지에서 등록하면 온보딩을 기꺼이 제공할게요.

LiteLLM 프록시 호스트용 환경 변수를 구성하세요:

export GRAYSWAN_API_KEY="your-grayswan-key"
export GRAYSWAN_API_BASE="https://api.grayswan.ai"

2. config.yaml 구성

Gray Swan 통합을 참조하는 가드레일 항목을 추가하세요. 아래는 권장 설정이에요.

model_list:                                 # this part is a standard litellm configuration for reference
  - model_name: openai/gpt-5.6-luna
    litellm_params:
      model: openai/gpt-5.6-luna
      api_key: os.environ/OPENAI_API_KEY
guardrails:
  - guardrail_name: "cygnal-monitor"
    litellm_params:
      guardrail: grayswan
      mode: [pre_call, post_call]            # monitor both input and output
      api_key: os.environ/GRAYSWAN_API_KEY
      api_base: os.environ/GRAYSWAN_API_BASE  # optional
      optional_params:
        on_flagged_action: passthrough         # or "block" or "monitor"
        violation_threshold: 0.5               # score >= threshold is flagged
        reasoning_mode: hybrid                 # off | hybrid | thinking
        policy_id: "your-cygnal-policy-id"     # Optional: Your Cygnal policy ID. Defaults to a content safety policy if empty.
      streaming_end_of_stream_only: true       # For streaming API, only send the assembled message to Cygnal (post_call only). Defaults to false.
      default_on: true
      guardrail_timeout: 30                   # Defaults to 30 seconds. Change accordingly.
      fail_open: true                         # Defaults to true; set to false to propagate guardrail errors.
general_settings:
  master_key: "your-litellm-master-key"
litellm_settings:
  set_verbose: true

3. 프록시 실행

litellm --config config.yaml --port 4000

가드레일 모드 선택 (Choosing Guardrail Modes)

Gray Swan은 pre_call, during_call, post_call 단계에서 실행할 수 있어요. 지연과 커버리지 요구사항에 따라 모드를 결합하세요.

on_flagged_action: block 또는 on_flagged_action: passthrough와 함께 during_call을 사용할 때:

• LLM 호출이 asyncio.gather로 가드레일 검사와 병행 실행돼요
• 가드레일이 위반을 감지해도 LLM 토큰은 여전히 소비돼요
• 가드레일 예외가 응답이 사용자에게 도달하는 것을 막지만, 실행 중인 LLM 작업은 취소하지 않아요
• 이는 사용자에게 오류/패스스루 메시지를 반환하면서 전체 LLM 비용을 지불한다는 뜻이에요

권장사항: passthrough(또는 block) on_flagged_action에는 during_call 대신 pre_call과 post_call을 사용하세요 (위 권장 구성 참고). during_call은 작동 경험에 영향을 주지 않는 저지연 로깅을 원할 때 모니터 모드에만 예약하세요.

Claude Code와 함께 사용 (Work with Claude Code)

litellm으로 Claude Code를 설정하는 공식 litellm 가이드를 따르고, 위에서 언급한 가드레일 부분을 litellm 구성에 추가하세요. Cygnal은 코딩 에이전트 정책 방어를 기본 지원해요. 플랫폼에서 자체 정책을 정의하거나 제공된 코딩 정책을 사용하세요. 위 예시 구성은(정책_id를 적절한 것으로 교체) Claude Code에도 권장되는 설정이에요.

extra_body로 요청별 재정의 (Per-request overrides via extra_body)

litellm_metadata.guardrails[*].grayswan.extra_body를 전달해 Gray Swan 가드레일 구성의 일부를 요청별로 재정의할 수 있어요.

extra_body는 Cygnal 요청 본문에 병합되며, config.yaml의 특정 필드(policy_id, violation_threshold, reasoning_mode)보다 우선해요.

extra_body 안에 metadata 필드를 포함하면 요청 본문의 metadata 필드 아래에 그대로 Cygnal API로 전달돼요.

예시:

curl -X POST "http://0.0.0.0:4000/v1/messages?beta=true" \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openrouter/anthropic/claude-sonnet-5",
    "messages": [{"role": "user", "content": "hello"}],
    "litellm_metadata": {
      "guardrails": [
        {
          "cygnal-monitor": {
            "extra_body": {
              "policy_id": "specific policy id you want to use",
              "metadata": {
                "user": "health-check"
              }
            }
          }
        }
      ]
    }
  }'

OpenAI 클라이언트:

from openai import OpenAI
client = OpenAI(api_key="anything", base_url="http://0.0.0.0:4000")
resp = client.responses.create(
    model="openrouter/anthropic/claude-sonnet-5",
    input="hello",
    extra_body={
        "litellm_metadata": {
            "guardrails": [
                {
                    "cygnal-monitor": {
                        "extra_body": {
                            "policy_id": "69038214e5cdb6befc5e991e",
                            "metadata": {"trace_id": "trace-123"},
                        }
                    }
                }
            ]
        }
    },
)

Anthropic 클라이언트:

from anthropic import Anthropic
client = Anthropic(api_key="anything", base_url="http://0.0.0.0:4000")
resp = client.messages.create(
    model="openrouter/anthropic/claude-sonnet-5",
    max_tokens=256,
    messages=[{"role": "user", "content": "hello"}],
    extra_body={
        "litellm_metadata": {
            "guardrails": [
                {
                    "cygnal-monitor": {
                        "extra_body": {
                            "policy_id": "69038214e5cdb6befc5e991e",
                            "metadata": {"trace_id": "trace-123"},
                        }
                    }
                }
            ]
        }
    },
)

참고 사항 (Notes):

• 가드레일 이름(예: cygnal-monitor)은 config.yaml의 guardrail_name과 일치해야 해요.
• 요청별 가드레일 재정의는 프록시 설정에 따라 프리미엄 라이선스가 필요할 수 있어요.

구성 참조 (Configuration Reference)