You need to enable JavaScript to run this app.
导航
实时音视频
  • 文档首页
    • /实时音视频/实时对话式 AI/进阶功能/接入第三方大模型或 Agent
接入第三方大模型或 Agent
最近更新时间：2025.11.19 11:47:50首次发布时间：2024.12.17 17:10:35
复制全文
我的收藏
有用
有用
无用
无用

在实时对话式 AI 场景中，除了集成火山方舟和 Coze 平台外，还支持您接入自研或第三方的大模型/Agent（如 Dify Agent），以满足特定业务需求。

接入方法

接入步骤

  1. 准备第三方大模型或 Agent 的请求接口 URL，并满足以下要求：

    • 推荐使用 HTTPS 域名，并支持公网访问。
    • 必须符合火山引擎 接口标准。你可通过 接口验证工具 验证接口是否符合标准。

  2. 调用 StartVoiceChat 接口，按照规定参数结构配置 LLMConfig。

    详细参数说明，请参见 StartVoiceChat。

    功能StartVoiceChat 配置字段说明

    核心接入参数

    服务类型Mode （必填）固定值 CustomLLM，以启用第三方模型模式。
    指定服务地址Url （必填）你的模型/Agent 的 HTTPS 服务接口地址。
    Bearer Token鉴权APIKey如果你的接口需要 Bearer Token，系统自动添加 Authorization Header。

    传入自定义请求、header、业务参数

    自定义 HeaderExtraHeader透传任意自定义 HTTP Header，用于复杂鉴权或业务逻辑。
    自定义 Query 参数(拼接在 Url 后)可在 Url 后拼接 ?key=value 来传递非敏感业务参数，格式为：https://<第三方模型或Agent的API地址>?<业务自定义参数名>=<参数值>
    自定义业务参数Custom可通过此 JSON 字符串字段，向你的接口请求体中透传自定义的业务数据。

    其他配置

    模型参数透传ModelName、Temperature、TopP、MaxTokens系统将这些标准模型参数透传到你接口的请求体中。
    上下文管理SystemMessages、UserPrompts、HistoryLength对话上下文由这三个字段共同控制系统。具体说明，参看第三方大模型上下文管理机制
    视觉理解VisionConfig将实时视频帧或外部图片数据发送给你的模型接口，从而实现感知环境、理解真人行为、图像问答等视觉交互。详细使用说明，请参见 视觉理解能力。
    Prefill 策略Prefill将 ASR 的中间识别结果提前发送给你的模型，以降低延迟。
    对话轮次EnableRoundId在请求体中加入字段 round_id，你可以解析该字段，用于日志追踪、问题排查和数据审计等。

配置示例

以下是一个 LLMConfig 配置示例。

{
    // ... AppId, RoomId, TaskId ...
    "Config": {
        // ... ASRConfig, TTSConfig ...
        "LLMConfig": {
            "Mode": "CustomLLM",
            "Url": "https://api.my-custom-agent.com/v1/chat-stream?user_tier=premium",
            "APIKey": "bearer-token-for-my-agent",
            "ExtraHeader": {
                "X-Request-Source": "RTC-VoiceChat"
            },
            "ModelName": "my-vertical-model-v2",
            "Temperature": 0.5,
            "HistoryLength": 5,
            "SystemMessages": [
                "你是一个专业的法律顾问，回答问题时请引用法条。"
            ],
            "UserPrompts": [
                { "Role": "user", "Content": "你好" },
                { "Role": "assistant", "Content": "您好，请问有什么法律问题可以帮您？" }
            ],
            "Custom": "{\"case_id\":\"2024-A-567\"}",
            "EnableRoundId": true
        }
    },
    // ... AgentConfig ...
}
接口标准

在对话期间，将按照以下格式通过 POST 请求访问你配置的第三方大模型或 Agent 的接口地址，获取相应结果。接口返回需支持 SSE 协议。

Request

  • Method: POST

  • Headers:

    • Content-Type: application/json
    • Authorization: Bearer <your_APIKey> （当需要 Bearer Token 认证方式鉴权大模型时）

  • Request body:

    参数类型必填描述
    messagesArray of messages是参考 StartVoiceChat.HistoryLength，包含最近 HistoryLength 轮对话内容。当前 ASR 内容在数组末位。
    streamBoolean否取值：true。
    temperatureFloat否透传 StartVoiceChat.LLMConfig.temperature。
    max_tokensInt否透传 StartVoiceChat.LLMConfig.MaxTokens。
    modelString是透传 StartVoiceChat.LLMConfig.ModelName。
    top_pFloat否透传 StartVoiceChat.LLMConfig.TopP。
    customString否自定义 JSON 字符串，透传业务传入的自定义参数。

    messages

    参数类型必填描述
    roleString是可取值及含义如下：
    • user
    • assistant
    contentString否对话内容。

