指标

此页面说明通过 WebRTC 数据通道发送给客户端的指标。

---

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

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

HTTP 请求：

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

请求正文：

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

---

2. 在客户端接收指标

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

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

• label === "rtvi-ai"
• type === "metrics"

---

3. 指标消息结构

A：TTFB 消息

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

B：处理消息

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

C：自定义（NeuroSync）消息

{
  "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. 查看指标的示例代码

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）。