> ## Documentation Index
> Fetch the complete documentation index at: https://docs.veadk.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# 模型

智能体默认使用全局配置的模型，即通过环境变量或 `config.yaml` 设置的模型（参见[快速开始](/productions/veadk/preview/zh/get-started/quickstart)）。当前默认推理模型为 `doubao-seed-2-1-pro-260628`。也可以在创建智能体时为其单独指定模型。

## 为单个智能体指定模型

通过 `model_name` 与 `model_provider` 覆盖全局默认模型：

```python lines theme={null}
from veadk import Agent

agent = Agent(
    model_name="doubao-seed-2-1-pro-260628",
    model_provider="openai",
)
```

未显式传入时，`model_provider`、`model_api_base`、`model_api_key` 均沿用全局配置。

使用非原生模型接口（即设置了 `model_provider`）时，VeADK 会在模型尚未输出任何内容的阶段自动对 HTTP 429 限流错误重试一次。重试延迟优先读取响应头中的 `Retry-After`，上限为 2 秒，未提供时使用 0.5 秒。一旦模型已经开始输出内容，不再进行重试，以避免重复输出。

### 按名称解析 API Key

除直接设置 `MODEL_AGENT_API_KEY` 外，还可以设置 `MODEL_AGENT_API_KEY_NAME`，让 VeADK 按名称获取火山方舟 API Key。显式提供的 Key 始终优先：

```bash lines theme={null}
export MODEL_AGENT_API_KEY_NAME="production-key"
```

创建智能体时也可传入 `model_api_key_name`。该能力从 VeADK 1.0.2 开始提供。

## 配置回退模型

`model_name` 也接受一个列表：第一个为主模型，其余作为回退模型；当主模型不可用时，依次尝试后续模型。

```python lines theme={null}
agent = Agent(
    model_name=["doubao-seed-2-1-pro-260628", "deepseek-r1-250528"],
)
```

回退模型同时适用于默认模型接口与 `enable_responses=True` 的 Responses API。

## 配置跨提供商回退模型

`model_name` 列表只能指定同一提供商下的回退模型。当回退模型使用不同的提供商、API 地址或 API Key 时，通过 `model_fallbacks` 参数指定。`model_fallbacks` 接受字符串或 `ModelFallbackEndpoint` 对象的列表，VeADK 会将其与 `model_name` 列表中的回退条目合并后一并传给 LiteLLM。

字符串条目按主模型的 `model_provider` 自动添加提供商前缀，等价于在 `model_name` 列表中追加同提供商模型名称：

```python lines theme={null}
from veadk import Agent

agent = Agent(
    model_name="doubao-seed-2-1-pro-260628",
    model_provider="ark",
    model_fallbacks=["deepseek-r1-250528"],
)
```

需要跨提供商回退时，使用 `ModelFallbackEndpoint` 为每个回退端点单独指定提供商、API 地址与凭证。`ModelFallbackEndpoint` 已从 `veadk` 顶层包导出：

```python lines theme={null}
from veadk import Agent, ModelFallbackEndpoint

agent = Agent(
    model_name="doubao-seed-2-1-pro-260628",
    model_provider="ark",
    model_api_key="primary-key",
    model_api_base="https://ark.example.com/api/v3",
    model_fallbacks=[
        ModelFallbackEndpoint(
            model_provider="openai",
            model_name="gpt-4o-mini",
            model_api_base="https://api.openai.com/v1",
            model_api_key_env="BACKUP_MODEL_API_KEY",
        ),
    ],
)
```

也可以传入与 `ModelFallbackEndpoint` 字段匹配的字典。VeADK 同时接受完整字段名与 LiteLLM 风格的别名：

```python lines theme={null}
agent = Agent(
    model_name="doubao-seed-2-1-pro-260628",
    model_provider="ark",
    model_api_key="primary-key",
    model_api_base="https://ark.example.com/api/v3",
    model_fallbacks=[
        {
            "model": "openai/gpt-4o-mini",
            "api_key": "openai-key",
            "api_base": "https://api.openai.com/v1",
        }
    ],
)
```

### `ModelFallbackEndpoint` 参数

