Kibana 仪表板 API 中的向后兼容性意味着什么

在技术预览期间，API 结构可能会随版本发生变化。[1]现在已不再如此。正式发布 (GA) 意味着：

• 完全向后兼容。新字段和面板类型将陆续添加，但现有字段和行为保持不变。未来如需引入任何破坏性变更，都会经过慎重评估，并且只会在新的 Elastic Stack 主版本中引入。

• 可用于生产环境，并提供全面支持。该 API 享有 Elastic 提供的全面支持保障。您可以放心地在生产环境中使用该 API，进行自动化部署、跨环境发布以及以编程方式管理仪表板。

Kibana 新增用于标签、Markdown 和链接面板的 API 终端

Elastic 9.5 还新增了一个用于标签的独立终端，让您可以对仪表板进行分类和筛选。现在，您可以通过专用 CRUD 终端以编程方式管理这些标签，从而更轻松地跨环境大规模组织仪表板。

新的 Markdown 和链接面板终端现已在 Serverless 中提供，并将在下一个 Elastic Stack 版本 (9.6) 中推出。

Kibana 仪表板 API 支持哪些面板类型？

仪表板 API 支持 9.5 中的所有按值面板（即直接在仪表板中定义的面板，而非保存以供重复使用的库面板）。每种受支持的面板类型都有一个类型化且经过验证的架构。

面板类型

状态

XY 图表

支持

指标

支持

饼图

支持

仪表盘图

支持

热图

支持

数据表

支持

树状图

支持

Discover 会话

支持

控件

支持

Markdown

支持

链接

支持

ML 面板

支持

Observability 面板

支持

Maps

即将推出

Vega

即将推出

如何以代码形式管理 Kibana 仪表板

仪表板 API 支持一套完整的以代码形式管理仪表板的工作流：将仪表板导出为简洁、可进行差异比较的 JSON，将其提交到 Git 并作为唯一可信来源，在拉取请求中审查更改，然后将同一定义部署到开发、预发布和生产环境。一旦以代码形式管理仪表板，就应将 Git 作为唯一可信来源：下次部署会覆盖直接在 UI 中所做的更改。

在空间、集群或阶段之间迁移仪表板时，主要挑战在于仪表板会按 ID 引用 Data view、库可视化等对象。由于这些 ID 是自动生成的，且不同环境中的 ID 各不相同，因此从一个环境导出的仪表板可能会引用另一个环境中不存在的对象。有三种方法可以处理这个问题，以下按自动化程度从高到低列出：

• 使用 Terraform。Elastic Stack Terraform 提供程序会跟踪每项资源，并自动映射各环境中的 ID，因此当您将仪表板从开发环境发布到生产环境时，引用可保持一致。

• 定义按值的 Elasticsearch 查询语言 (ES|QL) 面板。构建面板时，可移植性最高的方法是在仪表板中直接使用 ES|QL 定义其可视化。ES|QL 查询会从查询中指定的索引读取数据，因此面板不会包含对 Data view 或库对象的外部引用。这样便可获得一个完全自包含、可移植的仪表板。

• 分配一致的 ID。如果您引用 Data view、库可视化等已保存对象，请使用 PUT (upsert) 并指定 ID 来创建这些对象，而不要使用会自动生成 ID 的 POST。使用易读的 ID（例如 logs-prod），这样更便于在不同环境中重复使用和识别。

有关这些可移植性模式以及完整的以代码形式管理仪表板的工作流的详细介绍，请参阅“以代码形式管理仪表板”文档。

使用 PUT 通过仪表板 API 创建 Kibana 仪表板

下面是一个简单示例：使用 PUT 而非 POST 创建包含指标面板的仪表板，并以仪表板名称 (service-health-overview) 作为自定义 ID。同样的逻辑也适用于创建保存到库中的独立可视化。

Kibana 仪表板 API 路线图：Maps、Vega 和独立终端

我们正在积极扩展 API 的功能范围。下一步将支持 Maps 和 Vega 面板，并为其添加类型化架构。我们还在为 Discover 会话（除了现有的仪表板面板支持之外）、Vega、Maps 和注释构建独立的 CRUD 终端，使其与仪表板生命周期解耦。

有关完整的架构定义，请参阅仪表板 API 文档。对于 Terraform 用户，Elastic Stack Terraform 提供程序支持正式发布 (GA) 的仪表板 API。

注意

1. 核心终端自技术预览以来未发生变化。如果您基于 9.4 构建了集成，这些集成在 9.5 中也可正常运行。仅有两项轻微的破坏性变更，分别影响仪表板列表和时长单位格式，详见此处。

Kibana AI 仪表板创建的新增功能

功能

技术预览版 (9.4)

GA (9.5)

错误处理能力

无法重试失败的 ES|QL 查询

自动重试最多三次，并进行查询检查和调整

ES|QL 生成成本

所有查询均通过主模型路由

分层模型路由，价格最多可降低 5 倍

时间范围

固定默认窗口

基于数据时间分布的自动选择

筛选控件

不支持

自动为相关性最高的字段添加

Vega-Lite 图表

不支持

自然语言创建，包括散点图、箱形图、条件格式、自定义工具提示

图表编辑

不支持

通过自然语言编辑现有的 Vega-Lite 面板

AI 仪表板生成的自动错误恢复

在技术预览版中，代理不会重试失败的 ES|QL 查询。在 9.5 中，它检测查询错误并重试最多三次，检查每个错误并调整查询，然后再放弃。实际上，这消除了大部分空面板问题，并生成首次尝试即可正确渲染的仪表板。

为什么在 Elastic 9.5 中创建 AI 仪表板更便宜？

并非仪表板生成过程中的每一步都需要同等程度的推理。在 9.5 中，ES|QL 生成默认使用较轻量级模型，仅在需要时才回退到主模型。如果您的连接器使用 Anthropic 的 Claude Opus 4.8，这意味着所有面板的 ES|QL 生成成本将降低 5 倍。

根据您的数据自动选择时间范围

仪表板只有在显示正确的数据窗口时才有用。现在，代理会应用改进的逻辑来选择适配查询数据的合理时间范围，除非用户要求特定的时间范围。它会考虑数据的时间分布并进行相应的调整，无论是实时事件的最后一小时，还是趋势分析的过去 90 天，而不是默认使用固定的时间窗口。

AI 生成的仪表板上的自动筛选控件

仪表板创建现在支持控件；也就是说，交互式筛选器允许查看者按字段值缩小仪表板范围，而无需编辑底层查询。生成仪表板时，代理会自动在顶部添加控件，用于筛选最相关的字段。

使用自然语言创建 Vega-Lite 图表：图表类型和默认之外的格式

Vega 和 Vega-Lite 支持 Kibana 中的各种图表类型和自定义功能。使用 9.5，您可以直接用纯语言构建它们，而无需自己编写代码。

散点图、箱形图以及更多 Vega-Lite 图表类型

散点图、箱形图、分面小倍数、气泡图和组成图（类似将直方图与热图结合）等多种图表均由 Vega-Lite 支持。类似“向我显示响应时间与请求大小的散点图，按服务名称着色”这样的提示会生成一个具有正确数据映射的 Vega-Lite 面板。他们使用 Kibana 的默认调色板与仪表板的其余部分融为一体。

标准图表上的条件格式、自定义工具提示和标签

即使对于仪表板中已有的图表类型（如柱形图、折线图或面积图），有时您也需要比默认功能提供的更多控制。Vega-Lite 通过聊天功能填补了这一空白。一些示例包括：

• 条件颜色格式：以不同的颜色标记高于阈值的数据点；例如，当某些指标的峰值超过您的服务级别目标 (SLO) 时，将折线或柱状图中的数据点标记为红色。您可以向代理提出类似的问题：将折线图中所有高于 500 毫秒的点都变成红色。

  

• 自定义标记和标签：向数据点添加表情符号、符号或行内文本标签，使状态指示器一目了然。

  

• 自定义工具提示：使用不属于图表轴的其他指标、上下文或计算值来丰富悬停状态。可以提出类似这样的问题：添加一个工具提示，显示总记录数和每条柱状图的百分比。

  

这也适用于编辑现有的 Vega 图表。如果您的 Vega-Lite 面板需要进行一些调整，例如更改颜色标度、调整坐标轴或切换标记类型，请在聊天中描述更改，而不是深入研究 JSON 代码。

我们如何在 Kibana 中构建自然语言 Vega-Lite 生成

从句子生成 Vega-Lite 图表并不是一次性 向模型请求 JSON 提示。我们构建了一个小型的代理管道，将自然语言意图转化为经过验证、数据支持的图表。

当收到请求时，代理首先确定 Vega-Lite 是否合适。对于 Vega-Lite 请求，它将可视化建立在针对 Elasticsearch 的真实 ES|QL 查询之上，然后使用模型生成 Vega-Lite 代码。在渲染之前，结果会经过一个规范化层，纠正模式并绑定规范查询。它还应用了渲染安全转换。

有几个设计选择使该工作流可靠：

• 类型化工具调用：图表创建是一个结构化的工具调用，而不是将自由格式的 Vega-Lite 粘贴到对话中。

• 受限生成：模型在定义的模式内生成 Vega-Lite 代码，使输出更可预测且易于验证。

• 精选示例：结构模式（如分面、分层标记和热图）可在不复制底层数据的情况下提供指导。

• 执行和验证循环：在图表创作之前执行查询，验证失败会触发 ES|QL 生成的纠正性重试。

尝试在 Kibana 中创建 AI 仪表板和 Vega-Lite 图表

要尝试使用自然语言仪表板创建和 Vega-Lite 图表，请升级到 Elastic 9.5（或开始免费试用），然后在 Kibana 中打开聊天。然后要求它根据您的数据构建仪表板。对于 Vega-Lite，您可以尝试请求创建想要但从未创建过的图表类型，例如散点图或气泡图。如果结果不完全准确，请告诉代理需要修改的内容。它会与您一起迭代。

这需要企业许可证。开始使用。

本文中描述的任何功能或功能性的发布和时间均由 Elastic 自行决定。当前尚未发布的任何功能或功能性可能无法按时提供或根本无法提供。

每年，自然灾害都迫使应急管理人员、军事指挥官和公共安全官员在紧迫的时间内做出关乎重大利益的高风险决策。在传统模式下，这些决策依赖于电话联络网、电子表格以及散落分布在数十人脑海中的机构知识。单单是多头协调带来的沟通成本就会白白消耗掉极其宝贵的黄金救援时间。

本文旨在展示 Elastic 如何驱动一套具备敏捷响应能力的智能体灾害应急协调系统，该系统能够检测威胁、推理后勤逻辑并自动采取行动。为了具体说明，我们构建了一个模拟：一场虚构的 4 级飓风威胁着汉普顿锚地海岸线，触发了七个军事设施中超过 137,000 多名人员的自动转移。

免责声明：这是完全为演示目的而构建的虚构场景。飓风 ELARA-26 并不存在。设施位置基于真实的公开地理数据（美国国防部 [DoD] 军事设施、靶场和训练区 [MIRTA] 数据集），但所有业务运行数据（如人员数量、安置容量、资产、联系电子邮件以及任务概况）完全纯属虚构。本演示中的任何内容均不反映实际的战备状态、作战能力或行动规程。

为什么自动化灾害应急响应需要地理空间与智能体协调

当自然灾害威胁到关键基础设施时，协调方面的挑战会立即显现：

• 哪些设施位于受影响区域内？

• 需要转移多少人员？

