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 中也可正常运行。仅有两项轻微的破坏性变更，分别影响仪表板列表和时长单位格式，详见此处。

如今，这一切变得简单得多。Elastic Cloud API 密钥现在可以直接在 Elastic Cloud Serverless 上对 Elasticsearch 和 Kibana API 进行身份验证。您现在可以使用单一凭证来管理组织的资源并执行数据操作，例如 Elasticsearch 查询语言 (ES|QL) 查询、数据摄取和告警。

下面我们来看看我们构建这一功能的原因、如何设计全局分布式身份层来实现这一目标，以及它如何为跨项目搜索奠定基础。

秘密管理负担

围绕数据平台构建可靠的 CI/CD 管道、GitOps 工作流或 Terraform 自动化，都伴随着一项隐性成本：秘密信息蔓延。

在旧模式下，开发人员面临割裂的身份验证体验：

• 控制平面 (Elastic Cloud API 密钥)：组织级密钥，组织级作用域的密钥，用于通过 Elastic Cloud API 创建项目、邀请用户和管理计费。

• 数据平面（Elasticsearch API 密钥）： 项目范围密钥是在特定的 Serverless 项目中创建的，用于与 Elasticsearch 和 Kibana API 进行交互。

这意味着您的部署脚本必须对 Elastic Cloud 进行身份验证，配置 Serverless 项目，从该特定项目中提取新生成的 Elasticsearch API 密钥，然后将该密钥注入下游应用程序或自动化工具，从而导致复杂的管道、分散的审计日志以及更高的凭证泄露风险。

Elastic Cloud Serverless 中的统一身份验证

通过此次发布，Serverless 项目的拆分问题将不复存在。您现在可以创建一个明确授权用于 云、Elasticsearch 和 Kibana API 的 Elastic Cloud API 密钥。

• 以前：Elastic Cloud API 密钥严格来说是控制平面令牌。它可以创建项目、管理计费和邀请用户，但存在一个硬边界：它不能用于调用这些项目内部的 Elasticsearch 或 Kibana API。您始终需要第二个特定于项目的密钥来执行数据操作。

• 现在： 在创建 Elastic Cloud API 密钥时，选择 Cloud、Elasticsearch 和 Kibana API 访问权限，Serverless 的硬边界就被移除了。该 API 密钥成为一个真正统一的凭证。它保留了管理组织基础架构的能力，同时获得了跨任何已授权 Serverless 项目进行查询、摄取和分析数据的原生访问能力。

通过将这一切统一到单个 Elastic Cloud API 密钥之下，您获得了一个统一的身份，可以作为一个整体进行范围限定、审计、轮换和撤销。每个 API 调用——无论是配置新项目还是运行 ES|QL 查询——都会在审计日志中显示为使用同一凭证，从而在事件调查或合规性审查期间为您提供单一的追踪线索。凭证轮换成为一步操作，而无需跨独立的控制平面和数据平面秘密信息进行协调更新。而且由于角色分配是按项目进行的，一个密钥可以跨多个项目使用——在您的可观测项目中管理数据摄取，在安全项目中运行查询——无需为每个项目分别管理不同的凭证。

重要的是，统一并不意味着全部权限。通过使用 role_assignments 有效负载，您可以将统一密钥严格限定到单个项目和特定角色（例如只读），从而确保即使凭证泄露，其影响范围也能得到完全控制。如果某位开发人员离职或某个应用程序被停用，您可以在 Elastic Cloud Console 中撤销单个密钥，立即终止对控制平面以及所有关联 Elasticsearch 项目的访问。

