You need to enable JavaScript to run this app.
导航
Doubao API 调用指南
最近更新时间:2024.06.19 14:47:05首次发布时间:2024.05.14 23:50:35

豆包 (Doubao) 是字节内部团队研发的大规模预训练语言模型系列,本文详细介绍了 Doubao 语言模型的 SDK 及 API 使用方法。

适用范围

本文档适用以下模型:

模型名称简介
Doubao-lite-4kDoubao-lite拥有极致的响应速度,更好的性价比,为客户不同场景提供更灵活的选择。支持4k上下文窗口的推理和精调。
Doubao-lite-32kDoubao-lite拥有极致的响应速度,更好的性价比,为客户不同场景提供更灵活的选择。支持32k上下文窗口的推理和精调。
Doubao-lite-128kDoubao-lite 拥有极致的响应速度,更好的性价比,为客户不同场景提供更灵活的选择。支持128k上下文窗口的推理和精调。
Doubao-pro-4k效果最好的主力模型,适合处理复杂任务,在参考问答、总结摘要、创作、文本分类、角色扮演等场景都有很好的效果。支持4k上下文窗口的推理和精调。
Doubao-pro-32k效果最好的主力模型,适合处理复杂任务,在参考问答、总结摘要、创作、文本分类、角色扮演等场景都有很好的效果。支持32k上下文窗口的推理和精调。
Doubao-pro-128k效果最好的主力模型,适合处理复杂任务,在参考问答、总结摘要、创作、文本分类、角色扮演等场景都有很好的效果。支持128k上下文窗口的推理和精调。

API SDK

提供统一 SDK 的接入形式(需要使用API key鉴权,获取方式请参考 获取 API key),SDK中可以通过设置环境变量ARK_API_KEY或者Ark()初始化时引入API KEY。

Python

注意

目前仅支持 python>=3.7

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

# Authentication
# 1.If you authorize your endpoint using an API key, you can set your api key to environment variable "ARK_API_KEY"
# or specify api key by Ark(api_key="${YOUR_API_KEY}").
# Note: If you use an API key, this API key will not be refreshed.
# To prevent the API from expiring and failing after some time, choose an API key with no expiration date.

# 2.If you authorize your endpoint with Volcengine Identity and Access Management(IAM), set your api key to environment variable "VOLC_ACCESSKEY", "VOLC_SECRETKEY"
# or specify ak&sk by Ark(ak="${YOUR_AK}", sk="${YOUR_SK}").
# To get your ak&sk, please refer to this document([https://www.volcengine.com/docs/6291/65568](https://www.volcengine.com/docs/6291/65568))
# For more information,please check this document([https://www.volcengine.com/docs/82379/1263279](https://www.volcengine.com/docs/82379/1263279))
client = Ark()

# Non-streaming:
print("----- standard request -----")
completion = client.chat.completions.create(
    model="${YOUR_ENDPOINT_ID}",
    messages = [
        {"role": "system", "content": "你是豆包,是由字节跳动开发的 AI 人工智能助手"},
        {"role": "user", "content": "常见的十字花科植物有哪些?"},
    ],
)
print(completion.choices[0].message.content)

# Streaming:
print("----- streaming request -----")
stream = client.chat.completions.create(
    model="${YOUR_ENDPOINT_ID}",
    messages = [
        {"role": "system", "content": "你是豆包,是由字节跳动开发的 AI 人工智能助手"},
        {"role": "user", "content": "常见的十字花科植物有哪些?"},
    ],
    stream=True
)
for chunk in stream:
    if not chunk.choices:
        continue
    print(chunk.choices[0].delta.content, end="")
print()

Java

<dependency>
  <groupId>com.volcengine</groupId>
  <artifactId>volcengine-java-sdk-ark-runtime</artifactId>
  <version>LATEST</version>
