目前，火山方舟SDK V3在易用性、功能丰富性、稳定性和性能等各方面远超V1/V2，且已经上线并稳定运行一段时间。火山方舟平台SDK V1/V2 版本将于2024年11月30日正式下线，不再支持调用。建议用户尽快核实SDK版本，并于旧版本下线前参照本迁移指引完成SDK V1/V2至SDK V3版本切换和业务迁移。

• 如果您使用的是火山方舟官方提供的 SDK，可以通过 import 路径判断：出现 ark 字样的为 V3 API，出现 maas 字样的为 V1/V2 API。各语言import路径如下所示：

  语言	V1/V2	V3
  Python	import volcengine.maas	from volcenginesdkarkruntime import Ark
  Go	import "github.com/volcengine/volc-sdk-golang/service/maas"	import "github.com/volcengine/volcengine-go-sdk/service/arkruntime"
  Java	import com.volcengine.service.maas.MaasService	import com.volcengine.ark.runtime.service.ArkService

• 如果您使用的是自行实现的 HTTP 接口，可以通过域名或 path 前缀判断。各语言域名及path前缀如下所示：

  	V1	V2	V3
  域名	ml-maas-api.bytedance.net	ark-cn-beijing.bytedance.net	ark.cn-beijing.volces.com
  path前缀	/api/v1	/api/v2	/api/v3

接口参数映射

新旧API URL对应表及详细接口参数映射说明如下：

api/v1/chat -> api/v3/chat/completions 参数映射

请求参数

响应参数

非流式调用

流式调用

api/v2/endpoint/:endpoint_id/chat -> api/v3/chat/completions 参数映射

请求参数

响应参数

非流式调用

流式调用

api/v2/endpoint/:endpoint_id/embeddings -> api/v3/embeddings 参数映射

请求参数

响应参数

api/v2/endpoint/:endpoint_id/tokenization -> api/v3/tokenization 参数映射

请求参数

响应参数

SDK 迁移

Python

v1/v2 支持 python 3.5+，v3 需要 python 3.7+，3.7 以下的版本如需使用方舟 API 建议参考 API Specification 实现 HTTP 调用，或使用兼容 openai-like 协议的第三方 SDK。

v1 和 v3 对比

# v1 [deprecated]
# python -m pip install --user volcengine
import os
from volcengine.maas import MaasService, MaasException, ChatRole

maas = MaasService('ml-maas-api.bytedance.net', 'cn-beijing')

maas.set_ak(os.getenv("VOLC_ACCESSKEY"))
maas.set_sk(os.getenv("VOLC_SECRETKEY"))

resp = maas.chat({
    "model": {
        "name": "skylark-pro",
    },
    "messages": [
        {"role": ChatRole.USER, "content": "hello"}
    ]
})

print(resp)

# v3 [recommended]
# pip install 'volcengine-python-sdk[ark]'
from  volcenginesdkarkruntime  import  Ark

client = Ark(
    api_key=os.environ.get("ARK_API_KEY"), # 这里同时支持通过 api_key 构造和通过 aksk 构造，二者选其一即可
    base_url="https://ark-cn-beijing.bytedance.net/api/v3" # 内部用户可以通过内网域名调用
)

completion = client.chat.completions.create(
    model="ep-xxxxxx-yyy",
    messages = [
        {"role": "user", "content": "hello"},
    ],
)
print(completion)

v2 和 v3 对比

# v2 [deprecated]
# python -m pip install --user volcengine
import os
from volcengine.maas.v2 import MaasService
from volcengine.maas import MaasException, ChatRole

maas = MaasService('ml-maas-api.bytedance.net', 'cn-beijing')

maas.set_ak(os.getenv("VOLC_ACCESSKEY"))
maas.set_sk(os.getenv("VOLC_SECRETKEY"))

resp = maas.chat("ep-xxxxxx-yyy", {
    "messages": [
        {"role": ChatRole.USER, "content": "hello"}
    ]
})
print(resp)

# v3 [recommended]
# pip install 'volcengine-python-sdk[ark]'
from  volcenginesdkarkruntime  import  Ark