• 人员可以转移到哪里，那里的设施是否具有容载能力？

• 目前需要通知哪些人？

这些问题刻不容缓，获取答案也不能有片刻拖延。

部署管道：准备工作和设置

请按照此处示例存储库中的说明，通过 Cloud Connect 部署带有 Elastic 推理服务 (EIS) 的本地 Elastic 集群。

Elasticsearch 智能体灾害响应管道如何运作

该管道包含七个端到端协同工作层：

1. 数据摄取：全球灾害警报与协调系统 (GDACS) 灾害事件发送至 Elasticsearch

2. 摄取管道：GeoJSON 被摄取并规范化为 Elastic Common Schema (ECS)。

3. 地理空间富化：事件的受影响区域多边形与已建索引的军事设施边界进行匹配。

4. 警报通知：当灾害与任何设施交叉重合时，Kibana 检测规则将触发。

5. 工作流自动化：警报会触发一个 Kibana 工作流，从而启动 AI 智能体对话。

6. AI 推理：智能体对受影响的设施、其资产以及最近的支持设施进行推理，以确定所有资产和人员的转移方案。

7. 电子邮件通知：智能体会针对进出人员和/或资产向所有收件人发送电子邮件。

让我们逐层进行分析。

第 1 步：为具有地理边界的军事设施编制索引

其基础是来自 source.coop/seerai/hifld 的 DoD MIRTA 数据集。该数据集为每个设施提供 Point 类型的 geo_shape；即质心坐标，而非完整的边界多边形。

在 mitra-facilities 索引中，每个设施的文档除了包含 MIRTA 提供的原始信息外，还通过运营概况数据（均为虚构）进行了丰富：

正是这种包含丰富信息的索引，使 AI 智能体能够做出明智的分配决策——它不仅能识别“附近的基地”，还能筛选出那些具备可用安置容量、兼容任务类型以及能够接收迁入资产的后勤保障能力的基地。

第 2 步：采集和规范化 GDACS 事件

GDACS 发布关于地震、热带气旋、洪水、野火、火山和干旱的实时 GeoJSON 数据。我们使用自定义采集管道将此数据源采集到数据流 (logs-gdacs.events-*)，并将原始 GeoJSON 规范化为 ECS 字段。

GDACS 采集管道有几个值得注意的功能：

几何提取：质心作为 geo_point 存储以用于地图显示，而影响范围多边形则作为 geo_shape 存储在 gdacs.affected_area 中，该字段后续将用于相交查询。

严重性归一化：每种灾害类型都有不同的严重性等级。例如热带气旋按风速 (km/h) 衡量；地震则按里氏震级衡量。管道将它们全部映射到一个归一化的 0–100 分数：

归一化后的严重性分数随后会映射为相应的 severity_level 标签（低、中、高、极高），该标签用于检测规则中的警报严重性映射。

ECS 对齐：event.kind 设为 alert，event.category 设为 threat，时间戳映射到 event.start/event.end，并使用基于指纹的稳定 _id 实现去重。

第 3 步：地理空间信息富化：在索引时查找受影响的设施

Elasticsearch 的 geo_match 富化策略会在索引阶段将灾害影响区域多边形与各个设施边界进行匹配，无需在查询时执行连接操作。我们无需在搜索时进行查询，而是在采集管道中利用富化处理器，在文档被索引时将灾害影响区域多边形与各个设施的边界进行匹配。

该富化策略属于一种 geo_match 策略：

该处理器在采集管道末端运行：

INTERSECTS 可捕获边界与灾害影响区域多边形相接或重叠的任何设施，包括部分相交的情况。因此，每个 GDACS 事件文档都会存储一个 affected_facilities 嵌套数组，该数组会准确告诉我们哪些设施位于影响区域内。这个过程无需进行连接查询。

第 4 步：检测规则：针对设施受影响情况发出警报

Kibana 检测规则会监测 logs-gdacs.events-* 数据流，当某个 GDACS 事件包含至少一个受影响设施的信息时，该规则即触发警报：

该规则按小时运行（覆盖从 now-1h 到 now 的时间窗口），并使用动态严重性映射机制；由采集管道计算得出的 gdacs.severity_level 字段会自动决定警报的严重性。

此外，警报严重性还会通过字段映射影响风险评分：

规则触发时，会将完整的警报上下文（包括包含设施名称、类型和位置的富化 affected_facilities 数组）向下游传递给 Kibana 工作流。

第 5 步：工作流自动化：连接警报与智能体

Kibana 工作流处理从检测到响应的交接过程。自然灾害响应工作流由警报触发：

完整的警报负载信息（灾害类型、严重性、受影响区域以及受影响设施列表）会作为初始上下文转发给 AI 智能体，随后由智能体接手后续处理。

第6 步：AI 智能体：从数据到协同行动

mitra.response 智能体接收完整的警报负载信息，并在单次智能体循环中评估影响范围、查找接收设施、调配人员，以及发送疏散和接收通知，整个过程无需人工干预。

智能体有两个可用工具：

• mitra.nearest_facility使用 geo_shape 查询来检索 mitra-facilities 索引，并按距指定坐标的距离进行排序，返回最多 50 个具有可用容量的周边活跃设施；

• mitra.send_email 遍历设施对象的 JSON 数组并发送格式化的疏散或接收通知。

智能体的指令集定义了清晰的工作流：

1. 评估状况。解析警报，识别受影响的设施，并确定灾难范围。

2. 盘点需要迁移的人员与资产。统计各设施的人员数量、关键资产及安置需求。

3. 查找目标设施。针对每个受影响设施调用 mitra.nearest_facility，并排除仍处于危险区域的设施。

4. 制定分配决策。权衡单一设施与多设施安置方案，考量所属分支兼容性、安置容量及资产支持能力。

5. 发送协调电子邮件。向源设施发送疏散指令，向接收设施发送接收通知。

6. 生成摘要报告。生成简要报告，汇总受影响设施、总人数、转移资产、目标设施及相关注意事项，并发送至聊天中以供审查。

智能体的分配逻辑遵循现实世界的约束条件：不超过安置容量，尽可能优先进行同分支转移，使用联合基地应对多分支溢出需求，并优先考虑距离以尽量缩短运输时间。

最近设施工具

底层工作流查询使用带有圆形过滤器的 geo_shape 和 _geo_distance 排序：

可用容量是在查询时通过脚本字段计算得出的，该字段计算容纳容量减去当前人员数量。智能体利用该数据在各目的地之间分配人员，同时确保不超过容量限制。

飓风 ELARA-26：137,000 名人员的端到端智能体协同

飓风 ELARA-26 是一场 4 级风暴（最大风速 213 公里/小时），预计将在弗吉尼亚州的汉普顿锚地区域登陆。当系统接收到 GDACS 事件数据时，受影响区域的多边形与该地区的七个主要军事设施发生重叠。检测规则随之触发。工作流随即启动了智能体对话。

在单次智能体循环中，智能体执行了以下操作：

• 识别出受影响区域内的七处设施，共涉及 137,372 名人员。

• 调用 mitra.nearest_facility 查找风暴路径之外的接收设施。

• 根据可用安置容量和距离，将人员分配到九个接收设施。

• 生成并向所有七个受影响的设施发送疏散命令。

• 生成并向所有九个接收设施发送接收通知。

• 生成完整的协调摘要（如下所示）：

已疏散设施：

设施

人员

诺福克海军基地

50,000

小河堡-故事堡联合远征基地

18,000

欧西安纳海军航空站

15,355

欧西安纳海军航空站丹姆奈克分部

17,509

弗吉尼亚州国民警卫队彭德尔顿营基地

9,707

兰利-尤斯蒂斯联合基地

15,000

约克敦海军武器站

11,801

接收设施：

设施

距离

迁入人员

格雷格-亚当斯堡

97 公里

~40,000

匡提科海军陆战队基地

148 公里

~30,000

印第安黑德海军支援设施

151 公里

~30,000

安德鲁斯联合基地

180 公里

~30,000

帕图森特河海军航空站

141 公里

~10,000

国民警卫队巴特纳军营训练中心

174 公里

~5,000

国民警卫队贝瑟尼海滩训练基地

209 公里

~4,707

里瓦娜基地

140 公里

~7,500

国防通用物资供应中心

22 公里

~6,000

转移的资产包括运输车辆、直升机、巡逻艇、医疗单元、工程车辆、发电机、拖挂式水罐车、避难所套件以及通信系统。

自动化电子邮件通知

智能体确定分配方案后，便调用 mitra.send_email 并一次性发送了 16 封电子邮件；即向所有七个受影响设施发送疏散指令，向所有九个接收设施发送接收通知。每封邮件均包含目标设施、迁入人员数量、待转移资产以及协调联系人。原本需要耗费数小时通过电话逐级通知才能完成的工作，在智能体完成推理的那一刻便已自动处理完毕。

借助 RAG 和策略锚定增强智能体灾害应急响应

此演示纯粹基于结构化数据构建，例如容量数值、距离和运行状态。Elastic 的语义搜索和检索增强生成 (RAG) 功能可以通过两项新增功能使智能体变得更加智能：

历史响应检索：将以往的行动后报告、联邦紧急事务管理局 (FEMA) 事件摘要以及灾害响应记录作为向量嵌入编入索引。当新事件触发时，智能体能够从语义层面检索类似事件的处置方式，从而利用积累的机构经验（而非仅仅依赖容量计算）来指导分配决策。

策略与条令依据：索引 DoD 应急管理指令、设施业务连续性计划以及指挥官指导。智能体可以检索并引用指导响应的实际策略，确保每项决策都基于条令而非推断。

这两项功能都遵循相同的 Elastic 原生方法：推理管道会在索引时生成嵌入向量，并向智能体提供语义搜索工具。协调管道保持不变，智能体则变得更智能。

为什么 Elasticsearch 是公共部门智能体响应的理想平台

Elasticsearch 不是聊天机器人，也不是仪表板。它是具备响应能力的智能体工作流系统：它能够自主检测威胁、分析复杂的物流难题，并协调 137,000 人的转移工作，全程无需人工干预。之所以能实现这样的结果，是因为它所依赖的每项功能都集中在一个统一的平台中。

Elasticsearch 的地理空间支持功能（geo_point、geo_shape、富化策略以及基于距离的排序）能够处理空间推理，使大规模的相交检测和设施查询成为可能。语义搜索和向量嵌入技术确保了智能体的决策基于事实，即 AI 的推理建立在实际数据之上，而非凭空产生的“幻觉”假设。Kibana 的检测引擎、工作流、Agent Builder 以及 Agent Builder 工具将这一切无缝连接成一条管道，实现从原始事件到协同行动的完整流程，且无需任何外部粘合代码。

没有其他平台能像 Elastic 这样将这一切整合在一起。将实时索引、地理空间精度、语义检索和智能体编排全部集于单一堆栈中，并内置企业级安全和可观测性，这正是 Elastic 与其他工具的区别所在——那些工具或许在单一领域表现出色，但需要用户自行拼凑其余功能。

面向应急管理、消防、执法和公共卫生的智能体地理空间响应

凡是人员、设施和实时事件发生交集的场景，都可以应用同样的架构。具体的数据会发生变化，但处理流程不变。

应急管理：FEMA 和各州应急管理部门可以将避难所位置、集结区域和脆弱人群分布与美国国家气象局 (NWS) 发布的恶劣天气影响区域多边形进行对照映射，从而在风暴登陆前自动触发资源预置。

