update-provider-models

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Update Provider Model IDs

更新供应商模型ID

This skill covers adding new model IDs and removing obsolete ones across the AI SDK codebase. Each workflow uses search to discover all locations that need changes.

You may be asked to add or remove a single model ID, or to process a list of multiple model ID changes from an issue. For each model ID, follow the appropriate workflow:

If a new model ID is being added, follow the
```
<adding-new-model>
```
workflow.
If an obsolete model ID is being removed, follow the
```
<removing-obsolete-model>
```
workflow.

本操作指南涵盖在AI SDK代码库中添加新模型ID和移除已废弃模型ID的流程。每个工作流都会通过搜索来定位所有需要修改的位置。

你可能需要添加或移除单个模型ID，或是处理工单中的多个模型ID变更列表。针对每个模型ID，请遵循对应的工作流：

若要添加新模型ID，请遵循
```
<adding-new-model>
```
工作流。
若要移除已废弃模型ID，请遵循
```
<removing-obsolete-model>
```
工作流。

Critical Rules

核心规则

Exact matching: Model IDs are often substrings of others (e.g.
```
grok-3
```
vs
```
grok-3-mini
```
). Always verify each search result is the exact model, not a substring match.
Respect sort order: When inserting into any list (type unions, table rows, arrays), observe the existing order and place the new entry accordingly.
File naming for examples: Use kebab-case with hyphens replacing dots (e.g.
```
gpt-5.4-codex
```
→
```
gpt-5-4-codex.ts
```
).
Sequential processing: When handling multiple models, complete the full workflow for one model before starting the next.
Affected providers: New model IDs always need to be added to the primary provider package and the AI Gateway. There may be additional affected packages (e.g. Bedrock, Vertex, OpenAI-compatible) if the model is available there or referenced in tests/docs.
Never make unrelated changes: Only update model IDs and related references. Don't modify any other code, text, or formatting in the files you edit.
Never modify
CHANGELOG.md
files of
packages/codemod
: Changelog files are historical records, codemods are migration scripts. Do not edit either when updating model IDs.

<adding-new-model>

精确匹配：Model ID通常是其他Model ID的子串（例如
```
grok-3
```
和
```
grok-3-mini
```
）。请务必验证每个搜索结果都是精确匹配的模型，而非子串匹配。
遵循排序规则：在任何列表（类型联合、表格行、数组）中插入新条目时，请遵循现有排序规则，将新条目放在对应位置。
示例文件命名：使用短横线分隔的kebab-case格式，用短横线替换点号（例如
```
gpt-5.4-codex
```
→
```
gpt-5-4-codex.ts
```
）。
顺序处理：处理多个模型时，请完成一个模型的完整工作流后再开始下一个。
受影响的供应商：新模型ID必须添加到主供应商包和AI Gateway中。如果模型在其他包中可用或在测试/文档中被引用，可能还需要更新其他相关包（例如Bedrock、Vertex、兼容OpenAI的包）。
禁止无关修改：仅更新模型ID及相关引用。请勿修改所编辑文件中的任何其他代码、文本或格式。
禁止修改
packages/codemod
的
CHANGELOG.md
文件：变更日志是历史记录，codemod是迁移脚本。更新模型ID时请勿编辑这两类文件。

<adding-new-model>

Workflow for Adding a New Model ID

添加新模型ID的工作流

Step 1: Identify Scope

步骤1：确定范围

Determine:

Provider name (e.g.
```
anthropic
```
,
```
openai
```
,
```
google
```
,
```
xai
```
)

Exact model ID string (e.g.

claude-haiku-4-5-20260218

gemini-3.1-pro

gpt-5.4-codex

)

Model type: chat, embedding, image, etc.
Whether this is a new version of an existing older model, or even the stable version of an existing preview or experimental model
Whether any provider packages other than the primary one and the AI Gateway need to be updated (e.g. Bedrock, Vertex, OpenAI-compatible)
- If a similar model ID is listed in one of those other provider packages, the new model ID should likely be added there as well. Check the provider's documentation for clues on availability.

明确以下信息：

供应商名称（例如
```
anthropic
```
、
```
openai
```
、
```
google
```
、
```
xai
```
）

精确的Model ID字符串（例如