client = Ark(
    api_key=os.environ.get("ARK_API_KEY"), # 这里同时支持通过 api_key 构造和通过 aksk 构造，二者选其一即可
    base_url="https://ark-cn-beijing.bytedance.net/api/v3" # 内部用户可以通过内网域名调用
)

completion = client.chat.completions.create(
    model="ep-xxxxxx-yyy",
    messages = [
        {"role": "user", "content": "hello"},
    ],
)
print(completion)

Golang

v3 需要 1.18 及以上的 golang 版本，1.18 以下的 golang 版本如需使用方舟 API 建议参考 API Specification 实现 HTTP 调用，或使用兼容 openai-like 协议的第三方 SDK。

v1 和 v3 对比

// v1 [deprecated]
// go get -u github.com/volcengine/volc-sdk-golang
import (
    "fmt"
    "os"

    "github.com/volcengine/volc-sdk-golang/service/maas"
    "github.com/volcengine/volc-sdk-golang/service/maas/models/api"
)

func main() {
    r := maas.NewInstance("ml-maas-api.bytedance.net", "cn-beijing")
    
    r.SetAccessKey(os.Getenv("VOLC_ACCESSKEY"))
    r.SetSecretKey(os.Getenv("VOLC_SECRETKEY"))
    
    got, status, err := r.Chat(&api.ChatReq{
        Model: &api.Model{
            Name: "skylark-pro",
        },
        Messages: []*api.Message{
            {
                Role:    maas.ChatRoleOfUser,
                Content: "hello",
            },
        },
    })
    
    if err != nil {
        panic(err)
    }
    
    fmt.Println(got)
}

// v3 [recommended]
// go get -u github.com/volcengine/volcengine-go-sdk
import (
    "context"
    "fmt"
    "os"

    "github.com/volcengine/volcengine-go-sdk/service/arkruntime"
    "github.com/volcengine/volcengine-go-sdk/service/arkruntime/model"
    "github.com/volcengine/volcengine-go-sdk/volcengine"
)

func main() {
    client := arkruntime.NewClientWithApiKey( // 这里同时支持通过 api_key 构造和通过 aksk 构造，二者选其一即可
        os.Getenv("ARK_API_KEY"),
        arkruntime.WithBaseUrl("https://ark-cn-beijing.bytedance.net/api/v3"), // 内部用户可以通过内网域名调用
    )
    
    resp, err := client.CreateChatCompletion(context.Background(), model.ChatCompletionRequest{
       Model: "ep-xxxxxx-yyy",
       Messages: []*model.ChatCompletionMessage{
          {
             Role: model.ChatMessageRoleUser,
             Content: &model.ChatCompletionMessageContent{
                StringValue: volcengine.String("hello"),
             },
          },
       },
    })
    if err != nil {
        panic(err)
    }
    fmt.Println(resp)
}

v2 和 v3 对比

// v2 [deprecated]
// go get -u github.com/volcengine/volc-sdk-golang
import (
    "fmt"
    "os"

    api  "github.com/volcengine/volc-sdk-golang/service/maas/models/api/v2"
        client  "github.com/volcengine/volc-sdk-golang/service/maas/v2"
)

func main() {
    r := client.NewInstance("ml-maas-api.bytedance.net", "cn-beijing")

    r.SetAccessKey(os.Getenv("VOLC_ACCESSKEY"))
    r.SetSecretKey(os.Getenv("VOLC_SECRETKEY"))
    
    got, status, err := r.Chat("ep-xxxxxx-yyy", &api.ChatReq{
       Messages: []*api.Message{
          {
             Role:    api.ChatRoleUser,
             Content: "hello",
          },
       },
    })
    if err != nil {
       panic(err)
    }
    fmt.Println(got)
}

// v3 [recommended]
// go get -u github.com/volcengine/volcengine-go-sdk
import (
    "context"
    "fmt"
    "os"

    "github.com/volcengine/volcengine-go-sdk/service/arkruntime"
    "github.com/volcengine/volcengine-go-sdk/service/arkruntime/model"
    "github.com/volcengine/volcengine-go-sdk/volcengine"
)

