意見反饋

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

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

何時使用意見反饋

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

新增意見反饋

如要從應用程式程式碼為已持久化的 Trace 或 span 加上註解，請使用 mastra.observability.addFeedback()。此輔助函式在可觀測性進入點上屬選用，因此請檢查目前使用的可觀測性實作是否支援此函式。所有用戶端方法請參閱用戶端 SDK 可觀測性參考。

src/mastra/feedback.ts

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 中帶有此值；無論在串流結果中，還是稍後從記憶體取回訊息時都是如此：

src/mastra/message-trace.ts

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，因為此方法會直接寫入儲存區。

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() 分頁瀏覽原始記錄，或以增量模式輪詢。

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 等共用情境欄位。

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

查詢意見反饋分析

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

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

所有欄位、篩選條件、傳回類型及百分位數查詢參數，請參閱意見反饋參考。

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

意見反饋會流經可觀測性事件匯流排，因此支援意見反饋的匯出程式會自動轉送意見反饋。PostHog 匯出程式會將意見反饋以原生 $ai_feedback 事件傳送，並顯示在 PostHog 中已連結的 Trace 上。

相關內容

• 可觀測性概覽
• 追蹤概覽
• 指標概覽
• 用戶端 SDK 可觀測性參考
• 意見反饋參考