> 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/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/choose-a-transport.md).

# 选择一种传输方式

为 Convai Web SDK 应用在 SSE、WebRTC 和 WebSocket 之间做出选择，查看推荐的 SSE 聊天加实时语音模式及其原因，并进行任一配置。

Convai Web SDK 通过三种传输方式连接角色，而一个 `ConvaiClient` 可以使用其中任意一种。你可以在本页选择一种，也可以按我们的建议组合使用 SSE 和实时传输。

* **SSE** 适用于简单聊天：输入文本，输出文本或音频。每条消息对应一个 HTTP 请求。
* **实时传输（WebRTC，默认）** 适用于对话：语音输入和输出、视频、屏幕共享、口型同步和低延迟。连接期间会话会保持打开状态。
* **WebSocket** 可在 WebRTC 受阻时传输实时语音，例如在某些 WebView 或屏蔽 UDP 的网络中。请参阅 [使用 WebSocket 传输方式](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/websocket-transport-layer.md).

{% hint style="warning" %}
SSE 使用的交互 API 目前处于 Beta 阶段。该 API 可在生产环境（`https://interaction-api.convai.com/v1/interactions`）、预发布环境（`https://interaction-api-stg.convai.com/v1/interactions`）以及自托管部署中访问。请参阅 [通过 SSE 传输方式聊天](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/sse-transport.md).
{% endhint %}

### 比较传输方式

|                    | 实时传输（WebRTC）        | WebSocket                | SSE                                      |
| ------------------ | ------------------- | ------------------------ | ---------------------------------------- |
| 输入文本，流式输出文本        | 是                   | 是                        | 是                                        |
| 角色语音（TTS）          | 是，以音轨形式提供           | 是                        | 是，以 PCM 数据块形式提供，由页面播放                    |
| 语音输入（麦克风）          | 是                   | 是                        | 否                                        |
| 通过说话打断             | 是                   | 是                        | 否； `sendInterruptMessage()` 会停止回复        |
| 视频和屏幕共享            | 是                   | 否                        | 否                                        |
| 口型同步混合变形           | 是                   | 是                        | 否                                        |
| 连接                 | 会话期间保持打开的房间         | 会话期间保持打开的套接字             | 消息之间无需保持连接                               |
| 麦克风权限提示            | 麦克风开启时              | 麦克风开启时                   | 从不                                       |
| 网络                 | WebRTC，默认使用 TURN 中继 | WebSocket                | 标准 HTTPS                                 |
| 可在 Node 或无服务器环境中运行 | 否                   | 否                        | 是                                        |
| 选择方式               | `url` （默认）          | `transport: 'websocket'` | `interactionApiUrl` 或 `transport: 'sse'` |

### 推荐：聊天使用 SSE，语音模式使用实时传输

每次对话都从 SSE 开始，仅在用户选择交谈时切换到实时传输。Convai Playground 在生产环境中就是这样运行角色聊天的。

* **大多数轮次都是通过键入文字进行的。** 使用 SSE 时，消息之间不会保持连接打开。实时会话会在连接期间持续保留一个房间，并运行角色的处理流水线；无论是否处于空闲状态，都会一直持续，直到服务器因不活动而关闭会话。
* **聊天会立即打开，无需任何操作。** SSE 的 `connect()` 不会发起网络请求，也不会请求访问麦克风。实时连接会创建一个房间，并等待角色先加入，这需要几秒钟。
* **它能在更多网络环境中正常工作。** SSE 使用常规 HTTPS。限制严格的网络可能会阻止 WebRTC。
* **角色仍然可以说话。** 启用 TTS 后，SSE 会在同一响应中流式传输每条回复的语音。
* **语音模式会保留对话内容。** 在实时模式下，使用相同的角色会话 ID 重新连接同一个客户端，可以延续对话；退出语音模式时则会反向进行。

#### 在 SSE 上设置文本聊天

将 `interactionApiUrl` 指向交互 API，或指向你自己的服务器路由，由该路由添加 API 密钥，这样密钥就不会传到浏览器。在用户开启之前，保持机器人音频关闭，并自行播放 `audioData` 分块。每个分块都是 base64 编码的有符号 16 位小端序 PCM，不含 WAV 标头；从分块中读取 `sample_rate` 和 `channels` 。

{% code title="chat.ts" %}

