> Discover all available pages from the documentation index: https://mastra.zisheng.pro/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,
})
```

## 构造函数参数

**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' 用类型占位符替换

**options.instructions** (`string`): 检测 Agent 的自定义 instructions。如未提供，则使用基于检测类型的默认 instructions

**options.includeDetections** (`boolean`): 是否在日志中包含检测详情。适用于合规审计和调试

**options.lastMessageOnly** (`boolean`): 是否只检查批次中最新的消息，而不检查每条消息。使用此选项可避免在长线程中为每条较早的消息调用一次 LLM。

**options.preserveFormat** (`boolean`): 遮盖时是否保留 PII 格式。设为 true 时，会为电话号码保留类似 \*\*\*-\*\*-1234 的结构

**options.providerOptions** (`ProviderOptions`): 传给内部检测 Agent 的 Provider 特定选项。可用它控制模型行为，例如 thinking model 的 reasoning effort（例如 { openai: { reasoningEffort: 'low' } }）

## 返回值

**id** (`string`): Processor 标识符，设为 'pii-detector'

**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>`): 处理流式输出 part，以在流式传输期间检测和遮盖 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` 会先批量合并 stream chunk，再将其传给 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',
    }),
  ],
})
```

## 相关内容

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