---
title: 트레이스용 PII 삭제
description: "크루 및 플로우 실행 트레이스에서 민감한 데이터를 자동으로 삭제합니다"
icon: "lock"
mode: "wide"
---

## 개요

PII 삭제는 크루 및 플로우 실행 트레이스에서 개인 식별 정보(PII)를 자동으로 감지하고 마스킹하는 CrewAI AMP 기능입니다. 이를 통해 신용카드 번호, 주민등록번호, 이메일 주소, 이름과 같은 민감한 데이터가 CrewAI AMP 트레이스에 노출되지 않도록 보장합니다. 또한 조직별 데이터를 보호하기 위해 커스텀 인식기를 생성할 수 있습니다.


<Info>
  PII 삭제는 Enterprise 플랜에서 사용 가능합니다.
  배포 버전은 1.8.0 이상이어야 합니다.
</Info>


<Frame>
  ![PII 삭제 개요](/images/enterprise/pii_mask_recognizer_trace_example.png)
</Frame>


## PII 삭제가 중요한 이유

프로덕션 환경에서 AI 에이전트를 실행할 때, 민감한 정보가 종종 크루를 통해 흐릅니다:

- CRM 통합의 고객 데이터
- 결제 처리업체의 금융 정보
- 양식 제출의 개인 정보
- 내부 직원 데이터

적절한 삭제 없이는 이 데이터가 트레이스에 나타나, GDPR, HIPAA, PCI-DSS와 같은 규정 준수가 어려워집니다. PII 삭제는 트레이스에 저장되기 전에 민감한 데이터를 자동으로 마스킹하여 이 문제를 해결합니다.

## 작동 방식

1. **감지** - 알려진 PII 패턴에 대해 트레이스 이벤트 데이터를 스캔
2. **분류** - 민감한 데이터 유형 식별 (신용카드, SSN, 이메일 등)
3. **마스킹/삭제** - 구성에 따라 민감한 데이터를 마스킹된 값으로 대체

```
원본: "john.doe@company.com으로 연락하거나 555-123-4567로 전화하세요"
삭제됨: "<EMAIL_ADDRESS>로 연락하거나 <PHONE_NUMBER>로 전화하세요"
```

## PII 삭제 활성화

<Info>
  이 기능을 사용하려면 Enterprise 플랜이어야 하며 배포 버전이 1.8.0 이상이어야 합니다.
</Info>

<Steps>
  <Step title="크루 설정으로 이동">
    CrewAI AMP 대시보드에서 배포된 크루를 선택하고 배포/자동화 중 하나로 이동한 다음 **Settings** → **PII Protection**으로 이동합니다.
  </Step>

  <Step title="PII 보호 활성화">
    **PII Redaction for Traces**를 토글하여 활성화합니다. 이렇게 하면 트레이스 데이터의 자동 스캔 및 삭제가 활성화됩니다.

    <Info>
      각 배포에 대해 PII 삭제를 수동으로 활성화해야 합니다.
    </Info>

    <Frame>
      ![PII 삭제 활성화](/images/enterprise/pii_mask_recognizer_enable.png)
    </Frame>
  </Step>

  <Step title="엔티티 유형 구성">
    감지하고 삭제할 PII 유형을 선택합니다. 각 엔티티는 개별적으로 활성화하거나 비활성화할 수 있습니다.

    <Frame>
      ![엔티티 구성](/images/enterprise/pii_mask_recognizer_supported_entities.png)
    </Frame>
  </Step>

  <Step title="저장">
    구성을 저장합니다. PII 삭제는 이후 모든 크루 실행에서 활성화되며, 재배포가 필요하지 않습니다.
  </Step>
</Steps>

## 지원되는 엔티티 유형

CrewAI는 카테고리별로 구성된 다음 PII 엔티티 유형을 지원합니다.

### 글로벌 엔티티

