You need to enable JavaScript to run this app.
文档中心
火山方舟

火山方舟

请输入
  • 文档首页
    • 火山方舟入门迁移到方舟官方 SDK
复制全文
下载 pdf
我的收藏
入门
迁移到方舟官方 SDK
复制全文
下载 pdf
我的收藏
迁移到方舟官方 SDK
方舟官方 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.*。​
完成依赖替换后，按以下步骤调整代码：​
  1. 使用上文所示的客户端初始化方法，并显式传入文档提供的 Base URL。​
  1. 将模型 ID、推理接入点 ID 和文件 ID 等占位符替换为当前账号下的真实资源。​
  1. 更新请求和响应类型的 import 路径。Java 生成模型包使用 models；Go 请求中的联合类型按当前 SDK 提供的构造器创建。​
  1. 检查流式代码的结束条件和空内容处理。正常的流结束信号不应当作为请求失败上报。​
  1. 按类型遍历 Responses API 的输出项，不要假设第一个输出项一定是最终文本。​
  1. 对文件、内容生成和 Responses 等包含资源生命周期的调用，使用当前请求创建的资源 ID，不要复用示例中的历史 ID。​
  1. 对照当前 SDK 的类型定义和 API 文档更新参数，不要直接沿用旧版 SDK 的生成类型。​
兼容使用旧版 SDK​
SDK 支持的 API 会随版本更新。迁移前请查看 Python、Go 和 Java 仓库 README 中的 API coverage。如果当前版本尚未提供目标 API 或所需参数，请继续使用旧版 SDK 或对应 REST API，待新版支持后再迁移。​
迁移检查清单​
  1. 在独立环境安装最新稳定版。​
  1. 替换依赖、import 和客户端初始化代码。​
  1. 使用通用客户端初始化方法，并显式配置当前渠道的 Base URL。​
  1. 更新请求类型、响应解析和流式结束处理。​
  1. 将示例占位符替换为账号下可访问的真实资源，并核对 API Key 和所需授权。​
  1. 验证同步、异步、流式和资源生命周期调用。​
  1. 在依赖文件中锁定验证通过的版本，再移除对应的旧版 SDK 调用。​
  1. 新版 SDK 尚未覆盖的 API 继续使用旧版 SDK 或 REST API。​
​
最近更新时间：2026.10.28 22:44:19
这个页面对您有帮助吗？
有用
有用
无用
无用