ModerationProcessor

ModerationProcessor 是一个混合 Processor，可同时用于输入和输出处理。它使用 LLM 检测多个类别中的不当内容，从而提供内容审核。此 Processor 会根据可配置的审核类别评估消息，并提供灵活的已标记内容处理策略，帮助维护内容安全。

用法示例

import { ModerationProcessor } from '@mastra/core/processors'

const processor = new ModerationProcessor({
  model: 'openrouter/openai/gpt-oss-safeguard-20b',
  threshold: 0.7,
  strategy: 'block',
  categories: ['hate', 'harassment', 'violence'],
  lastMessageOnly: true,
})

构造函数参数

options:

Options

内容审核的配置选项

Options

model:

MastraModelConfig

审核 Agent 的模型配置

categories?:

string[]

要检查的审核类别。如未指定，则使用默认的 OpenAI 类别

threshold?:

number

标记内容的置信度阈值（0-1）。如果任何类别的分数超过此阈值，就会标记内容

strategy?:

'block' | 'warn' | 'filter'

内容被标记时采用的策略：'block' 返回错误并拒绝内容，'warn' 记录警告但允许内容通过，'filter' 移除被标记的消息

instructions?:

string

审核 Agent 的自定义 instructions。如未提供，则使用基于类别的默认 instructions

includeScores?:

boolean

是否在日志中包含置信度分数。适用于调整阈值和调试

lastMessageOnly?:

boolean

是否只审核批次中最新的消息，而不检查每条消息。使用此选项可避免在长对话中为每条较早的消息额外调用一次 LLM。

chunkWindow?:

number

审核流式 chunk 时，为提供上下文而包含的前序 chunk 数量。如设为 1，则包含前一个 part，依此类推。

providerOptions?:

ProviderOptions

传给内部审核 Agent 的 Provider 特定选项。可用它控制模型行为，例如 thinking model 的 reasoning effort（例如 { openai: { reasoningEffort: 'low' } }）

返回值

id:

string

Processor 标识符，设为 'moderation'

name?:

string

可选的 Processor 显示名称

processInput:

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

在发送给 LLM 前处理输入消息以审核内容

processOutputStream:

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

处理流式输出 part，以在流式传输期间审核内容

扩展用法示例

输入处理

src/mastra/agents/moderated-agent.ts

import { Agent } from '@mastra/core/agent'
import { ModerationProcessor } from '@mastra/core/processors'

export const agent = new Agent({
  id: 'moderated-agent',
  name: 'moderated-agent',
  instructions: 'You are a helpful assistant',
  model: 'openai/gpt-5.6-sol',
  inputProcessors: [
    new ModerationProcessor({
      model: 'openrouter/openai/gpt-oss-safeguard-20b',
      categories: ['hate', 'harassment', 'violence'],
      threshold: 0.7,
      strategy: 'block',
      instructions: 'Detect and flag inappropriate content in user messages',
      includeScores: true,
    }),
  ],
})

通过批量合并处理输出

将 ModerationProcessor 用作输出 Processor 时，建议将其与 BatchPartsProcessor 结合使用以优化性能。BatchPartsProcessor 会先批量合并 stream chunk，再将其传给审核器，从而减少审核所需的 LLM 调用次数。

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

import { Agent } from '@mastra/core/agent'
import { BatchPartsProcessor, ModerationProcessor } from '@mastra/core/processors'

export const agent = new Agent({
  id: 'output-moderated-agent',
  name: 'output-moderated-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 moderation on batched content
    new ModerationProcessor({
      model: 'openrouter/openai/gpt-oss-safeguard-20b',
      strategy: 'filter',
      chunkWindow: 1,
    }),
  ],
})

相关内容

• Guardrails