# 安装及升级 SDK

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

方舟提供了 Python 、 Go 和 Java 的 SDK ，方便使用对应编程语言快速调用方舟的模型服务。

推荐新项目使用最新稳定版方舟官方 SDK。对于新版 SDK 暂未支持的 API，可继续安装并使用旧版渠道 SDK；两套 SDK 的包名和导入路径不同，可以在迁移期间并存。请仅在对应代码路径中初始化所需客户端，避免混用请求或响应类型。

<span id="2708d57e"></span>
# Python SDK

<span id="f2baa8aa"></span>
## 前提条件

本地已安装了 Python ，且版本不低于 3.8。

> 可在终端中通过命令确认 Python 版本。

```Bash
python -V
```

> Python 可使用 [UV](https://docs.astral.sh/uv/) 安装，并通过它来管理虚拟环境。UV 是一个 Rust 编写的、速度极快的 Python 包和项目管理器，可以方便进行环境隔离，避免干扰您系统中已有的 Python 配置。

<span id="bb014324"></span>
## 安装 Python SDK

推荐安装最新版方舟官方 SDK：

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

在代码中使用：

```Python
from arkruntime import Ark
```

如需调用新版 SDK 暂不支持的 API，可继续安装旧版渠道 SDK：

```Bash
pip install 'volcengine-python-sdk[ark]'
```

> **说明**
>
> 如本地安装错误，可尝试下面方法：
> * Windows CMD 不支持单引号作为引用符。如在 Windows CMD 中执行，请改用双引号：
>   ```Bash
>   pip install "volcengine-python-sdk[ark]"
>   ```
>
> * [Windows系统安装SDK失败，ERROR: Failed building wheel for volcengine-python-sdk](/docs/modelark-faq#b74e8ad6)
> * 也可尝试使用 [uv](https://docs.astral.sh/uv/) 安装，速度更快：
>   ```Bash
>   uv pip install 'volcengine-python-sdk[ark]'
>   ```
> * 如需源码安装，下载并解压对应版本的 SDK 包，进入目录执行：
>   ```Bash
>   pip install .
>   ```

<span id="d6b883b8"></span>
## 升级 Python SDK

升级方舟官方 SDK：

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

升级旧版渠道 SDK：

```Bash
pip install -U 'volcengine-python-sdk[ark]'
```

<span id="f116fb9f"></span>
# Go SDK

<span id="0fa8c2bc"></span>
## 前提条件

检查 Go 版本，需 1.20 或以上。

```Bash
go version
```

如未安装或版本不满足，可访问 [Go 语言官方网站](https://golang.google.cn/dl/) 下载并安装，请选择 1.20 或以上版本。

<span id="ae8b42ab"></span>
## 安装 Go SDK

1. Go SDK 使用 go mod 管理，可运行以下命令初始化 go mod。`<YOUR_PROJECT_NAME>` 替换为项目名称。

    ```Bash
    # 如在文件夹 ark-demo 下打开终端窗口，运行命令go mod init ark-demo
    go mod init <YOUR_PROJECT_NAME>
    ```

2. 在本地初始化 go mod 后，运行以下命令安装最新版方舟官方 SDK。

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

3. 在代码中引入方舟官方 SDK。

    ```Go
    import "github.com/volcengine/ark-runtime-go/arkruntime"
    ```

> **说明**
>
> 如需锁定已验证版本，将 `latest` 替换为具体版本号。版本信息参见 [ark-runtime-go Releases](https://github.com/volcengine/ark-runtime-go/releases)。

如需调用新版 SDK 暂不支持的 API，可继续安装并引入旧版渠道 SDK：

```Bash
go get -u github.com/volcengine/volcengine-go-sdk
```

```Go
import "github.com/volcengine/volcengine-go-sdk/service/arkruntime"
```

4. 更新依赖后，使用命令整理依赖。

    ```Bash
    go mod tidy
    ```

<span id="f0739bb0"></span>
## 升级 Go SDK

* 将方舟官方 SDK 升级至最新版本：

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

* 将方舟官方 SDK 升级至指定版本：

    ```Bash
    go get github.com/volcengine/ark-runtime-go@<VERSION>
    ```

* 升级旧版渠道 SDK：

  ```Bash
  go get -u github.com/volcengine/volcengine-go-sdk@<VERSION>
  ```

<span id="e7ae2925"></span>
# Java SDK

<span id="41f31f3c"></span>
## 适用范围

本 SDK 仅适用于 Java 服务端开发，暂不支持 Android 平台。若需在 Android 平台使用相关功能，需由客户自行开发适配方案。

<span id="e3518e9f"></span>
## 前提条件

1. 检查并安装 Java 版本，Java 版本需 1.8 或以上。

    ```Bash
    java -version
    ```

如未安装 Java 或者版本不满足要求，可访问 [Oracle 官方网站](https://www.java.com/en/download/help/index_installing.html) 下载并安装适合操作系统的 Java 版本。请确保选择 1.8 或以上版本。

<span id="ae8db863"></span>
## 安装 Java SDK

火山方舟 Java SDK 支持通过 Maven 安装、通过 Gradle 安装两种方式。

### 安装方舟官方 SDK（推荐）

推荐新项目使用方舟官方 SDK。请从 [Maven Central](https://central.sonatype.com/artifact/com.volcengine/ark-runtime) 获取最新稳定版本，并将 `<VERSION>` 替换为该版本号。

```XML
<dependency>
  <groupId>com.volcengine</groupId>
  <artifactId>ark-runtime</artifactId>
  <version><VERSION></version>
</dependency>
```

```Groovy
implementation "com.volcengine:ark-runtime:<VERSION>"
```

### 安装旧版渠道 SDK

如需调用新版 SDK 暂不支持的 API，可继续使用以下旧版渠道 SDK。请将 `<VERSION>` 替换为方舟 Java SDK 最新版本号，SDK 版本可查询：https://central.sonatype.com/artifact/com.volcengine/volcengine-java-sdk-ark-runtime。如需安装指定版本 SDK，也可替换为具体版本号。

<span id="db12484d"></span>
#### 通过 Maven 安装

在 `pom.xml` 文件中进行如下配置，完整配置可参考 [Maven Central](https://central.sonatype.com/artifact/com.volcengine/volcengine-java-sdk-ark-runtime)：

```XML
...
<dependency>
  <groupId>com.volcengine</groupId>
  <artifactId>volcengine-java-sdk-ark-runtime</artifactId>
  <version><VERSION></version>
</dependency>
...
```

<span id="4858e8c3"></span>
#### 通过 Gradle 安装

在 `build.gradle` 文件中进行如下配置，在 `dependencies` 中添加依赖。

```plaintext
implementation 'com.volcengine:volcengine-java-sdk-ark-runtime:<VERSION>'
```

<span id="4ab4182d"></span>
## 升级 Java SDK

### 升级方舟官方 SDK

使用 Maven Central 上的最新稳定版本替换 `<VERSION>`，验证通过后在构建文件中锁定该版本。

### 升级旧版渠道 SDK

旧版渠道 SDK 请按下方方式查询和升级。

> **说明**
>
> 获取 SDK 版本信息，将 `<VERSION>` 替换为指定/最新版本号。SDK版本号可查询：[https://github.com/volcengine/volcengine-java-sdk/releases](https://github.com/volcengine/volcengine-java-sdk/releases)

同安装 Java SDK，指定需升级的版本号即可。

<span id="6f32c555"></span>
# 第三方SDK

火山方舟模型调用 API 与 OpenAI API 协议兼容，可使用兼容 OpenAI API 协议的多语言社区 SDK 调用火山方舟大模型或应用。可很方便地迁移模型服务至方舟平台以及 Doubao 大模型。具体使用方法请参考[兼容 OpenAI SDK](/docs/compatible-with-openai-sdk)。
<span id="4b8511f6"></span>
# 相关文档

[SDK 常见使用示例](/docs/sdk-common-examples)：包含SDK的常见用法。