(注意：对于 Elastic Cloud Hosted / 托管部署，Cloud API 密钥仍仅用于控制平面管理。计划在未来的版本中支持将其扩展到托管堆栈 API。）

自动化您的工作流

入门很简单。您可以完全通过 Elastic Cloud 控制台进行配置，也可以使用 Elastic Cloud API 对其进行自动配置。

UI 流程保持不变，但现在您可以在项目角色分配下选择 Cloud、Elasticsearch 和 Kibana API 访问权限。

下面说明如何使用 Elastic Cloud API 以编程方式创建统一密钥。请注意 application_roles 数组，正是它授予了密钥对 Elasticsearch 数据平面的原生访问权限：

一旦创建，您只需在 Authorization: ApiKey 标头中向 api.elastic-cloud.com 以及您的特定 Serverless Elasticsearch 终端传递完全相同的这个密钥即可。

底层实现：构建分布式身份层

使一个 Cloud API 密钥能够在控制平面和数据平面同时工作，并不像传递一个令牌那么简单。这需要解决一个根本性的分布式系统挑战。

过去，Cloud API 密钥存储在一个中心化的全局安全集群中。这对于可以接受较高延迟的控制平面操作来说没有问题。然而，Elasticsearch 数据请求要求超低延迟。我们不能为了验证每个搜索查询或摄取请求而在全局范围内往返访问中央控制平面。

为了解决这个问题，我们引入了一种由全局分布式数据存储提供支持的新身份验证架构。下面的序列图展示了一个客户端使用 Elastic Cloud API 密钥发送 Elasticsearch 查询的过程，说明了身份验证完全在本地区域内完成，无需往返全局控制平面。Elasticsearch 将身份验证委托给区域 IAM 服务，该服务针对全局分布式数据库的本地副本验证密钥并解析其角色分配。一旦授权通过，Elasticsearch 执行查询并将结果返回给客户端。

全局分布式持久化

Elastic Cloud API 密钥及其关联的角色定义不再仅依赖集中式安全集群，而是持久化存储在全球分布的高可用数据库中。该数据库在全球控制平面与实际运行您的 Serverless 项目的区域数据平面之间同步身份与访问管理 (IAM) 数据。

使用区域 IAM 进行本地验证

当您的客户端使用 Elastic Cloud API 密钥向 Elasticsearch 发送请求时，该请求不会返回全局控制平面。相反，它会被路由到新的区域 IAM 服务。它会验证本地数据库副本中的密钥，确保身份验证几乎无延迟，并且完全不受全局控制平面故障的影响。

动态角色映射

身份验证只是成功的一半；系统还需要对请求进行授权。区域 IAM 服务可立即将您的云端角色分配 (例如 application_roles) 转换为原生 Elasticsearch 权限。Elasticsearch 随后可在本地授权并执行请求，完全无需本地 .security 索引。

跨项目搜索的基础

这种分布式身份架构是 Elastic 平台未来发展的基础构建块。

由于身份和访问权限现在统一且全局同步，我们拥有了在不同项目之间安全传递您身份所需的框架。这为 Serverless 即将推出的 跨项目搜索 (CPS) 功能提供了支持。

借助 CPS，您将能够查询跨越多个远程 Serverless 项目的数据，例如将安全负载和可观测负载组合起来，就像它们是单一数据集一样简单。通过依赖统一 API 密钥，系统可以自动评估您在所有项目上的权限，而无需您在每个目标项目上配置复杂的信任关系、证书或重复的凭证。

了解详情

准备好简化您的技术栈了吗？

• 请参阅 Elastic Cloud API 密钥文档，了解如何分配堆栈访问权限。

• 请参考 Create API key（Elastic Cloud API） 文档，以实现密钥自动生成。

• 查看 Elastic API 密钥，了解 Elastic 平台中各类密钥的完整对比。

立即开始在 Elastic Cloud 上构建或继续您的构建之旅。

免责声明

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

Elastic 工作流是 Kibana 内置的自动化引擎，允许您通过简单的 YAML 配置定义多步流程。每个工作流都可以按计划或事件触发，也可以作为 Elastic Agent Builder 中的工具触发，并且每个步骤都可以调用 Kibana API、查询 Elasticsearch 或转换数据。

我们将使用仪表板查看计数作为具体示例，但同样的模式也适用于通过 Kibana 已保存对象 API 公开的任何指标。

准备工作

• 运行 9.3 的 Elastic Cloud 或自管型集群

• 已启用工作流（高级设置）

步骤 1：在 开发工具 中探索原始数据

在开始构建之前，我们先了解目前有哪些数据。Kibana 将其大部分配置和元数据作为已保存对象存储在专用的内部索引中。Kibana 通过这种方式跟踪的事项之一是仪表板查看次数，它使用一种名为“使用计数器”的特殊保存对象类型来实现。您可以在开发工具中直接查询它们：

响应类似如下：

counterName 字段是仪表板 ID，而 count 是该仪表板在特定日期的累计查看次数。Kibana 每天会为每个仪表板创建一个计数器对象；您可以在对象 ID 中看到日期后缀 (...viewed:server:20260310)。随着用户打开仪表板，计数在一天中不断增长。

我们不会在索引中复制这种每日文档模型，而是为每个工作流执行创建一个文档。每份文档都记录了该仪表板在捕获时当天的累计浏览量。

步骤 2：创建目标索引

我们需要一个索引来存储仪表板视图快照。以下命令创建了明确的映射，以便我们稍后进行聚合和可视化。在开发工具中运行此命令：

对 ID 和名称使用 keyword 映射可以进行聚合。使用 integer 来表示 view_count 是一个安全的默认设置，因为 Kibana 每天都会重置计数器，所以达到 32 位限制（一天内超过 20 亿次查看）并非实际需要担心的问题。它仍然支持数值运算，例如 max、avg 和 min 等。

步骤 3：创建工作流

前往 Stack Management > 工作流 > 新建工作流，然后粘贴以下工作流 YAML 配置：

在下一节中，我们将逐步分解工作流。

工作流如何运作

触发

工作流每 30 分钟按计划触发运行一次。这样我们就能获得时序数据，而不会对 API 造成过多压力。

fetch_dashboard_views

使用 kibana.request 调用 Kibana 已保存对象 API。无需进行身份验证设置：工作流引擎会根据执行上下文自动附加正确的标头。

index_each_dashboard（循环）

遍历由上一步返回的 saved_objects 数组。每次迭代中的当前项目均可作为 foreach.item。在循环内部，我们为每个仪表板运行两个嵌套步骤。

1. fetch_dashboard_name：

通过调用 GET /api/saved_objects/dashboard/{id} 来解决人类可读的仪表板标题。我们添加了 on-failure: continue: true，以便如果仪表板被删除但仍有浏览计数器，循环就会继续，而不是导致整个执行失败。

2. index_doc：

使用 POST /dashboard-views/_doc（无显式 ID）为每个文档建立索引，这样 Elasticsearch 就能自动生成 ID。这样，每次运行时都会创建一个新文档，从而随着时间推移构建浏览次数的历史记录，而不是覆盖之前的快照。

有两点值得注意：

• captured_at 字段使用日期筛选器将时间戳格式化为 ISO 8601。如果没有它，值就会显示为 JavaScript 日期字符串，例如 Tue Mar 10 2026 05:03:47 GMT+0000，Elasticsearch 不会将其映射为日期。

• view_count 使用 ${{ }} 语法和 | plus: 0 来保留数值类型。使用{{ }} 会将其显示为字符串，这将阻止在仪表板中进行数学运算。

UI 允许您可以很好地对每个工作流步骤进行故障排查。

第 4 步：构建统计仪表板

一旦工作流运行了几次并收集了数据，使用 dashboard-views Data view在 Kibana 中创建一个新的仪表板。

一些入门面板：

• 按浏览量排列的顶级仪表板：使用柱形图，X 轴为 dashboard_name，Y 轴为 last_value(view_count)。这将显示每个仪表板当前的每日浏览量。

• 随时间变化的浏览量：使用折线图，X 轴为captured_at，Y 轴为last_value(view_count)，按 dashboard_name 细分。由于每次运行都会添加一个新文档，因此使用最后一个值来获取每个时间分桶的峰值计数，而不是重复计数的总和。

• 当前快照：使用数据表和最新的 captured_at 来显示所有仪表板上最新的浏览量。

由于每个工作流都会创建一个新文档，因此您可以按时间范围进行筛选，以分析特定时段的活动、比较周与周之间的差异，或在仪表板低于浏览量阈值时发出警报。

结论

Elastic 工作流非常适合这种定期数据收集，因为源 (Kibana API) 和目标 (Elasticsearch) 都是原生的，这意味着无需管理任何凭据。工作流引擎会自动处理 kibana.request 和 elasticsearch.request 步骤的身份验证，因此您只需编写逻辑即可。

资源

• Elastic 工作流

• Kibana API

Elastic 的依赖管理

在 Elastic，我们必须管理数百甚至数千个存储库，包括私有和公共存储库。当发现关键 CVE 时，我们需要立即找到答案并采取行动：哪些存储库存在漏洞？我们能多快把它们修补好？除了安全性，生产力问题也随之而来：我们如何才能在不花费太多时间进行手动操作的情况下，迅速将新软件包版本的发布信息传播到所有依赖它的存储库？

寻找依赖管理方法的最初原因是需要建立一个具有自动更新功能的安全基础，以减少 CVE。仔细考虑有关依赖管理的解决方案后，我们首先着手构建一个自托管的基础设施。我们使用自己的 Kubernetes 集群来运行 Mend Renovate 社区自托管服务。我们的想法是能够提供一个依赖管理平台，让我们的用户能够以自助服务的方式访问该平台。

最初的实验取得了成功，因此越来越多的团队开始使用我们的平台，并将其应用于日常存储库的生命周期管理中，用于更新和 CVE 补丁修复。这种情况发生得太快，以至于我们很快就达到了自托管安装的上限。

挑战：我们如何在拥有大量存储库的大型组织中扩展依赖管理平台？

我们的依赖管理平台一次只能处理一个存储库，由于我们拥有大量存储库，这种顺序处理模型已无法跟上需求。我们已经确定，问题在于我们的依赖管理工具的单个实例无法处理我们庞大且不断增长的存储库列表这一概念。存储库在队列中等待，有时长达数小时。我们超过 50% 的存储库甚至没有每天进行处理。这意味着超过 50% 的存储库扫描间隔时间超过 24 小时。

大型存储库由于代码库规模庞大且有多个开放 PR，因此会造成更大的瓶颈。GitHub webhook 事件打乱了顺序。由于扫描时间无法预测，自动合并变得不可靠。我们曾向用户承诺扫描频率，但未能兑现。

决定内部构建：满足 Elastic 独特的扩展和安全需求

虽然我们考虑了商业选项，包括 Mend 的 Renovate 自托管企业版，但在 Elastic 内部，我们有几个关键计划正在加速推进。

我们决定构建一个内部平台，这一决定源于我们认识到，只有深度定制的解决方案才能满足 Elastic 不可妥协的特殊要求：

1. 投资我们的内部开发者平台：当时，我们已经开始大力投资内部开发者平台。我们正在讨论和设计每项服务都能融入其中的方法。这意味着我们希望为我们的依赖管理平台测试我们自己的规则和做法。除此之外，新的指南即将出台，我们希望在此之前设计好平台。

2. 本地集成和工作流程定制：我们需要与内部工具和内部流程直接集成。例如，我们希望通过服务目录（后台）将配置集中为代码。我们对后台的使用有特殊需求，希望我们的平台能与之兼容。因此，尽管可以将 Renovate 自托管 API 与我们的后台自动化结合使用，但这并不能完全覆盖我们的内部流程。

3. 针对 Elastic 的深度防御安全：我们严格的安全合规要求为我们的生态系统量身定制安全机制。我们正在努力强化对“非人类身份”的使用。这种访问权限的强化方式意味着，如果工具不支持 GitHub 内部的这种实现方式，那么非标准的身份验证方法将无法使用现成的工具。我们的工作流包括实施父子工作流密钥加密模式，并使用临时的一次性 GitHub 令牌。在我们复杂的多云环境中，内部构建是嵌入这些独特的安全层并最大限度减少攻击面的唯一实用方法。

解决方案：用于依赖管理的工作流编排

我们的解决方案源于这样一个事实，即我们希望在已使用的依赖管理工具的基础上进行构建，而不是将其替换掉并寻找其他方案。它已显示出其潜力，其灵活性对于满足我们整个组织的不同需求非常重要。我们考虑了不同的解决方案，而帮助我们做出决定的是我们必须承担的重大且有时特殊的需求。我们决定构建一个可靠且具有可扩展性的依赖管理平台，在这个Platform上，每个存储库都将单独处理，消除瓶颈，为未来发展奠定基础。

我们在设计该平台时遵循了三个核心原则：

1. 并行处理

每个存储库都有其专属的依赖管理处理环境。不再有排队的情况。我们的并发性仅受我们消耗的资源数量限制。我们还应用了智能分布式调度，以避免受到 GitHub 的速率限制。

2. 可自助服务

我们使用服务目录（后台）自动载入和管理任何新的存储库。我们使用自己的资源定义，让最终用户可以选择存储库的处理频率、计划分配多少资源，以及出于任何原因选择关闭或重新开启处理。随着用户需求的变化以及他们对新安装方式日益熟练，我们计划通过这种方式增加更多选项。

3. 缩小了机密范围和命名空间隔离

为了提高安全性，我们在每次工作流开始时为依赖管理 Pod 提供临时生成的 GitHub 令牌。此外，我们还将工作负载隔离在特定的命名空间中，以便仅向它们提供必要的机密。我们使用 Kubernetes RBAC 控制每个依赖管理工作流可以访问哪些机密。我们还使用加密技术将 GitHub 令牌从父工作流传播到子工作流。

我们使用 Kubernetes 重建了平台，并借助 Kubernetes 的强大功能，Argo 工作流为我们的流程逻辑提供支持，同时 Renovate CLI 已设置好，用于一次扫描和处理一个存储库。

亮点：我们正以一种创新的方式使用经过实战验证的开源项目，为所有这些项目提供新的工作示例，同时为我们的团队提高开发速度并减少 CVE。

依赖管理架构：四个微服务

该平台由四个定制组件构成：

工作流 Operator (Go/Kubebuilder)

Kubernetes Operator 通过三个自定义资源定义 (CRD) 管理工作流生命周期：

• RepoConfig CRD：存储库配置的单一事实来源。

这就是在 Operator 中定义 RepoConfig 的方式：

这就是 RepoConfig 实例的样子：

• 父级 CRD：管理用于计划扫描的 CronWorkflow。

在父控制器的协调循环内部，我们确保创建并保持工作流设置的最新状态，甚至在必要时将其删除。

首先，它会获取一些全局配置的工作流设置：

它确保互斥 configmap 是最新的，以防止类似的工作流同时运行：

然后创建工作流管理器，该结构将创建或更新 CronWorkflows 和工作流模板：

• 子 CRD：使用每个存储库的资源管理 WorkflowTemplate。

子控制器与父控制器有类似的协调职责，但这次它负责子命名空间中将由父工作流触发的工作流模板。

多控制器模式提供了明确的分隔：RepoConfig 控制器处理加入/退出，父控制器管理调度，子控制器处理执行模板。

GitHub 事件网关 (Go)

一个安全的 Webhook 代理，用于接收 GitHub 的 Webhook，验证签名，按组织/存储库进行筛选，并将其路由到 Argo Events。我们构建了 10 个不同的传感器，分别对依赖仪表板交互、PR 事件和软件包更新做出响应。

此网关可通过以下方式与 GitHub 应用集成：

• 验证传入的 GitHub Webhook 签名以确保安全。

• 将有效事件转发给 Argo Events EventSource，并附上所有相关标头和身份验证。

• 我们还在 EventSource 上配置了一个 authSecret，并在转发的请求中将其作为 Bearer 标头提供。

• 提供日志记录、指标和重试逻辑。

它对每个 GitHub 事件请求执行各种验证。

它确保某些 HTTP 属性存在：

同时，它还会验证每个请求的签名及其组织。

最后，它会根据事件类型路由到 Argo Events：

在 Argo Events 方面，有 10 个传感器在监视 Argo Events EventBus 上的新事件。

然后，脚本会应用每个传感器的逻辑：

后台同步器 (Go)

此过程将轮询我们的服务目录（后台）以获取存储库真实资源实体，将其转换为 RepoConfig CRD，并使平台与配置更改保持同步。更改将在三分钟内生效。

最后，它将数据写入 RepoConfig 实例。

工作流基础（混合：JavaScript、Go、Helm）

基础层包含 Helm 图表、JavaScript 配置、带有加密支持的适用于 Renovate CLI 的 Go 封装器，以及适用于 Alpine 软件包的自定义 APK 索引器。

自助服务配置

团队通过后台声明式配置其存储库：

资源组根据存储库大小分配 CPU 和内存：

• 小型：500m CPU，1Gi 内存。

• 中型：1000m CPU，2Gi 内存。

• 大型：2000m CPU，4Gi 内存。

配置受版本控制、可审计并自动应用。

父子模式

执行模型采用父子工作流模式：

• 父工作流：按计划运行的轻量级 CronWorkflow。加密机密，确定是否应运行扫描，将配置传递给子项。

• 子工作流：运行 Renovate CLI 的临时 Pod。动态分配资源，在隔离环境中解密机密，完成后终止。

这种分离提供了安全性（在父级加密机密）、资源优化（父级使用最少资源）以及可扩展性（子级并行运行）。

结果

性能转换

• 之前：每次处理一个存储库，有些存储库可能一天甚至更长时间都无法得到处理，每天扫描量不足 1000 次。

• 之后：超过 100 次并发扫描，通常每天 8,000 次扫描，最多可达 10000 次记录的扫描，仅受我们愿意投入的资源数量以及处理 GitHub 速率限制的方式的限制。

成本效率

尽管听起来有点奇怪，但每天运行 8000 个 Pod 可以比让一个长期运行的 Pod 试图达到同样的结果花费少得多，而且效果相同。

在之前的设置中，我们运行的是单个实例，在状态良好的情况下，每天能执行 500 到 600 次扫描。同时，由于不同类型的存储库将在同一个 Pod 上执行，我们需要根据最大的存储库来调整 Pod 的大小。这种尺寸比我们目前提供的超大型产品要大得多，我们的 Pod 使用 8 个 CPU 和 16G 内存。

为满足当前的每日输出，单个 Pod 需要运行 12 天。因此，将单个 Pod 运行 12 天的成本与每天运行 8,000 个“中等”大小 Pod 的成本进行比较，我们的新设计在相同的扫描输出下要高效得多：

指标

场景 A（工作流）

场景 B（长时间运行的单个 pod）

设置

8,000 个 pod（1 个 vCPU / 2GB）

1 个 pod（8 个 vCPU / 16 GB）*

持续时间

每次 10 分钟

连续 12 天

总工作时间

1,333 计算小时

288 个计算小时

总成本

$65.83

$113.75

不过，我们应考虑到，我们的工作负载默认设置为“小型”，绝大多数工作负载在 0.5 CPU 和 1G RAM 的情况下成功运行，只有少数需要更改为中型或大型。让我们看看，如果 60% 的工作负载运行在“小型”级别，30% 运行在“中型”级别，10% 运行在“大型”级别会发生什么情况，这更接近实际情况。

指标

场景 A（混合群）

场景 B（长时间运行）

战略

8,000 个 Pod（混合尺寸）

1 个 pod（8 个 vCPU / 16 GB）*

持续时间

每次 10 分钟

连续 12 天

总成本

$52.66

$113.75

保存

61.09 美元（便宜 54%）

—

我们可以看到，在相同的输出下，我们目前的配置成本效益要高得多。

增强安全

• 临时 GitHub 令牌（暴露时间为几分钟而不是几天）。

• 通过基于角色的访问控制 (RBAC) 边界实现命名空间隔离。

• 父工作流中的机密数据静态加密。

• 移除了直接访问金库的权限。

可预测的性能

有了有保障的扫描频率，我们终于可以设定服务水平目标 (SLO)。自动合并功能运行可靠。团队信任平台能够兑现承诺。

关键架构决策

以下是一些塑造平台外观的里程碑式设计决策。

• 为何采用父子工作流？

我们采用这种模式来实施深度防御策略。通过将高价值证书（例如 GitHub 应用密钥）限制在专用且锁定的命名空间，我们使用基于角色的访问控制 (RBAC) 来确保临时执行 Pod 无法随意访问敏感数据。最近的供应链漏洞（例如“Shai Hulud”持续集成/持续交付 [CI/CD] 攻击）表明，将执行动态脚本的运行时环境与凭据存储空间隔离开至关重要。

同时，这种解耦还实现了细粒度的资源优化。“父”工作流充当轻量级编排器，占用资源极少，而“子”工作流则处理计算密集型依赖扫描。这种分离简化了生命周期管理，使我们能够对每一层应用不同的协调逻辑，让用户能够控制执行参数（子级），同时保留对调度和安全基础设施的管理控制（父级）。

• 为什么采用可自助服务？

消除团队在存储库配置方面的瓶颈是一项关键要求。我们的使命是构建一个可扩展的自助服务平台，能够支持各种用例。我们认识到，鉴于存储库的庞大数量，为每项配置更改充当“守门员”的做法是不可持续的。相反，我们采取了一种赋能的理念：提供“轨道”（基础设施和保障措施），同时赋予用户驾驶“列车”（执行和自定义）的权力。我们相信，这种向团队自主权的转变，能让用户根据自己的具体运营需求来定制系统，从而显著提高了生产率。

• 为什么使用 Kubernetes Operator 模式？

如上所述，一个基本的设计原则是确保平台可以完全自助服务。我们需要一种自动机制来捕捉用户意图（例如切换扫描、调整调度频率或调整运行时资源限制），并立即将这些更改传播到底层工作流中。考虑到未来的需求，该系统还需要易于扩展。

为了实现这一目标，我们开发了自定义依赖管理 Kubernetes Operator。通过使用 CRD 作为配置接口，我们建立了一个原生 Kubernetes 协调循环。此 Operator 会持续监控用户定义的期望状态，并自动编排对工作流基础设施进行必要的更新。这确保了事件驱动的无缝操作，平台逻辑可以在后台处理所有复杂性。

• 为什么要设计 GitHub 事件网关？

采用事件驱动型架构 (EDA) 对平台的响应速度至关重要。尽管 CronWorkflows 提供了可靠的基线计划，但我们还需要具备灵活性来处理临时执行，例如用户通过仪表板手动触发扫描。为了实现这一目标，我们需要一个专用的摄取网关来验证有效负载的完整性并智能地路由请求。

我们评估了现有解决方案，包括 Argo 的原生 GitHub EventSource，但发现在运营开销和严格的 GitHub API 配额（例如，每个存储库的 Webhook 限制）方面存在重大风险。因此，我们构建了一个自定义网关，使我们的基础设施不受这些限制的影响。

至关重要的是，此网关在我们的迁移过程中充当了战略流量控制点。它充当了一个开关，使我们能够从传统系统向新的基础设施执行渐进式、细粒度的部署（流量切换）。这确保了数千个存储库的导入过程是受控且无风险的，而非“大爆炸”式切换。

经验教训

我们学到的一些经验教训与 Elastic 源代码密切相关：

1. 客户至上：平台为用户而构建。因此，将用户需求放在首位非常重要。这将平台塑造成高效设计的基础设施和应用程序，从而减少与用户的摩擦，简化平台的扩展，并使其易于采用。

2. 空间与时间：有时，最顺畅的道路也会通向变幻莫测的沙漠。我们最初尝试优化现有的顺序处理模型，但这并未解决我们的问题；事实上，它只是引入了更多复杂性和未解决的问题。重新构建并行处理平台的大胆决定需要大量的前期工作。然而，它最终为可持续的平台增长铺平了道路，并几乎消除了繁琐的日常管理工作。

3. 视情况而定：平台无法孤立运作；其成功取决于它与更广泛的生态系统的整合程度。在我们的案例中，与后台的集成至关重要，因为它是无缝服务导入的真实来源。同样，连接到 Artifactory 使我们能够高效地管理私有包更新，而且这些重要的集成远不止于此。

4. 进步，简单即完美：在整个实施过程中，我们不断对最初的假设进行压力测试，并在新障碍出现时进行调整。我们没有被完美主义所束缚，而是采取迭代的方法，逐一解决挑战，并根据实际情况调整迁移策略。

未来发展

该平台的交付使我们能够开展更有意义的工作，这将有助于我们改善平台的用户体验和效率。一些示例包括：

• 增加并规范自动合并的采用

自动合并功能通过消除繁琐的手动任务，显著加快了团队的工作进度。然而，我们需要确保设立严格的防护措施，确保这种速度提升不以牺牲安全性为代价。

• 改善围绕最终用户体验的可观测性

我们路线图的一个重要优先事项是增强可观测性，不仅是在平台层面，而且特别是从最终用户的角度。虽然捕获基础设施指标很简单，但要理解实际的用户体验需要更深入的见解。我们正在努力定义以用户为中心的核心关键性能指标 (KPI)，以便我们的遥测技术能够在问题升级为用户投诉之前检测到摩擦点和性能问题。

• 消除障碍以促进更广泛的应用

展望未来，我们的首要任务是找出并消除任何阻碍平台采用的障碍。无论这需要开发新的集成还是部署特定的功能集，我们都致力于数据驱动的规划。我们已成功构建了一个专为扩展而设计的平台；现在我们的重点转向最大限度地发挥其潜力。

了解全貌

依赖管理工作流项目展示了一个更广泛的原则：当您需要将开源工具扩展到其默认部署模型之外时，原生的 Kubernetes 模式提供了前进的道路。

通过拥抱：

• 用于配置的 CRD。

• 适用于生命周期管理的 Operator。

• 用于响应的事件驱动架构

• 用于部署的 GitOps。

我们构建了可独立于所管理的存储库数量进行扩展的编排。无论管理的是 100 个还是 1,000 个存储库，扫描单个存储库的性能都相同。

公布关键的 CVE 时，我们现在能在几分钟内给出答案，而不是几小时。这就是瓶颈和竞争优势的区别。

致谢

该平台建立在优秀的开源工具之上：

• Kubebuilder：用于启动 Kubernetes Operator 的开源框架，这些 Operator 可引导和编排工作流。[1][2]

• 后台：构建服务目录所基于的开源框架，也是我们获取事实依据的来源。[1][2]

• Argo 工作流和 Argo 事件：用于编排复杂流程并基于事件添加动态处理的开源套件。[1][2][3][4]

• Renovate CLI：处理存储库的开源依赖管理工具。[1][2]

*尽管我们的工作负载不一定在 AWS 上运行，而是在完整的 Kubernetes 集群上运行，但我们还是以 AWS Fargate 的定价模型作为单个 Pod 成本的参考。

此外，这些用例通常具有时间敏感性，而经历典型的开发阶段（创建代码分支，然后等待新版本发布）是一个耗时的过程。

那么，如果我们只需调用 API，或者在 Kibana 中点击几下就能完成整个过程，那会怎样呢？

查询规则用户界面

Elasticsearch 8.10 引入了查询规则和规则检索器。这些工具旨在根据规则在不影响有机结果排名的情况下将钉入结果注入查询。它们只是以声明式的简单方式在结果之上添加业务逻辑。

查询规则的一些常见用例包括

• 突出显示促销列表或销售：在顶部显示促销或赞助商品。

• 根据上下文或地理位置排除：当当地法规不允许显示某些项目时，隐藏这些项目。

• 优先处理关键结果：确保热门搜索或固定搜索始终排在前面，无论有机搜索排名如何。

要访问界面并与这些工具互动，需要点击 Kibana 侧边菜单，然后转到相关性下的查询规则 ：

查询规则菜单弹出后，点击创建第一个规则集：

接下来，您需要为规则集命名。

定义每条规则的表格有三个关键部分：

• 标准：适用规则必须满足的条件。例如，"当 query_string 字段包含Christmas值时 "或 "当 country 字段为CO 时"。

• 行动：这是您希望在条件满足时发生的事情。它可以被固定（将文档固定到顶部结果）或排除（隐藏文档）。

• 元数据：这些字段在查询运行时会随查询一起出现。它们可以包括用户信息（如位置或语言）以及搜索数据（query_string）。这些值是标准用于决定是否应用规则的值。

例如：热门项目

假设我们有一个电子商务网站，上面有不同的商品。在查看这些指标时，我们注意到在游戏机类别中，"DualShock 4 无线控制器 "是销售量最大的商品之一，尤其是当用户搜索关键词 "PS4 "或 "PlayStation 4 "时。因此，我们决定在用户搜索这些关键词时，将该产品放在搜索结果的顶部。

首先，让我们使用批量 API 请求为每个项目的文档建立索引：

如果我们不干预查询，该项目通常会出现在第四位。问题是这样的

结果如下

让我们创建一个查询规则来改变这种情况。首先，让我们像这样把它添加到规则集中：

或相应的API 请求：

要在查询中使用规则集 ，我们必须使用查询规则类型。这种查询主要由两部分组成：

• 匹配标准：这些是用于与用户查询进行比较的元数据。在本例中，当 query_string 字段的值为 "PlayStation 4 "时，规则集被激活。

• query：实际查询，用于搜索和获取有机结果。

这样，首先运行有机查询，然后 Elasticsearch 应用规则集中的规则：

示例：基于用户的元数据

查询规则的另一个有趣应用是使用元数据，根据用户或网页的上下文信息显示特定文档。

例如，假设我们想根据用户的忠诚度（用数值表示）来突出显示商品或定制销售。

我们可以直接将这些元数据导入查询，这样当所述值满足特定条件时，规则就会激活。

首先，我们将为一份只有忠诚度高的用户才能看到的文档建立索引：

现在，让我们在同一规则集内创建一条新规则，这样当忠诚度_级别等于或高于 80 时，项目就会出现在结果的顶部。

保存规则和规则集。

以下是相应的 REST 请求：

现在，在运行查询时，我们需要在元数据中包含新参数loyalty_level 。如果满足规则中的条件，新文档将出现在结果的顶部。

例如，在发送忠诚度级别为 80 的查询时：

我们将在结果上方看到忠诚度文件：

在下面的例子中，由于忠诚度等级为 70，因此不符合规则，物品不应出现在顶部：

结果如下：

例如：立即排除

假设我们的DualShock 4 无线控制器（ID 2）暂时缺货，无法出售。因此，业务团队决定在此期间将其从搜索结果中删除，而不是手动删除文档或等待某些数据流程启动。

我们将使用与刚才应用于热门项目类似的过程，但这次我们不选择 "已固定"，而是选择 "排除"。这条规则就像一个黑名单。将条件改为 "始终"，这样每次运行查询时，排除都会起作用。

规则应该是这样的

保存规则和规则集以应用更改。以下是相应的 REST 请求：

现在，当我们再次运行查询时，你会发现结果中不再有该项目，尽管之前的规则是将其固定。这是因为排除结果的优先级高于钉牢结果。

结论

查询规则使调整相关性变得非常容易，无需修改任何代码。新的Kibana UI 允许在几秒钟内做出这些更改，让您和您的业务团队对搜索结果拥有更多控制权。

除电子商务外，查询规则还能支持许多其他应用场景：在支持门户中突出显示故障排除指南，在知识库中显示关键的内部文档，在新闻网站中宣传突发事件，或过滤掉过期的职位或内容列表。它们甚至可以执行合规规则，如根据用户角色或地区隐藏受限资料。

在本博客中，我们将使用Mastra构建一个知识代理，它能记住用户所说的话，并能在稍后调用相关信息，使用 Elasticsearch 作为记忆和检索后端。您可以轻松地将这一概念扩展到现实世界的使用案例中，例如，支持代理可以记住过去的对话和解决方案，使他们能够根据先前的上下文为特定用户定制响应或更快地提供解决方案。

在这里，您将看到如何一步一步地建造它。如果你迷失了方向，或者只是想运行一个已完成的示例，请点击此处查看软件仓库。

什么是 Mastra？

Mastra 是一个开源的 TypeScript 框架，用于构建具有可交换推理、内存和工具部分的人工智能代理。它的语义调用功能通过将信息作为嵌入信息存储在向量数据库中，使代理能够记住和检索过去的互动。这样，代理就能保留长期对话的上下文和连续性。Elasticsearch 支持高效的密集矢量搜索，是实现这一功能的绝佳矢量存储工具。当触发语义调用时，代理会将过去的相关信息拉入模型的上下文窗口，使模型能够将检索到的上下文作为其推理和响应的基础。

入门必备

• 节点 v18+

• Elasticsearch（8.15 或更新版本）

• Elasticsearch API 密钥

• OpenAI API 密钥

注意：您需要这个是因为演示使用了 OpenAI 提供商，但 Mastra 支持其他人工智能 SDK 和社区模型提供商，因此您可以根据自己的设置轻松更换。

构建 Mastra 项目

我们将使用 Mastra 内置的 CLI 为我们的项目提供脚手架。运行该命令：

您将收到一组提示，首先是

1.为项目命名。

2.我们可以保留默认值，也可以不填。

3.在本项目中，我们将使用 OpenAI 提供的模型。

4.选择 "暂时跳过 "选项，因为我们将把所有环境变量存储在一个".env "文件中，稍后再进行配置。

5.我们也可以跳过该选项。

初始化完成后，我们就可以进入下一步。

安装依赖项

接下来，我们需要安装一些依赖项：

• ai - 核心人工智能 SDK 软件包，提供用于在 JavaScript/TypeScript 中管理人工智能模型、提示和工作流程的工具。Mastra 是在 Vercel 的人工智能 SDK基础上构建的，因此我们需要依赖它来实现模型与代理的交互。

• @ai-sdk/openai - 将 AI SDK 连接到 OpenAI 模型（如 GPT-4、GPT-4o 等）的插件，可使用 OpenAI API 密钥进行 API 调用。

• @elastic/elasticsearch -Node.js 的官方 Elasticsearch 客户端、用于连接到弹性云或本地集群，以进行索引、搜索和矢量操作。

• dotenv - 从 .env 文件中加载环境变量文件到 process.env 文件中、允许您安全地注入 API 密钥和 Elasticsearch 端点等凭证。

配置环境变量

如果还没有.env 文件，请在项目根目录下创建该文件。或者，你也可以复制并重命名我在软件仓库中提供的.env 示例。在该文件中，我们可以添加以下变量：

基本设置到此结束。从这里，您就可以开始构建和协调代理。我们将更进一步，添加 Elasticsearch 作为存储和矢量搜索层。

添加 Elasticsearch 作为向量存储

新建一个名为stores 的文件夹，并在其中添加此文件。在 Mastra 和 Elastic 正式推出 Elasticsearch 向量存储集成之前，Abhi Aiyer（Mastra 首席技术官）分享了名为ElasticVector 的早期原型类。简单地说，它将 Mastra 的内存抽象与 Elasticsearch 的密集向量功能连接起来，因此开发人员可以将 Elasticsearch 作为其代理的向量数据库。

让我们深入了解整合的重要部分：

输入 Elasticsearch 客户端

本节定义了ElasticVector 类，并设置了 Elasticsearch 客户端连接，同时支持标准部署和无服务器部署。

• ElasticVectorConfig extends ClientOptions:这将创建一个新的配置接口，继承所有 Elasticsearch 客户端选项（如node,auth,requestTimeout ）并添加我们的自定义属性。这意味着用户可以通过任何有效的 Elasticsearch 配置和我们的无服务器特定选项。

• extends MastraVector:这样，ElasticVector 就可以继承 Mastra 的基础MastraVector 类，这是所有矢量存储集成都要遵守的通用接口。这可以确保从代理的角度来看，Elasticsearch 的行为与其他任何 Mastra 向量后端一样。

• private client: Client:这是一个私有属性，用于保存 Elasticsearch JavaScript 客户端的实例。这样，班级就可以直接与群集对话。

• isServerless 和deploymentChecked ：这些属性共同作用，以检测和缓存我们连接的是无服务器还是标准 Elasticsearch 部署。首次使用时会自动检测，也可以明确配置。

• constructor(config: ClientOptions):该构造函数接收一个配置对象（包含 Elasticsearch 凭据和可选的无服务器设置），并使用它在this.client = new Client(config) 行中初始化客户端。

• super():它调用 Mastra 的基本构造函数，因此继承了日志记录、验证助手和其他内部钩子。

此时，Mastra 知道有一个名为 ElasticVector

检测部署类型

在创建索引之前，适配器会自动检测您使用的是标准 Elasticsearch 还是 Elasticsearch Serverless。这一点很重要，因为无服务器部署不允许手动配置分片。

发生了什么？

• 首先检查您是否在配置中明确设置了isServerless （跳过自动检测）。

• 调用 Elasticsearch 的info() API 获取群集信息

• 检查build_flavor field （无服务器部署返回serverless)