消防与紧急医疗服务：消防部门可以将救援力量位置和响应辖区叠加到野火蔓延范围或建筑火灾密集区，自动将互助请求指派给配备合适设备且距离最近的可用救援力量。

执法部门：执法机构可以将正在发生的事件位置与学校区域、关键基础设施和警员位置相关联，从而触发基于地理位置的封锁通知或资源调度，无需等待人工分类。

公立学校安全：学校区域可以监测校园边界内的实时威胁源。当威胁越过学校边界时，智能体立即通知管理部门、启动封锁通讯并协调执法部门响应，这一切均可以在调度员接听电话之前完成。

公共卫生：卫生部门可以将疾病监测数据或环境危险区域与诊所位置、人口密度图层和物资仓库库存进行比对，从而将资源调配至最需要的地方。

领域

用例

Elastic 功能

应急管理

将避难所位置与 NWS 发布的恶劣天气影响区域多边形进行匹配

geo_shape 富化 + Kibana 工作流

消防与紧急医疗服务

将救援力量位置与野火边界进行叠加

地理空间路径规划 + 最近设施查询

执法

将事件与学校区域和警员位置关联

基于地理位置的警报规则 + 智能体调度

公立学校安全

针对校园边界监测威胁源

检测规则 + 自动通知

公共卫生

将危险区域与诊所位置和物资仓库进行匹配

语义搜索 + 地理空间富化

尽管不同场景中的数据各不相同，但其底层模式——即数据采集、索引时富化、检测交集、触发智能体响应以及执行操作——是一样的。Elastic 为公共部门组织提供了一个平台，使其能够一次构建，多处适配。

本文中描述的任何功能或功能性的发布和时间均由 Elastic 自行决定。当前尚未发布的任何功能或功能性可能无法按时提供或根本无法提供。

该智能体可以从零开始构建仪表板，也可以与您已有的内容配合使用。查看仪表板时打开 AI Chat 侧边栏，它就会自动关联当前仪表板。您可以询问某项指标为何激增，按区域对其进行细分，或添加对比面板。您现有的仪表板会成为分析起点，而不只是最终产物。

幕后解析：我们如何在 AI Chat 中构建仪表板

我们通过“技能”让智能体学会特定任务；技能是说明如何处理特定问题的结构化描述。但是，构建仪表板技能意味着要教 LLM 生成有效的 Kibana 仪表板，而旧版 Saved Object API 使这一过程变得非常棘手：JSON 深度嵌套、版本之间存在细微差异，引用关系也很脆弱。我们需要一种全新的方法

专为以编程方式构建仪表板而打造的 API

新的仪表板 API 正是为这种场景而构建的。它没有暴露原始内部状态，而是为每种面板类型提供类型化、验证过的模式。API 负责在干净的外部结构与 Kibana 内部表示之间进行转换，因此代理可以专注于仪表板应包含的内容，而不是如何格式化它。

一个技能、一个工具、多种操作

dashboard-management 技能提供一个 manage_dashboard 工具，该工具接受有序的操作数组。每项操作都是一个独立动作：设置元数据、添加 Markdown 面板、根据自然语言创建基于 ES|QL 的可视化内容、编辑现有面板、将面板分组到可折叠分区，或重新定位网格中的项目。

智能体可以通过一次调用描述整个仪表板：标题、描述、分区，以及其中的每个面板：

操作按顺序执行，因此后面的步骤可以参考前面的步骤并在此基础上进行扩展。这种设计使对话始终集中在意图上，而不是实施细节上。

可视化管道：从自然语言到 ES|QL 再到可视化

当您请求生成仪表板时，智能体会探查您的数据，包括索引、字段映射和类型，然后规划可视化内容并调用 manage_dashboard。

每个面板都会经过各自的流水线：图表类型选择、ES|QL 生成、可视化配置和验证。我们将这一步从主智能体线程中隔离出来；每个面板的可视化构建都需要多次模型调用，如果混入主上下文，就会撑大上下文窗口，并干扰推理过程。

在 manage_dashboard 内部，所有面板会并发构建，然后按顺序重新组装。最终生成的是一个包含内嵌面板的完整仪表板，不会产生孤立的可视化内容，也不会出现同步问题。

为何将可视化创建纳入仪表板工具中

我们最初的方法是使用一个独立的 create_visualization 工具：每个面板调用一次，然后将每个附件移交给仪表板工具处理。这种方法确实可行，但每个可视化内容都需要单独的工具调用、独立的生命周期，以及明确的移交过程。更糟糕的是，在对话中编辑可视化内容并不会同步更新仪表板面板，容易让用户感到困惑。

我们将可视化创建直接纳入 manage_dashboard。同样的并行工作流仍会运行，但面板会直接组装到仪表板结构中，无需中间附件。调用更少，没有同步问题，生命周期也更统一。

独立可视化内容仍然可用；您可以通过附件引用将现有图表添加到仪表板中。但如果要从头开始构建，内联创建是更简洁的路径

面向安全团队

SOC 分析师和检测工程师在调查中途无法承受来回切换到仪表板编辑器的时间成本。借助 AI Chat，您可以按规则类型、主机或 MITRE 战术统计告警量，并在约一分钟内在对话线程中看到结果。随着威胁搜寻推进，您可以在不中断上下文的情况下逐步添加面板，例如进程执行异常、网络连接和时间线对比。

完成后即可保存。该仪表板可作为事件后复盘的参考、下一位分析师的起点，或每周威胁简报的基础，无需重复说明。

阅读这篇博客文章，详细了解安全团队如何使用仪表板创建功能以及近期推出的其他 AI Chat 功能。

面向可观测性和站点可靠性工程师 (SRE)

当服务在凌晨 2 点出现性能下降时，您没有时间从头开始构建仪表板。借助 AI Chat，SRE 可以描述所需指标（按服务划分的 p99 延迟、与部署事件相关的错误率、过去一小时的 Pod 重启次数），并在约一分钟内在调查对话线程中获得完整仪表板。随着排查思路逐渐清晰，智能体可以逐步细化仪表板：添加面板、更改时间窗口，或按区域细分。

保存仪表板后，它会立即在战情室中供所有加入事件处理会议的成员使用，并保持相同的面板和分析框架。事件结束后，它会成为事件后复盘的基础。

未来发展

我们正在推进 token 优化、更丰富的全屏交互、更广泛的面板支持，并持续提升质量。技术预览阶段正是确定开发优先事项的合适时机；如果有任何缺失，请通过顶部菜单中的“提交反馈”图标告知我们。

试用

升级到 Elastic 9.4（或开始试用），以全屏模式打开 AI Chat，并在真实调查场景中试用。您可以让智能体为您正在查看的指标生成图表，然后要求它继续细分。当分析脉络清晰成形后，即可保存并分享：相同的面板，相同的分析框架，无需重复说明。需要企业许可证（开始使用）。本文中描述的任何特性或功能，其发布及发布时间均由 Elastic 自行决定。当前尚未推出的任何特性或功能可能无法按时交付，甚至可能不会交付。

Kibana 在加载仪表板时如何获取数据

打开仪表板后，大部分面板（我们在内部称之为嵌入式面板）都会启动一个或多个 Elasticsearch 查询。但我们使用的不是同步 (sync) 搜索的简单调用和响应，而是异步 (async) 搜索（文档）的强大功能。

使用异步搜索，查询结果会保存在 Elasticsearch 中，而无需依赖任何特定的 HTTP 请求。这非常重要，因为它

• 使数据加载不受网络动荡的影响

• 为我们的后台搜索功能提供支持，让用户在等待长时间运行的仪表板或 Discover 会话时，仍能在 Kibana 中处理其他任务

提交初始查询后，Kibana 会监测搜索，以检测搜索何时完成并检索结果集。

传统轮询如何影响 Kibana 仪表板的加载时间

在传统轮询中，Kibana 会提交查询，关闭初始连接，然后定期检查 Elasticsearch 是否完成。

我们确实会在查询提交后给 Elasticsearch 一小段时间来完成搜索并返回结果。如果搜索完成得这么快，那就相当于一次简单的请求与响应。但是对于较长的搜索，初始连接会关闭，Kibana 开始定期检查搜索是否完成。这被称为轮询。

传统轮询的性能缺陷

从上图可以看出，这种方法的性能缺陷是：搜索很可能在 Kibana 的某个休眠间隔期间完成，从而造成时间损失。

在最坏的情况下（搜索在休眠期开始时完成），整个轮询间隔的时间都将浪费。

退避策略的影响

在进行轮询时，采用退避策略是一种标准做法。这意味着搜索时间越长，我们的轮询频率越低。

然而，这也意味着潜在的损失时间会随着搜索持续时间的增加而扩展。

轮询间隔如何产生锯齿延迟模式

将这些因素综合起来，我们损失的时间就成了一个阶梯状的锯齿函数。

在这里，峰值是最坏的情况，峰谷是最好的情况。这表明，传统轮询的成本取决于搜索持续时间（以及网络状况），可能从零到整个轮询间隔的全部时长不等。

持续轮询：Kibana 如何消除等待时间

传统轮询的问题在于 Kibana 和 Elasticsearch 之间缺乏基本的协调。理想情况下，Kibana 能够立即知道结果是否可用。那么，如果我们将轮询模式颠倒，使几乎所有时间都用于检查 Elasticsearch，而不再有任何休眠时间，会怎么样？

通过这种长轮询和取消睡眠间隔，因此一旦准备就绪，就能立即获得结果。

HTTP/1 降级

这个理论很可靠。那么，为什么启用连续轮询后，Kibana 部署的性能会下降这么多？

关键在于，此部署通过 HTTP/1 运行。在 HTTP/1 中，HTTP 请求与 TCP 连接一一对应。因此，多个长期轮询请求占用了浏览器有限的连接池，导致其他请求排队等待。

另一方面，在 HTTP/2+ 中，网络请求可以通过多路复用共享 TCP 连接，因此我们不会遇到这个问题。

因此，在 HTTP/2+ 中，持续轮询是一种优点，但在 HTTP/1 中，它却变成了一种缺点。

HTTP/1

HTTP/2+

TCP 连接

每个 HTTP 请求均有一个

多路复用（多个请求共享连接）

连续轮询行为

性能下降（连接池耗尽）

全面获益（立即见效）

Kibana 如何检测 HTTP 协议以优化轮询

HTTP/2 是推荐使用的协议，而且自 9.0 版起已成为 Kibana 的默认协议，因此不提供这项性能提升将是一大遗憾。另一方面，HTTP/1 体验已严重下降，任何尚未升级协议的本地部署均不应冒险使用该协议。答案显而易见：我们需要检测正在使用的协议，并采用最佳轮询策略。

Kibana 服务器当然有可能知道它使用的是哪种协议。但有一个问题：限制因素是浏览器的连接池。这意味着，真正重要的是浏览器所传达的信息。

由于代理的存在，这些并不总是相同的。

如果我们基于服务器协议进行优化，可能会有两种原因出错。

1. 在不应进行连续轮询的情况下进行轮询，会降低体验。

2. 未能在需要时应用连续轮询，就会错过优化机会。

幸运的是，现代浏览器提可以通过使用 PerformanceObserver 来检测任何已完成请求的最后一个网络跳转的协议。因此，我们会关注首次提交查询的协议，并在此基础上进行优化。

实验室结果：Kibana 中的连续轮询与传统轮询的对比

为了验证连续轮询，我们创建了查询延迟时间为 1 至 23 秒的仪表板，并测量了已启用和未启用优化的加载时间。然后，我们加载了带连续轮询和不带连续轮询的仪表板，以衡量收益（我们在 race-for-the-prize 中获得了很多乐趣）。

