智能体管理--实时音视频-火山引擎

文档中心

立即注册

导航

智能体管理

最近更新时间：2025.11.19 11:51:38首次发布时间：2025.09.01 21:29:30

智能体（Agent）是对话交互的核心，定义了设备的人设、技能和知识。

创建智能体

创建智能体，并配置对话所需的 LLM、ASR、TTS等服务。

前往硬件对话智能体_智能体管理，单击创建智能体，按照界面提示配置对话所需的 LLM、ASR、TTS 等服务。

详细配置说明，请参见配置智能体。

配置智能体

您可以在创建智能体的时候配置智能体，或在创建智能体后修改其配置。

操作入口：

创建智能体时配置：参见创建智能体。
修改已创建智能体的配置：
1. 在智能体管理页面，选择目标智能体，单击查看详情。
2. 在基本信息/智能体功能区域，单击编辑。

角色模板

角色模板根据不同场景预设了 LLM 模型、Prompt、语音合成音色以及欢迎语。您可以根据业务需求选择角色模板。

大模型 LLM

方舟大模型（推荐）

按照界面提示选择所需模型。部分模型支持关闭模型的深度思考模式，或启用视觉理解模型。

视觉理解相关配置，请参考视觉理解。

扣子模型

具体操作，以界面提示为准。

需注意：若使用扣子平台，所产生的 LLM Tokens 无法通过 License 或扩展资源抵扣。具体计费方式，请参考扣子_模型费用。

接入第三方大模型/Agent

请求 URL 需满足以下要求：
- 建议使用 HTTPS 域名，且必须支持公网访问。
- 必须符合火山引擎接口标准。您可通过接口验证工具验证接口是否符合标准。
如需传递非敏感的业务信息（如 session_id）：可以直接将它们作为查询参数拼接到此 URL 中，格式为：https://<第三方模型或Agent的API地址>?<业务自定义参数名>=<参数值>。
关于模型费用：若使用第三方大模型/Agent，所产生的 LLM Tokens 无法通过 License 或扩展资源抵扣。具体计费方式，以第三方大模型/Agent 计费为准。

视觉理解

接入视觉理解模型，使 AI 智能体能够理解实时视频画面或指定外部图片，从而实现感知环境、理解真人行为、图像问答等视觉交互。

使用前提：
- 目前仅火山方舟平台模型支持该功能，且模型需具备视觉理解能力。支持视频理解的模型，请参见视觉理解。
- Doubao-1.5 及之前系列的模型，不支持同时使用视觉理解能力和 Function Calling 功能。
启用视觉理解：
1. 打开视觉理解模型开关。
2. 确保为智能体关联的产品分配“视频处理”扩展资源。
  您需要先购买视频处理扩展资源，然后在 AI 服务购买与管理页面为产品分配“视频处理”扩展资源。

语音识别 ASR

支持选择以下模型：

火山引擎流式语音识别大模型
火山引擎流式语音识别

两者详细差异（如可识别语种、支持的能力等），请参见流式语音识别和流式语音识别大模型。

语音合成 TTS

模型	说明
语音合成	生成速度快，满足常规语音播报需求，适合短语或标准回复（如提醒、系统反馈）。
语音合成大模型	流式输入输出，相较于语音合成更生动、更具情感表现力，且支持多种合成音色。详细功能特性，参看大模型语音合成。
声音复刻大模型	流式输入输出，支持复刻真人音色，语音合成效果更自然。详细功能特性，参看大模型声音复刻。注意使用前，需先购买声音复刻扩展资源。

打断智能体

语音打断：默认开启。开启后，用户可通过语音来打断智能体说话。
关键词打断：为了防止误打断，您还可以单击高级配置，填入打断关键词。当识别到用户的语音中包括了预先设置的关键词时，智能体将被打断并停止输出。

语义判停

开启后，智能体将通过VAD+语义完整性判断来决定说话的时机，避免误打断用户说话的情况。

AI 降噪

当环境噪声较为明显时（如空调、风扇、键盘声），推荐开启 AI 降噪。

音频快速发送

开启后，可通过快速发送音频数据包以保障弱网环境下的传输稳定性和播报速度。

该功能需嵌入式 Linux SDK 版本不低于 1.57。

字幕或对话记录

您可以实时接收真人用户和智能体语音对话对应的文本内容，用于在应用终端显示实时字幕，或保存对话记录以便后续分析。支持通过服务端和客户端接收。

通过客户端实现

开启字幕接收。
1. 在智能体创建或配置页面，选择高级配置，并开启字幕显示。
2. 在客户端监听回调 on_volc_message_data 接收字幕结果。

解析字幕。
收到的字幕结果为二进制，使用前需解析。

字幕回调格式如下：

参数名	类型	描述
uid	String	消息发送者 ID。
message	String	二进制消息内容。与服务端返回二进制消息格式相同，详细参看二进制消息格式。

二进制消息格式

