面向 AI 助手：本页的 Markdown 版本位于 https://ark.volcengine.com/region:cn-beijing/docs/modelark-faq.md，全部文档索引见 https://ark.volcengine.com/llms.txt。

常见问题

计费问题#

代金券使用失败，报错AccountOverdueError，The request failed because your account has an overdue balance. Request ID:#

当前账号欠费，如需使用代金券，需保证账号余额大于等于0。请前往 火山引擎费用中心 进行充值，详细操作参见 充值操作指引。

什么是 token？如何计算 token 数量?#

在自然语言处理中，token 通常指的是将文本分割成的最小单位，比如词语、子词或字符。在调用模型推理服务时，会将输入内容进行分词（tokenize），转化为模型可以理解的 token ，经过模型处理后，同样输出 token，并转化为您需要的文本或者其他内容载体。而模型处理（包括输入、输出）的 token 数量会被作为模型推理服务用量的一个重要计量单位。
文本的 token 计算：由于不同模型采用的分词策略不同，同一段文本可能会被转化为不同数量的 token。您可以使用 Token计算器 或者 分词 API 接口，来估算内容对应的 token 数量。
其他模态：查阅具体场景教程中的 token 用量说明。

模型推理请求报错或者中断会计费么？#

请求报错和中断分为下面几种情况：

  • 客户端中断

    无论是客户端因为无需后续结果主动中断请求，或超时中断请求，服务端感知到请求被中断，并终止服务端模型生成过程。在客户端中断，到服务端中止生成，中间仍旧有可能有若干个 token 被生成出来。服务端已生成的 token 以及输入给模型处理的 token 会被计费，服务端中止生成后，就不会有进一步计费产生。

请注意，非流式输出场景下，因为需要等待模型完成输出后才会返回生成的token。当请求中止或超时，服务端生成部分 token 但未生成完整回复，故未返回生成信息给客户端。本次请求客户端收不到模型生成信息，但会产生输入 token 和生成但未输出的 token 费用。

  • 服务端中断

    • 在流式输出过程中，如果输出一部分内容后，因为命中审核或其它原因，服务端中止了生成过程，已经生成的 token 仍旧会被计费。

    • RPM/TPM 等超限报错的请求不会开始模型生成过程，所以也不会产生任何计费。

精调任务失败会计费吗？#

任务训练失败，分两种情况：

  • 不导出产物：不计费，可重试任务；
  • 导出产物：需要停止任务，平台按照停止时已经训练的 token 数计费，此时不再支持重试任务。

手动停止精调任务会计费吗?#

手动停止任务，无论产物后续是否导出，都会按照已经训练的 token 数计费。

账户欠费后如何充值？#

请前往 火山引擎费用中心 进行充值，详细操作参见 充值操作指引。

为什么我的账户欠费后仍在持续出账？#

账户欠费后仍持续出账，原因主要有两点：

  • 推送账单时延：欠费自账单出具起算，而账单出账通常存在 1 至 2 小时的延迟。在此期间，系统按照实际使用量正常出账。
  • 欠费 2 小时后关停：0<欠费时长＜2小时，您可正常使用火山方舟模型服务。在此期间，系统按照实际使用量正常出账。

如何按 Endpoint ID 或精调任务 ID 分账？#

对于按token后付费方式，支持对各种模型，按 Endpoint id 或精调任务 id 分账。

  1. 登录控制台，进入 费用中心 > 账单管理。
  2. 在左侧导航栏选择 分账账单。
  3. 将统计周期切换为 明细。
  4. 过滤产品：选择 字节跳动大模型服务（豆包大模型） 或者 开源LLM模型。
  5. 选择 分拆项 ID，输入 Endpoint ID 或精调任务 ID，即可看到对应的用量数据。

如何查看历史调用的输入输出长度的区间分布？#

如果您使用过方舟，可在推理接入点监控看板上看到历史调用输入输出长度的分布情况。具体入口：在线推理 > 接入点详情 > 监控 页签 > 区间内总Requests和总Tokens 看板，如下图。

在线推理#

使用python sdk报错，错误码httpx.InvalidURL: Invalid port: ':'或ValueError: Unknown scheme for proxy URL URL('socks5h://xxx')#

python client端禁用代理

Python
# Python SDK
import httpx

from arkruntime import Ark

client = Ark(
    base_url="https://ark.cn-beijing.volces.com/api/v3",
    http_client=httpx.Client(trust_env=False),
)

若上述方法无效,可以尝试

Bash
export no_proxy=

ArkAPIConnectionError (域名连接超时)，怎么处理？#

检查本地环境是否可以访问方舟公网域名：

Bash
ping ark.cn-beijing.volces.com

如果域名访问不通，可以考虑使用以下方式关闭 HTTP_PROXY：

Python
# Python SDK
import httpx