</dependency>
package com.volcengine.ark.runtime;


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 {

    /**
     * Authentication
     * 1.If you authorize your endpoint using an API key, you can set your api key to environment variable "ARK_API_KEY"
     * String apiKey = System.getenv("ARK_API_KEY");
     * ArkService service = new ArkService(apiKey);
     * Note: If you use an API key, this API key will not be refreshed.
     * To prevent the API from expiring and failing after some time, choose an API key with no expiration date.
     *
     * 2.If you authorize your endpoint with Volcengine Identity and Access Management(IAM), set your api key to environment variable "VOLC_ACCESSKEY", "VOLC_SECRETKEY"
     * String ak = System.getenv("VOLC_ACCESSKEY");
     * String sk = System.getenv("VOLC_SECRETKEY");
     * ArkService service = new ArkService(ak, sk);
     * To get your ak&sk, please refer to this document(https://www.volcengine.com/docs/6291/65568)
     * For more information,please check this document(https://www.volcengine.com/docs/82379/1263279)
     */
    public static void main(String[] args) {

        String apiKey = System.getenv("ARK_API_KEY");
        ArkService service = new ArkService(apiKey);

        System.out.println("\n----- standard request -----");
        final List<ChatMessage> messages = new ArrayList<>();
        final ChatMessage systemMessage = ChatMessage.builder().role(ChatMessageRole.SYSTEM).content("你是豆包,是由字节跳动开发的 AI 人工智能助手").build();
        final ChatMessage userMessage = ChatMessage.builder().role(ChatMessageRole.USER).content("常见的十字花科植物有哪些?").build();
        messages.add(systemMessage);
        messages.add(userMessage);

        ChatCompletionRequest chatCompletionRequest = ChatCompletionRequest.builder()
                .model("${YOUR_ENDPOINT_ID}")
                .messages(messages)
                .build();

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

        System.out.println("\n----- streaming request -----");
        final List<ChatMessage> streamMessages = new ArrayList<>();
        final ChatMessage streamSystemMessage = ChatMessage.builder().role(ChatMessageRole.SYSTEM).content("你是豆包,是由字节跳动开发的 AI 人工智能助手").build();
        final ChatMessage streamUserMessage = ChatMessage.builder().role(ChatMessageRole.USER).content("常见的十字花科植物有哪些?").build();
        streamMessages.add(streamSystemMessage);
        streamMessages.add(streamUserMessage);

        ChatCompletionRequest streamChatCompletionRequest = ChatCompletionRequest.builder()
                .model("${YOUR_ENDPOINT_ID}")
                .messages(streamMessages)
                .build();

        service.streamChatCompletion(streamChatCompletionRequest)
                .doOnError(Throwable::printStackTrace)
                .blockingForEach(
                        choice -> {
                            if (choice.getChoices().size() > 0) {
                                System.out.print(choice.getChoices().get(0).getMessage().getContent());
                            }
                        }
                );

        // shutdown service
        service.shutdownExecutor();
    }

}

Golang

package main

import (
    "context"
    "fmt"
    "io"
    "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"
)

/**
 * Authentication
 * 1.If you authorize your endpoint using an API key, you can set your api key to environment variable "ARK_API_KEY"
 * client := arkruntime.NewClientWithApiKey(os.Getenv("ARK_API_KEY"))
 * Note: If you use an API key, this API key will not be refreshed.
 * To prevent the API from expiring and failing after some time, choose an API key with no expiration date.
 *
 * 2.If you authorize your endpoint with Volcengine Identity and Access Management(IAM), set your api key to environment variable "VOLC_ACCESSKEY", "VOLC_SECRETKEY"
 * client := arkruntime.NewClientWithAkSk(os.Getenv("VOLC_ACCESSKEY"), os.Getenv("VOLC_SECRETKEY"))
 * To get your ak&sk, please refer to this document(https://www.volcengine.com/docs/6291/65568)
 * For more information,please check this document(https://www.volcengine.com/docs/82379/1263279)
 */

