豆包 (Doubao) / 云雀（Skylark）是字节内部团队研发的大规模预训练语言模型系列，本文详细介绍了 Doubao /Skylark 语言模型的 SDK 及 API 使用方法。
字节自研大模型于2024年5月正式命名为豆包大模型，不再使用Skylark名称，您可以逐步迁移使用豆包系列模型。

适用范围

本文档适用以下模型：

API Host

Host：maas-api.ml-platform-cn-beijing.volces.com
Region: cn-beijing

API SDK

提供统一 SDK 的接入形式（需要用 ak/sk 进行旁路鉴权，火山鉴权逻辑可以参考）

• Golang SDK: https://github.com/volcengine/volc-sdk-golang

• Python SDK: https://github.com/volcengine/volc-sdk-python

• Java SDK: https://github.com/volcengine/volc-sdk-java

Golang

// Usage:
//
// 1. go get -u github.com/volcengine/volc-sdk-golang
// 2. VOLC_ACCESSKEY=XXXXX VOLC_SECRETKEY=YYYYY go run main.go
package main

import (
        "encoding/json"
        "errors"
        "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("maas-api.ml-platform-cn-beijing.volces.com", "cn-beijing")

        // fetch ak&sk from environmental variables
        r.SetAccessKey(os.Getenv("VOLC_ACCESSKEY"))
        r.SetSecretKey(os.Getenv("VOLC_SECRETKEY"))

        req := &api.ChatReq{
                Messages: []*api.Message{
                        {
                                Role:    api.ChatRoleUser,
                                Content: "天为什么这么蓝？",
                        },
                        {
                                Role:    api.ChatRoleAssistant,
                                Content: "因为有你",
                        },
                        {
                                Role:    api.ChatRoleUser,
                                Content: "花儿为什么这么香？",
                        },
                },           
        }

        endpointId := "{YOUR_ENDPOINT_ID}"
        TestNormalChat(r, endpointId, req)
        TestStreamChat(r, endpointId, req)
}

func TestNormalChat(r *client.MaaS, endpointId string, req *api.ChatReq) {
        got, status, err := r.Chat(endpointId, req)
        if err != nil {
                errVal := &api.Error{}
                if errors.As(err, &errVal) { // the returned error always type of *api.Error
                        fmt.Printf("meet maas error=%v, status=%d\n", errVal, status)
                }
                return
        }
        fmt.Println("chat answer", mustMarshalJson(got))
}

func TestStreamChat(r *client.MaaS, endpointId string, req *api.ChatReq) {
        ch, err := r.StreamChat(endpointId, req)
        if err != nil {
                errVal := &api.Error{}
                if errors.As(err, &errVal) { // the returned error always type of *api.Error
                        fmt.Println("meet maas error", errVal.Error())
                }
                return
        }

        for resp := range ch {
                if resp.Error != nil {
                        // it is possible that error occurs during response processing
                        fmt.Println(mustMarshalJson(resp.Error))
                        return
                }
                fmt.Println(mustMarshalJson(resp))
                // last response may contain `usage`
                if resp.Usage != nil {
                        // last message, will return full response including usage, role, finish_reason, etc.
                        fmt.Println(mustMarshalJson(resp.Usage))
                }
        }
}

func mustMarshalJson(v interface{}) string {
        s, _ := json.Marshal(v)
        return string(s)
}

Python

'''
Usage:

1. python3 -m pip install --user volcengine
2. VOLC_ACCESSKEY=XXXXX VOLC_SECRETKEY=YYYYY python main.py
'''
import os
from volcengine.maas.v2 import MaasService
from volcengine.maas import MaasException, ChatRole

def test_chat(maas, endpoint_id, req):
    try:
        resp = maas.chat(endpoint_id, req)
        print(resp)
    except MaasException as e:
        print(e)

def test_stream_chat(maas, endpoint_id, req):
    try:
        resps = maas.stream_chat(endpoint_id, req)
        for resp in resps:
            print(resp)
    except MaasException as e:
        print(e)

if __name__ == '__main__':
    maas = MaasService('maas-api.ml-platform-cn-beijing.volces.com', 'cn-beijing')

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

    # document: "https://www.volcengine.com/docs/82379/1099475"
    # chat
    req = {
        
        "messages": [
            {
                "role": ChatRole.USER,
                "content": "天为什么这么蓝"
            }, {
                "role": ChatRole.ASSISTANT,
                "content": "因为有你"
            }, {
                "role": ChatRole.USER,
                "content": "花儿为什么这么香？"
            },
        ]
    }

    endpoint_id = "{YOUR_ENDPOINT_ID}"
    test_chat(maas, endpoint_id, req)
    test_stream_chat(maas, endpoint_id, req)
