跳至主要內容

Feedback

新增於： @mastra/core@1.18.0

Feedback API 會儲存及查詢人工介入的可觀測性訊號，例如評分、讚好／不讚好、留言及修正。使用模式請參閱 Feedback 指南。

使用範例
使用範例 的直接連結

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

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
建立 Feedback 的直接連結

addFeedback(args)
addfeedbackargs 的直接連結

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

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)
createfeedbackargs 的直接連結

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

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

列出 Feedback
列出 Feedback 的直接連結

listFeedback(args?)
listfeedbackargs 的直接連結

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

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 記錄的篩選條件。

orderBy?:

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

after?:

string
增量輪詢所用的增量游標。只適用於增量模式。

limit?:

number
在增量模式中傳回的更新數目上限。

OLAP 查詢
OLAP 查詢 的直接連結

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

getFeedbackAggregate(args)
getfeedbackaggregateargs 的直接連結

傳回一個彙總 Feedback 值。

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)
getfeedbackbreakdownargs 的直接連結

傳回按維度分組的 Feedback 值。

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

getFeedbackTimeSeries(args)
getfeedbacktimeseriesargs 的直接連結

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

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

getFeedbackPercentiles(args)
getfeedbackpercentilesargs 的直接連結

傳回按時間間距分桶的百分位數值。

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

類型
類型 的直接連結

FeedbackRecord
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 欄位
共用 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 的直接連結

將 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
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 路由
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
On this page