<!-- WEHUB_ZH_README -->
> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。  
> [English](./README.en.md) · [原始项目](https://github.com/anomalyco/models.dev) · [上游 README](https://github.com/anomalyco/models.dev/blob/HEAD/README.md)  
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

<p align="center">
  <a href="https://models.dev">
    <picture>
      <source srcset="./logo-dark.svg" media="(prefers-color-scheme: dark)">
      <source srcset="./logo-light.svg" media="(prefers-color-scheme: light)">
      <img src="./logo-light.svg" alt="Models.dev logo">
    </picture>
  </a>
</p>

---

[Models.dev](https://models.dev) 是一个全面的开源 AI 模型规格、定价与能力数据库。

目前没有一个数据库能涵盖所有可用 AI 模型的信息。我们发起 Models.dev，作为一个社区贡献项目来解决这一问题。我们也在 [opencode](https://opencode.ai). 内部使用它。

## API

你可以通过 API 访问这些数据。

```bash
curl https://models.dev/api.json
```

使用 **Model ID** 字段查询任意模型；这是 [AI SDK](https://ai-sdk.dev/). 使用的标识符。

与提供商无关（provider-agnostic）的模型元数据可单独获取：

```bash
curl https://models.dev/models.json
```

用于获取模型本身的事实信息，与由何处提供服务无关。若需要在一个响应中同时获取提供商端点与仅含模型的元数据：

```bash
curl https://models.dev/catalog.json
```

### Logos

提供商标志以 SVG 文件形式提供：

```bash
curl https://models.dev/logos/{provider}.svg
```

将 `{provider}` 替换为 **Provider ID**（例如 `anthropic`、`openai`、`google`）。若我们没有某提供商的标志，将返回默认标志。

## Contributing

数据以 TOML 文件形式存储在仓库中，按提供商和模型组织。标志存储为 SVG。这些内容用于生成本页面并驱动 API。

我们需要你的帮助来保持数据最新。

### Adding Model Metadata

仅含模型的事实信息存放在 `models/`，使用与提供商模型相同的路径式 ID。例如，`models/openai/gpt-5.toml` 定义底层 GPT-5 模型的元数据，而 `providers/openai/models/gpt-5.toml` 定义 OpenAI 特定的服务详情（如定价）。

将模型元数据用于与提供商无关的事实：

- `name`、`family`、`release_date`、`last_updated`、`knowledge`
- `attachment`、`reasoning`、`tool_call`、`structured_output`、`temperature`
- `[limit]` 默认值，如上下文、输入与输出 token 限制
- `[modalities]` 默认值
- `open_weights`、`license`、`links`、`weights` 以及 `benchmarks`

示例：

```toml
name = "GPT-5"
family = "gpt"
release_date = "2025-08-07"
last_updated = "2025-08-07"
attachment = true
reasoning = true
temperature = false
tool_call = true
structured_output = true
open_weights = false

[limit]
context = 400_000
input = 272_000
output = 128_000

[modalities]
input = ["text", "image"]
output = ["text"]

[[benchmarks]]
name = "Benchmark Name"
score = 72.5
metric = "accuracy"
source = "https://example.com/results"

[[weights]]
label = "Model weights"
url = "https://huggingface.co/example/model"
format = "safetensors"
```

提供商 TOML 可通过 `base_model` 继承这些事实，然后仅保留提供商特定字段或覆盖项：

```toml
base_model = "openai/gpt-5"

[cost]
input = 1.25
output = 10.00
cache_read = 0.125

[limit]
context = 200_000 # optional provider override
output = 32_000
```

生成时，提供商字段优先于模型元数据。当底层模型相同，但提供商以不同的上下文限制、模态、功能或定价提供服务时，请使用此方式。

### Adding a New Provider Model

要添加新模型，请先检查该提供商是否已存在于 `providers/` 目录中。若不存在，则：

#### 1. Create a Provider

若提供商尚未在 `providers/` 中：

1. 在 `providers/` 中创建一个以提供商 ID 命名的新文件夹。例如 `providers/newprovider/`。
2. 添加包含提供商详情的 `provider.toml`：

   ```toml
   name = "Provider Name"
   npm = "@ai-sdk/provider" # AI SDK Package name
   env = ["PROVIDER_API_KEY"] # Environment Variable keys used for auth
   doc = "https://example.com/docs/models" # Link to provider's documentation
   ```

   若提供商未发布 npm 包，但暴露了 OpenAI 兼容端点，请相应设置 npm 字段并包含 base URL：

   ```toml
   npm = "@ai-sdk/openai-compatible" # Use OpenAI-compatible SDK
   api = "https://api.example.com/v1" # Required with openai-compatible
   ```

#### 2. Add a Logo (optional)

要为提供商添加标志：

1. 在提供商目录中添加 `logo.svg` 文件（例如 `providers/newprovider/logo.svg`）
2. 使用 SVG 格式，不固定尺寸或颜色——填充/描边使用 `currentColor`

SVG 结构示例：

```svg
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor">
  <!-- Logo paths here -->
</svg>
```

#### 3. Add a Model Definition

在提供商的 `models/` 目录中创建新的 TOML 文件，文件名为模型 ID。

若模型 ID 包含 `/`，请使用子文件夹。例如，对于模型 ID `openai/gpt-5`，创建文件夹 `openai/`，并在其中放置名为 `gpt-5.toml` 的文件。

```toml
name = "Model Display Name"
attachment = true           # or false - supports file attachments
reasoning = false           # or true - supports reasoning / chain-of-thought
tool_call = true            # or false - supports tool calling
structured_output = true    # or false - supports a dedicated structured output feature
temperature = true          # or false - supports temperature control
knowledge = "2024-04"       # Knowledge-cutoff date
release_date = "2025-02-19" # First public release date
last_updated = "2025-02-19" # Most recent update date
open_weights = true         # or false  - model’s trained weights are publicly available

[cost]
input = 3.00                # Cost per million input tokens (USD)
output = 15.00              # Cost per million output tokens (USD)
reasoning = 15.00           # Cost per million reasoning tokens (USD)
cache_read = 0.30           # Cost per million cached read tokens (USD)
cache_write = 3.75          # Cost per million cached write tokens (USD)
input_audio = 1.00          # Cost per million audio input tokens (USD)
output_audio = 10.00        # Cost per million audio output tokens (USD)

[limit]
context = 400_000           # Maximum context window (tokens)
input = 272_000             # Maximum input tokens
output = 8_192              # Maximum output tokens

[modalities]
input = ["text", "image"]   # Supported input modalities
output = ["text"]           # Supported output modalities

[interleaved]
field = "reasoning_content" # Name of the interleaved field "reasoning_content" or "reasoning_details"
```

#### 3a. Reuse Model Metadata with `base_model`

对于镜像现有模型的封装提供商（wrapper provider），优先引用仅含模型的元数据，而不是重复与提供商无关的字段。

当提供商提供相同的底层模型，且仅提供商特定字段不同时，使用 `base_model`。

```toml
base_model = "anthropic/claude-opus-4-6"

[cost]
input = 5.00
output = 25.00
```

规则：

- `base_model` 必须指向 `models/` 中的 TOML 文件，使用 `<provider>/<model-id>`。
- 你可以在本地覆盖任何顶层模型字段。
- 若覆盖嵌套表（如 `[cost]`、`[limit]` 或 `[modalities]`），请包含该表所需的完整值。
- `base_model_omit` 为可选项，在合并本地覆盖后会移除继承的模型元数据字段。使用点路径字符串，例如 `base_model_omit = ["limit.input"]`。
- `id` 仍来自文件名；请勿将其添加到 TOML 中。

当封装模型在实质上与源模型相同，仅因提供商特定的定价、限制、模态、提供商请求结构或生命周期标志而有所不同时，使用 `base_model`。

同步与生成脚本在更新提供商 TOML 时应保留现有的 `base_model` / `base_model_omit` 字段。请勿使用旧版 `[extends]` 表。

#### 4. Submit a Pull Request

1. Fork 本仓库
2. 创建包含你更改的新分支
3. 添加你的提供商和/或模型文件
4. 提交 PR，并附上清晰的描述

### 验证

有一个 GitHub Action 会根据我们的 schema 自动验证你的提交，以确保：

- 所有必填字段都已存在
- 数据类型正确
- 值在可接受范围内
- TOML 语法有效

将现有 provider 字段迁移到 model metadata 时，请在修改前后对比生成的输出：

```bash
bun run compare:migrations
```

这会为每个变更的 model TOML 打印 diff，以便你确认生成的 JSON 仅在你预期的位置发生变化。

### Schema 参考

模型必须符合以下 schema，定义见 `packages/core/src/schema.ts`。

**Provider Schema：**

- `name`: String - 提供商的显示名称
- `npm`: String - AI SDK 包名
- `env`: String[] - 用于身份验证的环境变量键名
- `doc`: String - 提供商文档链接
- `api` _(optional)_: String - 兼容 OpenAI 的 API 端点。仅在使用 `@ai-sdk/openai-compatible` 作为 npm 包时才需要

**Model Schema：**

- `name`: String — 模型的显示名称
- `attachment`: Boolean — 是否支持文件附件
- `reasoning`: Boolean — 是否支持推理 / chain-of-thought
- `tool_call`: Boolean - 是否支持工具调用
- `structured_output` _(optional)_: Boolean — 是否支持结构化输出
- `temperature` _(optional)_: Boolean — 是否支持 temperature 控制
- `knowledge` _(optional)_: String — 知识截止日期，格式为 `YYYY-MM` 或 `YYYY-MM-DD`
- `release_date`: String — 首次公开发布日期，格式为 `YYYY-MM` 或 `YYYY-MM-DD`
- `last_updated`: String — 最近更新日期，格式为 `YYYY-MM` 或 `YYYY-MM-DD`
- `open_weights`: Boolean - 表示模型的训练权重是否公开可用
- `interleaved` _(optional)_: Boolean or Object — 是否支持交错推理（interleaved reasoning）。使用 `true` 表示通用支持，或使用包含 `field` 的对象来指定格式
- `interleaved.field`: String — 交错字段名称（`"reasoning_content"` 或 `"reasoning_details"`）
- `cost.input`: Number — 每百万输入 token 的费用（USD）
- `cost.output`: Number — 每百万输出 token 的费用（USD）
- `cost.reasoning` _(optional)_: Number — 每百万推理 token 的费用（USD）
- `cost.cache_read` _(optional)_: Number — 每百万缓存读取 token 的费用（USD）
- `cost.cache_write` _(optional)_: Number — 每百万缓存写入 token 的费用（USD）
- `cost.input_audio` _(optional)_: Number — 每百万音频输入 token 的费用（如单独计费）（USD）
- `cost.output_audio` _(optional)_: Number — 每百万音频输出 token 的费用（如单独计费）（USD）
- `limit.context`: Number — 最大上下文窗口（token 数）
- `limit.input`: Number — 最大输入 token 数
- `limit.output`: Number — 最大输出 token 数
- `modalities.input`: Array of strings — 支持的输入模态（例如 ["text", "image", "audio", "video", "pdf"]）
- `modalities.output`: Array of strings — 支持的输出模态（例如 ["text"]）
- `status` _(optional)_: String — 支持状态：
  - `alpha` - 表示模型处于 alpha 测试阶段
  - `beta` - 表示模型处于 beta 测试阶段
  - `deprecated` - 表示模型已不再通过提供商的公开 API 提供服务

### 示例

请参阅 `providers/` 目录中的现有提供商作为参考：

- `providers/anthropic/` - Anthropic Claude 模型
- `providers/openai/` - OpenAI GPT 模型
- `providers/google/` - Google Gemini 模型

### 前端开发

请确保已安装 [Bun](https://bun.sh/)。

```bash
$ bun install
$ cd packages/web
$ bun run dev
```

前端将在 http://localhost:3000 打开。

### 使用 opencode 进行手动测试

你可以通过 opencode 手动检查 provider 变更：

```bash
$ bun install
$ cd packages/web
$ bun run build
$ OPENCODE_MODELS_PATH="dist/_api.json" opencode
```

### 有问题？

如需帮助或对贡献有疑问，请提交 issue。

---

Models.dev 由 [SST](https://sst.dev). 维护者创建。

**加入我们的社区** [Discord](https://sst.dev/discord) | [YouTube](https://www.youtube.com/c/sst-dev) | [X.com](https://x.com/SST_dev)