claude-haiku-4-5-20260218

、

gemini-3.1-pro

、

gpt-5.4-codex

）

模型类型：聊天、嵌入、图像等
该模型是现有旧模型的新版本，还是现有预览版/实验性模型的稳定版
除主供应商包和AI Gateway外，是否需要更新其他供应商包（例如Bedrock、Vertex、兼容OpenAI的包）
- 如果其他供应商包中列出了类似的Model ID，新Model ID也应添加到其中。可查看供应商文档确认可用性。

Step 2: Find Where Similar Models Are Referenced

步骤2：查找相似模型的引用位置

Search for a similar existing model from the same provider (e.g. a lower version, or the preview version being replaced) across

packages/

content/

, and

examples/

. This reveals all locations that need updates.

bash

undefined

在

packages/

、

content/

和

examples/

目录中搜索同一供应商的现有相似模型（例如低版本模型，或被替代的预览版模型）。这将找出所有需要更新的位置。

bash

undefined

Search quoted occurrences to find all reference locations

搜索带引号的出现位置，找到所有引用位置

grep -r "'<similar-model-id>'" packages/ content/ examples/ --include='.ts' --include='.mdx' --include='.md' grep -r '"<similar-model-id>"' packages/ content/ examples/ --include='.ts' --include='.mdx' --include='.md'

undefined

undefined

Step 3: Update Type Definitions

步骤3：更新类型定义

For each relevant

packages

file found, add the new model ID to the type union (and const arrays if present), respecting existing sort order.

Examples of common locations for model ID type definitions:

```
packages/<provider>/src/*-options.ts
```
— the primary provider package

packages/gateway/src/gateway-language-model-settings.ts

— the AI Gateway package

```
packages/amazon-bedrock/src/**/*-options.ts
```
— if the model is available on Amazon Bedrock
```
packages/google-vertex/src/*-options.ts
```
— if the model is available on Google Vertex

This is NOT an exhaustive list — the search in Step 2 may reveal other files with model ID references that need updating as well.

Never replace a model ID here. Only add the new model ID. Replacing references to an older or preview model ID is only relevant in documentation and examples.

Example type union addition:

typescript

export type SomeModelId =
  | 'existing-model-a'
  | 'new-model-id' // ← add in sorted position
  | 'existing-model-b'
  | (string & {});

Example const array addition:

typescript

export const reasoningModelIds = [
  'existing-model-a',
  'new-model-id', // ← add in sorted position
  'existing-model-b',
] as const;

对于找到的每个相关

packages

文件，将新Model ID添加到类型联合（以及常量数组，如果存在的话）中，遵循现有排序规则。

Model ID类型定义的常见位置示例：

```
packages/<provider>/src/*-options.ts
```
— 主供应商包

packages/gateway/src/gateway-language-model-settings.ts

— AI Gateway包

packages/amazon-bedrock/src/**/*-options.ts

— 如果模型在Amazon Bedrock上可用

```
packages/google-vertex/src/*-options.ts
```
— 如果模型在Google Vertex上可用

这并非详尽列表——步骤2中的搜索可能会发现其他需要更新Model ID引用的文件。

请勿在此处替换Model ID，仅添加新的Model ID。替换旧版或预览版Model ID的引用仅适用于文档和示例场景。

类型联合添加示例：

typescript

export type SomeModelId =
  | 'existing-model-a'
  | 'new-model-id' // ← 按排序位置添加
  | 'existing-model-b'
  | (string & {});

常量数组添加示例：

typescript

export const reasoningModelIds = [
  'existing-model-a',
  'new-model-id', // ← 按排序位置添加
  'existing-model-b',
] as const;

Step 4: Update Documentation

步骤4：更新文档

For each

.mdx

file found in

content/

, add or update entries:

Capability tables: Add a row for the new model in the correct position with the appropriate capability checks (
```
<Check size={18} />
```
or
```
<Cross size={18} />
```
).
Inline code examples: If replacing a preview/older model as the recommended one, update code snippets like
```
const model = provider('old-model')
```
to use the new model.
"Latest" descriptions: Update text like "Latest model with enhanced reasoning" to reference the new model.

If you found the similar model ID referenced in a specific package's

README.md

