You need to enable JavaScript to run this app.
导航
API调用指南
最近更新时间:2024.05.15 11:07:00首次发布时间:2024.03.14 18:57:23

火山方舟对模型调用 API 进行了新版本升级。SDK V3 版本在 AK/SK 鉴权模式的基础上新增了 API Key 鉴权模式,只需根据调用说明获取 ARK_API_KEY 即可轻松调用。同时,我们还开放了更多参数,让您能够更好地对模型问答内容进行调整。
新版本功能正在逐步上线中,目前已开放对豆包大模型系列,以及 Llama/Mistral 等开源模型的 python 调用。如果您需要调用其他模型(如Moonshot、GLM3等)或其他语言(如Java、Golang),您仍然可以使用 SDK V2。我们将在近期持续更新,并为您提供更多功能和服务。

前提条件

  1. 用户可以通过火山引擎 SDK 来使用我们提供的服务,目前有 Python, Golang 和 Java 版本。

  2. 用户前往火山方舟的模型接入页面建立Endpoint,Endpoint为请求接入的入口,绑定接入方身份,限流,计费以及模型编排等信息。

  3. 调用前需要获取 AccessKey ID 和 Secret Access Key(AK/SK),用于 API 请求认证和鉴权,如何获取可参考密钥管理-帮助文档

  4. 如果用户需要自己实现 client 调用代码,需要用 AK/SK 进行旁路鉴权,火山鉴权逻辑可以参考:签名方法

构造签名时使用的服务元信息如下:

region: cn-beijing
service: ml_maas
schema: https
endpoint: maas-api.ml-platform-cn-beijing.volces.com
path: /api/v2/endpoint/${endpoint_id}/chat
content-type: application/json
AccessKey ID, Secret Access Key 用你火山帐号的 AK 和 SK
action 和 version 留空

API Host

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

API SDK