Response

注意

  • 协议：必须支持 SSE（Server-Sent Events）协议。
  • Headers：Content-Type 必须为 text/event-stream。
  • 结束符：必须包含 data: [DONE] 结束符。收到这个结束符系统才会把大模型的文本提交给 TTS 合成音频。

StatusCode==200

参数类型必填描述
idString是请求 UUID。不同请求的 ID 需不同，但同一个流式请求的 ID 需相同。
choicesArray of choices是流式回复对象。
createdInt是UnixTime 时间戳，精确到秒。同一个请求的流式所有块拥有相同的时间戳。
usageObject of usage否最后一个包可带此参数。
objectString是取值：chat.completion.chunk。填错将导致接口行为异常。
modelString是模型 ID。
stream_optionsobject of stream_options是流接口选项。

Choices

参数类型必填描述
finish_reasonString是
  • null：流式请求未结束。
    最后一个流式片段需填入以下值：
    • stop：正常结束。
    • length：达到 MaxTokens。
    • content_filter：内容不合规。
    • deltaObject of delta是流式片段对象。
    indexInt是数组中位置，从 0 开始。

    delta

    参数类型必填描述
    contentString是对话内容。
    roleString是可取值及含义如下：
    • user
    • assistant

    usage

    参数类型必填描述
    completion_tokensInt是generated tokens 长度。
    prompt_tokensInt是prompt tokens 长度。
    total_tokensInt是prompt+generated tokens 长度。

    stream_options

    参数类型必填描述
    include_usageBoolean是固定为 true，表示流式传输。

    成功请求及返回样例如下：

    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 不做任何处理，仅报错。

    参数类型必填描述
    ErrorError是错误详情。

    Error

    参数类型必填描述
    CodeString是错误码。
    MessageString是错误原因。

    StatusCode!==200、4xx、5xx

    此时 RTC 不做任何处理，仅报错，直接报错返回 StatusCode。

    使用工具验证第三方大模型或 Agent 的请求接口

    你可以使用工具验证第三方大模型或 Agent 的请求接口是否符合标准规范。如果符合要求，工具可以返回大模型或 Agent 预期的输出结果，否则将返回错误信息。

    注意

    目前验证工具仅支持在 Linux 和 macOS 系统上使用。

    下载和使用工具

    1. 下载验证工具包并解压。
      Archive.zip
      8.16MB
    2. 通过终端，使用 cd 命令进入工具包所在目录。
    3. 执行验证命令。

      注意

      如果你使用 zsh 终端，且 URL 中包含特殊字符（如 ?、=、& 等）时，必须对特殊字符进行转义。

      • Linux
        ./app-linux <llmAPIUrl> <llmModel> <llmAPIKey> <LLMQuestion>
      • macOS
        ./app-mac <llmAPIUrl> <llmModel> <llmAPIKey> <LLMQuestion>
      参数说明如下：
      参数名类型是否必填描述示例
      llmAPIUrlString是第三方大模型或 Agent 的完整请求 URL。https://api.cn/v1/chat/completion
      llmModelString否第三方大模型或 Agent 的名称。默认值为空。model-v1-chat
      llmAPIKeyString否APIKey。默认值为空。sk-0aeQbtlX2reL
      LLMQuestionString否发送给第三方大模型或 Agent 的测试问题。你好

    验证示例

    执行结果类似如下所示，表示验证通过：

    • openAI
    • 自定义 URL
    FAQ

    Q1：是否支持在本地环境调用和测试验证对话式 AI 第三方大模型或 Agent 接口？

    支持。

    Q2：使用第三方大模型时，设置的多轮历史对话 HistoryLength 未生效，每次请求只传递了最新一条对话内容怎么办？

    可以尝试以下排查：

    1. 检查你的大模型接口是否支持多轮历史对话。
    2. 确认第三方大模型的响应中是否包含正确的请求结束标识 data: [DONE]。如果第三方服务没有在响应末尾返回此结束符，系统可能无法正确识别一次完整请求的结束，从而无法正确地存储和使用历史对话记录。