피드백

추가된 항목: @mastra/core@1.18.0

피드백 API는 평점, 추천, 댓글, 수정 사항 등 사람이 직접 관찰한 신호를 저장하고 쿼리합니다. 사용 패턴은 피드백 가이드를 참조하세요.

사용예

다음 예제에서는 Observability 진입점을 통해 저장된 Trace에 평점을 기록합니다. 진입점의 addFeedback()은 선택 사항이므로 호출하기 전에 활성 Observability 구현에서 지원하는지 확인하세요.

if (!mastra.observability.addFeedback) {
  throw new Error('Feedback is not supported by the active observability implementation')
}

await mastra.observability.addFeedback({
  traceId: 'trace-123',
  spanId: 'span-456',
  feedback: {
    feedbackSource: 'user',
    feedbackType: 'rating',
    value: 1,
    comment: 'Helpful answer.',
  },
})

피드백 만들기

addFeedback(args)

Observability 진입점을 통해 지속적인 추적 또는 범위에 피드백을 추가합니다.

await mastra.observability.addFeedback?.({
  traceId: 'trace-123',
  spanId: 'span-456',
  feedback: {
    feedbackSource: 'user',
    feedbackType: 'rating',
    value: 1,
    comment: 'Helpful answer.',
  },
})

traceId?:

string

Trace that anchors the feedback target.

spanId?:

string

Span that anchors the feedback target.

correlationContext?:

CorrelationContext

대상을 저장소에서 복원하지 않고 데이터를 내보내는 데 사용할 활성 span 또는 Trace 컨텍스트입니다.

feedback:

FeedbackInput

Feedback payload to add.

createFeedback(args)

Observability 스토리지 도메인을 통해 하나의 피드백 레코드를 생성합니다. 저장소 수준 호출은 저장소에 직접 기록되므로 다음을 포함합니다.timestamp.

await observability.createFeedback({
  feedback: {
    feedbackId: 'feedback-1',
    timestamp: new Date(),
    traceId: 'trace-123',
    spanId: 'span-456',
    feedbackSource: 'user',
    feedbackType: 'rating',
    value: 1,
    comment: 'Helpful answer.',
  },
})

HTTP 및 클라이언트 SDK 생성 경로는 CreateFeedbackBody를 받고 서버 측에서 timestamp를 설정합니다. feedbackId가 생략되면 생성합니다.

await mastraClient.createFeedback({
  feedback: {
    traceId: 'trace-123',
    spanId: 'span-456',
    feedbackSource: 'user',
    feedbackType: 'rating',
    value: 1,
  },
})

batchCreateFeedback(args)

Observability 스토리지 도메인을 통해 여러 피드백 레코드를 생성합니다. 이 메서드는 HTTP 경로에 의해 노출되지 않습니다.@mastra/client-js.

await observability.batchCreateFeedback({
  feedbacks: [
    {
      feedbackId: 'feedback-1',
      timestamp: new Date(),
      traceId: 'trace-123',
      feedbackSource: 'user',
      feedbackType: 'rating',
      value: 1,
    },
    {
      feedbackId: 'feedback-2',
      timestamp: new Date(),
      traceId: 'trace-123',
      feedbackSource: 'qa',
      feedbackType: 'comment',
      value: 'Needs a citation before shipping.',
    },
  ],
})

피드백 나열

listFeedback(args?)

페이지 모드 또는 델타 모드에서 피드백 레코드를 반환합니다.

const response = await mastraClient.listFeedback({
  filters: {
    feedbackType: 'rating',
    feedbackSource: 'studio',
  },
  pagination: { page: 0, perPage: 20 },
  orderBy: { field: 'timestamp', direction: 'DESC' },
})

mode?:

'page' | 'delta'

List mode. Defaults to 'page'.

filters?:

FeedbackFilter

Filters for the feedback records.

pagination?:

{ page?: number; perPage?: number }

페이지 모드 페이지네이션입니다. page는 0부터 시작합니다.

orderBy?:

{ field?: 'timestamp'; direction?: 'ASC' | 'DESC' }

페이지 모드 정렬 구성입니다.

after?:

string

증분 폴링을 위한 델타 커서입니다. 델타 모드에서만 유효합니다.

