huawei-cloud-maas-tokens-usage

华为云 MaaS Token 使用情况监控技能

概述

通过 ShowStatistics API 查询华为云 MaaS（模型即服务）使用情况统计数据，包括总 Token 数、提示词 Token 数、补全 Token 数、请求总数和错误总数。支持查询过去 7 天、14 天、30 天或自定义时间范围。默认查询类型为 MaaS 预置服务。AK/SK 绝不会离开 Python 进程内存。

工具分离原则：

• Python SDK 签名 — 通过 huaweicloudsdkcore.signer.Signer 使用 AK/SK 签名（凭证绝不会离开 Python 进程内存，也绝不会出现在 ps -ef 中）
• Python requests — 向 MaaS ShowStatistics 端点发送 HTTP POST（仅从 Python 进程发送已签名的请求）
• 不使用 hcloud CLI — KooCLI 不支持 MaaS ShowStatistics；使用纯 Python REST 和 SDK 签名

安全架构：

• Python 脚本从环境变量（HW_ACCESS_KEY / HW_SECRET_KEY）或凭证文件读取 AK/SK（绝不要求用户在对话中输入、绝不通过 CLI 参数传递，也绝不导出到 Shell）
• 临时凭证还会包含 HW_SECURITY_TOKEN（由 SDK 签名器通过 X-Security-Token 标头传递）
• 签名由 Python 进程内的 huaweicloudsdkcore.Signer 执行；已签名的 Authorization 标头仅发送到 MaaS 端点
• AK/SK 绝不打印、绝不记录日志、绝不出现在 ps -ef 中，也绝不出现在对话中
• 不依赖 KMS、不依赖 hcloud CLI，也不依赖第三方技能

⛔ 禁止的操作（安全限制）

无论用户提出什么要求，本技能都严格禁止以下操作：

禁止的操作	原因
❌ 要求用户在对话中直接提供 AK/SK	凭证绝不能出现在对话中
❌ 接受用户在对话中直接提供的 AK/SK	凭证绝不能出现在对话中
❌ 在脚本或命令行参数中硬编码 AK/SK	存在凭证泄露风险
❌ 使用 hcloud configure set 传递明文 AK/SK 值	凭证会被记录在命令历史中
❌ 在任何输出中打印或记录 AK/SK 值	凭证只能存在于 Python 进程内存中
❌ 通过脚本将 AK/SK 导出到 Shell 变量或标准输出	凭证必须留在 Python 进程中；仅打印统计结果
❌ 手动实现 SDK-HMAC-SHA256 签名	容易出错；必须使用 huaweicloudsdkcore.Signer
❌ 对 Custom Endpoint 使用 service_type=3	API 仅支持 [1, 2, 4]；否则会返回 400 错误
❌ 将时区硬编码为 CST 或 Asia/Shanghai	必须自动检测操作系统的本地时区
❌ 不分段查询超过 30 天的时间范围	API 仅保留 30 天的数据；脚本必须自动分段
❌ 使用 cn-southwest-2 以外的区域	MaaS ShowStatistics 仅支持西南—贵阳一
❌ 不使用 maas_rest_usage_stats.py，而是编写新的查询脚本	必须使用 scripts/ 目录中的脚本

如果用户要求执行禁止的操作，必须拒绝并说明安全限制。

🚫 不支持的操作（能力边界）

此技能仅支持 ShowStatistics 聚合统计查询。MaaS 监控 API 系列包含 10 个 API；其余 9 个不在此技能的能力范围内，且尚未实现。

不支持的 API	用途	未涵盖的原因
ListServiceStatistics	列出各服务的统计数据	此技能侧重于令牌使用量汇总，而非各服务的细分数据
ShowDetailChart	显示详细图表数据	此技能返回汇总表，而非图表数据序列
ListErrors	列出错误详情	此技能仅报告错误数/错误率，不提供错误详情记录
ListServices	列出服务	此技能查询统计数据，而非服务清单
ListSourceIps	列出源 IP	此技能不跟踪调用方 IP 分布
GetServiceDetailMetricData	获取服务详细指标	此技能提供聚合指标，而非各服务的详细数据
ListVersionStatistics	列出版本统计数据	此技能不按模型版本进行细分
GetGenerationSupportedMetrics	获取支持的指标	此技能使用 ShowStatistics 响应中的固定指标集
ShowErrorCodeChart	显示错误代码图表	此技能报告错误率，而非错误代码分布

