使用 Grafana 从零构建 AI API 使用仪表板：新手完整图文教程（2024版）

我第一次做 AI 项目成本分析时，用的是最笨的方法——每周手动导出 Excel 计算 token 消耗。那时候 API 调用量小还好，后来项目上了生产环境，每天几万次请求，我终于意识到必须上一个实时监控仪表板。经过三天折腾，我用 Grafana + Prometheus 搭建了一套完整的 AI API 可视化方案，今天手把手教给你。

本教程完全面向零基础，我假设你连 API 是什么都不清楚。每一步都有详细说明，跟着做一定能成功。

一、为什么 AI 开发者需要监控仪表板

在我刚开始接入 AI API 时，觉得官网的用量页面够用了。直到有一天收到账单，费用比预期多了三倍——原来是程序里有个死循环在疯狂调用接口。从那以后我学乖了，实时监控太重要了。

AI API 监控仪表板能帮你解决这些问题：

• 实时看到每分钟调用次数，发现异常流量
• 按模型分组统计花费，掌握成本分布
• 监控响应延迟，及时发现性能问题
• 设置告警，费用超支前自动通知

二、前期准备：注册 HolySheep AI 获取 API Key

搭建仪表板前，你需要先有一个能用的 AI API。这里我推荐 立即注册 HolySheheep AI，这是目前国内开发者最喜欢的选择。

我选择 HolySheheep 的原因很简单：人民币直接充值，按官方汇率 1:7.3 换算，相当于省了 85% 的费用。而且国内直连延迟低于 50ms，比调式海外 API 爽多了。

2026 年主流模型输出价格参考（来自 HolySheheep）：

• GPT-4.1：$8.00 / MTok
• Claude Sonnet 4.5：$15.00 / MTok
• Gemini 2.5 Flash：$2.50 / MTok
• DeepSeek V3.2：$0.42 / MTok

注册完成后，在控制台获取你的 API Key，格式类似 sk-holysheep-xxxxxxxxxx。把这个 Key 复制保存好，后面代码里要用。

三、Grafana 环境快速搭建

Grafana 是一款开源的可视化工具，搭配 Prometheus 可以监控几乎任何数据。我用 Docker 方式安装最简单，一条命令搞定：

# 启动 Prometheus 和 Grafana
docker run -d \
  --name prometheus \
  -p 9090:9090 \
  -v /path/to/prometheus.yml:/etc/prometheus/prometheus.yml \
  prom/prometheus

docker run -d \
  --name grafana \
  -p 3000:3000 \
  grafana/grafana

安装完成后，打开浏览器访问 http://localhost:3000，默认账号密码都是 admin。首次登录会要求改密码，随意设一个好记的。

四、创建 Prometheus 配置文件采集 API 数据

这是最关键的部分。Prometheus 需要知道从哪采集数据，我们创建一个配置文件：

# prometheus.yml
global:
  scrape_interval: 15s

scrape_configs:
  - job_name: 'ai-api-metrics'
    static_configs:
      - targets: ['localhost:9091']
    metrics_path: '/metrics'

然后我们需要一个中间服务来暴露 AI API 的调用指标。我用 Python 写了一个轻量级的代理服务：

# api_proxy.py
from flask import Flask, request, jsonify
import requests
import time
from prometheus_client import Counter, Histogram, generate_latest

app = Flask(__name__)

定义指标收集器
request_count = Counter('ai_api_requests_total', 'Total API requests', ['model', 'status'])
request_duration = Histogram('ai_api_request_duration_seconds', 'Request duration', ['model'])
token_usage = Counter('ai_api_tokens_total', 'Total tokens used', ['model', 'type'])

HOLYSHEEP_API_KEY = "YOUR_HOLYSHEEP_API_KEY"
BASE_URL = "https://api.holysheep.ai/v1"

@app.route('/v1/chat/completions', methods=['POST'])
def chat_completions():
    start_time = time.time()
    headers = {
        "Authorization": f"Bearer {HOLYSHEEP_API_KEY}",
        "Content-Type": "application/json"
    }
    
    try:
        response = requests.post(
            f"{BASE_URL}/chat/completions",
            headers=headers,
            json=request.json,
            timeout=30
        )
        
        duration = time.time() - start_time
        result = response.json()
        
        # 提取模型名称和 token 数量
        model = result.get('model', 'unknown')
        prompt_tokens = result.get('usage', {}).get('prompt_tokens', 0)
        completion_tokens = result.get('usage', {}).get('completion_tokens', 0)
        
        # 记录指标
        request_count.labels(model=model, status='success').inc()
        request_duration.labels(model=model).observe(duration)
        token_usage.labels(model=model, type='prompt').inc(prompt_tokens)
        token_usage.labels(model=model, type='completion').inc(completion_tokens)
        
        return jsonify(result)
        
    except Exception as e:
        duration = time.time() - start_time
        request_count.labels(model='unknown', status='error').inc()
        request_duration.labels(model='unknown').observe(duration)
        return jsonify({"error": str(e)}), 500

@app.route('/metrics')
def metrics():
    return generate_latest()

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=9091)

运行这个代理服务：

pip install flask requests prometheus_client
python api_proxy.py

我的实战经验：第一版代理写完漏掉了错误处理，导致服务崩溃了好几次。一定要在 try-except 里记录所有异常，否则 Prometheus 采集不到失败数据，你以为调用成功实际上可能全挂了。

