PII检测器

🌐 PIIDetector

PIIDetector 是一款 混合处理器，可用于输入和输出处理，以检测和编辑个人可识别信息（PII），以确保隐私合规。该处理器通过识别各种类型的 PII 并提供灵活的处理策略来帮助维护隐私，包括多种编辑方法，以确保符合 GDPR、CCPA、HIPAA 及其他隐私法规的要求。

🌐 The PIIDetector is a hybrid processor that can be used for both input and output processing to detect and redact personally identifiable information (PII) for privacy compliance. This processor helps maintain privacy by identifying various types of PII and providing flexible strategies for handling them, including multiple redaction methods to ensure compliance with GDPR, CCPA, HIPAA, and other privacy regulations.

使用示例

🌐 Usage example

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"]
});

构造函数参数

🌐 Constructor parameters

options:

Options

Configuration options for PII detection and redaction

选项

🌐 Options

model:

MastraModelConfig

Model configuration for the detection agent

detectionTypes?:

string[]

PII types to detect. If not specified, uses default types

threshold?:

number

Confidence threshold for flagging (0-1). PII is flagged if any category score exceeds this threshold

strategy?:

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

Strategy when PII is detected: 'block' rejects with error, 'warn' logs warning but allows through, 'filter' removes flagged messages, 'redact' replaces PII with redacted versions

redactionMethod?:

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

Redaction method for PII: 'mask' replaces with asterisks, 'hash' replaces with SHA256 hash, 'remove' removes entirely, 'placeholder' replaces with type placeholder

instructions?:

string

Custom detection instructions for the agent. If not provided, uses default instructions based on detection types

includeDetections?:

boolean

Whether to include detection details in logs. Useful for compliance auditing and debugging

preserveFormat?:

boolean

Whether to preserve PII format during redaction. When true, maintains structure like ***-**-1234 for phone numbers

providerOptions?:

ProviderOptions

Provider-specific options passed to the internal detection agent. Use this to control model behavior like reasoning effort for thinking models (e.g., `{ openai: { reasoningEffort: 'low' } }`)

返回

🌐 Returns

id:

string

Processor identifier set to 'pii-detector'

name?:

string

Optional processor display name

processInput:

(args: { messages: MastraDBMessage[]; abort: (reason?: string) => never; tracingContext?: TracingContext }) => Promise<MastraDBMessage[]>

Processes input messages to detect and redact PII before sending to LLM

processOutputStream:

(args: { part: ChunkType; streamParts: ChunkType[]; state: Record<string, any>; abort: (reason?: string) => never; tracingContext?: TracingContext }) => Promise<ChunkType | null | undefined>

Processes streaming output parts to detect and redact PII during streaming

扩展使用示例

🌐 Extended usage example

输入处理

🌐 Input processing

src/mastra/agents/private-agent.ts

import { Agent } from "@mastra/core/agent";
import { PIIDetector } from "@mastra/core/processors";

export const agent = new Agent({
  name: "private-agent",
  instructions: "You are a helpful assistant",
  model: "openai/gpt-5.1",
  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
    })
  ]
});

批处理输出处理

🌐 Output processing with batching

在将 PIIDetector 用作输出处理器时，建议将其与 BatchPartsProcessor 结合使用以优化性能。BatchPartsProcessor 会在将数据块传递给 PII 检测器之前将流数据批量处理，从而减少检测所需的 LLM 调用次数。

🌐 When using PIIDetector as an output processor, it's recommended to combine it with BatchPartsProcessor to optimize performance. The BatchPartsProcessor batches stream chunks together before passing them to the PII detector, reducing the number of LLM calls required for detection.

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({
  name: "output-pii-agent",
  instructions: "You are a helpful assistant",
  model: "openai/gpt-5.1",
  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",
    })
  ]
});

相关

🌐 Related

• 护栏