# SDK 常见使用示例

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

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

<span id="243f3c5f"></span>
## 设置超时&重试次数

当您的网络环境不稳定或者响应时间较长的场景，可以设置超时和重试次数，以提高服务可用性。
* 超时设置（`timeout`）：适用于对响应时间较长的场景（如深度思考模型回复问题时间较长），避免请求时间超时导致服务中断，这里推荐30分钟（1800秒）。

    * Python SDK：默认 60秒 连接超时（建立网络连接的最大等待时间），600 秒 socket 超时（连接建立后的数据传输超时）。

    * Java SDK：默认 60秒 连接超时，600 秒 socket 超时。

    * Go SDK：默认 600s 端到端的总超时（从请求发起至响应接收的总超时）。
* 重试次数（`max_retries`）：适用于网络不稳定场景，自动重试因瞬时故障（如网络波动）失败的请求，默认2次，即请求失败默认会再重试2次，您可以按需配置。

**选项：Python**

```Python
import 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",
)
```

**选项：Go**

```Go
import (
    "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"),
)
```

**选项：Java**

```Java
import 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();
    }
}
```

<span id="fa44b913"></span>
## 使用Access Key鉴权

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

> 使用 Access Key 鉴权的实现原理是通过接口 [GetApiKey](/docs/get-api-key-api) 获取临时 API Key 进行鉴权，此接口限流较低，务必使用单例模式进行请求，避免因限流导致鉴权失败，可参考[单例请求](/docs/sdk-common-examples#063cdc02)。

**选项：Python**

```Python
import 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",
)
```

**选项：Go**

```Go
import (
    "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 .
)
```

**选项：Java**

```Java
import 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...
}
```

<span id="c8e7ffaf"></span>
## 设置自定义 header

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

```JSON
{
    "key1": "value1",
    "key2": "value2",
    ...,
    "keyN": "valueN"
}
```

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

<span id="7493fbd5"></span>
### 问题定位

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

**选项：Python**

```Python
import 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)
```

**选项：Go**

```Go
package 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)),
            },
        ),
    }
}
```

**选项：Java**

```Java
package 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();
    }
}
```

<span id="23274b89"></span>
### 加密数据

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

> 更多能力介绍和原理信息请参考[推理会话数据应用层加密方案](/docs/application-layer-encryption-for-inference-session-data)。

* 版本要求：

    * Python SDK：需要保证 `arkruntime` 版本为 `0.5.0` 及以上。参考[升级 Python SDK](/docs/install-and-upgrade-sdk#d6b883b8)升级 SDK。

    * Java SDK：需要保证 `com.volcengine:ark-runtime` 版本为 `0.5.0` 及以上。参考[升级 Java SDK](/docs/install-and-upgrade-sdk#4ab4182d)升级 SDK。
* 能力支持：

    * 仅支持文本生成模型和视觉理解图片理解模型请求。

    * 图片仅支持 Base64 图片加密， URL 图片无法加密。

    * 仅支持官方 Python SDK、Java SDK 的 [Chat API](/docs/chat-api) 。

    * 支持单轮、多轮会话，支持流式、非流式，同步、异步调用。

**选项：Python**

```Python
import 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)
```

**选项：Java**

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

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

代码示例如下：

```Java
package 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();
    }
}
```

<span id="d5f5495b"></span>
### 开启数据上报

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

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

* 版本要求：如果请求上报未生效，需升级 SDK 到最新版本。
* 能力支持：仅支持 [Responses API](/docs/create-model-responses-api)。

**选项：Python**

```Python
import 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)
```

**选项：Go**

```Go
package 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)
}
```

**选项：Java**

```Java
package 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();
    }
}
```

<span id="063cdc02"></span>
## 单例请求

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

**选项：Python**

```Python
import 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)
```

**选项：Go**

```Go
package 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)),
            },
        ),
    }
}
```

**选项：Java**

```Java
package 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();
    }
}
```

<span id="065e9d3e"></span>
## 设置Base Url

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

**选项：Python**

```Python
import 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",
)
```

**选项：Go**

```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"), // Configure the service endpoint for the target region.
)
```

**选项：Java**

```Java
import 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...
}
```