语言大模型具备文本理解和文字对话的能力。如当您传入文本信息时，大模型可以理解信息，并结合这些信息进行回复。通过这篇教程，您可以学习到如何使用模型服务 API，来调用模型理解文本，生成文本内容，并可以基于此 API 构建或者扩展自己的应用或者自动化任务。

您可以在以下场景中使用模型的文本生成能力。

• 您已有方舟 API Key，作为模型推理服务调用鉴权使用。如无，请参考1.获取 API Key。

• 在开通管理页开通所需模型的服务。

• 在模型列表获取所需模型的ID（Model ID），后续调用模型服务时需使用。

  说明

  如您需要控制限流、监控服务指标、加固安全、防护风险等高级能力，您也可通过 Endpoint ID 调用模型服务，具体可以参考获取 Endpoint ID。

支持文本生成的大模型当前支持在请求中传入图片链接，图片信息需要作为用户角色输入信息传给大模型，即"role": "user"，下面是简单的文本生成调用示例代码。

import os
# 通过 pip install volcengine-python-sdk[ark] 安装方舟SDK
from volcenginesdkarkruntime import Ark

# 从环境变量中获取您的API KEY，配置方法见：https://www.volcengine.com/docs/82379/1399008
api_key = os.getenv('ARK_API_KEY')
# 替换 <Model> 为模型的Model ID
model = "<Model>"

# 初始化Ark客户端
client = Ark(api_key = api_key)

# 创建一个对话请求
completion = client.chat.completions.create(
    model = model,
    messages = [
        {"role": "user", "content": "请将下面内容进行结构化处理：火山方舟是火山引擎推出的大模型服务平台，提供模型训练、推理、评测、精调等全方位功能与服务，并重点支撑大模型生态。 火山方舟通过稳定可靠的安全互信方案，保障模型提供方的模型安全与模型使用者的信息安全，加速大模型能力渗透到千行百业，助力模型提供方和使用者实现商业新增长。"},
    ],
)

print(completion.choices[0].message.content)

模型回复预览：

**一、火山方舟的所属与定位**
火山方舟是火山引擎推出的大模型服务平台。

**二、火山方舟的功能与服务**
1. 提供全方位功能
   - 包括模型训练、推理、评测、精调等功能与服务。
2. 重点支撑
   - 重点支撑大模型生态。

**三、火山方舟的安全保障与作用**
1. 安全保障
   - 通过稳定可靠的安全互信方案，保障模型提供方的模型安全与模型使用者的信息安全。
2. 作用
   - 加速大模型能力渗透到千行百业，助力模型提供方和使用者实现商业新增长。

当前支持文本生成的模型有如下这些：

• Doubao-1.5-pro：最新一代专业版大模型，单价不提升的同时，模型能力有大幅提升，在知识（MMLU_PRO：80.2； GPQA：66.2）、代码（FullStackBench：65.1）、推理（DROP：92.6）、中文（C-Eval：91.5）等相关的多项测评中获得高分，达到行业SOTA水平。
• Doubao-1.5-lite：最新一代轻量版大模型，单价不提升的同时，模型能力有大幅提升，模型效果比肩专业版模型Doubao-pro-32k-0828，您享受轻量版模型的成本和性能，获得过去专业版模型的效果。
• deepseek：支持DeepSeek V3最新版本（deepseek-v3-250324）、DeepSeek R1深度思考模型（deepseek-r1-250120）等。
• Doubao-pro：是字节推出的专业版大模型，在能力上突出，在参考问答、摘要总结、创作等广泛的应用场景上能提供优质的回答，是同时具备高质量与低成本的极具性价比模型。本系列模型根据角色扮演、工具调用、超长文本等细分领域推出加强版本，建议您首先尝试该系列模型对应领域的最新的版本，以获取更强的模型能力。
• Doubao-lite：是字节推出的轻量级大模型，具备极致的响应速度，且推理单价更便宜，适合不复杂的任务处理，或者对于时延有更高要求的场景。同时，模型配合精调使用可以获得更优质的效果。同样该系列模型也推出了角色扮演、长文本等细分领域加强的模型，供您选择。

更多模型选择的建议：

