byted-volcengine-finops

火山引擎账单 Skill

这个 Skill 用于通过火山引擎 Python SDK 查询费用中心账单数据，并围绕账期、分摊月、日期、实例、产品、账号、分账维度做汇总分析。

何时使用此 Skill

当用户要求：

• 分析火山引擎账单、成本和消费趋势的时候
• 查询账号维度账单总览信息的时候
• 查询产品维度成本分布的时候
• 核对账单明细、实例费用或账单类型的时候
• 查询分摊后成本、摊销成本或成本账单明细的时候
• 查询分账账单、分拆项费用或分摊结果的时候

主要功能

1. 账号账单总览查询

• 使用 ListBillOverviewByCategory 查询账号维度账单总览
• 适合先看整月整体账单金额和大盘趋势

2. 产品月度账单查询

• 使用 ListBillOverviewByProd 查询单产品、多产品、全量产品月度账单
• 支持分页获取完整产品列表
• 适合识别高成本产品和主要费用来源

3. 账单明细与分账查询

• 使用 ListBillDetail 查询账单明细
• 使用 ListAmortizedCostBillDetail 查询成本账单明细
• 使用 ListSplitBillDetail 查询分账账单
• 支持按账期、分摊月、日期、产品、账号、实例、分拆项筛选

4. 配置与调用方式

• 支持环境变量配置 AK/SK
• 支持 .env 文件配置
• 支持 Python 代码调用
• 支持通过 scripts/ 下的独立脚本直接调用
• 支持分页拉取与本地汇总分析
• 支持 JSON 结构化结果处理

处理逻辑

账单查询处理流程

1. 根据用户目标确定接口
   • 整体账单使用 ListBillOverviewByCategory
   • 产品月度账单使用 ListBillOverviewByProd
   • 明细核对使用 ListBillDetail
   • 成本明细使用 ListAmortizedCostBillDetail
   • 分账排查使用 ListSplitBillDetail
2. 根据时间要求确定账期与日期范围
   • 优先确定 BillPeriod
   • 成本账单优先确定 AmortizedMonth
   • 需要单日细查时补充 ExpenseDate
   • 成本账单按日细查时补充 AmortizedDay
   • 跨月查询需要拆成多个账期分别查询
3. 根据过滤条件组装 SDK 请求参数
   • 例如产品、账号、实例、账单类型、分拆项等
4. 如为分页接口则循环查询
   • 使用 Offset + Limit + NeedRecordNum 分页拉全量
   • 可使用 common.py 中的 fetch_all_pages 工具函数自动翻页
5. 对结果做汇总分析
   • 输出金额、排行、异常波动和待核对项

前置要求

需要安装火山引擎 Python SDK：

pip install --upgrade "volcengine-python-sdk>=5.0.30"

说明：

• 建议使用 5.x 最新版本
• 历史版本 4.0.1 ~ 4.0.42 存在 SDK 重试缺陷，尽量不要继续使用

配置方式

需要配置火山引擎的 Access Key 和 Secret Key。推荐使用以下两种方式之一：

方式 1：环境变量

export VOLCENGINE_AK="your-ak"
export VOLCENGINE_SK="your-sk"
export VOLCENGINE_REGION="cn-beijing"

方式 2：.env 文件

在 ~/.openclaw/workspace/.env 中配置：

VOLCENGINE_AK=your-ak
VOLCENGINE_SK=your-sk
VOLCENGINE_REGION=cn-beijing

账单参数说明

账单查询核心参数

• BillPeriod: 账务账期，格式为 YYYY-MM
• ExpenseDate: 账单日期，格式为 YYYY-MM-DD
• AmortizedMonth: 分摊月，格式为 YYYY-MM
• AmortizedDay: 分摊日，格式为 YYYY-MM-DD
• Offset: 分页偏移量
• Limit: 单页数量，范围 [1,300]
• NeedRecordNum: 是否返回总记录数，1 返回 Total，否则常为 -1
• IgnoreZero: 是否忽略折后价为 0 的数据，0 不忽略、1 忽略
• Product: 产品筛选条件。可选的产品 Code 请参考 references/product-code.md

关键参数枚举值

时间参数说明

• BillPeriod 是账单查询的核心时间参数，按月查询
• AmortizedMonth 是成本账单查询的核心时间参数，按月查询
• 如果不指定单日过滤，则默认按整月口径查询
• 若要查询单月中的某一天，可补充 ExpenseDate
• 若要查询单月中的某一天成本分摊，可补充 AmortizedDay
• 如果用户给出跨月日期范围，需要拆成多个 BillPeriod 分别查询后再汇总
• 如果用户给出跨月成本范围，需要拆成多个 AmortizedMonth 分别查询后再汇总

分页参数说明

• ListBillOverviewByProd
• ListBillDetail
• ListAmortizedCostBillDetail
• ListSplitBillDetail

以上四个接口都应按分页处理。

推荐策略：

• Offset 从 0 开始
• Limit 优先取 100 或 300
• NeedRecordNum 设为 1
• 每次查询完成后按 Offset += Limit 继续拉取
• 如果返回数量小于 Limit，或累计条数覆盖 Total，则结束分页
• 可直接使用 common.py 中的 fetch_all_pages 工具函数自动翻页

fetch_all_pages 使用示例：

from common import build_billing_api, fetch_all_pages
import volcenginesdkbilling

api = build_billing_api()