该模式与我们最初的锯齿状图相呼应。对于某些查询时长，收益很小，而对于其他查询时长，收益可达数秒。

结论

这一优化成功地用更高效的连续轮询策略取代了传统轮询固有的延迟。主要挑战在于有条件地实施此优化，以防止 HTTP/1 部署的性能下降。我们使用浏览器的 PerformanceObserver 来可靠地检测最终网络跳转所使用的协议，从而解决了这个问题。

实验室测试验证了这一理论，表明连续轮询可以在结果准备就绪后立即提供结果。平均而言，这将显著改善用户体验，使数据加载速度提高 25%。

这项工作是我们致力于缩短用户获得见解时间的最新举措。通过使 Kibana 成为 Elasticsearch 数据的更透明代理，我们推动了自身影响范围内的性能极限。更多精彩，敬请期待！

(在 2025 年，Thomas Neirynk 对提升 Kibana 仪表板性能的方法和动机进行了精彩的概述。这是该计划的最新进展。）

Kibana 仪表板构建器是什么？

想象一下：您只需用简单英文描述所需仪表板，就能看着它逐步呈现，并配有交互式图表、拖放式布局以及一键导出到 Kibana 的功能。

这正是 example-mcp-dashbuilder 的作用。它是一款开源 MCP（Model Context Protocol，模型上下文协议）应用，可将 AI 助手连接到 Elasticsearch，让您通过对话创建完整的 Kibana 仪表板。无需在菜单间反复点击。无需手动编写可视化配置。只需描述您的需求，AI 就会探查您的数据、编写 ES|QL 查询、构建图表，并在编辑器的聊天窗口中交付实时交互式仪表板。

从提示词到仪表板，仅需数秒

实际运行效果如下。您可以输入类似这样的内容：

“为我构建一个基于 logstash-* 的 Web 流量仪表板，包含总请求数、随时间变化的传输字节数、主要地理来源以及响应代码细分”

随后，AI 会：

1. 探查您的数据：列出索引并检查字段映射。

2. 编写 ES|QL 查询：根据您的架构量身定制，并使用正确的聚合。

3. 创建可视化内容：条形图、折线图、带迷你图的指标图、热力图、饼图。

4. 组织所有内容：可折叠分区、有意义的标题、合理的布局。

5. 渲染交互式预览：直接显示在聊天中，并配有工具提示、时间选择器和拖放功能。

每个图表在创建时都会内联显示，因此您可以实时查看进度。随后，view_dashboard 会显示完整的仪表板，所有面板都会按照 Kibana 的 48 列网格完成布局。

单个图表的内联预览

由 ES|QL 提供支持

所有数据检索均使用 ES|QL，即 Elasticsearch 的管道式查询语言。AI 不只是传递原始查询，还会利用其对 ES|QL 语法的内置知识，并结合您的数据结构信息，为每种可视化类型编写正确且高效的查询。

该服务器包含一份全面的 ES|QL 参考文档，并将其作为 MCP 资源提供。在编写任何查询之前，AI 会先读取这份参考文档，以了解可用的命令、函数和模式。结合数据可视化最佳实践指南（同样作为资源提供），AI 不仅知道如何查询，还懂得什么样的可视化效果更好：

• 针对时间序列使用 BUCKET(@timestamp, 1 day)；始终按时间字段 SORT 排序。

• 使用 | SORT value DESC | LIMIT 6 将饼图限制为最多六个扇区。

• 类别比较选用条形图，趋势分析选用折线图，关键绩效指标 (KPI) 选用指标图。

AI 驱动的数据探索，支持开放式分析

在脑海中设计好一个仪表板并将其构建出来是一回事。询问“这个索引中有哪些值得关注的内容？”并获得有用答案则更难；这要求 AI 懂得如何探索数据，而不仅仅是绘制图表。

example-mcp-dashbuilder 提供了一个 analysis://guidelines 资源，用于定义结构化探索流程：剖析数据、运行有针对性的聚合、呈现值得调查的模式、为最值得关注的发现构建图表，并提出用户接下来可能需要的下钻查询。“分析我的日志”或“在这个索引中寻找模式”等触发短语，会促使 AI 在执行任何其他操作前先读取该操作手册。因此，开放式提示词生成的是逻辑连贯的分析过程，而不是一堆随机图表。

结果是：您可以将一个陌生索引交给 AI，并获得一个起点，包括一个仪表板，以及一组简短提示，例如“以下是我注意到的情况，需要我深入分析其中某一项吗？”

Kibana 仪表板的导出与导入：完整闭环

导出/导入闭环让 example-mcp-dashbuilder 对已经在 Kibana 中工作的团队真正显现价值。example-mcp-dashbuilder 是一个独立工具，也是位于编辑器内的对话式仪表板界面，但它不会让您的工作局限于此。在这里构建的仪表板可以在需要时导入 Kibana；现有 Kibana 仪表板也可以反向导入，以便进行 AI 辅助编辑。

导出到 Kibana

当您对仪表板满意后，只需一条命令即可导出：

将此仪表板导出到 Kibana

每个面板都会转换为 Kibana Lens 原生可视化内容。转换过程会保留：

• ES|QL 查询：直接作为 Lens ES|QL 数据源传输。

• 网格位置：沿用 Kibana 使用的 48 列系统，因此您的布局看起来完全一致。

• 自定义颜色：系列调色板、指标背景、热力图色带。

最终生成的是一个功能完整的 Kibana 仪表板。不是屏幕截图。不是嵌入内容。而是一个真实的仪表板，您可以在 Kibana 中分享并继续编辑。

Kibana 仪表板与 Cursor 聊天中的仪表板并排显示。

从 Kibana 导入

该闭环同样支持反向操作：

“导入 ID 为 abc-123 的 Kibana 仪表板”

这会获取现有 Kibana 仪表板，将其 Lens 可视化内容转换回可编辑的图表配置，保留网格布局和分区，并将所有内容加载到 example-mcp-dashbuilder 中。之后，您可以使用自然语言修改该仪表板并重新导出。

这使得 AI 成为您现有 Kibana 工作流程中的协作者，而不是替代品。

自定义主题和颜色

想要品牌化仪表板？直接提出需求：

“创建一个粉色主题的仪表板，并使用自定义颜色”

所有可视化类型都支持自定义颜色配置：

• 图表：palette 接受用于系列和扇区的十六进制颜色数组。

• 指标：color 设置背景颜色。

• 热力图：colorRamp 定义从低值到高值的颜色渐变。

AI 能自然理解主题请求。输入“海洋主题”，它会选择蓝色和蓝绿色。输入“匹配我们的品牌颜色”并提供十六进制值，这些颜色会在导出时一并带入 Kibana。

采用自定义颜色的主题仪表板。

example-mcp-dashbuilder 的工作原理：MCP 架构

example-mcp-dashbuilder 基于 MCP 构建；MCP 是用于连接 AI 助手与外部工具和数据的开放标准。以下是其高层级架构概览：

MCP 服务器提供 25 个可由 AI 直接调用的工具，涵盖从运行 ES|QL 查询到导出仪表板的各类操作。同时，它还提供少量仅供应用内部调用的工具，供内联预览用于获取数据、持久化布局更改和检测时间字段。它提供三类资源：数据可视化最佳实践指南、ES|QL 参考文档，以及会在遇到开放式提示词（如“分析我的日志”“这个索引中有哪些值得关注的内容？”）时触发的深度分析操作手册。它既可以通过 stdio 运行，也可以通过 HTTP 运行；HTTP 传输支持流式响应和会话管理，因此多个客户端可以连接到同一台服务器。

MCP App 是交互式预览界面。它使用 React、Elastic Charts 和 Elastic UI 构建，并打包成一个独立且自包含的 HTML 文件。当 AI 调用 view_dashboard 或创建图表时，宿主程序会在沙盒化 iframe 中渲染此 HTML。该应用完全通过 MCP Apps 协议与服务器通信，并通过 postMessage 使用 callServerTool() 来获取数据、保存布局和检测时间字段。无需 localhost 服务器，无需配置端口，也没有外部网络依赖。

这意味着它可以与任何兼容 MCP 的客户端配合使用：Cursor、Claude Desktop、Claude.ai、VS Code with Copilot 等。

example-mcp-dashbuilder 支持哪些图表类型？

在撰写本文时，支持六种图表类型，涵盖了最常见的仪表板场景：

类型

适用场景

示例

条形图

类别比较

按地理来源划分的请求数

折线图

随时间变化的趋势

每小时传输的字节数

区域

随时间变化的数据量

随时间变化的请求量

饼图

局部与整体的比例关系（最多六个扇区）

响应代码分布

指标

带迷你图的单一 KPI

总请求数及每小时趋势

热力图

跨两个维度的模式

按星期几和小时划分的请求数

仪表板支持用于组织内容的可折叠分区、可自动检测时间字段的时间选择器，以及保存多个仪表板并在其间切换的功能；并行聊天会话通过贯穿每次工具调用的 dashboardId 保持相互隔离。

如何安装和运行 example-mcp-dashbuilder

example-mcp-dashbuilder 是开源项目，可直接使用。您需要 Node.js 22+、一个 Elasticsearch 实例（本地或 Elastic Cloud），以及一个兼容 MCP 的客户端。

Claude Desktop：从 GitHub Releases 下载最新 .mcpb 文件，然后双击安装。Claude Desktop 会提示您输入 Elasticsearch 凭据。

Cursor / Claude Code / VS Code Copilot：将您的 MCP 配置指向已发布的 tarball 压缩包；无需克隆，也无需 npm install：

将 ES_NODE, ES_API_KEY（或 ES_USERNAME / ES_PASSWORD）和 KIBANA_URL 设置为环境变量。如果您更倾向于基于源代码运行，请克隆仓库并运行 npm run setup，以启动交互式向导；该向导可处理本地 Elasticsearch 和 Elastic Cloud（Cloud ID + API 密钥）。

然后开始构建：

“探索 logs 索引，并尽可能为我构建最具洞察力的仪表板”

剩下的交给 AI 即可。😉

路线图：example-mcp-dashbuilder 即将推出的功能

这是一个早期版本，我们正在积极开发中。我们专注的一些领域：

• 更多图表类型：仪表图、环形图、树状图、数据表和标签云，以覆盖 Lens 的完整功能。

• 将仪表板推送到 Git：将仪表板配置写入代码仓库，用于版本控制和代码审查工作流。

• 更友好的错误处理体验：当 ES|QL 查询失败时提供更详细的反馈，并给出常见修复建议。

• 更丰富的分析流程：扩展深度分析操作手册，以覆盖更多数据形态（日志、指标、链路追踪）。

我们很期待看到您用它构建出的成果。欢迎试用、提交 issue，并告诉我们哪些可视化内容和工作流对您的团队最有帮助。

GitHub：elastic/example-mcp-dashbuilder

致谢

感谢 Walter Rafelsberger 和 Tim Schnell 在实现方面作出的贡献。

常见问题解答

什么是 example-mcp-dashbuilder？example-mcp-dashbuilder 是一款开源 MCP (Model Context Protocol) 应用，用于将 AI 助手连接到 Elasticsearch。它让您可以用简单英文描述 Kibana 仪表板，并自动生成 ES|QL 查询、创建可视化内容，在编辑器的聊天窗口中交付实时交互式仪表板。

example-mcp-dashbuilder 使用哪种查询语言来检索数据？所有数据检索均使用 ES|QL，即 Elasticsearch 的管道式查询语言。MCP 服务器包含一份内置 ES|QL 参考文档，AI 在编写任何查询之前都会先阅读该参考文档，从而确保每种可视化类型都具备正确语法和高效聚合。

我可以将使用 example-mcp-dashbuilder 构建的仪表板导出到 Kibana 吗？可以。运行“将此仪表板导出到 Kibana”会将每个面板转换为真正的 Kibana Lens 可视化内容，并保留 ES|QL 查询、48 列网格布局、自定义颜色和系列调色板。最终呈现的是一个功能完整的 Kibana 仪表板，而不是屏幕截图或嵌入内容。

我可以将现有 Kibana 仪表板导入 example-mcp-dashbuilder，以便进行 AI 辅助编辑吗？可以。只需提供 Kibana 仪表板 ID，系统便会获取现有仪表板，将其 Lens 可视化内容转换为可编辑的图表配置，并加载到 example-mcp-dashbuilder 中。之后，您可以使用自然语言修改仪表板，并重新导出到 Kibana。

哪些 MCP 客户端与 example-mcp-dashbuilder 兼容？example-mcp-dashbuilder 可与任何兼容 MCP 的客户端配合使用，包括 Cursor、Claude Desktop、Claude.ai 和 VS Code with Copilot。它同时支持 stdio 和 HTTP 传输，无需 localhost 服务器或端口配置。

example-mcp-dashbuilder 支持哪些图表类型？当前版本支持六种图表类型：条形图、折线图、面积图、饼图、指标图（带迷你图）和热力图。计划新增仪表图、环形图、树状图、数据表和标签云，以覆盖 Kibana Lens 的完整功能。

运行 example-mcp-dashbuilder 需要什么？您需要 Node.js 22 或更高版本、一个 Elasticsearch 实例（本地或 Elastic Cloud），以及一个兼容 MCP 的客户端。设置环境变量 ES_NODE、ES_API_KEY（或 ES_USERNAME/ES_PASSWORD）和 KIBANA_URL。对于 Claude Desktop，请从 GitHub Releases 下载 .mcpb 文件，然后双击安装。

变量控件是什么？

如果您以前用过 Kibana 仪表板，您可能知道我们经典的仪表板控件。那些方便的下拉菜单可以显示数据中的数值，让您只需点击几下就能筛选。

可变控件表面上看起来很相似，但却有巧妙的变化：它们并非自动筛选仪表板上的每个面板，而是可以直接插入单个可视化内部的 ES|QL 查询中。

这意味着您可以决定每个控件的适用范围。更妙的是，您可以将它们用于各种创意技巧，例如实时调整时间间隔、切换细分字段，或更改可视化参数。简而言之，它们为您的仪表板提供了真正的交互式体验，使您能够更快、更轻松地获得见解。

变量控件用例

好吧，变量控件听起来很有用，但您实际上能用它们做些什么？下面举例说明它们如何提升仪表盘的功能性：

筛选已选择的可视化内容

想要筛选部分可视化内容，但保留其他内容不变？变量控件功能可以让您做到这一点。选择要响应的面板，并在可视化的 ES|QL 查询中将它们连接起来。

选择不同的时间间隔

让用户可以在“5 分钟”、“1 小时”、“1 天”或任何合理的时间间隔之间切换。构建有预定义时间间隔的变量控件，并将其连接到时间序列查询。

更改函数

与其为每个操作创建多个图表，不如让仪表板用户选择自己想要查看最大值、平均值、不同百分位数或任何其他聚合器。

按不同字段分组

有时，您需要在调查过程中按不同维度对数据进行细分。通过变量控件，您可以定义多个“分组依据”字段，让仪表板用户选择有助于他们发现见解的字段。

如何创建？

创建变量控件的最简单（可能也是最有趣）方法是直接从可视化中的 ES|QL 查询编辑器中创建。只需开始输入查询，使用自动完成菜单，Kibana 就会帮助您创建。

但是如果您更喜欢以变量本身为基础开始创建，也可以前往：添加面板 → 控件 → 变量控件，然后在创建控件后将变量添加到可视化中。

示例 1：具有多值选择的筛选控件

1. 选择由 ES|QL 查询驱动的可视化，并在 WHERE 条件中单击“创建控件”。

2. 您将自动被重定向至变量创建弹出面板，此时“来自查询的值”这一类型已自动选定，并且变量的名称已经预填。请记住，控件的名称必须以“?...”开头，以便在可视化查询中使用。

您通常需要这样的查询来获取字段中的值，并根据仪表板中选择的时间范围进行更新：

3. 保存控件时，您会看到它出现在仪表盘的顶部，可视化查询也会用变量控件名称进行更新。

4. 如果要在控件中添加多值选择，则需要在查询中使用MV_CONTAINS函数，并在步骤 2 创建控件时选择“允许多选”（9.3 及更高版本可用）。

示例 2：时间间隔控制

如果您正在构建时间序列，可轻松地为日期直方图间隔添加一个变量控制：

1. 为时间序列编写 ES|QL 查询时，单击“创建控件”。为时间间隔创建变量时，最好使用 TBUCKET 而非 BUCKET，这样它就可以接受更具可读性的间隔，例如“1 小时”、“1 天”等。我们也会很快推出 TBUCKET 自动选项，以便自动适应时间范围。

2. 确定用于填充下拉菜单选项的时间间隔。

3. 在下拉菜单中选择不同的时间间隔，查看可视化如何变化。

示例 3：函数变量

1. 用“静态值”类型控件构建一个变量，并在下拉菜单的值中添加函数名。为了替换函数，请使用以“??...”开头的变量名。

2. 在 ES|QL 查询中包含变量名称。

示例 4：字段变量

1. 您可以使用“静态值”类型的控件，并填入所需字段的名称。为了让变量名在字段中生效，使用以“??...”开头的变量名非常重要。

2. 在可视化查询中引用想要的变量。

Discover 中的变量控件

变量控件不仅仅是仪表盘的功能，还可以直接在 Discover 的 ES|QL 编辑器中使用。您可以在 Discover 中构建控件，以获得更快的数据探索体验，并将其引入仪表盘，反之亦然。

技术细节

到现在为止，您可能已经注意到变量控件有一些规则，比如它们可以引用查询的哪些部分，以及您需要使用的命名前缀（“?...”用于值，“??...”用于字段或函数）。这是因为变量不仅仅是在客户端进行简单的字符串替换。它们实际上是查询语言本身最重要的因素（在 ES|QL 中称为参数）。

这种设计具有一些很大的优势。首先，Kibana 可以理解每个变量的上下文，这使我们能够自动为您生成并预先填充其配置。它也更加安全：由于该语言严格验证变量输入，因此可以防止恶意注入，并在出现异常时轻松处理错误。此外，它将复杂的验证和错误处理转移到服务器而不是客户端，从而提高了性能和稳定性。关于性能，最佳做法是创建包含快速查询的变量，因为它们在仪表盘之前加载，所以慢速查询会影响整个仪表盘的性能。

当然，这种架构暂时也有一些限制。变量尚不支持用于筛选的“Any”选项，目前也不能与LIKE或 FROM（用于切换数据源）等操作符结合使用。好消息是什么？我们正在着手添加这些功能。

控件的未来发展趋势

我们不会就此止步！我们所关注的一些改进包括：

✨ 在仪表板上随处放置控件的能力

✨ 控件链式连接：意味着一个控件的输出成为下一个控件的输入。

✨ 选择选项更理想，比如变量的“任意”选择

✨ 新控件类型（搜索类型控件和数据源变量）

✨ 以及更多您一直要求的生活质量改进，比如预筛选常规控件

如果您有任何想法或反馈，欢迎向我们提出。

在本文中，我们将实现这一目标。我们将创建一个应用程序，它可以获取仪表盘的图像，分析映射，然后生成仪表盘，而无需接触 Kibana！

步骤：

1. 后台& 应用程序工作流程

2. 准备数据

3. LLM 配置

4. 应用功能

后台& 应用程序工作流程

我首先想到的是让 LLM 生成整个 NDJSON 格式的 Kibana保存对象，然后将它们导入 Kibana。

我们尝试了几种型号：

• 双子座 2.5 pro

• GPT o3 / o4-mini-high / 4.1

• 克劳德 4 号十四行诗

• Grok 3

• Deepseek (Deepthink R1)

至于提示语，我们从最简单的开始：

尽管我们看了一些简单的示例，并详细解释了如何建立每种可视化，但我们还是一无所获。如果您对这项实验感兴趣，请点击此处了解详情。

采用这种方法的结果是，在尝试将 LLM 生成的文件上传到 Kibana 时看到了这些信息：

这意味着生成的 JSON 无效或格式不当。最常见的问题是 LLM 生成不完整的 NDJSON、产生参数幻觉，或者返回普通 JSON 而非 NDJSON，无论我们如何努力去执行其他操作。

受这篇文章的启发--搜索模板比 LLM 自由式更有效--我们决定给 LLM 提供模板，而不是要求它生成完整的 NDJSON 文件，然后我们在代码中使用 LLM 给出的参数来创建适当的可视化。

申请工作流程如下：

为简单起见，我们将省略一些代码，但您可以在 本 笔记本上找到完整应用程序的工作代码 。

准备工作

在开始开发之前，您需要具备以下条件：

1. Python 3.8 或更高版本

2. VenvPython 环境

3. 运行的 Elasticsearch 实例及其端点和 API 密钥

4. 存储在环境变量 OPENAI_API_KEY 下的 OpenAI API 密钥：

准备数据

在数据方面，我们将保持简单，使用 Elastic 样本网络日志。您可以在此了解如何将这些数据导入群集。

每份文档都包含向应用程序发出请求的主机的详细信息，以及请求本身及其响应状态的信息。下面是一个文件示例：

现在，让我们抓取刚刚加载的索引的映射，kibana_sample_data_logs ：

我们将把映射与稍后加载的图像一起传递。

LLM 配置

让我们对 LLM 进行配置，使其使用结构化输出来输入图像，并接收包含我们需要传递给函数的信息的 JSON，以生成 JSON 对象。

我们安装依赖项：

Elasticsearch 将帮助我们检索索引映射。Pydantic 允许我们在 Python 中定义模式，然后要求 LLM 遵循这些模式，而LangChain框架则有助于更轻松地调用 LLM 和人工智能工具。

我们将创建一个 Pydantic 模式，以定义我们希望从 LLM 得到的输出。我们需要从图片中了解图表类型、字段、可视化标题和仪表盘标题：

对于图像输入，我们将发送一个我刚刚画好的仪表盘：

现在我们声明 LLM 模型调用和图像加载。该函数将接收 Elasticsearch 索引的映射和我们要生成的仪表盘图像。

通过with_structured_output ，我们可以使用 PydanticDashboard 模式作为 LLM 生成的响应对象。通过Pydantic，我们可以定义带有验证功能的数据模型，从而确保 LLM 输出与预期结构相匹配。

要将图像转换为 base64 并作为输入发送，可以使用在线转换器 或用代码完成。

LLM 已经掌握了 Kibana 面板的上下文，因此我们不需要在提示中解释所有内容，只需提供一些细节，确保它不会忘记自己正在使用 Elasticsearch 和 Kibana。

让我们来分析一下提示：

部门

原因

您是根据 Kibana 9.0.0 版本的图像分析 Kibana 仪表板的专家。

通过强化 Elasticsearch 和 Elasticsearch 版本，我们降低了 LLM 产生旧参数/无效参数的可能性。

您将获得一个仪表盘图像和一个 Elasticsearch 索引映射。

我们解释说，图片是关于仪表盘的，以避免法律硕士做出任何错误的解释。

下面是仪表盘所基于的索引的索引映射，使用它可以帮助你理解数据和可用字段。索引映射： {index_mappings}

提供映射至关重要，这样 LLM 才能动态选择有效字段。否则，我们就可能在这里硬编码映射，这太死板了，或者依靠图像包含正确的字段名，这也不可靠。

根据图像中可见的内容，只包含与每个可视化相关的字段。

我们必须添加这一增强功能，因为有时它会尝试添加与图像无关的字段。

这将返回一个包含要显示的可视化数组的对象：

处理 LLM 答复

我们在上创建了一个 2x2 面板仪表盘示例，然后使用 "获取仪表盘 API "将其导出为 JSON 格式，然后将面板存储为可视化模板（饼状、条状、度量），在这些模板中，我们可以替换部分参数，根据问题创建带有不同字段的新可视化。

您可以在此处查看模板 JSON 文件。请注意我们是如何用 {variable_name} 更改我们稍后要替换的对象值的。

根据 LLM 提供的信息，我们可以决定使用哪个模板，替换哪些值。

fill_template_with_analysis 将接收单个面板的参数，包括可视化的 JSON 模板、标题、字段和可视化在网格上的坐标。

然后，它会替换模板的值，并返回最终的 JSON 可视化。

为了简单起见，我们将为 LLM 决定创建的面板分配静态坐标，并生成如上图所示的 2x2 网格仪表盘。

根据 LLM 决定的可视化类型，我们将选择一个 JSON 文件模板，并使用fill_template_with_analysis 替换相关信息，然后将新面板追加到稍后用于创建仪表盘的数组中。

仪表盘准备就绪后，我们将使用 创建 仪表盘 API 将新的 JSON 文件推送到 Kibana 以生成仪表盘：

要执行脚本并生成仪表盘，请在控制台中运行以下命令：

最终结果将是这样的

结论

在将文本转化为代码或将图像转化为代码时，LLM 展示了其强大的视觉能力。仪表盘 API 还能将 JSON 文件转化为仪表盘，而通过 LLM 和一些代码，我们就能将图片转化为 Kibana 仪表盘。

下一步是通过使用不同的网格设置、仪表盘大小和位置来提高仪表盘视觉效果的灵活性。此外，为更复杂的可视化和可视化类型提供支持也是对该应用程序的有益补充。

与第一次 Spotify Wrapped 分析的不同之处

在第一篇博客中，我们直接使用 Spotify 导出，没有执行任何规范化任务或其他数据处理。这一次，我们将使用相同的数据，但我们将对数据进行一些处理，使数据更加可用。这将使我们能够回答更复杂的问题，例如：.....：

• 排名前 100 的歌曲的平均时长是多少？

• 排名前 100 的歌曲平均受欢迎程度是多少？

• 一首歌曲的中位收听时长是多少？

• 我跳得最多的曲目是什么？

• 我什么时候喜欢跳过曲目？

• 我是否在一天中的某个时段比其他时段听得更多？

• 我是否在一周中的某一天比其他日子听得更多？

• 是特别感兴趣的月份吗？

• 聆听时间最长的艺术家是谁？

Spotify Wrapped 每年都会给你带来有趣的体验，向你展示今年你都听了些什么。它不会提供每年的变化情况，因此你可能会错过一些曾在你的前十名中，但现在已经消失的艺术家。

处理 Spotify Wrapped 数据以供分析

在第一个和第二个职位中，我们处理数据的方式有很大不同。如果您想继续使用第一篇文章中的数据，您需要考虑一些字段名称的变化，还需要恢复到 ES|QL 来进行某些提取，如hour of day on the fly。

不过，大家应该都能跟上这个帖子。在Spotify 到 Elasticsearch存储库中进行的数据处理包括向 Spotify API 询问歌曲的持续时间、受欢迎程度，以及重命名和增强某些字段。例如，Spotify 导出中的artist 字段本身只是一个字符串，并不代表功能或多艺术家曲目

使用仪表盘可视化 Spotify Wrapped 数据

我在 Kibana 中创建了一个仪表盘，将数据可视化。仪表板可在此处获取，您可以将其导入到您的 Kibana 实例中。仪表盘的内容相当广泛，可以回答上述许多问题。

让我们一起来了解一些问题以及如何回答这些问题！

排名前 100 的歌曲的平均时长是多少？

要回答这个问题，我们可以使用 Lens 或 ES|QL。让我们来探讨这三种方案。让我们用 Elasticsearch 的方式来正确表述这个问题。我们要找出排名前 100 的歌曲，然后计算所有这些歌曲加在一起的平均持续时间。用 Elasticsearch 术语来说，就是两个聚合：

1. 找出排名前 100 的歌曲

2. 计算这 100 首歌曲的平均持续时间。

Lens

在 Lens 中，这非常简单：创建一个新的 Lens，切换到表格，然后将title 字段拖放到表格中。然后点击title 字段，将大小设置为 100，并设置accuracy 模式。然后将duration 字段拖放到表中，并使用last value ，因为我们只需要每首歌曲持续时间的最后一个值。同一首歌只有一个持续时间。在last value 聚合的底部有一个摘要行下拉菜单，选择average ，它就会显示出来。

ES|QL

与 DSL& 聚合语言相比，ES|QL 是一种相当新鲜的语言，但它非常强大且易于使用。要在 ES|QL 中回答同样的问题，您需要编写以下查询：

让我带您逐步了解这个 ES|QL 查询：

1. from spotify-history - 这就是我们使用的索引模式。

2. stats duration=max(duration), count=count() by title - 这是第一次汇总，我们正在计算每首歌曲的最长持续时间和每首歌曲的计数。我们使用max 而不是 Lens 中使用的last value ，这是因为 ES|QL 目前没有首字母或末字母。

3. sort count desc - 我们按照每首歌曲的收听次数进行排序，因此收听次数最多的歌曲排在最前面。

4. limit 100 - 我们将结果限制在前 100 首歌曲中。

5. stats Average duration of the songs=avg(duration) - 我们计算歌曲的平均持续时间。

我是否对某个月份特别感兴趣？

要回答这个问题，我们可以借助运行时字段和 ES|QL 使用 Lens。我们马上就会发现，数据中没有直接表示month 的字段，而是需要从@timestamp 字段中计算出来。有多种方法可以做到这一点：

1. 使用运行时场，为透镜供电

2. ES|QL

我个人认为，ES|QL 是更整洁、更快捷的解决方案。

我们可以利用DATE_EXTRACT 函数从@timestamp 字段中提取月份，然后对其进行汇总。使用 ES|QL 可视化功能，我们可以将其放到仪表盘上。

每位艺术家每年的收听时长是多少？

这样做的目的是要看艺术家是否只是一朝一夕的事，或者是否会再次出现。如果我没记错的话，Spotify 只显示年度包装前 5 名的艺术家。也许你的第 6 位艺术家一直保持不变，或者他们在第 10 位之后发生了很大变化？

最简单的表示方法之一就是百分比柱形图。为此，我们可以使用透镜。跟着步骤走：

拖放listened_to_ms 字段。该字段以毫秒为单位表示您聆听一首歌曲的时间。默认情况下，Lens 将创建median 聚合，我们不希望这样，请将其更改为sum 。在顶部选择percentage ，而不是stacked 作为条形图类型。细目请选择artist ，并注明前 10 名。在Advanced 下拉菜单中，不要忘记选择accuracy mode 。现在，每一个色块都代表了你对这位艺术家的聆听程度。根据时间选择器的不同，条形图可能代表从天、周、月到年的数值。如果需要每周细分，请选择@timestamp ，并将mininum interval 设为year 。从我的情况来看，Fred Again.. 是我听得最多的艺术家，我的总收听时间中有近 12% 被Fred Again.. 占用。我们还看到，2024 年，Fred Again.. 略有下降，但Jamie XX 很大程度上有所增长。如果我们只比较条形图的大小。我们还可以看出，在Billie Eilish 不断播放的同时，2024 酒吧也在不断扩大。这意味着我在 2024 年比 2023 年收听了更多的Billie Eilish 。

每位艺术家每次收听时间与总体收听时间相比，收听率最高的曲目是什么？

这真是一个令人咂舌的问题。让我试着解释一下我想说的话。Spotify 会告诉你某位艺术家的热门歌曲，或你的 5 首热门歌曲。这确实很有趣，但艺术家的细分情况又如何呢？我的所有时间都被一首反复播放的歌曲消耗掉了，还是平均分配？

创建一个新镜头，选择Treemap 作为类型。对于metric ，与之前相同：选择sum 并使用listened_to_ms 作为字段。对于group by ，我们需要两个值。第一个是artist ，然后添加第二个title 。中间结果是这样的

让我们将其更改为前 100 名艺术家，并取消选择高级下拉菜单中的other ，同时启用精确度模式。标题改为前 10 名，并启用精确度模式。最终结果是这样的

这究竟说明了什么？在不考虑任何时间成分的情况下，我们可以知道，在我所有的 Spotify 收听记录中，我花了 5.67% 收听Fred Again.. 。其中，我花了 1.21% 来收听Delilah (pull me out of this) 。有趣的是，是否有一首歌占据了一位艺术家的位置，或者是否还有其他歌曲。树状地图本身就是一种很好的数据分布表现形式。

我是否在特定的时间和日期收听？

那么，我们可以利用Heat Map.Lens 可视化来回答这个超级简单的问题。创建新透镜，选择Heat Map 。对于Horizontal Axis ，选择dayOfWeek 字段，并将其设置为Top 7 ，而不是 Top 3。Vertical Axis 选择hourOfDay ，Cell Value 选择简单的Count of records 。现在，这将产生这个面板：

在这本《透镜》中有几处恼人的地方，让我在口译时感到不安。让我们试着清理一下。首先，我不太在意图例，请使用顶部的三角形、方形和圆形符号，并禁用它。

现在，令人讨厌的第二部分是日期排序。周一、周三、周四或其他任何时间，取决于你的价值观。hourOfDay 已正确排序。对日期进行排序的方法是一种有趣的黑客手段，即使用Filters 而不是Top Values 。点击dayOfWeek 并选择Filters ，现在应该是这样的：

现在开始输入日期。每天一个过滤器。"dayOfWeek" : Monday 并给它贴上标签Monday ，然后冲洗并重复。

但需要注意的是，Spotify 以 UTC+0 为单位提供数据，不包含任何时区信息。当然，他们也会提供 IP 地址和您收听的国家，我们可以从中推断出时区信息，但这可能会很复杂，而且对于像美国这样有多个时区的国家来说，这可能太麻烦了。这一点很重要，因为 Elasticsearch 和 Kibana 都支持时区，只要在@timestamp 字段中提供正确的时区，Kibana 就会自动根据浏览器时间调整时间。

我们可以看出，我在工作时间是一个非常活跃的倾听者，而在周六和周日就不那么活跃了。

结论

在这篇博客中，我们对 Spotify 数据所提供的错综复杂的信息进行了深入探讨。我们展示了一些简单快捷的方法来启动和运行一些可视化功能。能对自己的收听历史拥有如此大的控制权，实在令人惊叹。查看该系列的其他部分：

• 第 1 部分：如何在 Kibana 中制作自己的 Spotify 包裹

• 第 3 部分：异常检测人口工作

• 第 4 部分：检测数据中的关系

• 第 5 部分：用矢量找到最好的音乐朋友

以下是我们将在本教程中配置的内容的示意图：

使用 Ollama 设置本地推理

Ollama 是快速测试一组精选的用于本地推理的开源模型的绝佳方法，深受 AI 开发者的欢迎。

在裸机上运行 Ollama

在 Mac、Linux 或 Windows 上进行本地安装是利用您可能拥有的任何本地 GPU 功能的最简单方法，尤其是对于拥有 M 系列 Apple 芯片的用户而言。安装 Ollama 后，您可以使用以下命令下载并运行 DeepSeek R1。

您可能需要调整参数大小，使其适合您的硬件。可用的大小可以在此处找到。

您可以在终端中与模型聊天，但当您按下 Ctrl+D 退出命令或输入“/bye”时，模型仍会继续运行。要查看模型仍在运行，请输入：

在容器中运行 Ollama

或者，运行 Ollama 的最快方法是使用 Docker 这样的容器引擎。使用本地计算机的 GPU 并不总是那么简单，具体取决于环境，但只要容器具备足够的 RAM 和存储空间以运行多 GB 的模型，就能轻松完成快速测试设置。

在 Docker 中启动并运行 Ollama 就像执行以下命令一样简单：

这将在当前目录中创建一个名为“ollama”的目录，并将其挂载到容器内以存储 Ollama 配置和模型。根据所使用的参数数量，它们的大小可能从几 GB 到几十 GB 不等，因此请确保选择拥有足够可用空间的卷。

注意：如果您的计算机上有 Nvidia GPU，请确保安装 Nvidia 容器工具包，并在上面的 docker 运行命令中添加“--gpus=all”。

一旦 Ollama 容器在您的机器上运行起来，您就可以拉取一个类似 deepseek-r1 的模型：

与裸机方法类似，您可能需要调整参数大小以适合您的硬件。可用的大小可以在 https://ollama.com/library/deepseek-r1 中找到。

模型拉取完成后，您可以输入“/bye”退出提示符。要验证模型是否仍在运行：

使用 curl 测试我们的本地推理

要使用 curl 测试本地推理，您可以运行以下命令。我们使用 stream:false 以便可以轻松读取 JSON 叙事性响应：

测试“OpenAI 兼容”的 Ollama 和 RAG 提示

方便的是，Ollama 还提供一个 REST 终端，可模仿 OpenAI 的行为，以便与包括 Kibana 在内的各种工具兼容。

测试这个更复杂的提示会生成包含 <think> 部分的内容，模型在该部分经过训练以推理解决问题。

将 Ollama 连接到 Kibana

使用 Elasticsearch 的一个好方法是“start-local”开发脚本。

确保您的 Kibana 和 Elasticsearch 能够通过网络访问您的 Ollama。如果您使用的是 Elastic stack 的本地容器设置，则可能需要将“localhost”替换为“host.docker.internal”。或“host.containers.internal”。以获取到主机的网络路径。

在 Kibana 中，导航至“堆栈管理>警报和见解>连接器”。

如果您看到此常见设置警告，该怎么办

您需要确保 xpack.encryptedSavedObjects.encryptionKey 已正确设置。这是在本地 Docker 安装 Kibana 时经常遗漏的一个步骤，因此我将在 Docker 语法中列出修复步骤。

确保持久化 kibana/config 目录，以便在容器关闭时保存更改。我的 Kibana 容器卷在 docker-compose.yml 中是这样的：

现在，您可以创建密钥库，并输入一个值，这样连接器密钥就不会以明文形式存储。

完全重启整个集群以确保更改生效。

创建连接器

在连接器配置屏幕（在 Kibana 中，导航到“堆栈管理>警报和见解>连接器”）中，创建一个连接器并选择“OpenAI”类型。

用以下设置配置连接器

• 连接器名称：Deepseek（Ollama）

• 选择一个 OpenAI 提供商：其他（OpenAI 兼容服务）

• URL：http://localhost:11434/v1/chat/completions

  • 调整为指向 Ollama 的正确路径。请记住，如果您从容器内调用，请替换 host.docker.internal 或等效项。

• 默认模型：deepseek-r1:7b

• API 密钥：可随意填写，需输入一个值，但具体内容无关紧要

请注意，在连接器设置中测试连接到 Ollama 的自定义连接器目前在 8.17 版中已损坏，但在即将发布的 Kibana 8.18 版本中已修复。

我们的连接器如下所示：

将向量嵌入数据导入 Elasticsearch

如果您已熟悉 Playground 并设置了数据，可以跳转到以下 Playground 步骤，但如果您需要一些快速测试数据，我们需要确保已设置 _inference API。从 8.17 版开始，机器学习分配是动态的，因此要下载并打开 e5 多语言密集向量，我们只需在 Kiban 开发工具中运行以下程序。

如果您尚未执行此操作，这将触发从 Elastic 的模型存储库下载 e5 模型。

接下来，让我们加载一本公共领域的书籍作为 RAG 上下文。这里有一个从 Project Gutenberg 下载《爱丽丝漫游奇境记》的链接：链接。将此保存为 .txt 文件。

导航到 Elasticsearch > 主页 > 上传文件

选择或拖放您的文本文件，然后点击“导入”按钮。

在“导入数据”屏幕上选择“高级”选项卡，然后将索引名称设为“book_alice”。

选择“添加其他字段”选项，它位于“自动创建字段”的正下方。选择“添加语义文本字段”，将推理终端更改为“.multilingual-e5-small-elasticsearch”。选择“添加”，然后选择“导入”。

加载和推理过程完成后，我们就可以前往 Playground。

在 Playground 中测试 RAG

在 Kibana 中，导航至“Elasticsearch > Playground”。

在 Playground 屏幕上，您应该会看到一个绿色复选标记和“LLM 已连接”，以指示连接器存在。这就是我们刚刚在上面创建的 Ollama 连接器。可以在此处找到有关 Playground 的更长指南。

点击蓝色的“添加数据源”，然后选择我们之前创建的 book_alice 索引或你之前配置的使用推理 API 的其他索引。

Deepseek 是一种具有强一致性特征的链式思维模型。从 RAG 的角度来看，这既有好处也有坏处。思维链训练可能有助于 Deepseek 理解引文中看似矛盾的陈述，但由于与训练知识的强烈一致性，它可能更倾向于其自身版本的世界事实，而非我们的上下文基础。尽管出发点是好的，但这种强烈的一致性众所周知会使 LLM 在讨论我们的私人知识与训练数据集有冲突或未得到很好体现的主题时难以指导。

在 Playground 设置中，我们输入了以下系统提示：“您是使用《爱丽丝梦游仙境》一书中的相关文本段落回答问题的助手”，并接受了其他默认设置。

对于“谁参加了茶话会？”这个问题，我们得到的答案是：“答案：三月兔、帽匠和睡鼠参加了茶话会。[引用：位置 1 和 2]”，这是正确的。

我们可以在 <think> 标签中看到，Deepseek 确实仔细考虑了引用内容以回答问题。

测试对齐限制

让我们为 Deepseek 创建一个具有智力挑战性的场景来进行测试。我们将创建一个索引，包含 Deepseek 的训练数据已知不属实的阴谋论。

在 Kibana 开发工具中，我们来创建以下索引和数据：

这些阴谋论将作为我们为 LLM 提供的上下文依据。尽管采用了激进的系统提示，Deepseek 仍不会接受我们的事实版本。如果我们处于一种情况，知道我们的私有数据更值得信赖、更有根据或更符合我们组织的需求，这将是不可接受的：

对于测试问题“鸟是真实存在的吗？”（解释了解你的梗），我们得到的答案是“在提供的上下文中，鸟不被视为真实存在的，但在现实中，它们是真实存在的动物。[上下文：位置 1]”。这项测试证明了 DeepSeek R1 的强大功能，即使是在 7B 参数级别......不过，根据我们的数据集，它可能并非 RAG 的最佳选择。

那么我们学到了什么？

总而言之：

• 在 Ollama 等工具中本地运行模型是窥探模型行为的绝佳选择。

• DeepSeek R1 是一种推理模型，这意味着它在 RAG 等用例中各有利弊。

• Playground 能够通过类似于 OpenAI 的 REST API 连接到 Ollama 等推理托管框架，这种方式正逐渐成为 AI 托管早期阶段的事实标准。

总之，我们对本地“隔离网络”RAG 的发展程度印象深刻。自 2023 年我们首次撰写有关隐私优先 AI 搜索的文章以来，Elasticsearch、Kibana 中的工具以及可用的开放权重模型都有了长足的进步。

使用 Kibana 导入地理空间数据

我们在上一篇博客的示例中使用的数据是基于我们内部用于集成测试的数据。为方便起见，我们在此以 CSV 文件的形式提供了这些信息，您可以使用 Kibana 轻松导入这些信息。数据包括机场、城市和城市边界。您可以从以下网址下载数据

• 机场.csv

  • 其中包含三个数据集的合并：

    • 来自Natural Earth的机场（名称、位置和相关数据

    • 来自SimpleMaps的城市位置

    • 全球机场数据库中的机场标高

• airport_city_boundaries.csv

  • 其中包含上述机场和城市名称与一个新来源的合并：

    • 来自OpenStreetMap的城市边界

您可以猜到，我们花了一些时间将这些数据源合并到上述两个文件中，目的是测试 ES|QL 的地理空间特性。这可能与您的具体数据需求不尽相同，但希望这能让您对可能的情况有所了解。我们特别想展示几件有趣的事情：

• 将包含地理空间字段的数据与其他可索引数据一起导入

• 同时导入geo_point 和geo_shape 数据并在查询中一起使用

• 将数据导入可使用空间关系连接的两个索引中

• 创建摄取管道以促进未来的导入（超越 Kibana）

• 摄取处理器的一些示例，如csv 、convert 和 split

虽然我们将在本博客中讨论 如何 使用 CSV 数据，但重要的是要了解 使用 Kibana 添加地理数据的 几种方法 。在地图应用程序中，您可以上传 CSV、GeoJSON 和 ESRI ShapeFiles 等分隔数据，还可以直接在地图中绘制图形。在本博客中，我们将重点介绍从 Kibana 主页导入 CSV 文件。

导入机场

第一个文件是airports.csv、我们需要处理一些有趣的怪癖。首先，列之间有额外的空白分隔，这不是 CSV 文件的典型特征。其次，type 字段是一个多值字段，我们需要将其分割成不同的字段。最后，有些字段不是字符串，需要转换为正确的类型。所有这些都可以使用 Kibana 的 CSV 导入功能来完成。

从 Kibana 主页开始。有一个名为"添加集成入门" 的部分，其中有一个名为"上传文件" 的链接：

点击该链接，您将进入"Upload file" 页面。在此，您可以拖放airports.csv 文件，Kibana 将分析该文件并为您提供数据预览。它应该会自动检测到分隔符是逗号，第一行是标题行。但是，假设所有字段都是text 或keyword ，它可能没有修剪列之间多余的空白，也没有确定字段的类型。我们需要解决这个问题。

单击Override settings 并选中Should trim fields 复选框 ，然后Apply 关闭设置。现在，我们需要确定字段的类型。可在下一页查看，请点击Import 。

首先选择一个索引名称，然后选择Advanced ，进入字段映射和摄取处理器页面。

在此，我们需要对索引的字段映射和导入数据的摄取管道进行更改。首先，虽然 Kibana 可能会将scalerank 字段自动检测为long ，但却误将location 和city_location 字段视为keyword 。将它们编辑为geo_point ，最后得到类似的映射：

您在这里有一定的灵活性，但要注意的是，您选择的类型会影响字段的索引方式和可能的查询类型。例如，如果将location 设置为keyword ，则无法对其执行任何地理空间搜索查询。同样，如果将elevation 设置为text ，则无法对其执行数值范围查询。

现在是修复摄取管道的时候了。如果 Kibana 自动检测到scalerank 如上所示long ，它还会添加一个处理器，将字段转换为long 。我们需要为elevation 字段添加一个类似的处理器，这次将其转换为double 。编辑管道，确保您已将此转换到位。在保存之前，我们还需要进行一次转换，将type 字段分成多个字段。在管道中添加split 处理器，配置如下

最终的摄取管道应该是这样的

请注意，我们没有为location 和city_location 字段添加转换处理器。这是因为字段映射中的geo_point 类型已经了解这些字段中数据的WKT格式。geo_point 类型可以理解一系列格式，包括WKT、GeoJSON 等。例如，如果我们在 CSV 文件中有latitude 和longitude 两列，我们就需要添加script 或set 处理器，将这两列合并为一个geo_point 字段（例如。"set": {"field": "location", "value": "{{lat}},{{lon}}"}).

