# 模型与端点

MMSP 的客户端构成、各客户端支持的模型，以及如何调用任意兼容端点。

Source: https://mmsp.penguin.ooo/zh/docs/models/

客户端由 `client_type` 指定。**官方客户端**直接对接厂商原生 API，识别该厂商的模型，并从环境变量读取厂商的 key。**兼容客户端**则使用统一的接口协议，可调用任何提供该协议的端点。

使用模型时需传入精确的模型 id。如果模型 id 以已知的系列名开头，系统会自动识别其对应的官方客户端，此时可省略 `client_type`；否则会报错并要求显式指定。

## 官方客户端

| `client_type` | 模型 | 协议 | Key 与端点 |
| --- | --- | --- | --- |
| `openai-official` | `gpt-6.1-sol`、`gpt-6-astra`、`gpt-5.6-sol`、`gpt-5.5`；`text-embedding-3-large`、`text-embedding-3-small` | OpenAI Responses；`text-embedding-*` 走 Embeddings | `OPENAI_API_KEY` `OPENAI_BASE_URL` |
| `anthropic-official` | `claude-opus-5-5`、`claude-sonnet-5-5`、`claude-haiku-5-5`、`claude-fable-5-1`、`claude-opus-5`、`claude-sonnet-5` | Anthropic Messages | `ANTHROPIC_API_KEY` `ANTHROPIC_BASE_URL` |
| `google-official` | `gemini-4-argon`、`gemini-3.8-flash`、`gemini-3.7-flash`、`gemini-3.1-pro-preview`；`gemini-3.1-flash-image`、`gemini-3.8-flash-tts`；`gemini-embedding-2` | Gemini Interactions | `GEMINI_API_KEY` `GEMINI_BASE_URL` |
| `zai-official` | `glm-5.3`、`glm-5.3-flash`、`glm-5.2` | Chat Completions | `ZAI_API_KEY` `ZAI_BASE_URL` |
| `moonshot-official` | `kimi-k3.1-pro`、`kimi-k3.1-pro-highspeed`、`kimi-k3`、`kimi-k2.6` | Chat Completions | `MOONSHOT_API_KEY` `MOONSHOT_BASE_URL` |
| `deepseek-official` | `deepseek-flash`、`deepseek-v4-pro` | Responses | `DEEPSEEK_API_KEY` `DEEPSEEK_BASE_URL` |
| `minimax-official` | `MiniMax-M3.1-Flash`、`MiniMax-M3` | Responses | `MINIMAX_API_KEY` `MINIMAX_BASE_URL` |

每行列出了客户端读取的环境变量：先是 key，然后是端点。端点默认为厂商官方地址。官方客户端始终读取这些变量，因此也能用于对接镜像了厂商 API 的网关。例如，OpenRouter 上的 `deepseek/deepseek-v4-pro` 可通过 `deepseek-official` 调用，SiliconFlow 上的 `Pro/moonshotai/Kimi-K2.6` 可通过 `moonshot-official` 调用，只需传入网关的 `base_url` 和 `api_key` 即可。

Gemini 4 Argon（`gemini-4-argon`）支持 `low`、`medium`（默认）和 `high` 思考档位。MMSP 将 `none` 映射为 `low`，将 `xhigh`/`max` 映射为 `high`。其 1,048,576-token 上下文窗口由输入、思考和输出共享，同步流式输出最多 65,536 tokens。更长输出需要 Google 的存储式后台执行，不在 MMSP 的无状态流式接口范围内。缓存仅支持隐式缓存。

MiniMax-M3.1-Flash（`MiniMax-M3.1-Flash`）始终思考，支持 `low` 到 `max` 档位（默认 `max`）。MMSP 将 `none` 映射为 `low`，`xhigh` 和 `max` 原样传递。它没有 priority 档位，也会忽略 `tool_choice: "none"`，因此 `fast_mode` 和 `tool_choice: "none"` 会抛出 `UnsupportedParameterError`。

## 按模型 id 路由

若不指定 `client_type`，系统会根据模型 id 开头的系列名自动路由：

| id 前缀 | `client_type` |
| --- | --- |
| `gpt-`、`text-embedding-` | `openai-official` |
| `claude-` | `anthropic-official` |
| `gemini-` | `google-official` |
| `glm-` | `zai-official` |
| `kimi-` | `moonshot-official` |
| `deepseek-` | `deepseek-official` |
| `minimax-` | `minimax-official` |

匹配不区分大小写，因此 `MiniMax-M3` 也能正确路由。网关的模型 id（如 `moonshotai/kimi-k3`）或 Amazon Bedrock 的 id（如 `global.anthropic.claude-fable-5`）不以已知系列开头，必须显式指定 `client_type`。环境变量 `CLIENT_TYPE` 可为代码中未指定的客户端设置默认值。

