ModerationProcessor

ModerationProcessor は、入力と出力の両方の処理に使用できる ハイブリッド Processor です。LLM を使って複数のカテゴリーにわたる不適切なコンテンツを検出し、コンテンツモデレーションを行います。設定可能なモデレーションカテゴリーに基づいてメッセージを評価し、フラグが付いたコンテンツを柔軟な方法で処理することで、コンテンツの安全性を維持できます。

使用例

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 に与えるカスタムモデレーション指示。指定しない場合はカテゴリーに基づくデフォルトの指示を使用します

includeScores?:

boolean

信頼度スコアをログに含めるかどうか。しきい値の調整やデバッグに役立ちます

lastMessageOnly?:

boolean

すべてのメッセージを確認せず、バッチ内の最新メッセージだけをモデレーションするかどうか。長い会話で以前の各メッセージに追加の LLM 呼び出しが発生するのを防ぐために使用します。

chunkWindow?:

number

ストリームチャンクのモデレーション時に、コンテキストとして含める以前のチャンク数。1 を指定すると、直前の部分が含まれます。

providerOptions?:

ProviderOptions

内部のモデレーション Agent に渡す Provider 固有のオプション。思考モデルの推論量など、モデルの動作を制御するために使用します（例：{ openai: { reasoningEffort: 'low' } }）

戻り値

id:

string

'moderation' に設定された Processor の識別子

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>

ストリーミング中に出力パーツを処理し、コンテンツをモデレーションします

詳細な使用例

入力処理

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 はストリームチャンクをまとめてからモデレーターに渡し、モデレーションに必要な 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