| 엔티티 | 설명 | 예시 |
|--------|------|------|
| `CREDIT_CARD` | 신용/직불 카드 번호 | "4111-1111-1111-1111" |
| `CRYPTO` | 암호화폐 지갑 주소 | "bc1qxy2kgd..." |
| `DATE_TIME` | 날짜 및 시간 | "2024년 1월 15일" |
| `EMAIL_ADDRESS` | 이메일 주소 | "john@example.com" |
| `IBAN_CODE` | 국제 은행 계좌 번호 | "DE89 3704 0044 0532 0130 00" |
| `IP_ADDRESS` | IPv4 및 IPv6 주소 | "192.168.1.1" |
| `LOCATION` | 지리적 위치 | "뉴욕시" |
| `MEDICAL_LICENSE` | 의료 면허 번호 | "MD12345" |
| `NRP` | 국적, 종교 또는 정치 그룹 | - |
| `PERSON` | 개인 이름 | "홍길동" |
| `PHONE_NUMBER` | 다양한 형식의 전화번호 | "+82 (10) 1234-5678" |
| `URL` | 웹 URL | "https://example.com" |

### 미국 특정 엔티티

| 엔티티 | 설명 | 예시 |
|--------|------|------|
| `US_BANK_NUMBER` | 미국 은행 계좌 번호 | "1234567890" |
| `US_DRIVER_LICENSE` | 미국 운전면허 번호 | "D1234567" |
| `US_ITIN` | 개인 납세자 번호 | "900-70-0000" |
| `US_PASSPORT` | 미국 여권 번호 | "123456789" |
| `US_SSN` | 사회보장번호 | "123-45-6789" |

## 삭제 작업

활성화된 각 엔티티에 대해 데이터가 삭제되는 방식을 구성할 수 있습니다:

| 작업 | 설명 | 출력 예시 |
|------|------|----------|
| `mask` | 엔티티 유형 레이블로 대체 | `<CREDIT_CARD>` |
| `redact` | 텍스트를 완전히 제거 | *(비어있음)* |

## 커스텀 인식기

기본 제공 엔티티 외에도 조직별 PII 패턴을 감지하기 위한 **커스텀 인식기**를 생성할 수 있습니다.

<Frame>
  ![커스텀 인식기](/images/enterprise/pii_mask_recognizer.png)
</Frame>

### 인식기 유형

커스텀 인식기에는 두 가지 옵션이 있습니다:

| 유형 | 적합한 용도 | 사용 사례 예시 |
|------|------------|---------------|
| **패턴 기반 (Regex)** | 예측 가능한 형식의 구조화된 데이터 | 급여 금액, 직원 ID, 프로젝트 코드 |
| **거부 목록** | 정확한 문자열 매칭 | 회사명, 내부 코드명, 특정 용어 |

### 커스텀 인식기 생성

<Steps>
  <Step title="커스텀 인식기로 이동">
    조직 **Settings** → **Organization** → **Add Recognizer**로 이동합니다.
  </Step>

  <Step title="인식기 구성">
    <Frame>
      ![인식기 구성](/images/enterprise/pii_mask_recognizer_create.png)
    </Frame>

    다음 필드를 구성합니다:
    - **Name**: 인식기의 설명적 이름
    - **Entity Type**: 삭제된 출력에 나타날 엔티티 레이블 (예: `EMPLOYEE_ID`, `SALARY`)
    - **Type**: Regex 패턴 또는 거부 목록 중 선택
    - **Pattern/Values**: 매칭할 Regex 패턴 또는 문자열 목록
    - **Confidence Threshold**: 삭제를 트리거하는 데 필요한 최소 점수 (0.0-1.0). 높은 값 (예: 0.8)은 거짓 양성을 줄이지만 일부 매치를 놓칠 수 있습니다. 낮은 값 (예: 0.5)은 더 많은 매치를 잡지만 과도하게 삭제할 수 있습니다. 기본값은 0.8입니다.
    - **Context Words** (선택사항): 근처에서 발견될 때 감지 신뢰도를 높이는 단어
  </Step>

  <Step title="저장">
    인식기를 저장합니다. 배포에서 활성화할 수 있게 됩니다.
  </Step>