如果用户请求上述任一 API 或其底层能力（各服务细分数据、错误详情、图表数据、源 IP 列表、版本统计数据、错误代码分布等），你必须拒绝并说明：此技能仅支持 ShowStatistics 聚合统计查询（总令牌数/提示词令牌数/补全令牌数、请求数、错误数、错误率）。

架构

Huawei Cloud MaaS Tokens Usage Monitoring
├── Task 1: Query MaaS Tokens Usage Statistics (via MaaS ShowStatistics API)
│   ├── 1a. Load credentials    (env vars or --credentials-file, in Python memory only)
│   ├── 1b. Resolve time range  (last 7/14/30 days, this month, or custom YYYY-MM-DD)
│   ├── 1c. Auto-segment        (split ranges > 30 days, aggregate results)
│   ├── 1d. SDK sign request    (huaweicloudsdkcore.Signer, AK/SK in process memory)
│   ├── 1e. POST ShowStatistics (modelarts.{region}.myhuaweicloud.com)
│   ├── 1f. Aggregate & convert (token unit: thousand → M tokens)
│   └── 1g. Print table         (Total/Prompt/Completion Tokens, Requests, Errors, Error Rate)
└── Task 2: Verify & Report     (compare with console, check error rate)

前置条件

前置条件检查 1/3：需要 Python 3.8+ 和 huaweicloudsdkcore

MaaS ShowStatistics 查询脚本使用 Python，以便仅在进程内存中保存 AK/SK。 安装所需的软件包：

# 当系统时区为 UTC+8 时自动使用中国镜像（中国地区速度更快；通过 Python 自动检测）
PIP_INDEX=$(python3 -c "import time;print('-i https://mirrors.huaweicloud.com/repository/pypi/simple' if -(time.timezone)//3600==8 else '')")
pip install $PIP_INDEX huaweicloudsdkcore requests

验证 SDK 是否安装：

python3 --version                          # 预期：>= 3.8
python3 -c "import huaweicloudsdkcore; print('SDK OK')"
python3 -c "import requests; print('requests OK')"

前置条件检查 2/3：Python SDK 凭据的环境变量（优先级最高）

查询脚本（maas_rest_usage_stats.py）会从环境变量或凭据文件读取凭据。运行脚本前必须设置以下环境变量（除非使用 --credentials-file）：

变量	必需	说明
HW_ACCESS_KEY	是	华为云访问密钥 ID（AK）
HW_SECRET_KEY	是	华为云访问密钥（SK）
HW_SECURITY_TOKEN	否	临时安全令牌（仅用于临时 AK/SK）

# Linux — 验证是否已设置 HW_ACCESS_KEY / HW_SECRET_KEY（不会打印变量值）
python3 -c 'import os,sys;ak=os.environ.get("HW_ACCESS_KEY","");sk=os.environ.get("HW_SECRET_KEY","");ok=bool(ak) and bool(sk);print("AK/SK configured OK" if ok else "ERROR: HW_ACCESS_KEY/HW_SECRET_KEY not set");sys.exit(0 if ok else 1)'
# Windows（cmd / PowerShell）
python -c "import os,sys;ak=os.environ.get('HW_ACCESS_KEY','');sk=os.environ.get('HW_SECRET_KEY','');ok=bool(ak) and bool(sk);print('AK/SK configured OK' if ok else 'ERROR: HW_ACCESS_KEY/HW_SECRET_KEY not set');sys.exit(0 if ok else 1)"

如果验证结果为 ERROR（未设置变量），请进行配置：