代码中的支持模型列表始终保持最新，包含每个模型的 base URL、客户端类型、模态、上下文窗口和价格：

```typescript
import { listSupportedModels } from "@prismshadow/mmsp";

const models = listSupportedModels("CNY"); // 默认 "USD"
```

```python
from mmsp import list_supported_models

models = list_supported_models(currency="CNY")  # 默认 "USD"
```

## 兼容客户端

七个兼容客户端可调用任何提供对应协议的端点。使用时需用 `client_type` 指定协议，并同时提供端点和 key：可以传入 `base_url` 和 `api_key` 参数，或在环境变量中设置 `OPENAI_BASE_URL` 和 `OPENAI_API_KEY`（`ant-messages` 对应 `ANTHROPIC_` 变量对，`google-genai` 对应 `GEMINI_` 变量对，`openai-chat-vllm-adapter` 对应 `VLLM_` 变量对，`mmsp` 对应 `MMSP_` 变量对）。如果传入的 `base_url` 不是客户端的默认端点，又不提供 `api_key`，会报错：环境变量中的 key 不会自动用于代码指定的端点（[规则](https://mmsp.penguin.ooo/zh/docs/client/)）。`openai-chat-vllm-adapter` 和 `mmsp` 例外：它们的服务端可以不要 key，因此改为不带 key 调用；两者都不传时，分别发往 `http://127.0.0.1:8000/v1` 和 `http://127.0.0.1:25752/v1`。

| `client_type` | 协议 | 提供方 |
| --- | --- | --- |
| `openai-responses` | OpenAI Responses | OpenAI、OpenRouter、DeepSeek、Z.AI、MiniMax |
| `openai-chat` | OpenAI Chat Completions。`openai` 是其别名。 | 大多数网关、SiliconFlow、vLLM |
| `openai-chat-vllm-adapter` | vLLM 提供的 Chat Completions。将 `thinking_level` 映射到模板自有的开关。 | vLLM |
| `openai-embedding` | OpenAI Embeddings | 任何向量端点 |
| `ant-messages` | Anthropic Messages | Anthropic、OpenRouter、DeepSeek、Z.AI、MiniMax |
| `google-genai` | Google generateContent，即 Google GenAI SDK 所用的协议 | Vertex AI、Gemini API、代理此协议的网关 |
| `mmsp` | MMSP 本身 | [MMSP 服务端](https://mmsp.penguin.ooo/zh/docs/server/) |

如果网关支持多种协议，优先选择 `openai-responses`。OpenRouter 为其所有托管模型提供此协议；SiliconFlow 仅提供 Chat Completions。

```typescript
const client = new AutoLLMClient({
  model: "qwen/qwen3.8-27b",
  clientType: "openai-responses",
  baseUrl: "https://openrouter.ai/api/v1",
  apiKey: process.env.OPENROUTER_API_KEY,
});
```

```python
client = AutoLLMClient(
    model="qwen/qwen3.8-27b",
    client_type="openai-responses",
    base_url="https://openrouter.ai/api/v1",
    api_key=os.environ["OPENROUTER_API_KEY"],
)
```

常见网关的 base URL，以及示例读取 key 所用的环境变量：

| 网关 | Base URL | Key |
| --- | --- | --- |
| OpenRouter | `https://openrouter.ai/api/v1` | `OPENROUTER_API_KEY` |
| SiliconFlow | `https://api.siliconflow.cn/v1` | `SILICONFLOW_API_KEY` |
| TokenDance（词元跳动） | `https://tokendance.space/gateway/v1`，Anthropic Messages 使用 `https://tokendance.space/gateway` | `TOKENDANCE_API_KEY` |
| Google Vertex AI | `https://aiplatform.googleapis.com` | `VERTEX_API_KEY`：服务账号 JSON |
| Amazon Bedrock | `bedrock://<region>`，例如 `bedrock://us-east-1` | `BEDROCK_API_KEY`：`ACCESS_KEY,SECRET_KEY` |
| ModelVerse | `https://api.modelverse.cn/v1`，Claude 模型使用 `https://api.modelverse.cn/` | `MODELVERSE_API_KEY` |
| OpenCode Go | `https://opencode.ai/inference/go/openai/v1`，Anthropic Messages 使用 `https://opencode.ai/inference/go/anthropic`，Gemini 使用 `https://opencode.ai/inference/go/google` | `OPENCODE_API_KEY` |
| Fireworks AI | `https://api.fireworks.ai/inference/v1` | `FIREWORKS_API_KEY` |
| DashScope（阿里云百炼） | `https://dashscope.aliyuncs.com/compatible-mode/v1` | `DASHSCOPE_API_KEY` |
| Qwen Token Plan | `https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1` | `QWEN_TOKEN_PLAN_API_KEY`：Token Plan 的 key，只能用于这个端点 |
| Atlas Cloud | `https://api.atlascloud.ai/v1` | `ATLASCLOUD_API_KEY` |
| Penguin Go | `https://go.penguin.ooo/api/v1` | `PENGUIN_GO_API_KEY` |
| ModelScope（魔搭） | `https://api-inference.modelscope.cn/v1` | `MODELSCOPE_API_KEY`：账号的访问令牌 |
| vLLM | `http://127.0.0.1:8000/v1/` | `VLLM_API_KEY`，仅在服务端启动时设置了 key 才需要 |

TokenDance 用一个 key 提供多种协议。它的模型列表写明了每个模型支持的协议；选择支持其中一种协议的客户端，例如 `deepseek-v4.1-flash` 用 `openai-chat`；TokenDance 支持厂商自有 API 时选用厂商的官方客户端：`kimi-k3` 用 `moonshot-official`，`glm-5.3` 用 `zai-official`。

OpenCode Go 也用一个 key 提供多种协议，每种协议各有自己的 base URL，它的文档写明了每个模型用哪种协议：`gpt-6-luna`、`gpt-5.6-luna`、`grok-4.7` 和 Muse Spark 系列用 `openai-responses`；`claude-haiku-5-5`、`minimax-m3` 和 Qwen 系列在 Anthropic 地址上用 `ant-messages`；`gemini-4-argon` 在 Google 地址上用 `google-genai`；其余模型用 `openai-chat`。Fireworks AI、DashScope、Qwen Token Plan 和 Atlas Cloud 上的所有模型都用 `openai-chat`，ModelScope 上的用 `openai-responses`。Penguin Go 是一个 MMSP 服务端，它的模型用 `mmsp`；vLLM 服务端的模型用 `openai-chat-vllm-adapter`。

## Vertex AI 上的 Gemini

指定 `google-genai`，并将服务账号的 JSON key 作为 API key 传入。Vertex AI 的 Interactions 端点不提供这些模型，所以使用 Interactions 的 `google-official` 会拒绝此类 key。无论是否传入 `base_url`，客户端都调用全球端点 `https://aiplatform.googleapis.com`。

```typescript
const client = new AutoLLMClient({
  model: "gemini-3.8-flash",
  clientType: "google-genai",
  apiKey: fs.readFileSync("service-account.json", "utf8"),
});
```

```python
client = AutoLLMClient(
    model="gemini-3.8-flash",
    client_type="google-genai",
    api_key=open("service-account.json").read(),
)
```

思考签名仅在签发它的端点上有效。详见 [Fidelity](https://mmsp.penguin.ooo/zh/docs/fidelity/)。

## Amazon Bedrock 上的 Claude

指定 `anthropic-official`，将 `bedrock://<region>` 作为 base URL，并将 AWS 的 access key 与 secret key 用逗号连接后作为 API key 传入。模型 id 是 Bedrock 的推理配置文件，例如 `global.anthropic.claude-opus-5-5`；`global.` 配置文件按 Anthropic 的标价计费，地域配置文件（`us.`、`eu.`、`jp.`、`au.`）贵 10%。

```typescript
const client = new AutoLLMClient({
  model: "global.anthropic.claude-opus-5-5",
  clientType: "anthropic-official",
  baseUrl: "bedrock://us-east-1",
  apiKey: process.env.BEDROCK_API_KEY, // "ACCESS_KEY,SECRET_KEY"
});
```

```python
client = AutoLLMClient(
    model="global.anthropic.claude-opus-5-5",
    client_type="anthropic-official",
    base_url="bedrock://us-east-1",
    api_key=os.environ["BEDROCK_API_KEY"],  # "ACCESS_KEY,SECRET_KEY"
)
```

## 接口协议

每个客户端在底层只使用一种协议，无论通过哪个 `client_type` 调用。

| `client_type` | 接口协议 |
| --- | --- |
| `google-official`、`google-genai` | `google-genai` |
| `anthropic-official`、`ant-messages` | `ant-messages` |
| `openai-official`、`deepseek-official`、`minimax-official`、`openai-responses` | `openai-responses` |
| `zai-official`、`moonshot-official`、`openai-chat`、`openai-chat-vllm-adapter` | `openai-chat` |
| `openai-embedding`，以及 `text-embedding-*` 下的 `openai-official` | `openai-embedding` |
| `mmsp` | `mmsp` |