</Steps>

### 엔티티 유형 이해하기

**Entity Type**은 매칭된 콘텐츠가 삭제된 트레이스에 어떻게 나타나는지 결정합니다:

```
Entity Type: SALARY
Pattern: salary:\s*\$\s*\d+
입력: "직원 급여: $50,000"
출력: "직원 <SALARY>"
```

### 컨텍스트 단어 사용

컨텍스트 단어는 매칭된 패턴 근처에 특정 용어가 나타날 때 신뢰도를 높여 정확도를 향상시킵니다:

```
Context Words: "project", "code", "internal"
Entity Type: PROJECT_CODE
Pattern: PRJ-\d{4}
```

"project" 또는 "code"가 "PRJ-1234" 근처에 나타나면, 인식기는 그것이 진정한 매치라는 확신이 높아져 거짓 양성을 줄입니다.


## 삭제된 트레이스 보기

PII 삭제가 활성화되면, 트레이스에서 민감한 데이터 대신 삭제된 값이 표시됩니다:

```
Task Output: "고객 <PERSON>이 주문 #12345를 했습니다.
연락처 이메일: <EMAIL_ADDRESS>, 전화: <PHONE_NUMBER>.
<CREDIT_CARD>로 끝나는 카드로 결제가 처리되었습니다."
```

삭제된 값은 꺾쇠 괄호와 엔티티 유형 레이블 (예: `<EMAIL_ADDRESS>`)로 명확하게 표시되어, 어떤 데이터가 보호되었는지 쉽게 이해할 수 있으면서도 크루 동작을 디버그하고 모니터링할 수 있습니다.



## 모범 사례

### 성능 고려사항

<Steps>
  <Step title="필요한 엔티티만 활성화">
    활성화된 각 엔티티는 처리 오버헤드를 추가합니다. 데이터와 관련된 엔티티만 활성화하세요.
  </Step>

  <Step title="구체적인 패턴 사용">
    커스텀 인식기의 경우 거짓 양성을 줄이고 성능을 향상시키기 위해 구체적인 패턴을 사용하세요. Regex 패턴은 급여, 직원 ID, 프로젝트 코드 등 특정 패턴을 식별할 때 가장 적합합니다. 거부 목록 인식기는 회사명, 내부 코드명 등 정확한 문자열을 식별할 때 가장 적합합니다.
  </Step>

  <Step title="컨텍스트 단어 활용">
    컨텍스트 단어는 주변 텍스트가 매칭될 때만 감지를 트리거하여 정확도를 향상시킵니다.
  </Step>
</Steps>

## 문제 해결

<Accordion title="PII가 삭제되지 않음">
  **가능한 원인:**
  - 구성에서 엔티티 유형이 활성화되지 않음
  - 패턴이 데이터 형식과 매치되지 않음
  - 커스텀 인식기에 구문 오류가 있음

  **해결책:**
  - Settings → Security에서 엔티티가 활성화되어 있는지 확인
  - 샘플 데이터로 regex 패턴 테스트
  - 구성 오류에 대한 로그 확인
</Accordion>

<Accordion title="너무 많은 데이터가 삭제됨">
  **가능한 원인:**
  - 너무 광범위한 엔티티 유형이 활성화됨 (예: `DATE_TIME`이 모든 곳의 날짜를 잡음)
  - 커스텀 인식기 패턴이 너무 일반적임

  **해결책:**
  - 거짓 양성을 유발하는 엔티티 비활성화
  - 커스텀 패턴을 더 구체적으로 만들기
  - 정확도 향상을 위해 컨텍스트 단어 추가
</Accordion>

<Accordion title="성능 문제">
  **가능한 원인:**
  - 너무 많은 엔티티가 활성화됨
  - NLP 기반 엔티티 (`PERSON`, `LOCATION`, `NRP`)는 머신러닝 모델을 사용하므로 계산 비용이 높음

  **해결책:**
  - 실제로 필요한 엔티티만 활성화
  - 가능한 경우 패턴 기반 대안 고려
  - 대시보드에서 트레이스 처리 시간 모니터링
