跳到主要内容

反馈

反馈记录用于捕获人工参与环节中的信号，例如点赞、评分、评论和修正。当你需要将用户、QA、Studio 或系统审查数据附加到 Trace 或 span，并与其他可观测性信号一起查询时，可以使用反馈。

与指标和分数不同，反馈通常由人员或审查 Workflow 提供。数值反馈可以进行聚合、分组、按时间绘图和百分位查询。

何时使用反馈
何时使用反馈的直接链接

  • 收集用户对 Agent 响应的满意度评分。
  • 将 QA 评论或修正存储在其审查的 Trace 旁边。
  • 按 Agent、环境或实验构建评分仪表板。

添加反馈
添加反馈的直接链接

如果要从应用代码为已持久化的 Trace 或 span 添加注释，请使用 mastra.observability.addFeedback()。该 helper 在可观测性入口上是可选的，因此请检查当前可观测性实现是否支持它。所有客户端方法请参阅客户端 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
查找消息对应的 Trace的直接链接

反馈通常针对用户已经读过的消息收集，因此你需要该消息的 traceId。无论是在流结果中，还是之后从 memory 召回消息时，助手消息都会在 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。禁用 tracing 时生成的消息没有 traceId。

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

每次调用 createFeedback() 都需要 feedbackType 和 value。如果反馈需要锚定到 Trace 或特定 span，请添加 traceId 或 spanId。将 feedbackSource 用作可选字符串元数据，例如 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() 分页浏览原始记录，或使用 delta 模式轮询。

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

所有字段、过滤器、返回类型和百分位查询参数请参阅反馈参考。

将反馈导出到外部平台
将反馈导出到外部平台的直接链接

反馈会流经可观测性事件总线，因此支持反馈的 exporter 会自动转发。PostHog exporter 会将反馈作为原生 $ai_feedback 事件发送，并显示在 PostHog 中关联的 Trace 上。

On this page