提供统一 SDK 的接入形式(需要用 AK/SK 进行旁路鉴权,火山鉴权逻辑可以参考

Model Inference

Parameters 记录可选控制参数,具体哪些参数可用依赖具体模型的配置。

注意

用户前往火山方舟的模型推理页面建立Endpoint,Endpoint为请求接入的入口,绑定接入方身份,限流,计费以及模型编排等信息,不再支持通过模型名+版本访问。

Chat

Input

字段类型描述是否必填

messages

list

[
  {
    "role": "user",
    "content": "你好"
  }
]
{
    "role": "user",
    "content": [
        {
          "type": "image_url", //object类型,目前仅支持image_url
          "image_url": {
            "url": "",
            "image_bytes": "",
            "detail": "",
          }
        }
    ]
  }
  1. role:消息角色,目前支持system/user/assistant

  2. content:消息内容

消息是列表形式,依次记录了消息聊天上下文(第一个是最早的对话,最后一个是最新的对话)。以 Q 表示 user 消息, A 表示 assistant,不考虑 system 消息,输入形式如:Q1, A1, Q2, A2, Q3(输入应该是奇数个,为若干个 Q/A 对后面一个单独的 Q),system 消息可以按需插入其中。

目前content支持传入2种类型: string与list(object)

a. "type": "image_url"用于传入图片信息

i. image_url.url : 图片url

ii. image_url.image_bytes : 图片base64数据

iii. image_url.detail : 图片分辨率,low/high/auto

required

streamboolean是否流式返回。默认false,如果为 true,则按 SSE (Server-Sent Events) 协议返回数据
toolslist一个模型可能调用的工具列表。目前,只支持函数作为工具。使用此功能提供模型可能为其生成JSON输入的函数列表。
tools.typestring工具的类型,目前只支持 function
tools.function.namestring描述函数的名称,以便模型知道要调用哪个函数。如:SearchPlugin

tools.function.description

string

模型可以根据函数的描述来判断是否需要调用该函数,并确定调用函数的方式和时机。如:当回答问题需要借助搜索引擎时,使用这个插件,给定query返回相关搜索结果

tools.function.parameters

object

以 json schema 形式描述函数的参数,包括参数的名称和类型。这样模型就知道如何为函数提供正确的参数。
如:

{
    "properties": {
        "query": {
            "description": "表示搜索query,如果你希望借助搜索引擎回答下面的问题,你会如何搜索",
            "type": "string"
        }
    },
    "required": [
        "query"
    ],
    "type": "object"
}
tools.function.exampleslist函数的调用参数示例。如:"{\"query\":\"今天天气\"}"

parameters.max_new_tokens

integer

最多新生成 token 数(不包含 prompt 的 token 数目)

依赖模型默认配置

parameters.max_prompt_tokensinteger最大输入模型的 token 数,如果输入文本的 token 数超过该长度,将取最后 `max_prompt_tokens` 个 token 输入模型依赖模型默认配置
parameters.temperaturenumber采样温度,(0, 1.0]依赖模型默认配置
parameters.top_pnumber核采样,[0, 1.0]依赖模型默认配置
parameters.top_kintegertop-k-filtering 算法保留多少个 最高概率的词 作为候选,正整数。依赖模型默认配置
parameters.do_samplebool是否采样依赖模型默认配置
parameters.presence_penaltynumber存在惩罚,如果为正,值越大,模型谈论到新话题的概率越大,取值范围为 [-2.0, 2.0]依赖模型默认配置
parameters.frequency_penaltynumber频率惩罚,如果为正,值越大,模型逐字重复同一行的概率越小,取值范围为 [-2.0, 2.0]依赖模型默认配置
parameters.repetition_penaltynumber重复惩罚,取值范围为 [1.0, 2.0]依赖模型默认配置
parameters.logprobsinteger返回概率最高的候选集,取值范围[0, 10]依赖模型默认配置
parameters.logit_biasmap<string,number>接受一个map,该对象将token(token id使用tokenization接口获取)映射到从-100到100的关联偏差值。每个模型的效果有所不同,但-1和1之间的值会减少或增加选择的可能性;-100或100应该导致禁止或排他选择相关的token。依赖模型默认配置

Output

字段类型描述
choiceslist(choice)

choice

object

{
    "message": {
        "role": "assistant",
        "content": "Learning Python can be a fun and rewarding experience, and there are many resources available to help you get started."
    },
    "finish_reason": "stop",
}
  1. message:同上说明

  2. finish_reason:结束原因

    1. stop表示正常生成结束

    2. length表示已经到了指定的最大 token 数量(max_new_tokens

usage

object

{
    "prompt_tokens": 18,
    "completion_tokens": 317,
    "total_tokens": 335
}
  1. prompt_tokens:提示的 prompt token 数量

  2. completion_tokens:生成的 token 数量

  3. total_tokens:总的 token 数量

在 stream 模式下,只有最后一个输出 frame 才会记录 usage 内容

error(optioanl)

object

{
    "code_n": 1709802,
    "code": "RequestTimeout",
    "message": "请求超时"
}
  1. code_n:错误的编号

  2. code:具体错误的描述

  3. message:错误的信息

如果没有错误,error 这个条目为空
如果有错误,其余条目都为空,只有 error 条目

Code Sample

POST /api/v2/endpoint/${endpoint_id}/chat

说明

调用前请修改:

  1. 设置环境变量(或在代码中修改): VOLC_ACCESSKEYVOLC_SECRETKEY

  2. 修改调用模型名占位符{YOUR_ENDPOINT_ID}

  3. 本文档仅提供Curl调用示例,其他语言的代码示例可参见:

Curl (Non-Stream)
// Request
curl --request POST \
  --url http://maas-api.ml-platform-cn-beijing.volces.com/api/v2/endpoint/${YOUR_ENDPOINT_ID}/chat \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
        "stream": false,
        "parameters": {
                "max_new_tokens": 1024,
                "temperature": 0.9
        },
        "messages": [
                {
                        "role": "user",
                        "content": "你好"
                },
                {
                        "role": "assistant",
                        "content": "你好,有什么可以帮助您?"
                },
                {
                        "role": "user",
                        "content": "你可以做些什么?"
                }
        ]
}'

// Response
{
        "choices": [
            {
                    "message": {
                            "role": "assistant",
                            "content": "我可以回答各种问题,例如历史、科学、技术、文化、娱乐等方面的问题。我还可以生成文本,例如摘要、文章、故事等。您需要我做什么呢?"
                    },
                    "finish_reason": "stop"
            }
        ],
        "usage": {
                "prompt_tokens": 20,
                "completion_tokens": 43,
                "total_tokens": 63
        }
}
Curl (Stream)

在 stream 模式下,基于 SSE (Server-Sent Events) 协议返回生成内容:

  • 生成的内容形如data:{JSON_OF_OUTPUT_STRUCT}

data:{"choices":[{"message":{"content":"Hello!"}}]}

  • 最后一个有效生成内容,可以夹带usage信息,用来进行 token 统计。

  • data:[DONE]作为成功响应后的结束标识。

如果有error的话,不返回此标识。

// Request
curl --request POST \
  --url http://maas-api.ml-platform-cn-beijing.volces.com/api/v2/endpoint/${YOUR_ENDPOINT_ID}/chat \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
        "stream": true,
        "parameters": {
                "max_new_tokens": 1024,
                "temperature": 0.9
        },
        "messages": [
                {
                        "role": "user",
                        "content": "你好"
                },
                {
                        "role": "assistant",
                        "content": "你好,有什么可以帮助您?"
                },
                {
                        "role": "user",
                        "content": "你可以做些什么?"
                }
        ]
}'

