You need to enable JavaScript to run this app.
导航
火山方舟大模型服务平台
  • 文档首页
    • /火山方舟大模型服务平台/API 参考/其他说明/SDK 常见使用示例
SDK 常见使用示例
最近更新时间：2025.04.22 22:12:40首次发布时间：2025.04.22 22:12:40
我的收藏
有用
有用
无用
无用

当您使用官方 SDK 时，当需要并发调用，或者设置最大超时时间、设置header等典型的使用，可以参考本说明。

设置Base Url

初始化时 Ark、AsyncArk实例时，默认无需配置base_url参数，当您需使用其他base_url时，可以手动指定base_url参数。

import os
from volcenginesdkarkruntime import Ark

client = Ark(
    api_key=os.environ.get("ARK_API_KEY"),
    # 以华北 2 (北京) 为例，<ARK_BASE_URL> 处应改为 https://ark.cn-beijing.volces.com/api/v3
    base_url="<ARK_BASE_URL>"
)

设置超时&重试次数

import os
from volcenginesdkarkruntime import Ark

client = Ark(
    api_key=os.environ.get("ARK_API_KEY"),
    # 设置超时时间
    timeout=120,
    # 设置重试次数
    max_retries=2,
)

使用Access Key鉴权

import os
from volcenginesdkarkruntime import Ark
client = Ark(
    ak=os.environ.get("VOLC_ACCESSKEY"),
    sk=os.environ.get("VOLC_SECRETKEY"),
)

设置自定义 header

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

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

可以用于传递额外信息，如配置 ID来串联日志，使能数据加密能力，下面是典型示例。

问题定位

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

import os
from volcenginesdkarkruntime import Ark

client = Ark(
    api_key=os.environ.get("ARK_API_KEY"),
)

completion = client.chat.completions.create(
    # 替换为Model ID，请从文档获取 https://www.volcengine.com/docs/82379/1330310
    model="<MODEL>",
    messages = [
        {"role": "user", "content": "常见的十字花科植物有哪些？"},
    ],
    # 自定义request id
    extra_headers={"X-Client-Request-Id": "My-Request-Id"}
)
print(completion.choices[0].message.content)

加密数据

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

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

  • 版本要求：需要保证 SDK 版本 volcengine-python-sdk 1.0.104及以上。参考升级 Python SDK获得 SDK 的最新版本。
  • 能力支持：仅支持文本生成模型和视觉理解图片理解模型（注：图片仅支持 Base64 图片加密， URL 图片无法加密）请求，仅支持官方 Python SDK 的 对话(Chat) API ，支持单轮、多轮会话，支持流式、非流式，同步、异步接口。
import os
from volcenginesdkarkruntime import Ark

client = Ark(
    api_key=os.environ.get("ARK_API_KEY"),
)
completion = client.chat.completions.create(
    # 替换为Model ID，请从文档获取 https://www.volcengine.com/docs/82379/1330310
    model="<MODEL>",
    messages = [
        {"role": "user", "content": "常见的十字花科植物有哪些？"},
    ],
    #按下述代码设置自定义header，免费开启推理会话应用层加密
    extra_headers={'x-is-encrypted': 'true'}
)
print(completion.choices[0].message.content)

单例请求

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

import os
from volcenginesdkarkruntime import Ark

client = Ark(
    api_key=os.environ.get("ARK_API_KEY"),
)

# 请求1
completion = client.chat.completions.create(
    # 替换为Model ID，请从文档获取 https://www.volcengine.com/docs/82379/1330310
    model="<MODEL>",
    messages=[
        {"role": "user", "content": "今天天气不错"},
    ],
)
print(completion.choices[0].message.content)


# 请求2
completion = client.chat.completions.create(
    # 替换为Model ID，请从文档获取 https://www.volcengine.com/docs/82379/1330310
    model="<MODEL>",
    messages=[
        {"role": "user", "content": "你好"},
    ],
)
print(completion.choices[0].message.content)