migrate-ai-sdk-v6-to-v7

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AI SDK 6 to 7 Migration

AI SDK 6 迁移至 7.0 指南

Use

content/docs/08-migration-guides/23-migration-guide-7-0.mdx

from the AI SDK repo as the source of truth. This skill is the working checklist; read the guide for exact examples or when behavior is unclear.

以AI SDK仓库中的

content/docs/08-migration-guides/23-migration-guide-7-0.mdx

作为权威参考。本技能是实用检查清单；如需确切示例或对行为存疑，请阅读该指南。

Migration Workflow

迁移流程

Ensure the user has a clean backup or committed baseline before editing.
Inspect
```
package.json
```
and lockfiles to identify installed
```
ai
```
,
```
@ai-sdk/*
```
, provider, UI, MCP, and telemetry packages.
Upgrade AI SDK packages to latest versions, and add
```
@ai-sdk/otel
```
only if the project uses OpenTelemetry spans.
Update runtime and module assumptions: Node.js must be
```
>=22
```
, and AI SDK packages are ESM-only. Replace
```
require()
```
imports with ESM imports and add
```
"type": "module"
```
or use
```
.mjs
```
where needed.
Search for the v6 patterns below, migrate only the code that exists, then run typecheck and targeted tests.

Prefer behavior-preserving changes. When v7 changes semantics, decide whether the app wants the new all-steps behavior or the previous final-step-only behavior.

确保用户在编辑前有干净的备份或已提交的基线版本。
检查
```
package.json
```
和锁文件，识别已安装的
```
ai
```
、
```
@ai-sdk/*
```
、提供商、UI、MCP和遥测包。
将AI SDK包升级至最新版本，仅当项目使用OpenTelemetry追踪时才添加
```
@ai-sdk/otel
```
。
更新运行时和模块假设：Node.js版本必须为
```
>=22
```
，且AI SDK包仅支持ESM。将
```
require()
```
导入替换为ESM导入，并在需要时添加
```
"type": "module"
```
或使用
```
.mjs
```
后缀。
搜索下方的v6代码模式，仅迁移现有代码，然后运行类型检查和针对性测试。

优先选择保留原有行为的变更。当v7改变语义时，需决定应用是想要新的全步骤行为还是之前的仅最终步骤行为。

Core API Changes

核心API变更

experimental_customProvider

customProvider

experimental_generateImage

generateImage

;

Experimental_GenerateImageResult

GenerateImageResult

experimental_transcribe

transcribe

;

Experimental_TranscriptionResult

TranscriptionResult

experimental_generateSpeech

generateSpeech

;

Experimental_SpeechResult

SpeechResult

```
experimental_output
```
option/result ->
```
output
```
option/result.

CallSettings

LanguageModelCallOptions & Omit<RequestOptions, 'timeout'>

;

prepareCallSettings

prepareLanguageModelCallOptions

```
stepCountIs
```
->
```
isStepCount
```
.

experimental_customProvider

替换为

customProvider

。

experimental_generateImage

替换为

generateImage

；

Experimental_GenerateImageResult

替换为

GenerateImageResult

。

experimental_transcribe

替换为

transcribe

；

Experimental_TranscriptionResult

替换为

TranscriptionResult

。

experimental_generateSpeech

替换为

generateSpeech

；

Experimental_SpeechResult

替换为

SpeechResult

。

```
experimental_output
```
选项/结果替换为
```
output
```
选项/结果。

CallSettings

替换为

LanguageModelCallOptions & Omit<RequestOptions, 'timeout'>

；

prepareCallSettings

替换为

prepareLanguageModelCallOptions

。

```
stepCountIs
```
替换为
```
isStepCount
```
。

Prompts and Steps

提示词与步骤

Rename top-level

system

instructions

for

generateText

streamText

generateObject

streamObject

, and

streamUI

Move
```
{ role: 'system' }
```
messages from
```
prompt
```
or
```
messages
```
into top-level
```
instructions
```
. Only use
```
allowSystemInMessages: true
```
for trusted persisted messages.
Rename
```
experimental_prepareStep
```
to
```
prepareStep
```
.
In
```
prepareStep
```
, rename returned
```
system
```
to
```
instructions
```
.

experimental_repairToolCall

, use

{ instructions }

instead of

{ system }

Audit
```
prepareStep
```
behavior: returned
```
instructions
```
and
```
messages
```
now carry forward into later steps. If code depended on one-step-only overrides, rebuild from
```
initialInstructions
```
,
```
initialMessages
```
, and
```
responseMessages
```
explicitly.

对

generateText

、

streamText