• 如果没有 "构建味道"，则退回到检查标语阶段

• 缓存结果，避免重复调用应用程序接口

• 如果检测失败，则默认为标准部署

使用示例

在 Elasticsearch 中创建 "内存 "存储

下面的函数设置了一个 Elasticsearch 索引，用于存储嵌入式内容。它会检查索引是否已经存在。如果没有，它就会用下面的映射创建一个，其中包含一个dense_vector 字段，用于存储嵌入和自定义相似度度量。

有些事情需要注意：

• dimension 参数是每个嵌入向量的长度，这取决于你使用的嵌入模型。在我们的例子中，我们将使用 OpenAI 的text-embedding-3-small 模型生成嵌入，该模型输出大小为1536 的向量。我们将以此作为默认值。

• 下面的映射中使用的similarity 变量是由辅助函数 const similarity = this.mapMetricToSimilarity(metric) 定义的，该函数接收metric 参数的值，并将其转换为与 Elasticsearch 兼容的关键字，用于所选的距离度量。

  • 例如Mastra 使用cosine,euclidean, 和dotproduct 等一般术语来表示向量相似性。如果我们直接将度量euclidean 传递到 Elasticsearch 映射中，就会出现错误，因为 Elasticsearch 希望关键字l2_norm 代表欧氏距离。

