ModerationProcessor

ModerationProcessor 是一種混合式處理器，可同時用於輸入與輸出處理。它會使用 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' 的處理器識別碼

name?:

string

選用的處理器顯示名稱

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 作為輸出處理器時，搭配 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,
    }),
  ],
})

相關資源

• 防護機制