// Response
data:{"choices":[{"message":{"content":"我"}}]}

data:{"choices":[{"message":{"content":"可以"}}]}

data:{"choices":[{"message":{"content":"帮"}}]}

data:{"choices":[{"message":{"content":"您"}}]}

data:{"choices":[{"message":{"content":"回答"}}]}

data:{"choices":[{"message":{"content":"问题"}}]}

data:{"choices":[{"message":{"role":"assistant"},"finish_reason":"stop"}],"usage":{"prompt_tokens":20,"completion_tokens":13,"total_tokens":33}}

data:[DONE]

Tokenization

Input

字段类型描述是否必填

text

string

需要编码的文本。

"text": "天空为什么这么蓝?"

required

Output

字段类型描述
req_idstring请求 id

total_tokens

integer

编码后token的数量

"total_tokens": 5

tokens

list

token列表,如果一个字由多个token_id组成,那么以token:{token_id}的字符串形式返回

"tokens": [
   "天空",
   "为什么",
   "这么",
   "蓝",
   "?"
]
token_idslisttoken id列表,与offset_mapping一一对应
offset_mappinglist<tuple<number,number>>映射每个token在切片中的位置

Code Sample

POST /api/v2/endpoint/${endpoint_id}/tokenization

说明

调用前请修改:

  1. 设置环境变量(或在代码中修改): VOLC_ACCESSKEYVOLC_SECRETKEY

  2. 修改调用模型名占位符{YOUR_ENDPOINT_ID}

  3. 本文档仅提供Curl调用示例,其他语言的代码示例可参见:

Curl
// Request
curl --request POST \
  --url http://maas-api.ml-platform-cn-beijing.volces.com/api/v2/endpoint/${YOUR_ENDPOINT_ID}/tokenization \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "text": "天空为什么这么蓝?"
}'

// Response
{
    "total_tokens": 5,
    "tokens": [
        "天空",
        "为什么",
        "这么",
        "蓝",
        "?"
    ],
    "token_ids": [
        14539,
        4752,
        5189,
        5399,
        1077
    ],
    "offset_mapping": [
        [
            0,
            2
        ],
        [
            2,
            5
        ],
        [
            5,
            7
        ],
        [
            7,
            8
        ],
        [
            8,
            9
        ]
    ]
}

Classification

Input

字段类型描述

query

string

输入给模型的查询请求内容。

"query": "中国的第一个经济特区是?"

labels

list

类别列表,最多100个。强烈建议使用单token_id的标签,否则会大幅度降低性能

"labels": [
    "北京",
    "珠海",
    "深圳",
    "厦门",
    "上海"
]

Output

字段类型描述
req_idstring请求id

label

string

选中的label

label_logprobos

object

每个label的token概率,由key-value对构成。强烈建议使用单token_id的标签,否则会大幅度降低性能