limit?:

number

델타 모드에서 반환할 최대 업데이트 수입니다.

OLAP 쿼리

OLAP 피드백 쿼리는 숫자로 작동합니다.value fields.

getFeedbackAggregate(args)

하나의 집계 피드백 값을 반환합니다.

const response = await mastraClient.getFeedbackAggregate({
  feedbackType: 'rating',
  feedbackSource: 'user',
  aggregation: 'avg',
  comparePeriod: 'previous_day',
})

feedbackType:

string

Feedback type to aggregate.

feedbackSource?:

string

Feedback source to aggregate.

aggregation:

'sum' | 'avg' | 'min' | 'max' | 'count' | 'count_distinct' | 'last'

적용할 집계 방식입니다.

filters?:

FeedbackFilter

Additional filters.

comparePeriod?:

'previous_period' | 'previous_day' | 'previous_week'

선택적 기간 대비 비교입니다.

getFeedbackBreakdown(args)

측정기준별로 그룹화된 피드백 값을 반환합니다.

const response = await mastraClient.getFeedbackBreakdown({
  feedbackType: 'rating',
  groupBy: ['entityName'],
  aggregation: 'avg',
})

getFeedbackTimeSeries(args)

간격별로 버킷화된 피드백 값을 반환합니다.

const response = await mastraClient.getFeedbackTimeSeries({
  feedbackType: 'rating',
  interval: '1h',
  aggregation: 'avg',
  groupBy: ['feedbackSource'],
})

getFeedbackPercentiles(args)

간격별로 버킷화된 백분위수 값을 반환합니다.

const response = await mastraClient.getFeedbackPercentiles({
  feedbackType: 'rating',
  percentiles: [0.5, 0.95],
  interval: '1d',
})

유형

FeedbackRecord

feedbackId?:

string | null

이 피드백 이벤트의 고유 ID입니다. 생략하면 서버 경로에서 생성합니다.

timestamp:

Date

Time when the feedback was recorded.

traceId?:

string | null

사용 가능한 경우 피드백 대상을 고정하는 Trace입니다.

spanId?:

string | null

사용 가능한 경우 피드백 대상을 고정하는 span입니다.

feedbackSource?:

string | null

'user', 'qa', 'studio', 'system' 등의 선택적 출처 메타데이터입니다.

source?:

string | null

feedbackSource의 더 이상 사용되지 않는 별칭입니다.

feedbackType:

string

'rating', 'thumbs', 'comment', 'correction' 등의 피드백 유형입니다.

value:

number | string

피드백 값입니다. 숫자 값은 집계, 분석, 시계열 및 백분위수 쿼리를 지원합니다.

comment?:

string | null

피드백에 대한 추가 댓글 또는 컨텍스트입니다.

feedbackUserId?:

string | null

피드백을 제공한 사용자입니다.

sourceId?:

string | null

실험 결과 ID 등 이 피드백이 연결된 출처 레코드의 ID입니다.

metadata?:

Record<string, unknown> | null

피드백 레코드의 사용자 정의 메타데이터입니다.

공유 컨텍스트 필드

피드백 레코드에는 추적, 로그, 지표 및 점수와의 필터링, 그룹화 및 상관 관계를 위한 공유 Observability 컨텍스트 필드가 포함될 수 있습니다.

entityType?:

EntityType | null

신호를 생성한 엔터티의 유형입니다.

entityId?:

string | null

신호를 생성한 엔터티의 ID입니다.

entityName?:

string | null

신호를 생성한 엔터티의 이름입니다.

parentEntityType?:

EntityType | null

상위 엔터티의 유형입니다.

parentEntityId?:

string | null

ID of the parent entity.

parentEntityName?:

string | null

Name of the parent entity.

rootEntityType?:

EntityType | null

루트 엔터티의 유형입니다.

rootEntityId?:

string | null

ID of the root entity.

rootEntityName?:

string | null

Name of the root entity.

userId?:

string | null

Human end user who triggered execution.

organizationId?:

string | null

멀티테넌트 조직 또는 계정입니다.

resourceId?:

string | null

Broader resource context.

runId?:

string | null

Execution run identifier.

sessionId?:

string | null