func main() {
    client := arkruntime.NewClientWithApiKey( // 这里同时支持通过 api_key 构造和通过 aksk 构造，二者选其一即可
        os.Getenv("ARK_API_KEY"),
        arkruntime.WithBaseUrl("https://ark-cn-beijing.bytedance.net/api/v3"), // 内部用户可以通过内网域名调用
    )
    
    resp, err := client.CreateChatCompletion(context.Background(), model.ChatCompletionRequest{
       Model: "ep-xxxxxx-yyy",
       Messages: []*model.ChatCompletionMessage{
          {
             Role: model.ChatMessageRoleUser,
             Content: &model.ChatCompletionMessageContent{
                StringValue: volcengine.String("hello"),
             },
          },
       },
    })
    if err != nil {
        panic(err)
    }
    fmt.Println(resp)
}

Java

v1 和 v3 对比

/*
v1 [deprecated]
# pom.xml
<dependency>
    <groupId>com.volcengine</groupId>
    <artifactId>volc-sdk-java</artifactId>
    <version>LATEST</version>
</dependency>
*/
import com.volcengine.helper.Const;
import com.volcengine.model.maas.api.Api;
import com.volcengine.service.maas.MaasException;
import  com.volcengine.service.maas.MaasService;

import com.volcengine.service.maas.impl.MaasServiceImpl;

public class ChatDemo {
    public static void main(String[] args) {
        MaasService maasService = new MaasServiceImpl("ml-maas-api.bytedance.net", "cn-beijing");

        maasService.setAccessKey(System.getenv("VOLC_ACCESSKEY"));
        maasService.setSecretKey(System.getenv("VOLC_SECRETKEY"));

        Api.ChatReq req = Api.ChatReq.newBuilder()
                .setModel(Api.Model.newBuilder().setName("skylark-pro"))
                .addMessages(Api.Message.newBuilder().setRole(Const.MaasChatRoleOfUser).setContent("hello"))
                .build();
        Api.ChatResp resp = maasService.chat(req);
        System.out.println(resp);
    }
}

/*
v3 [recommended]
# pom.xml
<dependency>
  <groupId>com.volcengine</groupId>
  <artifactId>volcengine-java-sdk-ark-runtime</artifactId>
  <version>LATEST</version>
</dependency>
*/
import  com.volcengine.ark.runtime.model.completion.chat.ChatCompletionRequest;

import  com.volcengine.ark.runtime.model.completion.chat.ChatMessage;

import  com.volcengine.ark.runtime.model.completion.chat.ChatMessageRole;

import  com.volcengine.ark.runtime.service.ArkService;

import java.util.ArrayList;
import java.util.List;

public class ChatCompletionsExample {
    public static void main(String[] args) {
    
        // 这里同时支持通过 api_key 构造和通过 aksk 构造，二者选其一即可
        String apiKey = System.getenv("ARK_API_KEY"); 
        ArkService service = ArkService.builder()
                .apiKey(apiKey)
                .baseUrl("https://ark-cn-beijing.bytedance.net/api/v3") // 内部用户可以通过内网域名调用
                .build();

        final List<ChatMessage> messages = new ArrayList<>();
        final ChatMessage message = ChatMessage.builder().role(ChatMessageRole.USER).content("hello").build();
        messages.add(userMessage);

        ChatCompletionRequest chatCompletionRequest = ChatCompletionRequest.builder()
                .model("ep-xxxxxx-yyy")
                .messages(messages)
                .build();

        service.createChatCompletion(chatCompletionRequest).getChoices().forEach(choice -> System.out.println(choice.getMessage().getContent()));

        // shutdown service before process exited.
        service.shutdownExecutor();
    }

}

v2 和 v3 对比

/*
v2 [deprecated]
# pom.xml
<dependency>
    <groupId>com.volcengine</groupId>
    <artifactId>volc-sdk-java</artifactId>
    <version>LATEST</version>
</dependency>
*/
import  com.volcengine.model.maas.api.v2.*;

import  com.volcengine.service.maas.MaasException;

import  com.volcengine.service.maas.v2.MaasService;

import  com.volcengine.service.maas.v2.impl.MaasServiceImpl;

import java.util.ArrayList;
import java.util.Arrays;
import java.util.stream.Stream;

