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,
})

Constructor 參數

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

是否在 log 中包含信心分數。適用於調整門檻及偵錯

lastMessageOnly?:

boolean

是否只對批次中最新的訊息執行審核，而非檢查每一則訊息。對話較長時，可使用此選項避免為每一則較早的訊息額外呼叫一次 LLM。

chunkWindow?:

number

審核串流 chunk 時，要加入作為 context 的先前 chunk 數目。如設為 1，則會包含上一個部分，如此類推。

providerOptions?:

ProviderOptions

傳遞給內部審核 Agent 的 Provider 特有選項。可用來控制模型行為，例如推理模型的 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>

在串流期間處理串流輸出的各個部分，以審核內容

進階使用範例

輸入處理

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 會先將串流 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