SDK 常见使用示例

当您使用官方 SDK 时，设置自定义header等典型的使用，可以参考本说明。

设置超时&重试次数#

当您的网络环境不稳定或者响应时间较长的场景，可以设置超时和重试次数，以提高服务可用性。

超时设置（timeout）：适用于对响应时间较长的场景（如深度思考模型回复问题时间较长），避免请求时间超时导致服务中断，这里推荐30分钟（1800秒）。
- Python SDK：默认 60秒连接超时（建立网络连接的最大等待时间），600 秒 socket 超时（连接建立后的数据传输超时）。
- Java SDK：默认 60秒连接超时，600 秒 socket 超时。
- Go SDK：默认 600s 端到端的总超时（从请求发起至响应接收的总超时）。
重试次数（max_retries）：适用于网络不稳定场景，自动重试因瞬时故障（如网络波动）失败的请求，默认2次，即请求失败默认会再重试2次，您可以按需配置。

1
2
3
4
5
6
7
8
9
10
11
12import os
# Install the Ark SDK with: python -m pip install --upgrade arkruntime .
from arkruntime import Ark

client = Ark(
    api_key=os.environ.get("ARK_API_KEY"),
    # Allow enough time for long-running requests.
    timeout=1800,
    # Retry transient failures up to two times.
    max_retries=2,
    base_url="https://ark.cn-beijing.volces.com/api/v3",
)

1
2
3
4
5
6
7
8
9
10
11
12import (
    "os"
    "time"
    "github.com/volcengine/ark-runtime-go/arkruntime"
)

client := arkruntime.NewClientWithApiKey(
    os.Getenv("ARK_API_KEY"),
    arkruntime.WithTimeout(30*time.Minute), // Allow enough time for long-running requests.
    arkruntime.WithRetryTimes(2),           // Retry transient failures up to two times.
    arkruntime.WithBaseUrl("https://ark.cn-beijing.volces.com/api/v3"),
)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17import java.time.Duration;
import com.volcengine.ark.runtime.service.ArkService;

public class ConfigureSdkTimeoutRetryExample {
    public static void main(String[] args) {
        String apiKey = System.getenv("ARK_API_KEY");
        ArkService service = ArkService.builder()
            .apiKey(apiKey)
            .timeout(Duration.ofMinutes(30))
            .connectTimeout(Duration.ofSeconds(20))
            .retryTimes(2)
            .baseUrl("https://ark.cn-beijing.volces.com/api/v3")
            .build();

        service.shutdownExecutor();
    }
}

使用Access Key鉴权#

当需要通过火山引擎云服务的标准鉴权体系（Access Key/Secret Key）认证时使用。

使用 Access Key 鉴权的实现原理是通过接口 GetApiKey 获取临时 API Key 进行鉴权，此接口限流较低，务必使用单例模式进行请求，避免因限流导致鉴权失败，可参考单例请求。

1
2
3
4
5
6
7
8
9import os
# 通过命令安装方舟SDK python -m pip install --upgrade arkruntime .
from arkruntime import Ark
client = Ark(
    ak=os.environ.get("VOLC_ACCESSKEY"),
    sk=os.environ.get("VOLC_SECRETKEY"),
    # The base URL for model invocation .
    base_url="https://ark.cn-beijing.volces.com/api/v3",
)

1
2
3
4
5
6
7
8
9
10import (
    "os"
    "github.com/volcengine/ark-runtime-go/arkruntime"
)

client := arkruntime.NewClientWithAkSk(
        os.Getenv("VOLC_ACCESSKEY"),
        os.Getenv("VOLC_SECRETKEY"),
        arkruntime.WithBaseUrl("https://ark.cn-beijing.volces.com/api/v3"), // The base URL for model invocation .
)

1
2
3
4
5
6
7
8
9
10
11
12
13import com.volcengine.ark.runtime.service.ArkService;

public class CreateArkClientExample1 {
    public static void main(String[] args) {
        String ak = System.getenv("VOLC_ACCESSKEY");
        String sk = System.getenv("VOLC_SECRETKEY");
        ArkService service = ArkService.builder().ak(ak).sk(sk)
                // The base URL for model invocation .
                .baseUrl("https://ark.cn-beijing.volces.com/api/v3")
                .build();
    }
    // do your operation...
}