# 自动拉取全量账单明细
rows = fetch_all_pages(
    api_instance=api,
    request_cls=volcenginesdkbilling.ListBillDetailRequest,
    list_method_name="list_bill_detail",
    raw_kwargs={"BillPeriod": "2025-05"},
    limit=100,
)
print(f"共拉取 {len(rows)} 条记录")

返回字段速查

所有接口的返回结构都是 Result.List + Result.Total（分页接口），完整字段定义见 references/billing-api-notes.md。以下是各接口最常用的业务字段：

通用金额字段（ListBillOverviewByCategory / ListBillOverviewByProd / ListBillDetail）

通用维度字段（ListBillDetail / ListSplitBillDetail / ListAmortizedCostBillDetail）

ListSplitBillDetail 特有字段

ListAmortizedCostBillDetail 特有字段

核心接口说明

每个接口的完整请求参数和返回参数定义见 references/billing-api-notes.md，以下为最简参数模板。

1. ListBillOverviewByCategory

查询账单总览账号汇总信息。

适用场景：

• 查看整月总账
• 先看整体账单，再决定是否下钻

SDK 请求参数模板：

# 账号账单总览查询参数
category_request = {
    "BillPeriod": "2025-05"
}

2. ListBillOverviewByProd

分页查询产品月度账单。

适用场景：

• 看产品成本排行（单产品、多产品、全量产品月度账单）
• 识别高成本产品

SDK 请求参数模板：

# 产品账单总览查询参数
prod_request = {
    "BillPeriod": "2025-05",
    "Limit": 100,
}

3. ListBillDetail

分页查询账单明细。

适用场景：

• 核对某个产品或实例的费用组成
• 查某月、某天、某类账单或某个实例的费用明细

SDK 请求参数模板：

# 账单明细查询参数
detail_request = {
    "BillPeriod": "2025-05",
    "Limit": 100,
}

4. ListSplitBillDetail

分页查询分账账单。

适用场景：

• 核对分拆项费用
• 排查项目、标签或资源粒度的分账结果

SDK 请求参数模板：

# 分账账单查询参数
split_request = {
    "BillPeriod": "2025-05",
    "Limit": 100,
}

5. ListAmortizedCostBillDetail

分页查询成本账单明细。

适用场景：

• 查看分摊后成本
• 核对摊销口径下的产品、实例和账单类型费用

SDK 请求参数模板：

# 成本账单明细查询参数
amortized_detail_request = {
    "AmortizedMonth": "2025-05",
    "Limit": 100,
}

说明：

• 该接口的核心时间字段是 AmortizedMonth / AmortizedDay，不是普通账单接口里的 BillPeriod / ExpenseDate
• BillPeriod 在这个接口里是可选过滤条件，不能替代 AmortizedMonth

脚本目录

Skill 已将 5 个接口的调用示例提取为独立脚本，位于 scripts/ 目录：

• scripts/list_bill_overview_by_category.py
• scripts/list_bill_overview_by_prod.py
• scripts/list_bill_detail.py
• scripts/list_amortized_cost_bill_detail.py
• scripts/list_split_bill_detail.py
• scripts/common.py

说明：

• common.py 负责加载 .env、初始化 Billing SDK、统一输出 JSON，以及提供 fetch_all_pages 翻页工具函数
• 5 个接口脚本都支持命令行参数调用，参数名默认与接口文档中的请求参数名一致
• 数组类型参数使用"重复传参"的方式输入，例如重复传 --Product
• 分页脚本会在本地校验月份格式、日期归属月份、Limit 范围和 SplitDimension 的 JSON 格式
• 所有可选参数按需传入，不传则不出现在请求体中

请求调用示例

账号总览

python3 scripts/list_bill_overview_by_category.py \
  --BillPeriod 2025-05

产品总览

# 最小调用
python3 scripts/list_bill_overview_by_prod.py \
  --BillPeriod 2025-05 \
  --Limit 100

# 按产品筛选
python3 scripts/list_bill_overview_by_prod.py \
  --BillPeriod 2025-05 \
  --Limit 100 \
  --Product ECS --Product VKE

账单明细

# 最小调用
python3 scripts/list_bill_detail.py \
  --BillPeriod 2025-05 \
  --Limit 100

# 按天 + 按产品 + 按实例筛选
python3 scripts/list_bill_detail.py \
  --BillPeriod 2025-05 \
  --Limit 100 \
  --ExpenseDate 2025-05-15 \
  --Product ECS \
  --InstanceNo i-xxxxxxxx

分账明细

# 最小调用
python3 scripts/list_split_bill_detail.py \
  --BillPeriod 2025-05 \
  --Limit 100

# 按标签维度分账
python3 scripts/list_split_bill_detail.py \
  --BillPeriod 2025-05 \
  --Limit 100 \
  --SplitDimension '{"TOS":"project"}'

成本账单明细

# 最小调用
python3 scripts/list_amortized_cost_bill_detail.py \
  --AmortizedMonth 2025-05 \
  --Limit 100

# 按天 + 按分摊类型筛选
python3 scripts/list_amortized_cost_bill_detail.py \
  --AmortizedMonth 2025-05 \
  --Limit 100 \
  --AmortizedDay 2025-05-15 \
  --AmortizedType 4

参考资料

• 本地准备说明：references/install.md
• 接口请求参数和响应参数参考文档：references/billing-api-notes.md
• 产品 Code 映射表：references/product-code.md
• 官方 Python SDK 安装包：volcengine-python-sdk