> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/metrics.md).

# 指标

***

### 1. 在 Connect API 请求中启用指标

要在 WebRTC 数据通道上接收指标，请在调用 connect API 时设置 `debug` 到 `true` 。

HTTP 请求：

```http
POST https://live.convai.com/connect
X-Api-Key: <X-Api-Key>
Content-Type: application/json
```

请求正文：

```json
{
  "character_id": "<your character_id>",
  "debug": true
}
```

***

### 2. 在客户端接收指标

指标会作为 RTVI 消息通过 WebRTC 数据通道发送。

使用以下条件过滤传入消息：

* `label === "rtvi-ai"`
* `type === "metrics"`

***

### 3. 指标消息结构

#### A：TTFB 消息

```json
{
  "label": "rtvi-ai",
  "type": "metrics",
  "data": {
    "ttfb": [
      {
        "processor": "<PROCESSOR_INSTANCE>",
        "model": "<MODEL_NAME>",
        "value": "<TTFB_SECONDS>"
      }
    ]
  }
}
```

#### B：处理消息

```json
{
  "label": "rtvi-ai",
  "type": "metrics",
  "data": {
    "processing": [
      {
        "processor": "<PROCESSOR_INSTANCE>",
        "model": "<MODEL_NAME>",
        "value": "<PROCESSING_SECONDS>"
      }
    ]
  }
}
```

#### C：自定义（NeuroSync）消息

```json
{
  "label": "rtvi-ai",
  "type": "metrics",
  "data": {
    "custom": [
      {
        "processor": "<PROCESSOR_INSTANCE>",
        "model": "<MODEL_NAME>",
        "metric": "<CUSTOM_METRIC_NAME>",
        "value": "<CUSTOM_METRIC_VALUE>",
        "type": "NeuroSyncMetricsData"
      },
      {
        "processor": "<PROCESSOR_INSTANCE>",
        "model": "<MODEL_NAME>",
        "metric": "<CUSTOM_METRIC_NAME>",
        "value": "<CUSTOM_METRIC_VALUE>",
        "type": "NeuroSyncMetricsData"
      }
    ]
  }
}
```

说明：

* `data` 消息中只包含一个键（`ttfb` 或 `processing` 或 `custom`）。
* 在单个响应轮次中，你会收到多个指标消息。

***

### 4. 指标类型及含义

| 指标桶          | 位置                  | 含义                                | 单位 |
| ------------ | ------------------- | --------------------------------- | -- |
| `ttfb`       | `data.ttfb[]`       | 从处理器接收到第一条输入，到该处理器输出第一条结果的时间。     | 秒  |
| `processing` | `data.processing[]` | 该处理器在所发出的 span/turn 窗口内的总有效处理时间。  | 秒  |
| `custom`     | `data.custom[]`     | 自定义处理器指标（当前为 NeuroSync 的质量/吞吐信号）。 | 数字 |

条目字段：

* `processor` （字符串）：阶段实例标识符
* `model` （字符串，可选）：可用时的模型标识符
* `value` （数字）：指标值（或文档示例中的占位值）
* `metric` （字符串，仅自定义）：指标键，例如 `neurosync.output_fps`
* `type` （字符串，仅自定义）：当前 `NeuroSyncMetricsData`

当前发出的 NeuroSync 自定义指标：

* `neurosync.output_fps`
* `neurosync.blendshapes_received`
* `neurosync.blendshapes_sent`
* `neurosync.frames_dropped`

***

### 5. 查看指标的示例代码

```javascript
import { Room, RoomEvent } from "livekit-client";

const CORE_SERVICE_BASE_URL = "https://live.convai.com";
const API_KEY = "<X-Api-Key>";
const CHARACTER_ID = "<your character_id>";

async function startVoiceSessionAndWatchMetrics() {
  // 1) 调用启用了 debug 的 /connect
  const connectResp = await fetch(`${CORE_SERVICE_BASE_URL}/connect`, {
    method: "POST",
    headers: {
      "x-api-key": API_KEY,
      "content-type": "application/json",
    },
    body: JSON.stringify({
      character_id: CHARACTER_ID,
      debug: true,
    }),
  });

  if (!connectResp.ok) {
    throw new Error(`/connect failed: ${connectResp.status}`);
  }

  const connectData = await connectResp.json();
  const { room_url, token, session_id } = connectData;

  // 2) 使用 room_url + token 加入 WebRTC 房间
  const room = new Room();

  room.on(RoomEvent.Connected, () => {
    console.log("已连接到房间");
  });

  room.on(RoomEvent.DataReceived, (payload) => {
    // LiveKit 数据负载是字节 -> 解码 -> 解析 JSON
    let msg;
    try {
      const text = new TextDecoder().decode(payload);
      msg = JSON.parse(text);
    } catch {
      return;
    }

    // 3) 仅过滤 RTVI 指标消息
    if (msg?.label !== "rtvi-ai") return;
    if (msg?.type !== "metrics") return;

    const ttfb = msg?.data?.ttfb ?? [];
    const processing = msg?.data?.processing ?? [];
    const custom = msg?.data?.custom ?? [];

    console.log("RTVI 指标", { ttfb, processing, custom });
  });

  room.on(RoomEvent.Disconnected, () => {
    console.log("已断开与房间的连接");
  });

  await room.connect(room_url, token);

  // 返回对象，以便调用方稍后断开连接/清理
  return { room, session_id };
}

// 示例用法：
startVoiceSessionAndWatchMetrics().catch(console.error);
```

***

### 6. 使用说明

这些指标可在实时对话中提供每轮的即时上下文，并可作为实用的故障排查信号。当响应感觉变慢或质量下降时，此负载可帮助识别哪个阶段导致了最大的延迟（STT、LLM、TTS 或 NeuroSync）。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.convai.com/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/metrics.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.