设置自定义 header#

自定义的 header 字段采用键值对（key-value）结构，以对象形式呈现，具体格式示例如下：

1
2
3
4
5
6{
    "key1": "value1",
    "key2": "value2",
    ...,
    "keyN": "valueN"
}

可以用于传递额外信息，如配置 ID来串联日志，使能数据加密能力。支持该字段的接口有对话（Chat） API、批量（Chat）API，下面是典型示例。

问题定位#

您可以在请求时，为多个请求设置 key 为 X-Client-Request-Id，value 配置为自定义的 ID，并提供 ID 给方舟售后团队，为您串联客户端和服务端日志，方便问题定位。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20import os
# 通过命令安装方舟SDK python -m pip install --upgrade arkruntime
from arkruntime import Ark

client = Ark(
    api_key=os.environ.get("ARK_API_KEY"),
    # The base URL for model invocation .
    base_url="https://ark.cn-beijing.volces.com/api/v3",
)

completion = client.chat.completions.create(
    # Replace with Model ID .
    model = "doubao-seed-2-1-pro-260915",
    messages = [
        {"role": "user", "content": "Hello"},
    ],
    # 自定义request id
    extra_headers={"X-Client-Request-Id": "My-Request-Id"}
)
print(completion.choices[0].message.content)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48package main

import (
    "context"
    "fmt"
    "os"
    "github.com/volcengine/ark-runtime-go/arkruntime"
    arkmodel "github.com/volcengine/ark-runtime-go/arkruntime/model"
    "github.com/volcengine/ark-runtime-go/arkruntime/model/chat"
)

func main() {
    client := arkruntime.NewClientWithApiKey(
        os.Getenv("ARK_API_KEY"),
        arkruntime.WithBaseUrl("https://ark.cn-beijing.volces.com/api/v3"), // The base URL for model invocation .
    )
    ctx := context.Background()
    req := &chat.ChatCompletionRequest{
        Model: "doubao-seed-2-1-pro-260915", //Replace with Model ID .
        Messages: []chat.ChatCompletionRequestMessage{
userMessage("Hello"),
        },
    }


    // 自定义request id
    resp, err := client.CreateChatCompletion(
        ctx,
        req,
        arkruntime.WithCustomHeader(arkmodel.ClientRequestHeader, "my-request-id"), // 自定义请求头
    )
    if err != nil {
        fmt.Printf("standard chat error: %v\n", err)
        return
    }
    fmt.Println(resp.Choices[0].Message.Content)
}

