PII탐지기

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

사용예

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 구성

detectionTypes?:

string[]

감지할 PII 유형입니다. 지정하지 않으면 기본 유형을 사용합니다.

threshold?:

number

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

strategy?:

'block' | 'warn' | 'filter' | 'redact'

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

redactionMethod?:

'mask' | 'hash' | 'remove' | 'placeholder'

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

instructions?:

string

Agent의 사용자 정의 감지 지침입니다. 제공하지 않으면 감지 유형에 따른 기본 지침을 사용합니다.

includeDetections?:

boolean

로그에 감지 세부 정보를 포함할지 여부입니다. 규정 준수 감사 및 디버깅에 유용합니다.

lastMessageOnly?:

boolean

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

preserveFormat?:

boolean

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

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를 감지하고 수정하도록 스트리밍 출력 부분을 처리합니다.

확장된 사용 예

입력 처리

src/mastra/agents/private-agent.ts

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 호출 수를 줄입니다.

src/mastra/agents/output-pii-agent.ts

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',
    }),
  ],
})

관련된

• 난간