> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ko/llms.txt

# PII탐지기

그만큼`PIIDetector`는**하이브리드 프로세서**개인정보 보호 규정 준수를 위해 개인 식별 정보(PII)를 탐지하고 수정하기 위해 입력 및 출력 처리에 모두 사용할 수 있습니다. 이 프로세서는 PII 유형을 식별하고 GDPR, CCPA, HIPAA 및 기타 개인 정보 보호 규정을 준수하기 위한 다양한 수정 방법을 포함하여 이를 처리하기 위한 유연한 전략을 제공함으로써 개인 정보 보호를 유지하는 데 도움이 됩니다.

## 사용예

```typescript
import { PIIDetector } from '@mastra/core/processors'

const processor = new PIIDetector({
  model: 'openrouter/openai/gpt-oss-safeguard-20b',
  threshold: 0.6,
  strategy: 'redact',
  detectionTypes: ['email', 'phone', 'credit-card', 'ssn'],
  lastMessageOnly: true,
})
```

## 생성자 매개변수

**options** (`Options`): PII 감지 및 수정 구성 옵션

**options.model** (`MastraModelConfig`): 감지 Agent의 Model 구성

**options.detectionTypes** (`string[]`): 감지할 PII 유형입니다. 지정하지 않으면 기본 유형을 사용합니다.

**options.threshold** (`number`): 플래그를 지정할 신뢰도 임계값(0\~1)입니다. 범주 점수 중 하나라도 이 임계값을 초과하면 PII에 플래그가 지정됩니다.

**options.strategy** (`'block' | 'warn' | 'filter' | 'redact'`): PII가 감지되었을 때의 전략입니다. 'block'은 오류와 함께 거부하고, 'warn'은 경고를 기록하지만 통과시키며, 'filter'는 플래그가 지정된 메시지를 제거하고, 'redact'는 PII를 수정된 버전으로 대체합니다.

**options.redactionMethod** (`'mask' | 'hash' | 'remove' | 'placeholder'`): PII 수정 방법입니다. 'mask'는 별표로, 'hash'는 SHA256 해시로 대체하고, 'remove'는 완전히 제거하며, 'placeholder'는 유형 자리표시자로 대체합니다.

**options.instructions** (`string`): Agent의 사용자 정의 감지 지침입니다. 제공하지 않으면 감지 유형에 따른 기본 지침을 사용합니다.

**options.includeDetections** (`boolean`): 로그에 감지 세부 정보를 포함할지 여부입니다. 규정 준수 감사 및 디버깅에 유용합니다.

**options.lastMessageOnly** (`boolean`): 모든 메시지를 확인하는 대신 배치에서 가장 최근 메시지만 검사할지 여부입니다. 긴 스레드에서 이전 메시지마다 LLM을 한 번씩 호출하지 않으려면 사용하세요.

**options.preserveFormat** (`boolean`): 수정 중에 PII 형식을 보존할지 여부입니다. true이면 전화번호의 \*\*\*-\*\*-1234와 같은 구조를 유지합니다.

**options.providerOptions** (`ProviderOptions`): 내부 감지 Agent에 전달되는 Provider별 옵션입니다. 사고 Model의 추론 노력 수준과 같은 Model 동작을 제어할 때 사용하세요(예: { openai: { reasoningEffort: 'low' } }).

## 보고

**id** (`string`): 'pii-detector'로 설정되는 프로세서 식별자

**name** (`string`): 선택적 프로세서 표시 이름

**processInput** (`(args: { messages: MastraDBMessage[]; abort: (reason?: string) => never; tracingContext?: TracingContext }) => Promise<MastraDBMessage[]>`): LLM에 보내기 전에 입력 메시지를 처리하여 PII를 감지하고 수정합니다.

**processOutputStream** (`(args: { part: ChunkType; streamParts: ChunkType[]; state: Record<string, any>; abort: (reason?: string) => never; tracingContext?: TracingContext }) => Promise<ChunkType | null | undefined>`): 스트리밍 중에 PII를 감지하고 수정하도록 스트리밍 출력 부분을 처리합니다.

## 확장된 사용 예

### 입력 처리

```typescript
import { Agent } from '@mastra/core/agent'
import { PIIDetector } from '@mastra/core/processors'

export const agent = new Agent({
  id: 'private-agent',
  name: 'private-agent',
  instructions: 'You are a helpful assistant',
  model: 'openai/gpt-5.6-sol',
  inputProcessors: [
    new PIIDetector({
      model: 'openrouter/openai/gpt-oss-safeguard-20b',
      detectionTypes: ['email', 'phone', 'credit-card', 'ssn'],
      threshold: 0.6,
      strategy: 'redact',
      redactionMethod: 'mask',
      instructions:
        'Detect and redact personally identifiable information while preserving message intent',
      includeDetections: true,
      preserveFormat: true,
    }),
  ],
})
```

### 일괄 처리를 통한 출력 처리

`PIIDetector`를 출력 프로세서로 사용할 때는 성능 최적화를 위해 `BatchPartsProcessor`와 함께 사용하는 것이 좋습니다. `BatchPartsProcessor`는 스트림 청크를 PII 감지기에 전달하기 전에 함께 일괄 처리하여 감지에 필요한 LLM 호출 수를 줄입니다.

```typescript
import { Agent } from '@mastra/core/agent'
import { BatchPartsProcessor, PIIDetector } from '@mastra/core/processors'

export const agent = new Agent({
  id: 'output-pii-agent',
  name: 'output-pii-agent',
  instructions: 'You are a helpful assistant',
  model: 'openai/gpt-5.6-sol',
  outputProcessors: [
    // Batch stream parts first to reduce LLM calls
    new BatchPartsProcessor({
      batchSize: 10,
    }),
    // Then apply PII detection on batched content
    new PIIDetector({
      model: 'openrouter/openai/gpt-oss-safeguard-20b',
      strategy: 'redact',
    }),
  ],
})
```

## 관련된

- [난간](https://mastra.zisheng.pro/ko/docs/agents/guardrails)