"label_logprobos": {
       "上海": {
         "tokens": [ "上海" ],
         "token_logprobs": [ -8.4375 ]
       },
       "北京": {
         "tokens": [ "北京" ],
         "token_logprobs": [ -10.625 ]
       },
       "厦门": {
         "tokens": [ "厦门" ],
         "token_logprobs": [ -6.5625 ]
       },
       "深圳": {
         "tokens": [ "深圳" ],
         "token_logprobs": [ -1.8828125 ]
       },
       "珠海": {
         "tokens": [ "珠海" ],
         "token_logprobs": [ -7.9375 ]
       }
  }
  1. key: 标签名称

  2. value: 标签的概率

    1. token_logprobs:选中的token概率列表

    2. tokens:选中的token列表

注意

强烈建议使用单token_id的label,以大幅度提高性能。可以通过Tokenization接口判断是否为单token_id。

Code Sample

POST /api/v2/endpoint/${endpoint_id}/classification

说明

调用前请修改:

  1. 设置环境变量(或在代码中修改): VOLC_ACCESSKEYVOLC_SECRETKEY

  2. 修改调用模型名占位符{YOUR_ENDPOINT_ID}

  3. 本文档仅提供Curl调用示例,其他语言的代码示例可参见:

Curl
// Request
curl --request POST \
  --url http://maas-api.ml-platform-cn-beijing.volces.com/api/v2/endpoint/${YOUR_ENDPOINT_ID}/classification \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "query": "中国的第一个经济特区是?",
    "labels": [
        "北京",
        "珠海",
        "深圳",
        "厦门",
        "上海"
    ]
}'

// Response
{
    "label": "深圳",
    "label_logprobos": {
        "北京": {
            "tokens": [
                "北京"
            ],
            "token_logprobs": [
                -12.4375
            ]
        },
        "珠海": {
            "tokens": [
                "珠海"
            ],
            "token_logprobs": [
                -10.375
            ]
        },
        "上海": {
            "tokens": [
                "上海"
            ],
            "token_logprobs": [
                -10.25
            ]
        },
        "厦门": {
            "tokens": [
                "厦门"
            ],
            "token_logprobs": [
                -8.125
            ]
        },
        "深圳": {
            "tokens": [
                "深圳"
            ],
            "token_logprobs": [
                -3.75
            ]
        }
    },
    "usage": {
        "prompt_tokens": 15,
        "completion_tokens": 5,
        "total_tokens": 20
    }
}

Embeddings

Input

字段类型描述是否必填

input

list

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

"input": [
    "天很蓝",
    "海很深"
]

required

Output

字段子字段类型描述
req_idstring请求 id

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顺序对应

usage

object

该请求的用量统计信息。在 stream 模式下,只有最后一个输出片段才会记录 usage 内容。

prompt_tokensinteger输入 prompt 的 token 数量。
completion_tokensinteger模型输出的 token 数量。
total_tokensinteger输入和输出的总的 token 数量。

Code Sample

POST /api/v2/endpoint/${endpoint_id}/embeddings

说明

调用前请修改:

  1. 设置环境变量(或在代码中修改): VOLC_ACCESSKEYVOLC_SECRETKEY

  2. 修改调用模型名占位符{YOUR_ENDPOINT_ID}

  3. 本文档仅提供Curl调用示例,其他语言的代码示例可参见:

Curl
// Request
curl --request POST \
  --url http://maas-api.ml-platform-cn-beijing.volces.com/api/v2/endpoint/${YOUR_ENDPOINT_ID}/embeddings \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "input": [
        "天很蓝",
        "海很深"
    ]
}'

// Response
{
    "usage": {
        "prompt_tokens": 6,
        "total_tokens": 6
    },
    "object": "list",
    "data": [
        {
            "index": 0,
            "embedding": [
                0.011312266811728477,
                0.009318970143795013,
                ...
                -0.022353211417794228
            ],
            "object": "embedding"
        },
        {
            "index": 1,
            "embedding": [
                -0.001947728800587356,
                0.015627330169081688,
                0.018870584666728973,
                ...
                -0.03777957335114479
            ],
            "object": "embedding"
        }
    ]
}