• 无服务器兼容性：代码会自动省略无服务器部署的分片和副本设置，因为 Elasticsearch Serverless 会自动管理这些设置。

互动后存储新的记忆或笔记

该函数接收每次交互后生成的新嵌入以及元数据，然后使用 Elastic 的bulk API 将其插入或更新到索引中。bulk API 将多个写入操作合并为一个请求；索引性能的提升确保了在代理内存不断增长的情况下，更新仍能保持高效。

查询相似向量以实现语义召回

该功能是语义召回功能的核心。代理使用向量搜索，在我们的索引中找到类似的存储嵌入。

引擎盖下

• 使用 Elasticsearch 中的knn API 运行kNN（k-近邻）查询。

• 检索与输入查询向量最相似的 K 个向量。

• 可选择应用元数据过滤器来缩小搜索结果范围（例如，仅在特定类别或时间范围内进行搜索）

• 返回结构化结果，包括文档 ID、相似性得分和存储的元数据。

创建知识代理

现在，我们已经通过ElasticVector 集成看到了 Mastra 和 Elasticsearch 之间的连接，让我们来创建知识代理本身。

在agents 文件夹中，创建一个名为knowledge-agent.ts 的文件。我们可以从连接环境变量和初始化 Elasticsearch 客户端开始。

在这里，我们

