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

# 意見反饋

意見反饋記錄會擷取人機協作流程中的訊號，例如讚好或倒讚、評分、留言及修正。當你需要將用戶、QA、Studio 或系統的審查資料附加至 Trace 或 span，並連同其他可觀測性訊號一起查詢時，便可使用意見反饋。

意見反饋與指標和分數不同，通常由人員或審查 Workflow 提供。數值意見反饋可供彙總、分組、按時間繪製圖表，以及查詢百分位數。

## 何時使用意見反饋

- 收集用戶對 Agent 回應的滿意度評分。
- 將 QA 留言或修正儲存在其審查的 Trace 旁邊。
- 按 Agent、環境或實驗建立評分儀表板。

## 新增意見反饋

如要從應用程式程式碼為已持久化的 Trace 或 span 加上註解，請使用 `mastra.observability.addFeedback()`。此輔助函式在可觀測性進入點上屬選用，因此請檢查目前使用的可觀測性實作是否支援此函式。所有用戶端方法請參閱[用戶端 SDK 可觀測性參考](https://mastra.zisheng.pro/zh-HK/reference/client-js/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: 'The answer solved my issue.',
  },
})
```

## 尋找訊息的 Trace

意見反饋通常針對用戶已閱讀的訊息收集，因此你需要該訊息的 `traceId`。編程助手訊息會在 `content.metadata` 中帶有此值；無論在串流結果中，還是稍後從記憶體取回訊息時都是如此：

```typescript
const agent = mastra.getAgent('weatherAgent')
const memory = await agent.getMemory()

const { messages } = await memory!.recall({ threadId, perPage: false })

const message = messages.find(m => m.id === messageId)
const traceId = message?.content.metadata?.traceId
```

此值與執行結果中以 `traceId` 回報的 Trace 相同，因此在生成時收集的意見反饋，以及稍後針對已儲存訊息收集的意見反饋，都會連結至同一個 Trace。在停用追蹤期間產生的訊息不會有 `traceId`。

## 建立意見反饋

每次呼叫 `createFeedback()` 都需要 `feedbackType` 和 `value`。如要將意見反饋連結至某個 Trace 或特定 span，請加入 `traceId` 或 `spanId`。`feedbackSource` 可用作選用的字串 metadata，例如 `user`、`qa`、`studio` 或 `system`。

若直接寫入儲存層，請加入 `timestamp`，因為此方法會直接寫入儲存區。

```typescript
const observability = await mastra.getStorage()!.getStore('observability')

await observability!.createFeedback({
  feedback: {
    feedbackId: 'feedback-rating-1',
    timestamp: new Date(),
    traceId: 'trace-123',
    spanId: 'span-456',
    feedbackSource: 'user',
    feedbackType: 'rating',
    value: 1,
    comment: 'The answer solved my issue.',
    tags: ['production'],
  },
})

await observability!.createFeedback({
  feedback: {
    feedbackId: 'feedback-comment-1',
    timestamp: new Date(),
    feedbackSource: 'qa',
    feedbackType: 'comment',
    value: 'Needs a citation before shipping.',
    experimentId: 'support-agent-eval',
  },
})
```

## 列出意見反饋

使用 `listFeedback()` 分頁瀏覽原始記錄，或以增量模式輪詢。

```typescript
const result = await observability!.listFeedback({
  filters: {
    feedbackType: 'rating',
    feedbackSource: 'user',
    timestamp: { start: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000) },
  },
  pagination: { page: 0, perPage: 20 },
  orderBy: { field: 'timestamp', direction: 'DESC' },
})

console.log(result.feedback, result.pagination?.hasMore)
```

篩選條件包括 `traceId` 和 `spanId` 等目標欄位、`feedbackType`、`feedbackSource` 和 `feedbackUserId` 等意見反饋欄位，以及 `entityName`、`environment`、`experimentId` 和 `tags` 等共用情境欄位。

```typescript
await observability!.listFeedback({
  filters: {
    traceId: 'trace-123',
    feedbackType: ['rating', 'thumbs'],
    tags: ['production'],
  },
})
```

## 查詢意見反饋分析

OLAP 意見反饋查詢會對數值 `value` 欄位進行運算。這類查詢可用於評分、以 `1` 和 `-1` 編碼的讚好或倒讚、數值 QA 分數，或其他數值意見反饋類型。

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

const byAgent = await observability!.getFeedbackBreakdown({
  feedbackType: 'rating',
  groupBy: ['entityName'],
  aggregation: 'avg',
  filters: { environment: 'production' },
})

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

所有欄位、篩選條件、傳回類型及百分位數查詢參數，請參閱[意見反饋參考](https://mastra.zisheng.pro/zh-HK/reference/observability/feedback)。

## 將意見反饋匯出至外部平台

意見反饋會流經可觀測性事件匯流排，因此支援意見反饋的匯出程式會自動轉送意見反饋。[PostHog 匯出程式](https://mastra.zisheng.pro/zh-HK/reference/observability/tracing/exporters/posthog)會將意見反饋以原生 `$ai_feedback` 事件傳送，並顯示在 PostHog 中已連結的 Trace 上。

## 相關內容

- [可觀測性概覽](https://mastra.zisheng.pro/zh-HK/docs/observability/overview)
- [追蹤概覽](https://mastra.zisheng.pro/zh-HK/docs/observability/tracing/overview)
- [指標概覽](https://mastra.zisheng.pro/zh-HK/docs/observability/metrics/overview)
- [用戶端 SDK 可觀測性參考](https://mastra.zisheng.pro/zh-HK/reference/client-js/observability)
- [意見反饋參考](https://mastra.zisheng.pro/zh-HK/reference/observability/feedback)