实时音视频
实时音视频
文档指南
请输入
- 文档首页
实时音视频AI 音视频互动方案开发指南配置 ASR/LLM/TTS 服务接入第三方大模型或 Agent
复制全文
下载 pdf接入第三方大模型或 Agent
文档反馈
问问助手在对话式 AI 场景中，除了集成火山方舟和 Coze 平台模型外，您还可以接入自研或第三方的大模型/Agent（如 Dify Agent），以满足特定业务需求。
快速接入
1. 准备服务接口
准备一个符合如下标准的模型接口 URL：
- 支持公网访问，且必须使用 HTTPS 域名。
- 支持流式返回（SSE 协议），并以 data: [DONE] 结束。
- 系统请求该 URL 的响应超时时间为 10 秒，请确保您的服务能在此时间内响应。
2. 配置 StartVoiceChat
调用 StartVoiceChat 接口，按照规定参数结构配置 LLMConfig。LLMConfig 最小化配置示例如下：
- 完整参数参见接口文档 StartVoiceChat（2025-06-01）。
- 如果需要在每次请求时传递简单的业务标识（如 session_id 或 source），可以直接将参数作为 Query String 拼接在 Url 后。例如：https://api.my-custom-agent.com/v1/chat-stream?session_id=12345。如需传递更复杂的自定义数据，请参考传入自定义数据。
{
"Config": {
"LLMConfig": {
"Mode": "CustomLLM", // 必填，固定值
"Url": "https://api.my-custom-agent.com/v1/chat-stream", // 必填，您的服务地址
"APIKey": "bearer-token-for-my-agent" // 可选，鉴权 Token
}
// ... 其他配置
}
}
进阶配置
上下文管理
降低延迟（Prefill 策略）
将 Prefill 参数设置为 true，将 ASR 的中间识别结果提前发送给您的 LLM，让 LLM 提前生成回复，从而降低用户的感知延迟。
开启此功能会增加您模型的调用消耗。
视觉和图片理解
配置 MCP
通过 MCP（模型上下文协议），您可以将知识库问答（RAG）、联网搜索、业务 API 调用等外部服务封装为标准化工具，让 LLM 在对话中能智能地调用它们，以获取所需的数据或执行操作，并基于返回的结果生成更准确、专业的回复。具体实现方式，请参见接入 MCP。
Function calling
拼接参数
如果需要在每次请求时传递非敏感的业务信息（如 session_id），可以直接将它们作为查询参数拼接到 LLMConfig.Url中。
- 格式：https://<第三方模型或Agent的API地址>?<业务自定义参数名>=<参数值>。
- 示例：https://api.my-custom-agent.com/v1/chat-stream?session_id=12345。
传入自定义数据
您可以通过多种方式向第三方 LLM 服务透传自定义业务数据。
方式一：透传全局配置
如果你需要在整个智能体任务生命周期内传递固定参数（如用户标签、业务 ID 等），可以在调用 StartVoiceChat 时，通过 LLMConfig 中的以下字段传入：
- Custom：一个自定义的 JSON 字符串，会透传到 LLM 请求体的 custom 字段中。
- ExtraHeader：一个 JSON 对象，其键值对将作为额外的 HTTP Header 字段透传到 LLM 请求中。
{
"Config": {
"LLMConfig": {
"Mode": "CustomLLM",
"Url": "https://api.example.com/chat",
// 1. 通过 Custom 字段透传 JSON 字符串，对应 LLM 请求体的 custom 字段
"Custom": "{\"user_level\": \"vip\", \"biz_id\": \"order_123\"}",
// 2. 通过 ExtraHeader 透传自定义 HTTP Header
"ExtraHeader": {
"X-Custom-Source": "mobile_app",
"X-Client-Version": "1.0.0"
}
}
}
}
方式二：通过客户端动态透传
你可以在客户端发送自定义数据（如业务数据、算法检测结果等），这些数据会被缓存并跟随下一轮对话的 HTTP 请求（而非立即触发）透传给第三方 LLM 作为回复上下文，且不会被 TTS 直接朗读。
该功能适用于需要客户端与 LLM 进行实时业务数据交换的场景。例如：
- 游戏互动：客户端将玩家的实时状态（如生命值、位置）传给 LLM，LLM 根据此状态返回相应的游戏策略或对话，并通过回传的数据触发客户端的特定游戏事件。
- 情绪同步：客户端通过摄像头或传感器检测到用户情绪，将 “开心” 或 “难过” 等状态传给 LLM，LLM 在生成回复的同时，回传一个指令让客户端的虚拟形象做出相应的表情。
注意
该功能不支持 LLM 主动下发未经客户端请求的业务数据。如果您仅在 LLM 响应中单方面添加 X-Biz-Trace-Info 字段，可能出现非预期的结果。若您仅需 LLM 主动向客户端下发简单的文本指令，可通过传递自定义指令来实现。
- 客户端发送数据。
- 在客户端调用 RTC SDK 接口 发送自定义数据。
说明
客户端发送的数据不会立即推送给 LLM 服务。数据会被缓存，并在下一轮对话请求发生时，包含在 HTTP 请求体中一并透传。
- userId：填入 AI 的标识 ID（即 StartVoiceChat 配置的 AgentConfig.UserId）。
- buffer：需遵循 TLV 二进制格式：
-
-
- trace_data
-
-
- 客户端接收回传数据。
- 当 ASR 识别到用户说话并触发下一轮 LLM 请求时，系统会将缓存的自定义数据放入 HTTP 请求体的 X-Biz-Trace-Info 字段中转发给您的 LLM 服务。您可以在响应中返回该字段，系统会将其作为 trac 消息广播给客户端。在客户端监听 RTC SDK 的 （以 Android 为例）即可接收到从 LLM 回传的数据。
- 消息格式：
-
- 解析方式：可参考实时字幕（对话记录）的解析示例，将 magic number 校验改为 trac 获取最新的业务数据。
接口标准
在对话期间，将按照以下格式通过 POST 请求访问你配置的第三方大模型或 Agent 的接口地址，获取相应结果。接口返回需支持 SSE 协议。
Request
- Method: POST
- Headers:
- Content-Type: application/json
- Authorization: Bearer <your_APIKey> （当需要 Bearer Token 认证方式鉴权大模型时）
- Request body:
-
-
Response
注意
- 协议：必须支持 SSE（Server-Sent Events）协议。
- Headers：Content-Type 必须为 text/event-stream。
- 结束符：必须包含 data: [DONE] 结束符，表示模型本轮回答结束。
StatusCode==200
成功请求及返回样例如下：
curl -v --location 'https://rtc-cloud-rendering.byted.org/voicechat/test-sse' \
--header 'Content-Type: application/json' \
--data '{
"messages":[{
"role":"user",
"content":"今天适合干什么？"
}],
"stream": true,
"temperature": 0.1,
"max_tokens": 100,
"top_p": 0.9,
"model": "doubao-32k",
"stream_options": {"include_usage":true}
}'
> POST /voicechat/test-sse HTTP/1.1
> Host: rtc-cloud-rendering.byted.org
> User-Agent: curl/8.4.0
> Accept: */*
> Content-Type: application/json
> Content-Length: 254
>
< HTTP/1.1 200 OK
< Date: Thu, 15 Aug 2024 09:36:02 GMT
< Content-Type: text/event-stream
< Transfer-Encoding: chunked
< Connection: keep-alive
< Access-Control-Allow-Origin: *
< Cache-Control: no-cache
data: {"id":"c99d67a4-5ae9-11ef-bdf5-b8cef6dcdbe2","object":"chat.completion.chunk","choices":[{"finish_reason":null,"index":0,"delta":{"role":"assistant"}}],"model":"doubao-32k-2024-07-25","created":1723714562}
data: {"id":"c99d67a4-5ae9-11ef-bdf5-b8cef6dcdbe2","object":"chat.completion.chunk","choices":[{"finish_reason":null,"index":1,"delta":{"content":"天"}},{"finish_reason":null,"index":0,"delta":{"content":"从明"}}],"model":"doubao-32k-2024-07-25","created":1723714562}
data: {"id":"c99d67a4-5ae9-11ef-bdf5-b8cef6dcdbe2","object":"chat.completion.chunk","choices":[{"finish_reason":null,"index":0,"delta":{"content":"起，"}}],"model":"doubao-32k-2024-07-25","created":1723714562}
data: {"id":"c99d67a4-5ae9-11ef-bdf5-b8cef6dcdbe2","object":"chat.completion.chunk","choices":[{"finish_reason":null,"index":1,"delta":{"content":"幸福"}},{"finish_reason":null,"index":0,"delta":{"content":"做一个"}}],"model":"doubao-32k-2024-07-25","created":1723714562}
data: {"id":"c99d67a4-5ae9-11ef-bdf5-b8cef6dcdbe2","object":"chat.completion.chunk","choices":[{"finish_reason":null,"index":0,"delta":{"content":"的"}}],"model":"doubao-32k-2024-07-25","created":1723714562}
data: {"id":"c99d67a4-5ae9-11ef-bdf5-b8cef6dcdbe2","object":"chat.completion.chunk","choices":[{"finish_reason":null,"index":0,"delta":{"content":"人"}}],"model":"doubao-32k-2024-07-25","created":1723714562}
data: {"id":"c99d67a4-5ae9-11ef-bdf5-b8cef6dcdbe2","object":"chat.completion.chunk","choices":[{"finish_reason":null,"index":0,"delta":{"content":"。"}}],"model":"doubao-32k-2024-07-25","created":1723714562}
data: {"id":"c99d67a4-5ae9-11ef-bdf5-b8cef6dcdbe2","object":"chat.completion.chunk","choices":[{"finish_reason":null,"index":0,"delta":{"content":"喂马，"}}],"model":"doubao-32k-2024-07-25","created":1723714562}
data: {"id":"c99d67a4-5ae9-11ef-bdf5-b8cef6dcdbe2","object":"chat.completion.chunk","choices":[{"finish_reason":null,"index":0,"delta":{"content":"劈柴，"}},{"finish_reason":null,"index":1,"delta":{"content":"周游"}}],"model":"doubao-32k-2024-07-25","created":1723714562}
data: {"id":"c99d67a4-5ae9-11ef-bdf5-b8cef6dcdbe2","object":"chat.completion.chunk","choices":[{"finish_reason":null,"index":0,"delta":{"content":"世界"}},{"finish_reason":null,"index":1,"delta":{"content":"。"}}],"model":"doubao-32k-2024-07-25","created":1723714562}
data: {"id":"c99d67a4-5ae9-11ef-bdf5-b8cef6dcdbe2","object":"chat.completion.chunk","choices":[{"finish_reason":"stop","index":0,"delta":{}}],"model":"doubao-32k-2024-07-25","created":1723714562,"usage":{"prompt_tokens":1,"completion_tokens":2,"total_tokens":3}}
data: [DONE]
StatusCode==4xx、5xx
请求终止，报错返回。RTC 不做任何处理，仅报错。
参数 | 类型 | 必填 | 描述 |
Error | object | 是 | 错误详情。 |
Error
参数 | 类型 | 必填 | 描述 |
Code | String | 是 | 错误码。 |
Message | String | 是 | 错误原因。 |
响应示例：
{
"Error": {
"Code": "AuthenticationError",
"Message": "The API key or AK/SK in the request is missing or invalid. "
}
}
StatusCode!==200、4xx、5xx
此时 RTC 不做任何处理，仅报错，直接报错返回 StatusCode。
验证接口
你可以使用工具验证第三方大模型或 Agent 的请求接口是否符合标准规范。
验证工具仅支持在 Linux 和 macOS 系统上使用。
- 下载验证工具包并解压。
- 执行验证命令（Linux/macOS）。
- 如果你使用 zsh 终端，且 URL 中包含特殊字符（如 ?、=、& 等）时，必须对特殊字符进行转义。
- # 语法：./app-<os> <API地址> <模型名称> <APIKey> <测试问题># macOS./app-mac https://api.example.com/chat my-model sk-xxxxxx "你好"# Linux./app-linux https://api.example.com/chat my-model sk-xxxxxx "你好"
执行结果类似如下所示，表示验证通过：
- OpenAI
-
- 自定义 URL
-
FAQ
Q1：是否支持在本地环境调用或测试验证第三方大模型或 Agent 的接口？
支持。
Q2：多轮对话的 HistoryLength 未生效，每次请求只传递了最新一条对话内容？
可以尝试以下排查：
- 检查你的大模型接口是否支持多轮历史对话。
- 请检查您的接口返回中是否包含了标准的 data: [DONE] 结束符。如果缺失该结束符，系统可能无法判定一轮对话结束，从而导致上下文存储失败。
最近更新时间：2026.09.21 16:24:31
这个页面对您有帮助吗？
有用
有用
无用
无用