参数名	类型	描述
magic number	binary	消息格式，固定为 `subv`。
length	binary	字幕消息长度，单位为 bytes。存放方式为大端序。
subtitle_message	binary	字幕消息详细信息。格式参看subtitle_message 格式。

subtitle_message

参数名	类型	描述
type	String	消息格式，固定为 `subtitle`，表示消息类型为字幕。
data	data	字幕详细信息，包含字幕的文本、语言、说话人 ID 等具体信息。

data

参数名	类型	描述
text	String	字幕文本。
language	String	字幕语言。
userId	String	字幕来源者 ID。若字幕来源为真人用户，则该值为真人用户 UserId。若来源为智能体，则该值为智能体 UserId。
sequence	Int	字幕序号。
definite	Boolean	字幕是否为完整的分句。 true：是。 false：否。
paragraph	Boolean	字幕是否为完整的一句话。 true：是。 false：否。
roundId	Int	对话轮次。

subtitle_message 的示例如下：

{
"type": "subtitle",
"data" :[{
    "text": "上海天气炎热。气温为",
    "language": "zh",
    "userId": "bot1",
    "sequence":1,
    "definite":false,
    "paragraph":false,
    "roundId":1 
}]
}
{
"type": "subtitle",
"data" :[{
    "text": "上海天气炎热。气温为 30 摄氏度。",
    "language": "zh",
    "userId": "bot1",
    "sequence":2,
    "definite":true,
    "paragraph":false,
    "roundId":1 
}]
}

通过服务端实现

开启字幕接收。
1. 在智能体创建或配置页面，选择高级配置，在字幕显示区域配置以下参数：
  - ServerMessageUrl：接收字幕结果的 URL 地址，必须以域名开头。如果 URL 为 HTTPS 域名，请确保该域名 SSL 证书合法且完整。
  - ServerMessageSignature：鉴权签名。在接收到字幕结果后，与结果中的 signature字段值进行对比以进行鉴权验证。

解析字幕。
您指定的 URL 地址将收到来自服务器的 HTTP(S) POST 请求发送的字幕结果，格式为二进制，您需要阅读下文了解其结构进行解析。

收到的 HTTP(S) POST 请求的内容格式如下：

参数名	类型	描述
message	String	Base 64 编码的二进制消息内容。格式参看二进制消息格式。
signature	String	鉴权签名。可与步骤 1 传入的 `ServerMessageSignature` 字段值进行对比以进行鉴权验证。

二进制消息格式如下：

参数名	类型	描述
magic number	binary	消息格式，固定为 `subv`。
length	binary	字幕消息长度，单位为 bytes。存放方式为大端序。
subtitle_message	binary	字幕消息详细信息。格式参看subtitle_message 格式。

subtitle_message 格式：

参数名	类型	描述
type	String	消息格式，固定为 `subtitle`，表示消息类型为字幕。
data	data	字幕详细信息，包含字幕的文本、语言、说话人 ID 等具体信息。

data

参数名	类型	描述
text	String	字幕文本。
language	String	字幕语言。
userId	String	字幕来源者 ID。若字幕来源为真人用户，则该值为真人用户 UserId。若来源为智能体，则该值为智能体 UserId。
sequence	Int	字幕序号。
definite	Boolean	字幕是否为完整的分句。 true：是。 false：否。
paragraph	Boolean	字幕是否为完整的一句话。 true：是。 false：否。
roundId	Int	对话轮次。

subtitle_message 的示例如下：

{
"type": "subtitle",
"data" :[{
    "text": "上海天气炎热。气温为",
    "language": "zh",
    "userId": "bot1",
    "sequence":1,
    "definite":false,
    "paragraph":false,
    "roundId":1 
}]
}
{
"type": "subtitle",
"data" :[{
    "text": "上海天气炎热。气温为 30 摄氏度。",
    "language": "zh",
    "userId": "bot1",
    "sequence":2,
    "definite":true,
    "paragraph":false,
    "roundId":1 
}]
}

您可以参考以下示例代码对回调信息中的 message 内容进行解析。

const (
    subtitleHeader   = "subv"
    exampleSignature = "example_signature"
)

type RtsMessage struct {
    Message   string `json:"message"`
    Signature string `json:"signature"`
}

type Subv struct {
    Type string `json:"type"`
    Data []Data `json:"data"`
}

type Data struct {
    Definite  bool   `json:"definite"`
    Paragraph bool   `json:"paragraph"`
    Language  string `json:"language"`
    Sequence  int    `json:"sequence"`
    Text      string `json:"text"`
    UserID    string `json:"userId"`
}

func HandleSubtitle(c *gin.Context) {
    msg := &RtsMessage{}
    if err := c.BindJSON(&msg); err != nil {
       fmt.Printf("BindJson failed,err:%v\n", err)
       return
    }
    if msg.Signature != exampleSignature {
       fmt.Printf("Signature not match\n")
       return
    }

    subv, err := Unpack(msg.Message)
    if err != nil {
       fmt.Printf("Unpack failed,err:%v\n", err)
       return
    }

    fmt.Println(subv)

    //业务逻辑

    c.String(200, "ok")
}

