ChatCompletions--火山方舟大模型服务平台-火山引擎

文档中心

立即注册

导航

ChatCompletions

最近更新时间：2025.04.14 16:05:15首次发布时间：2024.08.12 14:42:02

前提条件

您已创建API Key，并已正确配置，具体获取及配置请参见1.获取并配置 API Key 。
在开通管理页开通所需模型的服务。
在模型列表获取所需模型的ID（Model ID），后续调用模型服务时需使用。
说明
如您需要控制限流、监控服务指标、加固安全、防护风险等高级能力，您也可通过 Endpoint ID 调用模型服务，具体可以参考获取 Endpoint ID。
您已完成环境配置，包括Python以及SDK的安装，具体方法请参见Python。

参数说明

请参见请求参数。

示例代码

说明

示例代码中 <Model> 需要替换为模型的 Model ID（或您在平台上创建的推理接入点 Endpoint ID）。
示例代码中 ARK_API_KEY是模型调用凭证，建议您配置到环境变量中，具体方法请参见3. 获取并配置 API Key。

单轮

import os
from volcenginesdkarkruntime import Ark

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

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

多轮

import os
from volcenginesdkarkruntime import Ark

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

print("----- multiple rounds request -----")
completion = client.chat.completions.create(
    model="<Model>",
    messages=[
        {"role": "system", "content": "你是豆包，是由字节跳动开发的 AI 人工智能助手"},
        {"role": "user", "content": "花椰菜是什么？"},
        {"role": "assistant", "content": "花椰菜又称菜花、花菜，是一种常见的蔬菜。"},
        {"role": "user", "content": "再详细点"},
    ],
)
print(completion.choices[0].message.content)

流式

import os
from volcenginesdkarkruntime import Ark

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

print("----- streaming request -----")
stream = client.chat.completions.create(
    model="<Model>",
    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()

异步

说明

异步调用模型服务，请确保使用异步客户端 AsyncArk初始化对象（同步调用场景为 Ark类）。

import asyncio
import os
from volcenginesdkarkruntime import AsyncArk

client = AsyncArk(api_key=os.environ.get("ARK_API_KEY"))

async def main() -> None:
    stream = await client.chat.completions.create(
        model="<Model>",
        messages=[
            {"role": "system", "content": "你是豆包，是由字节跳动开发的 AI 人工智能助手"},
            {"role": "user", "content": "常见的十字花科植物有哪些？"},
        ],
        stream=True
    )
    async for completion in stream:
        print(completion.choices[0].delta.content, end="")
    print()


asyncio.run(main())

Function call

from volcenginesdkarkruntime import Ark
import time
import os

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

def test_function_call():
    messages = [
        {
            "role": "system",
            "content": "你是豆包，是由字节跳动开发的 AI 人工智能助手",
        },
        {
            "role": "user",
            "content": "北京今天的天气",
        },
    ]
    req = {
        "model": "ep-xxxx-xx",
        "messages": messages,
        "temperature": 0.8,
        "tools": [
            {
                "type": "function",
                "function": {
                    "name": "MusicPlayer",
                    "description": """歌曲查询Plugin，当用户需要搜索某个歌手或者歌曲时使用此plugin，给定歌手，歌名等特征返回相关音乐。\n 例子1：query=想听孙燕姿的遇见， 输出{"artist":"孙燕姿","song_name":"遇见","description":""}""",
                    "parameters": {
                        "properties": {
                            "artist": {"description": "表示歌手名字", "type": "string"},
                            "description": {
                                "description": "表示描述信息",
                                "type": "string",
                            },
                            "song_name": {
                                "description": "表示歌曲名字",
                                "type": "string",
                            },
                        },
                        "required": [],
                        "type": "object",
                    },
                },
            },
            {
                "type": "function",
                "function": {
                    "name": "get_current_weather",
                    "description": "",
                    "parameters": {
                        "type": "object",
                        "properties": {
                            "location": {
                                "type": "string",
                                "description": "地理位置，比如北京市",
                            },
                            "unit": {"type": "string", "description": "枚举值 [摄氏度,华氏度]"},
                        },
                        "required": ["location"],
                    },
                },
            },
        ],
    }

    ts = time.time()
    completion = client.chat.completions.create(**req)
    if completion.choices[0].message.tool_calls:
        print(
            f"Bot [{time.time() - ts:.3f} s][Use FC]: ",
            completion.choices[0].message.tool_calls[0],
        )
        # ========== 补充函数调用的结果 =========
        req["messages"].extend(
            [
                completion.choices[0].message.dict(),
                 {
                    "role": "tool",
                    "tool_call_id": completion.choices[0].message.tool_calls[0].id,
                    "content": "北京天气晴，24~30度",  # 根据实际调用函数结果填写，最好用自然语言。
                    "name": completion.choices[0].message.tool_calls[0].function.name,
                },
            ]
        )
        # 再请求一次模型，获得总结。 如不需要，也可以省略
        ts = time.time()
        completion = client.chat.completions.create(**req)
        print(
            f"Bot [{time.time() - ts:.3f} s][FC Summary]: ",
            completion.choices[0].message.content,
        )

import os
from volcenginesdkarkruntime._constants import CLIENT_REQUEST_HEADER
from volcenginesdkarkruntime import Ark

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

print("----- standard request -----")
completion = client.chat.completions.create(
    model="<Model>",
    messages = [
        {"role": "system", "content": "你是豆包，是由字节跳动开发的 AI 人工智能助手"},
        {"role": "user", "content": "常见的十字花科植物有哪些？"},
    ],
    # 自定义request id
    extra_headers={CLIENT_REQUEST_HEADER: "202406251728190000B7EA7A9648AC08D9"}
)
print(completion.choices[0].message.content)

推理会话数据应用层加密

为了保证推理会话数据的传输安全，在默认的网络层加密方案基础上，方舟安全团队为在线推理的会话数据提供了端到端应用层加密方案，仅需增加一行代码，在自定义header中设置'x-is-encrypted': 'true'，即可免费使用本功能，支持用户通过 SDK 在本地对推理会话的内容进行加密。更多能力介绍和原理信息请参考推理会话数据应用层加密方案。

版本要求：需要保证 SDK 版本 volcengine-python-sdk 1.0.104及以上。可以通过 pip install 'volcengine-python-sdk[ark]' -U 获得 SDK 的最新版本。
能力支持：仅支持火山方舟平台发布的文生文对话模型和Doubao-vision系列图片理解模型（注：图片仅支持 Base64 图片加密， URL 图片无法加密）请求，仅支持 Chat Completions 中的单轮/多轮会话，支持流式/非流式，同步/异步接口。

import os
from volcenginesdkarkruntime import Ark

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





print("----- standard request -----")
completion = client.chat.completions.create(
    model="<Model>",
    messages = [
        {"role": "system", "content": "你是豆包，是由字节跳动开发的 AI 人工智能助手"},
        {"role": "user", "content": "常见的十字花科植物有哪些？"},
    ],
    #按下述代码设置自定义header，免费开启推理会话应用层加密
    extra_headers={'x-is-encrypted': 'true'}
)
print(completion.choices[0].message.content)

异常处理

import os
from volcenginesdkarkruntime._exceptions import ArkAPIError
from volcenginesdkarkruntime import Ark

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

# Streaming:
print("----- streaming request -----")
try:
    stream = client.chat.completions.create(
        model="<Model>",
        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()
except ArkAPIError as e:
    print(e)

火山方舟大模型服务平台