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

# PIIDetector

`PIIDetector` 是一個**混合型 processor**，可同時用於輸入及輸出處理，以偵測及遮蓋個人可識別資料（PII），從而符合私隱規定。此 processor 會識別不同類型的 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,
})
```

## Constructor 參數

**options** (`Options`): PII 偵測及遮蓋的配置選項

**options.model** (`MastraModelConfig`): 偵測 Agent 的模型配置

**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' 會以類型 placeholder 取代

**options.instructions** (`string`): 供 Agent 使用的自訂偵測指示。如未提供，則根據偵測類型使用預設指示

**options.includeDetections** (`boolean`): 是否在記錄中加入偵測詳情。適用於合規審計及除錯

**options.lastMessageOnly** (`boolean`): 是否只檢查批次中最新的訊息，而非檢查每則訊息。用於避免在較長的對話串中，為每則較早的訊息分別呼叫一次 LLM。

**options.preserveFormat** (`boolean`): 遮蓋時是否保留 PII 格式。設為 true 時，會保留電話號碼中 \*\*\*-\*\*-1234 一類的結構

**options.providerOptions** (`ProviderOptions`): 傳入內部偵測 Agent 的 Provider 專屬選項。可用於控制模型行為，例如 thinking 模型的推理強度（如 { openai: { reasoningEffort: 'low' } }）

## 返回值

**id** (`string`): 設為 'pii-detector' 的 processor 識別符

**name** (`string`): 可選的 processor 顯示名稱

**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` 作為輸出 processor，建議配合 `BatchPartsProcessor` 使用，以優化效能。`BatchPartsProcessor` 會先將串流區塊合併為批次，再傳送至 PII detector，從而減少偵測所需的 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',
    }),
  ],
})
```

## 相關內容

- [Guardrails](https://mastra.zisheng.pro/zh-HK/docs/agents/guardrails)