# 迁移到方舟官方 SDK

> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。

方舟官方 SDK 为 Python、Go 和 Java 提供统一的模型调用接口。本指南介绍如何从旧版渠道 SDK 迁移到最新版方舟官方 SDK。

建议先在独立测试环境中安装最新稳定版，并验证请求、流式输出、错误处理和资源生命周期。验证通过后，在生产项目的依赖文件中锁定实际使用的版本，再移除旧版依赖。

迁移期间可以同时保留新版与旧版 SDK。新版 SDK 暂未覆盖的 API 可以继续使用旧版 SDK 或对应 REST API。两套 SDK 使用不同的包名和导入路径，请分别初始化客户端，不要混用请求或响应类型。

<span id="sdk-migration-packages"></span>
## 安装新版 SDK

- **Python**：运行 `python -m pip install --upgrade arkruntime`。官方来源：[GitHub](https://github.com/volcengine/ark-runtime-python)、[PyPI](https://pypi.org/project/arkruntime/)。
- **Go**：运行 `go get github.com/volcengine/ark-runtime-go@latest`。官方来源：[GitHub](https://github.com/volcengine/ark-runtime-go)。
- **Java**：在构建文件中使用 Maven Central 提供的最新稳定版本。官方来源：[GitHub](https://github.com/volcengine/ark-runtime-java)、[Maven Central](https://central.sonatype.com/artifact/com.volcengine/ark-runtime)。

### Python

```bash
python -m pip install --upgrade arkruntime
```

```python
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

```bash
go get github.com/volcengine/ark-runtime-go@latest
```

```go
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](https://central.sonatype.com/artifact/com.volcengine/ark-runtime) 确认最新稳定版本，将 `ark-runtime.version` 设置为该版本，并在验证通过后提交锁定值。
不要在生产构建中使用 `LATEST` 或开放版本区间。

```xml
<dependency>
  <groupId>com.volcengine</groupId>
  <artifactId>ark-runtime</artifactId>
  <version>${ark-runtime.version}</version>
</dependency>
```

```java
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();
```

<span id="sdk-migration-changes"></span>
## 迁移要点

- **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。
2. 将模型 ID、推理接入点 ID 和文件 ID 等占位符替换为当前账号下的真实资源。
3. 更新请求和响应类型的 import 路径。Java 生成模型包使用 `models`；Go 请求中的联合类型按当前 SDK 提供的构造器创建。
4. 检查流式代码的结束条件和空内容处理。正常的流结束信号不应当作为请求失败上报。
5. 按类型遍历 Responses API 的输出项，不要假设第一个输出项一定是最终文本。
6. 对文件、内容生成和 Responses 等包含资源生命周期的调用，使用当前请求创建的资源 ID，不要复用示例中的历史 ID。
7. 对照当前 SDK 的类型定义和 API 文档更新参数，不要直接沿用旧版 SDK 的生成类型。

<span id="sdk-migration-gaps"></span>
## 兼容使用旧版 SDK

SDK 支持的 API 会随版本更新。迁移前请查看 [Python](https://github.com/volcengine/ark-runtime-python)、[Go](https://github.com/volcengine/ark-runtime-go) 和 [Java](https://github.com/volcengine/ark-runtime-java) 仓库 README 中的 API coverage。如果当前版本尚未提供目标 API 或所需参数，请继续使用旧版 SDK 或对应 REST API，待新版支持后再迁移。

<span id="sdk-migration-checklist"></span>
## 迁移检查清单

1. 在独立环境安装最新稳定版。
2. 替换依赖、import 和客户端初始化代码。
3. 使用通用客户端初始化方法，并显式配置当前渠道的 Base URL。
4. 更新请求类型、响应解析和流式结束处理。
5. 将示例占位符替换为账号下可访问的真实资源，并核对 API Key 和所需授权。
6. 验证同步、异步、流式和资源生命周期调用。
7. 在依赖文件中锁定验证通过的版本，再移除对应的旧版 SDK 调用。
8. 新版 SDK 尚未覆盖的 API 继续使用旧版 SDK 或 REST API。