> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ko/llms.txt

# 피드백

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

피드백 API는 평점, 추천, 댓글, 수정 사항 등 사람이 직접 관찰한 신호를 저장하고 쿼리합니다. 사용 패턴은 [피드백 가이드](https://mastra.zisheng.pro/ko/docs/observability/feedback)를 참조하세요.

## 사용예

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

```typescript
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 진입점을 통해 지속적인 추적 또는 범위에 피드백을 추가합니다.

```typescript
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`.

```typescript
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`가 생략되면 생성합니다.

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

### `batchCreateFeedback(args)`

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

```typescript
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?)`

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

```typescript
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)`

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

```typescript
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)`

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

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

### `getFeedbackTimeSeries(args)`

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

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

### `getFeedbackPercentiles(args)`

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

```typescript
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` |

## 관련된

- [피드백 가이드](https://mastra.zisheng.pro/ko/docs/observability/feedback)
- [클라이언트 SDK 관측 가능성 참조](https://mastra.zisheng.pro/ko/reference/client-js/observability)
- [Observability 구성](https://mastra.zisheng.pro/ko/reference/observability/tracing/configuration)