</Accordion>

---

## 실제 예시: 급여 패턴 매칭

이 예시는 트레이스에서 급여 정보를 감지하고 마스킹하는 커스텀 인식기를 생성하는 방법을 보여줍니다.

### 사용 사례

크루가 다음과 같은 형식의 급여 정보가 포함된 직원 또는 재무 데이터를 처리합니다:
- `salary: $50,000`
- `salary: $125,000.00`
- `salary:$1,500.50`

민감한 보상 데이터를 보호하기 위해 이러한 값을 자동으로 마스킹하려고 합니다.

### 구성

<Frame>
  ![급여 인식기 구성](/images/enterprise/pii_mask_custom_recognizer_salary.png)
</Frame>

| 필드 | 값 |
|------|-----|
| **Name** | `SALARY` |
| **Entity Type** | `SALARY` |
| **Type** | Regex Pattern |
| **Regex Pattern** | `salary:\s*\$\s*\d{1,3}(,\d{3})*(\.\d{2})?` |
| **Action** | Mask |
| **Confidence Threshold** | `0.8` |
| **Context Words** | `salary, compensation, pay, wage, income` |

### Regex 패턴 분석

| 패턴 구성요소 | 의미 |
|--------------|------|
| `salary:` | 리터럴 텍스트 "salary:" 매치 |
| `\s*` | 0개 이상의 공백 문자 매치 |
| `\$` | 달러 기호 매치 (이스케이프) |
| `\s*` | $ 뒤의 0개 이상의 공백 문자 매치 |
| `\d{1,3}` | 1-3자리 숫자 매치 (예: "1", "50", "125") |
| `(,\d{3})*` | 쉼표로 구분된 천 단위 매치 (예: ",000", ",500,000") |
| `(\.\d{2})?` | 선택적으로 센트 매치 (예: ".00", ".50") |

### 결과 예시

```
원본: "직원 기록에 salary: $125,000.00 연봉이 표시됩니다"
삭제됨: "직원 기록에 <SALARY> 연봉이 표시됩니다"

원본: "기본 salary:$50,000에 보너스 가능성"
삭제됨: "기본 <SALARY>에 보너스 가능성"
```

<Tip>
  "salary", "compensation", "pay", "wage", "income"과 같은 컨텍스트 단어를 추가하면 이러한 용어가 매칭된 패턴 근처에 나타날 때 감지 신뢰도가 높아져 거짓 양성을 줄입니다.
</Tip>

### 배포에서 인식기 활성화

<Warning>
  조직 수준에서 커스텀 인식기를 생성해도 배포에 자동으로 활성화되지 않습니다. 적용하려는 모든 배포에 대해 각 인식기를 수동으로 활성화해야 합니다.
</Warning>

커스텀 인식기를 생성한 후, 각 배포에서 활성화합니다:

<Steps>
  <Step title="배포로 이동">
    배포/자동화로 이동하여 **Settings** → **PII Protection**을 엽니다.
  </Step>

  <Step title="커스텀 인식기 선택">
    **Mask Recognizers** 아래에서 조직에서 정의한 인식기를 볼 수 있습니다. 활성화하려는 인식기 옆의 체크박스를 선택합니다.

    <Frame>
      ![커스텀 인식기 활성화](/images/enterprise/pii_mask_recognizers_options.png)
    </Frame>
  </Step>

  <Step title="구성 저장">
    변경 사항을 저장합니다. 인식기는 이 배포의 모든 후속 실행에서 활성화됩니다.
  </Step>
</Steps>

<Info>
  커스텀 인식기가 필요한 각 배포에서 이 프로세스를 반복합니다. 이를 통해 다양한 환경 (예: 개발 vs. 프로덕션)에서 어떤 인식기가 활성화되는지 세밀하게 제어할 수 있습니다.
</Info>
