메인 콘텐츠로 건너뛰기
내장 pii 탐지기는 흔한 엔티티를 다룹니다 — 이메일, 전화, 신용카드, SSN, IBAN, JWT, 클라우드 키. 하지만 당신의 민감한 데이터는 당신의 것입니다: 직원 ID, 내부 사건 번호, 고객 계정 참조, 파트너의 주문 형식. 커스텀 PII 엔티티는 동일한 마스킹 규칙에게 그 형태를 인식하도록 가르쳐, 게이트웨이가 모델 — 또는 어떤 다운스트림 툴 — 이 그것을 보기 전에 마스킹하게 합니다. 이 페이지는 커스텀 엔티티가 PII detection 규칙에 더하는 한 가지를 다룹니다: 자신의 탐지기. 전체 엔진 — 모든 규칙 타입, 스테이지, 라우트 — 은 Guardrails 레퍼런스를 참조하세요.
여기 모든 단계는 호스팅된 게이트웨이(api.orcarouter.ai)에 대한 콘솔 액션입니다. 당신의 세션에서 guardrail을 작성하며; 최종 /v1/* 호출만 sk-orca-... 릴레이 키를 사용합니다. guardrail을 생성하고 편집하려면 워크스페이스에서 **Developer+**가 필요합니다.

​
1. 커스텀 PII 탐지기 LLM guardrail이 필요할 때

내장 엔티티 세트는 닫혀 있으며 엔진, 검증기, 규칙 빌더 전반에서 공유됩니다. 표준 식별자에는 올바른 도구입니다. 마스킹하려는 데이터가 어떤 내장도 다루지 않는 예측 가능한 형태를 가질 때 커스텀 엔티티를 찾으세요:

내부 식별자

직원 ID(EMP482915), 사건 번호, 티켓 참조, 내부 SKU — 고정 접두사와 숫자 런이 있는 모든 것.

계정 및 주문 번호

제3자 모델에 그대로 도달해서는 안 되는 고객 계정 참조나 파트너의 주문 형식.

체크섬 번호

Luhn 검사를 통과하는 카드 유사 또는 멤버십 번호 — 비슷해 보이는 숫자 런의 거짓 양성을 줄이려면 체크섬을 추가하세요.

도메인별 코드

증권 번호, 청구 ID, 디바이스 시리얼 — 당신의 산업이 민감하게 취급하지만 일반 탐지기는 모르는 모든 토큰.
커스텀 엔티티는 하나의 pii 규칙 내부에서 내장 세트 위에 얹힙니다. 매치를 탐지하고 규칙의 액션 — mask, block, 또는 flag — 을 내장 엔티티와 정확히 동일하게 적용합니다.

​
2. 커스텀 엔티티의 해부

커스텀 엔티티는 세 개의 작은 필드와 선택적 마스크 태그입니다. Custom entities 아래 pii 규칙 에디터에서 추가합니다:
필드필수무엇을 하는가
nameyes안정적인 ID, 예: employee_id. 소문자 ASCII / 숫자 / _, 반드시 문자로 시작. Matches 피드와 감사 로그로 흐릅니다.
patternyesGo RE2 정규식(선형 시간, 역참조 없음). 반드시 컴파일되어야 함.
checksumnoluhn은 Luhn 알고리즘으로 각 매치를 검증합니다. ""(없음) 또는 "luhn"만 허용됩니다.
mask_withnomask 액션에서의 그대로의 대체 문자열. 기본값은 [<UPPERCASE_NAME>].
name은 게이트웨이의 나머지와 동일한 키 컨벤션을 따릅니다 — 소문자, 문자로 시작, 공백이나 하이픈 없음. 명확한 것을 선택하세요(case_number, partner_order_id); 규칙이 발동할 때 Matches 피드에서 보게 될 것입니다.

​
선택적 Luhn 체크섬

많은 “숫자 형태” 식별자 — 결제 카드, 일부 멤버십 및 계정 번호 — 는 Luhn(mod-10) 체크 디지트를 운반합니다. \d{16} 같은 단순 정규식은 전화번호, 타임스탬프, 주문 합계를 포함하여 모든 16자리 숫자 런을 매치합니다. checksum: "luhn"을 설정하면 탐지기가 매치된 숫자가 Luhn 검사도 통과할 때 만 발동하므로, 비슷해 보이는 런이 깔끔하게 빠져나가고 당신의 거짓 양성 비율이 낮게 유지됩니다. 직원 ID 같은 체크섬이 없는 토큰에는 비워두세요.

​
자신의 마스크 태그

mask 액션에서, 내장 이메일은 [EMAIL]로 렌더링됩니다. 커스텀 엔티티는 기본적으로 [<UPPERCASE_NAME>]로 렌더링됩니다 — employee_id 매치는 [EMPLOYEE_ID]가 됩니다. 모델이 받는 텍스트에 특정 대체 토큰을 원할 때 mask_with를 설정하여 그것을 그대로 오버라이드하세요(예: <id> 또는 ***). 엔티티 타입 전반의 렌더링 규칙은 마스킹 형식을 참조하세요.

​
3. 하나의 구체적인 예

당신의 프롬프트가 EMP 뒤에 여섯 자리 숫자가 오는 형식으로 직원 ID를 운반하고, 업스트림 모델이 실제 ID를 결코 보지 않도록 그것을 입력 스테이지에서 마스킹하고 싶다고 합시다. pii 규칙에 단일 커스텀 엔티티를 추가합니다: 
{
  "type": "pii",
  "stage": "input",
  "action": "mask",
  "entities": ["email"],
  "custom_entities": [
    {
      "name": "employee_id",
      "pattern": "EMP\\d{6}",
      "mask_with": "[EMPLOYEE_ID]"
    }
  ]
}
그 규칙은 동일한 패스에서 표준 이메일 그리고 당신의 직원 ID를 모두 마스킹합니다. 키를 연결하기 전에 Test 탭에서 테스트하세요: 
Forward EMP482915's note to jane@acme.com

Forward [EMPLOYEE_ID]'s note to [EMAIL]
업스트림으로 아무것도 보내지 않고 아무것도 계량되지 않습니다. 그 다음 guardrail을 키에 연결하고 (키에 연결하기 참조) 이전과 정확히 동일하게 /v1/chat/completions를 호출합니다 — 게이트웨이는 SDK 변경 없이 전달하기 전에 요청을 마스킹합니다.
마스킹은 양쪽 스테이지에서 실행됩니다: 입력 규칙은 모델이 보기 전에 요청을 마스킹하고, 출력 규칙은 모델의 응답을 마스킹합니다 — 스캐너가 인밴드로 매치를 재작성하는 스트리밍 응답을 포함하여. block 액션도 양쪽 스테이지에서 강제됩니다. 모델 응답을 게이트하려면, 출력 스테이지 규칙을 참조하세요.

​
체크섬 예시

카드 유사 멤버십 번호의 경우, 유효하지 않은 번호인 16자리 런이 매치되지 않도록 Luhn 검사를 추가하세요: 
{
  "name": "member_card",
  "pattern": "\\d{16}",
  "checksum": "luhn",
  "mask_with": "[MEMBER_CARD]"
}

​
4. 제한 및 검증

규칙 빌더는 저장 시 모든 커스텀 엔티티를 검증합니다 — 나쁜 탐지기는 결코 핫 경로에 도달하지 않습니다.
각 커스텀 엔티티는 전체 텍스트에 대한 정규식 스캔이므로, 규칙당 상한은 25입니다. 상한이 핫 경로를 선형으로 유지합니다; 컴파일된 패턴은 요청 전반에서 캐시됩니다. 더 많은 형태가 필요한가요? 동일한 guardrail의 여러 pii 규칙에 걸쳐 분할하세요.
pattern은 Go RE2 정규식입니다 — 선형 시간, 역참조 없음. 검증기는 컴파일되지 않는 패턴을 거부하며, 오류에 문제의 엔티티를 명시합니다.
""(검사 없음)과 "luhn"만 허용됩니다. 그 외 모든 것 — "sha256", "mod10", 심지어 "LUHN" — 은 저장 시 거부됩니다.
name은 반드시 문자로 시작하고 소문자 ASCII, 숫자, 밑줄만 사용해야 합니다. 한 규칙의 두 커스텀 엔티티는 이름을 공유할 수 없습니다.

​
5. 엔티티별 액션 오버라이드

커스텀 엔티티는 내장 엔티티와 동일한 entity_actions 맵에 참여합니다. 하나의 pii 규칙은 대부분을 마스킹하되 고민감도 커스텀 탐지기에서는 차단할 수 있습니다 — 엔티티를 그 name으로 참조하세요: 
{
  "type": "pii",
  "stage": "input",
  "action": "mask",
  "entities": ["email", "phone"],
  "custom_entities": [
    { "name": "ssn_internal", "pattern": "ID-\\d{9}", "checksum": "luhn" }
  ],
  "entity_actions": {
    "ssn_internal": "block"
  }
}
entity_actions의 키는 규칙에서 활성화된 내장 엔티티나 커스텀 엔티티의 name을 참조해야 하며; 값은 block, mask, flag, 또는 annotate여야 합니다. 검증기는 그 외 모든 것을 거부합니다.

​
6. 다음으로 갈 곳

PII Shield

커스텀 엔티티가 얹히는 단일 마스킹 규칙 — 내장 탐지기 세트와 타입 지정된 마스크 태그.

마스킹 형식

각 엔티티가 mask 액션에서 어떻게 렌더링되는지, 그리고 mask_with가 그것을 어떻게 오버라이드하는지.

정규식 탐지기

타입 지정된 PII 엔티티보다 단순 regex 규칙이 더 잘 맞을 때.

거짓 양성 튜닝

Matches 피드와 체크섬을 사용하여 정밀도를 맞춥니다.
완전한 PII 규칙 — 모든 필드, 평가 하니스, 그리고 전체 API — 은 Guardrails 레퍼런스를 읽거나, 엔드투엔드 루프를 처음부터 따라가려면 첫 guardrail 생성하기를 읽으세요.