• 使用dotenv 从.env 文件中加载变量。

• 检查 Elasticsearch 凭据是否被正确注入，我们是否能成功建立与客户端的连接。

• 在ElasticVector 构造函数中输入 Elasticsearch 端点和 API 密钥，以创建我们之前定义的向量存储实例。

• 如果使用 Elasticsearch Serverless，可选择指定isServerless: true 。这样可以跳过自动检测步骤，缩短启动时间。如果省略，适配器将在首次使用时自动检测您的部署类型。

接下来，我们可以使用 Mastra 的Agent 类来定义代理。

我们可以定义的字段有

• name 和instructions ：赋予其特性和主要功能。

• model:我们通过@ai-sdk/openai 软件包使用 OpenAI 的gpt-4o 。

• memory:

  • vector:指向我们的 Elasticsearch 存储库，因此嵌入式会从那里存储和检索。

  • embedder:使用哪种模型生成嵌入模型

  • semanticRecall 选项决定召回如何进行：

    • topK:检索多少条语义相似的信息。

    • messageRange:每场比赛应包括多少对话内容。

    • scope:定义内存边界。

快好了我们只需将新创建的代理添加到 Mastra 配置中。在名为index.ts 的文件中，导入知识代理并将其插入agents 字段。

其他领域包括

• storage:这是 Mastra 的内部数据存储，用于存储运行历史、可观察性指标、分数和缓存。有关 Mastra 存储的更多信息，请访问此处。