现在我们可以导入文件了。点击Import ，数据就会按照我们刚刚定义的映射和摄取管道导入索引。如果在摄取数据时出现任何错误，Kibana 会在这里报告，这样你就可以编辑源数据或摄取管道，然后再试一次。

请注意，新的摄取管道已经创建。可进入 Kibana 的Stack Management 部分，选择Ingest pipelines 查看。在这里，您可以看到我们刚刚创建的管道，如有必要，还可以对其进行编辑。事实上，Ingest pipelines 部分可用于创建和测试摄取管道，如果你计划进行更复杂的摄取，这是一项非常有用的功能。

如果您想立即探索这些数据，请跳到后面的章节，但如果您还想导入城市边界，请继续阅读。

导入城市边界

与前一个示例相比，airport_city_boundaries.csv中的城市边界文件导入更为简单。它包含一个city_boundary 字段和一个city_location 字段，前者是城市边界的 WKT 表示法，如POLYGON ，后者是城市位置的geo_point 表示法。我们可以用与机场数据类似的方式导入这些数据，但有一些不同之处：

• 我们需要选择覆盖设置Has header row ，因为这不是自动检测到的

• 我们不需要修剪字段，因为数据中已经没有多余的空白了

• 由于所有类型都是字符串或空间类型，因此我们无需编辑采集管道

