조정프로세서

그만큼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의 Model 구성

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별 옵션입니다. 사고 Model의 추론 노력 수준과 같은 Model 동작을 제어할 때 사용하세요(예: { 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,
    }),
  ],
})

관련된

• 난간