上下文管理--实时音视频-火山引擎

文档中心

立即注册

导航

上下文管理

最近更新时间：2025.11.19 11:47:50首次发布时间：2025.04.01 17:09:08

上下文管理能让智能体在单次的连续多轮对话中，记录并理解历史对话内容，从而做出更精准连贯的回复。支持在发起对话时设置基础上下文作为初始信息，或在对话过程中动态传入上下文，实时补充背景信息或通过文本直接发起提问。

说明

上下文管理主要用于实现智能体的短期记忆，即在单次连续对话中理解历史对话。如果要实现跨对话的长期记忆（如记住用户偏好），可接入火山记忆库。详细实现方法，请参见接入记忆库。

传入基础上下文

在发起对话时，通过 StartVoiceChat 接口为智能体设定初始的上下文信息。不同的大模型平台，其上下文管理机制有差异。

火山方舟 / 第三方大模型

上下文机制

使用火山方舟平台时，模型对话上下文生成逻辑由系统提示词（SystemMessages）、用户提示词（UserPrompts/UserMessages）和历史问题轮数（HistoryLength）共同控制。

参数名	类型	说明
`SystemMessages`	String[]	系统提示词。定义模型的角色、行为准则及输出格式等核心指令。
`UserPrompts`	Object[]	用户提示词。可用于增强模型的回复质量，模型回复时会优先参考此处内容，引导模型生成特定的输出或执行特定的任务。需包含 `Role`（仅支持 `user`/`assistant`）和 `Content` 字段，且必须成对出现。推荐使用该参数控制用户提示词，具有存储提示词自动逐出机制，且表现更稳定。
`HistoryLength`	Integer	模型存储历史问题轮数。
`UserMessages`	String[]	旧版本参数，不推荐使用，仅为兼容保留。用户提示词。可用于增强模型的回复质量，模型回复时会优先参考此处内容，引导模型生成特定的输出或执行特定的任务。

UserMessages 说明

UserMessages 是一个为保证向后兼容性而保留的旧版参数，不推荐使用，与 UserPrompts 的差异如下：

维度	UserPrompts (推荐)	UserMessages (不推荐)
数据类型	对象数组 Object[]	字符串数组 String[]
字段要求	必须包含 Role 和 Content 字段，且 user 和 assistant 角色需成对交替出现。	无严格字段要求，直接存储对话文本。
存储机制	自动逐出：当对话历史超过 HistoryLength 限制时，最早的 UserPrompts 会被逐出，为新的对话历史腾出空间。	永久存储：内容不会被自动逐出，会始终占用上下文空间。

上下文长度限制

上下文总长度（以 Tokens 计算）不得超过所选大模型的上限（如 8k）。计算方式取决于您使用的参数组合。

（推荐）使用 UserPrompts 时：
- 计算逻辑：UserPrompts 支持自动逐出，计算总长度时只包含当前对话中仍然生效的 UserPrompts。
- 计算公式：
```
总长度 = SystemMessages + 当前生效的 UserPrompts + HistoryLength 轮对话
```
- 示例：若 HistoryLength 为 3，模型上限 8k。当一轮旧的 UserPrompts 因对话轮数增加被逐出后，计算总长度时就不再包含它，从而为新的对话历史腾出空间。
（不推荐）使用 UserMessages 时：
- 计算逻辑：UserMessages 会被永久保留，计算总长度时需包含全部内容。
- 计算公式：
```
总长度 = SystemMessages + 全部 UserMessages + HistoryLength 轮对话
```
- 示例：若 HistoryLength 为 3，模型上限 8k。当一轮旧的 UserPrompts 因对话轮数增加被逐出后，计算总长度时就不再包含它，从而为新的对话历史腾出空间。

Coze 平台

上下文管理模式

使用Coze平台时，上下文管理有两种模式，通过 StartVoiceChat 中的字段 LLMConfig.EnableConversation 控制：