func main() {
    client := arkruntime.NewClientWithApiKey(os.Getenv("ARK_API_KEY"))
    ctx := context.Background()

    fmt.Println("----- standard request -----")
    req := model.ChatCompletionRequest{
       Model: "${YOUR_ENDPOINT_ID}",
       Messages: []*model.ChatCompletionMessage{
          {
             Role: model.ChatMessageRoleSystem,
             Content: &model.ChatCompletionMessageContent{
                StringValue: volcengine.String("你是豆包,是由字节跳动开发的 AI 人工智能助手"),
             },
          },
          {
             Role: model.ChatMessageRoleUser,
             Content: &model.ChatCompletionMessageContent{
                StringValue: volcengine.String("常见的十字花科植物有哪些?"),
             },
          },
       },
    }

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

    fmt.Println("----- streaming request -----")
    req = model.ChatCompletionRequest{
       Model: "${YOUR_ENDPOINT_ID}",
       Messages: []*model.ChatCompletionMessage{
          {
             Role: model.ChatMessageRoleSystem,
             Content: &model.ChatCompletionMessageContent{
                StringValue: volcengine.String("你是豆包,是由字节跳动开发的 AI 人工智能助手"),
             },
          },
          {
             Role: model.ChatMessageRoleUser,
             Content: &model.ChatCompletionMessageContent{
                StringValue: volcengine.String("常见的十字花科植物有哪些?"),
             },
          },
       },
    }
    stream, err := client.CreateChatCompletionStream(ctx, req)
    if err != nil {
       fmt.Printf("stream chat error: %v\n", err)
       return
    }
    defer stream.Close()

    for {
       recv, err := stream.Recv()
       if err == io.EOF {
          return
       }
       if err != nil {
          fmt.Printf("Stream chat error: %v\n", err)
          return
       }

       if len(recv.Choices) > 0 {
          fmt.Print(recv.Choices[0].Delta.Content)
       }
    }
}

API Specification

Chat

Input

字段子字段类型必填描述默认值

model

-

string

以 endpoint_id 索引对应的模型接入点。

-

messages

-

list

本次对话的消息列表,包含用户输入的最后一条消息。

-

rolestring发出该消息的对话参与者的角色,可选 system, userassistant。role 参数的设定有助于模型理解对话的结构和上下文,从而生成更准确、更合适的回应。例如,在多轮对话中,role可以帮助模型追踪不同参与者的发言和意图,即使在复杂的对话场景中也能保持连贯性。-
content (role=user)string消息的内容。user代表用户的输入,当 role 为 user 时,模型会将其视为来自用户的查询或陈述,并据此生成回应。-
content (role=assistant)string消息的内容。assistant表示机器人的回应。-
content (role=system)string消息的内容。system通常表示系统消息或系统提示,它可以用来给模型设定背景信息或指示,告诉模型它在对话中的角色或功能。-

frequency_penalty

-

number

-2.0 到 2.0 之间的数字。如果为正,会根据新 token 在文本中的出现频率对其进行惩罚,从而降低模型重复相同内容的可能性。

1

logit_bias

-

map

修改指定 token 在模型输出内容中出现的概率。 接受一个 map,该对象将 token(token id 使用 tokenization 接口获取)映射到从-100到100的关联偏差值。每个模型的效果有所不同,但-1和1之间的值会减少或增加选择的可能性;-100或100应该导致禁止或排他选择相关的 token。

null

logprobs-boolean是否返回输出 tokens 的 logprobs。如果为 true,则返回 message (content) 中每个输出 token 的 logprobs。false
top_logprobs-integer0 到 20 之间的整数,指定每个 token 位置最有可能返回的token数量,每个token 都有关联的对数概率。 如果使用此参数,则 logprobs 必须设置为 truenull

max_tokens

-

integer

模型最大输出 token 数。
输入 token 和输出 token 的总长度还受模型的上下文长度限制。

null

stop-string/array用于指定模型在生成响应时应停止的词语。当模型生成的响应中包含这些词汇时,生成过程将停止。null
stream-boolean是否流式返回。如果为 true,则按 SSE 协议返回数据。false

stream_options

-

object

stream=true 时可以设置这个参数。

null

include_usagebool如果设置,则在data: [DONE]消息之前会返回一个额外的块。此块上的 usage 字段显示了整个请求的 token 用量,其 choices 字段是一个空数组。所有其他块也将包含usage字段,但值为 null。false

temperature

-

number

采样温度在0到2之间。较高的值(如0.8)将使输出更加随机,而较低的值(如0.2)将使输出更加集中和确定。
通常建议修改 temperature 或 top_p,但不建议两者都修改。

1

top_p

-

number

temperature 抽样的另一种选择,称为核抽样,其中模型考虑具有 top_p 概率质量的 token。所以 0.1 意味着只考虑包含前 10% 概率质量的标记。
一般建议修改 top_p 或 temperature,但不建议两者都修改

1

Output

