方舟官方 SDK 为 Python、Go 和 Java 提供统一的模型调用接口。本指南介绍如何从旧版渠道 SDK 迁移到最新版方舟官方 SDK。
建议先在独立测试环境中安装最新稳定版，并验证请求、流式输出、错误处理和资源生命周期。验证通过后，在生产项目的依赖文件中锁定实际使用的版本，再移除旧版依赖。
迁移期间可以同时保留新版与旧版 SDK。新版 SDK 暂未覆盖的 API 可以继续使用旧版 SDK 或对应 REST API。两套 SDK 使用不同的包名和导入路径，请分别初始化客户端，不要混用请求或响应类型。
安装新版 SDK#
- Python：运行
python -m pip install --upgrade arkruntime。官方来源：GitHub、PyPI。 - Go：运行
go get github.com/volcengine/ark-runtime-go@latest。官方来源：GitHub。 - Java：在构建文件中使用 Maven Central 提供的最新稳定版本。官方来源：GitHub、Maven Central。
Python#
python -m pip install --upgrade arkruntime
import os
from arkruntime import Ark
client = Ark(
api_key=os.environ.get("ARK_API_KEY"),
base_url="https://ark.cn-beijing.volces.com/api/v3",
)
Go#
go get github.com/volcengine/ark-runtime-go@latest
import (
"os"
"github.com/volcengine/ark-runtime-go/arkruntime"
)
client := arkruntime.NewClientWithApiKey(
os.Getenv("ARK_API_KEY"),
arkruntime.WithBaseUrl("https://ark.cn-beijing.volces.com/api/v3"),
)
Java#
Maven 和 Gradle 的生产依赖必须使用具体版本。请从 Maven Central 确认最新稳定版本，将 ark-runtime.version 设置为该版本，并在验证通过后提交锁定值。
不要在生产构建中使用 LATEST 或开放版本区间。
<dependency>
<groupId>com.volcengine</groupId>
<artifactId>ark-runtime</artifactId>
<version>${ark-runtime.version}</version>
</dependency>
import com.volcengine.ark.runtime.service.ArkService;
ArkService service = ArkService.builder()
.apiKey(System.getenv("ARK_API_KEY"))
.baseUrl("https://ark.cn-beijing.volces.com/api/v3")
.build();
迁移要点#
- Python：将
volcengine-python-sdk[ark]、volcenginesdkarkruntime替换为arkruntime。 - Go：将
github.com/volcengine/volcengine-go-sdk/service/arkruntime替换为github.com/volcengine/ark-runtime-go/arkruntime。 - Java：将
com.volcengine:volcengine-java-sdk-ark-runtime、com.volcengine.ark.runtime.model.*替换为com.volcengine:ark-runtime、com.volcengine.ark.runtime.models.*。
完成依赖替换后，按以下步骤调整代码：
- 使用上文所示的客户端初始化方法，并显式传入文档提供的 Base URL。
- 将模型 ID、推理接入点 ID 和文件 ID 等占位符替换为当前账号下的真实资源。
- 更新请求和响应类型的 import 路径。Java 生成模型包使用
models；Go 请求中的联合类型按当前 SDK 提供的构造器创建。 - 检查流式代码的结束条件和空内容处理。正常的流结束信号不应当作为请求失败上报。
- 按类型遍历 Responses API 的输出项，不要假设第一个输出项一定是最终文本。
- 对文件、内容生成和 Responses 等包含资源生命周期的调用，使用当前请求创建的资源 ID，不要复用示例中的历史 ID。
- 对照当前 SDK 的类型定义和 API 文档更新参数，不要直接沿用旧版 SDK 的生成类型。
兼容使用旧版 SDK#
SDK 支持的 API 会随版本更新。迁移前请查看 Python、Go 和 Java 仓库 README 中的 API coverage。如果当前版本尚未提供目标 API 或所需参数，请继续使用旧版 SDK 或对应 REST API，待新版支持后再迁移。
迁移检查清单#
- 在独立环境安装最新稳定版。
- 替换依赖、import 和客户端初始化代码。
- 使用通用客户端初始化方法，并显式配置当前渠道的 Base URL。
- 更新请求类型、响应解析和流式结束处理。
- 将示例占位符替换为账号下可访问的真实资源，并核对 API Key 和所需授权。
- 验证同步、异步、流式和资源生命周期调用。
- 在依赖文件中锁定验证通过的版本，再移除对应的旧版 SDK 调用。
- 新版 SDK 尚未覆盖的 API 继续使用旧版 SDK 或 REST API。