> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# 实时模型

## 概述

实时模型是专为低延迟语音对话打造、可供语音智能体使用的 ElevenLabs 模型。

每个语音智能体都有一种 **语音模式**：**自定义** 或 **实时**。在自定义模式下，你可以自行选择 LLM、TTS 模型和 ASR 设置，如 [模型](/docs/zh/eleven-agents/customization/llm) 所述。在实时模式下，你选择实时模型，ElevenLabs 会为你管理这些设置。

提供两种实时模型：

| 模型                          | `realtime_model` 值        | 说明                                 |
| --------------------------- | ------------------------- | ---------------------------------- |
| **Eleven Realtime v1 Mini** | `eleven_realtime_v1_mini` | 默认实时模型。延迟最低，成本最低。                  |
| **Eleven Realtime v1 Max**  | `eleven_realtime_v1_max`  | 回复前会进行推理，适合复杂指令和多步骤工具调用。成本高于 Mini。 |

智能体的系统提示词、音色、工具、知识库和轮次设置在两种模式下的使用方式相同。

> **Tip**
>
> 正在使用其他实时 API，例如 SpaceXAI 或 OpenAI？[实时 API](/docs/zh/eleven-agents/guides/openai-realtime-compatibility) 可让你更快试用
> 实时模型：将现有客户端指向 ElevenLabs，并继续使用已有事件。

> **Note**
>
> 实时模型正逐步推出。如果智能体 **智能体** 标签页中未显示 **语音模式** 设置，
> 说明实时模型暂未在工作区中提供，且 API 会拒绝 `realtime_model`，并返回错误
> `Realtime models are not available for this workspace.`

## 选择语音模式

如果符合以下任一情况，请让智能体保持自定义模式：