、

generateObject

、

streamObject

和

streamUI

，将顶层

system

重命名为

instructions

。

将
```
prompt
```
或
```
messages
```
中的
```
{ role: 'system' }
```
消息移至顶层
```
instructions
```
中。仅对受信任的持久化消息使用
```
allowSystemInMessages: true
```
。
将
```
experimental_prepareStep
```
重命名为
```
prepareStep
```
。
在
```
prepareStep
```
中，将返回的
```
system
```
重命名为
```
instructions
```
。

在

experimental_repairToolCall

中，使用

{ instructions }

替代

{ system }

。

检查
```
prepareStep
```
的行为：返回的
```
instructions
```
和
```
messages
```
现在会延续到后续步骤。如果代码依赖单步覆盖逻辑，请显式从
```
initialInstructions
```
、
```
initialMessages
```
和
```
responseMessages
```
重新构建。

Lifecycle Callbacks

生命周期回调

```
experimental_onStart
```
->
```
onStart
```
.
```
experimental_onStepStart
```
->
```
onStepStart
```
.
```
onFinish
```
->
```
onEnd
```
.
```
onStepFinish
```
->
```
onStepEnd
```
.

For

embed

embedMany

, and

rerank

experimental_onFinish

onEnd

Callback event fields use
```
instructions
```
instead of
```
system
```
.

```
experimental_onStart
```
替换为
```
onStart
```
。
```
experimental_onStepStart
```
替换为
```
onStepStart
```
。
```
onFinish
```
替换为
```
onEnd
```
。
```
onStepFinish
```
替换为
```
onStepEnd
```
。

对于

embed

、

embedMany

和

rerank

，

experimental_onFinish

替换为

onEnd

。

回调事件字段使用
```
instructions
```
替代
```
system
```
。

Usage, Telemetry, and Include Options

使用量、遥测与包含选项

usage.cachedInputTokens

usage.inputTokenDetails.cacheReadTokens

usage.reasoningTokens

usage.outputTokenDetails.reasoningTokens

OpenTelemetry moved out of
```
ai
```
; install
```
@ai-sdk/otel
```
and call
```
registerTelemetry(new OpenTelemetry(...))
```
at app startup.
Telemetry is enabled by default once an integration is registered. Remove redundant
```
isEnabled: true
```
; use
```
isEnabled: false
```
to opt out per call.

Move

experimental_telemetry.tracer

into the

OpenTelemetry

constructor.

```
experimental_telemetry
```
->
```
telemetry
```
.
Telemetry integration callbacks:
```
onRerankFinish
```
->
```
onRerankEnd
```
,
```
onEmbedFinish
```
->
```
onEmbedEnd
```
. Update tracing-channel subscribers for the same event type names.
```
experimental_include
```
->
```
include
```
.
```
includeRawChunks
```
->
```
include.rawChunks
```
.
Request and response bodies are excluded by default. If code reads
```
request.body
```
or
```
response.body
```
, opt in with
```
include.requestBody
```
and, for
```
generateText
```
,
```
include.responseBody
```
.

usage.cachedInputTokens

替换为

usage.inputTokenDetails.cacheReadTokens

。

usage.reasoningTokens

替换为

usage.outputTokenDetails.reasoningTokens

。

OpenTelemetry已从
```
ai
```
包中移出；安装
```
@ai-sdk/otel
```
并在应用启动时调用
```
registerTelemetry(new OpenTelemetry(...))
```
。
注册集成后，遥测默认启用。移除冗余的
```
isEnabled: true
```
；如需按调用禁用，使用
```
isEnabled: false
```
。

将

experimental_telemetry.tracer

移至

OpenTelemetry

构造函数中。

```
experimental_telemetry
```
替换为
```
telemetry
```
。
遥测集成回调：
```
onRerankFinish
```
替换为
```
onRerankEnd
```
，
```
onEmbedFinish
```
替换为
```
onEmbedEnd
```
。更新追踪通道订阅者以匹配新的事件类型名称。
```
experimental_include
```
替换为
```
include
```
。
```
includeRawChunks
```
替换为
```
include.rawChunks
```
。
请求和响应体默认被排除。如果代码需要读取
```
request.body
```
或
```
response.body
```
，需通过
```
include.requestBody
```
（对
```
generateText
```
还需
```
include.responseBody
```
）选择加入。

Streaming, Messages, and Tools

流式传输、消息与工具