#

Java

/*

# pom.xml

<dependency>
        <groupId>com.volcengine</groupId>
        <artifactId>volc-sdk-java</artifactId>
        <version>LATEST</version>

</dependency>

*/

package com.volcengine.example.maas.v2;

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("maas-api.ml-platform-cn-beijing.volces.com", "cn-beijing");

        // fetch ak&sk from environmental variables
        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("天为什么这么蓝？"),
                        new Message().withRole(Message.ChatRole.ASSISTANT).withContent("因为有你"),
                        new Message().withRole(Message.ChatRole.USER).withContent("什么是中国")
                )));

        String endpointId = "${YOUR_ENDPOINT_ID}";
        testChat(maasService, endpointId, req);
        testStreamChat(maasService, endpointId, req);
    }

    private static void testChat(MaasService maasService, String endpointId, ChatReq req) {
        try {
            ChatResp resp = maasService.chat(endpointId, req);
            System.out.println(resp.getChoices().get(0).getMessage().getContent());
            System.out.println(resp.getUsage());
        } catch (MaasException e) {
            System.out.println("req_id: " + e.getRequestId());
            System.out.println("code: " + e.getCode());
            System.out.println("code_n: " + e.getCodeN());
            System.out.println("message: " + e.getMsg());
            e.printStackTrace();
        }
    }

    private static void testStreamChat(MaasService maasService, String endpointId, ChatReq req) {
        Stream<ChatResp> resps = null;
        try {
            resps = maasService.streamChat(endpointId, req);
        } catch (MaasException e) {
            e.printStackTrace();
        }


        assert resps != null;

        // it is possible that error occurs during response processing
        try {
            resps.forEach(resp -> {
                System.out.println(resp.getChoices().get(0).getMessage().getContent());

                // last message, will return full response including usage, role, finish_reason, etc.
                if (resp.getUsage() != null && resp.getUsage().getTotalTokens() > 0) {
                    System.out.println(resp.getUsage());
                }
            });
        } catch (RuntimeException e) {
            Throwable cause = e.getCause();
            if (cause instanceof MaasException) {
                System.out.println("req_id: " + ((MaasException) cause).getRequestId());
                System.out.println("code: " + ((MaasException) cause).getCode());
                System.out.println("code_n: " + ((MaasException) cause).getCodeN());
                System.out.println("message: " + ((MaasException) cause).getMsg());
            }
            System.out.println("caught: " + e);
        }
    }
}

API Specification

Chat

主要参考 OpenAI 和 HuggingFace Parameters 记录可选控制参数，具体哪些参数可用依赖模型服务（模型详情页会描述哪些参数可用）

Input

[
  {
    "role": "user",
    "content": "how to learn python?"
  }
]

Output

{
    "message": {
        "role": "assistant",
        "content": "Learning Python can be a fun and rewarding experience, and there are many resources available to help you get started. Here are some steps you can take to learn Python:\n\n1. Start by installing Python on your computer. You can download the latest version of Python from the official website at <https://www.python.org/downloads/>.\n2. Once you have Python installed, open a terminal or command prompt and enter `python` to start learning the language. This will open a Python interpreter, where you can start writing and running code.\n3. Learn the basics of Python by reading through the official Python documentation at <https://docs.python.org/3/>. This will cover topics such as variables, data types, control structures, functions, and modules.\n4. There are many online resources available to help you learn Python, including tutorials, courses, and forums. Some popular resources include Codecademy, edX, and Coursera.\n5. Practice writing and running code. The more you practice, the better you will become at Python. You can find many exercises and projects online to help you practice.\n6. Join a Python community. Python has a large and active community of developers, and joining one of these communities can be a great way to learn from others and get support. You can find communities on social media, online forums, and through online communities such as Stack Overflow.\n\nOverall, learning Python requires practice and dedication, but with the right resources and approach, it can be a fun and rewarding experience."
    },
    "finish_reason": "stop",
}

{
    "prompt_tokens": 18,
    "completion_tokens": 317,
    "total_tokens": 335
}

{
    "code": "UnauthorizedCode",
    "code_n": 123456,
    "message": "You are not authorized"
}

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

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

• 如果流式请求开始时就出现错误（如参数错误），HTTP返回非200，方法调用也会直接返回错误；

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