模式	上下文生成逻辑
RTC管理上下文	即 `EnableConversation: false`。模型对话上下文生成逻辑由历史问题轮数 `HistoryLength` 和 Coze 平台编排页人设与回复逻辑、插件、知识库共同控制。
Coze平台管理上下文	即 `EnableConversation: true`。模型对话上下文生成逻辑完全由 Coze 平台编排页人设与回复逻辑、插件、知识库共同控制。`HistoryLength` 参数不生效。

Coze 编排功能、插件等搭建能力详细介绍参看 Coze 开发智能体功能概述。

上下文长度限制

需要确保编排页人设与回复逻辑、插件、知识库与会话内容文本总长度不超过大模型上下文长度。历史问题轮数在 RTC 管理上下文时通过 HistoryLength 参数控制，在 Coze 平台管理上下文时通过模型设置页面操作。

动态传入上下文

除了启动时设定的基础上下文，你还可以在对话过程中，实时地为智能体传入文本信息，作为下一轮对话的背景参考，或直接触发回复。

使用限制

动态传入上下文在启用端到端实时语音大模型（S2SConfig）时无效。详细说明，请参见接入端到端实时语音大模型。

传入背景信息（不立即回复）

功能介绍

向智能体传入文本信息，作为它下一轮回答的背景参考，但不会立即触发回复。适用于需要结合实时变化或用户无法通过语音表达的隐式信息的场景。

场景	描述	示例
游戏陪玩	结合用户实时游戏数据生成合适的回答，为用户提供更贴心的陪伴。	自定义文本：“当前用户战绩 0-14，金币落后”。用户语音提问：“我该出什么装备？” 智能体输出：“我观察到你处于逆风局，建议先出防御装来稳住局势。”
健康咨询	结合用户实时生理数据生成个性化建议，提升健康指导的精准度。	自定义文本：“当前用户心率 130，面色发白”。用户语音提问：“我现在感觉不太舒服，怎么办？” 智能体输出：“监测到您心率持续偏高，建议您立刻暂停运动并补充电解质。”

实现方式

调用 UpdateVoiceChat 接口，并按如下配置关键参数：

Command：设置为 ExternalPromptsForLLM。
Message：填入要传入的背景信息文本内容。

请求示例

POST https://rtc.volcengineapi.com?Action=UpdateVoiceChat&Version=2024-12-01
{
    "AppId": "Your_AppId", 
    "RoomId": "Your_RoomId", 
    "TaskId": "Your_TaskId", 
    "Command": "ExternalPromptsForLLM",
    "Message": "当前用户战绩 0-14，金币落后"
}

传入文本直接提问（立即回复）

功能介绍

传入的文本会作为用户的直接提问，智能体会立即处理并生成语音回复。相当于模拟了一次用户的“文字输入”。

场景	描述
电商直播	将观众在弹幕或私信中提出的问题，实时发送给正在直播的 AI 智能体主播进行回答。
特殊内容输入	当问题包含生僻字、专业术语、复杂编码或同音字较多时，用户通过文本输入可以确保提问的准确性。

通过服务端实现

调用 UpdateVoiceChat接口，设置以下参数自定义传入大模型上下文：

参数	类型	描述
AppId	String	RTC 应用 AppId，参看获取 AppId。
RoomId	String	自定义会话房间 ID。
TaskId	String	自定义会话任务 ID。
Command	String	填入`ExternalTextToLLM`，表示自定义传入大模型上下文。
Message	String	填入自定义传入大模型上下文内容，长度不超过 200 个字符。
InterruptMode	Integer	传入大模型上下文内容处理优先级。 `1`：高优先级。智能体会终止当前交互，将文本送入大模型进行处理并输出结果。 `2`：中优先级。智能体会在当前交互结束后，将文本送入大模型进行处理并输出结果。 `3`：低优先级。如果此时智能体正在交互，智能体会直接丢弃传入的文本内容。如果未在交互，智能体会将文本送入大模型进行处理并输出结果。