```ts
import { ConvaiClient } from '@convai/web-sdk/core';

const client = new ConvaiClient({
  apiKey: 'YOUR_API_KEY',
  characterId: 'YOUR_CHARACTER_ID',
  interactionApiUrl: 'YOUR_INTERACTION_API_URL',
  ttsEnabled: false,
});

const ctx = new AudioContext();
let botMuted = true;
let endsAt = 0;

client.on('audioData', ({ audio, sample_rate, channels }) => {
  if (botMuted) return;
  const bytes = Uint8Array.from(atob(audio), (c) => c.charCodeAt(0));
  const view = new DataView(bytes.buffer);
  const frames = bytes.length / 2 / channels;
  const buffer = ctx.createBuffer(channels, frames, sample_rate);
  for (let ch = 0; ch < channels; ch++) {
    const out = buffer.getChannelData(ch);
    for (let i = 0; i < frames; i++) out[i] = view.getInt16((i * channels + ch) * 2, true) / 0x8000;
  }
  const source = ctx.createBufferSource();
  source.buffer = buffer;
  source.connect(ctx.destination);
  const startAt = Math.max(endsAt, ctx.currentTime + 0.04);
  source.start(startAt);
  endsAt = startAt + buffer.duration;
});

// 将此功能绑定到扬声器按钮。通过点击取消静音，浏览器便可启动音频。
function setBotMuted(muted: boolean) {
  botMuted = muted;
  if (!muted) void ctx.resume();
  client.toggleTts(!muted);
}

await client.connect();
client.sendUserTextMessage('Hello!');
```

{% endcode %}

`botTurnCompleted` 会在最后一个分块传送完毕时触发，因此用户再次发送消息时，回复语音可能仍在播放。发送消息时停止排队的音频源，避免旧回复与新回复重叠播放。

#### 将对话切换到实时模式以启用语音模式

保存角色会话 ID，然后在实时模式下使用该 ID 重新连接同一客户端。连接后启用 TTS 并取消麦克风静音。麦克风可能需要几秒钟才能开始工作，因此请根据 `audioStateChange` 事件显示麦克风状态，该事件来自 `client.audioControls`.

{% code title="voice-mode.ts" %}

```ts
let sessionId: string | undefined;
client.on('characterSessionId', (id) => {
  sessionId = id;
});

async function enterVoiceMode() {
  await client.disconnect();
  await client.connect({
    apiKey: 'YOUR_API_KEY',
    characterId: 'YOUR_CHARACTER_ID',
    characterSessionId: sessionId,
    startWithAudioOn: false,
    ttsEnabled: false,
  });
  client.toggleTts(true);
  await client.audioControls.unmuteAudio();
}

async function exitVoiceMode() {
  await client.audioControls.muteAudio();
  await client.disconnect();
  await client.connect({
    apiKey: 'YOUR_API_KEY',
    characterId: 'YOUR_CHARACTER_ID',
    interactionApiUrl: 'YOUR_INTERACTION_API_URL',
    characterSessionId: sessionId,
    ttsEnabled: false,
  });
}
```

{% endcode %}

{% hint style="info" %}
`disconnect()` 会清除客户端的单次连接状态。切换期间，请在自己的状态中保留对话记录，并将下一次连接收到的消息追加进去，同时根据 `id`去除重复项。语音轮次会以 `user-transcription` 消息的形式到达。
{% endhint %}

### 基于单一传输方式构建

此处的建议是默认方案。每种传输方式也都可以单独使用。

#### 仅使用实时模式

如果语音是用户使用应用的主要方式，例如对话式虚拟形象、语音助手或信息亭，或者你需要视频、屏幕共享或唇形同步，请从第一条消息起就使用实时模式。连接等待只会发生一次，而且后续每轮交互都具有实时延迟。预构建的 `ConvaiWidget` 就是以这种方式运行的；请从 [Web SDK 快速入门](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/quickstart.md).

{% code title="realtime.ts" %}

```ts
import { ConvaiClient } from '@convai/web-sdk/core';

const client = new ConvaiClient({
  apiKey: 'YOUR_API_KEY',
  characterId: 'YOUR_CHARACTER_ID',
  startWithAudioOn: true,
});

await client.connect();
```

{% endcode %}

#### 仅使用 SSE

如果应用从不接收用户语音输入，例如聊天窗口、支持小组件或表单助手（无论角色是否使用语音回复），则单独使用 SSE。SSE 也是唯一能在浏览器之外运行的传输方式，因此可用于服务器端集成、CI 检查和批处理作业。在此处导入 `@convai/web-sdk/core` ；根入口和 `/react` 入口会加载仅限浏览器的代码。其配置方式与上文的文本聊天相同，只是不启用语音模式。

#### 使用 WebSocket 代替 WebRTC

本文提到实时模式时，如果 WebRTC 不可用，可以改用 WebSocket 传输。它支持语音和唇形同步，但不支持视频。请参阅 [使用 WebSocket 传输](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/websocket-transport-layer.md).

### 快速做出选择

| 你的应用                   | 使用                         |
| ---------------------- | -------------------------- |
| 主要是聊天，对话语音是可选功能        | SSE 搭配实时语音模式（推荐）           |
| 主要通过语音交互：虚拟形象、语音助手或信息亭 | 仅使用实时模式                    |
| 需要视频、屏幕共享或唇形同步         | 仅使用实时模式，或在需要这些功能的部分切换到实时模式 |
| 只接收文本输入，可选择是否使用语音回复    | 仅使用 SSE                    |
| 在服务器、CI 环境或批处理作业中运行    | 仅使用 SSE                    |
| 需要在 WebRTC 受阻的环境中使用语音  | WebSocket                  |


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/choose-a-transport.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