from arkruntime import Ark

client = Ark(
    base_url="https://ark.cn-beijing.volces.com/api/v3",
    http_client=httpx.Client(trust_env=False),
)

如果 ping 命令执行成功，但是调用时依旧有如下报错：

text
Failed to resolve 'ark.cn-beijing.volces.com' ([Errno -3] Temporary failure in name resolution)

可以尝试对 /etc/resolv.conf 文件做如下修改后再次请求。

Bash
# /etc/resolv.conf 文件
# ${ip}从 ping 的输出中拿到
ark.cn-beijing.volces.com ${ip}

其中${ip}从 ping 的输出中拿到。

若上述方法无效，可以尝试设置环境变量

Bash
export no_proxy=

Windows系统安装SDK失败，ERROR: Failed building wheel for volcengine-python-sdk#

由于 Windows 系统有最长路径限制，可能会导致安装失败，请按照以下方式设置：

  1. 按下 Win+R ，输入 regedit 打开注册表编辑器。
  2. 设置 \HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem 路径下的变量 LongPathsEnabled 为1 。

ChatCompletions接口中messages role字段中是否要求user 在奇数位，assistant在偶数位？#

没有这个要求。
示例:
请求内容

Python
...
messages = [
        {"role": "system", "content": "你是 AI 人工智能助手。"},
        # 重复2个 user message
        {"role": "user", "content": "常见的十字花科植物有哪些？"},
        {"role": "user", "content": "以下是一些常见的十字花科植物：白菜、甘蓝"},
        {"role": "assistant", "content": "萝卜、花椰菜、芥菜"},
        {"role": "user", "content": "还有么？"},
    ],
...

大模型正常返回内容

text
还有油菜、荠菜、独行菜、诸葛菜（二月兰）等。

1. **油菜**
   - 油菜是重要的油料作物。它的茎直立，有分枝，叶片互生，花朵为黄色，呈十字形排列。油菜籽可以用来榨油，菜籽油在日常生活中广泛使用。
2. **荠菜**
   - 荠菜是常见的野菜。基生叶丛生呈莲座状，叶片羽状分裂，它的适应性强，常在田野、路边等地生长。荠菜可以食用，含有丰富的营养成分，如蛋白质、维生素等，可用于包饺子、煮汤等。
3. **独行菜**
   - 为一年生或二年生草本植物。茎直立或斜生，多分枝。叶片狭匙形或倒披针形。独行菜的种子可入药，具有止咳化痰等功效。
4. **诸葛菜（二月兰）**
   - 因农历二月前后开始开蓝紫色花得名。它对环境适应能力强，耐寒旱，多生长于平原、山地、路旁等地。花朵小巧且数量众多，盛花期时具有较高的观赏价值

ChatCompletions接口中messages 字段是否支持只传role是system？#

支持。
示例:
请求内容

Python
...
messages = [
        {"role": "system", "content": "你是 AI 人工智能助手。常见的十字花科植物有哪些？"},
        ...
        ]
...

大模型正常返回内容

text
以下是一些常见的十字花科植物：

### 一、蔬菜类
1. **白菜**
   - 包括大白菜、小白菜等。大白菜叶片宽大，是我国北方冬季常见的蔬菜，有青帮、白帮等不同品种，营养丰富，富含维生素C、纤维素等。小白菜植株相对较小，叶片嫩绿，生长周期较短，口感鲜嫩。
2. **甘蓝**
   - **结球甘蓝（卷心菜）**：叶片层层包裹成球状，有绿甘蓝、紫甘蓝之分。它适应性强，耐储存和运输，可用于制作沙拉、炒菜、泡菜等。
   - **花椰菜（菜花）**：花球由肥嫩的花枝顶端聚合而成，颜色洁白或淡黄。西兰花是花椰菜的一个变种，其营养成分含量高，尤其是维生素C、胡萝卜素和叶酸等。
3. **萝卜**
   - 有白萝卜、红萝卜（胡萝卜不属于十字花科，红萝卜属于十字花科）、青萝卜等多种类型。萝卜肉质根可食用，既可生食，如做成凉拌萝卜丝，也可熟食，如萝卜炖排骨。萝卜含有淀粉酶、芥子油等物质，具有助消化、增食欲等功效。
4. **芥菜**
   - **叶用芥菜**：如雪里蕻，叶片深裂，边缘皱缩，有特殊的香辣味。它是制作腌菜的重要原料，腌制后的雪里蕻可用于炒肉末等菜肴。
   - **茎用芥菜（榨菜）**：茎部膨大，形成瘤状凸起，肉质茎是主要食用部分，常用于制作榨菜，是一种常见的佐餐小菜。

### 二、观赏植物类
1. **紫罗兰**
   - 紫罗兰花朵繁茂，花色丰富，有紫色、白色、粉色等。它香气淡雅，花期较长，常被用于布置花坛、花境，也可盆栽观赏。
