gemini-token-optimization

Gemini 令牌优化

🚨 必须：先调用 gemini-cli-docs

停止——在提供任何有关 Gemini 令牌用量的回复之前：

1. 调用 gemini-cli-docs skill
2. 查询 具体的令牌或定价主题
3. 仅依据 已加载的官方文档作答

概述

用于优化委托给 Gemini CLI 的成本和令牌用量的 skill。对于高效批量操作和注重成本的工作流至关重要。

何时使用此 Skill

关键词： 令牌用量、成本优化、Gemini 成本、模型选择、Flash 与 Pro、缓存、批量查询、减少令牌

在以下情况下使用此 skill：

• 规划 Gemini 批量操作
• 优化大规模分析的成本
• 在 Flash 和 Pro 模型之间进行选择
• 了解令牌缓存的好处
• 跨会话跟踪用量

令牌缓存

Gemini CLI 会自动缓存上下文，以便重复使用先前处理过的内容来降低成本。

可用性

认证方法	是否支持缓存
API key（Gemini API）	是
Vertex AI	是
OAuth（个人版/企业版）	否

工作原理

• 系统指令和重复上下文会被缓存
• 缓存的令牌不计入计费
• 可通过 /stats 命令或 JSON 输出查看节省情况

提高缓存命中率

1. 使用一致的系统提示词——相同的前缀可提高缓存复用率
2. 批量处理相似查询——将相关分析放在一起
3. 重复使用上下文文件——保持文件和顺序一致

监控缓存用量

result=$(gemini "query" --output-format json)
total=$(echo "$result" | jq '.stats.models | to_entries | map(.value.tokens.total) | add // 0')
cached=$(echo "$result" | jq '.stats.models | to_entries | map(.value.tokens.cached) | add // 0')
billable=$((total - cached))
savings=$((cached * 100 / total))

echo "Total: $total tokens"
echo "Cached: $cached tokens ($savings% savings)"
echo "Billable: $billable tokens"

模型选择

模型比较

模型	上下文窗口	速度	成本	质量
gemini-2.5-flash	大	快	较低	良好
gemini-2.5-pro	很大	较慢	较高	最佳

选择标准

在以下情况下使用 Flash（-m gemini-2.5-flash）：

• 处理大型文件（批量分析）
• 执行简单的提取任务
• 成本是首要考虑因素
• 速度至关重要
• 任务较为简单

在以下情况下使用 Pro（-m gemini-2.5-pro）：

• 需要复杂推理
• 质量至关重要
• 需要细致入微的分析
• 任务需要深入理解
• 上下文超过 1M 个令牌

模型选择示例