file, update the model ID in those code examples as well.

对于在

content/

中找到的每个

.mdx

文件，添加或更新相关条目：

能力表格：在正确位置为新模型添加一行，并标记相应的能力（
```
<Check size={18} />
```
或
```
<Cross size={18} />
```
）。
内联代码示例：如果新模型替代了预览版/旧版模型成为推荐模型，请更新代码片段，例如将
```
const model = provider('old-model')
```
修改为使用新模型。
“最新版”描述：更新类似“具备增强推理能力的最新模型”的文本，使其指向新模型。

如果在某个包的

README.md

文件中找到了相似Model ID的引用，请同时更新这些代码示例中的Model ID。

Step 5: Create or Update Examples

步骤5：创建或更新示例

If the new model replaces an older one: Find existing examples using the old model and update them to use the new model ID.

If purely new with no predecessor: Create new example files, one file per top-level function that is relevant for the new model (e.g.

generateText

streamText

generateImage

). For example, if it's a new language model, you would create files like:

examples/ai-functions/src/generate-text/<provider>/<model-kebab>.ts

examples/ai-functions/src/stream-text/<provider>/<model-kebab>.ts

Or if it's a new image model, you might create:

examples/ai-functions/src/generate-image/<provider>/<model-kebab>.ts

Look for existing example files for the provider in the same folder, to use as a reference for your new example files.

In your search for the similar model ID, you may have found examples in which the model ID is part of a list of models (e.g. in an array of options for a test or example). In that case, add the new model ID to the same list in the example file, respecting sort order.

如果新模型替代了旧模型：找到使用旧模型的现有示例，将其更新为使用新Model ID。

如果是全新模型且无替代版本：为新模型相关的每个顶层函数创建新的示例文件（例如

generateText

、

streamText

、

generateImage

）。例如，如果是新的语言模型，你需要创建如下文件：

examples/ai-functions/src/generate-text/<provider>/<model-kebab>.ts

examples/ai-functions/src/stream-text/<provider>/<model-kebab>.ts

如果是新的图像模型，你可能需要创建：

examples/ai-functions/src/generate-image/<provider>/<model-kebab>.ts

可查看同一目录下该供应商的现有示例文件，作为创建新示例文件的参考。

在搜索相似Model ID时，你可能会发现示例文件中的模型列表（例如测试或示例中的选项数组）包含该Model ID。这种情况下，请将新Model ID添加到示例文件的同一列表中，遵循排序规则。

Step 6: Update Tests

步骤6：更新测试

Where reasonable, replace references to the older or preview model with the new model in test files, especially if the new model is now the recommended one.

Exception: Do not replace model IDs in fixtures or snapshots, or tests that use those fixtures or snapshots, as those are meant to be stable and reflect actual API responses captured.

在合理情况下，将测试文件中对旧版或预览版模型的引用替换为新模型，尤其是当新模型成为推荐模型时。

例外情况：请勿替换fixture或快照中的Model ID，也请勿修改使用这些fixture或快照的测试，因为它们是稳定的记录，用于反映捕获的实际API响应。

Step 7: Run Tests

步骤7：运行测试

bash

pnpm --filter @ai-sdk/<provider> test
pnpm --filter @ai-sdk/gateway test

Also run tests for any other affected packages:

bash

pnpm --filter @ai-sdk/openai-compatible test  # if snapshots/tests were updated
pnpm --filter @ai-sdk/amazon-bedrock test     # if Bedrock options were updated
pnpm --filter @ai-sdk/google-vertex test      # if Vertex options were updated

</adding-new-model> <removing-obsolete-model>

bash

pnpm --filter @ai-sdk/<provider> test
pnpm --filter @ai-sdk/gateway test

同时运行所有受影响包的测试：

bash

pnpm --filter @ai-sdk/openai-compatible test  # 如果更新了快照/测试
pnpm --filter @ai-sdk/amazon-bedrock test     # 如果更新了Bedrock配置
pnpm --filter @ai-sdk/google-vertex test      # 如果更新了Vertex配置

</adding-new-model> <removing-obsolete-model>

Workflow for Removing an Obsolete Model ID

移除已废弃Model ID的工作流

Step 1: Identify Successor

步骤1：确定替代模型