| 参数 | 类型 | 默认值 | 说明 |
| :- | :- | :- | :- |
| `model_name` | `str` | — | 回退模型名称。不包含提供商前缀时，若未设置 `model_provider` 则使用主模型的 `model_provider`。 |
| `model_provider` | `Optional[str]` | `None` | 回退模型的提供商。与主模型不同时视为跨提供商回退，需单独提供凭证与 API 地址。 |
| `model_api_base` | `Optional[str]` | `None` | 回退模型的 API 地址。跨提供商回退时必须设置。 |
| `model_api_key` | `Optional[str]` | `None` | 回退模型的 API Key，直接以值传入。 |
| `model_api_key_env` | `Optional[str]` | `None` | 回退模型 API Key 的环境变量名称，VeADK 在运行时读取该环境变量的值。 |
| `model_extra_config` | `dict` | `{}` | 传递给 LiteLLM 的额外配置。其中 `extra_headers` 和 `extra_body` 会与主模型的 `model_extra_config` 中对应字段深度合并，其余字段以回退端点的值为准。 |

<Note>
  `ModelFallbackEndpoint` 同时接受 LiteLLM 风格的别名：`model`、`provider`、`api_base`（或 `base_url`）、`api_key`、`api_key_env`、`extra_config`。
</Note>

<Warning>
  使用 `enable_responses=True`（Responses API）时，`model_fallbacks` 仅支持字符串条目（同一提供商的模型名称）。传入 `ModelFallbackEndpoint` 或字典形式的端点会报错。
</Warning>

<Note>
  在 `codex` 或 `piagent` 运行时中配置 `model_fallbacks` 时，回退链会被忽略，因为外部运行时不构建 LiteLLM 客户端。如需回退能力，请使用默认的 ADK 运行时。详见[运行时](/productions/veadk/preview/zh/components/agent/runtime#切换执行后端)。
</Note>

<Note>
  当同时传入 `model`（自定义 LiteLLM 客户端）与 `model_fallbacks` 时，`model_fallbacks` 不会生效；请在自定义模型对象上配置回退。
</Note>

## Responses API

Responses API 是火山方舟推出的接口，原生支持高效的上下文管理，输入输出格式更简洁，并具备更强的工具调用与多模态能力。在 VeADK 中启用后，智能体的每一轮对话都会经由该接口，从而获得原生的上下文缓存与图片、视频、文档理解能力。

### 启用

在创建智能体时设置 `enable_responses=True`：

```python lines theme={null}
from veadk import Agent

agent = Agent(enable_responses=True)
```

启用 Responses API 要求 `google-adk>=1.34.0`，且所用模型需支持该接口（豆包系列 0615 版本之后默认支持）。

### 多模态理解

除文本外，Responses API 还支持图片、视频与文档理解。通过 `google.genai.types.FileData` 传入多模态数据，`file_uri` 支持三种来源：

* **本地文件路径**：`file://{本地路径}`，底层自动经 Files API 上传。
* **Files API 资源**：`file_id://{file_id}`，用于已上传的文件。
* **网络地址**：直接传入 `https://` 链接，按 `mime_type` 识别类型。

以本地图片为例：

```python lines theme={null}
import os
from google.genai import types
from google.genai.types import FileData

local_path = os.path.abspath("example.png")
message = types.UserContent(
    parts=[
        types.Part(text="描述一下这张图片"),
        types.Part(
            file_data=FileData(
                file_uri=f"file://{local_path}",
                mime_type="image/png",
            )
        ),
    ],
)
```

视频还可在 `FileData` 中附带 `video_metadata`，用 `fps` 控制抽帧频率（默认 1，可在 0.2–5 之间调整）。

### 配置方舟上下文管理

启用 Responses API 时，可通过 `model_extra_config` 传入方舟支持的 `context_management` 配置。以下示例会清理较早的思维内容，仅保留最近一个思维轮次：

```python lines theme={null}
from veadk import Agent

agent = Agent(
    enable_responses=True,
    model_extra_config={
        "context_management": {
            "edits": [
                {
                    "type": "clear_thinking",
                    "keep": {"type": "thinking_turns", "value": 1},
                }
            ]
        }
    },
)
```

### 上下文缓存

Responses API 模式下默认开启会话缓存：系统自动存储初始上下文，并在每轮对话中动态更新，后续请求会将缓存内容与新输入合并后再送入模型。这对多轮对话、复杂工具调用等长上下文场景可显著降低重复 token 的开销。

缓存命中情况可通过返回事件的 `usage_metadata` 查看，其中 `cached_content_token_count` 为命中缓存的 token 数，`prompt_token_count` 为输入总 token 数，缓存命中率即两者之比。

<Warning>
  当智能体设置了 `output_schema` 时，该字段与缓存机制冲突，VeADK 会自动关闭上下文缓存。
</Warning>