你可参考以下示例从服务端实现自定义传入大模型上下文内容：

POST https://rtc.volcengineapi.com?Action=UpdateVoiceChat&Version=2024-12-01
{
    "AppId": "661e****543cf", 
    "RoomId": "Room1", 
    "TaskId": "task1", 
    "Command": "ExternalTextToLLM",
    "Message": "给一些出装建议。用户当前的背景是：金币落后，法师，输出高，脆皮",
    "InterruptMode": 2
}

通过客户端实现

使用 sendUserBinaryMessage 接口构造一个 Command 为 ExternalTextToLLM 的控制消息。该接口的 buffer 参数需要传入特定格式的内容，下图展示了 buffer 参数的格式：

alt

参数名	类型	描述
magic_number	binary	消息格式标识符，当前场景消息格式固定为 `ctrl`，用于标识该消息为控制消息。
length	binary	传入大模型上下文消息长度，单位为字节，采用大端序（Big-endian）存储方式，用于说明 `control_message` 字段的字节长度。
control_message	binary	传入大模型上下文配置信息，采用 JSON 格式，具体内容格式参看 control_message 格式。

control_message

参数名	类型	描述
Command	String	控制命令，此处填入 `ExternalTextToLLM`。
Message	String	传入大模型上下文内容，长度不超过 200 个字符。
InterruptMode	Int	传入大模型上下文内容处理优先级。 `1`：高优先级。智能体会终止当前交互，将文本送入大模型进行处理并输出结果。 `2`：中优先级。智能体会在当前交互结束后，将文本送入大模型进行处理并输出结果。 `3`：低优先级。如果此时智能体正在交互，智能体会直接丢弃传入的文本内容。如果未在交互，智能体会将文本送入大模型进行处理并输出结果。

你可参看以下示例从客户端实现自定义传入大模型上下文。

C++

Java

TypeScript

// 传入大模型上下文信息
void sendLLMMessage(const std::string &uid, const std::string& content) {
    nlohmann::json json_data;
    json_data["Command"] = "ExternalTextToLLM";
    json_data["Message"] = content;
    json_data["InterruptMode"] = 1; 
    sendUserBinaryMessage(uid, json_data.dump());
}

void buildBinaryMessage(const std::string& magic_number, const std::string& message, size_t& binary_message_length, std::shared_ptr<uint8_t[]>& binary_message) {
    auto magic_number_length = magic_number.size();
    auto message_length = message.size();

    binary_message_length = magic_number_length + 4 + message_length;
    binary_message = std::shared_ptr<uint8_t[]>(new uint8_t[binary_message_length]);
    std::memcpy(binary_message.get(), magic_number.data(), magic_number_length);
    binary_message[magic_number_length] = static_cast<uint8_t>((message_length >> 24) & 0xFF);
    binary_message[magic_number_length+1] = static_cast<uint8_t>((message_length >> 16) & 0xFF);
    binary_message[magic_number_length+2] = static_cast<uint8_t>((message_length >> 8) & 0xFF);
    binary_message[magic_number_length+3] = static_cast<uint8_t>(message_length & 0xFF);
    std::memcpy(binary_message.get()+magic_number_length+4, message.data(), message_length);
}

// userId 为房间内智能体的 ID（对应 StartVoiceChat 中的 AgentConfig.UserId）
int sendUserBinaryMessage(const std::string &uid, const std::string& message) {
    if (rtcRoom_ != nullptr)
    {
        size_t length = 0;
        std::shared_ptr<uint8_t[]> binary_message = nullptr;
        buildBinaryMessage("ctrl", message, length, binary_message);
        return rtcRoom_->sendUserBinaryMessage(uid.c_str(), static_cast<int>(length), binary_message.get());
    }
    return -1;
}