• 选择最新的模型：如果您首次选择模型，推荐您选择对应系列最新版本模型。如doubao-pro-32k 240828能力强于doubao-pro-32k 240615 10%左右，尤其在文本分类、内容创作等能力大幅提升。
• 选择对应领域的模型：如果您在角色扮演、工具调用等领域，推荐您选择对应领域加强的模型。可以在模型列表看到。
  • 联网总结：模型版本中带browsing字段的模型，配合联网插件使用，在网页内容总结方面具有更好的效果，信息检索回答任务全面提升，回答更准确、更少冗余内容。
  • 工具调用：模型版本中带functioncall字段的模型，对任务解析与函数调用的能力进行了重点优化，在调用预定义函数、获取外部信息方面都有更好的效果。如您使用大模型时需要调用函数或者其他接口时可选该类模型。
  • 角色扮演：模型版本中带character字段的模型，针对性提高角色扮演与情感陪伴能力，具备更强的上下文感知与剧情推动能力，多轮对话、智能交互类场景可以选择该模型。
  • 长文本：模型名称中带128k、256k字段的模型，可以输入 20 万字（128k）、40 万字（256k）左右的上下文，您进行如文本分类与信息抽取、小说全文总结摘要等长文本分析场景可以选择该类模型。
  • 通用任务：应对通用任务，适合绝大部分场景，如果您业务不在前面所述特定领域，即可选择该类模型。

模型计费说明请参见大语言模型。

提示词（Prompt）是输入给模型的信息，模型会根据提示词来进行推理，生成回复内容。正确设计和编写提示词，如提供说明、示例、好的规范等方法可以提高模型输出的质量和准确性。而进行提示词优化的工作也被称为提示词工程（Prompt Engineering）。

我们为您提供了如何编辑好的提示词的一些实践Prompt 最佳实践，您可以基于实践来优化提示词，以获得更好的回复。

下面为您介绍如何使用 chatcompletions 接口，将提示词正确输入给模型。
在 对话(Chat)-文本 API中，您可以通过 messages 对象将信息传入给模型，其中role字段定义信息传入的角色，content承载消息内容。模型会结合传入的角色和信息来理解内容，并生成对应的回复。

用户消息

最终用户传入给模型消息，此时 role 字段应设置为user，该类型消息往往是包含用户希望模型处理的具体任务或者处理的信息。
下面就是一个简单的用户消息，要求模型对文本进行结构化处理。

messages = [
    {"role": "user", "content": "请将下面内容进行结构化处理：火山方舟是火山引擎推出的大模型服务平台，提供模型训练、推理、评测、精调等全方位功能与服务，并重点支撑大模型生态。 火山方舟通过稳定可靠的安全互信方案，保障模型提供方的模型安全与模型使用者的信息安全，加速大模型能力渗透到千行百业，助力模型提供方和使用者实现商业新增长。"}
]

系统消息

用于指定模型扮演角色或交代背景信息，此时 role 字段应设置为system。如果设置系统消息，请放在messages列表的第一位。
下面是一个系统消息示例，模型会作为文本转化工具进行结构化处理。

messages =[
    {"role": "system", "content": "你是一个文本转化器，能够将输入的文本进行结构化处理。你收到信息后，只返回结构化处理后的内容，不应该返回其他内容。"},
    {"role": "user", "content": "请将下面内容进行结构化处理：火山方舟是火山引擎推出的大模型服务平台，提供模型训练、推理、评测、精调等全方位功能与服务，并重点支撑大模型生态。 火山方舟通过稳定可靠的安全互信方案，保障模型提供方的模型安全与模型使用者的信息安全，加速大模型能力渗透到千行百业，助力模型提供方和使用者实现商业新增长。"},
]

模型消息

假定为模型返回的消息，此时role字段应设置为assistant。在多轮对话中，会需要传入历史的对话，而模型回复的消息就可以用模型消息表示。

messages =[
    {"role": "system", "content": "你是个十进制计算器，只返回结算结果，不返回其他"},
    {"role": "user", "content": "一加一"},
    {"role": "assistant", "content": "2"},
    {"role": "user", "content": "再加一"},
]

