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

# Feedback

**新增於：** `@mastra/core@1.18.0`

Feedback API 會儲存及查詢人工介入的可觀測性訊號，例如評分、讚好／不讚好、留言及修正。使用模式請參閱 [Feedback 指南](https://mastra.zisheng.pro/zh-HK/docs/observability/feedback)。

## 使用範例

以下範例透過可觀測性進入點，為已持久保存的 Trace 記錄評分。進入點上的 `addFeedback()` 屬選用方法，因此呼叫前請先確認目前使用的可觀測性實作支援此方法。

```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.',
  },
})
```

## 建立 Feedback

### `addFeedback(args)`

透過可觀測性進入點，將 Feedback 加至已持久保存的 Trace 或 span。

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

**traceId** (`string`): 作為 Feedback 目標定位基準的 Trace。

**spanId** (`string`): 作為 Feedback 目標定位基準的 span。

**correlationContext** (`CorrelationContext`): 用於直接發出 Feedback 的即時 span 或 Trace context，毋須從儲存空間重新載入目標。

**feedback** (`FeedbackInput`): 要加入的 Feedback payload。

### `createFeedback(args)`

透過可觀測性儲存 domain 建立一筆 Feedback 記錄。儲存層級的呼叫會直接寫入儲存空間，因此須包含 `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)`

透過可觀測性儲存 domain 建立多筆 Feedback 記錄。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.',
    },
  ],
})
```

## 列出 Feedback

### `listFeedback(args?)`

以分頁模式或增量模式傳回 Feedback 記錄。

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

**mode** (`'page' | 'delta'`): 列表模式。預設為 'page'。

**filters** (`FeedbackFilter`): Feedback 記錄的篩選條件。

**pagination** (`{ page?: number; perPage?: number }`): 分頁模式的分頁設定。page 由零開始計算。

**orderBy** (`{ field?: 'timestamp'; direction?: 'ASC' | 'DESC' }`): 分頁模式的排序設定。

**after** (`string`): 增量輪詢所用的增量游標。只適用於增量模式。

**limit** (`number`): 在增量模式中傳回的更新數目上限。

## OLAP 查詢

OLAP Feedback 查詢會處理數值型別的 `value` 欄位。

### `getFeedbackAggregate(args)`

傳回一個彙總 Feedback 值。

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

**feedbackType** (`string`): 要彙總的 Feedback 類型。

**feedbackSource** (`string`): 要彙總的 Feedback 來源。

**aggregation** (`'sum' | 'avg' | 'min' | 'max' | 'count' | 'count_distinct' | 'last'`): 要套用的彙總方式。

**filters** (`FeedbackFilter`): 其他篩選條件。

**comparePeriod** (`'previous_period' | 'previous_day' | 'previous_week'`): 選用的逐期比較。

### `getFeedbackBreakdown(args)`

傳回按維度分組的 Feedback 值。

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

### `getFeedbackTimeSeries(args)`

傳回按時間間距分桶的 Feedback 值。

```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`): 此 Feedback 事件的唯一 ID。如省略，伺服器路由會自動產生。

**timestamp** (`Date`): 記錄 Feedback 的時間。

**traceId** (`string | null`): 如有 Trace，則以其作為 Feedback 目標的定位基準。

**spanId** (`string | null`): 如有 span，則以其作為 Feedback 目標的定位基準。

**feedbackSource** (`string | null`): 選用的來源 metadata，例如 'user'、'qa'、'studio' 或 'system'。

**source** (`string | null`): feedbackSource 已棄用的別名。

**feedbackType** (`string`): Feedback 類型，例如 'rating'、'thumbs'、'comment' 或 'correction'。

**value** (`number | string`): Feedback 值。數值支援彙總、明細、時間序列及百分位數查詢。

**comment** (`string | null`): Feedback 的其他留言或 context。

**feedbackUserId** (`string | null`): 提供 Feedback 的用戶。

**sourceId** (`string | null`): 此 Feedback 所連結的來源記錄 ID，例如實驗結果 ID。

**metadata** (`Record<string, unknown> | null`): Feedback 記錄的用戶自訂 metadata。

### 共用 context 欄位

Feedback 記錄可包含共用的可觀測性 context 欄位，用於篩選、分組，以及與 Trace、日誌、指標和分數建立關聯。

**entityType** (`EntityType | null`): 產生訊號的實體類型。

**entityId** (`string | null`): 產生訊號的實體 ID。

**entityName** (`string | null`): 產生訊號的實體名稱。

**parentEntityType** (`EntityType | null`): 上層實體的實體類型。

**parentEntityId** (`string | null`): 上層實體的 ID。

**parentEntityName** (`string | null`): 上層實體的名稱。

**rootEntityType** (`EntityType | null`): 根實體的實體類型。

**rootEntityId** (`string | null`): 根實體的 ID。

**rootEntityName** (`string | null`): 根實體的名稱。

**userId** (`string | null`): 觸發執行的人類終端用戶。

**organizationId** (`string | null`): 多租戶組織或帳戶。

**resourceId** (`string | null`): 較廣泛的資源 context。

**runId** (`string | null`): 執行 run 的識別碼。

**sessionId** (`string | null`): 用於將 Trace 分組的 session 識別碼。

**threadId** (`string | null`): 對話 thread 識別碼。

**requestId** (`string | null`): 用於建立關聯的 HTTP 請求 ID。

**environment** (`string | null`): 部署環境。

**serviceName** (`string | null`): 服務名稱。

**scope** (`Record<string, unknown> | null`): 套件、應用程式版本或部署 metadata。

**entityVersionId** (`string | null`): 產生訊號的實體版本 ID。

**parentEntityVersionId** (`string | null`): 上層實體的版本 ID。

**rootEntityVersionId** (`string | null`): 根實體的版本 ID。

**experimentId** (`string | null`): 實驗或 eval run 識別碼。

**executionSource** (`string | null`): 執行來源，例如本機、雲端或 CI。

**tags** (`string[] | null`): 用於篩選的標籤。

### `FeedbackInput`

將 `FeedbackInput` 與 `mastra.observability.addFeedback()`、`recordedTrace.addFeedback()` 及 `recordedSpan.addFeedback()` 一併使用。

**feedbackSource** (`string`): Feedback 的選用來源 metadata。

**source** (`string`): feedbackSource 已棄用的別名。

**feedbackType** (`string`): 要記錄的 Feedback 類型。

**value** (`number | string`): 要記錄的 Feedback 值。

**comment** (`string`): 其他留言或 context。

**feedbackUserId** (`string`): 提供 Feedback 的用戶。

**userId** (`string`): feedbackUserId 已棄用的別名。

**metadata** (`Record<string, unknown>`): 其他 Feedback 專用 metadata。

**experimentId** (`string`): 實驗或 eval run 識別碼。

**sourceId** (`string`): 此 Feedback 所連結的來源記錄 ID。

### `FeedbackFilter`

在 `listFeedback()` 及 OLAP 查詢的 `filters` 中使用 `FeedbackFilter`。

**timestamp** (`{ start?: Date; end?: Date; startExclusive?: boolean; endExclusive?: boolean }`): 按時間戳範圍篩選。

**traceId** (`string`): 按 Trace ID 篩選。

**spanId** (`string`): 按 span ID 篩選。

**feedbackType** (`string | string[]`): 按一個或多個 Feedback 類型篩選。

**feedbackSource** (`string`): 按 Feedback 來源篩選。

**source** (`string`): feedbackSource 已棄用的別名。

**feedbackUserId** (`string`): 按提供 Feedback 的用戶篩選。

**entityType** (`EntityType`): 按實體類型篩選。

**entityName** (`string`): 按實體名稱篩選。

**entityVersionId** (`string`): 按實體版本 ID 篩選。

**parentEntityType** (`EntityType`): 按上層實體類型篩選。

**parentEntityName** (`string`): 按上層實體名稱篩選。

**parentEntityVersionId** (`string`): 按上層實體版本 ID 篩選。

**rootEntityType** (`EntityType`): 按根實體類型篩選。

**rootEntityName** (`string`): 按根實體名稱篩選。

**rootEntityVersionId** (`string`): 按根實體版本 ID 篩選。

**userId** (`string`): 按人類終端用戶 ID 篩選。

**organizationId** (`string`): 按組織 ID 篩選。

**resourceId** (`string`): 按資源 ID 篩選。

**runId** (`string`): 按 run ID 篩選。

**sessionId** (`string`): 按 session ID 篩選。

**threadId** (`string`): 按 thread ID 篩選。

**requestId** (`string`): 按請求 ID 篩選。

**serviceName** (`string`): 按服務名稱篩選。

**environment** (`string`): 按環境篩選。

**executionSource** (`string`): 按執行來源篩選。

**experimentId** (`string`): 按實驗或 eval run 識別碼篩選。

**tags** (`string[]`): 按標籤篩選。相符記錄必須包含所有指定標籤。

## HTTP 路由

| 方法     | 路徑                                        | 用途                 | 權限                   |
| ------ | ----------------------------------------- | ------------------ | -------------------- |
| `GET`  | `/api/observability/feedback`             | 列出 Feedback 記錄     | 無衍生權限                |
| `POST` | `/api/observability/feedback`             | 建立一筆 Feedback 記錄   | 無衍生權限                |
| `POST` | `/api/observability/feedback/aggregate`   | 傳回一個彙總值            | `observability:read` |
| `POST` | `/api/observability/feedback/breakdown`   | 按維度將 Feedback 分組   | `observability:read` |
| `POST` | `/api/observability/feedback/timeseries`  | 按時間間距將 Feedback 分桶 | `observability:read` |
| `POST` | `/api/observability/feedback/percentiles` | 傳回百分位數序列           | `observability:read` |

## 相關內容

- [Feedback 指南](https://mastra.zisheng.pro/zh-HK/docs/observability/feedback)
- [用戶端 SDK 可觀測性參考資料](https://mastra.zisheng.pro/zh-HK/reference/client-js/observability)
- [可觀測性設定](https://mastra.zisheng.pro/zh-HK/reference/observability/tracing/configuration)