> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentscope.io/llms.txt
> Use this file to discover all available pages before exploring further.
# 概述
> 通过凭证接入模型 API，并用模型卡片发现可用模型
模型层通过两层结构把 AgentScope 与模型 API 连接起来：顶层是 **API 凭证（Credential）**，其下是该 API 开放的各模型族，包括**大语言模型（LLM）**、**语音合成（TTS）**、**嵌入模型（Embedding）** 和 **实时模型（Realtime）**。
**凭证**承载某个模型 API 的认证字段（`api_key`、`base_url` 等）。从一个凭证出发，可以发现该 API 在每个模型族下提供的全部模型。下表列出内置凭证及其下的模型类：
| 凭证 | 大语言模型（LLM） | 语音合成（TTS） | 嵌入模型（Embedding） | 实时模型 |
| --------------------- | -------------------------------------------- | -------------------------------------------------------------------------------------- | ------------------------- | ------ |
| `DashScopeCredential` | `DashScopeChatModel` | `DashScopeTTSModel`
`DashScopeRealtimeTTSModel`
`DashScopeCosyVoiceTTSModel` | `DashScopeEmbeddingModel` | *即将上线* |
| `OpenAICredential` | `OpenAIChatModel`
`OpenAIResponseModel` | `OpenAITTSModel` | `OpenAIEmbeddingModel` | *即将上线* |
| `GeminiCredential` | `GeminiChatModel` | `GeminiTTSModel` | `GeminiEmbeddingModel` | *即将上线* |
| `AnthropicCredential` | `AnthropicChatModel` | — | — | — |
| `DeepSeekCredential` | `DeepSeekChatModel` | — | — | — |
| `MoonshotCredential` | `MoonshotChatModel` | — | — | — |
| `XAICredential` | `XAIChatModel` | — | — | — |
| `OllamaCredential` | `OllamaChatModel` | — | `OllamaEmbeddingModel` | — |
这种分层与前端的自然交互流程（先注册凭证，再从凭证下挑选模型）一致，让界面只需鉴权一次，就能展示该 API 支持的所有模型族。
所有模型族共享同一种构造模式：模型接收一个**凭证**、一个**模型名**，以及可选的 API 专属 **`Parameters`** 对象。各模型族的创建与调用细节参见对应页面：
* [大语言模型](/versions/2.0.5dev/zh/building-blocks/model/llm)：驱动智能体的对话与工具调用
* [语音合成](/versions/2.0.5dev/zh/building-blocks/model/tts)：将文本转换为合成语音音频
* [嵌入模型](/versions/2.0.5dev/zh/building-blocks/model/embedding)：将文本与多媒体内容转换为稠密向量
**实时模型**即将上线：Realtime Model 支持正在从 v1.0 迁移到 v2.0。
## 前端集成
### 什么是模型卡片
模型卡片（ModelCard）是对模型能力与约束的声明式描述，用于驱动前端：模型选择器、参数表单、能力开关都可以基于它动态渲染，无需在前端硬编码任何与特定模型 API 相关的逻辑。每个模型族有自己的卡片类：
| 卡片类 | 模型族 | `type` 判别值 |
| -------------------- | ----- | ------------------- |
| `ModelCard` | 大语言模型 | `"chat_model"` |
| `TTSModelCard` | 语音合成 | `"tts_model"` |
| `EmbeddingModelCard` | 嵌入模型 | `"embedding_model"` |
三种卡片类共享一组核心字段：
| 字段 | 类型 | 说明 |
| --------------------- | -------------------------------------- | -------------------------------------------------------------- |
| `name` | `str` | 模型标识符（例如 `"claude-sonnet-4-6"`） |
| `label` | `str` | 用于展示的可读名称（例如 `"Claude Sonnet 4.6"`） |
| `status` | `"active" \| "deprecated" \| "sunset"` | 模型生命周期状态 |
| `input_types` | `list[str]` | 接受的输入 MIME 类型，前端据此过滤附件上传组件（例如仅在支持 `image/*` 时显示图片按钮） |
| `output_types` | `list[str]` | 模型可输出的 MIME 类型，用于标注模型能力（例如出现 `application/x-thinking` 时启用思考开关） |
| `parameter_schema` | `dict` | 最终用于渲染参数表单的 JSON Schema，由基础 schema 与逐模型覆盖合并而来（见下文） |
| `parameter_overrides` | `dict[str, dict]` | 合并前来自 YAML 的原始逐模型覆盖 |
在核心字段之外，每种卡片还有各自的专属字段：
| 卡片类 | 专属字段 |
| -------------------- | -------------------------------------------------------------------------------------------------- |
| `ModelCard` | `context_size`（最大上下文窗口 token 数）、`output_size`（最大输出 token 数）、`deprecated_at`（弃用日期） |
| `TTSModelCard` | `realtime`（是否支持流式输入）、`deprecated_at`；YAML 中的 `voices` 列表会作为 `voice` 字段的 enum 注入 `parameter_schema` |
| `EmbeddingModelCard` | `dimensions`（默认输出向量维度，必填）、`supported_dimensions`（俄罗斯套娃式模型允许的维度集合，`None` 表示维度固定）、`context_size`（可选） |
`input_types` 与 `output_types` 都用 MIME 类型描述模态，常见取值如下：
| MIME 类型 | 含义 |
| ------------------------------------- | -------- |
| `text/plain` | 文本 |
| `application/x-thinking` | 推理 / 思考链 |
| `application/x-embedding` | 稠密向量 |
| `image/*`（如 `image/png`、`image/jpeg`） | 图片 |
| `audio/*`（如 `audio/wav`、`audio/mp3`） | 音频 |
| `video/*`（如 `video/mp4`） | 视频 |
每张卡片由模型实现旁的 YAML 文件定义。下面三个 tab 分别展示各模型族的一张真实卡片：
```yaml Chat (claude-sonnet-4-6) theme={null}
name: claude-sonnet-4-6
label: Claude Sonnet 4.6
status: active
input_types:
- text/plain
- application/x-thinking
- image/jpeg
- image/png
- image/gif
- image/webp
output_types:
- text/plain
- application/x-thinking
context_size: 1000000
output_size: 65536
parameter_overrides:
max_tokens: {"maximum": 65536}
```
```yaml TTS (qwen3-tts-flash) theme={null}
name: qwen3-tts-flash
label: Qwen3-TTS-Flash
status: active
input_types:
- text/plain
output_types:
- audio/wav
# 会作为 voice 字段的 enum 注入 parameter_schema，
# 前端据此渲染下拉选择器
voices:
- Cherry
- Serena
- Ethan
- Chelsie
parameter_overrides: {}
```
```yaml Embedding (text-embedding-v4) theme={null}
name: text-embedding-v4
label: Text Embedding v4
status: active
input_types:
- text/plain
output_types:
- application/x-embedding
context_size: 8192
# 默认输出向量维度，以及这个俄罗斯套娃式
# 模型支持截断到的全部维度
dimensions: 1024
supported_dimensions: [2048, 1536, 1024, 768, 512, 256, 128, 64]
```
### 参数 Schema 与覆盖
暴露给前端的 `parameter_schema` 由两层叠加而成：
1. **基础 schema**：由模型的 `Parameters` 类通过 `model_json_schema()` 自动生成，列出全部可调参数（`temperature`、`max_tokens`、`thinking_enable` 等），并给出类型与 API 通用范围。
2. **逐模型覆盖**：YAML 中的 `parameter_overrides` 块会按字段叠加在基础 schema 之上。
覆盖之所以重要，是因为同一个 API 下不同模型的可调范围并不一致：每个 Qwen 模型都接受 `max_tokens`，但上限各不相同。借助覆盖，模型卡片可以收紧某个范围、固定默认值，或隐藏某个不适用的参数。
| 覆盖写法 | 效果 |
| ------------------------- | ------------------------------------------- |
| `param: { ... }` | 浅合并到基础字段（例如 `max_tokens: {maximum: 16384}`） |
| `param: { hidden: true }` | 在前端隐藏该参数 |
| `param: null` | 完全移除该参数 |
部分调整无需显式覆盖即会自动生效：`output_types` 中没有 `application/x-thinking` 时，Chat 卡片会自动去掉 `thinking_enable` / `thinking_budget`，并将 `max_tokens` 上限设为 `output_size`；TTS 卡片会把 `voices` 列表转换为 `voice` 字段的 enum。
### 获取模型卡片
模型卡片的发现遵循 **凭证类 ⇒ 模型类 ⇒ 模型卡片** 的层级：每个凭证都知道各模型族下与之关联的模型类（`get_chat_model_class()`、`get_tts_model_classes()`、`get_embedding_model_class()`），每个模型类则从实现旁的 `_models/` 目录加载 YAML 卡片定义：
```python theme={null}
from agentscope.credential import DashScopeCredential
# 凭证类 -> 模型类
model_cls = DashScopeCredential.get_chat_model_class() # -> DashScopeChatModel
# 模型类 -> 模型卡片
cards = model_cls.list_models() # -> list[ModelCard]
```
实践中，链路两端都可以直接调用 `list_models()`。下面三个 tab 分别展示各模型族的获取方式：
```python Chat theme={null}
from agentscope.credential import DashScopeCredential
from agentscope.model import AnthropicChatModel
# 通过凭证类：内部委托给与之关联的 Chat 模型类
cards = DashScopeCredential.list_models()
# 或直接通过模型类
cards = AnthropicChatModel.list_models()
for card in cards:
print(f"{card.name}: context={card.context_size}, inputs={card.input_types}")
```
```python TTS theme={null}
from agentscope.credential import DashScopeCredential
from agentscope.tts import DashScopeTTSModel
# 通过凭证类：汇总所有关联 TTS 模型类的卡片
cards = DashScopeCredential.list_tts_models()
# 或直接通过某个 TTS 模型类
cards = DashScopeTTSModel.list_models()
for card in cards:
print(f"{card.name} (realtime={card.realtime}): {card.label}")
```
```python Embedding theme={null}
from agentscope.credential import DashScopeCredential
from agentscope.embedding import OpenAIEmbeddingModel
# 从凭证发现嵌入模型类
embed_cls = DashScopeCredential.get_embedding_model_class()
cards = embed_cls.list_models()
# 或直接通过模型类
cards = OpenAIEmbeddingModel.list_models()
for card in cards:
print(f"{card.name}: dimensions={card.dimensions}")
```
这种设计让前端只需一个凭证，就能发现所有可用模型、它们的能力与合法参数范围，无需硬编码任何与特定模型 API 相关的逻辑。
## 延伸阅读
创建与调用对话模型、生成结构化输出、接入自定义模型 API。
标准与实时两种模式的语音合成，以及与智能体的集成。
文本与多模态内容嵌入，内置分批、重试与缓存。