Determine which model replaces the removed one in examples, tests, and docs. This is relevant for updating references.

If there is no obvious successor, you should leave old references in place in examples, docs, and tests.

确定在示例、测试和文档中替代被移除模型的模型。这对更新引用内容至关重要。

如果没有明确的替代模型，请保留示例、文档和测试中的旧引用。

Step 2: Find All Exact Occurrences

步骤2：查找所有精确匹配的引用

Search for the model ID with quotes to avoid substring false positives:

bash

undefined

使用带引号的方式搜索Model ID，避免子串误匹配：

bash

undefined

Single-quoted (TypeScript source, type unions)

单引号引用（TypeScript源码、类型联合）

grep -r "'<model-id>'" packages/ content/ examples/ --include='.ts' --include='.mdx' --include='.md' --include='.snap'

Double-quoted (JSON in snapshots, test fixtures with embedded JSON, docs)

双引号引用（快照中的JSON、包含嵌入式JSON的测试fixture、文档）

grep -r '"<model-id>"' packages/ content/ examples/ --include='.ts' --include='.mdx' --include='.md' --include='.snap'


Manually verify each result is the exact model and not a substring match (e.g. searching `'grok-3'` must not match `'grok-3-mini'`).

grep -r '"<model-id>"' packages/ content/ examples/ --include='.ts' --include='.mdx' --include='.md' --include='.snap'


手动验证每个结果都是精确匹配的模型，而非子串匹配（例如搜索`'grok-3'`时，请勿匹配`'grok-3-mini'`）。

Step 3: Remove from Type Definitions

步骤3：从类型定义中移除

Remove the

| 'model-id'

line from union types and entries from const arrays in

*-options.ts

files.

从

*-options.ts

文件的联合类型中移除

| 'model-id'

行，并从常量数组中移除对应的条目。

Step 4: Update Documentation

步骤4：更新文档

Remove rows from capability tables in
```
.mdx
```
files.
Replace inline code examples and descriptions referencing the removed model with the successor.

Update community provider docs in

content/providers/03-community-providers/

从
```
.mdx
```
文件的能力表格中移除对应行。
将引用被移除模型的内联代码示例和描述替换为替代模型。

更新

content/providers/03-community-providers/

中的社区供应商文档。

Step 5: Update Examples

步骤5：更新示例

Replace the removed model with the successor in example files that use it directly.
Remove from model lists in examples.
Delete dedicated example files only if no unique feature is demonstrated beyond the model itself (e.g. if the file is named after the model).

在直接使用被移除模型的示例文件中，将其替换为替代模型。
从示例中的模型列表中移除该模型。
仅当示例文件未展示模型本身之外的独特功能时（例如文件以模型命名），才删除专用示例文件。

Step 6: Update Tests and Snapshots

步骤6：更新测试和快照

Replace the model ID with the successor in
```
*.test.ts
```
files.
Replace the model ID in
```
__snapshots__/*.snap
```
files — model IDs appear in serialized JSON strings.
Replace in embedded JSON strings within test fixtures (e.g.
```
"model":"old-model"
```
→
```
"model":"new-model"
```
).
Update
```
examples/ai-functions/src/e2e/*.test.ts
```
— remove from model arrays or replace.
Update
```
packages/<provider>/README.md
```
if it contains code examples.

在
```
*.test.ts
```
文件中，将Model ID替换为替代模型的ID。
在
```
__snapshots__/*.snap
```
文件中替换Model ID —— Model ID会出现在序列化的JSON字符串中。
在测试fixture的嵌入式JSON字符串中替换（例如
```
"model":"old-model"
```
→
```
"model":"new-model"
```
）。
更新
```
examples/ai-functions/src/e2e/*.test.ts
```
—— 从模型数组中移除或替换该模型。
如果
```
packages/<provider>/README.md
```
包含代码示例，请同步更新。

Step 7: Run Tests

步骤7：运行测试

bash

pnpm --filter @ai-sdk/<provider> test

Also run tests for any other affected packages (same as Workflow A Step 7).

</removing-obsolete-model>

bash

pnpm --filter @ai-sdk/<provider> test

同时运行所有受影响包的测试（与添加新模型工作流的步骤7相同）。

</removing-obsolete-model>