Token Tamer — AI API 成本控制工具

使用此技能追踪 AI API 调用成本、强制执行支出预算，并获取优化建议。支持所有主流提供商：OpenAI、Anthropic、Gemini、Ollama 或自定义后端。

适用场景

当用户提出以下问题时，可调用该技能：

• “我当前在 API 调用上花了多少钱？”
• 设置每日 / 每周 / 每月预算上限
• 按模型或提供商维度查看成本明细
• 识别低效或浪费的 API 使用模式
• 当支出接近预算上限时接收告警

初始化配置

1. 将 config_example.py 复制为 token_config.py
2. 设置预算限额及各模型的单价
3. 配置用量数据存储文件路径

# token_config.py
USAGE_FILE = "./token_usage.json"
BUDGETS = {
    'daily': 10.00,
    'weekly': 50.00,
    'monthly': 150.00,
}
ALERT_THRESHOLDS = {
    'warning': 80,   # 预算使用率达 80% 时触发告警
    'critical': 95,  # 预算使用率达 95% 时触发告警
}

记录 API 调用用量

每次 API 请求后调用该方法，以追踪本次调用成本：

import token_config as config
from token_tamer import TokenTamer

tamer = TokenTamer(config)

# 记录一次调用 — 返回 (cost, status)
cost, status = tamer.log_usage(
    provider='anthropic',
    model='claude-sonnet-4-5',
    input_tokens=1500,
    output_tokens=800,
    task='summarize',       # 可选
    session='sess_001'      # 可选
)

if status == 'KILL':
    raise Exception("熔断开关已激活 — 日预算已超限")

查询预算状态

status = tamer.get_status()
# 返回结果示例：
# {
#   'daily':   { 'cost': 2.40, 'budget': 10.00, 'status': 'OK', 'message': None },
#   'weekly':  { 'cost': 8.10, 'budget': 50.00, 'status': 'OK', 'message': None },
#   'monthly': { 'cost': 8.10, 'budget': 150.00, 'status': 'OK', 'message': None },
#   'kill_switch': False
# }

if status['daily']['status'] == 'CRITICAL':
    print("日预算即将耗尽 — 建议切换至更低成本模型")

调用前预算检查

# 在发起高成本调用前进行检查（返回 True 表示允许，False 表示阻断）
if not tamer.check_before_call(estimated_cost=0.10):
    raise Exception("熔断开关已激活 — API 调用已被阻止")

成本报告

import token_config as config
from token_reports import ReportGenerator

reporter = ReportGenerator(config)

# 生成日报
report = reporter.generate_daily_report()
reporter.print_report(report)

# 生成周报
report = reporter.generate_weekly_report()
reporter.print_report(report)

# 按提供商维度拆分报告
report = reporter.generate_by_provider_report()
reporter.print_report(report)

# 按模型维度拆分报告
report = reporter.generate_by_model_report()
reporter.print_report(report)

# 按任务类型维度拆分报告
report = reporter.generate_by_task_report()
reporter.print_report(report)

浪费检测与优化建议

import token_config as config
from token_optimizer import WasteDetector, Optimizer

# 检测过去 7 天内的浪费行为
detector = WasteDetector(config)
waste = detector.detect_all(days=7)

# 获取优化建议
optimizer = Optimizer(config)
recommendations = optimizer.generate_recommendations(days=7)

命令行（CLI）使用方式

# 查看当前支出状态
python token_tamer.py --status

# 通过 CLI 记录一次调用
python token_tamer.py --log --provider openai --model gpt-4o 
    --input-tokens 1500 --output-tokens 300 --task "code_generation"

# 检查是否允许继续发起 API 调用（退出码 0 = 允许，1 = 阻断）
python token_tamer.py --check

# 生成日报
python token_reports.py --daily

# 检测浪费行为（过去 7 天）
python token_optimizer.py --detect-waste --days 7

# 获取优化建议
python token_optimizer.py --recommendations --days 7

完整 API 参考、模型定价配置说明及高级用法，请参阅 README.md。