• Linux：将 export HW_ACCESS_KEY=... / export HW_SECRET_KEY=... 添加到 shell 配置文件（~/.bashrc、~/.zshrc）或密钥管理器中，然后执行 source 加载配置文件。
• Windows：通过图形界面设置系统环境变量（系统属性 → 高级 → 环境变量 → 系统变量 → 新建）。请参阅 references/cli-installation-guide.md 中的“Windows GUI Setup”，了解分步说明。避免使用 setx（它会将凭据记录在命令历史中）。

⚠️ 切勿在对话中设置这些变量，也不要将其硬编码到脚本中。 设置后，重启终端/Python 进程，并重新运行上述验证。

前置条件检查 3/3：MaaS 服务区域限制

• 区域：cn-southwest-2（Southwest-Guiyang-1）——MaaS ShowStatistics API 唯一支持的区域
• API 数据保留期：30 天
• 速率限制：总请求数 ≤ 1000/min，每位用户 ≤ 200/min

---

身份验证

安全规则（必须遵守）：

• 禁止读取、回显或打印 AK/SK 值
• 禁止要求用户直接在对话中输入 AK/SK
• 禁止使用 hcloud configure set 传递明文凭据值
• 禁止接受用户直接在对话中提供的 AK/SK
• 仅允许从环境变量或凭据文件中读取凭据

⚠️ 重要：处理用户提供的凭据

如果用户试图直接提供 AK/SK（例如：“我的 AK 是 xxx，SK 是 yyy”）：

1. 立即停止——不要执行任何命令
2. 礼貌拒绝，并返回以下消息：

   为了保障账户安全，请勿直接在对话中提供华为云访问密钥 ID 和访问密钥 Secret。
   
   请使用以下安全方法之一配置凭据：
   
   方法 1：环境变量（永久 AK/SK）
       export HW_ACCESS_KEY=<your-access-key-id>
       export HW_SECRET_KEY=<your-access-key-secret>
   
   方法 2：环境变量（临时 AK/SK + 安全令牌）
       export HW_ACCESS_KEY=<your-temp-access-key-id>
       export HW_SECRET_KEY=<your-temp-access-key-secret>
       export HW_SECURITY_TOKEN=<your-security-token>
   
   方法 3：凭据文件
       创建一个文件（例如 ~/aksk.txt），第 1 行填写 AK，第 2 行填写 SK，若使用临时凭据，则第 3 行填写安全令牌。
       然后使用：--credentials-file ~/aksk.txt
   
   配置完成后，请重试您的请求。
   

3. 不要继续执行任何华为云操作，直到凭据配置完成

---

IAM 权限策略

确保 IAM 用户具有所需权限（ModelArts 监控 + IAM 读取权限，且仅限于 MaaS 查询工作流）。完整权限表和推荐的 IAM 策略 JSON，请参阅 references/iam-policies.md。

权限边界：

• 范围限制：仅查询 MaaS 统计数据（只读）。绝不修改或删除任何 MaaS 服务、端点或配置。
• 必须停止的情况：凭据缺失或无效、用户拒绝任何确认、API 返回 403/401，或时间范围超过 30 天且分段失败。
• 禁止的操作：修改 MaaS 服务、删除 API 密钥、更改 IAM 策略、访问 MaaS 查询工作流以外的资源、运行此技能中未记录的命令。

---

核心工作流

任务 1：查询 MaaS Token 使用统计

通过 ShowStatistics API 查询 MaaS 使用统计。数据与华为云控制台一致。

⚠️ 工具分离：Python SDK 签名 + Python requests

• Python SDK（huaweicloudsdkcore.Signer）：使用 AK/SK 对请求签名。凭据不会离开 Python 进程内存。
• Python requests：向 MaaS 端点发送已签名的 HTTP POST。不使用 CLI、shell 变量，也不会通过 ps -ef 泄露信息。

📄 详细步骤 → references/task-query-tokens-usage.md

子任务：