• 每个模型输出有几个关键的限制，各个模型详细的规格信息，请参见 模型列表。
  • 最大上下文长度（Context Window）：即单次请求模型能处理的内容长度，包括输入的内容和模型输出的内容，单位 token ，超出最大上下文长度的内容会被截断处理，这会导致模型处理信息时丢失部分信息或者输出信息被截断。如碰到上下文限制导致的内容截断，可以选择支持更大最大上下文长度规格的模型，如doubao-pro-128k、doubao-pro-256k等模型名称中带128k、256k字段的模型。
  • 最大输出长度（Max Output Tokens）：即单次模型输出的内容的最大长度，内容过长会被截断。如果碰到这种情况，可以参考Prefill Response模式最佳实践，实现多次回复，拼接出完整回复。
  • 每分钟处理内容量（TPM）：即账号下同模型（不区分版本）每分钟能处理的内容量限制，单位 token。如果默认 TPM 限制无法满足您的业务，您可以通过工单联系我们提升配额。

    举例来说：一个主账号下，创建doubao-pro-32k a、b、c 3个版本的A、B 、C 3个推理接入点，某模型的 TPM 为80w。那么某分钟，A、B、C 3个节点处理内容量 A 20w token、B 50w token、C 20w token，就会在触发80w TPM限制，并产生报错。

  • 每秒钟处理请求数（QPS）：即账号下同模型（不区分版本）每秒钟能处理的请求数上限，与上面TPM类似。如果默认 QPS 限制无法满足您的业务，您可以通过工单联系我们提升配额。

对于token用量，您可以使用接口分词 API来计算。

单轮对话

与模型进行一次交互，交互内容为单轮对话，模型根据系统消息和用户消息来返回内容。

因为是非流式输出，需要等待模型推理完所有内容，将内容一起返回给您，会有一定延时。

import os
from volcenginesdkarkruntime import Ark
# 从环境变量中获取您的API KEY，配置方法见：https://www.volcengine.com/docs/82379/1399008
client = Ark(api_key=os.environ.get("ARK_API_KEY"))

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

多轮对话

组合使用系统消息、模型消息以及用户消息，可以实现多轮对话，即根据一个主题进行多次对话。
需要注意，chat.completions接口是无状态的，在每次请求时，将历史信息都放在messages中，并通过role字段设置，让模型了解之前不同角色的不同对话内容，以便进行主题相关的延续性对话。

import os
from volcenginesdkarkruntime import Ark
# 从环境变量中获取您的API KEY，配置方法见：https://www.volcengine.com/docs/82379/1399008
client = Ark(api_key=os.environ.get("ARK_API_KEY"))