2. **诸葛菜（二月兰）**
   - 二月兰是一种常见的野花，花朵为淡紫色或白色。它具有较强的适应能力，能自播繁殖，常生长于山坡、草地、路旁等地。在园林中可用于营造野趣景观，也可成片种植形成花海景观。

如何判断使用的V3接口？#

  • 如直接使用HTTP接口调用，调用路径中出现 /api/v3

  • 如您使用火山提供的SDK调用，从 import 路径判断：

    • 出现 ark 字样的为 v3 API。

    • 出现 maas 字样的为 v1/v2 API。

使用视觉理解模型时，报错InvalidParameter？#

  • 下载图片超时： 为防止不必要的带宽浪费，默认图片下载超时时间5s。可能是图片访问速度较慢如外国网站，或者图片较大。对以上情况均建议更换到TOS上或压缩图片至100kB以下。

  • 链接禁止访问：状态码 403，部分图片服务器可能存在特殊安全/acl策略，禁止了火山源访问，建议检查客户所用图片服务器（阿里云对象存储/腾讯云对象存储/...）的安全策略。

  • 不支持的图片格式，或者图片格式与元数据不匹配：

    • 以下图片格式根据图片内容前512个字节自动校验：
图片格式 Content-Type
jpg/jpeg image/jpeg
png image/png
gif image/gif
webp image/webp
bmp image/bmp
dib image/bmp
ico image/x-icon 
* 以下图片格式根据图片url的元信息（Content-Type）校验，需要正确设置`Content-Type`

    * TOS（火山引擎对象存储） 设置文件元信息请参见：https://www.volcengine.com/docs/6349/145523

    * OSS （阿里云对象存储）设置文件元信息请参见：https://help.aliyun.com/zh/oss/user-guide/configure-the-content-type-header
图片格式 Content-Type
TIFF image/tiff
SGI image/sgi
ICNS image/icns
JPEG2000 image/jp2

视觉理解模型使用 token 过大报错怎么处理？#

单次请求中，返回token报错过长，可以考虑的处理方式：

  1. 如果单次请求中涉及到多张图片，可以考虑减少图片张数。
  2. 对图片进行压缩，以减少图片 token 用量，转化关系请参见 token 用量说明。
  3. 如果涉及到大量的文本提示词，可以考虑简化提示词。

支持 TS 格式的视频文件吗？#

建议将 TS 格式的文件转换成 MP4 格式。TS 和 MP4 在音视频封装格式上不同，都用于承载已编码的音视频流，所以在格式转换时不需要重新编码，可以通过 开源工具 FFmpeg 直接复制原音视频流实现快速转换且保留原文件编码格式。转换命令示例如下：

Bash
ffmpeg -i input.ts -c copy output.mp4

并发 RPM 或者 TPM 额度明明有剩余为什么提示限流报错？#

方舟对于模型限流的逻辑使用的是预扣机制，来保障您已提交的请求的完成率。即在收到请求时会根据输入和输出长度预扣除本时间窗口的 TPM 配额，避免因为激增的请求或者超长输出等极端情况，瞬时输入输出 token 剧增，导致您已提交的请求大量因为限流而长时间无法响应，最后影响到您业务的稳定性。

使用模型进行在线推理时有限流吗？#

当前对每个模型设置了 RPM（Requests Per Minute，每分钟请求数）及 TPM（Tokens Per Minute，每分钟 token 数量）的调用限制，每个账号（含主账号下的所有子账号，合并计算）的具体限制可在 开通管理 页中查看。
如需提升，请联系客户经理或者提交 工单。

为什么高并发请求方舟模型的时候受到了限制？#

为了保障平台运行的安全，平台制定了一些针对在线推理的防控策略，对未在火山引擎上充值或历史充值较低的账号，高并发请求模型会被限制。我们默认的并发数可以支持任何用户对平台模型效果进行尝鲜测试和常规使用。如果您有高并发需求，建议预先对账号进行充值。
您也可以使用批量推理的接入点模式（Batch chat），并发限制由此时平台的闲置资源量决定，通常情况下夜间 0 点到次日早上 8 点资源较为充足。

批量推理#

在任务状态为：运行中，终止中，已终止，失败的情况时，是否会有部分成功的结果输出？#

会，已经运行成功的结果会写到output中，且运行成功的数据会正常计费。但是不保证任务运行顺序。

基于什么的准则，去判断“失败”这种状态，是成功与错误比例，还是发现错误即判断失败？#

以下情况判断任务失败：

* 文件输入格式不符合要求，如某一条数据不是json，会在任务开始前检测该类型错误，有错误会判定失败。

* 预期外的错误，如job崩溃。