public class ChatV2Demo {
    public static void main(String[] args) {
        MaasService maasService = new MaasServiceImpl("ml-maas-api.bytedance.net", "cn-beijing");

        maasService.setAccessKey(System.getenv("VOLC_ACCESSKEY"));
        maasService.setSecretKey(System.getenv("VOLC_SECRETKEY"));

        ChatReq req = new ChatReq()
                .withMessages(new ArrayList<>(Arrays.asList(
                        new Message().withRole(Message.ChatRole.USER).withContent("hello")
                )));

        ChatResp resp = maasService.chat("ep-xxxxxx-yyy", req);
        System.out.println(resp);
    }
}

/*
v3 [recommended]
# pom.xml
<dependency>
  <groupId>com.volcengine</groupId>
  <artifactId>volcengine-java-sdk-ark-runtime</artifactId>
  <version>LATEST</version>
</dependency>
*/
import  com.volcengine.ark.runtime.model.completion.chat.ChatCompletionRequest;

import  com.volcengine.ark.runtime.model.completion.chat.ChatMessage;

import  com.volcengine.ark.runtime.model.completion.chat.ChatMessageRole;

import  com.volcengine.ark.runtime.service.ArkService;

import java.util.ArrayList;
import java.util.List;

public class ChatCompletionsExample {
    public static void main(String[] args) {
    
        // 这里同时支持通过 api_key 构造和通过 aksk 构造，二者选其一即可
        String apiKey = System.getenv("ARK_API_KEY"); 
        ArkService service = ArkService.builder()
                .apiKey(apiKey)
                .baseUrl("https://ark-cn-beijing.bytedance.net/api/v3") // 内部用户可以通过内网域名调用
                .build();

        final List<ChatMessage> messages = new ArrayList<>();
        final ChatMessage message = ChatMessage.builder().role(ChatMessageRole.USER).content("hello").build();
        messages.add(userMessage);

        ChatCompletionRequest chatCompletionRequest = ChatCompletionRequest.builder()
                .model("ep-xxxxxx-yyy")
                .messages(messages)
                .build();

        service.createChatCompletion(chatCompletionRequest).getChoices().forEach(choice -> System.out.println(choice.getMessage().getContent()));

        // shutdown service before process exited.
        service.shutdownExecutor();
    }

}

多语言社区SDK及 Langchain 调用指南

• 火山方舟大模型/智能体调用 v3 API 与 OpenAI API 协议兼容，您可以使用兼容 OpenAI API 协议的多语言社区 SDK 调用火山方舟大模型/智能体 API。详细说明可参考多语言社区 SDK。

• 目前SDK v3支持通过 Langchain 接入方舟 API，由于方舟 V3 接口兼容 Openai 的接口协议，您可以通过 ChatOpenAI 使用，详细说明可参考多语言社区 SDK。

联网插件切换

主要以 Python 为例，其余语言类似请参考：

• API Spec / 操作指南

• Python / Golang / Java

chat v1

import os
from volcengine.maas import MaasService, MaasException, ChatRole

maas = MaasService('ml-maas-api.bytedance.net', 'cn-beijing')

maas.set_ak(os.getenv("VOLC_ACCESSKEY"))
maas.set_sk(os.getenv("VOLC_SECRETKEY"))

resp = maas.chat({
    "model": {
        "name": "skylark-pro",
    },
    "messages": [
        {"role": ChatRole.USER, "content": "hello"}
    ],
    "plugins": ["browsing"],
})

print(resp)

bot chat v3

智能体中心>创建智能体>零代码>单聊>创建详情页

from  volcenginesdkarkruntime  import  Ark

client = Ark(
    api_key=os.environ.get("ARK_API_KEY"), # 这里同时支持通过 api_key 构造和通过 aksk 构造，二者选其一即可
    base_url="https://ark-cn-beijing.bytedance.net/api/v3" # 内部用户可以通过内网域名调用
)

completion = client.bot_chat.completions.create(
    model="bot-xxxxxx-yyy",
    messages = [
        {"role": "user", "content": "hello"},
    ],
)
print(completion)

V3 API 的详细说明参见 大模型调用指南，V3 SDK 的详细说明参见 SDK 调用指南。如有其他迁移问题，可以通过提交工单的方式，进行咨询。

本期下线时间说明