跳到主要内容

反馈

新增于： @mastra/core@1.18.0

反馈 API 用于存储和查询人在回路中的可观测性信号，例如评分、赞踩、评论和纠正。有关使用模式，请参阅反馈指南。

用法示例
用法示例的直接链接

以下示例通过可观测性入口为已持久化的 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.',
  },
})

创建反馈
创建反馈的直接链接

addFeedback(args)
addfeedbackargs的直接链接

通过可观测性入口向已持久化的 Trace 或 Span 添加反馈。

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

traceId?:

string
作为反馈目标锚点的 Trace。

spanId?:

string
作为反馈目标锚点的 Span。

correlationContext?:

CorrelationContext
用于发出反馈的实时 Span 或 Trace 上下文，无需从存储中重新载入目标。

feedback:

FeedbackInput
要添加的反馈负载。

createFeedback(args)
createfeedbackargs的直接链接

通过可观测性存储域创建一条反馈记录。存储层调用会直接写入存储，因此需要包含 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的直接链接

通过可观测性存储域创建多条反馈记录。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.',
    },
  ],
})

列出反馈
列出反馈的直接链接

listFeedback(args?)
listfeedbackargs的直接链接

以分页模式或增量模式返回反馈记录。

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
反馈记录的筛选条件。

orderBy?:

{ field?: 'timestamp'; direction?: 'ASC' | 'DESC' }
分页模式的排序配置。

after?:

string
用于增量轮询的增量游标。仅在增量模式下有效。

limit?:

number
增量模式下返回的最大更新数。

OLAP 查询
OLAP 查询的直接链接

OLAP 反馈查询针对数值型 value 字段执行操作。

getFeedbackAggregate(args)
getfeedbackaggregateargs的直接链接

返回一个反馈聚合值。

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

feedbackType:

string
要聚合的反馈类型。

feedbackSource?:

string
要聚合的反馈来源。

aggregation:

'sum' | 'avg' | 'min' | 'max' | 'count' | 'count_distinct' | 'last'
要应用的聚合方式。

filters?:

FeedbackFilter
其他筛选条件。

comparePeriod?:

'previous_period' | 'previous_day' | 'previous_week'
可选的环比比较周期。

getFeedbackBreakdown(args)
getfeedbackbreakdownargs的直接链接

返回按维度分组的反馈值。

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

getFeedbackTimeSeries(args)
getfeedbacktimeseriesargs的直接链接

返回按时间间隔分桶的反馈值。

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
此反馈事件的唯一 ID。省略时由服务端路由生成。

timestamp:

Date
记录反馈的时间。

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
反馈记录的用户自定义元数据。

共享上下文字段
共享上下文字段的直接链接

反馈记录可以包含共享的可观测性上下文字段，用于筛选、分组，以及与 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
更广泛的资源上下文。

runId?:

string | null
执行运行标识符。

sessionId?:

string | null
用于对 Trace 分组的会话标识符。

threadId?:

string | null
对话线程标识符。

requestId?:

string | null
用于关联的 HTTP 请求 ID。

environment?:

string | null
部署环境。

serviceName?:

string | null
服务名称。

scope?:

Record<string, unknown> | null
包、应用版本或部署元数据。

entityVersionId?:

string | null
产生该信号的实体版本 ID。

parentEntityVersionId?:

string | null
父实体的版本 ID。

rootEntityVersionId?:

string | null
根实体的版本 ID。

experimentId?:

string | null
实验或评估运行标识符。

executionSource?:

string | null
执行来源，例如本地、云端或 CI。

tags?:

string[] | null
用于筛选的标签。

FeedbackInput
feedbackinput的直接链接

将 FeedbackInput 与 mastra.observability.addFeedback()、recordedTrace.addFeedback() 和 recordedSpan.addFeedback() 配合使用。

feedbackSource?:

string
反馈的可选来源元数据。

source?:

string
feedbackSource 的已弃用别名。

feedbackType:

string
要记录的反馈类型。

value:

number | string
要记录的反馈值。

comment?:

string
补充评论或上下文。

feedbackUserId?:

string
提供反馈的用户。

userId?:

string
feedbackUserId 的已弃用别名。

metadata?:

Record<string, unknown>
其他反馈专用元数据。

experimentId?:

string
实验或评估运行标识符。

sourceId?:

string
此反馈所关联的来源记录 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[]
按一种或多种反馈类型筛选。

feedbackSource?:

string
按反馈来源筛选。

source?:

string
feedbackSource 的已弃用别名。

feedbackUserId?:

string
按提供反馈的用户筛选。

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
按运行 ID 筛选。

sessionId?:

string
按会话 ID 筛选。

threadId?:

string
按线程 ID 筛选。

requestId?:

string
按请求 ID 筛选。

serviceName?:

string
按服务名称筛选。

environment?:

string
按环境筛选。

executionSource?:

string
按执行来源筛选。

experimentId?:

string
按实验或评估运行标识符筛选。

tags?:

string[]
按标签筛选。匹配的记录必须包含所有指定标签。

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