# 在线推理（TPM 保障包）
> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。
**在线推理（TPM保障包）** 使用平台预留资源，保障模型请求吞吐量达到指定TPM（Tokens Per Minute，每分钟处理的Token总量），目前拥有最高优先级。同时，溢出部分使用 **在线推理（常规）** 处理 token，并溢出 token 按降级后的推理模式计费。本文介绍**在线推理（TPM 保障包）** 的主要优势、支持的模型和使用流程。
# 主要优势
* **更低的延迟**：相比 **在线推理（常规）**，**在线推理（TPM 保障包）** 的延迟更低，通常低 1/3 - 1/2。
* **更高的吞吐量**：通过预留资源保障指定TPM吞吐量，同时支持超过默认限流额度的并发请求数。
* **更强稳定性**：提供高资源确定性保障，在保障范畴内不会命中异常流量熔断、限速策略，持续保障业务服务可用性。
* **弹性伸缩**：后付费TPM保障包，支持定时调整TPM保障包数量，贴合业务波峰波谷，提升资源利用率并降低成本。
* **灵活组合**：
* **组合使用后付费与预付费保障包**：在业务高峰时段，您可以将按小时（后付费）与按天（预付费）的保障包叠加使用，以更好地匹配流量峰谷，从而避免资源浪费。
* **组合使用保障包与常规在线推理**：系统会优先消耗您的保障包额度。当请求超出额度后，将自动降级为常规在线推理模式。这种方式既能为可预估的流量提供性能保障，也能为临时流量高峰提供缓冲。**请注意，超出部分的流量会计算在默认限流额度中**。
# 适用场景
* 追求更低延迟，更高并发的高需业务。
* 可预估流量大小的高流量业务。
* 无法接受偶发的资源紧张报错的业务。
> **注意**
>
> * TPM 保障包保障输出 Token 生成速率（TPOT，Time Per Output Token），不同模型能达到的延迟水平存在差异。
> * TPM 保障包不保障首 Token 延迟（TTFT，Time To First Token），但通常 TTFT 优于公共资源池。
# 支持范围
## 支持模型
参考 [TPM 保障包](/docs/model-pricing#952683a2)，实际支持的模型以控制台显示为准。
如需支持更多模型或版本，可提交 [工单](https://console.volcengine.com/workorder/create?step=2&SubProductID=P00001166) 申请。
## 支持接口
[Chat API](/docs/chat-api)：当前只支持 Chat API。
# 使用流程
> 如业务对于延迟有需求，可提交 [工单](https://console.volcengine.com/workorder/create?step=2&SubProductID=P00001166) 申请。
## 1 创建推理接入点
TPM 保障包需与推理接入点（Endpoint，调用推理服务的网络入口，简称 接入点）绑定后使用，即在创建或编辑接入点时，购买或调整TPM保障包。
1. 访问 [创建推理接入点](https://ark.volcengine.com/region:cn-beijing/endpoint/create) ，按页面引导填写。注意选择接入模式为 **TPM保障包**。
* 强烈推荐打开右上角 **创建说明** 开关，帮助您了解每个配置项的使用场景和含义。
2. 根据业务需求使用 TPM计算器 **（** 选择接入模式为 **TPM保障包** 后，在右侧 **创建说明** 中可见）预估需购买的输入和输出额度，并 [申请配额](https://ark.volcengine.com/region:cn-beijing/projectManagement)。
详细抵扣说明见 [额度抵扣说明](/docs/tpm-guarantee-package#93d074ff)。
3. 创建完成后进入 **调度中** 状态，当状态变成 **健康** 后，可正常调用。
> **说明**
>
> 推理接入点默认会创建在 default 项目下，如果您希望在其他项目下创建，请在导航栏左下角切换项目。
## 2 获取 Endpoint ID
在 [在线推理](https://ark.volcengine.com/region:cn-beijing/endpoint) 查看并复制推理接入点 ID（Endpoint ID）。
## 3 通过 Endpoint ID 调用模型
典型示例代码如下，更多示例代码可参见 [文本生成](/docs/text-generation) 章节。
```Python
# 安装 sdk 参见 https://ark.volcengine.com/region:cn-beijing/docs/install-and-upgrade-sdk
# 文本生成支持 Chat API，暂不支持 Responses API
import os
from arkruntime import Ark
client = Ark(
api_key=os.environ.get("ARK_API_KEY"),
# The base URL for model invocation
base_url="https://ark.cn-beijing.volces.com/api/v3",
)
completion = client.chat.completions.create(
# Replace with your Endpoint ID
model="ep-2025****-**",
messages=[
{"role": "user", "content": "Hello"}
],
# service_tier="auto", # 默认为 auto，可不配置。
)
print(completion.choices[0].message)
```
# 额度抵扣说明
> **注意**
>
> **TPM 额度按分钟计量（Tokens Per Minute），并非瞬时额度：**
>
> * **瞬时上限与溢出**：单位时间内可用的最大瞬时额度约为分钟额度的 **25%** 左右；超出部分会自动降级为 **在线推理（常规）**。
> * **使用建议**：建议将请求流量在分钟内均匀分发，避免瞬时突发。
|说明 |图示：TPM计算器 | |
|---|---|---|
|**抵扣逻辑** | | | \
| | | | \
|* **不同模型**，请求的**不同输入输出长度**，抵扣 TPM 额度的速度不同，需按抵扣系数计算购买的TPM。 | | | \
|* 抵扣额度计算公式 | | | \
| * 抵扣输出额度 = 输出 token * 抵扣系数 | | | \
| * 抵扣输入额度 = 输入 token * 抵扣系数 | | | \
|**TPM 计算器** | | | \
| | | | \
|* 可通过 TPM 计算器 查看相应的抵扣系数，并估算实际需要购买的**可抵扣 TPM**。 | | | \
|* 入口：[创建接入点](https://ark.volcengine.com/region:cn-beijing/endpoint/create)，完成模型选择，并选中 TPM 保障包，在右侧创建说明窗格中展示。 | | | \
|**抵扣示例** | | | \
| | | | \
|* 购买的某模型的 TPM 信息： | | | \
| * 额度：输入 1000k TPM，输出 200k TPM。 | | | \
| * 抵扣系数：输入 10k token 时抵扣系数为 1，输出 1k token 时抵扣系数为 4。 | | | \
|* 当输出 TPM 达到 50k token 时，`50k * 4 抵扣系数 = 200k token`，TPM 输出额度达上限。 | | |
# 弹性伸缩
## 规则介绍
后付费TPM保障包，支持配置弹性伸缩规则，帮助您根据业务负载动态调整TPM保障包数量，进一步提升资源利用率并降低成本。
支持以下两种弹性规则，多个弹性规则可叠加，灵活覆盖全业务周期。详细配置要求和注意事项请参见控制台 **创建说明**。
* **定时弹性**：您可以设置在某一时间节点（可精确到分钟）后将TPM保障包的输入TPM（每分钟可处理的输入Token总量）和输出TPM（每分钟可生成的输出Token总量）调整到您所需的新的值。
* **周期性弹性**：您可以「按天重复」、「按周重复」或「Cron表达式」来设置时间规则，TPM保障包的输入TPM和输出TPM将会在您所设置的时间节点后调整到您所需的新的值。
## 配置示例
* 业务需求：下午6点到晚上9点期间，某 接入点 需要大约 10000 TPM 的保障包。
* 规则设置：可通过设置两条周期性弹性规则，如下表。
|规则说明 |示例截图 |
|---|---|
|每日 18:00 触发： | | \
| | | \
|* 输入 TPM：10k TPM | | \
|* 输出 TPM：1 k TPM | |
|每日 21:00 触发： | | \
| | | \
|* 输入 TPM：0k TPM | | \
|* 输出 TPM：0k TPM | |
# 订阅通知
您可以使用火山引擎消息通知服务（后简称 SNS） 来感知TPM保障包信息通知。
## 订阅流程
1. 申请 “SNS开白” ，使用请提交 [工单](https://console.volcengine.com/workorder/create?step=2&SubProductID=P00001166) 申请，并同步申请对应的消息事件：
* ModelTPMNewFailed：TPM保障包新购失败告警
* ModelTPMScaleUpFailed：TPM保障包扩容失败告警
2. 在 **主题** 页面创建主题。
* 发布者选项指定账号：`2100444922`
* 服务选择：`ark`
3. 在 **云服务事件订阅** 页面创建事件订阅。Topic TRN选择刚刚创建的主题，事件选择`ModelTPMNewFailed`、`ModelTPMScaleUpFailed`。
4. 在**订阅**页面，订阅前面创建的主题，并配置可接收端地址
* 配置完订阅后，SNS 会向接收端发送对应的确认链接，需确认该链接来完成订阅，确认链接demo如下。需要回调下文中SubscribeURL
```JSON
{
"Type": "SubscriptionConfirmation",
"MessageId": "f11b9a8f-****",
"TopicTrn": "trn:sns:cn-beijing:2100000825:topic/test",
"Message": "You have chosen to subscribe to the topic trn:sns:cn-beijing:2100000825:topic/wyy_test. To confirm the subscription, visit the SubscribeURL included in this message.",
"Timestamp": "2025-01-14T07:18:59Z",
"SignatureVersion": "1",
"Signature": "MEUCIB3NsKw***=",
"SigningCertURL": "https://sns-public-cn-beijing.tos-cn-beijing.volces.com/certificates/cn-beijing-a31d91fc-0683-****.pem",
"SubscribeToken": "eyJhbGciOiJIUzI1Ni****",
"SubscribeURL": "https://sns.cn-beijing.volcengineapi.com?Action=ConfirmSubscription&Version=2023-01-01&Token=eyJhbGc***"
}
```
* 回调成功后可在 **订阅** 页面看到对应的订阅状态为：已确认，表示订阅已完成。
## 订阅信息内容格式
TPM保障包订阅失败时通知的内容。
**ModelTPMNewFailed**
TPM保障包新购失败告警
```JSON
{
"EventID": "tpmro-202502111****-****",
"EventName": "ModelTPMNewFailed",
"EventTime": "2025-02-11T19:41:36+08:00",
"AccountID": 2100000825,
"ModelTPMInfo": {
"EndpointID": "ep-2025021******-cn***",
"FoundationModelName": "doubao-lite-4k"
}
}
```
**ModelTPMScaleUpFailed**
TPM保障包扩容失败告警
```JSON
{
"EventID": "tpmro-202502111****-****",
"EventName": "ModelTPMScaleUpFailed",
"EventTime": "2025-02-11T19:41:36+08:00",
"AccountID": 2100000825,
"ModelTPMInfo": {
"EndpointID": "ep-20250******-cn***",
"FoundationModelName": "doubao-lite-4k"
}
}
```
# 调整数量/续费/退订/修改弹性规则
1. 访问 [在线推理](https://ark.volcengine.com/region:cn-beijing/endpoint)，切换到**自定义推理接入点**页签。
2. 单击目标 接入点 名称，进入 接入点 概览页。
3. 在算力保障区域，根据需要对TPM保障包进行调整数量、续费、退订。
4. 在算力保障区域，单击 **弹性详情**，可查看当前的弹性规则。单击 **调整弹性**，可对弹性规则进行修改。
> **注意**
>
> 未到期的TPM保障包退订会产生惩罚系数，无法 100%退费。
# 使用限制
* 支持通过 [Chat API](/docs/chat-api) 调用模型。
* 不支持[结构化输出(beta)](/docs/structured-output-beta)（ **response_format.type** 无法设置为 `json_object`、`json_schema` ）。
* 不支持视频输入。
* 不支持 [Context Create API](/docs/create-context-cache-api) 、 [Responses API](/docs/create-model-responses-api) 。
* 当接入点请求超过保障包额度时，自动切换为普通在线推理模式，以 **按Token付费** 模式收费。
* 模型请求的输入范围符合下方条件。如不符合，无法使用 TPM 保障包，请求返回的 **service_tier** 字段为`default`，即普通在线推理模式，不扣减保障包额度。
* Doubao 模型，输入长度 (0, 128k]。
* DeepSeek 模型，输入长度(0, 64k]。
# 购买说明
详细的购买、变配、计费规则请参见[TPM 保障包计费说明](/docs/tpm-guarantee-package-pricing)。
# 常见问题
参见[TPM保障包](/docs/modelark-faq#5e8ec656)。