1. 1a. 加载凭据 — 从环境变量读取 HW_ACCESS_KEY / HW_SECRET_KEY / HW_SECURITY_TOKEN，或从 --credentials-file 读取（支持每行一个、逗号分隔、KEY=VALUE 格式）
2. 1b. 确定时间范围 — 解析 --from / --to（YYYY-MM-DD），或将用户表达式（“最近 7 天”/“最近 14 天”/“最近 30 天”/“本月”）映射为滚动或日历时间窗口
3. 1c. 自动分段 — 如果时间范围超过 30 天，则拆分为多个不超过 30 天的时间段并汇总结果
4. 1d. 使用 SDK 对请求签名 — Signer(_Creds(ak, sk)).sign(sdk_request) — AK/SK 仅存于 Python 进程内存中
5. 1e. POST ShowStatistics — requests.post("https://modelarts.{region}.myhuaweicloud.com/v1/{project_id}/maas/monitoring/show-statistics", headers=signed_headers, data=body_bytes)
6. 1f. 汇总并转换 — 汇总各时间段的结果；转换 Token 单位（千 → M Token，实际值 = 数值 × 1000）
7. 1g. 打印表格 — 输出 Total Tokens / Prompt Tokens / Completion Tokens / Total Requests / Total Errors / Error Rate + Period

任务 2：验证并报告

将 API 结果与华为云控制台进行比较，并报告错误率。

📄 验收标准 → references/acceptance-criteria.md

⚠️ 存在细微差异属于正常情况。 由于时间边界略有不同，API 与控制台的数据可能相差 < 0.1%。数据可靠。

---

核心命令

Python 脚本（SDK 签名 + requests — AK/SK 不会出现在 ps -ef 中）

命令	说明
pip install huaweicloudsdkcore requests	安装 Python SDK 签名库 + HTTP 客户端（UTC+8 环境下，添加 -i https://mirrors.huaweicloud.com/repository/pypi/simple）
python3 scripts/maas_rest_usage_stats.py --from 2026-05-08 --to 2026-05-21	查询指定日期范围内的预置服务使用情况（默认 --service-type 2）
python3 scripts/maas_rest_usage_stats.py --from 2026-05-08 --to 2026-05-21 --service-type 1	查询我的服务使用情况
python3 scripts/maas_rest_usage_stats.py --from 2026-05-08 --to 2026-05-21 --service-type 4	查询自定义端点使用情况
python3 scripts/maas_rest_usage_stats.py --from 2026-05-08 --to 2026-05-21 --infer-type batch	查询批量推理使用情况（默认 real_time）
python3 scripts/maas_rest_usage_stats.py --from 2026-05-08 --to 2026-05-21 --api-keys key1 key2	按 API Key 列表筛选
python3 scripts/maas_rest_usage_stats.py --from 2026-05-08 --to 2026-05-21 --credentials-file /path/to/aksk.txt	使用凭据文件而非环境变量
python3 scripts/maas_rest_usage_stats.py --from 2026-05-08 --to 2026-05-21 --raw	显示原始 API 响应（用于调试）

⚠️ 核心命令限制：

• MaaS 查询：必须使用 scripts/maas_rest_usage_stats.py — AK/SK 不会出现在 ps -ef 中
• 凭据：必须使用环境变量或 --credentials-file — 不得硬编码，也不得通过 CLI 参数传递
• --service-type：必须为 1、2 或 4 — 不得使用 3（API 会返回 400）
• --region：必须为 cn-southwest-2（默认值）— 唯一支持的区域
• 时间范围：必须与用户表达式完全一致 — “最近 7 天” ≠ “本月”

---

参数确认

执行任何任务前，必须与用户确认以下参数。禁止猜测。