func userMessage(content string) chat.ChatCompletionRequestMessage {
    return chat.ChatCompletionRequestMessage{
        OneOf: chat.NewChatCompletionRequestUserMessageChatCompletionRequestMessageSum(
            chat.ChatCompletionRequestUserMessage{
                Role: chat.ChatCompletionRequestUserMessageRoleUser,
                Content: chat.NewOptNilChatCompletionMessageContent(chat.NewStringChatCompletionMessageContent(content)),
            },
        ),
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29package com.example;

import com.volcengine.ark.runtime.Const;
import com.volcengine.ark.runtime.models.chat.*;
import com.volcengine.ark.runtime.service.ArkService;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;

public class ChatCompletionsExample3 {
    public static void main(String[] args) {
        String apiKey = System.getenv("ARK_API_KEY");
        // The base URL for model invocation .
        ArkService arkService = ArkService.builder().apiKey(apiKey)
                .baseUrl("https://ark.cn-beijing.volces.com/api/v3")
                .build();
        final List<ChatCompletionRequestMessage> messages = new ArrayList<>();
        final ChatCompletionRequestMessage userMessage = ChatCompletionRequestUserMessage.builder().role(ChatCompletionRequestMessageType.USER).content(ChatCompletionMessageContent.ofString("常见的十字花科植物有哪些？")).build();
        messages.add(userMessage);
        ChatCompletionRequest chatCompletionRequest = ChatCompletionRequest.builder()
                .model("doubao-seed-2-1-pro-260915") //Replace with Model ID .
                .messages(messages)
                .build();
        // 使用自定义的请求头
        arkService.createChatCompletion(chatCompletionRequest, new HashMap<String, String>(){{put(Const.CLIENT_REQUEST_HEADER, "my_request_id");}}).getChoices().forEach(choice -> System.out.println(choice.getMessage().getContent()));
        // shutdown service
        arkService.shutdownExecutor();
    }
}

加密数据#

为了保证推理会话数据的传输安全，你可以为在线推理的会话数据加密。使能能力后，SDK 会对推理会话的内容进行加密。

更多能力介绍和原理信息请参考推理会话数据应用层加密方案。

版本要求：
- Python SDK：需要保证 arkruntime 版本为 0.5.0 及以上。参考升级 Python SDK升级 SDK。
- Java SDK：需要保证 com.volcengine:ark-runtime 版本为 0.5.0 及以上。参考升级 Java SDK升级 SDK。
能力支持：
- 仅支持文本生成模型和视觉理解图片理解模型请求。
- 图片仅支持 Base64 图片加密， URL 图片无法加密。
- 仅支持官方 Python SDK、Java SDK 的 Chat API 。
- 支持单轮、多轮会话，支持流式、非流式，同步、异步调用。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20import os
# 通过命令安装方舟SDK python -m pip install --upgrade arkruntime
from arkruntime import Ark

client = Ark(
    api_key=os.environ.get("ARK_API_KEY"),
    # The base URL for model invocation .
    base_url="https://ark.cn-beijing.volces.com/api/v3",
)

completion = client.chat.completions.create(
    # Replace with Model ID .
    model = "doubao-seed-2-1-pro-260915",
    messages = [
        {"role": "user", "content": "Hello"},
    ],
    #按下述代码设置自定义header，免费开启推理会话应用层加密
    extra_headers={'x-is-encrypted': 'true'}
)
print(completion.choices[0].message.content)

在 pom.xml 文件中增加以下配置：

1
2
3
4
5
6
7
8
9
10
11
12
13
14<dependencies>
    <!-- BouncyCastle 核心加密库（bcpkix依赖此包） -->
    <dependency>
        <groupId>org.bouncycastle</groupId>
        <artifactId>bcprov-jdk18on</artifactId>
        <version>1.78.1</version>
    </dependency>
    <!-- 包含PEMParser的模块（处理PEM格式证书） -->
    <dependency>
        <groupId>org.bouncycastle</groupId>
        <artifactId>bcpkix-jdk18on</artifactId>
        <version>1.78.1</version>
    </dependency>
</dependencies>

代码示例如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39package com.ark.sample;

import com.volcengine.ark.runtime.models.chat.*;
import com.volcengine.ark.runtime.service.ArkService;
import java.time.Duration;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import java.util.HashMap;

public class ChatCompletionsExample {
    public static void main(String[] args) {
        String apiKey = System.getenv("ARK_API_KEY");
        ArkService service = ArkService.builder()
                .apiKey(apiKey)
                .baseUrl("https://ark.cn-beijing.volces.com/api/v3")
                .timeout(Duration.ofSeconds(1800)) // Set the backend request processing timeout in seconds, recommended to be 1800 seconds or longer
                .connectTimeout(Duration.ofSeconds(20)) // Set the connection timeout to 20 seconds
                .retryTimes(2)// Set the retry count to 2
                .build();
        final List<ChatCompletionRequestMessage> messages = new ArrayList<>();
        final ChatCompletionRequestMessage userMessage = ChatCompletionRequestUserMessage.builder().role(ChatCompletionRequestMessageType.USER).content(ChatCompletionMessageContent.ofString("Hello"))
                .build();
        messages.add(userMessage);

        ChatCompletionRequest chatCompletionRequest = ChatCompletionRequest.builder()
                .model("doubao-seed-2-1-pro-260915") //Replace with Model ID
                .messages(messages)
                .build();

        // Set custom headers with the code below to enable application-layer encryption for inference sessions at no cost
        Map<String, String> customHeaders = new HashMap<>();
        customHeaders.put("x-is-encrypted", "true");
        service.createChatCompletion(chatCompletionRequest, customHeaders).getChoices()
                .forEach(choice -> System.out.println(choice.getMessage().getContent()));
        // shutdown service
        service.shutdownExecutor();
    }
}

开启数据上报#

为了便于快速排查和定位问题，你可以在 Responses API 请求的 header 中增加"X-Fornax-Trace: true"开启数据上报。支持统计分析的数据见分析统计。

该能力限时免费提供使用。

版本要求：如果请求上报未生效，需升级 SDK 到最新版本。
能力支持：仅支持 Responses API。

1
2
3
4
5
6
7
8
9
10
11
12
13
14import os
from arkruntime import Ark

client = Ark(
    base_url='https://ark.cn-beijing.volces.com/api/v3',
    api_key=os.getenv('ARK_API_KEY'),
)

response = client.responses.create(
    model="<Endpoint_ID>",
    input="hello",
    extra_headers={'X-Fornax-Trace': 'true'}
)
print(response)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28package main

import (
    "context"
    "fmt"
    "os"
    "github.com/volcengine/ark-runtime-go/arkruntime"
    "github.com/volcengine/ark-runtime-go/arkruntime/model/responses"
)

func main() {
    client := arkruntime.NewClientWithApiKey(
        // Get API Key: https://ark.volcengine.com/region:cn-beijing/apikey
        os.Getenv("ARK_API_KEY"),
        arkruntime.WithBaseUrl("https://ark.cn-beijing.volces.com/api/v3"),
    )
    ctx := context.Background()

    resp, err := client.CreateResponses(ctx, &responses.ResponsesRequest{
        Model: "<Endpoint_ID>",
        Input: responses.NewStringResponsesInput("hello"),
    }, arkruntime.WithCustomHeader("X-Fornax-Trace", "true"))
    if err != nil {
        fmt.Printf("response error: %v\n", err)
        return
    }
    fmt.Println(resp)
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27package com.ark.sample;

import com.volcengine.ark.runtime.service.ArkService;
import com.volcengine.ark.runtime.models.responses.*;
import java.util.HashMap;
import java.util.Map;

public class demo {
    public static void main(String[] args) {
        String apiKey = System.getenv("ARK_API_KEY");
        // The base URL for model invocation
        ArkService arkService = ArkService.builder().apiKey(apiKey)
                .baseUrl("https://ark.cn-beijing.volces.com/api/v3")
                .build();

        ResponsesRequest request = ResponsesRequest.builder()
                .model("<Endpoint_ID>")
                .input(ResponsesInput.ofString("hello"))
                .build();
        Map<String, String> customHeaders = new HashMap<>();
        customHeaders.put("X-Fornax-Trace", "true");
        Response resp = arkService.createResponse(request, customHeaders);
        System.out.println(resp);

        arkService.shutdownExecutor();
    }
}

单例请求#

请使用单例方式请求模型服务，勿重复创建实例导致额外资源消耗。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29import os
# 通过命令安装方舟SDK python -m pip install --upgrade arkruntime
from arkruntime import Ark

client = Ark(
    # Get API Key: https://ark.volcengine.com/region:cn-beijing/apikey
    api_key=os.environ.get("ARK_API_KEY"),
    # The base URL for model invocation .
    base_url="https://ark.cn-beijing.volces.com/api/v3",
)

# 请求1
completion = client.chat.completions.create(
    model="doubao-seed-2-1-pro-260915",
    messages=[
        {"role": "user", "content": "Nice day"},
    ],
)
print(completion.choices[0].message.content)


# 请求2
completion = client.chat.completions.create(
    model="doubao-seed-2-1-pro-260915",
    messages=[
        {"role": "user", "content": "Hello"},
    ],
)
print(completion.choices[0].message.content)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59package main

import (
    "context"
    "fmt"
    "os"
    "github.com/volcengine/ark-runtime-go/arkruntime"
    "github.com/volcengine/ark-runtime-go/arkruntime/model/chat"
)

func main() {
    client := arkruntime.NewClientWithApiKey(
        os.Getenv("ARK_API_KEY"),
        arkruntime.WithBaseUrl("https://ark.cn-beijing.volces.com/api/v3"), // The base URL for model invocation .
    )
    ctx := context.Background()
    // 第一次请求
    req1 := &chat.ChatCompletionRequest{
       // Replace with Model ID .
       Model: "doubao-seed-2-1-pro-260915",
       Messages: []chat.ChatCompletionRequestMessage{
userMessage("Nice day"),
       },
    }

    resp1, err := client.CreateChatCompletion(ctx, req1)
    if err != nil {
       fmt.Printf("standard chat error: %v\n", err)
       return
    }
    fmt.Println(resp1.Choices[0].Message.Content)

    // 第二次请求
    req2 := &chat.ChatCompletionRequest{
       // Replace with Model ID .
       Model: "doubao-seed-2-1-pro-260915",
       Messages: []chat.ChatCompletionRequestMessage{
userMessage("Hello"),
       },
    }

    resp2, err := client.CreateChatCompletion(ctx, req2)
    if err != nil {
       fmt.Printf("standard chat error: %v\n", err)
       return
    }
    fmt.Println(resp2.Choices[0].Message.Content)
}

func userMessage(content string) chat.ChatCompletionRequestMessage {
    return chat.ChatCompletionRequestMessage{
        OneOf: chat.NewChatCompletionRequestUserMessageChatCompletionRequestMessageSum(
            chat.ChatCompletionRequestUserMessage{
                Role: chat.ChatCompletionRequestUserMessageRoleUser,
                Content: chat.NewOptNilChatCompletionMessageContent(chat.NewStringChatCompletionMessageContent(content)),
            },
        ),
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37package com.example;

import com.volcengine.ark.runtime.models.chat.*;
import com.volcengine.ark.runtime.service.ArkService;
import java.util.ArrayList;
import java.util.List;

public class ChatCompletionsExample4 {
    public static void main(String[] args) {
        String apiKey = System.getenv("ARK_API_KEY");
        // The base URL for model invocation .
        ArkService arkService = ArkService.builder().apiKey(apiKey)
                .baseUrl("https://ark.cn-beijing.volces.com/api/v3")
                .build();

        // 第一次请求
        final List<ChatCompletionRequestMessage> messages1 = new ArrayList<>();
        final ChatCompletionRequestMessage userMessage1 = ChatCompletionRequestUserMessage.builder().role(ChatCompletionRequestMessageType.USER).content(ChatCompletionMessageContent.ofString("今天天气不错？")).build();
        messages1.add(userMessage1);
        ChatCompletionRequest chatCompletionRequest1 = ChatCompletionRequest.builder()
                .model("doubao-seed-2-1-pro-260915")// Replace with Model ID .
                .messages(messages1)
                .build();
        arkService.createChatCompletion(chatCompletionRequest1).getChoices().forEach(choice -> System.out.println(choice.getMessage().getContent()));
        // 第二次请求
        final List<ChatCompletionRequestMessage> messages2 = new ArrayList<>();
        final ChatCompletionRequestMessage userMessage2 = ChatCompletionRequestUserMessage.builder().role(ChatCompletionRequestMessageType.USER).content(ChatCompletionMessageContent.ofString("你好")).build();
        messages2.add(userMessage2);
        ChatCompletionRequest chatCompletionRequest2 = ChatCompletionRequest.builder()
                .model("doubao-seed-2-1-pro-260915")// Replace with Model ID .
                .messages(messages2)
                .build();
        arkService.createChatCompletion(chatCompletionRequest2).getChoices().forEach(choice -> System.out.println(choice.getMessage().getContent()));
        // shutdown service
        arkService.shutdownExecutor();
    }
}

设置Base Url#

初始化时 Ark、AsyncArk实例时，默认无需配置base_url参数，当需要连接非默认区域的服务端点时使用，示例如下。

1
2
3
4
5
6
7
8
9import os
# Install the Ark SDK with: python -m pip install --upgrade arkruntime .
from arkruntime import Ark

client = Ark(
    api_key=os.environ.get("ARK_API_KEY"),
    # Configure the service endpoint for the target region.
    base_url="https://ark.cn-beijing.volces.com/api/v3",
)

1
2
3
4
5
6
7
8
9import (
    "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"), // Configure the service endpoint for the target region.
)

1
2
3
4
5
6
7
8
9
10
11
12
13
14import com.volcengine.ark.runtime.service.ArkService;

public class CreateArkClientExample {
    public static void main(String[] args) {
        String apiKey = System.getenv("ARK_API_KEY");
        ArkService service = ArkService.builder()
            .apiKey(apiKey)
            .baseUrl("https://ark.cn-beijing.volces.com/api/v3")
            // The base URL for model invocation .
            .build();
    }

    // do your operation...
}