• 不过，我们必须编辑字段映射，将city_boundary 字段设置为geo_shape ，将city_location 字段设置为 geo_point

我们最终的字段映射如下

与之前的airports.csv 导入一样，只需单击Import 即可将数据导入索引。数据将通过我们编辑的映射和 Kibana 定义的摄取管道导入。

使用开发工具探索地理空间数据

在 Kibana 中，通常使用"Discover" 探索索引数据。不过，如果您打算使用 ES|QL 查询编写自己的应用程序，尝试访问原始 Elasticsearch API 可能会更有趣。Kibana 有一个方便的控制台，可用于尝试编写查询。这就是所谓的Dev Tools 控制台，可以在 Kibana 侧边栏中找到。该控制台直接与 Elasticsearch 集群对话，可用于运行查询、创建索引等。

试试以下方法：

结果如下

距离

缩写

名字

位置

国家

城市

标高

273418.05776847183

火腿

汉堡

点 (10.005647830925 53.6320011640866)

德国

诺德施泰特

17.0

337534.653466062

TXL

柏林泰格尔国际机场

点 (13.2903090925074 52.5544287044101)

德国

霍恩诺恩多夫

38.0

483713.15032266214

OSL

奥斯陆加德尔莫尼

点 (11.0991032762581 60.1935783171386)

