腾讯云 ES 接入 OpenAI 可观测数据：从零到仪表盘的完整教程

你在用 GPT-4o 写代码、用 DALL·E 生成图片、用 Whisper 做语音转写——但你知道这个月到底烧了多少 token 吗？哪个项目在疯狂调用 API？哪个同事偷偷用着最贵的模型？ Elastic 的 OpenAI Integration 就是来回答这些问题的。它通过 OpenAI Usage API 把你的用量数据拉到 Elasticsearch 里，配合预置的 Kibana 仪表盘，让你对 OpenAI 的消费一目了然。 但在腾讯云 ES 上跑通这件事，有一个绕不开的坑：网络。本文会手把手带你踩过去。

整体架构

先搞清楚数据是怎么流的：

Elastic Agent 定期调用 OpenAI 的 Usage API 拉取用量数据，写入 Elasticsearch 的 logs-* 数据流，最后在 Kibana 的预置 Dashboard 里展示。

前置条件

在动手之前，确认你手里有这些东西：

Step 1：在 OpenAI 平台生成 Admin Key

OpenAI Integration 用的不是普通的 API Key，而是 Admin Key——只有它才有权限调用 Usage API。

1. 登录 OpenAI Platform
2. 进入 Settings → Organization → Admin keys（直达链接：https://platform.openai.com/settings/organization/admin-keys）
3. 点击 Create new admin key，给它起个名字，比如 elastic-openai-monitor
4. 复制生成的 Key，妥善保存——页面关掉就再也看不到了

⚠️ Admin Key 的权限很大，能读取整个组织的用量数据。建议单独创建一个，不要和业务 API Key 混用。用完如果不需要了，及时删除。

Step 2：解决腾讯云 ES 的网络问题（关键步骤）

这是腾讯云 ES 和 Elastic Cloud 最大的区别。腾讯云的 Kibana 和 ES 节点跑在 VPC 内网里，默认无法访问 Elastic Package Registry（EPR）——而 Fleet 安装 Integration 时需要从 EPR 下载集成包。

你有两条路：

方案 A：开启外网访问

在腾讯云 ES 控制台开启 Kibana 的外网访问。8.11 之后的网络架构支持这个操作。

方案 B：搭建本地 Elastic Package Registry

在 VPC 内的一台 CVM 上用 Docker 跑一个本地 EPR 镜像，速度快、稳定。

# 1. 在一台能访问公网的机器上拉取镜像
docker pull docker.elastic.co/package-registry/distribution:9.1.3

# 2. 保存镜像为 tar 文件
docker save -o package-registry-9.1.3.tar docker.elastic.co/package-registry/distribution:9.1.3

# 3. 把 tar 文件传到 VPC 内的 CVM 上，加载镜像
docker load -i package-registry-9.1.3.tar

# 4. 启动本地 EPR
docker run -d -p 8080:8080 docker.elastic.co/package-registry/distribution:9.1.3

然后提交腾讯云工单，要求售后团队在 kibana.yml 中添加：

xpack.fleet.registryUrl: "http://<你的CVM内网IP>:8080"

💡 这一步没法自己改，腾讯云托管的 Kibana 配置文件需要通过工单修改。提工单时说清楚需求，一般一个工作日内能处理。

配置生效后，在 Kibana 的 Integrations 页面应该能看到所有可用的集成包，包括 OpenAI。

Step 3：安装 Fleet Server

Fleet Server 是 Elastic Agent 的管理中枢。你需要在一台 CVM 上安装它。

1. 在 Kibana 左侧菜单找到 Fleet，点击 Settings
2. 在 Fleet Server hosts 中添加地址，格式为 https://<CVM内网IP>:8220
3. 回到 Fleet 主页，点击 Add Fleet Server，按提示创建 Fleet Server Policy
4. 页面会生成安装命令，在 CVM 上执行：

# 下载 Elastic Agent
curl -L -O https://artifacts.elastic.co/downloads/beats/elastic-agent/elastic-agent-9.1.3-linux-x86_64.tar.gz
tar xzvf elastic-agent-9.1.3-linux-x86_64.tar.gz
cd elastic-agent-9.1.3-linux-x86_64

# 安装 Fleet Server（参数从 Kibana 页面复制）
sudo ./elastic-agent install \
  --fleet-server-es=https://<ES内网地址>:9200 \
  --fleet-server-service-token=<你的service-token> \
  --fleet-server-policy=fleet-server-policy \
  --fleet-server-port=8220 \
  --insecure

--insecure 参数在腾讯云环境下通常是必要的，因为自签名证书校验容易出问题。如果你配置了完整的证书链，可以去掉这个参数，改用 --certificate-authorities 等参数指定证书。

安装成功后，Kibana 的 Fleet 页面会显示 Fleet Server connected。

Step 4：安装 Elastic Agent 并添加 OpenAI Integration

Fleet Server 本身也是一个 Agent，你可以直接在它上面添加 OpenAI Integration，也可以新建一个 Agent Policy 部署到另一台机器上。为了简单，我们直接在 Fleet Server 上操作。

4.1 添加 OpenAI Integration

1. 在 Kibana 中进入 Fleet → Agent policies
2. 选择你的 Agent Policy，点击 Add integration
3. 搜索 OpenAI，点击进入
4. 点击 Add OpenAI

