用Prometheus+Grafana构建DeepSeek API监控看板

简介针对API可观测性需求面向需要实时掌握DeepSeek API调用状态的开发与运维人员这份20页PDF系统讲解如何用Prometheus与Grafana搭建监控看板。文档从API监控基本概念与背景意义入手细化调用次数、响应时间、错误率三类核心指标逐步说明Prometheus安装部署、Exporter配置、PromQL查询以及Grafana仪表盘、可视化面板和报警规则设置内容覆盖数据采集、实时追踪、报警测试与优化等完整环节最后通过案例演示异常分析与优化方法。资源为单个PDF文件大小1.88MB完整度和清晰度均有保障目录结构便于按章节查阅。已有214人学习适合希望快速落地API监控体系并提升故障排查效率的技术读者。文档包含从环境准备到验证部署的完整实施路径可作为操作参考为线上API稳定性保障提供直观数据支撑。1. API监控看板的本质把 DeepSeek 调用变成可度量的数据API监控看板的本质是把每一次 DeepSeek 调用变成可度量的数据。用 PrometheusGrafana 这套组合你可以实时追踪调用指标从 QPS 波动、响应延迟到 token 消耗全部落到一条时间序列上。当你的业务接入 DeepSeek 之后最先崩溃的往往不是代码而是月末账单等到用户反馈“变慢了”才开始排查已经是被动救火。这篇文章面向后端工程师、SRE 和正在做大模型应用落地的小团队目标是用最快速度搭出一块能说明白的看板并掌握后续扩成告警体系所需的全部基础。2. 先设计指标再动手DeepSeek 调用指标与 Prometheus 数据模型在埋点之前先想清楚一个问题哪些指标对排障和成本控制有价值我一般会从四个维度出发请求量、延迟、错误、token 消耗。请求量代表调用频率观察 QPS 能判断业务高峰和扩容时机延迟至少要看 p95 和 p99因为大模型 API 的响应时长波动远比传统 RPC 大一次长尾请求可能拖垮整体体验错误率要按错误类型拆开超时、限流、无效请求的处理方式完全不同token 消耗是成本来源也是大模型产品特有的计费口径把输入、输出 token 分开记录月底对账就不用手工翻日志。这四个维度落实到 Prometheus 上就是一组带标签的指标。我推荐的指标契约如下指标名类型含义常用标签deepseek_requests_totalCounter累计调用次数model, endpointdeepseek_request_duration_secondsHistogram请求耗时分布modeldeepseek_errors_totalCounter累计错误次数model, error_typedeepseek_tokens_totalCounter累计 token 消耗model, token_typedeepseek_inflight_requestsGauge当前在途请求数model2.1 Prometheus 指标类型与 DeepSeek 场景的对应关系Prometheus 的核心指标模型是带标签的时间序列。Counter 只增不减适合累计值Gauge 可增可减适合瞬时值Histogram 在客户端预先计算分位数并暴露_bucket、_sum、_count服务端可以精确聚合Summary 也做分位数计算但聚合能力差多个实例的 Summary 不能直接合并。在 DeepSeek 监控场景下请求次数、错误次数和 token 消耗都用 Counter 即可实时并发量适合 Gauge延迟强烈建议用 Histogram因为不同 SDK 的 Summary 算法差异会导致聚合结果不准。给 Histogram 配置 buckets 时可以从 0.1 秒起步到 10 秒覆盖大模型响应的典型区间。如果你同时接入多个模型版本把 model 和 endpoint 作为标签区分不同调用链路的开销。2.2 用 Python client 暴露一个最小指标端点下面这段代码演示怎么用 Python 的prometheus_client库暴露这些指标安装方式就是pip install prometheus-client代码量很少。from prometheus_client import Counter, Gauge, Histogram, start_http_server import time requests_total Counter( deepseek_requests_total, Total DeepSeek API requests, [model, endpoint], ) errors_total Counter( deepseek_errors_total, Total DeepSeek API errors, [model, error_type], ) tokens_total Counter( deepseek_tokens_total, Token usage from DeepSeek responses, [model, token_type], ) inflight Gauge( deepseek_inflight_requests, Current in-flight DeepSeek requests, [model], ) duration Histogram( deepseek_request_duration_seconds, DeepSeek API latency in seconds, [model], buckets[0.1, 0.5, 1, 2.5, 5, 10], ) if __name__ __main__: start_http_server(8000) while True: time.sleep(1)start_http_server(8000)会启动一个线程默认暴露在/metrics路径Prometheus 从那里抓取。每个指标创建时可以指定标签名实际写入时通过labels(model..., endpoint...)填充。记住一点标签值必须是有限集合绝不能把 request_id 这类高基数字段放进去否则 Prometheus 内存会被打爆。3. Prometheus 监控部署与 Grafana 数据源连通3.1 用 Docker Compose 完成 Prometheus 监控部署使用容器化是最快的 Prometheus 监控部署方式。创建目录monitor/把下面的内容保存为docker-compose.ymlservices: prometheus: image: prom/prometheus:latest ports: - 9090:9090 volumes: - ./prometheus.yml:/etc/prometheus/prometheus.yml command: - --config.file/etc/prometheus/prometheus.yml grafana: image: grafana/grafana:latest ports: - 3000:3000 environment: - GF_SECURITY_ADMIN_PASSWORDadmin启动前先创建prometheus.yml否则 Prometheus 容器会因缺少配置文件拒绝启动。最简单的存活配置如下global: scrape_interval: 15s evaluation_interval: 15s scrape_configs: - job_name: deepseek_api metrics_path: /metrics static_configs: - targets: [host.docker.internal:8000]scrape_interval控制 Prometheus 多久抓一次 targets15 秒对 API 监控来说足够evaluation_interval控制告警规则的计算频率。targets指向的host.docker.internal:8000是容器内访问宿主机端口的约定地址如果你的应用也运行在同一 Docker 网络中可以直接写服务名比如app:8000。metrics_path默认就是/metrics这里显式写出便于后面排查。保存后在目录下执行docker compose up -d。启动后浏览器访问http://localhost:9090/targets在 target 列表里应该能看到deepseek_api状态为 UP。如果显示 DOWN大多数情况不是防火墙问题而是你本地还没有服务跑在 8000 端口这个在第四章处理。也可以直接在命令行验证抓取配置curl http://localhost:9090/api/v1/targets返回 JSON 中health字段为up表示抓取正常。这一步能快速定位配置问题。3.2 在 Grafana 中配置 Prometheus 数据源Grafana 启动后访问http://localhost:3000首次登录用admin/admin会让你改密码。接着进入左侧 Connections选择 Data sources点击 Add data source 并选择 Prometheus。URL 这里容易踩坑如果你用 Docker Compose 启动Grafana 容器内的localhost是自己的容器不是宿主机所以应该填http://prometheus:9090因为 compose 中的服务名可以作为 DNS 解析。如果 Grafana 是二进制方式安装则可以填http://localhost:9090。填好后点 Save test出现 success 就表示连通。如果你不想从零拖图表可以到 Grafana 官方 Dashboards 库搜索Prometheus相关关键词导入一个现成的模板再修改 PromQL 里的指标名为 DeepSeek 对应的名称。不过在导入前最好先理解查询逻辑否则后续排障还是会卡住。4. 在 DeepSeek API 调用代码中埋点并制作第一块看板4.1 封装 DeepSeek API 调用埋点与异常捕获现在把前面定义的指标真正用起来。DeepSeek API 兼容 OpenAI 的接口规范所以直接用openaiSDK 就可以只需要把base_url指向https://api.deepseek.com。下面是一个最小封装核心是在调用前后更新指标。import os import time import openai from prometheus_client import Counter, Gauge, Histogram client openai.OpenAI( api_keyos.getenv(DEEPSEEK_API_KEY), base_urlhttps://api.deepseek.com, ) requests_total Counter( deepseek_requests_total, Total DeepSeek API requests, [model, endpoint], ) errors_total Counter( deepseek_errors_total, Total DeepSeek API errors, [model, error_type], ) tokens_total Counter( deepseek_tokens_total, Token usage from DeepSeek responses, [model, token_type], ) inflight Gauge( deepseek_inflight_requests, Current in-flight DeepSeek requests, [model], ) duration Histogram( deepseek_request_duration_seconds, DeepSeek API latency in seconds, [model], buckets[0.1, 0.5, 1, 2.5, 5, 10], ) def call_deepseek(prompt, modeldeepseek-chat, endpointchat.completions): inflight.labels(modelmodel).inc() started time.perf_counter() try: resp client.chat.completions.create( modelmodel, messages[{role: user, content: prompt}], streamFalse, ) requests_total.labels(modelmodel, endpointendpoint).inc() usage getattr(resp, usage, None) if usage: tokens_total.labels(modelmodel, token_typeprompt).inc(usage.prompt_tokens) tokens_total.labels(modelmodel, token_typecompletion).inc(usage.completion_tokens) return resp except Exception as exc: errors_total.labels(modelmodel, error_typetype(exc).__name__).inc() raise finally: duration.labels(modelmodel).observe(time.perf_counter() - started) inflight.labels(modelmodel).dec()inflight在调用开始前增加结束后减少这样deepseek_inflight_requests的当前值就是并发数。requests_total只在成功响应时计数而errors_total在异常路径写。注意usage不是所有 SDK 响应都携带所以用getattr防御。error_type用type(exc).__name__得到Timeout、RateLimitError之类的分类后期可以按这个标签做告警。4.2 写 PromQL 查询从原始指标到可视化面板埋点只是第一步看板才是入口。以下这几条 PromQL 是实际使用中最常写的可以直接用在 Grafana 的 Query 编辑器里。面板名称PromQL每分钟请求量sum(rate(deepseek_requests_total[1m]))p95 延迟histogram_quantile(0.95, sum(rate(deepseek_request_duration_seconds_bucket[5m])) by (le))错误率sum(rate(deepseek_errors_total[5m])) / sum(rate(deepseek_requests_total[5m]))各模型 token 消耗sum(deepseek_tokens_total) by (model, token_type)当前并发sum(deepseek_inflight_requests)第一个1m是时间范围rate计算每秒增量乘以 60 可得每分钟速率。第二个histogram_quantile必须配合 histogram 的_bucket序列使用by (le)是固定写法否则聚合会报错。错误率需要两个 counter 速率做除法注意如果请求量分母为 0 时 PromQL 返回 NaN面板上会显示空白可以通过 Grafana 的 null 值设置处理。4.3 模拟流量验证指标流动为了验证整个链路你可以写一个简单脚本循环调用call_deepseek也可以只调用本地暴露的 metrics 端点。把上面的函数保存为monitor.py然后运行下面的验证脚本import time from monitor import call_deepseek for i in range(10): call_deepseek(ftest message {i}) time.sleep(1)运行前记得设置DEEPSEEK_API_KEY环境变量。如果本地没有配置可以先只打开/metrics端点确认指标名存在再用 mock 响应验证埋点逻辑。Prometheus 默认抓取周期是 15 秒所以埋点产生的新数据最多延迟 15 秒出现在图表里这不代表链路有问题。5. Prometheus 告警规则配置详解与监控体系常见坑5.1 Prometheus 告警规则配置从 YAML 到通知指标稳定采集之后就该接告警。Prometheus 的告警规则与抓取配置独立放在单独的 YAML 文件中并要在主配置里通过rule_files加载。下面是一个针对 DeepSeek 调用的规则文件alert.yml。groups: - name: deepseek-api rules: - alert: DeepSeekErrorRateHigh expr: | sum(rate(deepseek_errors_total[5m])) / sum(rate(deepseek_requests_total[5m])) 0.05 for: 10m labels: severity: warning annotations: summary: DeepSeek 错误率超过 5% description: 当前错误率 {{ $value | humanizePercentage }} - alert: DeepSeekP95LatencyHigh expr: | histogram_quantile(0.95, sum(rate(deepseek_request_duration_seconds_bucket[5m])) by (le)) 3 for: 5m labels: severity: critical annotations: summary: DeepSeek p95 延迟超过 3 秒for表示条件持续多长时间才触发能够滤掉瞬时抖动。要真正发出通知需要另起一个 Alertmanager 容器并配置邮件、钉钉或飞书渠道但规则本身是核心。在prometheus.yml中加入rule_files: [alert.yml]并重启 Prometheus就能在 UI 的 Alert 页面看到规则状态。5.2 抓取超时、高基数与标签泄漏第一个坑是抓取超时。如果抓取目标里的/metrics端点本身计算耗时较长比如每次导出时要重新统计 token那么 Prometheus 默认的scrape_timeout3 秒会超时。解决方式是在scrape_configs中设定scrape_timeout: 10s注意它必须小于scrape_interval否则没有意义。第二个坑是高基数。每一条唯一标签组合都是一个时间序列。如果你把用户的 ID 或 request ID 放进标签一个月后序列数会膨胀到百万级Prometheus 内存会被吃掉。正确做法是用 label 区分维度比如model、endpoint、error_type把用户维度放到日志系统而不是监控系统。第三个坑是标签泄漏。来自外部输入的值要作为标签时必须做白名单校验。比如从请求参数拿到的model名如果不校验攻击者可以随机生成大量 model 值造成类似高基数的问题。另外如果你现在已经有 OpenTelemetry Collector 在收集链路数据可以单独起一个 Prometheus 实例从 OTEL 的 Prometheus remote write endpoint 收数据但这不是常规做法。常规做法仍然是让 Prometheus 直接抓取应用自身的 metrics 端点链路更短排障也更简单。5.3 排查失败从 datasource 失效到图表空白Grafana 使用久了会碰到一些奇奇怪怪的问题。最常见的报错是failed to upgrade legacy queries datasource出现在从旧版 Grafana 升级到新版后图形面板中残留的老式数据源引用无法自动迁移。处理方式是进入该数据源配置重新选择保存一次或在系统设置里清掉grafana.db重建但要注意备份面板 JSON。对于图表空白先检查 Prometheus 的Status Targets页面确认 target 是否 UP再在查询页面用 Explore 执行 PromQL如果查询返回数据问题就出在面板配置如果返回空问题出在指标名或标签。还有一个容易忽略的点是 Grafana 面板的查询时间范围如果调用量很低统计范围太短会看不出曲线。现象可能原因处理方式图表空白且 target UPPromQL 标签名不匹配在 Explore 中试运行检查__name__和标签Grafana 报 legacy queries 错误旧版本数据源缓存重新保存数据源清理 grafana.db曲线有断点抓取间隔内目标有一次未返回增大scrape_interval或scrape_timeout6. 用 Grafana 变量和面板复制实现多环境复用在生产环境通常有 dev、qa、prod 三套环境各接一个 DeepSeek API key如果每个环境单独搭一套看板维护成本翻三倍。用 Grafana 的变量功能可以一套看板覆盖所有环境。做法是进入 Dashboard 的 Settings在 Variables 中添加一个变量Type 选 Custom名字写envValue 填prod,qa,dev。然后在面板的 PromQL 中引用$env比如sum(rate(deepseek_requests_total{env$env}[5m]))这样看板顶部会出现一个下拉框切换环境所有面板一起变化。这个方案隐含一个前提埋点写入的指标必须带env标签。所以应用在初始化指标时要从环境变量读取并作为默认标签。如果之前没有考虑可以用 Prometheus 配置中的metric_relabel_configs为抓取到的指标统一加上环境标签但改起来麻烦最可靠还是回到代码里加。对于已经搭好的某个环境看板也可以直接用 Dashboard 设置中的“拷贝整个面板”功能复制面板再把复制版的查询条件改掉这样比重新拖图表快得多。还有一个实用技巧是使用 Grafana 的?var-envqa链接参数把看板按环境分享出去。验证方法很简单切换变量后看面板数据的变化如果某环境没有指标会显示 no data说明该环境的标签值没有被正确写入。本文还有配套的精品资源点击获取