```
StreamTextResult.fullStream
```
->
```
stream
```
.
```
streamText
```
```
onChunk
```
now receives all stream parts, including lifecycle, boundary, finish, abort, and error parts. Guard by
```
chunk.type
```
before assuming text/tool/raw content.
```
step.response.messages
```
is no longer accumulated across previous steps. Use
```
result.responseMessages
```
for the full response message history, or flatten
```
result.steps
```
.

Tool execution callbacks:

experimental_onToolCallStart

onToolExecutionStart

experimental_onToolCallFinish

onToolExecutionEnd

Tool callback
```
experimental_context
```
->
```
context
```
.
Split shared runtime data from tool-specific data: use top-level
```
runtimeContext
```
for orchestration state, declare per-tool
```
contextSchema
```
, and pass per-tool values through
```
toolsContext
```
.

Move

needsApproval

from

tool()

dynamicTool()

into per-call or agent

toolApproval

```
experimental_activeTools
```
->
```
activeTools
```
.
```
ToolCallOptions
```
->
```
ToolExecutionOptions
```
.
```
isToolOrDynamicToolUIPart
```
->
```
isToolUIPart
```
.

```
StreamTextResult.fullStream
```
替换为
```
stream
```
。
```
streamText
```
的
```
onChunk
```
现在会接收所有流部分，包括生命周期、边界、完成、中止和错误部分。在假设内容为文本/工具/原始类型前，需先判断
```
chunk.type
```
。
```
step.response.messages
```
不再累积之前步骤的内容。如需完整的响应消息历史，使用
```
result.responseMessages
```
，或展开
```
result.steps
```
。

工具执行回调：

experimental_onToolCallStart

替换为

onToolExecutionStart

，

experimental_onToolCallFinish

替换为

onToolExecutionEnd

。

工具回调的
```
experimental_context
```
替换为
```
context
```
。
将共享运行时数据与工具特定数据分离：使用顶层
```
runtimeContext
```
存储编排状态，声明每个工具的
```
contextSchema
```
，并通过
```
toolsContext
```
传递工具专属值。

将

needsApproval

从

tool()

dynamicTool()

移至单次调用或agent的

toolApproval

中。

```
experimental_activeTools
```
替换为
```
activeTools
```
。
```
ToolCallOptions
```
替换为
```
ToolExecutionOptions
```
。
```
isToolOrDynamicToolUIPart
```
替换为
```
isToolUIPart
```
。

Content Parts and Reasoning

内容部分与推理

Tool result
```
{ type: 'media' }
```
is removed; use
```
{ type: 'file-data' }
```
.

Migrate

toModelOutput

image-*

file-*

file-id

, and

image-file-id

variants to canonical

{ type: 'file', mediaType, data: { type: 'data' | 'url' | 'reference', ... } }

User message

{ type: 'image', image, mediaType? }

is deprecated; use

{ type: 'file', mediaType: 'image' | 'image/*', data }

Add support for the new
```
reasoning-file
```
content type in exhaustive switches, renderers, serializers, and validators.
When adopting top-level
```
reasoning
```
, remove overlapping provider-specific reasoning settings from
```
providerOptions
```
unless provider-specific settings intentionally take precedence.

移除工具结果中的
```
{ type: 'media' }
```
；改用
```
{ type: 'file-data' }
```
。

将

toModelOutput

的

image-*

、

file-*

、

file-id

和

image-file-id

变体迁移为标准格式

{ type: 'file', mediaType, data: { type: 'data' | 'url' | 'reference', ... } }

。

用户消息中的

{ type: 'image', image, mediaType? }

已弃用；改用

{ type: 'file', mediaType: 'image' | 'image/*', data }

。

在穷举开关、渲染器、序列化器和验证器中添加对新
```
reasoning-file
```
内容类型的支持。
采用顶层
```
reasoning
```
时，移除
```
providerOptions
```
中重复的提供商特定推理设置，除非有意让提供商特定设置优先。

Multi-Step Result Shape

多步骤结果结构

```
result.usage
```
now includes all steps;
```
result.totalUsage
```
is deprecated. Use
```
result.finalStep.usage
```
for final-step-only usage.

Top-level

content

toolCalls

staticToolCalls

dynamicToolCalls

toolResults

staticToolResults

dynamicToolResults

files

sources

, and

warnings

now include all steps. Use

finalStep

for previous final-step-only behavior.

Top-level

reasoning

reasoningText

request

response

, and

providerMetadata

are deprecated for final-step data. Use

result.finalStep.*

; for

streamText

, await

result.finalStep

Apply the same result-shape rules to
```
onEnd
```
events.

```
result.usage
```
现在包含所有步骤；
```
result.totalUsage
```
已弃用。如需仅最终步骤的使用量，使用
```
result.finalStep.usage
```
。

