You need to enable JavaScript to run this app.
导航
API 调用指南
最近更新时间:2024.07.03 14:48:26首次发布时间:2024.05.14 23:50:07

火山方舟对模型调用进行了新版本升级,支持API Key的鉴权方式,同时开放更多参数。
目前已开放对豆包大模型系列和 Llama/Mistral 等开源模型的 cURL/Python SDK API/JAVA SDK API调用形式。我们将在近期持续更新,并为您提供更多功能和服务。

前提条件

用户前往火山方舟的模型推理页面创建推理接入点,调用API时通过设置model=ep-xxxxxxxxxx-yyyy进行调用。

API调用

cURL

  • API Key是访问推理接入点的鉴权凭证,可参考获取 API key获取。

  • 修改API Key占位符API_KEY,和推理接入点占位符YOUR_ENDPOINT_ID

Chat/Completions

curl https://ark.cn-beijing.volces.com/api/v3/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${API_KEY}" \
  -d '{
    "model": "${YOUR_ENDPOINT_ID}",
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful assistant."
      },
      {
        "role": "user",
        "content": "Hello!"
      }
    ],
    "stream": true
  }'

Embeddings

curl https://ark.cn-beijing.volces.com/api/v3/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "model": "$YOUR_ENDPOINT_ID",
    "input": ["花椰菜又称菜花、花菜,是一种常见的蔬菜。"]
  }'

Python SDK

Chat/Completions

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()

Embeddings

from volcenginesdkarkruntime import Ark

client = Ark(
    base_url="${BASE_URL}",
)

print("----- embeddings request -----")
resp = client.embeddings.create(
    model="${YOUR_ENDPOINT_ID}",
    input=["花椰菜又称菜花、花菜,是一种常见的蔬菜。"]
)
print(resp)

Java SDK

Chat/Completions

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

}

Embeddings

package com.volcengine.ark.runtime;


import com.volcengine.ark.runtime.model.embeddings.EmbeddingRequest;
import com.volcengine.ark.runtime.model.embeddings.EmbeddingResult;
import com.volcengine.ark.runtime.service.ArkService;

import java.util.ArrayList;
import java.util.List;

public class EmbeddingsExample {

    public static void main(String[] args) {

        String apiKey = System.getenv("ARK_API_KEY");
        ArkService service = ArkService.builder().apiKey(apiKey).baseUrl("${BASE_URL}").build();

        System.out.println("\n----- embeddings request -----");
        List<String> inputs = new ArrayList<>();
        inputs.add("花椰菜又称菜花、花菜,是一种常见的蔬菜。");
        EmbeddingRequest chatCompletionRequest = EmbeddingRequest.builder()
                .model("${YOUR_ENDPOINT_ID}")
                .input(inputs)
                .build();

        EmbeddingResult res = service.createEmbeddings(chatCompletionRequest);
        System.out.println(res);

        // shutdown service
        service.shutdownExecutor();
    }
}

Golang SDK

Chat/Completions

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)
       }
    }
}

Embeddings

package main

import (
    "context"
    "encoding/json"
    "fmt"
    "os"

    "github.com/volcengine/volcengine-go-sdk/service/arkruntime"
    "github.com/volcengine/volcengine-go-sdk/service/arkruntime/model"
)

func main() {
    client := arkruntime.NewClientWithApiKey(
       os.Getenv("ARK_API_KEY"),
       arkruntime.WithBaseUrl("${BASE_URL}"),
    )
    ctx := context.Background()

    fmt.Println("----- embeddings request -----")
    req := model.EmbeddingRequestStrings{
       Input: []string{
          "花椰菜又称菜花、花菜,是一种常见的蔬菜。",
       },
       Model: "${YOUR_ENDPOINT_ID}",
    }

    resp, err := client.CreateEmbeddings(ctx, req)
    if err != nil {
       fmt.Printf("embeddings error: %v\n", err)
       return
    }

    s, _ := json.Marshal(resp)
    fmt.Println(string(s))
}

API 规范

注意

model字段仅支持填写推理接入点(形式为ep-xxxxxxxxx-yyyy),不再支持模型名称+版本号的格式。

Chat/Completions

Input

字段子字段类型必填描述

model

-

string

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

messages

-

list

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

rolestring发出该消息的对话参与者的角色,可选 system, userassistant。role 参数的设定有助于模型理解对话的结构和上下文,从而生成更准确、更合适的回应。例如,在多轮对话中,role可以帮助模型追踪不同参与者的发言和意图,即使在复杂的对话场景中也能保持连贯性。

content (role=user)

string/array

消息的内容。user代表用户的输入,当 role 为 user 时,模型会将其视为来自用户的查询或陈述,并据此生成回应。当模型支持多模态时,可以为 list,list 的元素可以为 textimage_url,示例如下。

[
  {
    "type": "text",
    "text": "What'\''s in this image?"
  },
  {
    "type": "image_url",
    "image_url": {
      "url": "data:image/jpeg;base64,${图片base64字符串}"
    }
  }
]
content (role=assistant)string消息的内容。assistant表示机器人的回应。
content (role=system)string消息的内容。system通常表示系统消息或系统提示,它可以用来给模型设定背景信息或指示,告诉模型它在对话中的角色或功能。

frequency_penalty

-

number

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

logit_bias

-

map

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

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

max_tokens

-

integer

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

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

stream_options

-

object

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

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

temperature

-

number

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

top_p

-

number

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

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

由流式模型响应的模型输出增量,示例如下。

{
  "role": "assistant",
  "content": " there",
}
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 数量。

Embeddings

Input

字段类型描述是否必填
modelstring您创建的推理接入点 ID

input

list

输入给模型的需要向量化的内容。

"input": [
    "花椰菜又称菜花、花菜,是一种常见的蔬菜。"
]

Output

字段子字段类型描述
modelstring实际使用的模型名称和版本。

data

lis

每个query的向量化结果

{
    "data": [
        {
            "embedding": [
                0.01131823007017374,
                0.009313009679317474,
                ...
                -0.03317729011178017,
                0.00028884236235171556,
                -0.022333964705467224
            ],
            "object": "embedding"
        },
        {
            "embedding": [
                -0.0019542998634278774,
                ...
                -0.03738011419773102,
                -0.025939496234059334,
                -0.037807632237672806
            ],
            "index": 1,
            "object": "embedding"
        }
    ],
    "object": "list",
    "usage": {
        "prompt_tokens": 6,
        "total_tokens": 6
    }
}
  1. embedding: 向量

  2. index: 向量的序号,与query顺序对应

usageobject该请求的用量统计信息。
prompt_tokensinteger输入 prompt 的 token 数量。

completion_tokens

integer

模型输出的 token 数量。

total_tokensinteger输入和输出的总的 token 数量。