메인 콘텐츠로 건너뛰기
guardrail은 OrcaRouter 게이트웨이의 콘텐츠 정책 레이어입니다. 워크스페이스에서 이름이 지정된 정책을 하나 작성하고, API 키에 연결하면, 그 키가 하는 모든 /v1/* 호출이 검사됩니다 — 모델이 프롬프트를 보기 전과 모델이 응답한 후에 — 재배포 없이, SDK 변경 없이. 이 페이지는 Guardrails 섹션의 허브입니다: guardrail이 무엇인지, 규칙 타입, 스테이지와 액션, 그리고 정책이 키에 어떻게 연결되는지. 각 스포크는 더 깊이 파고듭니다. 전체 엔진 레퍼런스는 Guardrails를 참조하세요.

​
1. 게이트웨이에서 AI guardrails가 하는 일

대부분의 팀은 민감한 데이터를 프롬프트에서 차단하거나(PII, 시크릿), 안전하지 않은 콘텐츠를 게이트하거나(탈옥, 프롬프트 인젝션 의도), 컴플라이언스 제어를 충족하기 위해 guardrails를 찾습니다. guardrail은 게이트웨이의 답입니다: 워크스페이스 범위의, 이름이 지정된 정책 — 게이트웨이가 요청 입력과 모델 출력에 대해 실행하는 순서가 있는 규칙 목록입니다. 바인딩이 애플리케이션이 아니라 게이트웨이의 API 키에 존재하기 때문에, guardrail을 편집하면 연결된 모든 키가 다음 호출에서 이동합니다. 당신의 코드는 이전과 정확히 동일하게 /v1/chat/completions를 계속 호출합니다.
guardrails는 콘텐츠 정책입니다(텍스트 입력, 텍스트 출력). 동반자인 Agent Firewall은 툴 정책입니다 — 에이전트가 어떤 툴 호출을 할 수 있는지를 관리합니다. 둘은 결합됩니다; Guardrails vs. firewall을 참조하세요.

​
2. 하나의 구체적인 예

콘솔(/console/guardrails)에서 pii-shield라는 이름의 guardrail을 생성하고, 단일 PII 규칙을 추가합니다 — 스테이지 input, 액션 mask, 엔티티 email, ssn — 그리고 키에 연결합니다. 그 이후로: 
curl https://api.orcarouter.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-orca-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "Reply to jane@acme.com please"}
    ]
  }'
게이트웨이는 전달하기 전에 프롬프트를 Reply to [EMAIL] please로 재작성합니다 — 업스트림 모델은 그 주소를 결코 보지 못합니다. 그 ssn 엔티티를 block으로 전환하면 SSN을 담은 다음 요청은 HTTP 400으로 거부됩니다. 애플리케이션 변경 없음.
작성은 당신의 세션에 대한 콘솔 / 관리 API 액션입니다 — sk-orca-... 릴레이 키는 /v1/* 트래픽 전용이며, 정책 편집에는 결코 쓰이지 않습니다. guardrail을 생성하거나 편집하려면 Developer+ 역할이 필요합니다.

​
3. 규칙: 타입, 스테이지, 액션

모든 규칙은 세 가지 질문에 답합니다. 엔진은 적용 가능한 모든 규칙을 실행하고 그것들을 하나의 결정으로 접습니다.
일곱 가지 규칙 타입. 내장 규칙은 결정적입니다(순수 문자열/정규식, 네트워크 없음); 고급 규칙은 모델 또는 벤더로 외부 호출하며 동시에 실행됩니다.
  • keyword — 리터럴 거부 목록, 대소문자를 구분하지 않는 부분 문자열 매치.
  • regex — RE2 패턴(선형 시간, 역참조 없음).
  • pii — 내장 엔티티 탐지기와 사용자 정의 탐지기. §5 참조.
  • max_chars — 한 스테이지에서 문자 수를 상한 처리합니다.
  • external — 연결된 벤더(Aporia, Averta, 또는 자신의 webhook)에 위임합니다.
  • llm_judge — 워크스페이스의 모델에 대한 의미론적 검사.
  • grounding — 요청에서 검색된 소스(RAG)에 대해 답변 충실도를 채점합니다.
input(요청), output(모델의 응답), 또는 both. 입력 규칙은 업스트림 호출 전에 실행되고; 출력 규칙은 모델이 응답한 후에 실행됩니다. input stage와 output stage를 참조하세요.
규칙 빌더에 다섯 가지 액션이 나타납니다:
  • block — HTTP 400으로 호출을 거부합니다.
  • mask — 매치를 마스킹하고 정화된 텍스트를 통과시킵니다.
  • flag — 트래픽에 대해 아무것도 변경하지 않고; 매치만 기록합니다.
  • annotate — 텍스트는 그대로 두되 업스트림에 보안 메모를 주입합니다 (예: 모델이 응답하기 전에 CVE 권고).
  • spotlight — 매치된 신뢰할 수 없는 텍스트를 구분자로 감싸고 모델에게 그것을 지시가 아니라 데이터로 취급하라고 알립니다.
Actions를 참조하세요. 강제하기 전에 라이브 트래픽에서 규칙을 측정하려면 flag를 사용하세요.

​
4. guardrail이 연결되고 해석되는 방식

guardrail은 guardrail_id를 통해 키에 바인딩되거나, 워크스페이스가 한 guardrail을 기본값으로 표시할 수 있습니다. 임의의 요청에 대해 게이트웨이는 다음 순서로 해석합니다:
  1. 명시적 연결 — 키의 guardrail_id가 존재하고 활성화된 guardrail을 가리키면, 그것이 적용됩니다. 명시적 연결은 결코 폴백하지 않습니다: 그것을 비활성화하는 것이 오프 스위치입니다.
  2. 워크스페이스 기본값 — 키에 연결이 없으면, 활성화된 기본 guardrail이 적용됩니다.
  3. 둘 다 아님 — 강제 없음; 요청은 기능을 한 번도 활성화하지 않은 워크스페이스와 바이트 단위로 동일합니다.
이것은 firewall과 다릅니다. 비활성화된 연결 firewall 정책은 폴백합니다 워크스페이스 기본값으로; 비활성화된 연결 guardrail은 없음으로 갑니다. guardrails에서 오프 스위치는 문자 그대로입니다.
워크스루: 첫 guardrail 생성하기, 키에 연결하기, 계정 기본값 설정하기.

​
5. PII 탐지기

pii 규칙은 닫힌 내장 탐지기 세트를 제공합니다: email, phone, credit_card, ssn, ip, iban, mac_address, jwt, aws_access_key, api_key_openai, bitcoin_address — 그리고 지역별 jp_mynumber, kr_rrn, cn_resident_id. mask 액션에서 각 매치는 타입 지정된 태그가 됩니다 — 이메일은 [EMAIL]로, SSN은 [SSN]으로 렌더링됩니다. 규칙당 최대 25개의 커스텀 엔티티(선택적 Luhn 체크섬이 있는 정규식)를 얹을 수 있고, 엔티티별 오버라이드를 통해 한 규칙 안에서 서로 다른 엔티티를 서로 다른 액션으로 라우팅할 수 있습니다.
턴키 시작점은 PII Shield 프리셋입니다 — 단일 pii 규칙, mask, 스테이지 both. 입력 스테이지 마스킹은 모델 앞에서 요청을 재작성하고 (스트리밍이든 아니든); 출력 마스킹은 비스트리밍 응답에서만 응답을 재작성합니다 — 스트림 내 출력 재작성은 로드맵에 있습니다. PII Shield, 커스텀 엔티티, 그리고 마스킹 형식을 참조하세요.

​
6. 프리셋 선택기

New guardrail은 템플릿으로 열립니다. 프리셋은 서버 측에서 작성되므로, 콘솔, 샌드박스, 그리고 이 문서가 동일한 동작을 기술합니다. 선택기는 그것들을 카테고리로 그룹화합니다:
카테고리예시 프리셋스포크
pii / secretsPII Shield, 시크릿 자격 증명 차단기시크릿 차단
safety프롬프트 인젝션, 탈옥, 자해프롬프트 인젝션
complianceGDPR, PCI, HIPAA, 컴플라이언스 로거컴플라이언스 로거
brand / cost욕설, 경쟁사 언급, 크기 상한브랜드 안전 · 비용
agentURL / 셸 툴 / 출력 내 SQL 필터에이전틱
code_security시크릿 파일 차단, 카피레프트 라이선스 검토코드 보안
프리셋은 씨앗이지 잠금이 아닙니다 — 적용한 뒤 자유롭게 편집하세요. 더 많은 시작점은 템플릿 아래에 있습니다.

​
7. guardrail이 차단할 때

차단된 요청은 오류 코드 guardrail_blocked와 함께 HTTP 400을 반환하며, 발동한 guardrail과 규칙을 명시하는 메시지를 담습니다.
  • 쿼터가 청구되지 않습니다. 입력 스테이지 차단은 계량 전에 발동하고; 출력 스테이지 차단은 사전 소모된 쿼터를 환불합니다.
  • 요청은 skip-retry로 표시됩니다 — 동일한 프롬프트를 다시 실행해도 그저 다시 차단될 뿐이므로, 게이트웨이는 다른 채널에서 재시도를 낭비하지 않습니다.
스트리밍에서 block은 최선 노력으로 강제됩니다 — 스캐너가 작은 룩어헤드를 버퍼링하고 규칙이 발동하면 스트림을 끊으므로, 이미 플러시된 바이트는 회수할 수 없습니다. 출력에 대한 mask는 비스트리밍 응답에만 적용됩니다 — 스트리밍 응답에서는 게이트웨이가 마스크를 계산하지만 마스킹된 텍스트를 전달하지는 않습니다; 스트림 내 출력 재작성은 로드맵에 있습니다. (입력 스테이지 마스킹은 스트리밍과 비스트리밍 모두에서 라이브입니다.) guardrail_blocked 오류와 스트리밍 커버리지를 참조하세요.

​
8. 라이브가 된 후

Matches 피드

발동하는 모든 규칙은 타입, 액션, 스테이지, 상세를 기록합니다. 그룹화, 필터, 내보내기하고 단일 매치로 드릴인합니다.

로깅 및 프라이버시

매치된 부분 문자열은 Log raw content가 켜져 있을 때만 기록됩니다 — 기본적으로 꺼져 있는, 프라이버시 보수적 자세.

버전 관리

모든 변경은 히스토리 행을 씁니다. 임의의 두 버전을 diff하고 새 버전으로 되돌립니다 — 히스토리는 절대 변경되지 않습니다.

테스트 및 평가

샌드박스 Test 탭은 업스트림 호출 없이 현재 정책을 평가하고, 평가 하니스는 번들 또는 커스텀 코퍼스에 대해 그것을 채점합니다.
거짓 양성은 튜닝 신호이지 규칙을 비활성화할 이유가 아닙니다. Matches 피드에서 그것을 표시하고 패턴을 좁히세요 — 거짓 양성 튜닝을 참조하세요.

​
9. 다음으로 갈 곳

Guardrails — 모든 필드, 모든 라우트, LLM-judge와 grounding 규칙, 그리고 외부 벤더를 심층적으로.