顶层的

content

、

toolCalls

、

staticToolCalls

、

dynamicToolCalls

、

toolResults

、

staticToolResults

、

dynamicToolResults

、

files

、

sources

和

warnings

现在包含所有步骤。如需之前仅最终步骤的行为，使用

finalStep

。

顶层的

reasoning

、

reasoningText

、

request

、

response

和

providerMetadata

已弃用，用于获取最终步骤数据请使用

result.finalStep.*

；对

streamText

，需等待

result.finalStep

。

将相同的结果结构规则应用于
```
onEnd
```
事件。

Stream Response Helpers

流响应助手

The

streamText

result helper methods are deprecated. Replace result methods with top-level stateless helpers:

result.toUIMessageStream(...)

toUIMessageStream({ stream: result.stream, ... })

result.toUIMessageStreamResponse(...)

toUIMessageStream(...)

plus

createUIMessageStreamResponse({ stream })

result.pipeUIMessageStreamToResponse(response, ...)

toUIMessageStream(...)

plus

pipeUIMessageStreamToResponse({ response, stream })

result.toTextStreamResponse()

toTextStream({ stream: result.stream })

plus

createTextStreamResponse({ stream })

result.pipeTextStreamToResponse(response)

toTextStream({ stream: result.stream })

plus

pipeTextStreamToResponse({ response, stream })

streamText

结果的助手方法已弃用。将结果方法替换为顶层无状态助手：

result.toUIMessageStream(...)

替换为

toUIMessageStream({ stream: result.stream, ... })

。

result.toUIMessageStreamResponse(...)

替换为

toUIMessageStream(...)

加上

createUIMessageStreamResponse({ stream })

。

result.pipeUIMessageStreamToResponse(response, ...)

替换为

toUIMessageStream(...)

加上

pipeUIMessageStreamToResponse({ response, stream })

。

result.toTextStreamResponse()

替换为

toTextStream({ stream: result.stream })

加上

createTextStreamResponse({ stream })

。

result.pipeTextStreamToResponse(response)

替换为

toTextStream({ stream: result.stream })

加上

pipeTextStreamToResponse({ response, stream })

。

Package-Specific Checks

包特定检查

MCP:
```
MCPTransportConfig.redirect
```
now defaults to
```
'error'
```
. Only set
```
redirect: 'follow'
```
for trusted MCP servers that rely on redirects.
Vue:
```
@ai-sdk/vue
```
```
Chat
```
class is deprecated. Prefer
```
useChat
```
, including getter/ref init for reactive chat inputs.

Anthropic and

@ai-sdk/google-vertex/anthropic

providerMetadata.anthropic.cacheCreationInputTokens

was removed. Use

usage.inputTokenDetails.cacheWriteTokens

; raw Anthropic usage remains at

finalStep.providerMetadata?.anthropic?.usage

Google: rename
```
GoogleGenerativeAI*
```
types, classes, and functions to
```
Google*
```
, e.g.
```
createGoogleGenerativeAI
```
->
```
createGoogle
```
. The
```
google
```
entry point is unchanged.

MCP：
```
MCPTransportConfig.redirect
```
现在默认值为
```
'error'
```
。仅当受信任的MCP服务器依赖重定向时，才设置
```
redirect: 'follow'
```
。
Vue：
```
@ai-sdk/vue
```
的
```
Chat
```
类已弃用。优先使用
```
useChat
```
，包括为响应式聊天输入初始化getter/ref。

Anthropic和

@ai-sdk/google-vertex/anthropic

：移除了

providerMetadata.anthropic.cacheCreationInputTokens

。使用

usage.inputTokenDetails.cacheWriteTokens

；原始Anthropic使用量仍可通过

finalStep.providerMetadata?.anthropic?.usage

获取。

Google：将
```
GoogleGenerativeAI*
```
类型、类和函数重命名为
```
Google*
```
，例如
```
createGoogleGenerativeAI
```
替换为
```
createGoogle
```
。
```
google
```
入口点保持不变。

Validation

验证

Run the project typecheck after edits, then the smallest relevant test suite. Also smoke-test streaming, chat UI, tool execution, telemetry, and multi-step flows if the migration touched them. If type errors remain, search the migration guide for the exact removed or renamed symbol before inventing a workaround.

编辑后运行项目类型检查，然后运行最小相关测试套件。如果迁移涉及流式传输、聊天UI、工具执行、遥测和多步骤流程，还需进行冒烟测试。如果仍存在类型错误，请先在迁移指南中搜索已移除或重命名的符号，再尝试寻找解决方法。