• logger:Mastra 使用Pino，这是一个轻量级结构化 JSON 日志记录器。它可捕捉代理启动和停止、工具调用和结果、错误以及 LLM 响应时间等事件。

• observability:控制人工智能跟踪和代理执行的可见性。它可以跟踪

  • 每个推理步骤的开始/结束。

  • 使用了哪种模式或工具。

  • 输入和输出。

  • 分数和评估

使用 Mastra Studio 测试代理

祝贺你如果您已经到达这里，那么您就可以运行这个代理，测试它的语义回忆能力了。幸运的是，Mastra 提供了一个内置的聊天用户界面，这样我们就不必自己创建了。

要启动 Mastra 开发服务器，请打开终端并运行以下命令：

在初始捆绑和启动服务器后，它应该会为你提供一个 Playground 的地址。

将此地址粘贴到浏览器中，您将看到 Mastra Studio。

选择knowledgeAgent ，然后开始聊天。

为了快速测试一切接线是否正确，请给它提供一些信息，如 "团队宣布 10 月份的销售业绩增长了 12% ，主要是由企业续订驱动的。下一步是扩大对中端市场客户的拓展"。下一步，开始新的聊天，并提问："我们说过下一步需要关注哪个客户群？知识代理应该能够回忆起您在第一次聊天中提供给它的信息。您应该会看到类似的回复：