挪威

奥斯陆

208.0

522538.03148094116

BMA

Bromma

点（17.9456175406145 59.3555902065112）

瑞典

斯德哥尔摩

15.0

522538.03148094116

ARN

阿尔兰达

点 (17.9307299016916 59.6511203397372)

瑞典

斯德哥尔摩

38.0

624274.8274399083

DUS

杜塞尔多夫国际机场

点 (6.76494446612174 51.2781820420774)

德国

杜塞尔多夫

45.0

633388.6966435644

PRG

鲁兹恩

点 (14.2674849854076 50.1076511703671)

捷克

布拉格

381.0

635911.1873311149

AMS

史基浦机场

点 (4.76437693232812 52.3089323889822)

荷兰

霍夫多尔普

-3.0

670864.137958866

法国

法兰克福国际机场

点 (8.57182286907608 50.0506770895207)

德国

法兰克福

111.0

683239.2529970079

WAW

奥克西国际机场

点 (20.9727263383587 52.171026749259)

波兰

Piaseczno

111.0

使用 Kibana 地图可视化地理空间数据

Kibana 地图是可视化地理空间数据的强大工具。它可用于创建具有多个图层的地图，每个图层代表不同的数据集。数据可以通过各种方式进行过滤、汇总和样式化。在本节中，我们将向您展示如何使用上一节导入的数据在 Kibana 地图中创建地图。