// 传入大模型上下文信息
public void sendLLMMessage(String userId, String content) {
    JSONObject json = new JSONObject();
    try {
        json.put("Command", "ExternalTextToLLM");
        json.put("Message", content);
        json.put("InterruptMode", 1); // InterruptMode 可选值1,2,3
    } catch (JSONException e) {
        throw new RuntimeException(e);
    }
    String jsonString = json.toString();
    byte[] buildBinary = buildBinaryMessage("ctrl", jsonString);
    sendUserBinaryMessage(userId, buildBinary);
}

private byte[] buildBinaryMessage(String magic_number, String content) {
    byte[] prefixBytes = magic_number.getBytes(StandardCharsets.UTF_8);
    byte[] contentBytes = content.getBytes(StandardCharsets.UTF_8);
    int contentLength = contentBytes.length;

    ByteBuffer buffer = ByteBuffer.allocate(prefixBytes.length + 4 + contentLength);
    buffer.order(ByteOrder.BIG_ENDIAN);
    buffer.put(prefixBytes);
    buffer.putInt(contentLength);
    buffer.put(contentBytes);
    return buffer.array();
}
// userId 为房间内智能体的 ID（对应 StartVoiceChat 中的 AgentConfig.UserId）
public void sendUserBinaryMessage(String userId, byte[] buffer) {
    if (rtcRoom_ != null) {
        rtcRoom_.sendUserBinaryMessage(userId, buffer, MessageConfig.RELIABLE_ORDERED);
    }
}

import VERTC from '@volcengine/rtc';
const BotName = 'RobotMan_';  // 房间内智能体的 ID（对应 StartVoiceChat 中的 AgentConfig.UserId）
const CommandKey = 'ctrl';
const engine = VERTC.createEngine('Your AppID');

/**
 * @brief 指令类型
 */
enum COMMAND {
  /**
   * @brief 传入大模型上下文信息
   */
  EXTERNAL_TEXT_TO_LLM = 'ExternalTextToLLM',
};

/**
 * @brief 打断的类型
 */
enum INTERRUPT_PRIORITY {
  /**
   * @brief 占位
   */
  NONE,
  /**
   * @brief 高优先级。智能体会终止当前交互，将文本送入大模型进行处理并输出结果。
   */
  HIGH,
  /**
   * @brief 中优先级。智能体会在当前交互结束后，将文本送入大模型进行处理并输出结果。
   */
  MEDIUM,
  /**
   * @brief 低优先级。如果此时智能体正在交互，智能体会直接丢弃传入的文本内容。如果未在交互，智能体会将文本送入大模型进行处理并输出结果。
   */
  LOW,
};

/**
 * @brief 将字符串包装成 TLV
 */
function stringToTLV(inputString: string, type = '') {
  const typeBuffer = new Uint8Array(4);

  for (let i = 0; i < type.length; i++) {
    typeBuffer[i] = type.charCodeAt(i);
  }

  const lengthBuffer = new Uint32Array(1);
  const valueBuffer = new TextEncoder().encode(inputString);

  lengthBuffer[0] = valueBuffer.length;

  const tlvBuffer = new Uint8Array(typeBuffer.length + 4 + valueBuffer.length);

  tlvBuffer.set(typeBuffer, 0);

  tlvBuffer[4] = (lengthBuffer[0] >> 24) & 0xff;
  tlvBuffer[5] = (lengthBuffer[0] >> 16) & 0xff;
  tlvBuffer[6] = (lengthBuffer[0] >> 8) & 0xff;
  tlvBuffer[7] = lengthBuffer[0] & 0xff;

  tlvBuffer.set(valueBuffer, 8);

  return tlvBuffer.buffer;
};

/**
 * @brief 传入大模型上下文信息
 */
engine.sendUserBinaryMessage(
  BotName,
  stringToTLV(
    JSON.stringify({
      Command: COMMAND.EXTERNAL_TEXT_TO_LLM,
      Message: '给一些出装建议。用户当前的背景是：金币落后，法师，输出高，脆皮',
      InterruptMode: INTERRUPT_PRIORITY.HIGH,
    }),
    CommandKey,
  )
);