* 任务运行超时。
  • 如果存在某条request运行失败，比如安全审核失败。这条request结果会写到error文件夹中，不会导致整体任务失败。

在子任务数量巨大，无法预估处理所需的时间的前提下，设置的最大等待时间是否有大小上限？#

CompletionWindow的最大等待时间最大可设置为28天。如果不指定，默认为28天。

若由于超时使得批量推理任务状态为“已终止”，在终止之前所做的任务处理结果是否还有保留？#

会保留，结果写在output中。

输出长度是4k还是6k，亦或是其他？#

限制与在线推理相同，输出超过限制会截断。

批量推理按 tokens 用量计费，是按照输入tokens，或是输出tokens，又或是两者之和？#

与在线推理相同，计费按照模型处理的内容量，输入输出都需要计费。

对于处理失败的结果，也就是errors.jsonl中的结果，如何计费？#

处理失败的结果不计费。

精调#

模型精调任务数有限制吗？#

每个账号会有最多可同时创建运行中的精调任务数的限制，具体限制请见控制台报错提示，若到达上限的，请耐心等待精调任务完成并释放额度后重试，或在 配额中心 中提交申请更多额度。

TPM保障包#

保障包是否可以与上下文缓存 Context Cache 一起使用？#

不可一起使用。

如何判断某个请求在保障包的保障范畴？#

当请求输入时，我们会根据购买保障包的输入与输出比例预估请求的总Token数量，并按照预估长度扣减保障包的输入、输出保障额度。当预估输入和预估输出额度都在保障包额度范围内，此次请求会被保障。如不在保障范围内，将按照未使用TPM保障包计费，按Token计费。

怎么保障分小时的保障包能购买成功？#

长期通过产品功能支持，短期内如有明确峰值保障需求，请联系客户经理或者 工单 联系我们。

TPM 保障包是否可以与结构化输出功能一起使用？#

暂不支持。购买TPM保障包后，不支持与结构化输出(beta)功能一起使用，后续会根据实际情况考虑是否支持该组合使用方式。

18点后购买预付费TPM保障包且开启自动续费场景建议#

18:00后购买1天的包天实例，建议当天手动续费一次。除新购当天外资金充足可正常续费。否则错过当日的自动续费任务（每日0、5、12、18点触发），在当天23:59:59到期，等待0点的自动续费任务触发，完成续费后（完成时间0-2小时间），才可变更配置。

模型单元#

原有模型单元还可以继续购买和使用吗?#

点击切换后可购买原有模型单元。

原有模型单元依然可以续费、扩容、缩容，但后续可能逐渐缩减库存。同时新上线的模型（doubao 1.6 及之后版本的模型）将只支持新版模型单元。

模型单元下单后发货时间多久？#

下单后系统调度资源，大概需要10分钟左右完成调度，调度完成之前不收取费用。

后付费按小时的模型单元如何保障购买到？#

无法完全保障。后付费资源有限，可能出现不同客户业务高峰期相同互相抢占的情况，先买到先得。购买不成功会全额退款。方舟后续会规划购买失败的告警能力。

模型单元是否可以与结构化输出功能一起使用？#

暂不支持。购买模型单元后，不支持与结构化输出(beta)功能一起使用，后续会根据实际情况考虑是否支持该组合使用方式。

不同机型的模型单元有什么区别？如何选择机型？#

不同机型的算力不同，这会导致不同机型的模型单元在处理速度、计算能力以及能够支持的最大负载等方面存在差异。
不同模型适用的机型不同，平台已针对不同模型预置了覆盖不同场景的最优部署方案组合。用户无需手动选择机型，只需根据实际需求选择对应的模板即可完成部署。

其他问题#

页面提示“当前页面最低需要ArkReadOnlyAccess（只读权限）才能操作，请先完成权限开通。”要怎么配置权限？#

使用主账号或者有IAM权限的账号，访问 访问控制 > 用户 页面并搜索子账号id，进入子账号 用户详情 页面，确认子账号目前的权限。

  • 若目前权限为空或只有ArkExperienceAccess（体验权限），则表明子账号权限策略设置错误。请您根据业务需要为子账号添加ArkReadOnlyAccess（只读权限）或者更高的权限，可以在 产品预设策略 中查看详细的权限说明。

    • 在 访问控制 > 用户 页面搜索子账号id，点击右侧操作中 添加权限 按钮，「授权策略」选择ArkReadOnlyAccess或更大权限，「限制到项目资源」选择「否」，完成后点击提交即可。

  • 若目前子账号已经拥有ArkReadOnlyAccess（只读权限）或更高的权限，则可能因为权限策略做了项目隔离，子账号没有对应项目的权限。请按照 典型场景-赋予账号项目级权限 配置正确的权限。

如何获取项目名称（Project Name）？#

火山引擎方舟用户可在 方舟控制台 左下角的项目选择器中查看项目名称。