Trace 그룹화에 사용하는 세션 식별자입니다.

threadId?:

string | null

Conversation thread identifier.

requestId?:

string | null

HTTP request ID for correlation.

environment?:

string | null

Deployment environment.

serviceName?:

string | null

Name of the service.

scope?:

Record<string, unknown> | null

패키지, 앱 버전 또는 배포 메타데이터입니다.

entityVersionId?:

string | null

신호를 생성한 엔터티의 버전 ID입니다.

parentEntityVersionId?:

string | null

상위 엔터티의 버전 ID입니다.

rootEntityVersionId?:

string | null

루트 엔터티의 버전 ID입니다.

experimentId?:

string | null

Experiment or eval run identifier.

executionSource?:

string | null

로컬, 클라우드 또는 CI 등의 실행 출처입니다.

tags?:

string[] | null

Labels for filtering.

FeedbackInput

mastra.observability.addFeedback(), recordedTrace.addFeedback(), recordedSpan.addFeedback()과 함께 FeedbackInput을 사용하세요.

feedbackSource?:

string

피드백의 선택적 출처 메타데이터입니다.

source?:

string

Deprecated alias for feedbackSource.

feedbackType:

string

Type of feedback to record.

value:

number | string

Feedback value to record.

comment?:

string

Additional comment or context.

feedbackUserId?:

string

User who provided the feedback.

userId?:

string

Deprecated alias for feedbackUserId.

metadata?:

Record<string, unknown>

피드백별 추가 메타데이터입니다.

experimentId?:

string

Experiment or eval run identifier.

sourceId?:

string

이 피드백이 연결된 출처 레코드의 ID입니다.

FeedbackFilter

listFeedback() 및 OLAP 쿼리의 filters에서 FeedbackFilter를 사용하세요.

timestamp?:

{ start?: Date; end?: Date; startExclusive?: boolean; endExclusive?: boolean }

타임스탬프 범위로 필터링합니다.

traceId?:

string

Filter by trace ID.

spanId?:

string

Filter by span ID.

feedbackType?:

string | string[]

하나 이상의 피드백 유형으로 필터링합니다.

feedbackSource?:

string

Filter by feedback source.

source?:

string

Deprecated alias for feedbackSource.

feedbackUserId?:

string

피드백을 제공한 사용자로 필터링합니다.

entityType?:

EntityType

Filter by entity type.

entityName?:

string

Filter by entity name.

entityVersionId?:

string

Filter by entity version ID.

parentEntityType?:

EntityType

Filter by parent entity type.

parentEntityName?:

string

Filter by parent entity name.

parentEntityVersionId?:

string

상위 엔터티 버전 ID로 필터링합니다.

rootEntityType?:

EntityType

Filter by root entity type.

rootEntityName?:

string

Filter by root entity name.

rootEntityVersionId?:

string

Filter by root entity version ID.

userId?:

string

Filter by human end-user ID.

organizationId?:

string

Filter by organization ID.

resourceId?:

string

Filter by resource ID.

runId?:

string

Filter by run ID.

sessionId?:

string

Filter by session ID.

threadId?:

string

Filter by thread ID.

requestId?:

string

Filter by request ID.

serviceName?:

string

Filter by service name.

environment?:

string

Filter by environment.

executionSource?:

string

Filter by execution source.

experimentId?:

string

실험 또는 Evals 실행 식별자로 필터링합니다.

tags?:

string[]

태그로 필터링합니다. 일치하는 레코드는 지정된 태그를 모두 포함해야 합니다.

HTTP 경로

메서드	경로	목적	권한
GET	/api/observability/feedback	피드백 레코드 나열	파생 권한 없음
POST	/api/observability/feedback	피드백 레코드 생성	파생 권한 없음
POST	/api/observability/feedback/aggregate	단일 집계 값 반환	observability:read
POST	/api/observability/feedback/breakdown	차원별로 피드백 그룹화	observability:read
POST	/api/observability/feedback/timeseries	간격별로 피드백 버킷화	observability:read
POST	/api/observability/feedback/percentiles	백분위수 계열 반환	observability:read

관련된

• 피드백 가이드
• 클라이언트 SDK 관측 가능성 참조
• Observability 구성