看到这样的响应，意味着代理成功地将我们之前的信息以嵌入的形式存储在 Elasticsearch 中，并在稍后使用向量搜索进行检索。

检查代理的长期记忆存储

在 Mastra Studio 的代理配置中，前往memory 选项卡。这可以让您了解您的代理随着时间的推移学到了什么。嵌入并存储在 Elasticsearch 中的每一条消息、响应和交互都会成为长期记忆的一部分。您可以对过去的交互进行语义搜索，以快速找到代理之前了解到的信息或上下文。这与代理在语义回想时使用的机制基本相同，但在这里你可以直接检查它。在下面的示例中，我们搜索 "销售 "一词，并返回所有包含销售内容的互动。

结论

通过连接 Mastra 和 Elasticsearch，我们可以为代理提供内存，这是上下文工程的关键层。有了语义记忆功能，代理可以随着时间的推移建立上下文，将他们的反应建立在所学知识的基础上。这意味着更准确、更可靠、更自然的互动。

早期的整合只是一个起点。同样的模式可以让支持代理记住过去的票单，让内部机器人检索相关文档，或者让人工智能助理在对话中回忆起客户的详细信息。我们还在努力实现与 Mastra 的正式集成，以便在不久的将来使这种搭配更加完美。

我们很期待看到您的下一个作品。试试吧，探索Mastra及其内存功能，并随时与社区分享您的发现。