func Unpack(msg string) (*Subv, error) {
    data, err := base64.StdEncoding.DecodeString(msg)
    if err != nil {
       return nil, fmt.Errorf("DecodeString failed,err:%v", err)
    }
    if len(data) < 8 {
       return nil, fmt.Errorf("Data invalid")
    }
    dataHeader := string(data[:4])
    if dataHeader != subtitleHeader {
       return nil, fmt.Errorf("Header not match")
    }
    dataSize := binary.BigEndian.Uint32(data[4:8])
    if dataSize+8 != uint32(len(data)) {
       return nil, fmt.Errorf("Size not match")
    }

    subData := data[8:]
    subv := &Subv{}
    err = json.Unmarshal(subData, subv)
    if err != nil {
       return nil, fmt.Errorf("Unmarshal failed,err:%v\n", err)
    }
    return subv, nil
}

func main() {

    r := gin.Default()
    r.POST("/example_domain/vertc/subtitle", HandleSubtitle)
    r.Run()
}

Function calling

使大模型识别用户对话中的特定需求，并调用外部函数实现天气查询、数学计算等功能。

仅支持在火山方舟模型平台的部分模型上使用。具体支持的模型，请参见支持的模型选型。

接收消息URL：接收结果的 URL 必须以域名开头。如果 URL 为 HTTPS 域名，请确保该域名 SSL 证书合法且完整。
接收消息签名：鉴权签名。在接收到字幕结果后，与结果中的 signature 字段值进行对比以进行鉴权验证。
创建工具：定义一个或多个可供 LLM 调用的函数工具。

关于工具构造及方舟 Function calling 的更多信息，请参见 Function calling。

为智能体关联产品

智能体创建并发布后，您可以将智能体与指定产品进行关联或更改关联。

操作入口：在智能体管理页面，找到目标智能体，单击编辑关联产品，可为智能体关联一个或多个产品，或取消关联某个产品。

接收智能体任务状态

通过服务端回调来获取智能体任务的状态变化（如任务开始/结束）和任务错误信息，从而实现精细化的任务监控和故障排查。适用于以下场景：

监听智能体任务状态
通过监听智能体任务状态，捕获用户结束说话、智能体回答完毕等关键节点，以便添加自定义业务逻辑，例如记录任务时长、更新客户端 UI 状态或触发下游数据分析流程等。
分析服务端耗时
通过比对不同状态回调的时间戳，分析 ASR、LLM、TTS 各个核心处理阶段的耗时，为性能体验优化提供数据支持。
排查智能体任务错误原因
当任务发生异常时，回调会提供错误码和错误信息，帮助您快速定位问题根源。

实现方式

前往功能配置，选择回调设置。
单击添加配置，按页面指引填写相关参数，其中回调事件选择 VoiceChat。
如无特殊需求则无需配置业务标识，否则可能导致无法正常收到回调消息。
配置完成后，当智能体任务状态变更或发生错误时，配置的 URL 将会收到推送事件回调消息（JSON 格式）。回调消息内容，参看回调消息说明。

回调消息说明

消息事件名称：VoiceChat，表示智能体任务状态变化。

事件详情：
EventData

参数名	类型	描述	示例值
AppId	String	音视频应用的唯一标识。	`661e****543cf`
BusinessId	String	业务标识。	`biz1`
RoomId	String	房间 ID，房间的唯一标识。	`room1`
TaskId	String	智能体任务 ID。	`task1`
UserID	String	说话人 UserId。	`user1`
RoundID	Int64	对话轮次。从 `0` 开始计数。	`0`
EventTime	Int64	该事件在 RTC 服务器上发生的 Unix 时间戳 (ms)。	`1611736812853`
EventType	Int64	任务状态类型。 `0`：智能体任务状态发生变化。 `1`：智能体任务出现错误。	`0`
RunStage	String	状态详情。 `taskStart`：任务开始。 `taskStop`：任务结束。 `beginAsking`：房间用户开始说话。 `asrFinish`：房间用户结束说话。 `answerFinish`：智能体说话完成。 `asr`：ASR 处理阶段。 `llm`：LLM 处理阶段。 `tts`：TTS 处理阶段。 `preParamCheck`：参数校验错误。	`preParamCheck`
ErrorInfo	ErrorInfo	任务错误详细信息。	-

ErrorInfo

参数名	类型	描述	示例值
Errorcode	Int	错误状态码。	`1001`
Reason	String	错误详细原因。	-

参数示例

{
    "AppId": "661e****543cf",
    "BusinessId": "biz1",
    "RoomId": "room1",
    "TaskId": "room1",
    "UserID": "user1",
    "RoundID": 0,
    "EventTime": 1611736812853,
    "EventType": 0,
    "RunStage": "taskStart",
    "ErrorInfo": {
        "Errorcode": 1001,
        "Reason": ""
    }
}