非流式调用
字段子字段类型描述
id-string一次 chat completion 接口调用的唯一标识。
choices-array本次 chat 结果列表。长度固定为 1。
indexinteger该元素在 choices 列表的索引。

message

object

模型输出的消息内容,示例如下:

{
  "role": "assistant",
  "content": "\n\nHello there, how may I assist you today?",
}
finish_reasonstring模型生成结束原因,stop表示正常生成结束,length 表示已经到了生成的最大 token 数量,content_filter 表示命中审核提前终止。

logprobs

object

该输出结果的概率信息,其只有一个 content 字段,类型为 array,表示message列表中每个元素content token的概率信息,content 元素子字段说明如下:

  1. token [string]: 对应 token;

  2. logprob [number]:token的概率;

  3. bytes [array]:表示 token 的 UTF-8 字节表示的整数列表。在字符由多个 token 表示,并且它们的字节表示必须组合以生成正确的文本表示的情况下(表情符号或特殊字符)非常有用。如果 token 没有 byte 表示,则可以为空。

  4. top_logprobs [array]:最可能的token列表及其在此 token位置的对数概率:

    1. token [string]: 对应token;

    2. logprob [number]:token的概率;

    3. bytes [array]:表示 token 的 UTF-8 字节表示的整数列表。在字符由多个 token 表示,并且它们的字节表示必须组合以生成正确的文本表示的情况下(表情符号或特殊字符)非常有用。如果 token 没有 byte 表示,则可以为空。

created-integer本次对话生成时间戳(秒)。
model-string实际使用的模型名称和版本。
object-string固定为 chat.completion。

usage

-

object

本次请求的 tokens 用量。

prompt_tokensinteger本次请求中输入的 token 数量。
completion_tokensinteger模型生成的 token 数量。
total_tokensinteger总的 token 数量。
流式调用
字段子字段类型描述
id-string一次 chat completion 接口调用的唯一标识,一次流式调用所有的 chunk 有相同的 id。

choices

-

array

结果列表。长度固定为 1。如果设置了stream_options: {"include_usage": true},则最后一个 chunk 的 choices 也为空列表。

indexinteger该元素在 choices 列表的索引。

delta

object

由流式模型响应的模型输出增量。

finish_reasonstring模型生成结束原因,stop表示正常生成结束,length 表示已经到了生成的最大 token 数量,content_filter 表示命中审核提前终止。

logprobs

object

该输出结果的概率信息,其只有一个 content 字段,类型为 array,表示message列表中每个元素content token的概率信息,content 元素子字段说明如下:

  1. token [string]: 对应 token;

  2. logprob [number]:token的概率;

  3. bytes [array]:表示 token 的 UTF-8 字节表示的整数列表。在字符由多个 token 表示,并且它们的字节表示必须组合以生成正确的文本表示的情况下(表情符号或特殊字符)非常有用。如果 token 没有 byte 表示,则可以为空。

  4. top_logprobs [array]:最可能的token列表及其在此 token位置的对数概率:

    1. token [string]: 对应token;

    2. logprob [number]:token的概率;

    3. bytes [array]:表示 token 的 UTF-8 字节表示的整数列表。在字符由多个 token 表示,并且它们的字节表示必须组合以生成正确的文本表示的情况下(表情符号或特殊字符)非常有用。如果 token 没有 byte 表示,则可以为空。

created-integer本次对话生成时间戳(秒)。
model-string实际使用的模型名称和版本。
object-string固定为 chat.completion.chunk。

usage

-

object

本次请求的 tokens 用量。
一个可选字段,仅当在请求中设置stream_options: {"include_usage": true}时才会出现。如果设置了它,除了最后一个 chunk 包含整个请求的 token 使用量外,其它 chunk 的 usage 都是 null。

prompt_tokensinteger本次请求中输入的 token 数量。
completion_tokensinteger模型生成的 token 数量。
total_tokensinteger总的 token 数量。

在 stream 模式下,基于 SSE (Server-Sent Events) 协议返回生成内容,每次返回结果为生成的部分内容片段:

  • 内容片段按照生成的先后顺序返回,完整的结果需要调用者拼接才能得到;

  • 如果流式请求开始时就出现错误(如参数错误),HTTP返回非200,方法调用也会直接返回错误;

  • 如果流式过程中出现错误,HTTP 依然会返回 200, 错误信息会在一个片段返回。