* 智能体使用[自定义 LLM](/docs/zh/eleven-agents/customization/llm/custom-llm)、Amazon Bedrock 或 [Speech Engine](/docs/zh/eleven-api/guides/cookbooks/speech-engine)。
* 智能体需要特定的 LLM 或 TTS 模型。
* 工作流节点会覆盖 LLM、TTS 模型或其他[托管设置](#managed-settings)。
* 智能体会转接至自定义模式的智能体，或从此类智能体接收转接。
* 智能体仅支持文本。实时模型专为语音对话打造。

否则，请从 Eleven Realtime v1 Mini 开始。在以下情况下，改用 Eleven Realtime v1 Max：

* 智能体需要遵循较长或复杂的指令，或依赖多步骤工具调用，而 Mini 的回复效果不够好。
* 智能体必须遵守美国或欧盟的 [Zero Retention Mode](/docs/zh/eleven-agents/customization/privacy/zrm) 或 [HIPAA](/docs/zh/eleven-agents/legal/hipaa)。Mini 不支持这两项要求。

Max 不适用于印度和新加坡数据驻留环境，并且需要至少 1,024 的令牌上限，或不设上限。请参阅[限制](#limitations)和[合规与数据驻留](#compliance-and-data-residency)。

## 配置

#### 通过控制台更新

#### 打开智能体标签页

在控制台中打开智能体，然后前往 **智能体** 标签页。

#### 设置语音模式

将 **语音模式** 设为 **实时**。智能体会切换到 Eleven Realtime v1 Mini。

#### 选择模型

如需改用 Eleven Realtime v1 Max，请从 **模型** 列表中选择它。

#### 发布

发布更改。如果智能体违反[限制](#limitations)中的任一规则，发布会失败。

若要关闭实时模式，请将 **语音模式** 设为 **自定义** 并发布。智能体会恢复使用其保存的 LLM、TTS 模型和 ASR 设置。

#### 通过 CLI 更新

#### 拉取智能体配置

```bash
elevenlabs agents pull --agent "<agent-name>"
```

#### 编辑 \`agent_configs/\<agent-name>.json\`

设置 `conversation_config.realtime_model`：

```json
{
  "conversation_config": {
    "realtime_model": "eleven_realtime_v1_mini"
  }
}
```

若要关闭实时模式，请将 `realtime_model` 设为 `null`。

#### 推送更改

```bash
elevenlabs agents push --agent "<agent-name>"
```

#### 通过 API 更新

```python
from elevenlabs import ElevenLabs

elevenlabs = ElevenLabs()

elevenlabs.conversational_ai.agents.update(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    conversation_config={
        "realtime_model": "eleven_realtime_v1_mini",
    },
)
```

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient();

await elevenlabs.conversationalAi.agents.update("agent_7101k5zvyjhmfg983brhmhkd98n6", {
  conversationConfig: {
    realtimeModel: "eleven_realtime_v1_mini",
  },
});
```

若要关闭实时模式，请在 Python 中将 `realtime_model` 设为 `None`，或在 TypeScript 中将 `realtimeModel` 设为 `null`。

## 托管设置

设置实时模型后，ElevenLabs 会管理以下设置，智能体将忽略为它们保存的值。切换回自定义模式后，会重新使用保存的值。

| 设置      | `conversation_config` 中的字段                |
| ------- | ----------------------------------------- |
| LLM     | `agent.prompt.llm`                        |
| 推理强度    | `agent.prompt.reasoning_effort`           |
| 思考预算    | `agent.prompt.thinking_budget`            |
| 并行工具调用  | `agent.prompt.enable_parallel_tool_calls` |
| 级联超时    | `agent.prompt.cascade_timeout_seconds`    |
| TTS 模型  | `tts.model_id`                            |
| 表现模式    | `tts.expressive_mode`                     |
| ASR 提供商 | `asr.provider`                            |

令牌上限（`agent.prompt.max_tokens`）会保留已保存的值，但工作流节点无法覆盖它，并且 Eleven Realtime v1 Max 要求最低值。请参阅[限制](#limitations)。

如需更改其中任一设置，请将智能体切换到自定义模式。

## 仍然适用的设置

所有其他智能体设置的作用方式都与自定义模式相同，包括：

* 系统提示词和首条消息
* 音色，包括[多音色支持](/docs/zh/eleven-agents/customization/voice/multi-voice-support)
* [语言](/docs/zh/eleven-agents/customization/voice/customization/language)
* 温度
* [工具](/docs/zh/eleven-agents/customization/tools)和[知识库](/docs/zh/eleven-agents/customization/knowledge-base)
* [对话流程](/docs/zh/eleven-agents/customization/conversation-flow)设置，例如轮次积极度、超时和打断

智能体处于实时模式时，控制台会隐藏包括温度在内的 LLM 设置。请使用 CLI 或 API 更改实时智能体的温度。

如果实时模型未及时回复或返回错误，智能体会按照 [LLM 级联](/docs/zh/eleven-agents/customization/llm/llm-cascading)的说明回退到备用 LLM。实时模型决定智能体在回退前等待多久。

## 限制

发布智能体时，ElevenLabs 会检查以下规则。违反任一规则的草稿仍可保存，但发布会失败，并显示需要更改的设置。

* **仅限 ElevenAgents 智能体**：通过其他 ElevenLabs 产品（例如 [Speech Engine](/docs/zh/eleven-api/guides/cookbooks/speech-engine)）创建的智能体无法使用实时模型。
* **不支持自定义 LLM**：智能体的 LLM 为自定义 LLM 或 Amazon Bedrock 时，无法使用实时模式。切换前，请先在自定义模式中选择内置 LLM。
* **工作流不得覆盖托管设置**：工作流节点无法覆盖任何[托管设置](#managed-settings)或令牌上限。请移除覆盖设置，或让智能体保持自定义模式。
* **Max 的令牌上限**：Eleven Realtime v1 Max 需要令牌上限为 1,024 或更高，或不设上限。
* **模式间转接**：实时模式的智能体只能向其他实时模式智能体[转接](/docs/zh/eleven-agents/customization/tools/system-tools/agent-transfer)，或接收其转接。支持 Mini 与 Max 智能体之间的转接。

> **Warning**
>
> 发布时仅检查已发布智能体发起的转接。从自定义模式智能体转接至实时智能体的情况，
> 仅会在下次发布该自定义模式智能体时被检测到；在此之前，对话期间会拒绝该转接，
> 当前智能体会继续留在通话中。

转接错误为 `Transfers between default and Realtime model modes are not supported.`，其中 "default" 指自定义模式。

## 合规与数据驻留

实时模型与其他模型遵循相同的 [Zero Retention Mode](/docs/zh/eleven-agents/customization/privacy/zrm)、[HIPAA](/docs/zh/eleven-agents/legal/hipaa) 和[数据驻留](/docs/zh/overview/administration/data-residency)规则。Mini 和 Max 的可用性不同：

| 环境                          | Eleven Realtime v1 Mini | Eleven Realtime v1 Max |
| --------------------------- | ----------------------- | ---------------------- |
| 美国                          | 可用                      | 可用                     |
| 欧盟数据驻留                      | 可用                      | 可用                     |
| 印度数据驻留                      | 可用                      | 不可用                    |
| 新加坡数据驻留                     | 可用                      | 不可用                    |
| Zero Retention Mode 和 HIPAA | 不可用                     | 在美国和欧盟可用               |

无论是在工作区强制执行，还是在智能体上启用，Zero Retention Mode 都会生效。

如果实时模型不符合智能体的合规或数据驻留设置，ElevenLabs 会拒绝该模型，并返回注明模型名称的错误。请选择另一种实时模型，或切换到自定义模式。

## 定价

实时智能体按标准 ElevenAgents 每分钟费率计费，另加实时模型费率下的输入、缓存输入和输出令牌费用。Eleven Realtime v1 Max 的每令牌成本高于 Eleven Realtime v1 Mini。请参阅 [ElevenLabs 定价](https://elevenlabs.io/pricing)了解当前费率。

## 相关资源

* [模型](/docs/zh/eleven-agents/customization/llm)
* [LLM 级联](/docs/zh/eleven-agents/customization/llm/llm-cascading)
* [智能体转接](/docs/zh/eleven-agents/customization/tools/system-tools/agent-transfer)
* [Zero Retention Mode](/docs/zh/eleven-agents/customization/privacy/zrm)
* [HIPAA 合规](/docs/zh/eleven-agents/legal/hipaa)