4.2 配置 Integration

在配置页面，你需要填写以下关键信息：

关于 Bucket Width 的选择建议：

• 1m：最细粒度，适合看最近 24 小时的数据，但数据量大
• 1h：适合 1-15 天的中期分析
• 1d：适合 15 天以上的长期趋势，数据量最小

🎯 我的建议：如果你刚开始用，先保持默认的 1m + 24h。等跑稳了之后，如果想拉更长的历史数据，把 Bucket Width 改成 1d，Initial Interval 改成 180d（半年），跑一次之后再改回来。用 1m 的粒度拉半年数据会触发大量 API 请求，很可能超时。

4.3 选择数据流

OpenAI Integration 支持 8 种数据流，默认全部开启：

• completions — GPT 系列模型的对话补全（最常用，token 消耗大户）
• embeddings — 文本嵌入
• images — DALL·E 图片生成
• audio_speeches — TTS 文本转语音
• audio_transcriptions — Whisper 语音转文字
• moderations — 内容审核
• vector_stores — 向量存储
• code_interpreter_sessions — 代码解释器

如果你只用了 GPT 和 Embeddings，可以把其他的关掉，减少不必要的 API 调用。

配置完成后，点击 Save and continue。

Step 5：验证数据采集

等待 5-10 分钟（取决于你设置的 Interval），然后验证数据是否正常流入。

5.1 在 Discover 中查看

1. 进入 Kibana 的 Discover
2. 选择 logs-* 数据视图
3. 搜索 data_stream.dataset : "openai.*"

你应该能看到类似这样的文档：

{
  "openai": {
    "completions": {
      "input_tokens": 22,
      "output_tokens": 149,
      "input_cached_tokens": 0
    },
    "base": {
      "model": "gpt-4o-mini-2024-07-18",
      "num_model_requests": 1,
      "project_id": "proj_xxx",
      "user_id": "user-xxx"
    }
  },
  "@timestamp": "2026-04-26T00:00:00.000Z"
}

5.2 查看预置仪表盘

OpenAI Integration 自带了一套 Kibana Dashboard：

1. 进入 Kibana → Dashboards
2. 搜索 OpenAI
3. 打开 OpenAI Overview 仪表盘

你会看到：

• 总调用次数和 Token 消耗的概览
• 按模型分类的调用量和 Token 用量趋势
• Top 项目、用户、API Key 的排行
• 图片生成的尺寸分布和调用量
• 语音转写的时长统计
• TTS 的字符数统计

Step 6：设置告警（可选但强烈推荐）

数据有了，下一步是让它主动告诉你"出事了"。

示例：Token 用量超限告警

1. 进入 Observability → Alerts → Create rule
2. 选择 Custom threshold
3. 配置：
   • 数据源：logs-openai.completions-*
   • 聚合字段：SUM(openai.completions.input_tokens) + SUM(openai.completions.output_tokens)
   • 阈值：比如每天超过 100 万 token 就告警
   • 通知方式：邮件、Webhook、Slack 等

示例：用 SLO 监控模型分布

如果你希望团队优先使用便宜的 GPT-3.5 而不是 GPT-4o，可以创建一个 SLO：

• Good events：openai.base.model 包含 gpt-3.5*
• Total events：所有 OpenAI 请求
• 目标：80%（即至少 80% 的请求应该走 GPT-3.5）
• 按 openai.base.project_id 分组，找出哪个项目在"乱花钱"

常见问题排查

Q：Fleet 页面加载很慢，Integration 列表为空？

→ EPR 连接问题。确认本地 Package Registry 是否正常运行，kibana.yml 中的 registryUrl 是否配置正确。

Q：Agent 状态显示 Healthy 但 Discover 里没数据？

→ 检查 OpenAI Admin Key 是否正确。可以用 curl 手动测试 Usage API

curl -H "Authorization: Bearer sk-admin-xxx" \
  "https://api.openai.com/v1/organization/usage/completions?start_time=$(date -d '1 day ago' +%s)"

如果返回 401，说明 Key 有问题。

Q：数据有延迟？

→ 正常。OpenAI Usage API 本身有几分钟到几十分钟的延迟，再加上 Elastic Agent 的采集间隔（默认 5 分钟），总延迟在 10-30 分钟左右。这不是实时监控，是用量分析。

Q：Elastic Agent 和 ES 之间通信失败？

→ 腾讯云 VPC 内常见的证书问题。尝试在 Agent 注册命令中加 --insecure --fleet-server-es-insecure，或者正确配置 CA 证书。

写在最后

说实话，这个 Integration 做的事情并不复杂——就是定时调 OpenAI 的 Usage API，把数据存到 ES 里。但它的价值在于：把散落在 OpenAI 后台的用量数据，拉到了你自己的可观测体系里。

你可以把它和其他业务指标放在一起看，比如"上线新功能后 GPT-4o 的调用量涨了 3 倍"，或者"某个项目的 token 消耗突然翻倍，是不是 prompt 写得太啰嗦了"。这些洞察，光看 OpenAI 的账单页面是得不到的。

花点时间搞定基础设施，换来的是对 AI 支出的长期可见性——这笔账怎么算都划算。