在 Kibana 菜单中，导航至Analytics->Maps ，打开新的地图视图。单击Add Layer ，选择Documents ，选择数据视图airports ，然后编辑图层样式，使用elevation 字段为标记着色，这样我们就可以很容易地看到每个机场的高度。

单击 "保持更改 "保存地图：

现在添加第二个图层，这次选择airport_city_boundaries 数据视图。这次，我们将使用city_boundary 字段对图层进行样式设置，并将填充颜色设为淡蓝色。这将在地图上显示城市边界。确保对图层重新排序，以确保机场标记位于顶部。

空间连接

ES|QL 不支持JOIN 命令，但可以使用ENRICH 命令实现连接的特殊情况。该命令的操作类似于 SQL 中的 "左连接"，允许您根据两个数据集之间的空间关系，用另一个索引中的数据来丰富一个索引的结果。

例如，我们可以通过查找包含机场位置的城市边界，用机场服务城市的附加信息来丰富机场表的结果，然后对结果进行一些统计：

如果不先准备 enrich 索引就运行该查询，将会收到类似的错误信息：

如前所述，这是因为 ES|QL 不支持真正的JOIN 命令。其中一个重要原因是 Elasticsearch 是一个分布式系统，而连接是一种昂贵的操作，很难扩展。不过，ENRICH 命令的效率相当高，因为它利用了专门编制的在整个集群中复制的丰富索引，从而可以在每个节点上执行本地连接。

为了更好地理解这一点，让我们把重点放在上面查询中的ENRICH 命令上：

该命令指示 Elasticsearch 丰富从airports 索引中获取的结果，并在原始索引的city_location 字段和airport_city_boundaries 索引的city_boundary 字段之间执行intersects 连接，我们在前面的几个示例中使用了该连接。但其中一些信息在该查询中并不清晰。我们看到的是丰富策略的名称city_boundaries ，缺失的信息被封装在该策略定义中。

在这里我们可以看到，它将执行geo_match 查询（intersects 是默认值），要匹配的字段是city_boundary ，而enrich_fields 是我们要添加到原始文档中的字段。其中一个字段region 实际上被用作STATS 命令的分组键，如果没有这种 "左连接 "功能，我们是做不到这一点的。有关 enrich 策略的更多信息，请参阅enrich 文档。

Elasticsearch 中的丰富索引和策略最初是为在索引时使用另一个准备好的丰富索引中的数据来丰富数据而设计的。不过，在 ES|QL 中，ENRICH 命令在查询时工作，不需要使用摄取管道。这实际上使它与 SQLLEFT JOIN 非常相似，只是不能连接任何两个索引，只能在左侧连接一个普通索引，在右侧连接一个专门编制的丰富索引。

无论在哪种情况下，无论是用于摄取管道还是在 ES|QL 中使用，都有必要执行一些准备步骤来设置丰富索引和策略。上文我们已经导入了airport_city_boundaries 索引，但在ENRICH 命令中，它不能直接用作丰富索引。我们首先需要执行两个步骤：

• 创建上述丰富策略，以定义源索引、源索引中要匹配的字段以及匹配后要返回的字段。

• 执行该策略可创建丰富索引。这将建立一个特殊的内部索引，将原始源索引读取到一个更高效的数据结构中，并在整个集群中复制。

可以使用以下命令创建丰富策略：

可以使用以下命令执行该策略：

请注意，如果您更改了airport_city_boundaries 索引的内容，则需要重新执行该策略，才能在丰富索引中看到更改的内容。现在，让我们再次运行原始 ES|QL 查询：

这将返回拥有最多机场的前 5 个区域，以及所有匹配区域机场的中心点和这些区域内城市边界的 WKT 表示长度范围：

中心点

计数

地区

点（-12.13908685930073331.024386116624648)

126

无效

点（-83.1039831787347842.300230911932886)

3

底特律

点 (39.74537850357592 47.21613017376512)

3

городской округ Батайск

点（-156.8098678719252320.476673701778054)

3

夏威夷

点（-73.9451533276587740.70366442203522)

3

纽约市

点（-83.1039831787347842.300230911932886)

3

底特律

点（-76.6687301918864324.306286952923983)

2

新普罗维登斯

点 (-3.0252167768776417 51.39245774131268)

2

加的夫

点（-115.4099348466843432.73126147687435)

2

墨西卡利市

点 (41.790108773857355 50.302146775648)

2

Центральный район

点（-73.8890273217111845.57078813901171)

2

蒙特利尔

您可能还会注意到，最常见的地区是null 。这意味着什么？回想一下，我曾将此命令比作 SQL 中的 "左连接"，也就是说，如果没有为某个机场找到匹配的城市边界，则仍会返回该机场，但airport_city_boundaries 索引中的字段值为null 。结果发现，有 125 个机场没有找到匹配的city_boundary ，有一个机场找到了匹配的region 字段，但该字段是null 。这样就统计出了 126 个机场，结果中没有region 。如果您的用例要求所有机场都能与城市边界相匹配，那就需要获取更多数据来填补空白。有必要确定两件事：

• airport_city_boundaries 索引中哪些记录没有city_boundary 字段

• airports 索引中哪些记录与ENRICH 命令不匹配（即"......"）。不相交）

在 Kibana 地图中使用 ES|QL 获取地理空间数据

Kibana 在地图应用程序中添加了对空间 ES|QL 的支持。这意味着您现在可以使用 ES|QL 在 Elasticsearch 中搜索地理空间数据，并在地图上将结果可视化。

在添加图层菜单中有一个新的图层选项，名为"ES|QL" 。与迄今为止介绍的所有地理空间功能一样，该功能在"技术预览版" 中。选择该选项可根据 ES|QL 查询结果在地图上添加图层。例如，您可以在地图上添加一个图层，显示世界上所有的机场。

或者您也可以添加一个图层，显示airport_city_boundaries 索引中的多边形，或者更好的办法是使用上面那个复杂的ENRICH 查询，生成每个地区有多少个机场的统计数据？

后续工作计划

上一篇地理空间搜索博客主要介绍了使用ST_INTERSECTS 等函数进行搜索的方法，Elasticsearch 自 8.14 版起提供了这些功能。本博客将向您展示如何导入我们用于这些搜索的数据。不过，Elasticsearch 8.15 提供了一个特别有趣的功能：ST_DISTANCE ，可用于执行高效的空间距离搜索，这将是下一篇博客的主题！