一、为什么需要自定义仪表板：超越通用统计
EIOS 控制台提供了开箱即用的用量和性能仪表板，能满足 80% 的通用监控需求。但当你的企业有特定的业务指标（如"按客户项目维度的 AI 成本分摊"、"按部门维度的 Agent 采纳率"、"AI 输出对实际业务 KPI 的贡献值"），通用仪表板就显得力不从心。EIOS 的 分析查询 API（Analytics API）就是为了这 20% 的深度定制需求而设计的。它提供了一套类 SQL 的查询语法（但设计目标是阻止昂贵的大范围扫描），允许开发者以任意维度对平台的运行时数据进行聚合、过滤、排序和可视化。数据源涵盖：Agent 执行记录（每次调用的输入/输出摘要、Token 消耗、耗时、成功率、用户评分）、知识库检索记录（检索次数、命中率、Top K 结果的相关性分数）、API 调用日志（按端点、模型、时间段、用户的聚合统计）、计费数据（按项目/部门/标签的成本归属）。自定义仪表板让 AI 运维从"看完平台面板就结束"升级为"将 AI 指标嵌入企业现有 BI 系统（如 Grafana、Metabase、Tableau 或自研数据大屏），让 CEO、CFO 和部门经理在同一个工具中看到业务数据和 AI 效能数据"。
二、Analytics API 查询语法与端点详解
Analytics API 的查询端点 POST /v1/analytics/query 接受一个结构化的 JSON 查询体，包含以下核心要素：
POST /v1/analytics/query
{
"metrics": ["execution_count", "avg_latency_ms", "tokens_total", "cost_total"],
"dimensions": ["agent_id", "department", "date"],
"filters": [
{ "field": "date", "operator": "between", "values": ["2025-09-11", "2025-09-11"] },
{ "field": "agent_id", "operator": "in", "values": ["agt_legal", "agt_finance"] },
{ "field": "status", "operator": "eq", "value": "success" }
],
"order_by": { "field": "cost_total", "direction": "desc" },
"limit": 100,
"granularity": "day"
}支持的 指标（Metrics） 超过 40 个，包括执行量（execution_count）、成功率（success_rate）、平均耗时（avg_latency_ms）、各百分位耗时（p50/p95/p99_latency_ms）、Token 消耗（tokens_input/tokens_output/tokens_total）、成本（cost_total）、用户评分（avg_user_rating）、检索命中率（retrieval_hit_rate）和错误率（error_rate）。支持的 维度（Dimensions） 包括时间（按小时/天/周/月粒度）、Agent ID、模型名称、部门标签、项目标签、环境（sandbox/staging/production）和错误类型。过滤条件支持等于、不等于、包含、范围、前缀匹配和正则表达式。查询结果的 数据新鲜度 取决于数据源——实时数据（过去 24 小时）延迟 < 1 分钟，历史数据（24 小时以上）延迟 < 5 分钟。结果以 JSON 数组格式返回，同时支持 CSV 导出（在请求头中设置 Accept: text/csv），方便直接导入 Excel 或 BI 工具。
三、Grafana 集成：零代码构建实时监控面板
对于已经使用 Grafana 进行基础设施监控的团队，EIOS 提供了 Grafana 数据源插件（EIOS Analytics Datasource for Grafana）。安装插件后，开发者可以在 Grafana 中直接选择 EIOS Analytics 作为数据源，使用 Grafana 原生的 Query Builder 或直接编写 Analytics API 查询语句，然后将结果渲染为 Grafana 丰富的可视化图表——时序折线图、柱状图、热力图、仪表盘（Gauge）、状态时间线、表格等。一次配置，数据自动刷新，无需编写任何展示层代码。推荐的 Grafana 面板布局包含以下核心视图：第一行，全局概览——今日总调用量、成本、成功率和活跃 Agent 数（大数字展示）；第二行，Agent 排行榜——按调用量、成本和用户评分的 Top 10 Agent 列表；第三行，时序趋势——过去 30 天的调用量、成本和延迟趋势（折线图，支持按 Agent 和模型筛选）；第四行，错误热力图——按小时和错误类型的矩阵热力图，一眼定位问题发生的时间段和根因类型；第五行，成本分布饼图——按部门、项目或模型的成本占比。Grafana 的告警引擎同样可以利用 Analytics API 数据——如"当日成本超过预算 120% 时发送告警"或"连续 3 个时间窗口成功率低于 95% 时通知值班工程师"。
四、BI 工具集成与数据导出
如果团队不使用 Grafana，而是重度依赖 Metabase、Tableau、Power BI 或 Apache Superset，EIOS Analytics API 同样可以无缝对接。对于 Metabase，可以通过其"自定义问题"功能编写 Analytics API 查询语句；对于 Tableau 和 Power BI，推荐使用 CSV 导出接口（POST /v1/analytics/export）定期将数据拉取至本地，然后通过 BI 工具的数据连接器加载。对于需要 实时数据大屏 的场景（如挂在办公区墙上的 TV Dashboard），EIOS 提供了一个 公开分享令牌（Share Token） 机制——在控制台中生成一个只读的、时效有限的分享令牌，将该令牌嵌入自研大屏前端的 API 调用中，即可在无需后端代理的情况下直接从前端拉取 Analytics 数据。令牌支持 IP 白名单和域名绑定（防止令牌泄露后被滥用），以及数据脱敏选项（隐藏具体的 Token 消耗数值，仅展示百分比趋势）。对于需要将 EIOS 数据导入企业数据仓库（如 Snowflake、ClickHouse、StarRocks）的场景，企业版支持 数据导出到 S3/OSS 对象存储——按小时、天或周将 Analytics 数据以 Parquet 格式自动导出至指定的对象存储桶，供数据仓库的 ETL 流水线消费。
五、高级可视化：业务价值归因与 ROI 计算
真正让 CEO 和 CFO 关注 AI 仪表板的，不是 Token 消耗数据，而是 AI 投入对业务产出的实际贡献。EIOS Analytics API 支持通过 自定义标签（Custom Tags） 机制将业务价值数据关联至 AI 调用。在每次 Agent 执行时，调用方可以通过 X-EIOS-Tags 请求头传递业务上下文标签（如 customer_id: C8872, ticket_id: T12934, resolution_time_saved_min: 45）。这些标签在 Analytics API 中成为可查询的维度。结合业务数据，开发者可以构建这样的仪表板查询："按部门聚合，计算通过 AI 辅助节省的总工时 × 平均时薪 = AI 创造的直接人力成本节约"，然后将这个计算得出的 ROI 数值展示在仪表板的 C 位。另一个高级可视化是 Agent 采纳漏斗：有多少员工知道 AI 助手存在 → 有多少人尝试过 → 有多少人每周使用超过 3 次 → 有多少人对 AI 输出的采纳率超过 80%。这个漏斗帮助管理者识别 AI 推广的瓶颈环节——是宣传不够（知道的人少）、体验不好（尝试后放弃）、还是输出质量不达预期（频繁使用但采纳率低）。Analytics API 的数据结合行为漏斗分析，让 AI 从"技术部门的一个工具"升级为"全公司的数字化生产力引擎"。
六、仪表板开发实战模板
为了降低自定义仪表板的开发门槛，EIOS 提供了 三个开箱即用的仪表板模板（开源，GitHub 仓库 eios-dashboard-templates），开发者可以 Fork 后按需定制。模板一：「AI 运营指挥中心」（React + ECharts）——面向 CTO 和 AI 团队负责人，展示全局 Agent 健康状态、资源利用率和异常告警，使用 WebSocket 实时刷新，适合挂墙展示。模板二：「部门 AI 效能看板」（Vue 3 + AntV G2）——面向各部门负责人，展示本部门 AI 使用量、采纳率、成本分摊和效率提升数据，支持按时间段和 Agent 筛选。模板三：「财务 AI 成本分析」（静态 HTML + Chart.js）——面向 CFO 和财务团队，展示月度 AI 支出趋势、按项目/部门的成本分布、预算使用进度和异常消费预警，通过 CSV 导出接口定期更新数据。每个模板包含完整的文档（README）、环境变量配置指南和 Docker Compose 一键部署文件。模板遵循 MIT 协议，允许任意修改和二次分发。EIOS 开发者社区还定期举办 仪表板设计赛，评选最佳可视化创意和最佳数据洞察，获奖作品被纳入官方模板库并标注作者。
