ModerationProcessor

ModerationProcessor est un Processor hybride qui peut traiter aussi bien les entrées que les sorties afin de modérer le contenu à l’aide d’un LLM capable de détecter des contenus inappropriés dans plusieurs catégories. Ce Processor contribue à préserver la sûreté du contenu en évaluant les messages selon des catégories de modération configurables, avec des stratégies flexibles pour gérer le contenu signalé.

Exemple d’utilisation

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

Paramètres du constructeur

options:

Options

Options de configuration de la modération du contenu

Options

model:

MastraModelConfig

Configuration du modèle de l’Agent de modération

categories?:

string[]

Catégories à vérifier lors de la modération. Si elles ne sont pas indiquées, les catégories OpenAI par défaut sont utilisées

threshold?:

number

Seuil de confiance du signalement (0 à 1). Le contenu est signalé si le score d’une catégorie dépasse ce seuil

strategy?:

'block' | 'warn' | 'filter'

Stratégie appliquée lorsque du contenu est signalé : 'block' le rejette avec une erreur, 'warn' enregistre un avertissement mais le laisse passer et 'filter' supprime les messages signalés

instructions?:

string

Instructions de modération personnalisées destinées à l’Agent. Si elles ne sont pas fournies, les instructions par défaut fondées sur les catégories sont utilisées

includeScores?:

boolean

Indique si les scores de confiance doivent être inclus dans les logs. Utile pour ajuster les seuils et déboguer

lastMessageOnly?:

boolean

Indique si la modération doit être exécutée uniquement sur le message le plus récent du lot, au lieu de vérifier chaque message. Utilisez cette option pour éviter un appel supplémentaire au LLM pour chaque ancien message des longues conversations.

chunkWindow?:

number

Nombre de segments précédents à inclure comme contexte lors de la modération des segments du flux. Une valeur de 1 inclut la partie précédente, et ainsi de suite.

providerOptions?:

ProviderOptions

Options propres au Provider transmises à l’Agent de modération interne. Utilisez-les pour contrôler le comportement du modèle, par exemple l’effort de raisonnement des modèles de réflexion (par exemple, { openai: { reasoningEffort: 'low' } })

Valeur renvoyée

id:

string

Identifiant du Processor défini sur 'moderation'

name?:

string

Nom d’affichage facultatif du Processor

processInput:

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

Traite les messages d’entrée afin de modérer leur contenu avant de l’envoyer au LLM

processOutputStream:

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

Traite les parties de la sortie diffusée afin de modérer leur contenu pendant le streaming

Exemple d’utilisation avancée

Traitement des entrées

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

Traitement des sorties par lots

Lorsque vous utilisez ModerationProcessor comme Processor de sortie, il est recommandé de l’associer à BatchPartsProcessor afin d’optimiser les performances. BatchPartsProcessor regroupe les segments du flux avant de les transmettre au modérateur, ce qui réduit le nombre d’appels au LLM nécessaires à la modération.

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

Voir aussi

• Guardrails