---
title: 对接说明
description: 模型服务、外部 Agent 与实时语音通道的接入方式。
icon: plug
---

# 对接说明

## 模型服务

优先通过「组件库 / 模型资源」接入。接口定义会动态给出表单字段，凭证写入 `secrets`，普通参数写入 `values`。

| 场景 | 推荐接口类型 |
| --- | --- |
| 通用大模型、转写、合成、向量 | `openai-llm`、`openai-asr`、`openai-tts`、`openai-embedding` |
| 端到端实时语音 | `stepfun-realtime` 或 `qwen-audio-realtime` |
| 讯飞语音 | `xfyun-asr`、`xfyun-tts`、`xfyun-super-tts` |

讯飞接入需要将 `appId`、`apiKey`、`apiSecret` 写入 `secrets`，WebSocket 地址及音色等参数写入 `values`。

### 百炼双向流式 TTS

在模型资源中选择 `Alibaba Cloud Streaming TTS`（`dashscope-tts`），填写四个字段：

- `modelId`：Qwen-Audio-TTS 3.1/3.0 的 plus、flash，或 CosyVoice v3.5/v3 的 plus、flash、v2。
- `apiUrl`：北京为 `wss://<WorkspaceId>.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference`，其他地域使用对应业务空间域名。
- `apiKey`：对应地域和业务空间的 API Key。
- `voice`：与模型匹配的系统音色或已创建成功的音色 ID。CosyVoice v3.5 需要复刻或设计音色。

保留 `cosyvoice-v1` 配置兼容，但服务是否仍可用以账号实际调用为准。
已有资源若填写旧的 HTTP `/services/audio/tts` 地址，必须手动更新为上述 WebSocket 地址；种子文件更新不会覆盖已有数据库资源。

适配器逐段发送 LLM 文本，同时接收音频，每轮回复使用独立连接。固定请求 24 kHz 单声道 PCM，由服务适配到流水线采样率；不开放语速、情感、SSML 等高级参数。打断会关闭该轮连接。
“测试连接”会实际合成一句短文本，收到音频和完成事件才返回成功，会产生少量合成用量。

此接口不支持 Qwen3-TTS-Realtime、Sambert 或 MiniMax，它们需要不同协议适配。
协议参考：[百炼 WebSocket API](https://help.aliyun.com/zh/model-studio/cosyvoice-websocket-api)。

### Qwen-Audio Realtime

在「组件库 / 模型资源」中新建 `Alibaba Cloud Qwen-Audio Realtime` 资源：

- WebSocket URL 必须包含百炼业务空间 ID，例如 `wss://<WorkspaceId>.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime`。
- API Key 填写该业务空间可用的百炼密钥。
- MVP 支持 `server_vad` 与 `smart_turn`；前者可以调整 VAD 阈值和静音时长。
- 当前模型固定使用 16 kHz 单声道 PCM 输入、24 kHz 单声道 PCM 输出，管线会自动匹配采样率。

保存前可使用「测试连接」验证鉴权、地域、业务空间 ID 和模型是否匹配。

## 外部 Agent

创建助手时选择 「智能体平台」，接入 Dify 或 FastGPT：

- Dify：填写服务地址和 API Key。
- FastGPT：额外填写应用 ID。

外部 Agent 的上下文、知识库和工具由对方服务处理。

## 实时语音通道

以下是管理界面语音预览和既有自定义客户端使用的平台通道，需要管理员鉴权；它们不是对外的 OpenAI Realtime 兼容协议。新业务客户端优先参照[Realtime 兼容协议设计](/realtime-protocol)，使用 `/v1/realtime` WebSocket 或 `/v1/realtime/calls` WebRTC。

| 通道 | 地址 | 适用场景 |
| --- | --- | --- |
| WebRTC 信令 | `ws(s)://<host>/ws/voice` | 浏览器低延迟语音与视频输入。 |
| 裸音频 WebSocket | `ws(s)://<host>/ws/stream` | 服务端、话务网关或自定义客户端。 |

两个通道均使用管理员登录 Cookie 鉴权。推荐仅传 `assistant_id`，让服务端解析模型密钥；`inline_config` 仅用于调试。

### WebSocket 音频流启动

连接 `/ws/stream` 后，先发送一条文本 JSON，再发送二进制音频帧：

```json
{"assistant_id":"asst_xxx"}
```

WebRTC 在公网环境通常需要 TURN。设置 `STUN_URL`、`TURN_URLS` 和 `TURN_SECRET` 后，可通过 `GET /api/webrtc/ice-servers` 获取浏览器 ICE 配置。远程部署建议让 `STUN_URL` 指向同机 coturn，避免等待不可达的公共 STUN。