五、在 Grafana 中添加数据源并创建仪表板

回到 Grafana 界面，按以下步骤操作：

第一步：添加 Prometheus 数据源

点击左侧齿轮图标 → Data Sources → Add data source → 选择 Prometheus → URL 填写 http://localhost:9090 → 点击 Save & test

第二步：创建新仪表板

点击左侧加号 → Dashboard → New dashboard → 点击 Add new panel

第三步：添加可视化面板

在面板配置页面，Metrics 浏览器输入框里写入 PromQL 查询语句。以下是我常用的几个查询：

• 总请求次数：sum(increase(ai_api_requests_total[1m]))
• 按模型分组请求：sum by (model) (increase(ai_api_requests_total[5m]))
• Token 消耗趋势：sum by (model, type) (increase(ai_api_tokens_total[1h]))
• 响应延迟 P99：histogram_quantile(0.99, rate(ai_api_request_duration_seconds_bucket[5m]))

右侧 Visualization 选择合适的图表类型，Requests 用 Bar Chart，Token 消耗用 Time Series，延迟用 Gauge。

六、实战案例：配置成本告警

这是我在生产环境里的真实配置。当每小时 token 消耗超过阈值时，企业微信机器人会自动通知我。

在 Grafana 中创建告警规则：

# Alert Rule 配置
名称：API 成本告警
条件：avg() of query(A) is above 100000
for: 5m
labels:
  severity: critical
annotations:
  summary: "Token 消耗异常，请检查是否存在异常调用"
  description: "当前小时 Token 消耗已达 {{ $value }}，请登录查看详情"

告警通知渠道可以配置邮件、企业微信、钉钉或飞书。我的经验是即时通讯比邮件管用，邮件经常看不到。

七、Grafana 仪表板模板分享

我把自己用的模板导出了一份，可以直接导入使用。模板包含以下面板：

• 实时请求 QPS 曲线
• 各模型调用占比饼图
• Token 消耗日/周/月趋势
• 响应延迟分布直方图
• 错误率监控
• 预估日账单金额

# 导入方法
1. 在 Grafana 左侧点击 + 号
2. 选择 Import
3. 上传我提供的 dashboard.json 或粘贴 JSON 内容
4. 选择 Prometheus 数据源
5. 点击 Import 完成

常见报错排查

错误一：Prometheus 无法采集到数据

报错表现：Grafana 中数据源测试通过，但面板显示"No data"

排查步骤：

# 1. 检查 Prometheus 是否正常运行
docker ps | grep prometheus

2. 检查 Prometheus 日志
docker logs prometheus

3. 手动测试指标端点是否可访问
curl http://localhost:9091/metrics

解决方案：确保 Prometheus 配置文件中 targets 地址和端口与你的代理服务一致。如果代理服务重启过，检查容器网络是否互通。

错误二：API 调用返回 401 认证错误

报错表现：浏览器控制台显示 {"error": {"message": "Invalid authentication", "type": "invalid_request"}}

排查步骤：

# 1. 检查 API Key 是否正确配置
2. 确认 Key 没有包含多余空格或换行符
3. 验证 Key 是否在 HolySheep 控制台激活

测试 API Key 是否有效
curl -X POST https://api.holysheep.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_HOLYSHEEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4.1", "messages": [{"role": "user", "content": "test"}]}'

解决方案：我曾经因为复制 Key 时多了一个空格折腾了两小时。建议 Key 存放在环境变量里，用 os.getenv("HOLYSHEEP_API_KEY") 读取，避免硬编码出错。

错误三：Token 统计数字不准确

报错表现：Prometheus 记录的 token 数量和 HolySheep 控制台显示的不一致

排查步骤：

# 检查代码中 token 提取逻辑
确保使用正确的响应字段

HolySheheep API 返回格式
{
  "usage": {
    "prompt_tokens": 100,
    "completion_tokens": 200,
    "total_tokens": 300
  }
}

解决方案：某些模型在流式响应时不返回 usage 字段，需要等请求完全结束后才能拿到准确数字。如果你的应用重度依赖流式输出，考虑在服务端缓存请求参数，等响应完成后再统计。

错误四：Grafana 面板加载很慢

报错表现：仪表板打开需要好几秒，查询经常超时

排查步骤：

# 1. 减少查询时间范围，优先看最近 6 小时而非 30 天
2. 使用 recording rules 预聚合数据
3. 检查 Prometheus 资源使用

recording_rules:
  - name: api_request_rate
    rules:
      - record: job:request_rate:5m
        expr: rate(ai_api_requests_total[5m])

解决方案：我的仪表板一开始查 30 天数据，Prometheus 每次查询都要扫描大量数据块。后来我创建了 recording rules，把常用的聚合结果提前算好，查询时间从 8 秒降到 0.3 秒。

总结

通过本教程，你已经掌握了使用 Grafana 构建完整 AI API 监控仪表板的全部技能。从注册 HolySheheep API、搭建 Prometheus 采集架构，到在 Grafana 中创建可视化面板和告警规则，一套组合拳下来，你的 AI 应用运维能力会提升一大截。

我个人的经验是，监控一定要在上线前就配置好，而不是出了问题再补救。等你看到账单才意识到要监控，就太晚了。

如果遇到问题，欢迎在评论区留言，我会尽量解答。

👉 免费注册 HolySheheep AI，获取首月赠额度