completion = client.chat.completions.create(
    # 替换 <Model> 为模型的Model ID
    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
# 从环境变量中获取您的API KEY，配置方法见：https://www.volcengine.com/docs/82379/1399008
client = Ark(api_key=os.environ.get("ARK_API_KEY"))

print("----- streaming request -----")
stream = client.chat.completions.create(
    # 替换 <Model> 为模型的Model ID
    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()

异步输出

当您的任务较为复杂或者多个任务并发等场景下，您可以使用Asyncio接口实现并发调用，提高程序的效率，优化体验。示例代码如下：

import asyncio
import os
from volcenginesdkarkruntime import AsyncArk
# 从环境变量中获取您的API KEY，配置方法见：https://www.volcengine.com/docs/82379/1399008
client = AsyncArk(api_key=os.environ.get("ARK_API_KEY"))

async def main() -> None:
    stream = await client.chat.completions.create(
        # 替换 <Model> 为模型的Model ID
        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

支持工具调用模型包括deepseek-v3-250324、deepseek-r1-240120、doubao-1.5-pro-32k-250115、doubao-1.5-lite-32k-250115等，详细请参见 支持范围。

import os
from volcenginesdkarkruntime import Ark

# 从环境变量中获取您的API KEY，配置方法见：https://www.volcengine.com/docs/82379/1399008
client = Ark(api_key=os.environ.get("ARK_API_KEY"))

print("----- function call request -----")
completion = client.chat.completions.create(
    # 替换 <Model> 为模型的Model ID
    model="<Model>",
    messages = [
        {"role": "user", "content": "北京今天天气如何？"},
    ],
    tools=[
        {
            "type": "function",
            "function": {
                "name": "get_current_weather",
                "description": "获取给定地点的天气",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "location": {
                            "type": "string",
                            "description": "地点的位置信息，比如北京"
                        },
                        "unit": {
                            "type": "string",
                            "enum": [
                                "摄氏度",
                                "华氏度"
                            ]
                        }
                    },
                    "required": [
                        "location"
                    ]
                }
            }
        }
    ]
)
print(completion.choices[0])

异常处理

增加异常处理，帮助定位问题。

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

# 从环境变量中获取您的API KEY，配置方法见：https://www.volcengine.com/docs/82379/1399008
client = Ark(api_key=os.environ.get("ARK_API_KEY"))

# Streaming:
print("----- streaming request -----")
try:
    stream = client.chat.completions.create(
        # 替换 <Model> 为模型的Model ID
        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)

Prefill Response模式

通过预填（Prefill）部分Assistant 角色的内容，来引导和控制模型的输出。输出的控制可以应用在多个方面：强制按照 JSON 或 XML 等特定格式输出；跳过已生成的内容，避免触发模型最大输出限制；控制大模型在角色扮演场景中保持同一角色。

• 支持的模型：Doubao-pro ［热门］、Doubao-lite 0828版本及以后。
• 更详细的场景使用说明，请参见Prefill Response模式最佳实践。

import os
from volcenginesdkarkruntime import Ark

# 从环境变量中获取您的API KEY，配置方法见：https://www.volcengine.com/docs/82379/1399008
client = Ark(api_key=os.environ.get("ARK_API_KEY"))
completion = client.chat.completions.create(
    # 替换 <Model> 为模型的Model ID
    model="<Model>",
    messages=[
        {"role": "user", "content": "你是一个计算器，请计算： 1 + 1 "},
        # 最后Role为Assistant，并补充部分内容，便于模型进行续写
        {"role": "assistant", "content": "="}
    ]
)
print(completion.choices[0].message.content)

对话加密

为了保证推理会话数据的传输安全，在默认的网络层加密方案基础上，为在线推理的会话数据提供了端到端应用层加密方案，更多能力介绍和原理信息请参见推理会话数据应用层加密方案。
您可以通过增加一行代码免费使用本功能。

• 使用要求
  • 需要保证 SDK 版本 volcengine-python-sdk 1.0.104及以上。可以通过 pip install 'volcengine-python-sdk[ark]' -U 获得 SDK 的最新版本。
• 使用限制
  • 仅支持豆包文生文语言模型。
  • 仅支持 ChatCompletions 中的单轮/多轮会话，支持流式/非流式，同步/异步接口。

示例代码如下

import os
from volcenginesdkarkruntime import Ark

# 从环境变量中获取您的API KEY，配置方法见：https://www.volcengine.com/docs/82379/1399008
client = Ark(api_key=os.environ.get("ARK_API_KEY"))

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

设置模型最大输出长度

当您需要调整模型输出长度，如需要控制成本，希望模型每次输出不超过500字；或者希望模型输出内容篇幅更长，避免中途截断，您可以通过在请求时设置max_tokens字段，来达成目标。

import os
from volcenginesdkarkruntime import Ark

# 从环境变量中获取您的API KEY，配置方法见：https://www.volcengine.com/docs/82379/1399008
client = Ark(
    api_key=os.environ.get("ARK_API_KEY"),
    )
completion = client.chat.completions.create(
    # 替换 <Model> 为模型的Model ID，查询链接https://www.volcengine.com/docs/82379/1330310
    model="<Model>",
    messages=[
        {"role": "system", "content": "你是豆包，是由字节跳动开发的 AI 人工智能助手"},
        {"role": "user", "content": "常见的十字花科植物有哪些？"},
    ],
    # 设置模型最大输出长度为 1024 token，您可以按需进行调整
    max_tokens=1024,
)
print(completion.choices[0].message.content)

批量推理

方舟为您提供批量推理的能力，当您有大批量数据处理任务，可以使用批量推理能力，以获得更大吞吐量。详细介绍和使用，请参见 批量推理。

• 对话(Chat)-文本 API：文本生成的API参数说明，调用模型的文本生成能力，可参考文本生成API参数说明。
• 常见问题-在线推理：在线推理的常见问题，如果遇到错误，可以尝试在这里找解决方案。
• Prefill Response模式最佳实践：提升多轮对话角色一致性，优化模型回复格式，缓解模型输出最大限制，可参考本解决方案。