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

# 反馈

**新增于：** `@mastra/core@1.18.0`

反馈 API 用于存储和查询人在回路中的可观测性信号，例如评分、赞踩、评论和纠正。有关使用模式，请参阅[反馈指南](https://mastra.zisheng.pro/docs/observability/feedback)。

## 用法示例

以下示例通过可观测性入口为已持久化的 Trace 记录评分。入口中的 `addFeedback()` 是可选方法，因此调用前请确认当前可观测性实现支持该方法。

```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: 'Helpful answer.',
  },
})
```

## 创建反馈

### `addFeedback(args)`

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

```typescript
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)`

通过可观测性存储域创建一条反馈记录。存储层调用会直接写入存储，因此需要包含 `timestamp`。

```typescript
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` 时，该路由会自动生成：

```typescript
await mastraClient.createFeedback({
  feedback: {
    traceId: 'trace-123',
    spanId: 'span-456',
    feedbackSource: 'user',
    feedbackType: 'rating',
    value: 1,
  },
})
```

### `batchCreateFeedback(args)`

通过可观测性存储域创建多条反馈记录。HTTP 路由和 `@mastra/client-js` 不提供此方法。

```typescript
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?)`

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

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

**pagination** (`{ page?: number; perPage?: number }`): 分页模式的分页配置。page 从零开始计数。

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

**after** (`string`): 用于增量轮询的增量游标。仅在增量模式下有效。

**limit** (`number`): 增量模式下返回的最大更新数。

## OLAP 查询

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

### `getFeedbackAggregate(args)`

返回一个反馈聚合值。

```typescript
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)`

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

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

### `getFeedbackTimeSeries(args)`

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

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

### `getFeedbackPercentiles(args)`

返回按时间间隔分桶的百分位值。

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

## 类型

### `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` 与 `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`

在 `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 路由

| 方法     | 路径                                        | 用途         | 权限                   |
| ------ | ----------------------------------------- | ---------- | -------------------- |
| `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` |

## 相关内容

- [反馈指南](https://mastra.zisheng.pro/docs/observability/feedback)
- [客户端 SDK 可观测性参考](https://mastra.zisheng.pro/reference/client-js/observability)
- [可观测性配置](https://mastra.zisheng.pro/reference/observability/tracing/configuration)