# Bulk file analysis - use Flash
for file in src/*.ts; do
  gemini "List all exports" -m gemini-2.5-flash --output-format json < "$file"
done

# Security audit - use Pro for quality
gemini "Deep security analysis" -m gemini-2.5-pro --output-format json < critical-auth.ts

# Cost tracking with model info
result=$(gemini "query" --output-format json)
model=$(echo "$result" | jq -r '.stats.models | keys[0]')
tokens=$(echo "$result" | jq '.stats.models | to_entries[0].value.tokens.total')
echo "Used $model: $tokens tokens"

批处理策略

为什么要批处理？

• 减少 API 开销
• 提高缓存命中率
• 提供一致的上下文

批处理模式

模式 1：拼接文件

# Instead of N separate calls
# Do one call with all files
cat src/*.ts | gemini "Analyze all TypeScript files for patterns" --output-format json

模式 2：批量处理提示词

# Combine related questions
gemini "Answer these questions about the codebase:
1. What is the main architecture pattern?
2. How is authentication handled?
3. What database is used?" --output-format json

模式 3：分阶段分析

# First pass: Quick overview with Flash
overview=$(cat src/*.ts | gemini "List all modules" -m gemini-2.5-flash --output-format json)

# Second pass: Deep dive critical areas with Pro
echo "$overview" | jq -r '.response' | grep "auth\|security" | while read module; do
  gemini "Deep analysis of $module" -m gemini-2.5-pro --output-format json
done

成本跟踪

按查询跟踪

result=$(gemini "query" --output-format json)

# Extract all cost-relevant stats
total_tokens=$(echo "$result" | jq '.stats.models | to_entries | map(.value.tokens.total) | add // 0')
cached_tokens=$(echo "$result" | jq '.stats.models | to_entries | map(.value.tokens.cached) | add // 0')
models_used=$(echo "$result" | jq -r '.stats.models | keys | join(", ")')
tool_calls=$(echo "$result" | jq '.stats.tools.totalCalls // 0')
latency=$(echo "$result" | jq '.stats.models | to_entries | map(.value.api.totalLatencyMs) | add // 0')

echo "$(date): tokens=$total_tokens cached=$cached_tokens models=$models_used tools=$tool_calls latency=${latency}ms" >> usage.log

按会话跟踪

# Track cumulative usage across a session
total_session_tokens=0
total_session_cached=0
total_session_calls=0

track_usage() {
  local result="$1"
  local tokens=$(echo "$result" | jq '.stats.models | to_entries | map(.value.tokens.total) | add // 0')
  local cached=$(echo "$result" | jq '.stats.models | to_entries | map(.value.tokens.cached) | add // 0')

  total_session_tokens=$((total_session_tokens + tokens))
  total_session_cached=$((total_session_cached + cached))
  total_session_calls=$((total_session_calls + 1))
}

# Use in workflow
result=$(gemini "query 1" --output-format json)
track_usage "$result"

result=$(gemini "query 2" --output-format json)
track_usage "$result"

echo "Session total: $total_session_tokens tokens ($total_session_cached cached) in $total_session_calls calls"

优化清单

大规模操作前

• 选择合适的模型（Flash 或 Pro）
• 检查是否支持缓存（API key 或 Vertex）
• 规划批处理策略
• 设置用量跟踪

操作期间

• 监控缓存命中率
• 跟踪每次查询的成本
• 如果质量不足，调整模型
• 批量处理相似查询

操作后

• 检查总用量
• 计算实际成本
• 找出优化机会
• 记录经验

快速参考

节省成本的命令

# Use Flash for bulk
gemini "query" -m gemini-2.5-flash --output-format json

# Check cache effectiveness
gemini "query" --output-format json | jq '{total: .stats.models | to_entries | map(.value.tokens.total) | add, cached: .stats.models | to_entries | map(.value.tokens.cached) | add}'

# Minimal output (fewer output tokens)
gemini "Answer in one sentence: {question}" --output-format json

成本估算

令牌数量粗略估算：

• 1 个令牌约等于 4 个字符（英文）
• 1 页代码约为 500-1000 个令牌
• 典型源文件约为 200-2000 个令牌

关键词注册表（委托给 gemini-cli-docs）

主题	查询关键词
缓存	token caching、cached tokens、/stats
模型选择	model routing、flash vs pro、-m flag
成本	quota pricing、token usage、billing
输出控制	output format、json output

测试场景

场景 1：检查令牌用量

查询：“如何查看 Gemini 使用了多少令牌？” 预期行为：

• 在“令牌用量”或“Gemini 成本”触发时激活 Skill
• 提供提取 JSON 统计信息的模式 成功标准：用户收到用于提取令牌数量的 jq 命令

场景 2：降低成本

查询：“如何降低 Gemini CLI 批量分析的成本？” 预期行为：

• 在“成本优化”或“减少 token”时激活技能
• 推荐使用 Flash 模型并进行批处理 成功标准：用户获得成本优化策略

场景 3：模型选择

查询：“这项任务应该使用 Flash 还是 Pro？” 预期行为：

• 在“Flash 与 Pro 的对比”或“模型选择”时激活技能
• 提供决策标准表格 成功标准：用户获得模型对比和建议

参考资料

查询 gemini-cli-docs，获取以下主题的官方文档：

• “token 缓存”
• “模型选择”
• “配额与定价”

版本历史

• v1.1.0（2025-12-01）：新增测试场景部分
• v1.0.0（2025-11-25）：首次发布