参数	必填/可选	说明	默认值
时间范围	必填	--from / --to（YYYY-MM-DD），或用户表达（“过去 7 天”“过去 14 天”“过去 30 天”“本月”）	过去 7 天
服务类型	可选	--service-type：1=我的服务，2=预置服务，4=自定义端点	2（预置服务）
推理类型	可选	--infer-type：real_time（在线）或 batch	real_time
区域	可选	华为云区域（仅支持 cn-southwest-2）	cn-southwest-2
API 密钥筛选条件	可选	使用 --api-keys 列表筛选指定密钥	所有密钥
凭证文件	可选	--credentials-file 路径（可替代环境变量）	-
原始响应	可选	使用 --raw 标志显示原始 API 响应	关闭

注意：无需提供 AK/SK 参数。Python 脚本从环境变量或凭证文件中读取凭证。AK/SK 绝不会从 Python 进程导出。

---

脚本工具

脚本	说明
maas_rest_usage_stats.py	MaaS ShowStatistics API 查询脚本（SDK 签名 + requests，AK/SK 绝不会出现在 ps -ef 中）。自动分段处理超过 30 天的范围，自动检测操作系统本地时区，支持永久/临时 AK/SK + 凭证文件。用法请参阅上文的核心命令。

⚠️ 脚本使用规则：

• 必须使用现有脚本；不得编写新的查询脚本替代
• 不得将脚本内部逻辑拆分为单独的 curl/HTTP 命令
• 不得手动实现 SDK-HMAC-SHA256 签名 — 必须使用 huaweicloudsdkcore.Signer

---

验证方法

详情请参阅 references/verification-method.md。常见问题及解决方案请参阅 references/troubleshooting.md。

快速验证（永久 AK/SK）：

python3 -c 'import os,sys;ak=os.environ.get("HW_ACCESS_KEY","");sk=os.environ.get("HW_SECRET_KEY","");ok=bool(ak) and bool(sk);print("AK/SK configured OK" if ok else "ERROR: HW_ACCESS_KEY/HW_SECRET_KEY not set");sys.exit(0 if ok else 1)'
python3 scripts/maas_rest_usage_stats.py --from 2026-05-08 --to 2026-05-21

快速验证（临时 AK/SK + Security Token）：

python3 -c 'import os,sys;ak=os.environ.get("HW_ACCESS_KEY","");sk=os.environ.get("HW_SECRET_KEY","");st=os.environ.get("HW_SECURITY_TOKEN","");ok=bool(ak) and bool(sk) and bool(st);print("Temp AK/SK + Token configured OK" if ok else "ERROR: HW_ACCESS_KEY/HW_SECRET_KEY/HW_SECURITY_TOKEN not set");sys.exit(0 if ok else 1)'
python3 scripts/maas_rest_usage_stats.py --from 2026-05-08 --to 2026-05-21

**⚠️ 凭证提醒：**Python 脚本从环境变量或凭证文件中读取 AK/SK。如需配置凭证，请参阅 references/cli-installation-guide.md。

---

安全设计

安全架构确保 AK/SK 仅存在于 Python 进程内存中 — 绝不会出现在 ps -ef、Shell 变量、环境变量（只读访问）或对话中。工具分离：使用 Python SDK 签名进行 AK/SK 身份验证，使用 Python requests 向 MaaS 端点发送 HTTP POST。凭证绝不会被打印、记录或导出。临时凭证通过 SDK 签名器将 HW_SECURITY_TOKEN 添加为 X-Security-Token 请求头。

📄 完整详情（工具分离表、凭证泄露风险消除、凭证生命周期）→ references/security-design.md

---

参考资料

文档	描述
cli-installation-guide.md	前置条件 + Python SDK + 凭证配置 + Windows GUI 环境变量设置
task-query-tokens-usage.md	任务 1：查询令牌使用统计的详细步骤
related-apis.md	MaaS ShowStatistics API 和参数详情
maas-metrics.md	MaaS 监控指标参考
iam-policies.md	所需的 IAM 权限
verification-method.md	查询结果验证方法
acceptance-criteria.md	正确/错误模式对比
troubleshooting.md	常见查询问题和解决方案
security-design.md	安全设计：工具隔离、凭证生命周期
maas_rest_usage_stats.py	ShowStatistics API 使用统计脚本（AK/SK 不会出现在 ps -ef 中）