通过此次集成，Elasticsearch 用户获得了一个新的部署选项，能够将数据控制在安全边界内，实现可预测的基础设施成本，并原生运行于 Google Cloud 上。与此同时，更广泛的 Google Cloud 生态系统也能够使用 Jina 专为搜索和检索构建的最先进模型。

这是更广泛发布计划的第一阶段。与后续即将推出的模型一起，这一系列将构成一个完整的检索堆栈：嵌入您的数据、嵌入查询、检索和重排序候选结果、使用多模态嵌入将搜索扩展到图像——所有这些都在您控制的基础架构上完成。您今天就可以从 jina-embeddings-v3 开始，模型已经通过 Elastic Inference Service（EIS）在 Elasticsearch 生态系统中为生产搜索管道提供支持。

每个模型都运行在单个 NVIDIA L4（24 GB）上，这是 Google Cloud 上最具成本效益的 GPU 层级。Google Cloud Model Garden 上的大多数其他嵌入模型都需要 A100 80 GB 或 H100，其每小时实例成本大约是 L4 的三倍，这还没有算上词元用量。

通过 Vertex AI 部署时，无需额外的商业许可证。

为什么选择模型花园？

为什么要通过 Model Garden 进行部署，而不是使用 API？归结为三个因素：控制、成本和上下文。

您的数据永远不会离开本地环境

对大多数开发者来说，最大的吸引力在于自行部署的架构。当您通过 Model Garden 部署 Jina 模型时，模型权重运行在您自己的 Google Cloud 项目以及您自己的 VPC 内的 GPU 实例上。这对于任何面临数据安全顾虑（如金融或医疗行业）的从业者来说，都是一个颠覆性的改变。由于没有外部 API 调用，您的敏感数据始终保留在安全边界内。

按预测进行扩展

您不需要为每次嵌入句子或重排序文档付费，而是支付固定的每小时实例成本。而且，因为每个 Jina 模型都可以在 Google Cloud 上最经济的 GPU 级别 NVIDIA L4 上运行，所以入门门槛很低。无论您处理数千个请求还是数十亿个请求，您的基础架构费用都是可预测的。这种模式实际上会奖励您的流量增长，而不是向您征税。

一切尽在同一屋檐下

如果您的数据已经存放在 Google Cloud 上的 Elasticsearch、BigQuery 或 Cloud Storage 中，那么将推理引擎保持在这些数据附近是非常合理的。通过 Model Garden 部署，Jina 搜索基础模型继承了您已经在使用的所有企业级功能：用于访问控制的身份与访问管理 (IAM)、在现有 Google Cloud 账单上的统一计费，以及接入 Vertex AI Pipelines 进行机器学习运维 (MLOps) 工作流的能力。

虽然 Jina AI Cloud API 和 Elastic Cloud 为突发流量或现有搜索工作流提供了最快的路径，但 Model Garden 对于需要严格数据安全和大规模可预测成本的企业应用来说是理想选择。Elastic 希望在任何您需要的地方满足您的需求。

Jina AI 模型

jina-embeddings-v3

我们成熟的多语言嵌入模型，具有 572M 个参数和 8K 个词元上下文。在 Massive Text Embending Benchmark (MTEB) 英语测试中获得 65.5 分。支持五种任务特定的低秩适配 (LoRA) 适配器（检索查询/段落、文本匹配、分类、集群）以及从 1024 到 64 维度的 Matryoshka 截断。该模型已通过 EIS 在 Elasticsearch 生态系统中得到广泛采用。

我们首先推出 v3，因为许多生产系统已经依赖于它。如果您正在将基于 v3 的管道迁移到 Google Cloud，您现在可以直接运行相同的模型，无需更改嵌入维度或重建索引。

jina-embeddings-v5-text（small 和 nano）

我们于 2026 年 2 月发布的第五代文本嵌入模型，达到了顶级性能，可与数倍于其规模的模型相媲美。

v5-text-small （6.77 亿参数）：在多语言 MTEB（MMTEB）基准套件上得分为 67.0，该套件涵盖 9 种任务类型的 131 项任务；在 MTEB 英文基准上得分为 71.7。它是 MTEB 排行榜上最强大的 10 亿以下多语言嵌入模型。

v5-text-nano （2.39 亿参数）：在 MMTEB 上得分为 65.5。没有其他 5 亿参数以下的模型能达到这一水平。其规模不到大多数同类模型的一半，是边缘计算和延迟敏感型部署的自然选择。

两种模型均支持：

• 四个特定任务的 LoRa 适配器：检索、文本匹配、分类、集群。在推理时通过 task 参数选择合适的适配器。
• Matryoshka 维度截断：将嵌入维度从 1024（nano 为 768）减少至 32。适度截断（例如 256 维）时质量损失极小。维度减半大致使存储减半。
• 二值量化：使用二值化将 1,024 维嵌入从 2 KB 压缩到 128 字节。专门的训练使得这种压缩的损失极小。
• 多语言：small 支持 119 种语言，nano 支持 93 种语言。

jina-reranker-v3

一个 0.6B 参数的多语言 listwise 重排序器，采用最后但不晚的交互架构。查询和最多 64 个候选匹配项被输入到单个 131K 词元的上下文窗口中，模型在评分前执行跨文档比较。Jina Reranker v3 在 BEIR 上达到了 61.94 的 nDCG@10，优于规模大 6 倍的模型。这与 pointwise 重排序器（对每个文档单独评分）有本质区别，能产生更好的结果，尤其是对于从单个文档中进行段落检索。

jina-clip-v2

一个 0.9B 参数的多模态、多语言嵌入模型，将文本和图像映射到共享的 1024 维空间。它支持：

• 89 种语言的文本图像检索。
• 图像分辨率为 512×512。
• 8K 词元文本输入。
• 针对两种模态的 Matryoshka 截断（从 1024 维到 64 维）

在图像到文本基准测试中表现出色，包括多语言任务。

开始使用

Jina Embeddings v3 即日起在 Model Garden 上线。以下是运行它的方法。

您需要一个启用了 Vertex AI API 的 Google Cloud 项目，以及足够的 GPU 配额用于至少一个 g2-standard-8 实例（NVIDIA L4）。如果您是 Google Cloud 的新用户，请从设置指南开始。

Jina Embeddings v3 的 Model Garden 页面 将引导您完成整个流程：上传模型、创建终端节点、选择机器类型，然后部署。在自己的项目中打开它，并遵循指导步骤。在区域和配额允许的情况下，也可以使用 A100 和 H100 机器，但入门只需 L4 即可。

从点击到首次嵌入，整个过程只需几分钟。

后续计划

Jina Embeddings v3 是一个起点。在接下来的几周里，我们将把 Jina 检索堆栈的其余部分带到 Model Garden：v5 文本嵌入（small 和 nano）、jina-reranker-v3 以及用于多模态搜索的 jina-clip-v2。所有这些模型都将以相同的自行部署模式在单个 L4 GPU 上运行。

MCP 应用改变了答案的呈现形态。工具现在可以在返回文本摘要的同时提供交互式 UI，而宿主端（如 Claude Desktop、Claude.ai、VS Code Copilot、Cursor）则会直接在对话中进行内联渲染。模型利用保留的精炼文本进行逻辑推理。用户在聊天窗口旁就能获得一个实时可交互的界面。

三个特性让这种集成方式区别于“返回 URL 的 webhook”：

• 上下文保留。UI 就在对话中。无需切换标签页，无需切换上下文。
• 双向数据流。UI 可以调用 MCP 服务器上的工具以获取最新数据，宿主端也能将智能体的新结果推送回 UI，无需额外的 API 层或复杂的身份验证基础设施。
• 沙盒化的信任边界。MCP 应用在由宿主管控的 iframe 中运行。它们无法访问父页面、读取 Cookie，也无法逸出其容器。

安全运营依托于告警分类、调查图谱和 Attack Discovery，AI 智能体可将数百条告警关联为少数几条攻击链。可观测性意味着分布式链路追踪和时间序列下钻。在 Kibana 中构建意味着采用网格化的仪表板布局。如果将这些内容平铺成文字，就会失去其有用之处。我们为这三个平台都构建了 MCP 应用，并将它们一起开源，这样同一个对话就可以从分类队列转移到依赖关系图，再到实时仪表板，而无需离开聊天界面。

三个参考应用中的每一个都是一个为多个交互视图提供服务的 MCP 服务器，而不是一组独立的产品。仅安全应用就提供六个仪表板，它们共享同一个服务器框架、同一个工具可见性模型和同一个宿主桥接层。这种模式虽然轻量，但其提供的交互面正是价值倍增之处。

Elastic Security MCP 应用

为什么这对 SOC 很重要

当智能体告诉 SOC 分析师“主机 host-314 上有 47 条告警，这是摘要”时，它实际上并未开始实质性工作。它只是指出了工作的起点。真正的工作发生在告警列表、进程树、调查图谱和案例记录中。您无法仅凭一段文本就完成这些实际工作。

安全 MCP 应用程序返回了工作流本身。分析师提示代理，代理在聊天中返回了一个交互式仪表板，分析师可以在其中深入查看警报、运行威胁搜寻、关联攻击链并打开案例，所有这些操作都不会丢失对话的线索。由于所有发现、查询和案例都会回写到 Elasticsearch，同样的调查会在 Kibana 中等待，分析师可以在对话结束后接着处理。

六个交互式仪表板

Elastic Security MCP 应用提供了六个交互式组件，分别对应 SOC 的核心工作流。每个都是一个 React UI，当代理调用相应工具时，会在对话中以内联方式渲染：

每个工具都会返回一个紧凑的文本摘要，供模型进行推理，同时分析人员可以在交互式 UI 上操作。UI 还可以通过 MCP 主机桥在幕后获取最新数据。完整的工具模型和桥接 API 位于 代码库的架构文档。

该应用还随附 Claude Desktop 技能，以及 SKILL.md 文件，用于指导代理何时以及如何使用各个工具。从最新版本下载预构建的技能 zip 压缩包。

从告警到案例

四项技能覆盖了 SOC 的核心工作流。每个技能都会接收一个提示，调用一个工具，并返回一个交互式仪表板，以及供模型推理的文本摘要。分析师的一天通常从告警队列开始。

对告警进行分类。让代理按主机、规则、用户或时间窗口进行分类。让代理按主机、规则、用户或时间窗口进行分类。Alert Triage 技能会返回一个 AI 判定仪表板，位于原始警报列表上方。每个检测规则都有一个判定，将该规则的活动分类为良性、可疑或恶意，并附有置信度分数和推荐操作。点击任意警报即可打开包含进程树、网络事件、相关警报和 MITRE ATT&CK 标签的详细视图。无需在 AI 会话与 Kibana 告警仪表板之间反复来回，一切操作都在对话中实时完成。

开展威胁搜寻。让代理在您的索引中执行威胁搜寻。Threat Hunt 技能会返回一个 ES|QL 工作台，该工作台预先填充并自动执行了查询，结果中的每个实体均可点击进行深入查看。模型在表格下方写了一个简短的读数：哪些地方异常、哪些内容彼此关联、哪些值得进一步查看。然后，它会给出下一步切入点：要么更深入地研究威胁，要么在 MCP 应用中开始一项新技能，以补充迄今为止所做的工作。与之完美契合的是启动 Attack Discovery，从而为您已深入探究的告警和目前搜寻到的威胁收集更多上下文信息。与之完美契合的是启动 Attack Discovery，从而为您已深入探究的告警和目前搜寻到的威胁收集更多上下文信息。

运行 Attack Discovery。Attack Discovery 技能会触发 Attack Discovery API，并返回按优先级排序的发现列表。每个发现都是一组相互关联的警报，这些警报会被串联成一条攻击链，并会在前面优先展示 MITRE 策略、风险评分、置信度标签，以及受影响的主机和用户。智能体的摘要会按相同的排名顺序显示在发现下方，而对话现在已包含采取行动所需的一切：搜寻查询、分类决策、关联的链条，均已为下一步做好准备。

无需离开聊天窗口即可创建案例。批量批准发现项，或让代理为特定告警创建案例。案例管理技能会根据批准的发现项创建一个案例（附带源告警，继承自攻击链的 MITRE 策略），并以内联方式渲染实时案例列表。点击案例以查看其详细视图，其中包含一行 AI 操作按钮：总结案例、建议下一步、提取 IOC 和生成时间线。每个按钮都会将一个结构化的提示放回聊天中，这样代理就能获取案例上下文，无需重新说明上下文。代理的摘要位于案例列表下方，涵盖了完整的事件响应队列，包括刚创建的案例和仍需处理的早期发现。

本演练中的每一步都运行相同的循环：收到提示后，技能接收提示，工具返回一个简洁的文本摘要供模型进行推理，同时返回一个交互式用户界面（UI）供分析师操作。形成端到端的 SOC 流程——搜寻、分类、关联、创建案例，并推动下一步。模型会在每一步中保留会话上下文。单独调用其中任何一个，它仍然是完整的仪表板，指向您指定的数据切片。无论哪种方式，工作都会在对话中积累；没有标签切换，没有复制粘贴，没有交接。

另外两项技能补全了这个应用：检测规则浏览器，用于调整噪声较高的规则；样本数据生成器，用于在新集群上生成逼真的 ECS 事件。后续文章将深入探讨全部六个方面：调查图谱、攻击流程画布和端到端演练。

“Elastic Security 的 MCP 应用弥合了自动检测和手动搜索之间的差距。”通过将安全数据直接导入 Claude Desktop 的单一接口，我们在不到一小时内发现了“无声”威胁，这些风险不会触发标准警报，但需要立即采取行动。对于我们的分析师来说，这是一个力量倍增器。”Mandy Andress：Elastic 首席信息安全官（CISO）。

运作方式

每个 MCP 应用都是一个小型 Node.js 服务器，其工具会返回供模型推理的精炼文本摘要，以及由宿主内联渲染的 React UI。由于它是基于开放的 MCP 应用程序规范构建的，因此同一服务器可在任何兼容主机上运行——有关完整设计，请参阅软件仓库的架构文档。

试用

需要启用 Security 的 Elasticsearch 9.x，以及用于案例、规则和攻击发现的 Kibana。最快的方式是使用最新版本中的一键式 .mcpb 安装包——在 Claude Desktop 中双击它，系统会提示您输入 Elasticsearch URL 和 API 密钥。Cursor、VS Code、Claude Code、Claude.ai 和从源代码构建的设置指南都在软件仓库中。

Elastic Search MCP 应用程序：通过对话构建的仪表板

Kibana 用户都深知创建仪表板的繁琐：必须停下工作，打开 Kibana，选择索引、字段和可视化效果，最后再调整保存。一个图表还没显示出来，就已经经历了五次上下文切换。

新的 example-mcp-dashbuilder 参考应用将其简化为一个提示。要求代理“为我构建一个包含收入指标、订单趋势和类别细分的仪表板”，而且仪表板会在对话中返回，无需切换标签。

在该提示后，代理通过 ES|QL 探索您的 Elasticsearch 数据，并选择与数据相匹配的图表类型：用于比较的条形图、用于趋势的折线图、用于 KPI 的指标卡，以及用于二维模式的热力图。它在 Kibana 的 48 列网格上布置面板，使用 Elastic UI Borealis 主题，结果是完全交互式的：您可以直接在聊天中拖动、调整大小和将面板分组到可折叠的部分中。当仪表板看起来合适时，只需一次工具调用即可将其导出到 Kibana，同时保留 ES|QL 查询和自定义颜色。您还可以将现有的 Kibana 仪表板导入到聊天中，以便进行 AI 辅助编辑。

其原理与 Security 应用相同：当产物本身就是产品时，在对话中直接返回它，就能打通从描述需求到看到结果之间的闭环。

在底层，它遵循相同的 MCP 应用模式。Node.js 服务器注册一个面向模型的 view_dashboard 工具，以及一组仅供应用内部调用、由 UI 直接调用的工具（数据获取、布局持久性、时间字段检测、导出/导入）。仪表板视图本身是一个单一的独立 HTML 文件，与 vite-plugin-singlefile 捆绑在一起，并作为 MCP 应用资源提供。开发者复刻（fork）该代码库后，会获得与 Security 应用中相同的服务器 shell 和主机桥，但面向不同的任务场景。example-mcp-dashbuilder README 文件包含了完整的架构和图表类型参考。

Elastic Observability MCP 应用

第三个参考应用 Elastic Observability MCP 应用则是针对 SRE 场景解决这一“交互形态”问题的对应版本。当生产环境中出现故障时，值班工程师需要的答案不是一张图表，而是由 K8s 指标、APM 拓扑、ML 异常、风险评估等信息拼接而成的诊断。答案的形式是一个因果故事：什么失败了，为什么，什么取决于它，以及下一步该怎么做。

六种支持可观测调查工作流的工具

集群健康状况汇总

询问“哪里出故障了？”或“给我一份状态报告”，即可一目了然地掌握全局：包括整体健康状态标识、性能下降的服务及其原因、内存占用最高的 pod、异常严重程度分解，以及服务吞吐量——全部在一个内联视图中。这是当您感觉有些不对劲，但又不知道该从哪里入手的时候的起点。视图会根据您的部署支持的内容进行调整。APM 为您提供服务运行状况。Kubernetes 指标添加了 pod 和 Node 上下文。ML 作业也会将异常纳入其中。

服务依赖关系图表

问“哪些服务会调用 checkout？”或者“显示拓扑结构”并获取分层依赖图表——上游调用者、下游依赖项、协议、每条边的调用量和延迟。让我们让 Claude “给我看看前端的服务依赖关系”：

缩放、平移和悬停以获取理解复杂服务关系所需的所有详细信息：

利用影响半径评估风险

询问“如果我的 k8s Node 宕机会发生什么？”并获取一个辐射状影响图：目标 Node 位于中心，完全中断的部署用红色表示，性能下降的用琥珀色表示，未受影响的用灰色表示。浮动摘要卡显示有风险的 pod 和重新调度的可行性。单副本部署被标记为单点故障。

观测

代理访问 Elastic 的主要方式——一个工具，三种模式，满足三种不同需求。说“CPU 当前情况如何？”，它会运行一次 ES|QL 查询并返回一个表。说“显示我接下来 60 秒的前端延迟”，它会实时采样该指标，并原地更新图表。说“当内存降到 80MB 以下时告诉我”或“在接下来 10 分钟内留意任何异常”，它会一直等待，直到条件触发或时间窗口结束。视图可根据模式进行调整：用于单次查询的结果表、用于采样和阈值条件的带当前/峰值/基线统计数据的实时趋势图，以及用于异常模式的按严重程度评分的触发卡。

运作方式

与 Security 和 Search 应用相同的 MCP 应用模式：一个 Node.js 服务器，六个面向模型的工具，对应六个单文件视图资源。工具按部署后端（通用、APM 依赖、K8s 依赖、ML 依赖）进行分组，因此代理和用户都可以提前知道哪些工具适用于特定部署，而不是在调用时发现功能缺口。MCP 应用还包含一个示例的 Agent Builder 工作流：k8s-crashloop-investigation-otel 可以在 Kubernetes 告警触发时启动，并在您打开任何仪表板前返回结构化的根因摘要。

代理化技术栈，交互式

关于此模式的三个属性值得直接说明。首先，工具结果不再是工作的终点，而是工作的起点：对话返回的是您可以采取行动的接口，而不是您必须采取行动的摘要。其次，同一个智能体、同一个模型上下文和同一个对话线程，现在可以在 Security、Search 和 Observability 界面之间顺畅切换，而无需离开对话。第三，这之所以可行，是因为 Elasticsearch 和 Kibana 已经公开了 API。MCP 应用程序是我们已提供的产品功能之上的一个轻量级的交互层。

Attack Discovery 已经为该应用内的关联发现视图提供支持。在堆栈内部，同样的代理模式进一步延伸：Elastic 工作流自动执行确定性步骤（丰富实体、创建案例、隔离主机），而 Agent Builder 则对数据进行推理并调用这些工作流作为工具。MCP 应用将同一套安全界面引入外部对话；工作流和 Agent Builder 则在技术栈内部对其进行扩展。不同的入口点，底层是相同的 Elastic API。

试用：

• 安全性：example-mcp-app-security
• 搜索与仪表板： example-mcp-dashbuilder
• 可观测性：example-mcp-observability

还没有 Elasticsearch 集群吗？开始免费试用 Elastic Cloud。如需进一步了解安全应用背后的构建模块，请参阅相关 Security Labs 文章：Elastic 工作流和 Agent Builder、Agent 技能，以及攻击发现。

如今，这一切变得简单得多。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 数据平面的原生访问权限：

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey $EC_API_KEY" \
  "https://api.elastic-cloud.com/api/v1/users/auth/keys" \
  -d '{
    "description": "unified-automation-key",
    "expiration": "90d",
    "role_assignments": {
      "project": {
        "elasticsearch": [
          {
            "role_id": "elasticsearch-admin",
            "organization_id": "YOUR_ORG_ID",
            "all": false,
            "project_ids": ["YOUR_PROJECT_ID"],
            "application_roles": ["admin"]
          }
        ]
      }
    }
  }'

一旦创建，您只需在 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 自行决定。当前尚未发布的任何功能或功能性可能无法按时提供或根本无法提供。

组织往往会积累大量文档，例如支持工单、法律文件、新闻资讯和研究论文；在提出正确的问题之前，首先需要了解这些文档里都包含哪些内容。没有标签或训练数据，手动审查数千份文档是不切实际的。当您不知道要搜索什么时，传统搜索无济于事。

本文将介绍一种 Elasticsearch 原生方法，用于无监督文档集群和时序故事追踪，帮助解决这一发现难题。读完本文后，您就可以像这样跨天追踪故事脉络：

您将发现：

• 为什么当您希望在没有查询的情况下进行主题发现时，集群嵌入（而非检索嵌入）至关重要。
• 如何借助 Elasticsearch 的 k 近邻 (kNN) 和批量 msearch，通过密度探测质心分类按主题对文档进行分组。
• significant_text 如何自动为集群添加标签，让主题在无需训练模型的情况下也能清晰呈现。
• 时间故事链如何将每日集群联系起来，展示主题如何逐日演变。

该管道以来自 BBC News 和 The Guardian 的约 8,500 篇 2025 年 2 月文章作为测试语料库。新闻之所以适合作为示例，是因为它具有清晰的时间演化特征；而在任何文档发现至关重要的场景中，这种模式同样适用，例如法律审查、合规监控、研究整合和客户支持分流。

技术栈：

• Jina v5 集群嵌入：用于主题分组的任务专用低秩自适应 (LoRA) 适配器。Jina 已加入 Elastic，其模型可通过 Elastic Inference Service (EIS) 原生调用。
• Elasticsearch：可扩展的 kNN、significant_text 标签生成和向量存储。
• DiskBBQ：一种基于磁盘的向量索引格式，结合了 Better Binary Quantization (BBQ) 与分层 k-means 分区，以加速近似最近邻 (ANN)。这种索引分区是向量搜索的内部机制，与本文使用的密度探测集群算法相互独立。与 bbq_hnsw 相比，bbq_disk 将量化向量存储在磁盘上，并仅在堆内存中保留分区元数据，在保持高召回率的同时，大幅降低了资源需求。
• 全局集群 + 每日时间链接：发现与故事演变。

您需要：

• Elasticsearch 部署（Elastic Cloud、Elasticsearch Serverless 或 Elastic 自托管 8.18+/9.0+）：bbq_disk 需要 8.18 或更高版本。可选的 diversify retriever 部分需要 9.3+ 或 serverless。
• Jina API 密钥：免费层级包含 1,000 万个 token，足以覆盖核心集群管道的需求（约 425 万个 token）。可选的 retrieval-versus-clustering 对比需要进行第二轮嵌入计算。
• Guardian API 密钥（免费）。

设置

安装所需软件包：

pip install elasticsearch pandas numpy plotly umap-learn python-dotenv pydantic-settings datasets requests

可选（仅当您从此仓库运行抓取帮助程序时）：

pip install beautifulsoup4

然后在项目根目录的 .env 文件中配置 API 密钥：

ELASTIC_CLOUD_ID=your-cloud-id        # or ELASTIC_HOST=https://...
ELASTIC_API_KEY=your-api-key
JINA_API_KEY=your-jina-key
GUARDIAN_API_KEY=your-guardian-key

此笔记本调用 load_dotenv(override=True)，因此本地 .env 值优先。

Connected to Elasticsearch

第 1 部分：发现式集群 —— 为什么要使用集群嵌入？

大多数向量搜索都会使用经过训练的检索嵌入来将查询与相关文档进行匹配。这对于搜索非常合适，但并不适合用于发现。当您希望在没有任何查询的情况下找到语料库中的主题时，您需要使用能将相似文档组合在一起的嵌入。

Jina v5 通过面向特定任务的低秩适配 (LoRA) 适配器解决了这个问题。LoRA 在保持大部分基础模型权重冻结的同时，对目标内部层添加小幅低秩更新，使模型行为转向特定任务，而无需完全重新训练。同一基模型根据 task 参数产生不同的嵌入：

集群适配器经过训练，使相同主题的文档在嵌入空间中更接近，而不同主题的文档则更远离。下面的可视化对比会更直观地呈现这种差异。

检索与集群：可视化对比

为了展示这种差异，我们分别使用两种任务类型对文档样本进行嵌入。集群在原始 1024 维嵌入空间中执行；Uniform Manifold Approximation and Projection (UMAP) 仅用于将这些嵌入投影到 2D 进行可视化。UMAP 保留局部邻域结构，因此可用于比较集群的分离程度。

下图展示了同一组 480 篇文档样本分别采用两种任务类型进行嵌入后，再通过 UMAP 投影到 2D 的结果。请观察集群面板中那些更紧密、彼此分离更明显的颜色分组。

    Full dataset: 8,495 articles
    Sources: guardian: 5749, bbc: 2746
    Date range: 2025-02-01 to 2025-02-28


    Sample: 480 docs across 8 sections
    section
    Film              60
    World news        60
    Australia news    60
    Opinion           60
    Football          60
    US news           60
    Sport             60
    Business          60


    Clustering embeddings: 480
    Retrieval embeddings:  480


    UMAP projection complete

检索嵌入（左）会更分散地铺开各个主题；集群嵌入（右）则会基于相同文档形成更紧密、彼此分离更明显的分组。

集群嵌入能够形成更紧密、视觉上也更清晰的分组。检索嵌入会更均匀地分布各个主题，因此非常适合搜索（细粒度相似度）；但对发现来说，更关键的是紧密的主题集群。

这就是为什么在本演练的其余部分中使用 task="clustering" 的原因。

加载数据集

该语料库结合了 2025 年 2 月的两个新闻来源：

• BBC News通过RealTimeData/bbc_news_alltimeHuggingFace 数据集。
• The Guardian 通过 Guardian Open Platform API。

纳入多个来源，有助于验证集群识别出的是真正的主题，而不是某个来源特有的写作风格。

    Total articles:  8,495
    
    Source breakdown:
    source
    guardian    5749
    bbc         2746
    
    Date range: 2025-02-01 → 2025-02-28
    Days covered: 28
    
    Sample article:
      Source:  guardian
      Title:   Carbon monoxide poisoning ruled out in death of Gene Hackman and wife, police sa
      Section: Film
      Text:    Authorities have ruled out that Gene Hackman and his wife, Betsy Arakawa, died from carbon monoxide poisoning earlier this week in their home in Santa Fe, New Mexico. The Santa Fe county sheriff, Adan...

使用集群任务进行嵌入

在调用 Jina v5 API 处理所有文档时均会传入 task="clustering"。嵌入会缓存到磁盘，因此后续运行会完全跳过 API。

API 调用很简单。task 参数是与典型嵌入使用的关键区别：

payload = {
    "model": "jina-embeddings-v5-text-small",
    "input": texts,
    "task": "clustering",  # ← This selects the clustering LoRA adapter
}

以下时间反映的是缓存命中情况。第一次对 API 运行时间更长，具体取决于语料库大小。

    Embeddings ready: 8,495 vectors of dimension 1024
    Time: 0.6s

索引到单个 Elasticsearch 索引

对于发现式集群，整个月的数据都会写入同一个索引 (docs-clustering-all)。每日分区会在后续阶段进行，用于实现时间故事链接。

索引映射对向量字段使用 bbq_disk：

{
  "embedding": {
    "type": "dense_vector",
    "dims": 1024,
    "index": true,
    "similarity": "cosine",
    "index_options": {
      "type": "bbq_disk"        // hierarchical k-means partitioning for ANN index lookup; separate from this post's clustering algorithm
    }
  }
}

1024 维 float32 向量大小为 4 KB。 bbq_disk 使用分层 k-means 将向量划分为小集群，对其进行二进制量化，并将全精度向量存储在磁盘上以便进行二次评分。只有分区元数据保留在堆内存中，因此即使面对大型语料库，内存需求仍然较低。对于能够承受更多堆内存的工作负载，bbq_hnsw 构建分层可导航小世界 (HNSW) 图，以实现更快的查找，但资源消耗更高。

dense_vector 字段类型支持多种量化策略：bbq_disk 和 bbq_hnsw 最适合高维嵌入，例如此处使用的 1,024 维向量。

    Indexed 8,495 documents into docs-clustering-all
    Time: 57.5s

集群：基于密度探测的质心分类

传统的集群算法（如 HDBSCAN）假设您可以将完整的 N×d 向量矩阵保存在内存中，并运行重复的完整遍历更新。对于 8,495 篇 1024 维文档而言，这一规模尚可管理（约 35 MB）；但如果没有额外基础设施，这种方法就无法扩展到数百万篇文档。

从概念上看，该算法类似于采用 Voronoi 分配和噪声底限的 KMeans++ 初始化；但它将 Elasticsearch kNN 搜索作为计算原语，因此几乎所有工作都在服务器端完成。

1. 抽取 5% 的文件 作为密度探针（随机抽样，至少 50 个）。
2. 通过批量 msearch kNN 查询探测密度。每个探针发出 kNN 查询，并记录其邻居的平均相似度。高平均相似度 = 嵌入空间中的稠密区域。msearch 在单个 HTTP 调用中发送多个搜索请求，这一点至关重要：密度探测生成数百个 kNN 查询，批量处理可避免每个请求的开销。
3. 通过多样化策略选择高密度种子：将密度高于中位数的候选种子按密度从高到低排序，只有当它与每个现有种子的余弦相似度都低于分离阈值时，才按贪婪策略予以接受。这是唯一的客户端计算（8k 文档约 0.01 秒）。
4. 通过 msearch kNN 按质心对所有文档进行分类：每个种子都作为一个质心，kNN 搜索会检索相似度高于阈值的邻近文档。每个文档都会被分配给返回该文档且得分最高的质心。小集群被归为噪声。

Elasticsearch 负责处理核心计算：使用 msearch 进行密度探测和分类，并使用 significant_text 生成标签。对于该语料库（8,495 个文档），5% 的密度探针样本会发起 425 个 kNN 探针查询，msearch 会将其批量处理为 9 次 HTTP 调用（批大小为 50），从而避免每个探针单独发起一次请求的开销。再结合 bbq_disk ANN 查找，整个集群阶段便能兼顾速度与可扩展性。在集群过程中，kNN 查询会使用尽可能小的 num_candidates 值来提升速度；而在生产环境的搜索查询中，则应使用更高的 num_candidates 值，以牺牲一定延迟为代价换取更高的召回率。

集群的自然大小由每个质心周围的嵌入空间密度决定，而非硬性的 k 上限。主题越密集的区域，形成的集群就越大；而越小众的主题，则会形成更小的集群。

为什么不选择 KMeans 或 HDBSCAN？

KMeans 假设集群为球形，并需要将完整的 N×d 矩阵加载到内存中。对于适合内存的语料库，HDBSCAN 是一个强有力的替代方案。它既可以处理任意形状的集群，也具备更易理解的密度语义。

密度探测质心方法面向的是另一类场景：您希望在同一系统中完成存储、检索和集群，或者数据规模已经大到使客户端矩阵运算变得不切实际。它使用 Elasticsearch kNN 作为计算原语，处理任意大小的集群，并将几乎所有计算保留在服务器端。

    Clustered global index in 31.6s
      Total clusters: 82
      Total noise:    2420 (28.5%)
      Density probes: 425 kNN queries via 9 _msearch HTTP calls

理解噪声率

约 28% 的噪声率是有意为之，并不意味着系统出现了故障。在配置的 similarity_threshold 下，不属于任何密集集群的文档将保持未分配状态，而不是被强制匹配到不合适的集群中。这相当于一道质量门槛：评论专栏、短文和一次性报道往往难以形成集群，因为它们缺乏构成连贯分组所需的主题密度。

阈值可调：降低 similarity_threshold 会产生更激进的集群（分配更多文档，但集群更松散），提高则会收紧集群并增加噪声比例。对于这种包含混合新闻内容的语料库，约 30% 的噪声比例是一个合理的平衡点。生产部署应根据特定领域的质量标准调整阈值。

使用 significant_text 自动添加标签

现在，每个集群都需要一个便于人工理解的标签。Elasticsearch 的 significant_text 聚合会找出在前景集（集群）中出现异常频繁、而在背景集（完整语料库）中不常见的词项。

其底层采用统计启发式方法（默认为 JLH 分数），平衡了绝对频率与相对频率的变化，无需机器学习，也无需调用大语言模型 (LLM)。例如，一个关于英国政治的集群，可能会浮现出 starmer、labour、downing 等词项，因为与整体新闻语料库相比，这些词项在该集群中出现得异常频繁。

在这一全局处理阶段，标签直接基于 docs-clustering-all 计算，因此前景集和背景集都取自整个月的数据。在第 2 部分中，标签会使用每日索引模式 (docs-clustering-*)。这是一个通配符，可让查询同时覆盖所有匹配的索引，从而为 significant_text 提供更广泛的背景，以获得更好的对比效果。

一个最小查询形状如下所示：

{
  "size": 0,
  "query": { "term": { "cluster_id": "72" } },
  "aggs": {
    "label_terms": {
      "significant_text": {
        "field": "text",
        "size": 5,
        "filter_duplicate_text": true
      }
    }
  }
}

significant_text significant_text 也可作为一道质量门槛：未产生任何显著词项的集群，说明其缺乏可区分的词汇特征。这类分组本身并不连贯，因此应归为噪声，而不应赋予带有误导性的标签。

一个轻量级的确定性清理步骤会移除噪声较大的标签词项（如数字 token 和通用词），并在必要时回退到代表性标题。这样既保留了 Elasticsearch 原生标签的特点，也提升了可读性。

    Sample cluster labels:
      cluster   3  (200 docs)  arsenal | mikel | villa
      cluster   1  (198 docs)  volodymyr | ukrainian | kyiv
      cluster   0  (196 docs)  hostages | hamas | israeli
      cluster   4  (187 docs)  scrum | rugby | borthwick
      cluster  52  (185 docs)  fossil | renewable | renewables
      cluster  10  (156 docs)  labour | gwynne | mps
      cluster  40  (151 docs)  novel | novels | literary
      cluster  11  (149 docs)  mewis | sarina | wiegman
      cluster  44  (143 docs)  flooding | rainfall | rain
      cluster  13  (131 docs)  doge | musk | elon
      cluster  12  (128 docs)  murder | insp | knockholt
      cluster   5  (124 docs)  putin | backstop | starmer


    Reassigned 35 docs from incoherent clusters to noise
    Total docs: 8,495
    Clustered:  6,040 (71.1%)
    Noise:      2,455 (28.9%)

集群可视化

下方的可视化结果展示了全局集群阶段的发现，包括按日期划分的集群文档与噪声文档分布、整个月的 UMAP 投影，以及用于验证集群反映的是主题而非来源的来源构成图。

2025 年 2 月期间，集群文档与噪声文档的每日分布情况。

UMAP 中的每个彩色岛屿都代表一个集群：一组关于同一主题的文章，纯粹是通过嵌入相似性而发现的。灰色噪声点则是未能明确归入任何集群的文章（通常是短篇文章、观点文章或一次性报道）。

来源细分图表确认，集群中的文章同时来自 BBC News 和 The Guardian。集群找到的是主题，而非来源，这正是无监督发现应该产生的结果。

使用 diversify retriever 探索集群的广度

普通 kNN 返回与集群质心（密集核心）最相似的文档。但真实的集群往往还会涵盖多个子主题。diversify retriever 使用最大边际相关性 (MMR)，呈现既与质心相关、彼此之间又有所差异的文档。

关键参数是λ（lambda）：

• λ = 1.0 → 纯相关性（与普通 kNN 相同）。
• λ = 0.0 → 纯多样性（结果最大程度分散）。
• λ = 0.5 → 均衡：既与主题保持相关，又能覆盖不同角度。

最简 retriever 请求结构如下：

{
  "size": 8,
  "retriever": {
    "diversify": {
      "type": "mmr",
      "field": "embedding",
      "lambda": 0.5,
      "query_vector": "",
      "retriever": {
        "knn": {
          "field": "embedding",
          "query_vector": "",
          "k": 50,
          "num_candidates": 100
        }
      }
    }
  }
}

在 diversify 层级，type、field 和 query_vector 参数均为必需：field 用于告知 MMR 应使用哪个 dense_vector 字段来计算结果之间的相似度，而 query_vector 则提供相关性评分的参考向量。

这可以让您回答：“这个集群到底涵盖了什么？”而不仅仅是“它的中心是什么？”

    Exploring cluster 52 (185 docs)
    Label: fossil | renewable | renewables
    Centroid computed (dim=1024)


    ========================================================================
    Plain kNN (closest to centroid)
    ========================================================================
      1. [0.9738] Green campaigners fear ministers are poised to award billions of pounds in fresh subsidies to Drax power station, despite strong concerns...
      2. [0.9710] Thirteen more oil and gas licences could be cancelled as ministers decide new guidance for fossil fuel extraction after a landmark court...
      3. [0.9699] Experts have accused the fossil fuel industry of seeking special treatment after lobbyists argued greenhouse gas emissions from oilfields...
      4. [0.9681] Burning wood is a terrible way of producing electricity . Chopping down trees destroys habitats for wildlife, and growing new trees cannot...
      5. [0.9649] Keir Starmer will do huge damage to the global fight against climate change if he gives in to political pressure and allows the development...
      6. [0.9641] Labour will next week be confronted with stark policy choices that threaten to expose the fault lines between the Treasury and the...
      7. [0.9638] The Drax power station near Selby in north Yorkshire burns imported wood pellets  The government has agreed a new funding arrangement with...
      8. [0.9581] If you care about the world we are handing on to future generations, the news on Thursday morning was dramatic. This January was the...
    
    ========================================================================
    Diversify retriever (MMR, lambda=0.5)
    ========================================================================
      1. [0.9738] Green campaigners fear ministers are poised to award billions of pounds in fresh subsidies to Drax power station, despite strong concerns...
      2. [0.9434] Oil and gas interests have waged a coordinated campaign to kill pro-electrification policies that ban gas connections in new buildings ,...
      3. [0.9303] It was interesting to read that new licences for oil and gas production in the North Sea are being delayed by legal action ( Thirteen more...
      4. [0.9139] The US energy secretary, Chris Wright, has said he “would love to see Australia get in the game of supplying uranium and maybe going down...
      5. [0.9077] Rachel Reeves was facing criticism on Saturday night as it was confirmed that a report she cited as evidence that a third ­runway at...
      6. [0.8996] When Margaret Thatcher opened the Hadley Centre for Climate Change in 1990 journalists suggested she was attempting to appear to be doing...
      7. [0.8993] The vast majority of governments are likely to miss a looming deadline to file vital plans that will determine whether or not the world has...
      8. [0.8987] European imports of seaborne gas shipments fell by a fifth last year to their lowest level since the pandemic, according to a new report,...
    
    Overlap: 1/8 documents appear in both result sets
    
    Avg pairwise similarity (lower = more diverse):
      Plain kNN:          0.9057
      Diversify retriever: 0.6965

普通 kNN 的结果往往集中在主题的某一个侧面，也就是那些与质心最相似、彼此之间也最相似的文档。diversify retriever 则会展示同一集群的不同侧面，包括子主题、不同来源和多样化视角。

多样性指标定量证实了这一点：diversify retriever 结果的平均两两相似度较低，意味着返回的文档覆盖范围更广。

这适用于：

• 理解一个集群实际涵盖的范围，不仅要关注其中心，还要关注其边缘。
• 生成摘要。多样化且有代表性的文档为 LLM 提供了更好的素材。
• 寻找代表性示例，用于人工审核或下游标签生成。
• 质量检查。如果多样化结果看起来不够连贯，就说明这个集群可能需要进一步拆分。

第 2 部分：时间故事链

跨天追踪故事

第 1 部分对整个月的数据进行了全局集群，以发现其中的主题。为了呈现时间演化，同样的密度探测质心分类会按天在每日索引上独立运行，再将相邻日期的集群连接起来。请注意，每日集群与第 1 部分中的全局集群相互独立；每天都会生成自己的集群分配和标签，并根据当天的内容进行调整。

链接方法：采样与查询

对于第 A 天的每个集群：

1. 采样几个代表性文档。
2. 对 B 天的索引运行 kNN。
3. 统计落入 B 天每个集群的命中数量。
4. 如果命中比例超过阈值（kNN 比例 ≥ 0.4），则记录一条链接。

这速度很快（每个集群只查询少量文档，不是全部），并且使用 Elasticsearch 的原生 kNN，无需外部工具。

Preparing daily indices for temporal linkage...


Indexed 8,495 docs into 28 daily indices


Temporal links found: 808 in 145.4s

Strongest links:
  2025.02.01 'league | arsenal | premier' -> 2025.02.02 'league | season | striker'  (100%)
  2025.02.03 'league | striker | loan' -> 2025.02.04 'league | striker | season'  (100%)
  2025.02.03 'score | operator | gedling' -> 2025.02.04 'league | striker | season'  (100%)
  2025.02.12 'playoff | leg | bayern' -> 2025.02.13 'league | players | injury'  (100%)
  2025.02.14 'league | injury | football' -> 2025.02.15 'league | premier | football'  (100%)
  2025.02.18 'russia | ukraine | talks' -> 2025.02.19 'saudi | russia | arabia'  (100%)
  2025.02.18 'football | league | bayern' -> 2025.02.19 'league | manchester | players'  (100%)
  2025.02.21 'league | premier | manchester' -> 2025.02.22 'game | players | defeat'  (100%)
  2025.02.21 'rugby | calcutta | brilliant' -> 2025.02.22 'game | players | defeat'  (100%)
  2025.02.26 'metals | kyiv | ukrainian' -> 2025.02.27 'ukraine | russia | talks'  (100%)

kNN 比例达到 100% 表示源集群中的所有采样文档都落入同一个目标集群，也就是强度最高的跨日关 流水以上大多数关联都与足球相关，这很合理：英超联赛的报道每天都有，且主题一致性很高。

score | operator | gedling → league | striker | season 链接是一个小众本地足球集群（Gedling 是一家非联赛俱乐部）在第二天被吸收到更广泛的英超联赛集群中的一个例子，这是每日以不同粒度重新集群的自然效果。

构建故事链

故事链是由连续多天的关联集群组成的序列。

单个配对链接可以显示周一与周二“英国政治”集群之间的关联。故事链则能揭示完整的发展脉络：一个故事从周一开始，在一周内持续发展，并在周五逐渐淡出。

链通过贪婪策略构建，所依据的是 kNN 比例 ≥ 0.4 的关联；这意味着源集群中至少有 40% 的采样文档会落入同一个目标集群。算法从最早出现的集群开始，并始终沿着最强的出向关联继续延伸。

    Strong links (kNN fraction >= 0.4): 244
    Story chains spanning 3+ days: 18
      Chain 1: 'ukrainian | kyiv | eastern' (19 days: Feb 3 → Feb 21)
      Chain 2: 'playing | opposition' (19 days: Feb 10 → Feb 28)
      Chain 3: 'tadhg | maro | cadan' (10 days: Feb 1 → Feb 10)
      Chain 4: 'invade | china | putin' (8 days: Feb 21 → Feb 28)
      Chain 5: 'elected | labour | leader' (7 days: Feb 12 → Feb 18)
      Chain 6: 'film | swift | awards' (6 days: Feb 2 → Feb 7)
      Chain 7: 'amendment | termination | reporting' (6 days: Feb 12 → Feb 17)
      Chain 8: 'officers | scene | police' (5 days: Feb 1 → Feb 5)

最长的链条连续 19 天追踪乌克兰–俄罗斯相关报道。考虑到 2025 年 2 月持续紧张的地缘政治局势，这并不令人意外。其次是贯穿当月 19 天的英超足球报道。更短的链条则对应于颁奖季（电影/颁奖，6 天）、六国橄榄球赛（10 天）以及英国政治领导层相关报道（7 天）。每条链都代表一条故事轨迹，这些轨迹完全是基于每日索引之间的嵌入相似性自动发现的。

Sankey：可视化故事流

Sankey 图是一种流向可视化图表，其中连线宽度表示连接强度。在这里，每个垂直条带代表一天，每个节点代表一个每日集群（大小由文档数量决定），每条彩色路径则描绘出一条跨时间延展的故事链。链接宽度表示 kNN 重叠强度：更粗的链接意味着更多采样文档落入目标集群。每条链都使用统一颜色，因此从左到右的一条同色路径就代表一个故事的发展过程。

例如，乌克兰－俄罗斯链（作为较长路径之一清晰可见）从 2 月初一直延续到第三周；其链接始终较粗，表明该主题在不同日期之间具有很强的连续性。

时间故事链贯穿 2025 年 2 月。每条彩色路径都代表一个跨天延续的故事；连线宽度表示 kNN 重叠强度。

这种方法的成果

本文完整介绍了基于 Elasticsearch 构建的无监督文档集群管道：

1. 集群嵌入：Jina v5 的任务专用适配器可生成针对主题分组优化的嵌入，而不仅仅是用于查询-文档匹配。
2. 全局发现式集群：在一个索引中对整个月的数据进行集群，可最大限度地发掘跨日主题。
3. 密度探测质心分类：取样 5%，通过 msearch kNN 探测密度，选择不同的高密度种子，再根据这些质心对所有文档进行分类。Elasticsearch 负责处理大部分计算任务；客户端仅负责耗时极短（约 0.01 秒）的种子选择工作。
4. significant_text标签生成：无需借助 ML 模型或人工标注，显著性检验就能生成有意义的集群标签。无法产生任何显著词项的集群，说明其内部缺乏连贯性，因此会被降为噪声——这也是一种内置的质量控制机制。
5. 时间故事链接：借助每日索引以及跨索引的采样与查询 kNN，追踪故事如何随时间演变。

关键要点：

• 嵌入任务类型至关重要：集群嵌入能够形成明显更紧密的主题分组。
• 借助 kNN 搜索，Elasticsearch 既可以充当存储层，也可以充当集群引擎。
• 密度探测质心分类几乎将所有计算保留在服务器端，并生成由嵌入空间密度决定的自然大小的集群。
• significant_text 该方法速度快、可解释性强，在自动标注和质量门控方面同样十分有效。

这种方法适用的场景：

• 您拥有带有时间戳的文本，且希望在无标注训练数据的情况下进行主题发现。
• 您希望使用同一套技术栈完成存储、向量搜索、标注和时间关联。

还可以进一步探索的扩展方向：

• 多周期集群（如按周、按月汇总）
• 通过增量集群分配进行实时摄取。
• 以 significant_text 词项为种子生成 LLM 集群摘要。
• 在更大规模下，采样得到的 KMeans 质心可以作为基于密度的集群算法的热启动种子，从而降低探测阶段的成本。

亲自试用

您可以将其替换为自己的带时间戳文档语料库；任何包含日期信息的文本集合都适用于这一管道。完整的笔记本和支持代码可在 配套仓库中找到。

• 开始免费试用 Elastic Cloud：几分钟内即可启动一个支持 bbq_disk 的托管集群。
• 试用 Elasticsearch Serverless：无需管理集群，可自动扩展，并支持本演练涵盖的全部内容。

词汇检索（文本匹配）、语义检索（概念匹配）和混合检索（结合词汇和语义信号）本身并不能解决这些问题。词汇检索可能返回所有包含“橙子”的结果，而针对“橙子”这类高意图查询的纯语义检索，则可能扩展至相关商品（如柠檬或葡萄柚）。混合检索虽能融合词汇与语义信号，但仍无法判定该查询应被视为导航型搜索、需应用哪些约束条件，或应遵循何种业务规则。问题根源不在于检索技术本身，而在于缺乏治理层。该层级需在检索启动前，识别查询类型并确定需执行的约束规则。

在这篇博文中，我们将探讨电子商务搜索管理、其重要性以及控制层如何确保可预测的准确检索。

电子商务搜索中的治理含义

在此语境下，治理意味着在用户查询与检索引擎之间引入决策层。该层执行以下功能：

• 对查询意图进行分类：这是导航（“橙子”）还是发现（“送给爷爷的礼物”）？
• 适用业务限制：适用哪些类别界限、资格规则、供应限制或商品推广政策？
• 通向适当策略的路径：这应该使用词汇检索、语义检索，还是混合检索？

治理层决定每次查询应使用哪种检索方法，必须执行哪些限制条件，以及在检索开始前应适用哪些业务策略。重要的是不要将治理层与混合检索混为一谈：混合检索是一种结合了词汇和语义信号的检索策略，而治理层是决定应使用词汇检索、语义检索还是混合检索的上游决策层。

现状：应用层“spaghetti”的实现

当前，许多零售商试图通过直接在应用层添加逻辑来解决这一问题，但这往往导致“意大利面代码”，即由数千行硬编码的条件语句、正则表达式和复杂搜索模板堆砌而成的代码结构。

这种方法可以提供如上所示的期望搜索结果；然而，它会产生很大的操作障碍：

• 工程依赖问题：业务人员与商品运营团队若需修改搜索行为，必须通过提交工程工单并经历长达数周的部署周期，导致操作效率低下且灵活性受限。
• 碎片化：搜索逻辑分散于应用代码与搜索模板之间，难以解释或审计，导致后续迭代风险陡增。

即使团队认识到路由规则的必要性，争论也常常集中在错误的问题上：选择哪种检索方法。

错误的选择：词汇、语义与混合

搜索团队经常将挑战描述为检索策略的选择：词法/BM25、语义/向量和混合。这种框架是可以理解的（检索方法很重要），但它忽略了实际部署中最常见的失败模式，即对所有查询使用单一检索方法会导致次优结果。

商业搜索融合了几种截然不同的意图：

• 确定性、高意图导航（“橙子”、“牛奶”、“不含花生的巧克力”、“廉价橄榄油”）。
• 探索发现（“山区徒步旅行夹克”，“送给喜欢机器人的 12 岁孩子的礼物”）。
• 运营限制（供应、尺寸、价格、颜色）。
• 商品推广与活动（包括流量提升、降权、季节性活动）

当系统通过相同的检索策略来处理所有这些问题时，由于运行模式缺乏管理，结果往往会以可预见的方式出现系统性错误。当团队没有意识到这是一个治理缺口时，他们会用他们唯一掌握的手段来应对，那就是进行更多的调整。

为何“相关性调整”会周而复始

如果没有路由层，“相关性”通常会变成永无止境的待办事项：

• 为何此查询结果将配件显示在核心产品之上？
• 为什么这个主查询突然开始出现相关内容？
• 为什么在我们添加同义词、调整分析器或启用混合模式后，结果发生了变化？
• 为什么业务团队需要一个工程版本来修复一个查询？

团队的回应是更多的调整：更多的同义词，更多的提升，更多的重新排名的实验，更多的应用程序代码中的异常。这种方法可以维持一段时间，但常常导致脆弱行为，因为系统仍缺乏明确的决策层来确定查询类型并在检索前强制执行正确的约束。

剖析电子商务意图：“头部”与“尾部”

在本节中，我们采用“头部”与“尾部”作为电商领域中常见导航与探索性查询模式的实用简称。实际上，许多查询都同时包含这两方面的特征：

头部查询（确定性意图）

这些是直接的导航查询，用户清楚地知道自己想要什么：

• 单项意图（“橙子”、“牛奶”、“面包”）。
• 具体品牌或产品系列（例如“iPhone 15 Pro”、“健怡可乐”）。
• SKU、型号、尺寸（“ABC123”、“air max 270”）。

对于这些查询而言，词汇检索能够处理词元对应关系（即匹配单词），但业务层面还期望能够遵循相关限制条件、返回可预测的排序结果，并确保结果可控。商品运营人员需要确保查询在正确的类别范围内得到解析，遵循适用性规则，并凸显特定的业务优先级。

需要建立治理机制以确保查询按预期分类解析。例如，“橙子”应归类至生鲜蔬果类别，而非橙汁、橙酱或橙味汽水等细分品类。

尾部查询（探索性发现）

这些是描述性强、意图明确的查询，购物者通过此类查询进行探索性搜索：

• “送给爱吃甜食的爷爷的礼物”
• “山区徒步旅行夹克”
• “适合全天站立的鞋子”

在这方面，词汇检索往往会遇到问题。语义检索之所以出色，是因为它能将查询概念与产品联系起来，即使在措辞不匹配的情况下也是如此。但仅靠语义检索也很少能达到要求。无论使用哪种检索方法，实际查询通常都需要执行限制条件。

约束条件与检索方法正交

对语义检索进行约束并不意味着混合搜索。这些都是正交的概念。诸如 Elasticsearch 中的过滤器和增强等约束条件可以应用于任何词汇、语义或混合检索。所面临的挑战是决定如何解释查询、必须执行哪些约束条件以及使用哪种检索策略。

以下是一些结合检索与硬约束的查询示例：

• 橙子：对“橙子”进行词汇检索，并加上类别限制，如“水果”或“农产品”，排除橙子果酱、橙汁和橙汽水。
• 价格低于 4 美元且富含维生素 C 的水果：营养意图语义检索加上限制条件，结果仅限于水果类别和 4 美元以下的产品。
• 舒适的工作鞋：针对上下文意图的语义检索加上限制结果为鞋的类别约束。

这些查询无法通过单一方法来处理：

• 纯词汇检索在此场景下往往不足，因为“富含维生素 C”或“舒适”等短语可能并非以清晰的结构化属性形式存在。这类信息通常需从产品描述、用户评价或规格参数中推断得出。
• 纯语义检索往往也不足，因为如果没有明确限制，像“富含维生素C的水果”这样的查询可能会扩展到维生素补充剂、水果味饮料或高维生素蔬菜，超出预期类别和价格范围。

治理层决定查询是否需要词汇检索、语义理解、约束执行或这些方面的组合。如果没有这一层，电子商务团队可能会最终：

• 过度限制：将词汇检索用于语义请求（例如“送给爷爷的礼物”）。
• 限制不足：对高意图的头部查询使用语义查询（例如“橙子”）。

治理挑战在于构建一个能够针对每类查询做出正确判断的系统。

在没有治理的情况下会发生什么

最常见的故障模式很简单：团队直接获取原始用户查询并将其传递给单一检索策略（词汇、语义或混合），而没有中间治理层。

词汇检索未能达到预期的解析效果

当用户搜索“橙子”时，词汇检索策略可能会返回任何包含该词项的内容：橙汁、橙子果酱或橙子汽水。系统正确匹配了该术语，但如果没有治理，它可能无法解析预期的购物上下文（水果）。

语义检索的范围已超出预期限制

当用户搜索“橙子”时，语义系统可能会检索邻近产品概念中与概念相关的项目。系统可能会正确理解更宽泛的领域（水果或农产品），但如果没有明确的治理，它仍然会超出用户的预期限制（具体来说就是橘子）。

差距在于治理

所需的是一个上游决策层，该层在检索开始之前确定查询意图并强制执行正确的约束条件。这解决了以下问题：

• 类似或相关的项目会出现在用户实际想要的项目旁边。
• 模糊的类别界限（“饮料”与“农产品”）。
• 无法进行季节性促销或活动。
• 不可预测且无法解释的结果。

意图理解与路由规则：必要的控制平面

治理型搜索系统在检索前（在 Elasticsearch 中执行查询之前）引入了一个轻量级控制平面。控制机制将在本博客系列的第 3 部分和第 4 部分中详细讨论。目前，我们只讨论它能做什么，而不谈具体工作原理：

控制平面可以理解意图、应用业务策略，并确保采用适当的检索策略，具体如下：

1. 检测意图信号

• 此查询是导航型还是发现型？
• 这是已知的头部查询（牛奶、面包、香蕉）吗？
• 是否有已知的产品、品牌或类别解释（例如，“橙子”应解析为农产品）。
• 查询是否为类似 SKU 的模式？
• 查询是否属于活动或季节性政策（例如圣诞节期间，提升与火鸡相关的结果）？
• 查询是否包含约束条件（类别、属性、排除项、价格/尺寸/颜色）？

2. 应用治理与业务政策

• 首先强制执行确定性约束（类别/属性/否定/可用性）。
• 应用当前有效的商品推广策略（提升/下调/置顶/覆盖）。
• 通过优先规则解决冲突（例如活动覆盖与全局策略）。

3. 选择合适的检索策略

• 用于导航/高意图头部查询的词汇（快速、确定性）。
• 为真正的发现查询提供语义检索。
• 在明确业务约束下，结合词汇和语义信号可增加价值的混合搜索。

实际上，控制平面的输出并不只是“使用混合检索”或“使用语义检索”。这是一个受治理的检索方案：对购物者意图的解读、应适用的约束和政策，以及应执行的检索策略。以下几个简单示例可以具体说明这一点：

控制平面会为每个查询选择合适的策略和检索策略，且能够一致、可预测且可扩展。这使得高级检索方法在生产中的可预测性更高，因为首先执行的是意图一致性约束，路由决策为显式而非隐式。

与其他方法的关系

有些团队使用改进的嵌入模型来更好地捕捉产品语义，这可以大大提高语义检索的质量。其他方法则使用重新排序方法（如学习排序 (LTR)），在检索结果生成后基于用户交互或业务指标优化结果排序。这两种方法均有价值且常互为补充。更优质的嵌入向量能提升相似度匹配精度，而重排序可优化候选结果间的排序质量。

治理解决了问题的另一层：它位于检索的上游。它决定应使用哪种检索策略（例如，词汇检索、语义检索或混合检索）、需要哪些确定性约束，以及哪些查询应结合多项业务策略。

受治理控制平面可实现哪些功能

一旦治理层就位，运营模式将发生根本性变革。与收入紧密相关的查询将具备可预测性。业务团队无需等待工程团队的发布周期，即可自主更新搜索行为，而语义检索、混合检索等高级方法，则可通过路由规则和管控机制逐步部署，而非直接全局启用或禁用。

本系列的下一篇文章将探讨该操作模型在实践中的具体表现，以及为什么它可能与其背后的检索技术同等重要。

如果商户必须打开一个 Jira 工单并等待部署来修复一个关键的收入查询，瓶颈不在于引擎；而在于运营模式。现代电子商务搜索需要一种方式，能够快速安全地将业务意图转化为受控、可审计的搜索行为，同时在可测量增值的地方使用高级检索。

本系列内容预告

本系列探讨的模式在检索的上游运行：在查询生成开始之前，将业务意图转化为正确的查询策略。在下一篇文章中，我们将从技术问题转向运营问题：当业务团队无需工程部署即可更改搜索行为时会发生什么，以及为什么治理可以确保安全。

将受治理的电子商务搜索付诸实践

在企业级电商服务场景中，工程瓶颈、应用层逻辑脆弱性以及搜索结果不可预测性等问题，均可通过 Elastic Services 的专业服务得以解决。本系列所述的受治理控制平面架构，正是由 Elastic Services 工程团队精心打造。

若您的团队仍在耗费大量工程资源将商品运营需求转化为代码修改，或搜索相关性优化任务积压始终难以缩减，我们可协助评估现有技术架构，并规划一条实现搜索配置业务化、可治理的转型路径。请联系 Elastic Services。

加入讨论

对搜索治理、检索策略或电子商务搜索架构有疑问？加入更广泛的 Elastic 社区讨论。

我们最近通过添加对 Elasticsearch 作为向量数据库的支持，参与了 mastra-ai/mastra 开源项目。借助这项新功能，您可以在 Mastra 中原生使用 Elasticsearch 来存储嵌入内容。除了向量之外，Elasticsearch 还提供了一系列高级功能，以满足您所有的上下文工程需求。(例如混合搜索和重排序).

本文详细介绍了使用 Elasticsearch 实现检索增强生成 (RAG) 架构的智能体的创建过程。我们将展示一个演示项目，其中采用智能体方法来与存储在 Elasticsearch 中的科幻电影数据语料库进行交互。该项目可在 elastic/mastra-elasticsearch-example 获取。

Mastra

Mastra 是一个用于创建智能体 AI 应用的 TypeScript 框架。

Mastra的项目结构如下：

src/
├── mastra/
│   ├── agents/
│   │   └── weather-agent.ts
│   ├── tools/
│   │   └── weather-tool.ts
│   ├── workflows/
│   │   └── weather-workflow.ts
│   ├── scorers/
│   │   └── weather-scorer.ts
│   └── index.ts
├── .env.example
├── package.json
└── tsconfig.json

在 Mastra 中，您可以构建智能体、工具、工作流和评分。

智能体是一个接收消息作为输入并产生响应作为输出的类。智能体可以使用工具、大型语言模型 (LLM) 和内存（图 1）。

智能体的工具允许其与“外部世界”交互，例如与 Web API 通信或执行内部操作，如查询 Elasticsearch。内存组件对于存储对话历史（包括过去的输入和输出）至关重要。这些存储的上下文使智能体能够利用过去的交互，为未来的问题提供更知情且更相关的响应。

工作流允许您使用清晰、结构化的步骤来定义复杂的任务序列，而不是依赖单个智能体的推理（图 2）。它们让您可以完全控制任务的分解方式、数据在任务之间的移动方式以及何时执行哪些任务。工作流默认使用内置执行引擎运行，也可以部署到工作流运行器。

在 Mastra 中，您还可以定义分数，这些分数是通过模型评分、基于规则和统计方法来评估智能体输出的自动化测试结果。评分器返回分数：量化输出满足评估标准程度的数值（通常在 0 到 1 之间）。这些分数使您能够客观地跟踪性能、比较不同方法并识别 AI 系统中的改进领域。您可以使用自己的提示和评分函数自定义评分器。

Elasticsearch

要运行演示项目，我们需要一个正在运行的 Elasticsearch 实例。您可以在 Elastic Cloud 上激活免费试用版，或使用 start-local 脚本在本地安装：

curl -fsSL https://elastic.co/start-local | sh

这将在您的计算机上安装 Elasticsearch 和 Kibana，并生成一个用于配置 Mastra 集成的 API 密钥。

API 密钥将显示为上一条命令的输出，并存储在 elastic-start-local 文件夹中的 .env 文件内。

安装与配置演示

我们创建了一个 elastic/mastra-elasticsearch-example 存储库，其中包含演示项目的源代码。存储库中报告的示例演示了如何在 Mastra 中创建一个实现 RAG 架构、用于从 Elasticsearch 检索文档的智能体。

我们为演示提供了一个关于科幻电影的数据集。我们从 Kaggle 上的 IMDb 数据集中提取了 500 部电影。

第一步是使用 npm 安装项目依赖，执行以下命令：

npm install

然后我们需要配置包含各项设置的 .env 文件。我们可以使用以下命令，复制 .env.example 文件的结构来生成该文件：

cp .env.example .env

现在我们可以编辑 .env 文件，补充缺失的信息：

OPENAI_API_KEY=
ELASTICSEARCH_URL=
ELASTICSEARCH_API_KEY=
ELASTICSEARCH_INDEX_NAME=scifi-movies

Elasticsearch 索引的名称为 scifi-movies。如果您想更改它，可以使用环境变量 ELASTICSEARCH_INDEX_NAME。

我们使用 OpenAI 作为嵌入服务，这意味着您需要在 OPENAI_API_KEY 环境变量中提供 OpenAI 的 API 密钥。

示例中使用的嵌入模型是 openai/text-embedding-3-small，嵌入维度为 1536。

为了生成最终答案，我们使用了 openai/gpt-5-nano 模型来降低成本。

RAG 架构允许您使用性能较低（且通常成本较低）的 LLM 模型，因为答案落地的主要工作是由检索组件（此处为 Elasticsearch）承担。

较小的 LLM 仅负责两个主要任务：

• 重写/嵌入查询：将用户的自然语言问题转换为用于语义搜索的向量嵌入。
• 综合答案：获取高度相关的检索上下文块（文档/电影），并将它们合成为一个连贯的、最终的、人类可读的答案，并遵循给出的提示指示。

由于 RAG 流程可提供答案所需的精确事实上下文，最终的 LLM 不需要非常庞大或高度复杂，也不需要在其自身参数中拥有所有必需的知识（这正是大型、昂贵模型的优势所在）。它本质上是一个针对 Elasticsearch 提供的上下文的高级文本摘要器和格式化器，而不是一个功能齐全的知识库本身。这使得可以使用像 gpt-5-nano 等模型来优化成本和延迟。

配置完 .env 文件后，可以使用以下命令将电影数据导入 Elasticsearch：

npx tsx src/utility/store.ts

您应该看到如下输出：

🚀 Starting ingestion of 500 movies from 500_scifi_movies.jsonl...
Ingesting ░░░░░░░░░░░░░░░░░░░░░░░░ 1/500 (0%) | ok:1 | fail:0 | chunks:1 | eta:19m 33s | current:Capricorn One
Ingesting ░░░░░░░░░░░░░░░░░░░░░░░░ 2/500 (0%) | ok:2 | fail:0 | chunks:2 | eta:10m 32s | current:Doghouse
Ingesting ░░░░░░░░░░░░░░░░░░░░░░░░ 3/500 (1%) | ok:3 | fail:0 | chunks:3 | eta:7m 33s | current:Dinocroc
Ingesting ░░░░░░░░░░░░░░░░░░░░░░░░ 4/500 (1%) | ok:4 | fail:0 | chunks:7 | eta:6m 10s | current:Back to the Future           
Ingesting ░░░░░░░░░░░░░░░░░░░░░░░░ 5/500 (1%) | ok:5 | fail:0 | chunks:9 | eta:5m 14s | current:The Projected Man            
Ingesting ░░░░░░░░░░░░░░░░░░░░░░░░ 6/500 (1%) | ok:6 | fail:0 | chunks:11 | eta:4m 41s | current:I, Robot
...
✅ Ingestion complete in 1m 46s. Success: 500, Failed: 0, Chunks: 693.

scifi-movies 索引的映射包含以下字段：

• embedding：dense_vector，1536 维，cosine 相似度。
• description，包含电影描述的文本。
• director，包含导演姓名的文本。
• title，包含电影标题的文本。

我们使用 title + description 生成嵌入向量。由于 title 和 description 是两个独立的字段，将两者拼接可以确保生成的嵌入向量同时捕获电影的具体唯一标识 (title) 和丰富的描述性上下文 (description)，从而实现更准确、更全面的语义搜索结果。这种组合输入为嵌入模型提供了更好的文档内容单一表示，便于相似性匹配。

运行演示

您可以使用以下命令运行演示：

npm run dev

该命令将在 localhost:4111 启动一个 Web 应用，以访问 Mastra Studio（图3）。

Mastra Studio提供了一个交互式 UI 用于构建和测试您的智能体，以及一个将 Mastra 应用程序作为本地服务公开的 REST API。这让您可以立即开始构建，无需担心集成问题。

我们提供了一个 Elasticsearch Agent，它使用 Mastra 的 createVectorQueryTool 作为工具，利用 Elasticsearch 执行语义搜索。该智能体采用 RAG 方法搜索相关文档（即电影）来回答用户的问题。

该智能体使用以下提示：

You are a helpful assistant that answers questions based on the provided context.
Follow these steps for each response:

1. First, carefully analyze the retrieved context chunks and identify key information.
2. Break down your thinking process about how the retrieved information relates to the query.
3. Draw conclusions based only on the evidence in the retrieved context.
4. If the retrieved chunks don't contain enough information, explicitly state what's missing.

Format your response as:
THOUGHT PROCESS:
- Step 1: [Initial analysis of retrieved chunks]
- Step 2: [Reasoning based on chunks]

FINAL ANSWER:
[Your concise answer based on the retrieved context]

Important: When asked to answer a question, please base your answer only on the context provided in the tool. 
If the context doesn't contain enough information to fully answer the question, please state that explicitly and stop it.
Do not add more information than what is present in the retrieved chunks.
Remember: Explain how you're using the retrieved information to reach your conclusions.

如果您点击 Mastra Studio > Agents菜单并选择 Elasticsearch Agent，则可以使用聊天系统测试该智能体。例如，您可以提出如下关于科幻电影的问题：

查找五部关于 UFO 的电影或电视剧。

您会注意到智能体将执行 vectorQueryTool。您可以点击调用的工具来查看输入和输出。执行结束时，LLM 将根据来自 Elasticsearch 的 scifi-movies 索引的上下文回答您的问题（图 4）。

Mastra 在内部执行以下步骤：

1. 向量转换：用户的问题 “查找五部关于 UFO 的电影或电视剧” 使用 OpenAI 的 openai/text-embedding-3-small 模型转换为向量嵌入。
2. 向量搜索：然后将此嵌入向量用于通过向量搜索查询 Elasticsearch。
3. 结果检索：Elasticsearch 返回一组与查询高度相关的 10 部电影（即那些向量与用户查询向量最接近的电影）。
4. 答案生成：检索到的电影和原始用户问题被发送给 LLM，具体为 openai/gpt-5-nano。LLM 处理这些信息并生成最终答案，确保满足用户请求的五个结果。

Elasticsearch 智能体

下面我们展示了 Elasticsearch 智能体的源代码。

import { Agent } from "@mastra/core/agent";
import { ElasticSearchVector } from '@mastra/elasticsearch';
import { createVectorQueryTool } from '@mastra/rag';
import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
import { Memory } from "@mastra/memory";

const es_url = process.env.ELASTICSEARCH_URL;
const es_apikey = process.env.ELASTICSEARCH_API_KEY;
const es_index_name = process.env.ELASTICSEARCH_INDEX_NAME;
const prompt = 'insert here the previous prompt';

const esVector = new ElasticSearchVector({
  id: 'elasticsearch-vector',
  url: es_url,
  auth: {
    apiKey : es_apikey
  }
});

const vectorQueryTool = createVectorQueryTool({
  vectorStore: esVector,
  indexName: es_index_name,
  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small")
});

export const elasticsearchAgent = new Agent({
  id: "elasticsearch-agent",
  name: "Elasticsearch Agent",
  instructions: prompt,
  model: 'openai/gpt-5-nano',
  tools: { vectorQueryTool },
  memory: new Memory(),
});

vectorQueryTool 是被调用来实现 RAG 示例中检索部分的工具。它使用了 Elastic 为 Mastra 贡献的 ElasticSearchVector 实现。

该智能体是 agent 类的一个对象，它使用了 vectorQueryTool、提示和内存组件。可以看出，将 Elasticsearch 连接到智能体所需的代码量非常少。

结论

本文展示了将 Elasticsearch 与 Mastra 框架集成以构建复杂的智能体 AI 应用程序的简便性和强大功能。具体来说，我们逐步实现了一个 RAG 智能体，能够对 Elasticsearch 中索引的科幻电影数据语料库执行语义搜索。

一个关键收获是 Elastic 对 Mastra 开源项目的直接贡献，提供了 Elasticsearch 作为向量存储的原生支持。这种集成显著降低了入门门槛，正如 Elasticsearch Agent 源代码所证明的那样。使用 ElasticSearchVector 和 createVectorQueryTool，将 Elasticsearch 连接到智能体的完整设置仅需最少数量的配置代码行。

Elasticsearch 提供了多项高级功能来增强结果相关性。例如，混合搜索通过将词法搜索与向量搜索相结合，显著提高了准确性。另一个有趣的功能是在混合搜索结束时使用最新的Jina 模型重排序。要了解有关这些技术的更多信息，请参阅 Elasticsearch Labs 的以下文章：

• Elasticsearch 混合搜索 - Valentin Crettaz
• Jina 模型介绍、功能及其在 Elasticsearch 中的应用 作者：Scott Martens

我们还鼓励您探索所提供的示例，并开始使用 Mastra 和 Elasticsearch 构建自己的数据驱动的智能体应用。如需了解更多关于 Mastra 的信息，您可在此处查看官方文档。

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

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

准备工作

• 运行 9.3 的 Elastic Cloud 或自管型集群
• 已启用工作流（高级设置）

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

GET kbn:/api/saved_objects/_find?type=usage-counter&filter=usage-counter.attributes.domainId:"dashboard"%20and%20usage-counter.attributes.counterType:"viewed"&per_page=10000

响应类似如下：

{
  "page": 1,
  "per_page": 10000,
  "total": 1,
  "saved_objects": [
    {
      "type": "usage-counter",
      "id": "dashboard:346f3c64-ebca-484d-9d57-ec600067d596:viewed:server:20260310",
      "attributes": {
        "domainId": "dashboard",
        "counterName": "346f3c64-ebca-484d-9d57-ec600067d596",
        "counterType": "viewed",
        "source": "server",
        "count": 1
      },
      ...
    }
  ]

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

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

步骤 2：创建目标索引

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

PUT dashboard-views
{
  "mappings": {
    "properties": {
      "captured_at": {
        "type": "date"
      },
      "dashboard_id": {
        "type": "keyword"
      },
      "dashboard_name": {
        "type": "keyword"
      },
      "view_count": {
        "type": "integer"
      }
    }
  }
}

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

步骤 3：创建工作流

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

name: dashboard-views-ingestion
triggers:
  - type: scheduled
    with:
      every: 30m

steps:
  - name: fetch_dashboard_views
    type: kibana.request
    with:
      method: GET
      path: >-
        /api/saved_objects/_find?type=usage-counter&per_page=10000&filter=usage-counter.attributes.domainId:"dashboard"%20and%20usage-counter.attributes.counterType:"viewed"

  - name: index_each_dashboard
    type: foreach
    foreach: "{{ steps.fetch_dashboard_views.output.saved_objects }}"
    steps:
      - name: fetch_dashboard_name
        type: kibana.request
        with:
          method: GET
          path: /api/saved_objects/dashboard/{{ foreach.item.attributes.counterName }}
        on-failure:
          continue: true

      - name: index_doc
        type: elasticsearch.request
        with:
          method: POST
          path: /dashboard-views/_doc
          body:
            dashboard_id: "{{ foreach.item.attributes.counterName }}"
            dashboard_name: "{{ steps.fetch_dashboard_name.output.attributes.title }}"
            view_count: "${{ foreach.item.attributes.count | plus: 0 }}"
            captured_at: "{{ execution.startedAt | date: '%Y-%m-%dT%H:%M:%SZ' }}"

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

工作流如何运作

触发

工作流每 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

Elasticsearch 拒绝了延迟到达的指标。这些拒绝导致管道滞后，导致更多的延迟数据，从而引发了更多的拒绝。最终，该管道彻底停滞了。

我们不得不从快照中恢复数据，重新索引数据，并重新设计摄取管道以恢复数据。

根本原因并非索引生命周期管理 (ILM) 本身。而是时序数据流 (TSDS) 以及它们如何执行有时间限制的后备索引。

TSDS 可以将指标的存储需求减少 40——70%，但使 TSDS 高效的架构更改也改变了索引随时间推移的行为方式。这些变化在设计 ILM 策略或数据摄取管道可能会产生延迟到达的数据时非常重要。

简要说明

使用 TSDS 时：

• 后备索引仅接受特定时间窗口内的文档。
• 如果在索引移动到冷冻或冻结状态后有延迟的数据到达，Elasticsearch 将拒绝接受这些文档，或将其路由到故障存储（如果已配置）。

设计规则：

warm_min_age > rollover_max_age + maximum_expected_lateness

什么是时序数据流？

时序数据流 (TSDS) 是针对指标数据进行了优化的专用数据流。对数据进行路由，使相关文档位于同一分片内，从而优化它们以进行查询和检索。下面介绍 Elasticsearch 如何实现这一操作：

每个文档包含：

• 时间戳。
• 用于识别时间序列的维度字段。
• 表示测量值的度量字段。

示例包括：

• 每台主机的 CPU 使用率。
• 每项服务的请求延迟。
• 每个传感器的温度读数。

维度 确定了我们要测量的内容，而度量 则代表了随时间变化的值。

尺寸

维度描述被测量的实体。

示例:

host.name
service.name
container.id

我们在映射中按以下方式定义它们：

time_series_dimension: true

指标

指标代表数值，并使用以下方式定义：

time_series_metric

常用指标类型：

• 计量：数值会上升和下降。
• 计数器：数值不断增加，直至重置。

Elastic Agent 主要收集指标和日志数据，因此，即使您没有手动启用任何 TSDS 索引，集群中仍可能包含这些索引。

_tsid 字段

Elasticsearch 内部会根据维度字段生成 _tsid 值。这样，具有相同尺寸的文档就可以路由到相同的分区，从而改进：

• 压缩。
• 查询位置。
• 聚合性能。

关键区别：有时间限制的后备索引

传统数据流始终写入最新的支持索引，称为 写索引，但 TSDS 的行为有所不同。

每个 TSDS 后备索引都有一个定义的时间窗口，并且仅接受 @timestamp 值在该窗口内的文档：

GET _data_stream/my-metrics-data-stream


     "index_mode": "time_series",
     "time_series": {
       "temporal_ranges": [
         {
           "start": "2026-01-15T14:35:50.000Z",
           "end": "2026-03-16T11:34:40.000Z"
         }
       ]
     }

为文档编制索引时，Elasticsearch 会将其路由到负责该时间戳的后备索引，这意味着与传统索引不同，TSDS 可以同时写入多个后备索引。

例如：

• 实时数据 → 最新索引。
• 较晚的数据 → 覆盖该时间范围的较早索引。

为延迟到达的数据进行设计

真正的摄取管道很少能完美地按时提供指标。指标可能会由于网络中断、传输过程中的积压、批量摄取以及边缘设备的丢失而延迟，这些设备重新连接后会开始追赶进度。

传统索引会悄然吸收这些延迟。TSDS 不会。

如果文档的时间戳超出了可写后备索引的范围，Elasticsearch 将拒绝该文档，这意味着您的 ILM 策略必须考虑延迟数据。

关键制约因素

后备索引必须保持足够长的可写时间，以接受延迟数据。

实际上：

time_until_readonly > maximum_expected_lateness

由于 ILM 衡量的是从滚动更新开始算起的年限，因此操作规则变为：

warm_or_cold_min_age > rollover_max_age + maximum_expected_lateness

例如，如果指标最多可能延迟六小时到达，则索引在滚动更新后必须保持至少六小时的可写状态。

正是由于没有考虑到这一限制，才导致了前面所述的摄取失败。延迟到达的数据被定向到一个早期索引，该索引已经处于冷层并因此被写入阻塞。

处理被拒绝的文档

当 TSDS 拒绝文档时，Elasticsearch 返回一个错误，表明时间戳不在可写索引的范围内。您的摄取管道如何处理该错误，决定了是丢失数据还是停止摄取。

处理被拒绝文档的主要机制是故障存储。

故障存储（在 Elasticsearch 9.1+ 中推荐）

Elasticsearch 9.1 引入了失败存储，它能自动捕获被拒绝的文档。Elasticsearch 不会将错误返回给客户端，而是将失败的文档写入数据流中的专用失败索引。

您可以使用以下方法检查故障：

GET metrics-myapp::failures/_search

使用故障存储可防止摄取管道因拒绝错误而阻塞，同时保留失败的数据以供分析或重新索引。

监测拒绝问题

延迟到达问题通常首先表现为摄取异常。您可能会先注意到它们：

• 索引速率突然下降。
• 拒绝的文档激增。
• 越来越多的故障存储条目。
• 管道输入和输出计数不匹配。

通过对这些信号发出警报，操作人员可以在管道停滞之前检测问题。工作流、机器学习作业和其他机制可用于自动检测和通知。

TSDS + ILM 迁移检查清单

如果要将指标集群迁移到 TSDS、引入 ILM 分层，或升级到指标默认为 TSDS 的 Elasticsearch 版本，请先查看这些项目。

1. 测量摄取延迟

在更改 ILM 策略之前，请确定：

• 正常摄取延迟。
• 事件期间的最坏延迟情况。
• 批量管道造成的延迟。

您的 ILM 设计必须适应最大实际延迟。

2. 验证索引时间窗口

检查您的 TSDS 支持索引：

GET _data_stream/

寻找：

• time_series.start_time
• time_series.end_time

这些界限决定了哪些索引可以接受文档。了解这些时间窗口有助于您确定数据最多可以延迟多久才不会被拒绝。

3. 为延迟到达的数据调整热层的大小

确保后备索引保持可写状态的时间足够长，以便写入延迟到达的数据。

操作规则：

• warm_min_age > rollover_max_age + maximum_expected_lateness

请记住，如果指标可能晚到六个小时，那么索引必须至少在六个小时内保持可写状态。

4. 决定如何处理被拒绝的文档

在启用 TSDS 之前选择策略：

• 故障存储（在 Elasticsearch 9.1+ 中推荐）。
• Logstash 死信队列。
• 为延迟到达的数据提供后备索引。
• 接受有限的数据丢失。

5. 监测摄取健康状况

为以下内容添加警报：

• 索引速率下降。
• 已拒绝的文档。
• 故障存储增长。
• 管道输入/输出不匹配。

数据延迟问题通常首先表现为摄取异常。

总结

时序数据流为指标工作负载提供重大的存储和性能改进，但它们引入了重要的架构变更：后备索引是时间绑定的，这影响了 ILM 的行为。

使用 TSDS 时：

• 索引必须保持足够长的可写时间，以接受延迟数据。
• 摄取管道应安全处理被拒绝的文档。

要记住的关键规则是：

warm_min_age > rollover_max_age + maximum_expected_lateness

如果围绕这一约束条件设计 ILM 策略，TSDS 就能很好地处理指标工作负载。

但若忽视这一限制，您的摄取管道可能会很难发现这些时间界限。

您的第一个查询

首先定义一个映射到 Elasticsearch 索引的普通旧 CLR 对象 (POCO)。属性名称通过标准System.Text.Json 属性（如[JsonPropertyName]）或配置的JsonNamingPolicy 解析为 ES|QL 列名。适用于客户端其他部分的源序列化规则在这里也同样适用。

using System.Text.Json.Serialization;

public class Product
{
    [JsonPropertyName("product_id")]
    public string Id { get; set; }

    public string Name { get; set; }

    public string Brand { get; set; }

    [JsonPropertyName("price_usd")]
    public double Price { get; set; }

    [JsonPropertyName("in_stock")]
    public bool InStock { get; set; }
}

类型设置完成后，查询语句如下所示：

var minPrice = 100.0;
var brand = "TechCorp";

await foreach (var product in client.Esql.QueryAsync(q => q
    .From("products")
    .Where(p => p.InStock && p.Price >= minPrice && p.Brand == brand)
    .OrderByDescending(p => p.Price)
    .Take(10)))
{
    Console.WriteLine($"{product.Name}: ${product.Price}");
}

该提供程序将此转换为以下 ES|QL：

FROM products
| WHERE (in_stock == true AND price_usd >= ?minPrice AND brand == ?brand)
| SORT price_usd DESC
| LIMIT 10

需要注意的一些细节：

• 属性名称解析：由于 [JsonPropertyName] 属性，p.Price 变成了 price_usd，根据默认 camelCase 命名策略，p.Brand 变成 brand。
• 参数捕获：C# 变量 minPrice 和 brand 被捕获为命名参数 (?minPrice，?brand)。它们与 JSON 有效负载中的查询字符串分开发送，这样可以防止注入，并实现服务器端查询计划缓存。
• 流式传输：QueryAsync<T> 返回 IAsyncEnumerable<T>。从 Elasticsearch 返回数据时，数据会逐行具体化。

您还可以在不执行的情况下检查生成的查询及其参数：

var query = client.Esql.CreateQuery()
    .Where(p => p.InStock && p.Price >= minPrice && p.Brand == brand)
    .OrderByDescending(p => p.Price)
    .Take(10);

Console.WriteLine(query.ToEsqlString());
// FROM products | WHERE (in_stock == true AND price_usd >= 100) | SORT price_usd DESC | LIMIT 10

Console.WriteLine(query.ToEsqlString(inlineParameters: false));
// FROM products | WHERE (in_stock == true AND price_usd >= ?minPrice AND brand == ?brand) | SORT price_usd DESC | LIMIT 10

var parameters = query.GetParameters();
// { "minPrice": 100.0, "brand": "TechCorp" }

这如何运作？快速回顾一下 LINQ

使 LINQ 提供程序成为可能的机制是 IEnumerable<T> 和 IQueryable<T> 之间的区别。

在 IEnumerable<T> 上调用 .Where(p => p.Price > 100) 时，lambda 会编译为 Func<Product, bool>，即一个由运行时在进程内执行的常规委托。这就是 LINQ-to-Objects。

当您在IQueryable<T> 上调用相同的方法时，C# 编译器会将 lambda 封装在Expression<Func<Product, bool>> 中。这是一种数据结构，表示代码的结构，而不是代码的可执行形式。在运行时，该表达式树可被检查、分析，并转换为另一种语言。

// IEnumerable: the lambda is a compiled delegate
IEnumerable local = products.Where(p => p.Price > 100);

// IQueryable: the lambda is an expression tree, a data structure
IQueryable remote = queryable.Where(p => p.Price > 100);

IQueryProvider 接口是扩展点。任何提供程序均可通过实现 CreateQuery<T> 和 Execute<T>，将这些表达式树转换为目标语言。实体框架就是利用此机制生成 SQL 语句。LINQ to ES|QL 提供程序使用它来生成 ES|QL 查询。

上述查询的表达式树如下所示：

示例查询的表达式树。

此表达式树由内而外嵌套：Take 包裹着 OrderByDescending，它又包裹着 Where，而后者再包裹着 From，而最内层是根节点 EsqlQueryable<Product> 常量。对于 &&、>= 和 == 这几种操作符而言，Where 谓词本身是一个由 BinaryExpression 个节点构成的子树，其中包含 MemberExpression 个叶子节点，这些叶子节点用于属性访问，以及对 minPrice 和 brand 变量的闭包捕获。提供程序会遍历这一数据结构，从而生成最终的 ES|QL 查询。

深入了解：转换管道

从 LINQ 表达式到查询结果的路径遵循六阶段管道：

转换管道概述。

1. 表达式树捕获

当在一个 IQueryable<T> 对象上串联使用 .Where()、.OrderBy()、.Take() 及其他操作符时，标准的 LINQ 基础架构会构建一个表达式树。EsqlQueryable<T> 实现了 IQueryable<T> 接口，并将处理委托给 EsqlQueryProvider。

2. 翻译

当查询被执行 (通过枚举、调用 ToList()，或使用 await foreach) 时)，EsqlExpressionVisitor自内而外遍历表达式树。它会将每个 LINQ 方法调用分派给一个专门的访问器进行处理：

在翻译过程中，表达式中引用的 C# 变量被捕获为命名参数。

3. 查询模型

访问器不会直接生成字符串。相反，它们会产生 QueryCommand 对象，一个不可变的中间表征。一个 FromCommand、一个 WhereCommand、一个 SortCommand 和一个 LimitCommand，各代表一条 ES|QL 处理命令。这些数据被收集到EsqlQuery 模型中。

查询模型和命令模式。

该中间模型与表达式树和输出格式均解耦。它可以被检查、拦截（通过 IEsqlQueryInterceptor）或在格式化前进行修改。

4. 格式化

EsqlFormatter 依次访问每个QueryCommand ，并生成最终的 ES|QL 字符串。每条命令占一行，通过 ES|QL 中用于串联处理命令的管道 (|) 运算符分隔。若标识符包含特殊字符，系统会自动用反引号进行转义处理。

5. 执行

格式化后的 ES|QL 查询字符串及捕获的参数会以 JSON 数据载荷的形式发送至 Elasticsearch 的 /_query 终端。而 IEsqlQueryExecutor 接口则对传输层进行了抽象封装，这正是分层包架构发挥作用的关键环节。

6. 实现

EsqlResponseReader 流式传输JSON响应，但不会将整个结果集缓冲到内存中。以流式方式传输 JSON 响应数据，无需将整个结果集缓存至内存。针对每次查询预先计算生成的 ColumnLayout 树结构，会将扁平化的 ES|QL 列名（如 address.street、address.city）映射到嵌套的 POCO 属性。每行数据会被组装为 T 实例，并通过 IEnumerable<T> 或 IAsyncEnumerable<T> 逐个返回。

分层架构

LINQ to ES|QL 功能分为三个软件包：

软件包架构。Elastic.Esql 是纯转换引擎。该组件完全不依赖 HTTP 协议栈，集成了表达式访问器、查询模型、格式化器及响应解析器等核心模块。您可独立使用它来构建和检查 ES|QL 查询（无需连接 Elasticsearch），这在测试验证、查询日志记录或自定义执行层开发等场景中极具实用价值。翻译要点解析：

// Translation-only: no Elasticsearch connection needed
var provider = new EsqlQueryProvider();
var query = new EsqlQueryable(provider)
    .From("products")
    .Where(p => p.InStock)
    .OrderByDescending(p => p.Price);

Console.WriteLine(query.ToEsqlString());
// FROM products | WHERE in_stock == true | SORT price_usd DESC

Elastic.Clients.Esql 是一款轻量级的独立 ES|QL 客户端。该组件通过 Elastic.Transport 在 Elastic.Esql 之上扩展了 HTTP 协议执行能力。如果您的应用程序仅需使用 ES|QL 而无需其他 Elasticsearch API，此方案可实现最小化依赖集成。

Elastic.Clients.Elasticsearch 是完整的 Elasticsearch.NET 客户端。它还建立在Elastic.Esql 的基础上，并通过client.Esql 命名空间公开 LINQ 提供程序接口。这是大多数应用程序的推荐入口点。

两个执行层组件包均提供了针对 IEsqlQueryExecutor 接口的独立实现。该策略接口作为转换与传输层的桥梁。

当与源码生成的 JsonSerializerContext 配合使用时，这三个组件包均支持原生 AOT 编译。如需完整客户端集成方案，请参阅原生 AOT 文档。

不只使用基础功能

上面的例子涵盖了筛选、排序和分页。该提供程序支持更广泛的操作范围。

聚合

GroupBy结合 Select 中的聚合函数，转换为 ES|QL STATS ... BY：

var stats = client.Esql.Query(q => q
    .GroupBy(p => p.Brand)
    .Select(g => new
    {
        Brand = g.Key,
        Count = g.Count(),
        AvgPrice = g.Average(p => p.Price),
        MaxPrice = g.Max(p => p.Price)
    }));

// -> FROM products | STATS COUNT(*), AVG(price_usd), MAX(price_usd) BY brand

投影

Select，使用匿名类型生成 EVAL、KEEP 和 RENAME 命令：

var query = client.Esql.CreateQuery()
    .Select(p => new { ProductName = p.Name, p.Price, p.InStock });

// -> FROM products | KEEP name, price_usd, in_stock | RENAME name AS ProductName

丰富的函数库

通过 EsqlFunctions 类，可以使用超过 80 个 ES|QL 函数，涵盖日期/时间、字符串、数学、IP、模式匹配和评分。标准 Math.* 和 string.* 方法也已转换：

.Where(p => p.Name.Contains("Pro"))       // -> WHERE name LIKE "*Pro*"
.Where(p => EsqlFunctions.CidrMatch(      // -> WHERE CIDR_MATCH(ip, "10.0.0.0/8")
    p.IpAddress, "10.0.0.0/8"))

查找连接

跨索引查找转换为 ES|QL LOOKUP JOIN：

var enriched = client.Esql.Query(q => q
    .LookupJoin(
        "category-lookup-index",
        product => product.Id,
        category => category.CategoryId,
        (product, category) => new { product.Name, category!.CategoryLabel }));

原生 ES|QL 直通接口

对于 LINQ 提供程序尚未涵盖的 ES|QL 功能，您可以添加原始片段：

var results = client.Esql.Query(q => q
    .Where(p => p.InStock)
    .RawEsql("| EVAL discounted = price_usd * 0.9"));

服务器端异步查询

对于长时间运行的查询，可将其提交给服务器进行后台处理：

await using var asyncQuery = await client.Esql.SubmitAsyncQueryAsync(
    q => q.Where(p => p.InStock),
    asyncQueryOptions: new EsqlAsyncQueryOptions
    {
        WaitForCompletionTimeout = TimeSpan.FromSeconds(5),
        KeepAlive = TimeSpan.FromMinutes(10)
    });

await asyncQuery.WaitForCompletionAsync();
await foreach (var product in asyncQuery.AsAsyncEnumerable())
    Console.WriteLine(product.Name);

服务器端异步查询对于长时间运行的分析型查询/大规模数据集处理尤其有用，这类操作可能会超出常规的超时阈值；在存在负载均衡器、API 网关或代理（这些组件会强制执行严格的 HTTP 超时设置）的超时敏感环境中，异步查询同样优势显著。异步查询通过将查询提交与结果获取解耦，避免了连接中断的情况。

开始使用

LINQ to ES|QL 自以下版本起可用：

• Elastic.Clients.Elasticsearch v9.3.4（9.x 分支）
• Elastic.Clients.Elasticsearch v8.19.18（8.x 分支）

从 NuGet 安装：

dotnet add package Elastic.Clients.Elasticsearch

入口点位于client.Esql上：

有关完整的功能参考，包括查询选项、多字段访问、嵌套对象和多值字段处理，请参阅LINQ to ES|QL 文档。

结论

LINQ 转 ES|QL 将 C# LINQ 的强大表达能力引入到 Elasticsearch 的 ES|QL 查询语言中，让您无需手工编写查询字符串，就能生成强类型、可组合的查询。它具备自动参数捕获、流式物化功能，还拥有分层式的软件包架构，既能满足独立转换需求，也能适配完整的 Elasticsearch 客户端，可自然融入任意规模的 .NET 应用程序。安装最新客户端，将 LINQ 表达式指向索引，剩下的就交给该提供程序来处理。

本文将探讨构建自定义 Elasticsearch MCP 服务器的优势，并展示如何使用 TypeScript 创建该服务器，以将 Elasticsearch 连接到 LLM 驱动的应用程序。

为什么要构建自定义 Elasticsearch MCP 服务器？

Elastic 为 MCP 服务器提供了一些替代方案：

• Elastic Agent Builder MCP 服务器，适用于 Elasticsearch 9.2 及以上版本
• 适用于旧版本的 Elasticsearch MCP 服务器（Python）

如果您需要更好地控制 MCP 服务器与 Elasticsearch 的交互，构建自己的自定义服务器可以让您灵活地根据自身需求进行定制。例如，Agent Builder 的 MCP 终端仅限于 Elasticsearch 查询语言 (ES|QL) 查询，而自定义服务器允许您使用完整的查询 DSL。在将结果传递给 LLM 之前，您还可以控制结果的格式，并可以集成其他处理步骤，例如我们将在本教程中实现的由 OpenAI 驱动的摘要功能。

通过阅读本文，您将学会使用 TypeScript 创建 MCP 服务器，该服务器可搜索存储在 Elasticsearch 索引中的信息，对其进行总结并提供引用。我们将使用 Elasticsearch 进行检索，使用 OpenAI 的 gpt-4o-mini 模型提炼摘要并生成引用，并使用 Claude Desktop 作为 MCP 客户端和 UI 来接收用户查询并提供回复。最终我们将得到一个内部知识助手，帮助工程师在整个组织的技术文档中发现并综合最佳实践。

准备工作：

• Node.js 20 +
• Elasticsearch
• OpenAI API 密钥
• Claude Desktop

什么是 MCP？

MCP 是由 Anthropic 创建的开放标准，提供大型语言模型与外部系统（如 Elasticsearch）之间的安全双向连接。您可以在这篇文章中了解更多关于 MCP 现状的信息。

MCP 的发展每天都在变化，服务器的使用范围越来越广。此外，构建自定义 MCP 服务器也非常简单，我们将在本文中进行演示。

MCP 客户端

可用的 MCP 客户端由很多，每个客户端都有自己的特点和局限性。为了简化和普及，我们将使用 Claude Desktop 作为演示中的 MCP 客户端。它将作为聊天界面，用户可以用自然语言提问，它还将自动调用我们的 MCP 服务器提供的工具来搜索文档和生成摘要。

创建 Elasticsearch MCP 服务器

通过使用 TypeScript 软件开发工具包，我们可以轻松创建一个能够根据用户查询输入来查询 Elasticsearch 数据的服务器。

本文将介绍将 Elasticsearch MCP 服务器与 Claude Desktop 客户端集成的步骤：

1. 为 Elasticsearch 配置 MCP 服务器。
2. 将 MCP 服务器加载到 Claude Desktop。
3. 测试一下。

为 Elasticsearch 配置 MCP 服务器。

首先，我们来初始化一个 Node 应用程序：

npm init -y

这将会创建一个 package.json 文件，有了它，我们就可以开始安装该应用程序所需的依赖项。

npm install @elastic/elasticsearch @modelcontextprotocol/sdk openai zod && npm install --save-dev ts-node @types/node typescript

• @elastic/elasticsearch 将使我们能够访问 Elasticsearch Node.js 库。
• @modelcontextprotocol/sdk 提供核心工具来创建和管理 MCP 服务器、注册工具以及处理与 MCP 客户端的通信。
• openai 允许与 OpenAI 模型进行交互以生成摘要或自然语言响应。
• zod 帮助定义和验证每个工具中输入和输出数据的结构化模式。

ts-node，@types/node 和 typescript 将在开发过程中用于键入代码和编译脚本。

配置数据集

为了提供 Claude Desktop 可以使用我们的 MCP 服务器进行查询的数据，我们将使用模拟的内部知识库数据集。来自该数据集的文档是这样子的：

{
    "id": 5,
    "title": "Logging Standards for Microservices",
    "content": "Consistent logging across microservices helps with debugging and tracing. Use structured JSON logs and include request IDs and timestamps. Avoid logging sensitive information. Centralize logs in Elasticsearch or a similar system. Configure log rotation to prevent storage issues and ensure logs are searchable for at least 30 days.",
    "tags": ["logging", "microservices", "standards"]
}

为了摄取数据，我们准备了一个脚本，该脚本在 Elasticsearch 中创建一个索引并将数据集加载到其中。您可以在这里找到它。

MCP 服务器

创建一个名为 index.ts 的文件，并添加以下代码来导入依赖项并处理环境变量：

// index.ts
import { z } from "zod";
import { Client } from "@elastic/elasticsearch";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import OpenAI from "openai";

const ELASTICSEARCH_ENDPOINT =
  process.env.ELASTICSEARCH_ENDPOINT ?? "http://localhost:9200";
const ELASTICSEARCH_API_KEY = process.env.ELASTICSEARCH_API_KEY ?? "";
const OPENAI_API_KEY = process.env.OPENAI_API_KEY ?? "";
const INDEX = "documents";

此外，让我们初始化客户端以处理 Elasticsearch 和 OpenAI 的调用：

const openai = new OpenAI({
  apiKey: OPENAI_API_KEY,
});

const _client = new Client({
  node: ELASTICSEARCH_ENDPOINT,
  auth: {
    apiKey: ELASTICSEARCH_API_KEY,
  },
});

为了使我们的实现更加稳健，并确保输入和输出结构化，我们将使用 zod 定义模式。这使我们能够在运行时验证数据，及早发现错误，并使工具响应更容易以编程方式进行处理：

const DocumentSchema = z.object({
  id: z.number(),
  title: z.string(),
  content: z.string(),
  tags: z.array(z.string()),
});

const SearchResultSchema = z.object({
  id: z.number(),
  title: z.string(),
  content: z.string(),
  tags: z.array(z.string()),
  score: z.number(),
});

type Document = z.infer;
type SearchResult = z.infer;

请在此处了解更多关于结构化输出的信息。

现在让我们初始化 MCP 服务器：

const server = new McpServer({
  name: "Elasticsearch RAG MCP",
  description:
    "A RAG server using Elasticsearch. Provides tools for document search, result summarization, and source citation.",
  version: "1.0.0",
});

定义 MCP 工具

完成所有配置后，我们就可以开始编写将由 MCP 服务器公开的工具了。此服务器公开两种工具：

• search_docs：使用全文本搜索在 Elasticsearch 中搜索文档。
• summarize_and_cite：汇总和综合先前检索到的文档中的信息，以回答用户的问题。该工具还可添加引用源文档的引文。

这两个工具共同构成了一个简单的“检索后总结”工作流，其中一个工具获取相关文档，另一个工具使用这些文档生成汇总的引用回复。

工具响应格式

每个工具都可以接受任意输入参数，但必须以以下结构作出响应：

• 内容：这是工具以非结构化格式做出的响应。该字段通常用于返回文本、图像、音频、链接或嵌入内容。在本应用程序中，它将用于返回包含工具生成的信息的格式化文本。
• 结构化内容： 这是一个可选返回，用于以结构化格式提供每个工具的结果。这对程序化用途非常有用。虽然本 MCP 服务器没有使用它，但如果您想开发其他工具或以编程方式处理结果，它可能会很有用。

基于这个结构，让我们详细探讨每个工具。

Search_docs 工具

此工具在 Elasticsearch 索引中执行 全文本搜索，以根据用户查询检索最相关的文档。它突出显示关键匹配项，并快速提供相关性评分概述。

server.registerTool(
  "search_docs",
  {
    title: "Search Documents",
    description:
      "Search for documents in Elasticsearch using full-text search. Returns the most relevant documents with their content, title, tags, and relevance score.",
    inputSchema: {
      query: z
        .string()
        .describe("The search query terms to find relevant documents"),
      max_results: z
        .number()
        .optional()
        .default(5)
        .describe("Maximum number of results to return"),
    },
    outputSchema: {
      results: z.array(SearchResultSchema),
      total: z.number(),
    },
  },
  async ({ query, max_results }) => {
    if (!query) {
      return {
        content: [
          {
            type: "text",
            text: "Query parameter is required",
          },
        ],
        isError: true,
      };
    }

    try {
      const response = await _client.search({
        index: INDEX,
        size: max_results,
        query: {
          bool: {
            must: [
              {
                multi_match: {
                  query: query,
                  fields: ["title^2", "content", "tags"],
                  fuzziness: "AUTO",
                },
              },
            ],
            should: [
              {
                match_phrase: {
                  title: {
                    query: query,
                    boost: 2,
                  },
                },
              },
            ],
          },
        },
        highlight: {
          fields: {
            title: {},
            content: {},
          },
        },
      });

      const results: SearchResult[] = response.hits.hits.map((hit: any) => {
        const source = hit._source as Document;

        return {
          id: source.id,
          title: source.title,
          content: source.content,
          tags: source.tags,
          score: hit._score ?? 0,
        };
      });

      const contentText = results
        .map(
          (r, i) =>
            `[${i + 1}] ${r.title} (score: ${r.score.toFixed(
              2,
            )})\n${r.content.substring(0, 200)}...`,
        )
        .join("\n\n");

      const totalHits =
        typeof response.hits.total === "number"
          ? response.hits.total
          : (response.hits.total?.value ?? 0);

      return {
        content: [
          {
            type: "text",
            text: `Found ${results.length} relevant documents:\n\n${contentText}`,
          },
        ],
        structuredContent: {
          results: results,
          total: totalHits,
        },
      };
    } catch (error: any) {
      console.log("Error during search:", error);

      return {
        content: [
          {
            type: "text",
            text: `Error searching documents: ${error.message}`,
          },
        ],
        isError: true,
      };
    }
  }
);

我们将 fuzziness : “AUTO” 配置为根据被分析的词元的长度具有可变的拼写错误容忍度。我们还设置了 title^2 来提高标题字段匹配的文档的分数。

摘要和引用工具

该工具根据上一次搜索中检索到的文档生成摘要。它使用 OpenAI 的 gpt-4o-mini 模型来综合最相关的信息，提供直接来自搜索结果的响应，以回答用户的问题。除了摘要之外，它还返回所使用源文档的引用元数据。

server.registerTool(
  "summarize_and_cite",
  {
    title: "Summarize and Cite",
    description:
      "Summarize the provided search results to answer a question and return citation metadata for the sources used.",
    inputSchema: {
      results: z
        .array(SearchResultSchema)
        .describe("Array of search results from search_docs"),
      question: z.string().describe("The question to answer"),
      max_length: z
        .number()
        .optional()
        .default(500)
        .describe("Maximum length of the summary in characters"),
      max_docs: z
        .number()
        .optional()
        .default(5)
        .describe("Maximum number of documents to include in the context"),
    },
    outputSchema: {
      summary: z.string(),
      sources_used: z.number(),
      citations: z.array(
        z.object({
          id: z.number(),
          title: z.string(),
          tags: z.array(z.string()),
          relevance_score: z.number(),
        })
      ),
    },
  },
  async ({ results, question, max_length, max_docs }) => {
    if (!results || results.length === 0 || !question) {
      return {
        content: [
          {
            type: "text",
            text: "Both results and question parameters are required, and results must not be empty",
          },
        ],
        isError: true,
      };
    }

    try {
      const used = results.slice(0, max_docs);

      const context = used
        .map(
          (r: SearchResult, i: number) =>
            `[Document ${i + 1}: ${r.title}]\\n${r.content}`
        )
        .join("\n\n---\n\n");

      // Generate summary with OpenAI
      const completion = await openai.chat.completions.create({
        model: "gpt-4o-mini",
        messages: [
          {
            role: "system",
            content:
              "You are a helpful assistant that answers questions based on provided documents. Synthesize information from the documents to answer the user's question accurately and concisely. If the documents don't contain relevant information, say so.",
          },
          {
            role: "user",
            content: `Question: ${question}\\n\\nRelevant Documents:\\n${context}`,
          },
        ],
        max_tokens: Math.min(Math.ceil(max_length / 4), 1000),
        temperature: 0.3,
      });

      const summaryText =
        completion.choices[0]?.message?.content ?? "No summary generated.";

      const citations = used.map((r: SearchResult) => ({
        id: r.id,
        title: r.title,
        tags: r.tags,
        relevance_score: r.score,
      }));

      const citationText = citations
        .map(
          (c: any, i: number) =>
            `[${i + 1}] ID: ${c.id}, Title: "${c.title}", Tags: ${c.tags.join(
              ", ",
            )}, Score: ${c.relevance_score.toFixed(2)}`,
        )
        .join("\n");

      const combinedText = `Summary:\\n\\n${summaryText}\\n\\nSources used (${citations.length}):\\n\\n${citationText}`;

      return {
        content: [
          {
            type: "text",
            text: combinedText,
          },
        ],
        structuredContent: {
          summary: summaryText,
          sources_used: citations.length,
          citations: citations,
        },
      };
    } catch (error: any) {
      return {
        content: [
          {
            type: "text",
            text: `Error generating summary and citations: ${error.message}`,
          },
        ],
        isError: true,
      };
    }
  }
);

最后，我们需要用 stdio 启动服务器。这意味着 MCP 客户端将通过读取和写入其标准输入和输出流与我们的服务器进行通信。stdio 是最简单的传输选项，适用于客户端作为子进程启动的本地 MCP 服务器。在文件末尾添加以下代码：

const transport = new StdioServerTransport();
server.connect(transport);

现在请您使用以下命令编译该项目：

npx tsc index.ts --target ES2022 --module node16 --moduleResolution node16 --outDir ./dist --strict --esModuleInterop

这将创建一个 dist 文件夹，并在其中创建一个 index.js 文件。

将 MCP 服务器加载到 Claude Desktop。

请按照本指南配置 MCP 服务器和 Claude Desktop。在 Claude 配置文件中，我们需要设置以下值：

{
  "mcpServers": {
    "elasticsearch-rag-mcp": {
      "command": "node",
      "args": [   "/Users/user-name/app-dir/dist/index.js"
      ],
      "env": {
        "ELASTICSEARCH_ENDPOINT": "your-endpoint-here",
        "ELASTICSEARCH_API_KEY": "your-api-key-here",
        "OPENAI_API_KEY": "your-openai-key-here"
      }
    }
  }
}

args 的值应指向 dist 文件夹中的编译后文件。您还需要在配置文件中设置环境变量，使其名称与代码中定义的名称完全一致。

测试一下

在执行每个工具前，点击搜索和工具，确保这些工具已启用。您还可以在这里启用或禁用每个工具：

最后，让我们从 Claude Desktop 聊天中测试 MCP 服务器，并开始提问：

针对问题“搜索有关身份验证方法和基于角色的访问控制的文档”，已执行 search_docs 工具并返回以下结果：

Most Relevant Documents:
Access Control and Role Management (highest relevance) - This document covers role-based access control (RBAC) principles, including ensuring users only have necessary permissions, regular auditing of user roles, revoking inactive accounts, and implementing just-in-time access for sensitive operations.
User Authentication with OAuth 2.0 - This document explains OAuth 2.0 authentication, which enables secure delegated access without credential sharing. It covers configuring identity providers, token management with limited scope and lifetime, and secure storage of refresh tokens.
Container Security Guidelines - While primarily about container security, this document touches on access control aspects like running containers as non-root users and avoiding embedded credentials.
Incident Response Playbook - This mentions role assignment during incidents (incident commander, communications lead, etc.), which relates to access control in emergency scenarios.
Logging Standards for Microservices - This document includes guidance on avoiding logging sensitive information, which is relevant to authentication security.

回复是：“太好了！我找到了 5 份关于身份验证方法和基于角色的访问控制的相关文档。以下是找到的内容：”

该工具调用会将源文档作为其响应有效负载的一部分返回，这些文档随后用于生成引用。

您也可以在一次交互中串联使用多个工具。在这种情况下，Claude Desktop 会分析用户的问题，并确定首先需要调用 search_docs 来检索相关文档，然后将这些结果传递给 summarize_and_cite 以生成最终回答，所有这些都无需用户单独提示：

在这种情况下，对于“在我们的系统中改进身份验证和访问控制的主要建议是什么？附上参考文献”，我们得到了以下结果：

Based on the documentation, here are the main recommendations to improve authentication and access control across your systems:

Key Recommendations

1. Implement Role-Based Access Control (RBAC)
Ensure users have only the permissions necessary for their job functions. This principle of least privilege minimizes security risks by limiting access to what's truly needed. [1]

2. Regular Access Audits
Conduct regular audits of user roles and promptly revoke access for inactive accounts. This helps prevent unauthorized access from dormant or compromised accounts. [1]

3. Just-in-Time (JIT) Access
Implement just-in-time access for sensitive operations, where permissions are granted only when needed and for a limited duration. This reduces the attack surface by minimizing standing privileges. [1]

4. OAuth 2.0 for Secure Authentication
Use OAuth 2.0 to enable secure delegated access without sharing user credentials. This protocol allows third-party applications to access resources on behalf of users without exposing passwords. [2]

5. Token Security and Management
Configure your identity provider to issue tokens with limited scope and lifetime

Store refresh tokens securely
Validate access tokens consistently to maintain security [2]
References

Access Control and Role Management (Tags: security, access-control)
User Authentication with OAuth 2.0 (Tags: authentication, oauth)
These recommendations work together to create a defense-in-depth approach, where multiple security layers protect your systems from unauthorized access.

与上一步一样，我们可以看到每个工具对该问题的响应：

注意：如果出现子菜单询问是否批准使用每个工具，请选择“始终允许”或“允许一次”。

结论

MCP 服务器代表了本地和远程应用中 LLM 工具标准化的重要一步。虽然完全兼容仍在开发中，但我们正朝这个方向快速推进。

在本文中，我们学习了如何用 TypeScript 构建一个自定义 MCP 服务器，将 Elasticsearch 连接到基于 LLM 的应用。我们的服务器公开了两个工具：search_docs 用于使用查询 DSL 检索相关文档；summarize_and_cite 用于通过 OpenAI 模型和 Claude Desktop 作为客户端 UI 生成带引用的摘要。

不同客户端和服务器提供商之间的兼容性前景看起来一片光明。下一步包括为您的智能体添加更多功能和灵活性。这里有一篇实用的文章介绍了如何使用搜索模板参数化查询，以获得精确性和灵活性。

正因如此，我们才构建了只读仪表板。这是您一直在要求的控制权。放心地共享仪表板，无需担心下一个拥有编辑权限的人会更改或破坏仪表板。

注意：只读权限在 Elastic Cloud Serverless 中可用，并且从 9.3 版本开始在 Elastic Cloud Hosted 和 Elastic Self-Managed 中可用。

当“人人皆可编辑”成为障碍时

在 Kibana 中，共享通常意味着空间层级的权限。如果有人可以在某个空间创建仪表板，他们也可以编辑或删除其他人的仪表板。这对协作来说原本是件好事，直到情况变得不妙。一次意外的编辑可能会导致错误的决策、失去信任和大量的清理工作。

我们听说过一些替代方案：“我们在仪表板名称中加上‘只读’，希望用户能注意到”。或者：“我们给它们贴上标签，然后祈祷好运。”希望并不是一种权限模型。您需要一种真正的方法来锁定仪表板，同时又不将所有人拒之门外。

到底出了什么问题

Deb 和 Kevin 都拥有对运营空间中的日志监控仪表板的编辑权限。Kevin 对图表进行了一些更改。当 Deb 回来后，发现数字与她之前提交的不符。她必须追溯哪些地方发生了变化（通常凭记忆），然后进行修正，还要弄清楚有多少份报告发出了错误数据。

只读仪表板：合理的所有权和控制权

只读仪表板可解决此问题，让您能够控制其他用户是否可以编辑该仪表板。共享仪表板时，您可以选择：编辑（默认，与当前相同）或查看。在查看模式下，只有你（和 Kibana 管理员）可以对其进行更改或删除。其他人可以打开它、使用它、信任它，但他们无法对其进行修改。

您将获得的内容

• 仪表板完整性：在查看模式下，该空间内具有编辑权限的其他用户无法修改或删除仪表板。如果他们尝试，会被告知仪表板已锁定。您的图表和逻辑将保持原样。
• 您掌控一切：你是所有者。您随时都可以编辑、完善和更新。以“仅查看”的方式共享并不会将您锁定，而是会锁定其他人看到的版本。
• 灵活的生命周期：您可以随时将仪表板切换回“可编辑”状态。Kibana 管理员仍然可以管理所有仪表板（例如，在仪表板所有者离开的情况下）。因此，不会出现无人管理的情况。

您可以广泛共享最终确定的关键任务仪表板，并确信这些仪表板将保持一致。所有 Elastic 层级和产品（包括 Serverless）均提供此功能。

谁能做什么？

按角色快速参考：

• 仪表板所有者：您创建了它；您拥有完全的编辑权限。
• Kibana 管理员：可以管理所有仪表板。
• 具有空间编辑权限的用户：可以创建和编辑自己的仪表板；但不能编辑或删除仅查看的仪表板。
• 具有空间视图的用户：只能查看（和列出）仪表板。

如何启用只读

您可以在保存新仪表板时设置仅查看模式，也可以稍后从共享菜单中设置。

保存新仪表板时

• 创建您的仪表板，然后单击“保存”。
• 在“另存为新仪表板”模态框中，找到“权限”。
• 从“可编辑”更改为“可查看”。
• 单击“保存”。完成。它对其他所有人都是只读的。

对于您已拥有的仪表板

• 打开仪表板。
• 打开“共享仪表板”菜单。

• 在共享模式中，找到“权限”并切换到“可查看”。将立即应用更改；空间中的其他用户将无法再编辑或删除它。

• 您可以将鼠标悬停在“共享”操作上，查看给定仪表板拥有的权限类型。

查看哪些仪表板被锁定

在主仪表板列表中，无法编辑或删除的仪表板有一个禁用选择复选框。这为找出“仅查看”的内容提供了一种简便的方法。

在仪表板中，您还会发现“编辑”操作已禁用，并且会出现一个工具提示，说明仪表板已设置为“仅查看”。

试用

只读仪表板现已推出。创建仪表板，将其切换到“可查看”，然后共享。您的团队将获得单一可信来源，而您则高枕无忧。标题中不再包含“请勿编辑”字样。

我们很想听听您是如何使用只读仪表板的。在我们的社区论坛中分享您的反馈。

本文重新聚焦于这个问题：智能体构建自身上下文需要哪些正确的搜索接口？它首先讨论了 shell 工具与专用数据库工具之间的取舍。在此基础上，它提供了一个实用的框架，用于为您的智能体需求找到正确的接口。

对智能体而言，“构建上下文”到底意味着什么？

在早期的 Retrieval-Augmented Generation (RAG) 管道中，开发人员设计了一个固定的检索管道，而大型语言模型（LLM）只是上下文的被动接收者。这是一个根本性的限制：无论是否需要，每次查询都要检索上下文，而且不检查上下文是否真的有帮助。

随着向智能体式 RAG 的转变，智能体现在可以访问一组搜索工具来构建自己的上下文。例如，Claude Code [1] 和 Cursor [2] 都允许智能体根据任务的实际需求，在不同的搜索工具之间进行选择，甚至将它们组合起来用于链式查询。

有哪些用于上下文工程的搜索接口？

上下文可以存在于不同的位置，例如网络上、本地文件系统中或数据库中。智能体可以通过不同的工具与这些脱离上下文的每个数据源进行交互：

• shell 工具 可以执行 shell 命令并访问本地文件系统。一些内置 shell 工具的例子包括 Claude API 的 bash 工具、OpenClaw 的 exec 工具以及 LangChain 的 shell 工具。
• 专用数据库工具，例如来自模型上下文协议（MCP）服务器（例如，Elastic Agent Builder MCP 服务器）的工具或自定义工具（例如，run_esql(query) 或 db_list_index()），可以查询数据库。
• 专用文件搜索工具可以搜索和读取本地（或上传）文件（无需完整的 shell 访问权限）。一些内置文件搜索工具的例子是 Gemini API 的文件搜索工具 或 OpenAI 的文件搜索工具。
• 网络搜索工具可以从网络上检索信息。
• 记忆工具会存储和回忆长期记忆中的内容（无论存储方式如何）。

如图所示，shell 工具功能强大，可用于从不同数据源检索上下文，包括：

• 文件系统：智能体会探索目录结构（ls、find），搜索相关内容（grep、cat），并不断重复，直到构建足够的上下文。
• 数据库：智能体可以使用数据库命令行接口（CLI）工具（例如，elasticsearch-sql-cli），通过 curl 调用 HTTP API 或运行脚本，这在与 Agent Skills 结合使用时特别有用。Agent Skills 是注入到智能体上下文中用于指导正确工具使用的可复用、带示例的文档（例如 Elastic Agent Skills for Elasticsearch）。
• 网络：智能体可以通过搜索提供商的 API，使用 curl 命令执行网络搜索。

然而，shell 工具提供直接的系统访问权限，因此需要采取安全措施，例如在隔离的沙盒环境中运行，并记录所有执行的命令。

何时使用哪种搜索接口

正确的搜索接口取决于您的数据、查询模式以及用例场景。本节将作为实用的入门起点。

文件系统并不会让数据库过时

文件系统与数据库的讨论并非关于存储层。例如，LangChain 解释说，其记忆系统实际上并不将记忆存储在真实的文件系统中。相反，它将记忆存储在数据库中，并以文件集合的形式呈现给智能体 [3]。

文件系统天然适用于以文件为中心的用例，例如编码智能体。它们也可以很好地用作临时暂存区或工作记忆，以及适用于无需考虑并发问题的单用户或单智能体场景。在这些情况下，在投入构建专用接口之前，使用物理文件系统或将数据表示为文件系统可以为您提供灵活性。

但是，文件系统存储确实存在缺点，例如并发性弱、需要手动执行模式约束、原子事务支持差。当您的应用程序需要扩展或迁移到多智能体场景时，这些缺点会更加明显。任何忽视这些缺点的人都注定要痛苦地重新发明更糟糕的数据库，却缺乏生产数据库已经提供的、经过数十年工程实践的事务安全或访问控制机制。此外，在大多数企业环境中，您并非选择是否使用数据库——因为数据库已经存在，并存储着业务关键数据。

Shell 工具 + 文件系统

对于文件系统搜索，shell 工具是自然的起点。当前，编码智能体正在推动该领域取得巨大进展。由于它们处理本地文件中的代码，因此自然是以文件为主的用例。因此，LLM 在后训练阶段会针对编码任务进行微调。这就是为什么许多 LLM 不仅擅长编写代码，还擅长使用 shell 命令和操作文件系统的原因。

使用带有内置 CLI（如 ls 和 grep）的 shell 工具来查找文件是有效的。使用 grep，像“Find all files that import matplotlib”这样的查询既快速、精确又廉价。但是，当智能体需要处理概念性查询（例如“How does our app handle failed authentication?”）时，使用 grep 进行模式匹配很快就会触及天花板。为了填补这一空白，出现了一些将语义搜索能力带到命令行的替代方案，包括 jina-grep。

然而，grep 及其许多语义搜索替代方案在语料库上的运行速度为 O(n)。对于代码库相关的使用场景，这可能没问题。但是，如果数据量增加，延迟就会变得很明显。在这种情况下，为了保持性能，需要使用索引数据存储。

shell 工具 + 数据库

另一种为数据添加更多搜索能力（例如语义搜索或混合搜索）的方法是将数据存储在数据库中，就像 Cursor 所做的那样。此外，当数据需要复杂的关系连接或聚合时，数据库接口是不可或缺的。

数据存储在数据库中而非文件系统上时，shell 工具可以在某些用例中充当轻量级的数据库接口。如果您的查询足够简单，只需 CLI 或 curl 调用即可完成，那么专用的数据库工具可能会带来不必要的复杂性。

这种方法也适用于早期的探索阶段，此时您还不知道智能体最终会发展出什么样的查询模式。在这种情况下，Agent Skills 可以为智能体提供足够的结构来正确执行查询，而无需投入构建专用工具。但是，当智能体需要大量迭代才能找出针对重复任务查询数据库的正确方式时，使用 shell 工具作为接口所带来的词元开销，就不再能抵消避免使用额外工具的简单性优势了。

专用数据库工具

特别是当重复的查询模式是结构化的或分析性的时，专用的数据库工具就变得必要了。Vercel 和 Braintrust 的一篇博客文章比较了拥有不同搜索工具集的智能体，在半结构化数据（如客户支持工单和销售通话记录）上执行真实世界的检索任务（例如，“How many open issues mention 'security'?”或“Find issues where someone reported a bug and later someone submitted a PR claiming to fix it?”）[4]。

拥有专用数据库工具的智能体，与仅拥有 shell 工具和文件系统的智能体相比，使用的词元更少，速度更快，犯的错误也更少。经验表明，当查询需要对半结构化数据进行分析推理时，直接使用数据库工具才是正确的选择。

组合使用搜索接口

没有哪一个搜索接口能完美处理所有查询。例如，Cursor 将 shell 工具（用于通过 grep 搜索）和语义搜索工具组合起来，让智能体根据用户提示选择正确的工具。智能体会选择 grep 来匹配特定的符号或字符串，选择语义搜索来处理概念性或行为性问题，并在探索性任务中同时使用两者。

Vercel 的实验报告了相同的结果：其混合型智能体可同时访问 shell 工具和专用数据库工具，通过首先使用专用数据库工具，然后通过文档系统 grepping 验证结果，在所有测试的智能体中取得了最佳性能。这种方法在工具选择和验证的推理上消耗了更多的词元和时间。

这两个示例中的模式是相同的：组合优于任何单一接口，但组合的代价是增加成本和延迟。

寻找合适工具的实用建议

合适的搜索接口应该简洁、目标明确，并且能够满足您的智能体的实际查询模式。当前的最佳实践是让智能体拥有尽可能少的工具，而不是让它拥有数百个 MCP 工具。这是因为，预先公开所有可能的工具会带来弊端：它会使上下文窗口臃肿，并使智能体困惑于到底该使用哪个工具。例如，据报道 Claude Code 只有大约 20 种工具。

相反，渐进式公开的理念是从一套最基本的工具开始，让智能体在需要时才发现额外的功能。Anthropic [5] 和 Cursor [6] 的研究表明，这种方法可以节省 47%–85% 的词元。例如，Claude Code 直接实现了这一点，允许智能体逐步发现如何查询 API 或数据库，而无需在每次 LLM 调用时都将这些知识消耗在上下文中。

一旦您熟悉了智能体的查询模式，就可以重新审视智能体默认可以访问的搜索工具集。一种思考这种取舍的有用方式是使用”低门槛，高上限“原则，用于决定哪些工具值得被纳入。高上限工具不会限制智能体的潜力。例如，一个通用的 shell 工具允许智能体编写完整的数据库查询（包括模糊查询），但代价是推理开销、更高的延迟和更低的可靠性。

“低门槛”工具则相反。它们是封装了特定查询的专用工具，智能体可以以最少的推理开销直接使用，从而产生更低的成本和更高的可靠性。但它们需要前期工程投入，无法覆盖所有可能的查询，并且可能使智能体更难选择正确的工具。

可将每个工具视为处在一条连续谱上：低门槛工具更容易被代理正确使用，但覆盖范围较窄。高上限工具用途广泛，但要用得好需要更多推理。

多数智能体需要混合使用不同的搜索工具。但每个工具都需要“凭实力”加入。我们建议从一个通用的搜索工具（例如 search_database() 工具或 shell 工具）开始。然后，复用您出于安全目的已经保留的命令日志，来跟踪智能体的实际行为，包括工具调用、重试次数以及每个用户查询的调用次数。并且，当您看到某个查询模式重复出现或执行失败时，这就是为该模式构建专用工具的信号。

总结

文件系统与数据库的争论分散了工程师们真正需要关注的问题：智能体构建自身上下文需要哪些正确的搜索接口？答案很可能是：不是单一一个接口。

shell 工具是一种用于与不同上下文外数据源交互的通用工具，因此是一个很好的起点。但在结构化分析查询的用例中，它的效率和准确度不如专用数据库工具。

目标是找到能够良好处理智能体实际查询模式的最小搜索工具集。从 shell 工具开始，记录智能体的实际行为。当您发现某个查询模式重复出现且执行失败时，就该为该模式设计专用工具了。

参考资料

1. Thariq (Anthropic). Lessons from Building Claude Code: Seeing like an Agent (2026).

2. Cursor: Documentation. Semantic & agentic search (2026).

3. Harrison Chase (LangChain). How we built Agent Builder’s memory system (2026).

4. Ankur Goyal (Braintrust) and Andrew Qu (Vercel). Testing if "bash is all you need" (2026).

5. Anthropic. Introducing advanced tool use on the Claude Developer Platform (2025).

6. Cursor. Dynamic context discovery (2026).

派对越来越拥挤了

您要举办一个披萨派对。您有几位朋友协助您招待宾客，他们分别在房间的不同位置。您把披萨分给每位朋友，他们会在饥饿的宾客陆续到来时开始分发披萨。

起初，一切运行顺利。有几位宾客陆续进来，朋友们端上披萨片，大家都很开心。但随后关于您的披萨的消息传开了。门铃一直在响。宾客们蜂拥而至。很快，人群聚集在您的一位朋友周围，就是那个拿着意式辣味香肠披萨的朋友，似乎大家都想要那块披萨。

您那位拿着意式辣味香肠披萨的朋友感到不知所措。宾客们正在等待，变得不耐烦了，还排起了长队。与此同时，您的朋友手持玛格丽特披萨站在那里，几乎没有人要一片。

您需要怎么做？

您又点了几份意式辣味香肠披萨，并把它们分给其他朋友。现在有三位朋友在拿着意式辣味香肠披萨分发，而不再只是一个人。人群散开了，突然间您就能一次性接待三倍数量的宾客。

随着您举办的派对越来越多，有几件事会变得越来越清晰：

• 并非所有披萨都同样受欢迎。有些供不应求，有些则鲜有人问津。您不需要为那些不受欢迎的披萨准备多余的“份数”。您需要为那些排队的披萨准备更多“份数”。
• 在排队人数变多之前多点几份披萨。如果您等到朋友已经忙得不可开交、客人都气得离场时才行动，那就太晚了。最好是在看到人群聚集时，就提前加点一份披萨。
• 别太快把披萨撤走。即使意式辣味香肠披萨周围的人群散开了五分钟，也不代表高峰期已经过去。也许他们只是在加饮料，甚至只是在聊天（现在还是这样吗？）。把多余的披萨准备好。如果冷场确实持续了一段时间，那时再撤走也不迟。
• 您能分发的披萨数量取决于有多少朋友来帮忙。如果您只有四个朋友在帮忙，十张披萨也改变不了结果。一次只能供应四份。将您的披萨数量与可用人手相匹配。
• 当一个朋友离开时，记得接管他的披萨。如果您的朋友需要离开，请立即拿走他们的披萨。披萨不能无人看管地放置。将它交给其他人，或者妥善收好。

我们已经聊完了披萨和副本

现在让我们把这些生动的小故事映射回 Elasticsearch。

在我们的类比中，披萨是副本（索引分片的副本），帮助提供服务的朋友是搜索节点，饥肠辘辘的宾客是搜索查询，而人头攒动的热门披萨则是搜索负载较高的热门索引。

当特定索引的搜索流量增加时，我们会创建额外的副本，并将它们分发到搜索节点上。任何副本都可以为该索引的任何查询提供服务，就像任何拿着意式辣味香肠披萨的朋友都可以分发意式辣味香肠披萨片一样。更多副本意味着更高的吞吐量：三个副本每秒处理的查询量是单个副本的三倍。

衡量饥饿程度

在决定订购多少披萨之前，我们需要了解人群的饥饿程度。

Elasticsearch 会跟踪每个分片的搜索负载。这是一个度量指标，用于衡量分片正在处理的搜索活动的数量。我们将此汇总到索引的所有分片中，以了解总的搜索需求。

最重要的是相对搜索负载：您的项目总搜索流量中，每个索引所占的比例是多少？如果一个索引的搜索量为 60%，而另一个索引的搜索量为 5%，我们就知道应该在哪里增加容量。

披萨背后的数学原理

我们按照以下公式计算最佳副本数量：

desired_replicas = min(ceil(L × N / (S × X)), N)

其中：

• L = 索引的相对搜索负载（介于 0 和 1 之间）。
• N = 项目中所需搜索节点的数量。
• S = 索引中的分片数量。
• X = 用于避免热点的阈值（默认值：0.5）。

示例：四个搜索节点，具有两个主分片的一个索引，接收 80% 的搜索流量：

desired_replicas = min(ceil(0.8 × 4 / (2 × 0.5)), 4)
                 = min(4, 4)
                 = 4

这个热索引有四个副本，分布在各个搜索节点上。

阈值 X（默认为 0.5）非常重要。我们不会等到副本完全不堪重负才采取行动；当副本的负载达到一半容量时，我们就会进行扩展。当看到人群聚集时再分发额外的披萨，而不是等到宾客已经开始离开的时候。

快速扩展，缓慢收缩

当搜索负载增加时，我们立即添加副本。没有理由让用户等待。

当搜索负载下降时，我们会等待一段时间再采取行动。在减少副本之前，我们需要看到持续约 30 分钟的低需求。（这是为了应对流量高峰，因为短暂的平静并不意味着派对结束。）

这很重要，因为添加副本是有成本的。在高效提供查询之前，新的副本会复制数据并预热其缓存。过于急切地移除副本意味着在流量自然波动时持续支付这种启动成本。

尊重拓扑边界

副本永远不能超过搜索节点的数量。拥有比节点更多的副本并不会带来任何好处（您能送出的披萨数量取决于帮忙的朋友数量）。

从您的项目中移除节点时，我们会立即减少副本数量以进行匹配。无需等待冷却时间，因为您无法拥有未分配的副本。朋友离开的那一刻，我们就会移除他们的披萨。

无服务器的全貌

用于搜索负载均衡的副本与其他自动缩放系统协同工作：

• 搜索自动缩放可调整搜索节点的数量（有多少朋友在帮忙）。
• 用于搜索负载均衡的副本通过调整每个索引的副本数量来分发流量（我们需要每种披萨的数量）。
• 数据流自动分片优化了写入的分片数量（如何将每个披萨切片，详情见上一篇文章）。

一个重要的设计原则：用于负载均衡的副本不会直接触发搜索自动扩展。相反，通过将搜索请求分发给更多副本，可以提高搜索节点的资源利用率。这种更高的利用率会触发我们现有的自动扩展逻辑，以便在需要时增加容量。用于负载均衡的副本可让自动扩展发挥作用，确保搜索节点真正得到使用，而不是将所有流量都集中在单个副本上造成瓶颈，而其他节点却处于闲置状态。

这对您意味着什么

您无需预测哪些索引会更受欢迎。当流量模式发生变化时，您无需手动调整副本。您无需因为流量激增导致最繁忙的索引不堪重负，而不得不凌晨 3 点起床进行处理。

系统会观察排队的地点，并为这些地点订购更多披萨。冷索引不会在不必要的副本上浪费资源。热门索引会获得所需的容量。您的预算用在了最重要的地方。

结论

在自动分片文章中，我们确保您的披萨切得恰到好处。现在，有了用于搜索负载均衡的副本，我们可以确保在饥饿的人群到来时，有足够的披萨送到他们手中。

试用 Elastic Cloud Serverless，让我们来处理披萨分发事宜。

准备工作

• Elasticsearch 9.3 或 Elastic Cloud Serverless：您可以按照这些说明创建云部署，或者改用 start-local 快速入门。
• Python 3.12：在此处下载 Python。
• Hugging Face 访问令牌。

使用 Hugging Face 推理终端完成聊天

首先，我们将构建一个实用示例，将 Elasticsearch 连接到 Hugging Face 推理终端，以从博客文章集合中生成 AI 驱动的推荐。对于应用知识库，我们将使用公司博客文章数据集，其中包含有价值但通常难以查找的信息。

通过这个终端，语义搜索可以检索与给定查询最相关的文章，而 Hugging Face LLM 则会根据这些结果生成简短的上下文推荐。

让我们来看看我们将要构建的信息流的高级概述：

在本文中，我们将测试 SmolLM3-3B 是否能将其紧凑的大小与强大的多语言推理和工具调用能力相结合。根据搜索查询，我们将把所有匹配的内容（英语和西班牙语）发送到 LLM，以生成一份推荐文章列表，并根据搜索查询和结果提供自定义描述。

以下是具备 AI 推荐生成系统的文章网站用户界面可能的外观。

您可以在已链接的笔记本中找到此应用程序的完整实现。

配置 Elasticsearch 推理终端

要使用 Elasticsearch Hugging Face 推理终端，我们需要两个重要元素：Hugging Face API 密钥和正在运行的 Hugging Face 终端 URL。它应该如下所示：

PUT _inference/chat_completions/hugging-face-smollm3-3b
{
    "service": "hugging_face",
    "service_settings": {
        "api_key": "hugging-face-access-token", 
        "url": "url-endpoint" 
    }
}

Elasticsearch 中的 Hugging Face 推理终端支持不同的任务类型：text_embedding、completion、chat_completion 和 rerank。在这篇博客文章中，我们使用 chat_completion 是因为我们需要模型根据搜索结果和系统提示生成对话式推荐。此终端允许我们使用 Elasticsearch API 以简单的方式直接从 Elasticsearch 执行聊天完成：

POST _inference/chat_completion/hugging-face-smollm3-3b/_stream
{
  "messages": [
      { "role": "user", "content": "" }
  ]
}

这将作为应用程序的核心，接收通过模型传递的提示和搜索结果。有了理论基础，我们就开始实施应用程序。

在 Hugging Face 上设置推理终端

要部署 Hugging Face 模型，我们将使用 Hugging Face 一键式部署，这是一种用于部署模型终端的简单快速的服务。请记住，这是一项付费服务，使用它可能会产生额外费用。此步骤将创建用于生成文章推荐的模型实例。

您可以从一键目录中选择一个模型：

让我们选择 SmolLM3-3B 模型：

从此处获取 Hugging Face 终端 URL：

正如在 Elasticsearch Hugging Face 推理终端文档中提到的，文本生成需要一个与 OpenAI API 兼容的模型。因此，我们需要将 /v1/chat/completions 子路径附加到 Hugging Face 终端 URL。最终结果将如下所示：

https://j2g31h0futopfkli.us-east-1.aws.endpoints.huggingface.cloud/v1/chat/completions

有了这个，我们就可以在 Python 笔记本中开始编码了。

生成 Hugging Face API 密钥

创建 Hugging Face 账户，并按照以下说明获取 API 令牌。您可以选择三种令牌类型：细粒度（推荐用于生产，因为它仅提供对特定资源的访问）、读取（适用于只读访问）或写入（适用于读取和写入访问）。在本教程中，读取令牌就足够了，因为我们只需要调用推理终端。请保存此密钥以备下一步使用。

设置 Elasticsearch 推理终端

首先，让我们声明一个 Elasticsearch Python 客户端：

os.environ["ELASTICSEARCH_API_KEY"] = "your-elasticsearch-api-key"
os.environ["ELASTICSEARCH_URL"] = "https://xxxx.us-central1.gcp.cloud.es.io:443"

es_client = Elasticsearch(
    os.environ["ELASTICSEARCH_URL"], api_key=os.environ["ELASTICSEARCH_API_KEY"]
)

接下来，我们创建一个使用 Hugging Face 模型的 Elasticsearch 推理终端。此终端将允许我们基于博客文章和传递给模型的提示来生成响应。

INFERENCE_ENDPOINT_ID = "smollm3-3b-pnz"

os.environ["HUGGING_FACE_INFERENCE_ENDPOINT_URL"] = (
 "https://j2g31h0futopfkli.us-east-1.aws.endpoints.huggingface.cloud/v1/chat/completions"
)
os.environ["HUGGING_FACE_API_KEY"] = "hf_xxxxx"

resp = es_client.inference.put(
        task_type="chat_completion",
        inference_id=INFERENCE_ENDPOINT_ID,
        body={
            "service": "hugging_face",
            "service_settings": {
                "api_key": os.environ["HUGGING_FACE_API_KEY"],
                "url": os.environ["HUGGING_FACE_INFERENCE_ENDPOINT_URL"],
            },
        },
    )

数据集

该数据集包含将要查询的博客文章，代表整个工作流中使用的多语言内容集：

// Articles dataset document example: 
{
    "id": "6",
    "title": "Complete guide to the new API: Endpoints and examples",
    "author": "Tomas Hernandez",
    "date": "2025-11-06",
    "category": "tutorial",
    "content": "This guide describes in detail all endpoints of the new API v2. It includes code examples in Python, JavaScript, and cURL for each endpoint. We cover authentication, resource creation, queries, updates, and deletion. We also explain error handling, rate limiting, and best practices. Complete documentation is available on our developer portal."
  }

Elasticsearch 映射

定义数据集后，我们需要创建一个适合博客文章结构的数据模式。以下索引映射将用于在 Elasticsearch 中存储数据：

INDEX_NAME = "blog-posts"

mapping = {
    "mappings": {
        "properties": {
            "id": {"type": "keyword"},
            "title": {
                "type": "object",
                "properties": {
                    "original": {
                        "type": "text",
                        "copy_to": "semantic_field",
                        "fields": {"keyword": {"type": "keyword"}},
                    },
                    "translated_title": {
                        "type": "text",
                        "fields": {"keyword": {"type": "keyword"}},
                    },
                },
            },
            "author": {"type": "keyword", "copy_to": "semantic_field"},
            "category": {"type": "keyword", "copy_to": "semantic_field"},
            "content": {"type": "text", "copy_to": "semantic_field"},
            "date": {"type": "date"},
            "semantic_field": {"type": "semantic_text"},
        }
    }
}


es_client.indices.create(index=INDEX_NAME, body=mapping)

在这里，我们可以更清楚地看到数据的结构。我们将使用语义搜索来检索基于自然语言的结果，同时使用 copy_to 属性将字段内容复制到 semantic_text 字段中。此外，title 字段包含两个子字段：original 子字段根据文章的原始语言存储英语或西班牙语标题；而 translated_title 子字段仅存在于西班牙语文章中，并包含原始标题的英语翻译。

采集数据

以下代码片段使用批量 API 将博客文章数据集摄取到 Elasticsearch 中：

def build_data(json_file, index_name):
    with open(json_file, "r") as f:
        data = json.load(f)

    for doc in data:
        action = {"_index": index_name, "_source": doc}
        yield action


try:
    success, failed = helpers.bulk(
        es_client,
        build_data("dataset.json", INDEX_NAME),
    )
    print(f"{success} documents indexed successfully")

    if failed:
        print(f"Errors: {failed}")
except Exception as e:
    print(f"Error: {str(e)}")

现在，我们已将文章摄取到 Elasticsearch 中，我们需要创建一个能够针对 semantic_text 字段进行搜索的函数：

def perform_semantic_search(query_text, index_name=INDEX_NAME, size=5):
    try:
        query = {
            "query": {
                "match": {
                    "semantic_field": {
                        "query": query_text,
                    }
                }
            },
            "size": size,
        }

        response = es_client.search(index=index_name, body=query)
        hits = response["hits"]["hits"]

        return hits
    except Exception as e:
        print(f"Semantic search error: {str(e)}")
        return []

我们还需要一个调用推理终端的函数。在这种情况下，我们将使用 chat_completion 任务类型调用终端，以获取流式响应：

def stream_chat_completion(messages: list, inference_id: str = INFERENCE_ENDPOINT_ID):
    url = f"{ELASTICSEARCH_URL}/_inference/chat_completion/{inference_id}/_stream"
    payload = {"messages": messages}
    headers = {
        "Authorization": f"ApiKey {ELASTICSEARCH_API_KEY}",
        "Content-Type": "application/json",
    }

    try:
        response = requests.post(url, json=payload, headers=headers, stream=True)
        response.raise_for_status()

        for line in response.iter_lines(decode_unicode=True):
            if line:
                line = line.strip()

                if line.startswith("event:"):
                    continue

                if line.startswith("data: "):
                    data_content = line[6:]

                    if not data_content.strip() or data_content.strip() == "[DONE]":
                        continue

                    try:
                        chunk_data = json.loads(data_content)

                        if "choices" in chunk_data and len(chunk_data["choices"]) > 0:
                            choice = chunk_data["choices"][0]
                            if "delta" in choice and "content" in choice["delta"]:
                                content = choice["delta"]["content"]
                                if content:
                                    yield content

                    except json.JSONDecodeError as json_err:
                        print(f"\nJSON decode error: {json_err}")
                        print(f"Problematic data: {data_content}")
                        continue

    except requests.exceptions.RequestException as e:
        yield f"Error: {str(e)}"

现在，我们可以编写一个函数，调用语义搜索函数以及 chat_completions 推理终端和建议终端，以生成将分配到卡片中的数据：

def recommend_articles(search_query, index_name=INDEX_NAME, max_articles=5):
    print(f"\n{'='*80}")
    print(f"🔍 Search Query: {search_query}")
    print(f"{'='*80}\n")

    articles = perform_semantic_search(search_query, index_name, size=max_articles)

    if not articles:
        print("❌ No relevant articles found.")
        return None, None

    print(f"✅ Found {len(articles)} relevant articles\n")

    # Build context with found articles
    context = "Available blog articles:\n\n"
    for i, article in enumerate(articles, 1):
        source = article.get("_source", article)
        context += f"Article {i}:\n"
        context += f"- Title: {source.get('title', 'N/A')}\n"
        context += f"- Author: {source.get('author', 'N/A')}\n"
        context += f"- Category: {source.get('category', 'N/A')}\n"
        context += f"- Date: {source.get('date', 'N/A')}\n"
        context += f"- Content: {source.get('content', 'N/A')}\n\n"

    system_prompt = """You are an expert content curator that recommends blog articles.

    Write recommendations in a conversational style starting with phrases like:
    - "If you're interested in [topic], this article..."
    - "This post complements your search with..."
    - "For those looking into [topic], this article provides..."


    FORMAT REQUIREMENTS:
    - Return ONLY a JSON array
    - Each element must have EXACTLY these three fields: "article_number", "title", "recommendation"
    - If the original title is in spanish, use the "translated_title" subfield in the "title" field

    Keep each recommendation concise (2-3 sentences max) and focused on VALUE to the reader.

    EXAMPLE OF CORRECT FORMAT:
    [
        {"article_number": 1, "title": "Article title in english", "recommendation": "If you are interested in [topic], this article provides..."},
        {"article_number": 2, "title": "Article title in english", "recommendation": " for those looking into [topic], this article provides..."}
    ]

    Return ONLY the JSON array following this exact structure."""

    user_prompt = f"""Search query: "{search_query}"

    Generate recommendations for the following articles: {context}
    """

    messages = [
        {"role": "system", "content": "/no_think"},
        {"role": "system", "content": system_prompt},
        {"role": "user", "content": user_prompt},
    ]

    # LLM generation
    print(f"{'='*80}")
    print("🤖 Generating personalized recommendations...\n")

    full_response = ""

    for chunk in stream_chat_completion(messages):
        print(chunk, end="", flush=True)
        full_response += chunk

    return context, articles, full_response

最后，我们需要提取信息并将其格式化以便打印：

def display_recommendation_cards(articles, recommendations_text):
    print("\n" + "=" * 100)
    print("📇 RECOMMENDED ARTICLES".center(100))
    print("=" * 100 + "\n")

    # Parse JSON recommendations - clean tags and extract JSON
    recommendations_list = []
    try:

        # Clean up  tags
        cleaned_text = re.sub(
            r".*?", "", recommendations_text, flags=re.DOTALL
        )
        # Remove markdown code blocks ( ... ``` or ``` ... ```)
        cleaned_text = re.sub(r"```(?:json)?", "", cleaned_text)
        cleaned_text = cleaned_text.strip()

        parsed = json.loads(cleaned_text)

        # Extract recommendations from list format
        for item in parsed:
            article_number = item.get("article_number")
            title = item.get("title", "")
            rec_text = item.get("recommendation", "")

            if article_number and rec_text:
                recommendations_list.append(
                    {
                        "article_number": article_number,
                        "title": title,
                        "recommendation": rec_text,
                    }
                )
    except json.JSONDecodeError as e:
        print(f"⚠️  Could not parse recommendations as JSON: {e}")
        return

    for i, article in enumerate(articles, 1):
        source = article.get("_source", article)

        # Card border
        print("┌" + "─" * 98 + "┐")

        # Find recommendation and title for this article number
        recommendation = None
        title = None
        for rec in recommendations_list:
            if rec.get("article_number") == i:
                recommendation = rec.get("recommendation")
                title = rec.get("title")
                break

        # Print title
        title_lines = textwrap.wrap(f"📌 {title}", width=94)
        for line in title_lines:
            print(f"│  {line}".ljust(99) + "│")

        # Card border
        print("├" + "─" * 98 + "┤")

        # Print recommendation
        if recommendation:
            recommendation_lines = textwrap.wrap(recommendation, width=94)
            for line in recommendation_lines:
                print(f"│  {line}".ljust(99) + "│")

        # Card bottom
        print("└" + "─" * 98 + "┘")

让我们通过询问一个有关安全博客文章的问题来测试一下：

search_query = "Security and vulnerabilities"

context, articles, recommendations = recommend_articles(search_query)

print("\nElasticsearch context:\n", context)

# Display visual cards
display_recommendation_cards(articles, recommendations)

如下所示，我们可以看到工作流在控制台中生成的卡片：

您可以在此文件中查看全部结果，包括所有点击和 LLM 响应。

我们正在征集与“安全与漏洞”相关的文章。此问题将用作针对 Elasticsearch 中存储的文档的搜索查询。然后将检索到的结果传递给模型，该模型根据这些结果的内容生成推荐。我们可以看到，该模型出色地生成了引人入胜的短文本，能够激发读者点击的欲望。

结论

本示例展示了如何将 Elasticsearch 和 Hugging Face 结合起来，为 AI 应用程序创建一个快速高效的集中式系统。由于 Hugging Face 拥有丰富的模型目录，这种方法不仅减少了人工操作，还具有灵活性。通过使用 SmolLM3-3B，我们特别看到了紧凑的多语言模型在与语义搜索搭配使用时，仍能提供有意义的推理和内容生成。这些工具共同为构建智能内容分析和多语言应用程序提供了可扩展且高效的基础。

为了解决这个问题，像 Elasticsearch 这样的搜索引擎使用了两种主要的优化策略：

1. 近似搜索（分层可导航小世界 [HNSW]）：我们不需要扫描每一份文档，而是建立一个导航图，以便快速跳转到答案的可能邻域。
2. 量化：我们对向量进行压缩（例如，从 32 位浮点数压缩为 8 位整数，甚至 1 位二进制值），以减少内存使用量并加快计算速度。

但优化往往会使准确性下降。

这种担忧是有道理的：“如果我在搜索过程中压缩数据并使用快捷方式，我会错过最佳结果吗？”“这种优化是否会降低搜索引擎的相关性？”

为了证明 Elastic 的量化不会降低结果，我们使用DBPedia-14 数据集构建了一个可重复的测试工具，以精确计算在使用 Elasticsearch 的默认优化时，准确率下降了多少（特别是召回率）才能提高速度。

总结：可能比您想象的要少得多。点击此处查看笔记本，亲自试试

定义（面向非专业人士）

在了解代码之前，让我们先明确一些术语。

• 相关性与召回率：相关性具有主观性（我找到的是优质内容吗？），而召回率则是基于数学计算。如果数据库中有 10 份文档与查询在数学层面完美匹配，而搜索引擎找到了其中 9 份，那么召回率就是 90%（或 0.9）。
• 精确搜索（扁平式）：有时也被称为“暴力搜索”法。搜索引擎会扫描索引中的每一份文档并计算距离。
  • 优点：召回率达到 100%。
  • 缺点：计算量大且大规模扩展缓慢。
• 近似搜索 (HNSW)：“捷径”方法。搜索引擎生成 HNSW 图表。它遍历图表以找到最近邻。
  • 优点：速度极快且可扩展。
  • 缺点：如果图表遍历过早停止，可能会错过近邻。

实验：精准与近似

为了测试召回率，我们使用了 DBPedia-14 数据集，这是一个包含 14 个本体类别的大型标题和摘要数据集，通常用于训练和评估文本分类模型。具体而言，我们将重点关注“电影”类别。我们希望将优化的生产设置与数学上完美的基准真值进行比较。

在此次实验中，我们采用 jina-embeddings-v5-text-small 模型。这是一款处于行业领先水平的多语言模型，在文本表征方面树立了行业基准。我们选择该模型，是因为它确立了当下高性能嵌入的标杆标准。通过将 Jina v5 卓越的精准度与Elasticsearch原生量化技术相结合，我们能够展示一种既具备高效计算能力，又在检索质量上毫不妥协的搜索架构。

我们设置了一个具有双重映射的索引。我们同时将相同的文本导入两个不同的字段：

1. content.raw 类型：flat。这会使 Elasticsearch 对全部 Float32 向量执行暴力扫描。通过这种扫描，系统会返回完全匹配的结果，并将用于我们的基线。
2. content 类型为semantic_text。默认情况下使用 HNSW + 更好的二进制量化 (BBQ)。这是用于近似匹配的标准、优化生产设置。

Recall@10 测试

在我们的评估指标中，我们使用了 Recall@10。

我们随机挑选了 50 部电影，并对这两个字段运行了相同的查询。

• 如果精确（扁平式）搜索显示前 10 个近邻是 ID [1, 2, 3……10]，
• 而近似 (HNSW) 搜索结果显示的是 ID [1，2，3... 9，99]。
• 我们正确地找到了前 10 个中的 9 个。得分为 0.9。

这是我们使用的映射：

# The "Control Group": Forces exact brute-force scan
"raw": {
    "type": "semantic_text",
    "inference_id": ".jina-embeddings-v5-text-small",
    "index_options": {
        "dense_vector": {
            "type": "flat"
        }
    }
}

结果：成功的“平直线”

我们进行了一次规模测试，重新加载了整个数据集，并对 1,000 到 40,000 个文档的索引规模进行了测试。

召回率得分情况如下：

结果非常稳定。即使我们扩大了搜索范围，近似搜索也能在 99% 的情况下与暴力精确搜索相匹配。

为什么它如此有效？

您可能会认为将向量压缩成二进制值会对准确性的影响更大。不这样做的原因在于 Elasticsearch 处理检索的方式。

目前大多数嵌入模型输出的是 Float32 向量，这些向量很大。为了提高搜索效率，Elasticsearch 对高维向量使用量化技术。具体来说，自 9.2 版起，它默认使用BBQ。

BBQ 采用重新打分机制：

1. 遍历：搜索引擎使用压缩（量化）向量来快速遍历 HNSW 图表。由于向量较小，它可以高效地进行过度采样，收集更大的候选文档列表（例如，前 100 个大致相似的文档），而不会影响性能。
2. 重新评分：一旦有了这些候选文件，它就会只检索这几份文件的全精度值，以计算出最终的精确排名。

这样就能两全其美，既能以量化的速度完成繁重的工作，又能以浮点运算的精度完成最终排序。

我们能做得更好吗？

值得注意的是，我们在这里看到的结果是使用默认设置和随机抽样数据得出的。可以将其视为高性能的起点。尽管 Jina v5 性能卓越，但这些召回率分数并非适用于所有数据集的“万能保障”。每个数据集都有其独特之处，虽然您肯定可以进一步调整优化以挖掘出更多性能潜力，但您始终应基于自身特定数据进行基准测试，以明确性能上限所在。

结论

这是一次规模非常小的测试。不过，本次测试的重点并非专门评估嵌入模型或 BBQ 的性能，而是要展示如何通过极简的设置轻松衡量数据集的召回率。

如果您想用自己的数据运行此测试，可以点击此处查看笔记本，亲自试试。

该扩展以开源项目的形式在此处提供。

Gemini CLI 是什么？如何安装？

Gemini CLI 是一个开源的 AI 智能体，它可将 Google 的 Gemini 模型直接引入命令行。它允许开发人员从终端与 AI 进行交互，以执行诸如生成代码、编辑文件、运行 shell 命令和从网上检索信息等任务。

与典型的聊天界面不同，Gemini CLI 可与您的本地开发环境集成，这意味着它可以直接在终端内理解项目上下文、修改文件、运行构建或测试，以及自动化工作流。这对于想要在不离开命令行工作流的情况下进行 AI 辅助编码和自动化的开发人员、网站可靠性工程师 (SREs) 和工程师来说非常有用。

Gemini CLI 可通过多个软件包管理器安装。最常用的方法是通过 npm 安装：

npm install -g @google/gemini-cli

如要了解其他安装选项，请参阅官方安装页面。

安装完成后，运行以下命令启动 CLI：

gemini

您会看到一个屏幕，如图 1 所示：

配置 Elasticsearch

我们需要运行一个 Elasticsearch 实例。如要使用模型上下文协议 (MCP) 服务器，您还需要安装 Kibana 9.3+。如要使用下面描述的 Elasticsearch 查询语言 (ES|QL) 技能 (esql)，则不需要 Kibana。

您可以在 Elastic Cloud 上激活免费试用版，或使用 start-local 脚本在本地安装：

curl -fsSL https://elastic.co/start-local | sh

这将在您的计算机上安装 Elasticsearch 和 Kibana，并生成一个用于配置 Gemini CLI 的 API 密钥。

API 密钥将显示为上一条命令的输出，并存储在 .env 文件中，该文件位于 elastic-start-local 文件夹。

如果您使用的是本地部署的 Elasticsearch（例如使用 start-local），并且您想将 Elastic Agent Builder 与 MCP 一起使用，那么您还需要连接一个大型语言模型 (LLM)。您可以阅读此文档页面以了解不同的选项。

如果您使用的是 Elastic Cloud（或无服务器架构），那么您已经预先建立了 LLM 连接。

安装 Elasticsearch 扩展

您可以使用以下命令为 Gemini CLI 安装 Elasticsearch 扩展：

gemini extensions install https://github.com/elastic/gemini-cli-elasticsearch

您可以通过打开 Gemini 并执行以下命令来检查扩展程序是否已成功安装：

/extensions list

您应该看到 Elasticsearch 扩展可用。

如要使用 MCP 集成，您需要安装 Elasticsearch 9.3 或更高版本。您需要从 Kibana 获取您的 MCP 服务器 URL：

• 从智能体处获取 MCP 服务器 URL > 查看所有工具 > 管理 MCP > 复制 MCP 服务器 URL。
• URL 将如下所示：https://your-kibana-instance/api/agent_builder/mcp

您需要 Elasticsearch 终端 URL。这通常显示在 Kibana Elasticsearch 页面的顶部。如果您使用 start-local 运行 Elasticsearch，那么您已经在 start-local.env 文件的ES_LOCAL_URL 密钥中拥有了终端。

您还需要一个 API 密钥。如果您使用 start-local 运行 Elasticsearch，那么您已经在 start-local .env 文件中拥有了 ES_LOCAL_API_KEY。否则，您可以使用 Kibana 界面创建 API 密钥，详见此处：

• 在 Kibana 中：Stack Management > Security > API 密钥 > 创建 API 密钥。
• 我们建议仅设置 API 密钥的读取权限，并启用 feature_agentBuilder.read 权限，详见此处。
• 复制已编码的 API 密钥值。

在您的 shell 中设置所需的环境变量：

export ELASTIC_URL="your-elasticsearch-url"
export ELASTIC_MCP_URL="your-elasticsearch-mcp-url"
export ELASTIC_API_KEY="your-encoded-api-key"

安装示例数据集

您可以安装 Kibana 提供的电子商务订单数据集。它包含一个名为 kibana_sample_data_ecommerce 的单个索引，其中包含来自一家电子商务网站的 4675 个订单的信息。对于每笔订单，我们都有以下信息：

• 客户信息（姓名、ID 号码、出生日期、电子邮件等）。
• 订单日期。
• 订单编号。
• 产品（包含价格、数量、ID、类别、折扣和其他详情的所有产品列表）
• SKU。
• 总价（不含税，含税）。
• 总数量。
• 地理信息（城市、国家、洲、位置、地区）。

如要安装示例数据，请在 Kibana 中打开集成页面（在顶部搜索栏中搜索“集成”），然后安装示例数据。更多详情请参阅此处的文档。

本文旨在展示如何轻松配置 Gemini CLI 以连接到 Elasticsearch 并与 kibana_sample_data_ecommerce 索引交互。

如何使用 Elasticsearch MCP（模型上下文协议）

您可以在 Gemini 中使用以下命令检查连接：

/mcp list

您应该会看到 elastic-agent-builder 已启用，如图 2 所示：

Elasticsearch 提供了一组默认工具。请参阅此处的描述。

使用这些工具，您可以与 Elasticsearch 进行交互，提出类似以下的问题：

• Give me the list of all the indexes available in Elasticsearch.
• How many customers are based in the USA in the kibana_sample_data_ecommerce index of Elasticsearch?

根据问题的不同，Gemini 会使用一个或多个可用工具来尝试回答问题。

/elastic 命令

在 Gemini CLI 的 Elasticsearch 扩展中，我们还添加了 /elastic 命令。

如果执行 /help 命令，您将看到所有可用的 /elastic 选项（图 3）：

这些命令在您想直接执行 elastic-agent-builder MCP 服务器的特定工具时会很有用。例如，使用以下命令可以获取 kibana_sample_data_ecommerce 的映射：

/elastic:get-mapping kibana_sample_data_ecommerce

这些命令本质上是执行特定工具的快捷方式，而不是依赖 Gemini 模型来确定应该调用哪个工具。

如何使用 Elasticsearch 的技能？

该扩展还附带了 ES|QL 的代理技能，ES|QL 是 Elasticsearch 中提供的 Elasticsearch 查询语言。Agent Skills 是一种开放格式，为 AI 编码智能体（如 Gemini CLI）提供特定任务的自定义指令。它们使用一种称为渐进式披露的概念，即在系统初始提示中只添加对技能的简要说明。当您要求智能体执行任务时，比如查询 Elasticsearch，它会将请求与相关技能匹配，并动态加载详细说明。这是一种高效管理词元预算的方法，同时为 AI 提供所需的准确上下文。

esql技能旨在让 Gemini CLI 直接针对集群编写和执行 ES|QL 查询。ES|QL 是一种功能强大的管道化查询语言，能非常直观地进行数据探索、日志分析和聚合。启用该技能后，您无需查找 ES|QL 语法；只需用自然语言向 Gemini CLI 提出有关数据的问题，智能体会处理剩下的问题。

执行操作是通过在终端中运行简单的 curl 命令来完成的。之所以能做到这一点，是因为 Elasticsearch 提供了一套丰富的 REST API，可轻松用于将系统集成到任何架构中。

esql 技能的功能：

• 发现索引和模式：智能体可以使用该技能的内置工具列出可用索引并获取字段映射。例如，在为电子商务数据集编写查询之前，智能体可以在 kibana_sample_data_ecommerce 上运行模式检查，以了解可用的字段，如 taxful_total_price 或 category。
• 无缝自然语言翻译：该技能不仅仅为智能体提供了一个简单的参考手册；它还提供了一个专门的指南，用于解读用户意图。当您用自然语言输入请求（如“按服务分组显示平均响应时间”）时，智能体会使用技能捆绑的模式匹配功能，将您的文字立即转换为正确的 ES|QL 聚合、筛选条件和命令。
• 自我纠正：如果查询失败（例如由于类型不匹配或语法错误），该技能会返回生成的查询以及确切的 Elasticsearch 错误信息，使智能体能够立即修复查询并再次尝试，而无需您进行干预。

由于 esql 技能也作为工具在 elastic-agent-builder MCP 服务器中可用，我们需要暂时禁用该服务器。您可以使用以下命令禁用它：

/mcp disable elastic-agent-builder

然后，您只需在 Gemini CLI 中输入类似这样的提示：

Find the top 5 product categories by total sales revenue in the kibana_sample_data_ecommerce index

代理将：

• 认识到 esql 技能的必要性。
• 检查 kibana_sample_data_ecommerce 的模式。
• 构建一个 ES|QL 查询，比如：FROM kibana_sample_data_ecommerce | STATS total_revenue = SUM(taxful_total_price) BY category.keyword | SORT total_revenue DESC | LIMIT 5。
• 针对 Elasticsearch API 执行查询。
• 直接在终端中向您展示最终答案。

在这里，我们分享了一个 Gemini 对先前提示的响应示例：

───────────────────────────────────────────────────────────
> Find the top 5 product categories by total sales revenue in the kibana_sample_data_ecommerce index   ───────────────────────────────────────────────────────────
✓  Activate Skill "esql": Interact with Elasticsearch using ES|QL and curl. Use when querying, managing indices,  …
Skill esql activated. Resources loaded from /home/user/.gemini/extensions/elasticsearch/skills/esql: 
Showing up to 200 items (files + folders).                                                                     /home/user/.gemini/extensions/elasticsearch/skills/esql/                                                            ├───SKILL.md 
└───references/
├───esql-reference.md 
├───generation-tips.md 
└───query-patterns.md

✦ I will start by exploring the mapping of the kibana_sample_data_ecommerce index to identify the fields for product category and sales revenue. Then, I will construct and execute an ES|QL query to determine the top 5 product categories by total sales revenue.

✓  Shell curl -s "${ELASTIC_URL%/}/kibana_sample_data_ecommerce/_mapping" -H "Authorization: ApiKey $(printenv ELAS…                                                                                                                       {  
   "kibana_sample_data_ecommerce": { 
     "mappings": { 
       "properties": {
         "category": { 
           "type": "text", 
           "fields": {
             "keyword": {
               "type": "keyword"
             }
           }
         }, 
         "currency": {
           "type": "keyword"
         }, 

✦ Okay, I have the mapping. The category is products.category.keyword and sales revenue is taxful_total_price. I'll now execute the ES|QL query to get the top 5 categories by revenue.

✓  Shell curl -s -X POST "${ELASTIC_URL%/}/_query" \  -H "Authorization: ApiKey $(printenv ELASTIC_API_KEY)" \  -H …
{ 
   "took": 62,
   "is_partial": false, 
   "completion_time_in_millis": 1772805644164,
   "documents_found": 4675,
   "values_loaded": 12084, 
   "start_time_in_millis": 1772805644102, 
   "expiration_time_in_millis": 1773237644087,  
   "columns": [ 
     { 
       "name": "total_revenue",    
       "type": "double"  
     }, 
     {   
       "name": "products.category.keyword",

✦ The query for top 5 product categories by revenue was successful. I'll format the returned JSON values into a   user-friendly list.

 ✓  Shell 
                             
 Top 5 product categories by total sales revenue: 
 1. Men's Clothing: 149393.91
 2. Women's Clothing: 135099.91
 3. Women's Shoes: 105479.17
 4. Men's Shoes: 91797.92
 5. Women's Accessories: 60830.31 

✦ I've found the answer; now I'll format it for clarity.

 ✓  Shell 

 Here are the top 5 product categories by total sales revenue:                                                        
                                                                      
 | Rank | Category              | Total Revenue | 
 |------|-----------------------|---------------| 
 | 1    | Men's Clothing        | 149,393.91    |
 | 2    | Women's Clothing      | 135,099.91    |
 | 3    | Women's Shoes         | 105,479.17    |
 | 4    | Men's Shoes           | 91,797.92     | 
 | 5    | Women's Accessories   | 60,830.31     | 

✦ I've formatted and presented the answer. I'm finished.
 ───────────────────────────────────────────────────────────

值得注意的是，Gemini 模型如何通过显示其遵循的所有步骤来生成最终响应。在这里，您可以清楚地看到技能对模型推理过程的影响。当模型第一次意识到需要使用某项技能或执行 shell 命令时，它会采用人机协同的方式请求权限。

通过处理模式发现、查询生成和执行的繁重工作，esql 技能可以让您完全专注于答案，而不是获得答案的机制。您将获得所需的数据，格式正确且直接存储在终端中，无需写一行语法或切换到其他应用。

结论

在本文中，我们介绍了我们最近发布的适用于 Gemini CLI 的 Elasticsearch 扩展。此扩展让您可以使用 Gemini 和 Elastic Agent Builder 提供的 Elasticsearch MCP 服务器（从 9.3.0 版本开始提供）以及 /elastic 命令与您的 Elasticsearch 实例进行交互。

此外，该扩展还包含一项 esql 技能，可以将用户的自然语言请求转换为 ES|QL 查询。这种技能在无法使用 MCP 服务器时特别有用，因为底层通信是由在终端中执行的简单 curl 命令驱动的。Elasticsearch 提供了一套丰富的 REST API，可以轻松集成到任何项目中。这在开发智能体 AI 应用时尤为有用。

有关 Gemini CLI 扩展的更多信息，请访问此处的项目库。

这就是为什么我们要开源 Elastic Agent Skills，即 Elasticsearch、Kibana、Elastic Observability 和 Elastic Security 方面的原生平台专业知识。您可以把它们添加到您已经使用的智能体运行时，把您的智能体从那种只会猜大量语法的“通才”提升成为一个具有专业知识的智能体，比如能像 Elastic 自己的工程团队一样使用许多架构标准。最初的技术预览版本侧重于与 Elastic Cloud Serverless 具有最大兼容性的技能，但后续版本将迅速发展，以包含对旧堆栈版本的更好支持。

此外，Elastic 正在从两头解决这个问题。对于 Elastic 平台上的智能体，Elastic Agent Builder（现已正式发布）允许您创建和交互那些继承了您的数据访问控制的 AI 智能体，使用内置的搜索和分析工具，并结合上下文协同仪表板、警报和调查开展工作。我们正在努力确保在 Elastic 平台上提供卓越的智能体体验。但并非每个智能体都与 Elastic 兼容。您的团队可能已经在使用 Cursor、Claude Code 或其他运行时，这些智能体也需要正确理解 Elastic。这时 Agent Skills 就派上用场了。

智能体在专业平台上为何面临重重困难

大语言模型 (LLM) 是非常强大的通才。由于其训练数据包含丰富的示例，它们可以编写 Python 代码、解释 Kubernetes 清单，并重构 React 组件。但是，当涉及到平台特定的工作时，例如涉及专有查询语言、深度 API 接口和特定领域的最佳实践，它们的不足之处是可以预见的。

对于 Elasticsearch 来说，差距具体体现出来：

• Elasticsearch 查询语言 (ES|QL) 是一个新领域。LLM 主要使用 SQL 进行训练，但 ES|QL 是一种管道化查询语言，具有不同的语法、不同的函数和不同的语义。智能体经常编写看似合理但无法解析的查询。它们会混淆 WHERE 和 | WHERE，编造不存在的函数，并完全忽略了基于管道的组合模型。
• API 接口表面范围广且具有专业深度。Elasticsearch、Kibana 和 Elastic Security 在搜索、摄取、告警、检测规则、案例管理、仪表板等多个领域有数百个 API。一个只配备一般训练数据的智能体必须猜测要调用哪个终端、请求正文是什么样子，以及如何处理响应。它经常会猜错，削弱了人们对它的信任。
• 最佳实践不在训练数据中。何时应该使用 semantic_text 而不是自定义嵌入管道？如何构建 10GB CSV 的摄取管道？MITRE ATT&CK 技术的正确检测规则语法是什么？通用智能体在默认情况下不会加载经过整理、结构可靠的 Elastic 特定知识。它们需要查找这些知识，即使找到了，原始文档也并不总是包含熟练从业人员所具备的判断和最佳实践。

结果就是，开发人员花在修复智能体输出上的时间比他们自己编写代码所需的时间还多。这不是任何人愿意接受的体验。

代理技能：Platform 知识，专为代理人员量身定制

Agent Skills 是包含指令、脚本和参考资料的独立目录，智能体运行时可以动态加载这些目录。当技能处于活动状态时，智能体可在正确的时间获得正确的上下文：查询语法、API 模式、验证逻辑、实例，因此它可以在第一次尝试时正确完成任务。

每个技能都遵循开放的 agentskills.io 规范：一个文件夹中包含一个 SKILL.md 文件，其中包含元数据和结构化说明。无专有格式，无锁定。技能可在智能体运行时中使用，包括 Cursor、Claude Code、GitHub Copilot、Windsurf、Gemini CLI、Cline 和 Codex 等。

v0.1.0 初始版本包含什么内容

Elastic Stack 的第一组技能跨越五个领域：

• 与 Elasticsearch API 交互（搜索、索引、集群管理）
• 构建和管理 Kibana 内容，例如仪表板、警报、连接器等
• Elastic Observability 的领域专业知识
• Elastic Security 的领域专业知识
• 在 Agent Builder 中创建高效的智能体

技能可组合

技能不是单一的。它们采用的是模块化设计。您的智能体仅加载与当前任务相关的技能。正在编写 ES|QL 查询？ES|QL 技能将激活。需要从这些结果构建仪表板？仪表板技能将激活。要评估应用程序的健康状况？服务健康技能将发挥作用。要调查安全警报？随着调查的深入，分流技能将逐步衔接到案件管理和响应技能。

这种可组合性意味着您不需要一个庞大的、试图涵盖一切的单一提示。每种技能都完全符合其领域所需的语境，不多也不少。

适用于构建搜索和 AI 应用程序的开发人员

如果您正在将数据加载到 Elasticsearch、编写查询或迁移索引，技能可以缩短生成代码、遇到错误和搜索文档以查明问题所在的周期。

让您的智能体加载一个 CSV 文件，它会使用流式摄取工具来处理背压并从数据中推断映射。它不是那种手动编写的 _bulk 循环，不会在处理第一个大文件时就耗尽内存。让它使用 ES|QL 进行查询，它会发现您的实际索引名称和字段模式，然后编写具有正确语法、适当聚合和版本感知功能选择的有效管道查询，而不是需要三轮调试的 SQL 风格猜测。让它跨集群重新索引，它会遵循完整的操作工作流：用显式映射创建目的地，调整吞吐量设置，异步运行作业，完成后恢复生产设置，而不是简单地调用 _reindex，跳过有经验的操作员会遵循的一半步骤。

您得到的不是一个给您一个似是而非的起点，让您不得不去解决的智能体，而是一个编码了操作规范，让输出真正有效的智能体。

使用 Elastic Agent Skills 的影响示例

面向安全团队

安全团队每天都重复相同的操作工作流：对警报进行分流、调整检测规则、管理案例。Agent Skills 可对程序知识进行编码，让您的 AI 智能体能够正确执行这些工作流，以正确的顺序调用正确的 API，并使用正确的字段名称。如需通过实践操作指南，在不离开 IDE 的情况下从零开始构建一个完整的 Elastic Security 环境，请参阅 从您的 AI 智能体开始使用 Elastic Security。

面向可观测与运维团队

针对 Elastic Observability 的全新 Agent Skills 可以减轻对复杂系统进行检测、管理 SLO、筛选复杂数据以及评估服务健康状况的操作难度。将 Elastic 原生专业知识直接嵌入 AI 智能体中，可以让团队通过简单的自然语言执行复杂的可观测工作流。这使 SRE 和运营团队能够更快地解决事件，并更轻松地维护可靠的系统。阅读这篇博文了解详情。

开源、开放规范、社区驱动

我们根据 Apache 2.0 许可协议发布 Agent Skills，因为我们认为智能体知识应该是开放的。技能所遵循的 agentskills.io 规范是一项开放标准，不是 Elastic 的专有格式。我们希望这些技能成为社区共同努力的成果，而不是封闭的生态系统。

大局的一部分

Agent Skills 是旨在使 Elasticsearch 成为最适合智能体使用的数据平台的更广泛计划的一部分。对于在 Elasticsearch 平台上运行的智能体，Agent Builder 还能更进一步，继承数据的访问控制和权限，提供用于搜索和分析的内置和自定义工具，并让用户在仪表板、警报和调查的上下文中与智能体进行交互。最后，Agent Builder 即将推出对技能的支持，允许开发者灵活地利用 Elastic Agent Skills 以及来自任何其他来源的技能，在 Elasticsearch 平台上实现安全、上下文增强的聊天和自动化。

对于部署在其他地方的智能体，我们正投入努力，建设开放的生态系统：

• 模型上下文协议 (MCP) 服务器扩展：扩展 Agent Builder 中的 MCP 终端，在当前搜索、ES|QL 和索引操作之外提供更多工具。
• 身份验证改进：使代理能够更轻松地安全连接，目标是消除手动复制粘贴 API 密钥的操作。
• LLM 可读文档：发布 llms.txt 和 AGENTS.md 文件，让智能体能够自行发现和理解 Elastic API。
• 用于智能体工作流的命令行接口 (CLI)：命令行工具，使连接管理和常见操作更适合智能体使用。

技能是您今天能使用的层面。其余的功能即将到来。

开始使用

开始之前：AI 编码智能体使用真实凭证、真实 shell 访问权限进行操作，通常还拥有运行它们的用户的全部权限。当这些智能体用于安全工作流时，风险会更高：您相当于是将检测逻辑、响应操作和敏感遥测数据的访问权限交给了一个自动化系统。每个组织的风险状况都是不同的。在启用 AI 驱动的安全工作流之前，请评估智能体可以访问哪些数据、可以采取哪些操作以及如果出现意外行为会如何。

将 Elastic Agent Skills 安装到您的智能体运行时：

npx skills add elastic/agent-skills

这会自动检测您已安装的智能体运行时，并将技能放置在正确的配置目录中。之后，您的智能体会自动获取这些技能。

您还可以直接浏览技能目录，然后将技能文件夹复制到智能体的配置目录中，从而手动安装各个技能。

还没有 Elasticsearch 集群吗？开始免费试用 Elastic Cloud。您只需一分钟就能获得一个完全配置的环境。

探索项目：

• Agent Skills 存储库
• agentskills.io 规格
• Elasticsearch 文档
• Elastic Cloud 免费试用

正如我们在之前的帖子中看到的，函数调用提供的一致性不仅仅是一种不错的优化手段，它还是至关重要的。一旦我们从评估循环中消除了结构性错误，标准场景（例如第 4 层数据集中的场景）的结果便有了显著提升。

然而，有一个显而易见的问题需要回答：

当情况变得真正复杂时，这种方法还管用吗？

现实中的实体解析很少因简单情况而失败。当名称跨越语言、文化、书写系统、时间段和组织边界时，它就会失效。当人们用头衔而非名字称呼，公司更改名称，音译不一致，且尝试仅凭上下文（而非拼写）提及现实实体时，这种方法就失败了。

因此，在本系列的最后一篇文章中，我们对该系统进行了所谓的终极挑战。

是什么让这成为终极挑战？

在之前的评估中，我们使用越来越复杂的数据集对该系统进行了测试。当我们达到上一篇帖子中所讨论的第 4 层时，我们已经要应对昵称、头衔、多语言名称以及语义引用的混合情况了。这些测试表明，架构本身是可靠的，但可靠性问题，特别是不规范的 JSON 格式抑制了召回率。

有了函数调用，我们终于有了稳定的基础。这让我们有机会提出一个更有趣的问题：

一个统一的管道能否同时处理多种不同类型的实体解析问题？

终极挑战数据集的设计正是为了推动这一层面的发展。

该数据集并未专注于单一难点（如昵称或音译），而是结合了 50 多种不同的挑战类型，包括：

• 文化命名惯例。
• 基于标题的引用。
• 业务关系和历史名称变更。
• 多语言和跨脚本提及。
• 复合挑战融合了上述多种元素。

关键是，这并不是针对某个狭窄的用例进行优化。这是要测试当规则从一个实体变更到另一个实体时，设计模式是否成立。

数据集概览

终极挑战数据集包含：

• 50个实体，涵盖个人、组织和机构。
• 约 60 篇文章，结构和语言复杂程度各不相同。
• 51 个不同的挑战类别，大致分为以下几类：
  • 文化命名惯例。
  • 标题和专业背景。
  • 商业关系与组织关系。
  • 多语言和音译挑战。
  • 综合场景和边缘情况场景。

在本系列的前几篇文章中，我们看到使用生成式 AI (GenAI) 创建数据集可谓喜忧参半。如果没有它，要收集足够多、足够多样化的测试数据将极其困难。但如果不加以控制，这种模式往往会让事情变得过于简单。

例如，在早期的一次生成过程中，我们发现模型将“俄罗斯总统”等短语作为弗拉基米尔·普京 (Vladimir Putin) 的明确别名。这在今天看来可能是合理的，但却违背了测试上下文解析的目的。如果文章讨论的是 20 世纪 90 年代的俄罗斯，会发生什么情况？系统应根据上下文推断出正确的实体，而不是依赖于硬编码的别名。

因此，我们特意设计了这个数据集，以避免使用捷径。当系统能够推断出含义时，则不明确列出别名。描述性短语没有预先链接到实体。正确的匹配通常取决于文章层面的上下文，而不仅仅是局部文本。

重要说明：尽管我们展示了系统在各种场景下的能力，但这仍是一个具有教育意义的原型。处理真实世界受制裁实体监控的生产系统需要额外的验证、合规性检查、审计跟踪，以及针对敏感用例的专门处理。

为什么这些场景很难应对

在本系列的第一篇文章中，我们介绍了一个简单但含义模糊的示例：“新的 Swift 更新来了！”挑战在于，“Swift”可以根据上下文解析为现实世界中的多个实体。这个示例反映了一个更广泛的事实：自然语言本质上是模棱两可的。

因此，实体解析不仅仅是字符串匹配的问题。人们经常依赖共享知识、文化规范和情境背景来解析引用，我们甚至很少注意到我们正在这样做。

考虑以下几个常见案例：

• 没有地缘政治和时间背景，“总统”这样的头衔就毫无意义。
• 公司名称可能指母公司、子公司或之前的品牌，具体取决于文章的撰写时间。
• 一个人的名字可能会以不同的顺序、书写系统或音译方式出现，这取决于语言和文化。
• 同一个短语在不同的语境中可以合法地指代不同的实体，系统必须能够像接受匹配短语一样自信地拒绝匹配短语。

没有单一的规则集可以高效地处理所有这些情况。这就是为什么这款原型如此激进地将关注点分开：

• Elasticsearch 高效而透明地缩小了候选空间。
• LLM 仅在需要判断且必须自行解释的情况下使用。
• 检索和推理仍然是两个不同步骤。

随着挑战类型多样性的增加，这种区分变得更加重要。

系统如何在无特殊处理的情况下应对多样性

这次评估最有趣的结果之一是没有改变的内容：

• 我们没有针对日语名字添加特殊逻辑。
• 我们没有为阿拉伯语父名添加自定义规则。
• 我们没有添加历史公司名称的硬编码映射。

相反，该系统依赖于系列早期引入的相同核心要素：

• 为语义搜索编制索引的上下文丰富实体。
• Elasticsearch 中的混合检索（精确检索、别名检索和语义检索）。
• 一组数量少且定义明确的候选匹配项。
• 受函数调用和最小模式约束的 LLM 判断。

这表明系统的灵活性来自表征和架构，而非不断增长的规则集合。

当系统成功时，是因为检索到了正确的候选对象，且 LLM 有足够的上下文来解释为什么某个引用会（或不会）映射到某个特定实体。

结果：它的表现如何？

在最终挑战数据集上，系统得出了以下总体结果：

• 精度：约 91%
• 召回： ~86%
• F1 分数：约 89%
• LLM 接受率：约 72%

在各类挑战中的表现

按挑战类型细分结果可以揭示优势和局限性：

在以下领域的表现最为突出（100% F1 分数）：

• 跨脚本匹配（西里尔字母、韩文、中文企业实体）。
• 希伯来语场景（父名、职业头衔、宗教头衔、音译）。
• 企业层级（航空航天、多元化制造、多部门公司）。
• 专业头衔（学术、军事、政治、宗教）。
• 涉及多种书写系统的综合日语场景。

表现优异（80–99% F1 分数）包括：

• 国际政治人物（98%）。
• 历史名称变更 (90%)。
• 复杂的业务层次结构（89%）。
• 日本公司名称（93%）。
• 跨脚本音译（86%）。
• 阿拉伯语父名（86%）。

更具挑战性的领域包括：

• 高级音译（中文、韩文）：0% F1。
• 某些日本场景（敬语、姓名顺序、书写系统变化）：~67% F1。
• 一些阿拉伯语场景（公司名称、机构引用）：约 40% F1。

这里重要的是为什么系统在这些情况下会遇到困难。这些失败并非由于整体方法的崩溃，而是由于特定组件的局限性，尤其是在某些多语言场景中用于语义搜索的密集向量模型。

由于检索和判断是完全分离的，因此提高性能无需重写系统。更换功能更强大的多语言嵌入模型、丰富实体上下文或改进检索策略，都能在不改变核心架构的情况下改善这些类别的结果。

从架构的角度来看，这才是真正的成功指标。

这告诉我们关于设计的启示

回顾整个系列，有几个模式尤为突出：

• 准备工作比巧妙搭配更重要。预先为实体添加上下文信息可以显著减少以后可能出现的歧义。
• LLM 作为评判者最有价值，而非检索者。让他们解释为什么某个匹配是有意义的，比要求他们进行搜索要有效得多。
• 可靠性确保准确性。函数调用不仅清理了 JSON，还释放了检索步骤中已存在的召回能力。
• 通用性胜过专业化。少量经过精心挑选的抽象概念无需自定义逻辑即可处理数十种挑战类型。

这就是为什么原型有意采用 Elasticsearch 原生架构，并在 LLM 的使用上有意采取保守策略的原因。目标不是取代搜索；而是在意义至关重要的情况下，使搜索变得可解释。

总结

最终的挑战并非追求完美的指标，而是回答一个更根本的问题：

一个透明、搜索优先、LLM 辅助的架构能否处理现实世界中的实体歧义，而不陷入规则或黑箱的情况？

对于这个具有教育意义的原型，答案是肯定的，但需要明确注意生产环境的强化、合规性、监控以及数据质量等方面的问题。如果您正在构建的系统需要说明为什么要进行实体匹配，那么这种模式值得认真考虑。我希望这个系列能告诉人们，实体解析其实并不神秘。只要合理地进行关注点分离，就可以对问题进行推理、评估和优化。

这项工作还提出了一种更广泛的架构模式。由此出现了经典检索增强生成 (RAG) 的一次细微但重要的演变。我们没有让检索直接为生成提供信息，而是引入了一个明确的评估步骤。首先使用 LLM 对检索到的候选结果进行判断和合理性检查，只有通过审核的结果才允许用于增强生成。您可以将其视为“生成增强型检索增强生成与评估”，或者简称为“GARAGE”，毕竟谁不喜欢一个好听的缩写词呢。

还有哪些其他用例可以从这种模式中受益？需要信任、透明和可辩护推理的系统是当然的候选者。未来在这一领域的工作应该会像我们在这里看到的结果一样引人注目，我很期待看到社区接下来会有什么新的发展。

下一步：亲自试用

想看看终极挑战的实际操作吗？请查看终极挑战笔记本，它通过实际实现、详细解释和动手示例，提供了完整的实践指南。

完整的实体解析管道展示了生产使用所需的核心概念和架构。您可以将其用作构建系统的基础，这些系统可以监测新闻文章、跟踪实体提及情况，并回答有关哪些实体出现在哪些文章中的问题，同时还能保持透明度和可解释性。

在 HNSW 中，搜索过程是通过在图中迭代扩展候选节点来推进的，同时维护一个迄今为止已发现的、规模受限的最近邻节点集合。每次扩展都会带来一定的影响（包括向量运算、磁盘随机寻址等操作），并且随着搜索的推进，这种影响所带来的边际效益往往会逐渐降低。

优化 HNSW 图遍历的一种方法是，当发现新真实邻近节点的边际概率不再提升时，立即停止搜索。因此，在 Elasticsearch 9.2 中，我们引入了新提前终止机制。当连续访问图节点的次数达到固定数量，但仍无法提供足够的新最近邻节点时，搜索过程就会停止。

本文将指导您了解我们如何改进 HNSW 中提到的提前终止机制，使其更适合不同的数据集和数据分布。

HNSW 中的提前终止

在 HNSW 中，搜索过程是通过在近邻图中迭代扩展候选节点来推进的，同时持续维护一个迄今已发现、规模受限的最近邻节点集合，直至搜索遍历完整个图，或者满足某些提前终止条件为止。

因此，提前终止不一定总是性能优化，它本身就是搜索算法不可或缺的组成部分。决定终止搜索的时机，直接决定了效率与召回率之间的权衡关系。在 Elasticsearch 中，针对 HNSW 图的查询已内置多种提前终止机制：

• 访问节点的最大数量固定不变。
• 已达到固定的超时时间。

这些规则虽然简单且可预测，但在很大程度上与搜索的实际操作无关。此外，它们主要用于确保最终用户在合理的时间内完成查询。

在上一篇博文中，我们介绍了 HNSW 冗余的概念。简而言之，当 HNSW 持续评估那些无法带来更多最近邻节点的新候选节点时，就会产生冗余计算。

耐心：衡量进展而非过程

“耐心”这一概念将提前终止的判定标准重新定义为“衡量进展而非过程”。

而不是问：

“我们走了多少步？”

新的问题变成了：

"在我们彻底丧失希望之前，我们能够接受浪费多少计算量？"

在 HNSW 搜索过程中，早期探索阶段通常能显著提升前 k 个候选结果集的质量。在 HNSW 图探索的初始阶段，随着算法不断发现与查询向量距离更近的邻近节点，邻近节点集会持续更新。随着搜索逐步收敛，这类质量提升会逐渐减少。基于“耐心”机制的终止策略会监测这一变化模式，当持续一段时间内未再出现显著改进时，即终止搜索过程。

在实际操作中，我们在遍历 HNSW 图的过程中，每跳转到一个候选节点时，都会计算队列饱和度。该指标用于衡量在访问最近一个图节点期间，未发生变化的最近邻节点所占的百分比（或者说，是上一轮迭代中引入的新邻节点数量的倒数）。若连续多次迭代中，这一比率持续过高，我们便会停止对图的遍历。

从概念层面来看，“耐心”机制将HNSW搜索视为一个收益递减的过程。当搜索收益趋于平稳时，继续遍历图结构所带来的增益将微乎其微。

这种框架之所以强大，是因为它将终止与可观察到的结果直接联系起来，而不是与任意的固定限制联系起来。

采用这种智能提前终止技术的优势在于，HNSW 图探索过程在保持近乎完美的相对召回率的同时，往往会访问更少数量的图节点。

为了直观地说明这一点，我们可以在几个数据集（FinancialQA 和 Quora）和模型（JinaV3 和 E5-small）上绘制基于耐心的提前终止（标注为 et=static）与默认 HNSW 行为（标注为 et=no）的对比图。

静态阈值和 HNSW 动态

实际上，Elasticsearch 使用静态阈值来实现这一点。其中一个阈值指的是饱和阈值，即我们认为次优的饱和度比率。另一个阈值指的是，在队列达到次优饱和度的情况下，我们允许访问的连续图节点数，即耐心阈值。

当我们在 Elasticsearch 9.2 中引入这种提前终止策略时，我们决定选择保守的默认设置，以便在延迟和内存消耗方面仍能达到效果的同时，尽可能多地让系统召回。因此，我们将饱和阈值设为 100%，耐心阈值设为 KNN 查询中 num_candidates 的（有界）30%。

在很多情况中，这些设置能取得不错的效果；然而，对于请求相同数量邻节点的两个查询而言，它们的收敛行为可能存在极大差异。有些查询会遇到密集的局部邻域，能迅速达到饱和状态；而有些查询则必须遍历漫长且稀疏的路径，才能找到具有竞争力的候选节点。事实证明，后一种情况最难以有效处理。

因此，我们有时会发现：

• 简单查询的过度探索。
• 复杂查询的过早终止。

因此，我们认为固定阈值编码了关于收敛的全局假设，而我们可以使 HNSW 更好地适应不同的动态。

实现 HNSW 的提前终止自适应

自适应提前终止从另一个角度解决了这个问题。该算法不是强制执行预定义的停止阈值，而是从搜索动态本身推断何时停止。

因此，我们不再比较连续两个候选节点间的队列饱和度比率，而是决定引入即时平滑发现率 $d_{q,i}$（即最近一次访问 i 中，针对查询 q 新发现的邻近节点数量），同时结合图遍历过程中该发现率的滑动均值 $\mu_{q,i} $和标准差$\sigma_{q,i}$（采用韦尔福德算法计算）。这些关于发现率的统计量按每个查询独立计算，从而可根据不同查询的特性动态调整其“耐心”阈值。

先前静态设定的阈值将根据发现率统计数据实现自适应调整：饱和阈值调整为滚动均值加上标准差；同时，我们将耐心值设为与标准差呈反比变化的动态参数。

提前退出的规则保持不变；当瞬时发现率低于自适应饱和阈值时，即判定达到饱和状态。如果在连续访问的候选节点数量超过自适应耐心值所设定的次数后，饱和状态仍持续存在，则停止对图的遍历。

如此一来，我们实现了搜索行为不再依赖于 KNN 查询中的 num_candidates 参数（该参数可能始终被设定为固定值或保留默认值，而与提前终止机制无关），同时能够根据每个查询和向量分布进行动态适配。

在 FinancialQA 和 Quora 数据集上，采用自适应策略（标记为 et=adaptive）时，每个访问节点的召回率相较于静态策略（ et=static）和默认 HNSW 行为（et=no）均有显著提升。

在 Elasticsearch 9.3 中，HNSW 密集向量字段的自适应提前终止默认处于启用状态（最终可以通过相同的索引级别设置将其关闭）。

集成通过配置 Filebeat 输入来执行数据采集。为了从 HTTP API 采集数据，我们通常使用 HTTP JSON 输入。然而，即便是最基础的列表 API，在具体细节上也可能千差万别，而 HTTP JSON 输入采用 YAML 配置进行数据转换的模式，往往使所需的采集逻辑难以自然表达，有时甚至无法实现。

为此，我们引入了通用表达式语言 (CEL) 输入，让与 HTTP API 的交互更加灵活。CEL 是一种专为嵌入到应用中而设计的语言，适用于需要以快速、安全且可扩展的方式来表达条件和数据转换的场景。通过 CEL 输入，集成构建者只需编写一个表达式，即可读取设置、跟踪自身状态、发起请求、处理响应，并最终返回可直接摄取的事件。

本文将探讨 CEL 与其他编程语言的区别、我们针对 Filebeat 的 CEL 输入所进行的扩展，以及由此带来的数据采集逻辑表达灵活性与能力提升。

CEL 及其在输入中的工作方式

CEL 是一种表达式语言，它没有“语句”这一概念。在编写 CEL 时，您不是通过编写语句来指示它执行操作，而是通过编写表达式来定义要生成的值。每个 CEL 表达式都会计算出一个值，较小的表达式可以组合成更大的表达式，按照更复杂的规则生成结果。稍后，我们将了解如何通过表达式来实现其他语言中需要用语句来完成的逻辑。

CEL 有意设计为一种非图灵完备的语言，因此不支持无界循环。稍后，我们将介绍如何使用宏来处理列表和映射；正是通过禁止无界循环，CEL 能够保证每个表达式的执行时间可预测且有限。

CEL 输入需要配置一个 CEL 程序（即一个表达式）以及一些初始状态。这个初始状态会作为输入传递给程序。程序执行后会产生一个新的输出状态。如果输出状态中包含事件列表，这些事件会被提取出来并发布。输出状态的其余部分则作为下一次执行的输入。如果输出状态包含一个或多个事件，并且带有 want_more: true 标志，程序会立即再次执行；否则，它会在剩余的配置时间间隔内等待，然后才继续执行。下面是输入控制流的简化示意图：

只要输入还在运行，每次执行的输出都会作为下一次执行的输入。存储在 “cursor” 键下的数据会被保存到磁盘，并在输入重启后重新加载，但其余状态在重启后不会保留。

CEL 语言本身功能有限，且不会产生副作用，但它支持扩展。cel-go 实现为其添加了一些功能，例如可选语法和类型。Mito 库在 cel-go 的基础上进一步扩展，增加了发起 HTTP 请求等功能。CEL 输入使用的正是 Mito 提供的 CEL 版本。

与 Mito 合作

要使用 CEL 输入构建或调试集成，最关键的是理解：针对给定的输入状态，您的 CEL 程序会输出什么。在开发过程中，如果每次都要在完整的 Elastic Stack 环境中通过 CEL 输入来运行程序，会非常繁琐。为了更快地获得反馈，可以使用 Mito 的命令行工具，它允许您直接运行 CEL 程序，并查看它对给定输入产生的输出。

Mito 是用 Go 语言编写的，您可以通过以下命令安装：

go install github.com/elastic/mito/cmd/mito@latest

使用 Mito 运行 CEL 程序时，通常需要提供两个文件：一个是 JSON 文件，包含初始输入状态；另一个是 CEL 源文件，包含程序代码。

mito -data state.json src.cel

为了方便复制粘贴，本文示例采用单条命令的形式，利用 <(echo '...content...') 语法将每个文件的内容动态生成临时文件。在实际开发中，直接使用真实的文件会更方便。

从 GitHub 获取 issue 数据

以下示例是一个完整的 CEL 程序，用于从 GitHub API 获取 issue 数据。它的初始输入状态包含 API 端点的 URL 以及分页处理的相关信息。CEL 程序利用这些输入数据生成请求，然后解码响应，从中生成事件，并将这些事件作为输出状态的一部分返回。

mito -data <(echo '
  {
    "url": "https://api.github.com/repos/elastic/integrations/issues",
    "per_page": 3,
    "max_pages": 3
  }
') <(echo '
  int(state.?cursor.page.orValue(1)).as(page,
    (
      state.url + "?" + {
        "state": ["all"],
        "sort": ["created"],
        "direction": ["asc"],
        "per_page": [string(state.per_page)],
        "page": [string(page)],
      }.format_query()
    ).as(full_url,
      request("GET", full_url).with({
        "Header": {
          "Accept": ["application/vnd.github+json"],
          "X-GitHub-Api-Version": ["2022-11-28"],
        }
      }).do_request().as(resp,
        resp.Body.decode_json().as(data,
          state.with({
            "events": data.map(i, {
              "html_url": i.html_url,
              "title": i.title,
              "created_at": i.created_at,
            }),
            "cursor": { "page": page + 1 },
            "want_more": size(data) == state.per_page && page < state.max_pages,
          })
        )
      )
    )
  )
')

程序第一次执行会产生以下输出：

{
  "cursor": {
    "page": 2
  },
  "events": [
    {
      "created_at": "2018-09-14T09:47:35Z",
      "html_url": "https://github.com/elastic/integrations/issues/3250",
      "title": "Increase support of log formats in haproxy filebeat module"
    },
    {
      "created_at": "2019-02-06T12:37:37Z",
      "html_url": "https://github.com/elastic/integrations/issues/487",
      "title": "ETCD Metricbeat module needs polishing and grooming"
    },
    {
      "created_at": "2019-08-13T11:33:11Z",
      "html_url": "https://github.com/elastic/integrations/pull/1",
      "title": "Initial structure"
    }
  ],
  "max_pages": 3,
  "per_page": 3,
  "url": "https://api.github.com/repos/elastic/integrations/issues",
  "want_more": true
}

这些事件会被提取出来，并在 CEL 输入中发布，以便摄取。剩余的输出数据将作为输入状态传递给下一次 CEL 程序执行。

为了帮助理解这个 CEL 程序的工作原理，我们先看一些更简单的 CEL 示例，并深入讨论 CEL 输入的运行细节。

CEL 基础知识

CEL 语言中只有表达式，没有语句。每个 CEL 表达式成功执行后都会得到一个最终值。以下是一个最简单的 CEL 表达式示例及其输出：

mito <(echo '
  "hello" + " " + "world"
')

"hello world"

许多简单表达式都很直观。数学运算要求操作数类型相同（例如 int 与 int），因此请根据需要进行类型转换（此处是从 int 转换为 double）：

mito <(echo '
  double((1 + 2) * (3 + 4)) / 2.0
')

10.5

CEL 语言中没有变量，但您可以为表达式的结果命名，并借助 Mito 的 as 宏在更大的表达式中使用它。在此示例中，表达式 (1 + 1) 的值为 2，而 .as(n, ...) 会将该值命名为 n，以便在表达式 "one plus one is "+string(n) 中使用：

mito <(echo '
  (1 + 1).as(n, "one plus one is "+string(n))
')

"one plus one is 2"

还可以在映射中累积信息，并在表达式中稍后使用；下面的示例用 with 演示了这一点：

mito <(echo '
  { "key": "value" }.with({ "key2": "value2" }).as(data,
    {
      "data": data,
      "size": size(data),
    }
  )
')

{
  "data": {
    "key": "value",
    "key2": "value2"
  },
  "size": 2
}

我们再来看这个例子。注意嵌套部分 ({ "data": data, "size": size(data), })，它定义了最终值的结构。这是一个映射，包含 "data" 和 "size" 两个键。这些键的值依赖于 data，而它是由外层表达式定义的。从内向外阅读 CEL 表达式，有助于快速理解它们会返回什么。

CEL 没有 if 这样的控制流语句，但可以用三元运算符实现条件分支：

mito <(echo '
  1 + 1 < 12 ? "few" : "many"
')

"few"

由于 CEL 不是图灵完备语言，因此不支持无限循环和递归。这保证了执行时间可预测，并且与输入数据的大小和表达式的复杂度成正比。

虽然单个 CEL 表达式不能使用无限循环，但您可以用 map 这样的宏来处理列表和映射：

mito <(echo '
  [1, 2, 3].map(x, x * 2)
')

[2, 4, 6]

本节介绍了以下内容：

• 字符串、数字、列表和映射。
• 字符串连接。
• 数学运算。
• 类型转换。
• 条件语句。
• 命名子表达式。
• 处理集合。

接下来，我们将学习如何发出 HTTP 请求。

请求

Mito 为 CEL 扩展了发起 HTTP 请求的能力：

mito <(echo '
  get("https://example.com").as(resp, string(resp.Body))
')

"..."

请求可以在执行前明确构造，这样就可以使用不同的 HTTP 方法，并添加请求头和请求体。

在这个示例中，我们借助 format_query 构建 URL，向请求添加一个请求头，并使用 decode_json 解析响应体。当传入 -log_requests 选项时，Mito 会以 JSON 格式记录每个请求和响应的详细信息。

mito -log_requests <(echo '
  request("GET",
    "https://postman-echo.com/get?" + {
        "q": ["query value"]
     }.format_query()
  ).with({
    "Header": { "Accept": ["application/json"] }
  }).do_request().as(resp, {
    "status": resp.StatusCode,
    "data": resp.Body.decode_json(),
  })
')

{"time":"...","level":"INFO","msg":"HTTP request",...}
{"time":"...","level":"INFO","msg":"HTTP response",...}
{
  "data": {
    "args": {
      "q": "query value"
    },
    "headers": {
      "accept": "application/json",
      "accept-encoding": "gzip, br",
      "host": "postman-echo.com",
      "user-agent": "Go-http-client/2.0",
      "x-forwarded-proto": "https"
    },
    "url": "https://postman-echo.com/get?q=query+value"
  },
  "status": 200
}

管理状态和评估

我们已经介绍了如何发出请求，以及生成期望输出状态所需的 CEL 基础知识，接下来就来仔细看看输出状态应该包含哪些内容，以及这些内容如何帮助我们引导后续的处理流程。

集成的 CEL 程序需要确保其输出状态能够作为下一次执行的输入。配置设定了初始状态，输出中应保留这些状态值，并根据需要更新。一个简单的做法是使用 state.with({ ... })，在原有状态映射的基础上合并覆盖。小型程序常见的一种模式是将整个程序包裹在 state.with() 中，这样在成功、错误等输出数据的分支中，就无需重复处理状态传递逻辑。

如果某些状态值不是在初始输入状态中硬编码，而是在执行过程中动态初始化，那么程序在设置初始值之前需要先检查是否已存在值。这正是可选语法和类型支持能够发挥作用的场景。在映射键的字段名前面加上问号，访问就变为可选：可能得到值，也可能得不到，但后续仍可以进行可选访问，并且在无值时可以方便地提供默认值：

mito -data <(echo '{}') <(echo '
  int(state.?counter.orValue(0)).as(counter,
    state.with({
      "counter": counter + 1,
      "want_more": counter + 1 < 3,
    })
  )
')

{ "counter": 1, "want_more": true }
{ "counter": 2, "want_more": true }
{ "counter": 3, "want_more": false }

在这个例子中，从 state 读取的计数器值需要转换为 int，因为状态中的所有数字都按照 JSON 和 JavaScript Number 类型的惯例序列化为浮点数。另外需要注意的是，Mito 会响应 "want_more": true，但在 CEL 输入中运行时，只有当输出中同时包含事件时，才会重复执行。

由 CEL 输入运行的 CEL 程序必须在输出映射中包含一个 "events" 键。它的值可以是事件映射的列表、空列表，或单个事件映射。单个事件映射通常用于表示错误。该事件会被输入发布，其值也会被记录到日志；如果设置了 error.message，该值还会用于更新集成在 Fleet 中的健康状态。如果程序生成的是单个非错误事件，最好将其包装在列表中。

回顾一下我们之前的 GitHub issues 程序的输出：

{
  "url": "https://api.github.com/repos/elastic/integrations/issues",
  "per_page": 3,
  "max_pages": 3,
  "cursor": {
    "page": 2
  },
  "events": [
    { ... },
    { ... },
    { ... }
  ],
  "want_more": true
}

该程序通过以下方式有效地管理了其状态：

• 在 url、per_page 和 max_pages 字段中沿用了初始状态的值。
• 在 cursor.page 中添加了需要在重启后持久化的状态。
• 返回准备发布在 events 列表中的事件。
• 请求立即与 want_more: true 进行重新评估。

现在您已经理解了可选访问和状态管理，以及 CEL 基础知识和 HTTP 请求，完整的 GitHub issues 示例程序应该已经比较容易阅读了。不妨用 Mito 运行一下，并尝试做些修改。

回顾与资源

本文介绍了 CEL 语言，以及它如何在 Mito 库中得到扩展以用于 CEL 输入。通过一个从 GitHub API 获取 issue 数据的示例程序，我们展示了 CEL 的灵活性，并逐一解析了理解该程序所需的全部细节：访问初始状态中的配置、与 HTTP API 交互、返回待导入的事件，以及为后续执行管理状态。

要深入学习并使用 CEL 输入构建集成，以下资源值得探索：

• CEL 输入 － Filebeat 文档
• Mito 文档
• 通用表达式语言 － cel.dev 网站
• 创建集成 － Elastic 文档

对于使用 CEL 输入构建集成，最有价值的资源或许是现有 Elastic 集成中的 CEL 代码，这些代码可以在 GitHub 上找到：

cel.yml.hbs Elastic 集成存储库中的 cel.yml.hbs 文件 － GitHub。

1. 新的 Swift 更新来了！开发人员迫不及待地想要尝试新功能。
2. 新的 Swift 更新来了！新专辑将于下个月发布。

有了这些增加的上下文，我们应该能够将名称“Swift”解析到正确的实体。

在上一篇文章中，我们设置了观察清单，并用额外的上下文丰富了实体信息。看上面的例子，我们需要在清单中至少包含以下两个实体：Taylor Swift 和 Swift 编程语言。我们还介绍了如何从文本中提取实体提及。这两个例子都能提取“Swift”。有了这些要素——丰富的观察清单和提取出的实体——我们终于可以介绍本次的主角了：实体匹配。

请记住：这是一个教育原型，旨在教授实体匹配概念。生产系统可能会使用不同的大型语言模型 (LLM)、自定义匹配规则、专门的判断管道或结合多种匹配策略的集成方法。

问题：为何匹配如此困难

人类语言是一种非凡的事物。它最有趣的特性之一是其无限的创造力。我们可以生成并理解无数的新句子。那么，在实体解析中完全精确的匹配极为罕见，这还奇怪吗？作者们在可能的情况下都力求创新。如果每次提到某个实体时，我们都必须书写和阅读完整名称，那将会变得非常乏味。因此，尽管精确匹配很简单，但现实情况是我们需要一种更复杂的方法来进行实体解析：这种方法必须足够强大，以处理人类作者无限创造力中的至少一部分挑战。这就是我们将问题分解为两个步骤的原因：使用 Elasticsearch 大规模检索可能的候选实体，然后使用 LLM 来判断这些候选实体是否真正指向同一个现实世界中的实体。

解决方案：三步匹配与透明的 LLM 判断

我们正处于使用计算机方式的范式转变之中。正如互联网的兴起将我们从本地计算带入全球互联网络一样，生成式 AI (GenAI) 正在从根本上改变内容、代码和信息的创建方式。事实上，伴随本系列的教育型原型几乎完全是作者通过精心设计提示词，使用 LLM “vibe coded” 出来的。这并不是说 LLM 已经或将要达到人类语言所固有的那种生产力，但这确实意味着我们现在拥有一个强大的资源来帮助进行实体解析。

我们在使用生成式 AI 时的一个常见模式是检索增强生成 (RAG)。在这里，检索检索意味着检索实体候选（而不是生成答案），LLM 严格用于匹配评估和解释。虽然我们可以要求 LLM 帮助我们进行端到端的实体解析，但这在时间和金钱上都是一种成本高昂的方法。RAG 通过使用更高效的方式为 LLM 提供上下文，从而帮助 LLM 完成工作，进而使 LLM 能够有效地协助实体解析。

对于 RAG 中的检索部分，我们再次求助于 Elasticsearch。我们首先使用精确匹配、别名匹配以及结合了关键词和语义搜索的混合搜索来寻找潜在的匹配项。一旦找到这些潜在匹配项，我们就将它们发送给 LLM 进行判断。LLM 充当最终的匹配评估器。我们还让 LLM 解释其推理过程，这是与其他实体解析系统的一个重要区别。没有这些解释，实体解析就是一个黑匣子；有了它们，我们可以亲眼看到为什么某个匹配是合理的。

关键概念：三步匹配、混合搜索和透明 LLM 判断

什么是三步匹配？在项目开始时，我们假设语义搜索将是系统的一个关键部分，但并非每个匹配都需要如此复杂的搜索。为了有效地找到匹配项，我们采用了渐进式的方法。首先，我们使用关键词搜索检查完全精确的匹配。如果找到这样的匹配，我们的工作就完成了，可以继续下一个。如果精确匹配失败，我们转向别名匹配。为简化起见，在原型中，别名匹配也是使用关键词进行精确匹配完成的。在生产环境中，您可能会通过标准化、音译规则、模糊匹配或精心管理的别名表来扩展这一步。如果在前两步之后仍未找到潜在的匹配项，那么是时候通过 Elasticsearch 的混合搜索（结合了倒数排序融合）来引入语义搜索了。

什么是混合搜索？在 Elasticsearch 中，我们可以使用语义搜索来找到将上下文考虑在内的有意义的匹配。Elasticsearch 广泛用于向量搜索和混合检索。语义相似性对于理解含义非常强大，但它不能替代结构化过滤（例如，按时间范围、位置或标识符过滤），并且在存在精确匹配时通常是不必要的。Elasticsearch 以其词汇搜索而闻名，这在不适合语义搜索的任务中表现出色。为了充分利用这两种方法，我们在单个混合查询中将词汇搜索与语义搜索结合使用。然后，我们使用 RRF 合并结果，以找到最可能的匹配项。在原型中，排名前两位的结果成为可以发送给 LLM 进行判断的潜在匹配项。

为什么需要 LLM 判断？LLM 的判断和解释使得我们的系统能够透明地处理歧义和上下文。这对于像“the president”这样可能根据上下文指代多个实体的情况至关重要，但它也使昵称和文化差异等情况在系统中能够很好地处理。最后，当我们考虑关键任务，例如识别制裁名单中的实体时，我们需要知道匹配被接受的原因，才能信任该系统。至关重要的是，LLM 并不搜索整个语料库；它只评估 Elasticsearch 返回的那一小部分候选集。

实际结果：通过 LLM 推理进行匹配

任何自然语言处理任务的一个主要挑战是创建一份黄金文档，一份告诉我们预期结果是什么的“答案”。没有它，几乎不可能判断一个系统在某个任务上表现如何，但创建这样一份文档可能是一个费力且费时的过程。对于实体解析原型，我们再次求助于生成式 AI 来帮助建立我们可以用来测试的数据。

我们首先定义了几种挑战类型，例如昵称和音译，然后要求 LLM 创建一个分层的数据集集合，这些数据集将逐渐变大，对系统来说也更具挑战性。数据集的创建并不像人们希望的那样简单。LLM 有一种强烈的“作弊”倾向，使得获取正确答案变得过于容易。例如，其中一种挑战类型侧重于语义上下文。这种类型包括将“Russian author”解读为“Leo Tolstoy”。LLM 错误地将“Russian author”作为“Leo Tolstoy”的一个别名，这就没有必要通过混合搜索来寻找匹配项了。

在进行了几次重构以修复此类问题后，我们有了五个可供使用的数据集层级。第 1-4 层规模逐渐增大，包含的挑战类型也更多。第 5 层是“终极挑战”数据集，由所有挑战类型中最棘手的例子组成。所有测试数据都可以在全面评估目录中找到。

为了评估我们基于提示的实体解析方法，我们将注意力集中在第 4 层数据集上。一个重要的说明是，评估是作为受控实验进行的，这样我们可以专注于实体匹配的质量。观察清单数据预先丰富了上下文，并且实体是提前从文章中提取出来的。这确保了评估的重点是匹配而非提取的准确性。这将匹配质量孤立出来；端到端的性能还将额外取决于提取的召回率和丰富数据的质量。

评估数据集

第 4 层评估数据集对系统的能力提供了一个全面的测试：[1]

• 观察清单实体：跨不同类型（人物、组织、地点）的 66 个实体。
• 测试文章：69 篇涵盖现实世界实体解析场景的文章。
• 预期匹配：所有文章中预期的 206 个实体匹配。
• 挑战类型：测试实体解析各个方面的 15 种不同挑战类型。

数据集中包含的挑战类型有：

• 昵称：“Bob Smith” → “Robert Smith”（七篇文章）。
• 头衔和尊称： “Dr. Sarah Williams” → “Sarah Williams”（五篇文章）。
• 语义上下文：“Russian author” → “Leo Tolstoy”（八篇文章）。
• 多语言名字：处理不同书写系统中的名称（六篇文章）。
• 商业实体： 公司名称变体（七篇文章）。
• 高管引用：“Microsoft CEO”→“Satya Nadella”（五篇文章）。
• 政治领导人：基于头衔的引用（五篇文章）。
• 名称首字母：“J.Smith” → “John Smith”（三篇文章）。
• 名称顺序变体：不同的名称顺序惯例（三篇文章）。
• 名称截断：部分名称匹配（三篇文章）。
• 名称拆分：名称在文本中拆分（三篇文章）。
• 缺少空格/连字符：格式变体（两篇文章）。
• 音译：跨书写系统的名称匹配（两篇文章）。
• 组合挑战：一篇文章中包含多个挑战（共六篇文章）。
• 复杂商业关系：分层商业关系（五篇文章）。

让我们看看基于提示的实体解析表现如何。

整体性能

结果显示，由 LLM 驱动的匹配评估前景广阔，但也揭示了一个显著的可靠性问题。因为每个候选对都必须由 LLM 进行评估，结构化输出的失败可能会抑制接受率和召回率，即使检索环节工作正常。

错误率问题

回顾一下，我们在原型中采取的第一步是使用 Elasticsearch 创建潜在的匹配对。每个这样的潜在匹配都需要由 LLM 进行评估。为了高效地处理所有这些匹配项，我们将 LLM 调用批量组合在一起。这降低了 API 成本和延迟，但也增加了在输出中得到格式错误 JSON 的风险。随着批量大小的增加，JSON 变得更长、更复杂，使得 LLM 更有可能生成无效的 JSON。这就是 30% 错误率的来源。在评估中，我们每个请求使用 5 个匹配项的批量大小。即使采用这个保守的批量大小，我们仍然遇到 JSON 解析失败的情况，这显著地影响了评估结果。

下一步：优化 LLM 集成

现在，我们已经使用语义搜索和 LLM 判断匹配了实体，我们拥有了一个完整的实体解析管道。然而，这种方法引入了一种新的故障模式：当模型的判断正确，但其输出却不可用时。我们可以优化 LLM 集成以获得更好的可靠性和成本效益。在下一篇文章中，我们将探讨如何使用函数调用来实现结构化输出，这可以在减少错误和成本的同时，提供有保障的结构和类型安全。

亲自试用

想亲眼看看实体匹配是如何运作的吗？请查看实体匹配笔记本，它通过实际实现、详细解释和动手示例，提供了完整的实践指南。该笔记本精确地向您展示了如何使用三步搜索、带有 RRF 的混合搜索以及由 LLM 驱动的带推理的判断来匹配实体。

请记住：这是一个教育原型，旨在教授这些概念。在构建生产系统时，需要考虑额外的因素，如模型选择、成本优化、延迟要求、质量验证、错误处理和监控等，而这些在本学习重点的原型中并未涵盖。

备注

1. 这些数据集是合成的，专为教育目的设计；它们模拟了真实的挑战，但不代表任何单一的生产环境领域。

我们在 2000 万文档语料库上进行的基准测试显示，Elasticsearch 在过滤向量搜索方面的吞吐量比 OpenSearch 高达 8 倍，同时在我们测试的配置中也实现了更高的 Recall@100。上下文工程不仅仅依赖快速的向量检索。随着工作流的迭代，团队还需要强大的相关性控制（如混合搜索和过滤）、操作简便性和可预测的性能。但是，由于智能体通常会在每个请求中多次运行检索、推理、检索循环，因此检索延迟会成倍增加，所以这方面的改进会直接转化为更好的端到端响应能力和更低的成本。

对于上下文工程来说，检索不是一次性的步骤。智能体和应用程序会反复运行循环，例如检索→推理→检索，以完善查询、验证事实、组合基础上下文并完成任务。这种模式在智能体工作流和迭代检索增强生成 (RAG) 中很常见。由于每个用户请求可能会多次调用检索，这会增加响应延迟和/或增加基础设施成本。

为什么向量搜索性能至关重要？

想象一个购物助手回答以下问题：“我需要一个价格在 60 美元以下的随身背包，它可以容纳一台 15 英寸的笔记本电脑、防水，并且可以在周五之前送达。”

在生产环境中，助手很少只发出一个向量查询然后停止。它会运行一个检索循环以构建正确的上下文，并且每一步通常会受到过滤条件的限制，如可用性、地区、发货承诺、品牌规则和政策资格。

第 1 步：解读意图，并转化为约束条件。

智能体可将请求转化为结构化的过滤条件和语义查询，例如：

• 过滤条件：有现货，可配送至用户邮编，可在周五前送达，价格低于 60 美元，有效上架
• 向量查询：“随身背包15英寸笔记本电脑防水”

步骤 2：检索候选对象，然后进行细化。

它通常会重复检索，但会有所变化，以避免遗漏好的匹配结果：

• “旅行背包随身便携笔记本电脑保护套”
• “15 英寸防水通勤背包”
• “轻型机舱背包”

每个查询都使用相同的资格过滤条件，因为检索无关或不可用的项目会造成上下文的浪费。

步骤 3：展开以确认详细信息并降低风险。

代理随后再次检索以验证影响最终答案的关键属性：

• 材料与防水性表述
• 尺寸和笔记本隔层都适合
• 退货政策或保修限制
• 库存不足时的替代方案

这就是多步上下文工程：检索、推理、检索、组合。

延迟与召回为何对上下文工程至关重要

这些交互可能涉及每个用户会话中数十次过滤的检索调用。这使得每次调用的延迟成为端到端响应时间的直接倍增因素，而低召回率则迫使进行额外的重试或导致智能体错过符合条件的项目，导致答案质量下降。

要点：在上下文工程系统中，过滤近似最近邻 (ANN) 并非一次单一查找。由于这是在约束条件下的重复操作，因此即使大型语言模型 (LLM) 是最明显的组件，向量搜索性能也会立即体现在延迟、吞吐量和成本上。

基准测试

成果度

在图表 2 中，每个点代表一个测试配置。最佳结果出现在左上方，这意味着更高的召回率和更低的延迟。Elasticsearch 的结果始终比 OpenSearch 更接近左上角，表明在相同的工作负载配置下，Elasticsearch 具有更好的速度和准确率。

一些关键见解

• s_n_r_value: size_numCandidates_rescoreOversample 的简写（在这些测试中，k 和 numCandidates 设置为等于 numCandidates），例如，100_500_1 表示 size=100、numCandidates=500 和 k=500，重新评分过采样=1。
• 召回率：该配置的测量召回率@100
• 平均延迟（毫秒）：每次查询的平均端到端延迟
• 吞吐量：每秒查询次数
• 召回率 (%)：Elasticsearch 相较于 OpenSearch 的相对召回率提升 (Elasticsearch - OpenSearch) / OpenSearch
• 延迟 Xs：OpenSearch 平均延迟除以 Elasticsearch 平均延迟
• 吞吐量 Xs：Elasticsearch 吞吐量除以 OpenSearch 吞吐量

例如，在 100_9000_1 处，OpenSearch 每次检索平均为 687 毫秒， Elasticsearch 为 90 毫秒，而在 10 步检索循环中，等待时间约为 10 x (687 - 90) = 6 秒。

查看完整结果。

方法

我们使用 Python 发送查询并跟踪响应时间及其他统计数据，向引擎发送了以下查询。请记住，任何向量搜索引擎的性能取决于您如何调整其核心参数：考虑多少个候选项，重新评分的程度，以及返回多少上下文。这些设置直接影响召回率（找到正确答案的可能性）和延迟（获得结果的速度）。

在我们的基准测试中，我们使用了通常在智能体检索循环中调整的候选对象、重新评分和结果大小设置，并测量了 Elasticsearch 在该工作负载下的表现。然后我们以相同的设置运行了 OpenSearch 作为参考。

OpenSearch

GET /_search
{
  "query": {
    "knn": {
      "": {
        "vector": [...],
        "k": ,
        "method_parameters": {
          "ef_search": 
        },
        "rescore": {
          "oversample_factor": 
        },
        "filter": {
          
        }
      }
    }
  },
  "size": ,
  "_source": {
    "excludes": [
      ""
    ]
  }
}

• "size": <RESULT_SIZE>：返回给客户端的命中次数。在这个基准测试中，计算 Recall@100 的结果大小为 100。
• "k": <NUMBER_OF_CANDIDATES>：最近邻候选对象的数量。
• "ef_search": <NUMBER_OF_CANDIDATES>：要检查的向量数量。
• "oversample_factor": <OVERSAMPLE>：在重新评分之前检索了多少个候选向量。

Elasticsearch

GET /_search
{
  "query": {
    "knn": {
      "field": "",
      "query_vector": [...],
      "k": ,
      "num_candidates": ,
      "rescore_vector": {
        "oversample": 
      },
      "filter": {
        
      }
    }
  },
  "size": ,
  "_source": {
    "excludes": [
      ""
    ]
  }
}

• "size": <RESULT_SIZE>：返回给客户端的命中次数。在这个基准测试中，计算 Recall@100 的结果大小为 100。
• "k": <NUMBER_OF_CANDIDATES>：从每个分片返回的最近邻数量。
• "num_candidates": <NUMBER_OF_CANDIDATES>：进行 knn 搜索时每个分片要考虑的最近邻候选数目。
• "oversample": <OVERSAMPLE>：在重新评分之前检索了多少个候选向量。

示例

Knn 查询, (100_500_1)，将如下所示：

OpenSearch

GET search_catalog_128/_search
{
  "query": {
    "knn": {
      "search_catalog_embedding": {
        "vector": [...],
        "k": 500,
        "method_parameters": {
          "ef_search": 500
        },
        "rescore": {
          "oversample_factor": 1
        },
        "filter": {
          "term": {
            "valid": true
          }
        }
      }
    }
  },
  "size": 100,
  "_source": {
    "excludes": [
      "search_catalog_embedding"
    ]
  }
}

Elasticsearch

GET search_catalog_128/_search
{
  "query": {
    "knn": {
      "field": "search_catalog_embedding",
      "query_vector": [...],
      "k": 500,
      "num_candidates": 500,
      "rescore_vector": {
        "oversample": 1
      },
      "filter": {
        "term": {
          "valid": true
        }
      }
    }
  },
  "size": 100,
  "_source": {
    "excludes": [
      "search_catalog_embedding"
    ]
  }
}

完整配置、Terraform 脚本、Kubernetes 清单和基准测试代码均可在此存储库的 es-9.3-vs-os-3.5-vector-search 文件夹中找到。

集群设置

我们在六台 e2-standard-16 云服务器上运行了测试，每台服务器配备 16 个 vCPU 和 64 GB 内存。在每台服务器上，我们为每个运行搜索引擎节点的 Kubernetes pod 分配了 15 个 vCPU 和 56 GB RAM，其中 28 GB 保留给 JVM 堆。

这些集群运行 Elasticsearch 9.3.0 和 OpenSearch 3.5.0 (Lucene 10.3.2)。由于在此基准测试中两个系统使用相同的 Lucene 版本，我们观察到的吞吐量和延迟差异不能单独归因于 Lucene，而是反映了每个引擎如何集成和执行过滤后的 k 最近邻 (kNN) 检索和重新评分的差异。我们使用了一个单一索引，包含三个主分片和一个副本（因此总共 6 个分片，每个节点 1 个分片）。

我们还在同一区域使用了一台独立服务器运行基准客户端，并收集时序统计数据。

该数据集

对于这个基准测试，我们使用了一个大规模电子商务风格的目录嵌入数据集，包含 2000 万份文档，旨在反映实际的大规模筛选后向量检索的扩展能力。

每份文件代表一个目录项目，包括：

• 一种用于近似 kNN 检索的 128 维稠密向量嵌入。
• 结构化元数据字段用于筛选（例如，项目有效性和可用性，以及其他目录限制条件），从而支持常见的生产环境模式，即仅在符合条件的子集内检索最近邻。

我们之所以选择这个数据集，是因为它捕捉到了我们在生产中看到的智能体和 RAG 型系统所面临的核心性能挑战：仅有矢量相似性是不够的，检索经常受到筛选条件的限制，系统必须在这些限制条件下保持较高的召回率和较低的延迟。与较小的 QA 风格数据集相比，2000 万文档的语料库更能反映筛选后 ANN 系统在实践中面临的扩展和候选压力。

结论

在现代 AI 架构中，尤其是在那些围绕上下文工程构建的架构中，向量搜索速度并非一个微不足道的实现细节。它是一个倍增因素。当智能体和工作流迭代检索→推理→检索时，检索性能直接影响端到端延迟、吞吐量以及输入到模型中的上下文质量。

在我们的基准测试中，与 OpenSearch 相比，当 Elasticsearch 在正确性取决于检索正确文档而不仅仅是相似向量的情况下，始终能以更低的延迟提供更高的召回率。在受控数据集上，差异是显而易见的，而在生产中，这些收益会在大量检索调用中累积，从而提高响应速度、增加容量裕度并降低基础设施成本。

延展阅读

1. 什么是上下文工程？
2. 混合搜索和上下文工程的演进
3. 相关性在 AI 智能体的上下文工程中的影响

该系列包括两个型号：

• jina-embeddings-v5-text-small
• jina-embeddings-v5-text-nano

这些模型是创新的嵌入模型新训练方法的成功结果。它们的性能优于规模是其数倍的模型，节省了内存和计算资源，并更快地响应请求。

jina-embeddings-v5-text-small 模型拥有 6.77 亿个参数，支持 32,768 个令牌的输入上下文窗口，并默认生成 1,024 维的嵌入。

jina-embeddings-v5-text-nano 其大小约为同类产品的三分之一，拥有 2.39 亿个参数和 8,192 个令牌的输入上下文窗口，并生成 768 维的嵌入。

这两个模型在整体 MMTEB（多语言 MTEB）基准性能方面是同类中最好的。在参数量少于 5 亿的模型中，jina-embeddings-v5-text-nano 表现最佳，尽管其参数量不足 2.5 亿，而 jina-embeddings-v5-text-small 模型是参数量少于 7.5 亿的多语言嵌入模型中的领先者。

这些模型可通过 Elastic 推断服务 (EIS)、在线 API 获得，并支持本地托管。有关如何访问 jina-embeddings-v5-text 模型的说明，请参阅以下“入门”部分。

嵌入模型和语义索引显著提高了搜索算法的准确性，但在涉及语义相似性和意义提取的任务中也有各种其他用途，例如：

• 查找重复文本。
• 识别释义和翻译。
• 发现主题。
• 推荐引擎。
• 情感和意图分析。
• 垃圾邮件过滤。
• 还有更多。

功能

这个新型号系列具有多项旨在提高相关性和降低成本的功能。

任务优化

我们针对四种广泛的任务类型优化了 jina-embeddings-v5-text 模型：

针对一项任务进行优化通常意味着必须在另一项任务上做出妥协，因此大多数嵌入模型仅在某一种任务上具有竞争力。但 jina-embeddings-v5-text 模型能够通过训练特定任务的低秩适配 (LoRA) 适配器在所有四个领域实现专业化，而不会相互影响。

LoRA 适配器是一种用于 AI 模型的插件，它可以显著改变模型的行为，同时仅略微增加模型的总体大小。与为每个任务都配备一个拥有数亿参数的完整模型不同，jina-embeddings-v5-text 模型系列允许您仅使用一个带有紧凑型 LoRa 适配器的模型来完成每项任务。这节省了内存、存储空间和推理成本。

截断嵌入

我们使用套娃式表征学习对 jina-embeddings-v5-text 模型进行了训练，这种方法能让您在几乎不影响嵌入质量的情况下将其压缩到更小的尺寸。

默认情况下，jina-embeddings-v5-text-small 会生成 1024 维嵌入向量，每个向量由 16 位数字表示，使每个嵌入大小为 2KB。对于大量文档集合而言，这可能需要存储大量数据，而在充满嵌入向量的向量数据库中进行搜索，其复杂度与数据库的大小以及每个存储向量的维度数都成正比。

但您可以将嵌入的大小减半（丢弃 1,024 维度中的 512 维），这样占用的空间减半，而搜索速度将翻倍。这会对性能产生影响。丢弃信息会降低精确度。但如下图所示，即使去掉一半的嵌入，性能也只是略有下降：

只要您的嵌入至少有 256 维，精确度损失就会相当小。然而，如果低于这一水平，相关性和准确性就会迅速下降。

通过这种截断嵌入方法，用户可以在准确性和计算成本之间自行权衡。它为您提供了从搜索 AI 中大幅提高效率和节约成本的工具。

稳健量化

量化是另一种缩小嵌入尺寸的方法。量化不是丢弃嵌入中的部分数据，而是降低嵌入中数字的精度。jina-embeddings-v5-text 模型以 16 位数字生成嵌入，但我们可以对这些数字进行四舍五入，从而降低其精度和存储所需的位数。在最极端的情况下，我们可以将每个数字缩减为一位（0 或 1），将 jina-embeddings-v5-text 的默认 1024 维嵌入从 2 千字节压缩到 128 字节，仅通过二进制量化就实现了 94% 的压缩率。这与截断一样，能大幅节省内存和计算成本。然而，和截断一样，量化也会使嵌入的准确性降低。

我们已训练了 jina-embeddings-v5-text 模型，通过将精度损失降至最低，使这些模型与 Elasticsearch 的更优的二进制量化一起工作。对这些模型的二值化嵌入进行的基准测试表明，其性能几乎与未二值化的等效模型相当。请参阅技术报告，以获取有关二值化性能的详细消融研究。

多语言性能

许多嵌入模型是多语言的，因为它们已在包含大量语言的材料上进行了训练。但这并不意味着它们在所有支持的语言中都有同样出色的表现。

我们在 MMTEB 多语言基准测试中确定了 211 种语言，并将它们区分开来，以便能够逐个语言地将我们的模型与类似模型进行比较。下图以热力图的形式总结了我们的结果。每个补丁都是一种语言（通过 ISO-639 编码识别），颜色越绿，表明该模型的表现与同类模型的平均表现相比越好：

虽然不同语言的准确性各不相同，但 jina-embeddings-v5-text 模型在世界大多数语言中都处于领先或接近领先地位。

有关多语言性能的详细信息，请参阅 jina-embeddings-v5-text 技术报告。

Elastic 中的 Jina：用于搜索的最先进的原生 AI

借助 EIS 上的 jina-embeddings-v5-text 模型，您可以在 Elasticsearch 中原生运行高性能多语言嵌入模型，并享受完全托管、GPU 加速的推理服务，而无需配置或扩展基础设施。jina-embeddings-v5-text 模型通过采用最新的 AI 技术，以紧凑的多语言模型扩展了不断增长的 EIS 模型目录。这些模型在信息检索和标准数据分析基准方面拥有最先进的性能，并提供了无与伦比的全球多语言支持。

两种模型的大小相差很大，用户可以根据自己的应用需求和预算来选择最合适的模型。此外，jina-embeddings-v5-text 模型拥有强大的嵌入功能，即使截断为较小尺寸或量化为较低精度时仍能保持性能，从而为进一步节省存储和计算成本以及处理延迟提供了机会。

借助 jina-embeddings-v5-text 系列、Jina Reranker 以及 Elastic 的快速向量和 BM25 搜索，用户现在可以使用 Elastic 提供的端到端、最先进的混合搜索功能。当您需要最相关的结果时，无论是用于检索增强生成 (RAG) 管道、搜索应用程序还是数据分析，Elastic 与 Jina 搜索 AI 模型都能提供可靠且经济高效的优质服务。

开始使用

jina-embeddings-v5-text 模型已完全集成到 EIS 中，您可以在创建索引时将 type 字段设置为 semantic_text，并在 inference_id 字段中指定模型（jina-embeddings-v5-text-small 或jina-embeddings-v5-text-nano），如本示例所示：

PUT multilingual-semantic-index
{
  "mappings": {
    "properties": {
      "content": {
        "type": "semantic_text",
        "inference_id": ".jina-embeddings-v5-text-small"
      }
    }
  }
}

# Ingest data about France
POST multilingual-semantic-index/_doc
{
  "content": "The capital of France is Paris"}

GET multilingual-semantic-index/_search
{
  "query": {
    "semantic": {
      "field": "content",
      "query": "What is the French capital?"
    }
  }
}

Elasticsearch 在索引和检索过程中会自动选择合适的 LoRA 适配器。嵌入维度（请参阅上文“截断嵌入”部分）可以在创建自定义推理端点时设置。

有关使用 jina-embeddings-v5-text 模型的更多信息，请参阅 Elasticsearch 文档。

更多信息

要了解有关 jina-embeddings-v5-text 模型的更多信息，请阅读 Jina AI 博客上的发行说明和技术报告，其中包含有关性能和 Jina AI 创新的新训练程序的更详细技术信息。有关在本地下载和运行这些模型的信息，请访问 Hugging Face 上的jina-embeddings-v5-text 集合页面。

Jina AI 模型在 CC-BY-NC-4.0 许可证下可用，因此您可以免费下载并试用它们，但如需用于商业用途，请联系 Elastic 销售人员。

本文将介绍如何使用最低得分参数来提高语义搜索结果的精确度。如想测试本博客文章中提供的示例，请访问 相关 Jupyter 笔记本。

背景：精确率和召回率

在搜索相关性中，精确率和召回率是关键概念。强烈建议尚不熟悉这些内容的读者查阅相关资料。以下是摘要。

• 精确率：返回的搜索结果中与用户相关的比例。
• 召回率：搜索结果集中包含的语料库中所有相关文档的百分比。

或者换句话说，精确率只返回相关结果，而召回率则返回所有相关结果。可以想象，这些需求经常相互冲突。语义搜索往往具有很高的召回率，但在精确率方面可能会不理想。继续阅读，了解如何避免这种情况。

推出最低得分参数

min_score参数通过设定最低得分阈值提升检索精度，系统将自动过滤得分低于该阈值的匹配结果，从而精简结果集。以下是一个简单的示例：

GET search-movies/_search
{
  "retriever": {
    "linear": {
      "min_score": 4,
      "retrievers": [
        ...
      ]
    }
  }
}

得分归一化

设置最低得分阈值固然可行，但并非所有语义模型都能返回适用于静态阈值的分值。以 ELSER 为例，它所返回的分值是无界得分。有些密集模型得分是密集聚类的，只有在特定查询的背景下才有意义。

对于大多数语义搜索情况，我们建议在应用“min_score”之前使用归一化方法。归一化确保文档得分在规定区间内。Elasticsearch 检索器提供了两种此类归一化器，即“l2_norm”和“minmax”。最常用的是“minmax”，因为它简单易懂，在很多情况下都很有效。“minmax”的主要属性包括：

• 文档分数分布在 0 到 1 之间。
• 得分最高的文件总是记为 1 分。
• 得分最低的文件总是记为 0 分。
  • 这可能会使其不太适合关键字搜索。更多讨论请参见“混合搜索”部分。

以下是一个包含min_score规范化语义查询的示例。排名窗口参数已增加到 500，使系统能够返回从第 100 条开始的更长结果列表。

GET search-movies/_search
{
  "size": 100,
  "_source": [
    "title", "overview"
  ],
  "retriever": {
    "linear": {
      "rank_window_size": 500,
      "min_score": 0.25,
      "retrievers": [
        {
          "normalizer": "minmax",
          "retriever": {
            "standard": {
              "query": {
                "semantic": {
                  "field": "overview_vector",
                  "query": "superhero movie"
                }
              }
            }
          }
        }
      ]
    }
  }
}

当前参数已设置为高于生产环境的常规值，以便我们全面检验搜索结果质量并针对性优化输出。

使用线性检索器的混合搜索

对于混合搜索，最简单的方法是归一化所有分数，分配权重，并应用最低得分。请注意，通过选择总和为 1 的权重，可以将总分控制在 0-1 的范围内。这样使得最终得分易于解读，且便于调整 min_score。以下是一个示例：

GET search-movies/_search
{
  "size": 100,
  "_source": ["title", "overview","keywords"],
  "retriever": {
    "linear": {
      "rank_window_size": 500,
      "min_score": 0.25,
      "retrievers": [
        {
          "weight": 0.6,
          "normalizer": "minmax",
          "retriever": {
            "standard": {
              "query": {
                "semantic": {
                  "field": "overview_vector",
                  "query": "superhero movie"
                }
              }
            }
          }
        },
        {
          "weight": 0.4,
          "normalizer": "minmax",
          "retriever": {
            "standard": {
              "query": {
                "multi_match": {
                  "query": "superhero movie",
                  "fields": ["overview","keywords", "title"],
                  "type": "cross_fields",
                  "minimum_should_match": "2"
                }
              }
            }
          }
        }
      ]
    }
  }
}

使用 RRF 的混合搜索

使用 BM25 时，我们通常通过其他方式控制精度，例如使用AND 操作符或minimum_should_match 。此外，由单个、精确和罕见术语组成的查询自然会导致搜索结果较少，而且往往都是高度相关的结果。这就可能导致：

• 在 BM25 检索器中，排名靠后的结果即使绝对 BM25 分值接近头部结果，仍会被赋予较低的归一化分数。
• 将极低的 BM25 分值与语义分值相加，总分即可近似为语义分值。
• 缺少 BM25 分值参考可能导致 min_score threshold 丢弃该文档。

作为解决方案，我们可以改用倒数排序融合 (RRF) 来结合 BM25 和语义结果。该方法通过关注各结果集中的文档位置而非原始分值，巧妙规避了不同检索算法评分体系难以直接比较的技术难题。在这种情况下，min_score 仅应用于语义检索器。

GET search-movies/_search
{
  "_source": ["title", "overview","keywords"],
  "retriever": {
    "rrf": {
      "rank_window_size": 500,
      "retrievers": [
        {
          "linear": {
            "rank_window_size": 500,
            "min_score": 0.25,
            "retrievers": [
              {
                "normalizer": "minmax",
                "retriever": {
                  "standard": {
                    "query": {
                      "semantic": {
                        "field": "overview_vector",
                        "query": "superhero movie"
                      }
                    }
                  }
                }
              }
            ]
          }
        },
        {
          "standard": {
            "query": {
              "multi_match": {
                "query": "superhero movie",
                "fields": ["overview", "keywords","title"],
                "type": "cross_fields",
                "minimum_should_match": "2"
              }
            }
          }
        }
      ]
    }
  }
}

结论

通过采用 min_score，我们已验证可有效降低语义检索算法因高召回率导致的结果集中误报数量。要了解有关检索器的更多信息，请参阅本博文和Elasticsearch 文档。

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 is the Schema for the repoconfigs API
type RepoConfig struct {
	metav1.TypeMeta `json:",inline"`

	// metadata is a standard object metadata
	// +optional
	metav1.ObjectMeta `json:"metadata,omitempty,omitzero"`

	// spec defines the desired state of RepoConfig
	// +required
	Spec RepoConfigSpec `json:"spec"`

	// status defines the observed state of RepoConfig
	// +optional
	Status RepoConfigStatus `json:"status,omitempty,omitzero"`
}

这就是 RepoConfig 实例的样子：

apiVersion: workflows.elastic.co/v1
kind: RepoConfig
metadata:
  generation: 3
  name: elastic-test-repo
  namespace: dependency-management-operator
spec:
  owner: group:my-team
  renovate:
    config:
      resourceGroup: SMALL
      runFrequency: 4h
    enabled: true
  repository: elastic/test-repo

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

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

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

func (r *ParentReconciler) reconcileSubResources(ctx context.Context, req ctrl.Request, parent *workflowsv1.Parent) error {
	logger := logf.FromContext(ctx)
	logger.Info("Reconcile SubResources for Parent", "name", req.NamespacedName)
	wfSet := workflowsettings.WorkflowSettings{
		RunFrequency:   parent.Spec.RunFrequency,
		ResourceGroups: "parent",
	}

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

	cfMngr := resources.NewConfigMapManager(r.Client, r.Scheme, r.OperatorConfig.ParentNamespace)
	err := cfMngr.CreateOrUpdateSyncMutexConfigmap(ctx, fmt.Sprintf("%s%s", r.OperatorConfig.ResourcesPrefix, r.OperatorConfig.SyncMutexCfgMapName), strings.TrimPrefix(parent.Spec.Repository, "elastic/"), r.OperatorConfig.SemaphoreConcurrencyLimit)

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

	wfMngr := resources.NewArgoWorkflowManager(r.Client,
		r.Scheme,
		curateResourceName(
			strings.ReplaceAll(parent.Spec.Repository, "/", "-"),
		),
		parent.Namespace,
		"parent-workflow",
		false).
		WithOrganization(r.OperatorConfig.GitHubOrg).
		WithRepoName(parent.Spec.Repository).
		Init(true, true).
		WithPrefix(r.OperatorConfig.ResourcesPrefix).
		WithWfTemplateName(r.OperatorConfig.ParentWorkflowTemplate).
		WithResources(wfSet.GetResourceCategory()).
		WithSchedule(wfSet.GetCronSchedule()).
		WithImagePullSecrets([]corev1.LocalObjectReference{{
			Name: r.OperatorConfig.WorkflowImagePullSecrets,
		}}).
		AddArgument(true, true, "extra_cli_args").
		SetArgument(true, false, "extra_cli_args", "none").
		AddTemplate(resources.NewParentDAGTemplateInstance()).
		AddTemplate(resources.NewWorkflowsTemplateInstance("check-child-workflows", r.OperatorConfig.WorkflowImagePullPolicy, r.OperatorConfig.WorkflowNodeSelector)).
		AddTemplate(resources.NewWorkflowsTemplateInstance("security", r.OperatorConfig.WorkflowImagePullPolicy, r.OperatorConfig.WorkflowNodeSelector)).
		AddTemplate(resources.NewWorkflowsTemplateInstance("submit-child-workflow", r.OperatorConfig.WorkflowImagePullPolicy, r.OperatorConfig.WorkflowNodeSelector))
	wfMngr.OverWriteCommand("submit-child-workflow", r.OperatorConfig.ChildNamespace)
	wfMngr.OverwriteWfTemplateName("parent-wftmpl")
	wfMngr.AddSynchronization(fmt.Sprintf("%s%s", r.OperatorConfig.ResourcesPrefix, r.OperatorConfig.SyncMutexCfgMapName), "{{workflow.parameters.repo_name}}")
	err = wfMngr.CreateOrUpdateCronWorkflow(ctx)
	if err != nil {
		return fmt.Errorf("failed to create or update cron workflow: %w", err)
	}
	err = wfMngr.CreateOrUpdateWorkflowTemplate(ctx)
	if err != nil {
		return fmt.Errorf("failed to create or update workflow template: %w", err)
	}
	return nil

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

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

func (r *ChildReconciler) reconcileSubResources(ctx context.Context, req ctrl.Request, child *workflowsv1.Child) error {
	logger := logf.FromContext(ctx)
	logger.Info("Reconcile SubResources for Child", "name", req.NamespacedName)
	wfSet := workflowsettings.WorkflowSettings{
		ResourceGroups: child.Spec.ResourceCategory,
	}
	wfMngr := resources.NewArgoWorkflowManager(r.Client,
		r.Scheme,
		curateResourceName(
			strings.ReplaceAll(child.Spec.Repository, "/", "-"),
		),
		child.Namespace,
		"runner",
		true).
		Init(false, true). // only manage workflow template
		WithPrefix(r.OperatorConfig.ResourcesPrefix).
		WithSuffix("-child-wftmpl").
		WithRepoName(child.Spec.Repository).
		WithOrganization(r.OperatorConfig.GitHubOrg).
		WithResources(wfSet.GetResourceCategory()). // will override resources of presets if set
		WithImagePullSecrets([]corev1.LocalObjectReference{{
			Name: r.OperatorConfig.WorkflowImagePullSecrets,
		}}).
		AddTemplate(resources.NewWorkflowsTemplateInstance("runner", r.OperatorConfig.WorkflowImagePullPolicy, r.OperatorConfig.WorkflowNodeSelector)).
		AddArgument(false, true, "repo_full_name").
		AddArgument(false, true, "repo_name").
		AddArgument(false, true, "encrypted_token").
		AddArgument(false, true, "extra_cli_args")
	wfMngr.OverWriteCommand("runner", r.OperatorConfig.ChildNamespace)
	err := wfMngr.CreateOrUpdateWorkflowTemplate(ctx)
	if err != nil {
		return fmt.Errorf("failed to create or update workflow template: %w", err)
	}
	return nil
}

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

GitHub 事件网关 (Go)

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

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

• 验证传入的 GitHub Webhook 签名以确保安全。
• 将有效事件转发给 Argo Events EventSource，并附上所有相关标头和身份验证。
• 我们还在 EventSource 上配置了一个 authSecret，并在转发的请求中将其作为 Bearer 标头提供。
• 提供日志记录、指标和重试逻辑。

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

它确保某些 HTTP 属性存在：

// ValidateRequestMethod checks if the request method is POST.
func ValidateRequestMethod(r *http.Request) error {
	if r.Method != http.MethodPost {
		return fmt.Errorf("method not allowed, only POST is accepted")
	}
	return nil
}

// ValidateRequiredHeaders checks for required GitHub headers.
func ValidateRequiredHeaders(r *http.Request) error {
	eventType := r.Header.Get("X-GitHub-Event")
	deliveryID := r.Header.Get("X-GitHub-Delivery")
	signature := r.Header.Get("X-Hub-Signature-256")
	if eventType == "" || deliveryID == "" || signature == "" {
		return fmt.Errorf("missing required GitHub headers")
	}
	return nil
}

// ValidateUserAgent checks that the User-Agent header starts with GitHub-Hookshot/
func ValidateUserAgent(r *http.Request) error {
	userAgent := r.Header.Get("User-Agent")
	if !strings.HasPrefix(userAgent, "GitHub-Hookshot/") {
		return fmt.Errorf("invalid User-Agent")
	}
	return nil
}

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

// ValidateSignature verifies the GitHub webhook signature.
func ValidateSignature(r *http.Request, secret string) ([]byte, error) {
	payload, err := GitHub.ValidatePayload(r, []byte(secret))
	if err != nil {
		return nil, fmt.Errorf("invalid GitHub signature: %w", err)
	}
	return payload, nil
}

// ValidateAllowedOwner checks if the organization login is in the allowed organizations list.
func ValidateAllowedOwner(payload []byte, allowedGitHubOrganizations []string) (string, error) {
	var orgLogin string
	var payloadMap map[string]any
	if err := json.Unmarshal(payload, &payloadMap); err == nil {
		if orgObj, ok := payloadMap["organization"].(map[string]any); ok {
			if login, ok := orgObj["login"].(string); ok {
				orgLogin = login
			} else if name, ok := orgObj["name"].(string); ok {
				orgLogin = name
			}
		}
	}
	if !slices.Contains(allowedGitHubOrganizations, orgLogin) {
		return orgLogin, fmt.Errorf("organization login not allowed")
	}
	return orgLogin, nil
}

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

	// Map eventType to Argo `EventSource` path
	var endpoint string
	switch eventType {
	case "push":
		endpoint = "/push"
	case "issues":
		endpoint = "/issues"
	case "pull_request":
		endpoint = "/pull-requests"
	default:
		slog.Info("Ignoring unhandled event type", "event_type", eventType, "delivery_id", deliveryID)
		w.WriteHeader(http.StatusOK)
		_, _ = w.Write([]byte("ok"))
		return
	}
	forwardURL := h.config.ArgoEventSourceForwardURL + endpoint

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

apiVersion: argoproj.io/v1alpha1
kind: Sensor
metadata:
  name: {{ .Values.sensors.packageUpdateOnDefaultBranch.name }}
  namespace: {{ .Release.Namespace }}
spec:
  eventBusName: {{ .Values.eventBus.name }}

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

script: |
          local e = event
          if not e or not e.body or not e.body.repository then
            return false
          end

          -- e.g., "refs/heads/main"
          local ref = e.body.ref
          local default_branch = e.body.repository.default_branch
          if not ref or not default_branch then
            return false
          end

          local expected = "refs/heads/" .. default_branch
          if ref ~= expected then
            return false
          end

        {{- if .Values.sensors.packageUpdateOnDefaultBranch.packageFiles }}
          patterns = { {{- range $i, $f := .Values.sensors.packageUpdateOnDefaultBranch.packageFiles }}{{ if $i }}, {{ end }}"{{ $f }}"{{- end }} }
        {{- end }}

          local function anyMatch(path)
            if type(path) ~= "string" then return false end
            for _, pat in ipairs(patterns) do
              -- match filename at repo root, or anywhere under subdirs
              if path:match(pat) or path:match(".+/" .. pat) then
                return true
              end
            end
            return false
          end

          local function filesContainPackage(paths)
            if type(paths) ~= "table" then return false end
            for _, p in ipairs(paths) do
              if anyMatch(p) then return true end
            end
            return false
          end

          -- Inspect all commits (GitHub includes added/modified/removed lists)
          local commits = e.body.commits
          if type(commits) ~= "table" then
            -- Fallback: some payloads include only head_commit
            commits = {}
            if type(e.body.head_commit) == "table" then
              table.insert(commits, e.body.head_commit)
            end
          end

          for _, c in ipairs(commits) do
            if filesContainPackage(c.added) or filesContainPackage(c.modified) or filesContainPackage(c.removed) then
              return true
            end
          end

          return false

后台同步器 (Go)

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

repoMap := make(map[string]map[string]interface{})
			for i := range entities {
				entity := &entities[i]
				if entity.Spec.Type != "GitHub-repository" {
					continue
				}

				implRaw, err := json.Marshal(entity.Spec.Implementation)
				if err != nil {
					logger.Error("Failed to marshal implementation", "error", err)
					continue
				}

				var implMap map[string]interface{}
				err = json.Unmarshal(implRaw, &implMap)
				if err != nil {
					logger.Error("Failed to unmarshal implementation map", "error", err)
					continue
				}
				var repoName string
				if specMap, ok := implMap["spec"].(map[string]interface{}); ok {
					if repo, ok := specMap["repository"].(string); ok {
						repoName = repo
					}
				}
				if repoName == "" {
					continue
				}

				var workflowsRaw []byte
				if v, ok := implMap["spec"].(map[string]interface{}); ok {
					if r, ok := v["renovate"]; ok {
						workflowsRaw, _ = json.Marshal(r)
					} else {
						workflowsRaw = []byte(`{}`)
					}
				} else {
					workflowsRaw = []byte(`{}`)
				}

				var workflowsWithDefaults schema.WorkflowsMetadata
				err = json.Unmarshal(workflowsRaw, &rworkflowsWithDefaults)
				if err != nil {
					logger.Error("Failed to unmarshal workflows config", "error", err)
					continue
				}

				workflowsMap := map[string]interface{}{
					"enabled":        workflowsWithDefaults.Enabled,
					"require_pr":     workflowsWithDefaults.RequirePr,
					"resource_group": string(workflowsWithDefaults.ResourceGroup),
					"run_frequency":  string(workflowsWithDefaults.RunFrequency),
				}
				repoMap[repoName] = map[string]interface{}{
					"renovate": workflowsMap,
					"owner":    entity.Spec.Owner,
				}
			}
			logger.Info("Fetched GitHub Repository data from Backstage", "repository_count", len(repoMap), "status_code", resp.StatusCode)

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

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

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

自助服务配置

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

spec:
  renovate:
    enabled: true
    config:
      resourceGroup: LARGE      # SMALL | MEDIUM | LARGE  
      runFrequency: "0 */4 * * *"  # Every 4 hours

资源组根据存储库大小分配 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 的成本进行比较，我们的新设计在相同的扫描输出下要高效得多：

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

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

增强安全

• 临时 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 成本的参考。

在为高并发工作负载调优 Elasticsearch 时，标准方法是最大限度地增加 RAM，将工作文档集保存在内存中，以实现低搜索延迟。因此，best_compression 很少被考虑用于搜索工作负载，因为它主要被视为 Elastic Observability 和 Elastic Security 用例中优先考虑存储效率的节省存储措施。

在本博客中，我们证明当数据集大小显著超出操作系统页面缓存时，best_compression通过减少 I/O 瓶颈来提升搜索性能和资源效率。

设置

我们的用例是一个运行在 Elastic Cloud CPU 优化实例上的高并发搜索应用程序。

• 数据量：约 5 亿份文档
• 基础架构：6 个 Elastic Cloud（Elasticsearch 服务）实例（每个实例：1.76 TB 存储 | 60 GB 内存 | 31.9 个 vCPU）
• 内存与存储比率：约 5% 的总数据集可存储在 RAM 中

症状：高延迟

我们观察到，当当前请求数在 19:00 左右激增时，搜索延迟显著恶化。如图 1 和图 2 所示，尽管每个 Elasticsearch 实例的流量峰值约为每分钟 400 个请求，但平均查询服务时间仍恶化至超过 60 毫秒。

在完成初始连接处理后，CPU 使用率保持相对较低，表明计算并非瓶颈。

查询量与页面错误之间出现了强相关性。随着请求增加，我们观察到页面错误比例上升，峰值约为每分钟 40 万次。这表明活跃数据集无法完全放入页面缓存。

同时，JVM 堆使用率也显示正常且平稳。这排除了垃圾回收问题，并确认瓶颈在于 I/O。

诊断：I/O 瓶颈

系统存在 I/O 瓶颈。Elasticsearch 依赖操作系统页面缓存从内存提供索引数据。当索引过大而无法放入缓存时，查询会触发开销很大的磁盘读取。虽然典型的解决方案是水平扩展（添加节点/RAM），但我们希望先充分利用现有资源的效率改进。

解决方案

默认情况下，Elasticsearch 对其索引段使用 LZ4 压缩，在速度和大小之间取得平衡。我们假设，改用 best_compression （使用 zstd）会减少索引的大小。更小的占用空间使得更大比例的索引能够放入页面缓存，以微不足道的 CPU 增加（用于解压缩）换取磁盘 I/O 的减少。

为了启用 best_compression，我们使用索引设置 index.codec: best_compression 重新索引了数据。或者，也可以通过关闭索引、将索引编解码器重置为 best_compression，然后进行段合并，也可实现相同的结果。

POST my-index/_close
PUT my-index/_settings
{
    "codec": "best_compression"
}
  
POST my-index/_open  
POST my-index/_forcemerge?max_num_segments=1

结果

结果证实了我们的假设：存储效率的提高直接转化为搜索性能的大幅提升，而 CPU 利用率并未相应增加。

应用 best_compression 后，索引大小减少了约 25%。虽然低于在重复日志数据中观察到的减少幅度，但这 25% 的减少实际上将我们的页面缓存容量提升了相同的比例。

在下一次负载测试期间（从 17:00 开始），流量甚至更高，每个 Elasticsearch 节点的请求峰值达到每分钟 500 次。

尽管负载更高，但 CPU 利用率仍低于上一次运行。先前测试中较高的使用率可能是由于过多的页面错误处理和磁盘 I/O 管理开销所致。

至关重要的是，页面错误显著下降。即使在更高的吞吐量下，错误次数也稳定维持在每分钟低于 20 万次，而基准测试中的错误次数则超过 30 万次。

尽管页面错误结果仍然不太理想，但查询服务时间却减少了约 50%，即使在负载更重的情况下也保持在 30 毫秒以下。

结论：为搜索启用 best_compression

对于搜索用例中数据量超过可用物理内存的情况，best_compression 是一个强大的性能调优工具。

应对缓存未命中的常规解决方案是通过扩展来增加 RAM。然而，通过减少索引占用空间，我们实现了相同的目标：最大化页面缓存中的文档数量。我们的下一步是探索索引排序，以进一步优化存储并从现有资源中获得更多性能。

代理正凭借其提升效率和改善客户体验方面的潜力而日益受到重视。但在实践中，为代理提供正确的上下文是困难的，尤其是在处理杂乱无章的非结构化企业数据时。开发人员必须管理工具、提示、状态、推理逻辑、模型，最重要的是从业务来源检索相关上下文，以提供准确的结果和操作。Elastic Agent Builder 提供这些核心组件，用于开发安全、可靠、上下文驱动的代理。

Agent Builder 核心功能

Agent Builder 利用 Elastic 在搜索相关性和检索增强生成方面的长期投入，并致力于将 Elasticsearch 打造成最佳的向量数据库，从而简化以数据为中心的上下文 AI 代理的开发。

Agent Builder 允许您：

• 立即开始使用内置的会话代理，它可以回答问题、执行分析并驱动对 Elasticsearch 中任何数据的调查。
• 快速从复杂的非结构化数据转变为具有基于配置的开发体验的自定义代理。
• 利用内置的 ES|QL 或自定义工具，利用最佳的混合搜索相关性来提高上下文质量和代理可靠性。
• 将复杂的工作流（预览）作为可重复使用的工具来执行，以丰富数据、更新记录、发送消息等，实现基于规则的自动化。
• 使用工作流和 MCP 连接 Elasticsearch 外部的数据源，以关联和整合代理的上下文。
• 使用通过 MCP 提供的内置和自定义工具与任何代理或应用程序框架集成，并能够连接到外部 MCP（预览版）、支持 A2A 和提供完整的 API 支持。
• 通过与第三方解决方案（如用于复杂文档处理的 LlamaIndex 或用于安全、结构化工具访问的 Arcade.dev）集成，扩展 Agent Builder 的功能。

为了进一步扩展 Agent Builder 的功能，我们推出了 Elastic Workflows，这是我们新的基于规则的自动化功能，目前处于技术预览阶段。对于组织任务，代理有时需要基于规则的操作的确定性和可靠性，这通常是实现特定业务逻辑所必需的。Elastic Workflows 为代理提供了一种简单、声明式的方式，用于编排内部和外部系统，以执行操作、收集和转换数据和上下文。工作流是完全可组合、事件驱动且灵活的，并且可以通过 MCP 作为工具提供给代理。

从数据到代理仅需几分钟

开发代理可能需要花费数周的前期工作来整合独立的数据存储、构建手动管道、调整查询和管理复杂的编排。Agent Builder 不需要单独的数据存储、向量数据库、RAG 管道、搜索层、查询转换器和工具编排器，从而减少了开发代理的时间，使您能够专注于代理逻辑和应用程序交付。

Agent Builder 原生集成了 Elasticsearch 平台的基元，从而加快了代理开发的速度。

• 首先，内置的对话代理可以立即与您的索引数据进行聊天和推理。
• 通过 Kibana、API 或 MCP 和 A2A 进行交互式访问，将代理集成到应用程序、仪表板或 CI/CD 系统中。
• 使用默认工具进行构建，以了解您的数据结构，选择适当的索引，生成优化的混合、语义和结构化查询，并根据自然语言提示使用 ES|QL 创建可配置的可视化。

要深入了解，请尝试完整的实践演练。

基于 Elasticsearch 构建，这是一个用于上下文工程的完整数据平台

对于 AI 代理，上下文质量对于提供有效的推理和降低幻觉的风险至关重要。对于许多企业 AI 代理而言，执行任务所需的业务数据是最关键的上下文信息。作为大规模可扩展数据存储、向量数据库和相关性领域的领导者，Elasticsearch 已经提供了许多强大的上下文工程原语。上下文工程超越了简单的检索增强生成，允许您定制和扩展数据获取、排序、筛选和呈现给代理的方式，有助于减少噪音和歧义。

Elasticsearch 提供的上下文引擎结合了词汇搜索、向量搜索和结构化筛选，通过确保模型在相关且精确的上下文中运行，显著提高了 LLM 性能。这种功能由代理检索提供支持，同时还具备内置工具和搜索逻辑，能够自动选择正确的索引，并将自然语言转化为针对上下文优化的查询。

利用 Agent Builder，您可以确保代理首先获得最有用的上下文，并设有相关性和排名控制，从而允许您微调评分、排名和筛选逻辑。Elasticsearch 可让您控制重要内容、重要原因以及优先级，而非依赖不透明的检索行为。这一切都由 Elasticsearch 作为可扩展性平台提供支持，可以在单个平台上存储和扩展来自文本、向量、元数据、日志等的所有数据，从而更轻松地管理代理的上下文。

将复杂的工作流作为可重复使用的工具来执行

虽然 AI 代理可以对复杂的任务进行推理，但许多自动化工作都依赖于可靠地执行基于规则的操作，以强制实施特定的业务逻辑。Elastic Workflows 提供了一种简单、声明式的方式来编排内部和外部系统，以执行操作、收集上下文或数据，并将其整合为代理的一部分。在 YAML 中定义的工作流是完全可组合的，这使得它们能够根据任务需求变得简单或复杂。这为代理提供了在 Elasticsearch 平台和解决方案以及第三方应用程序中执行操作的有效方式。

使用 Agent Builder 集成工作流可通过三个步骤完成（先决条件：启用工作流，详情请参阅此处）

1. 使用内置自动完成和测试功能的基于 YAML 的简单编辑器创建并保存新的工作流。

2. 在 Agent Builder 中创建一个类型为“工作流”的新工具，并提供说明，帮助代理确定何时使用工作流工具。

3. 将工作流工具添加到您的自定义代理。

4. 就是这样！现在，代理可以在对话中调用工作流。

您的代理，您的规则

Agent Builder 不会将您限制在单一的开发范式中。相反，它旨在为代理提供开放、灵活的开发方法，使代理能够完全掌控数据、相关性、模型、互操作性、安全性和代理设计。

自定义代理定义可让您准确选择代理可访问的工具、嵌入自定义系统提示、定制代理的指令并定义安全边界。代理仍然与模式无关，让您能够灵活配置首选的本地和跨更广泛生态系统的 LLM，而无需受限于单一提供商。

构建可扩展的工具，将特定领域的逻辑（例如特定的索引筛选器、ES|QL 连接、分析管道）封装起来，并对其加以约束，以确保其在生产环境中安全使用。完整的 API 支持实现了与其他代理框架的互操作性，并原生支持模型上下文协议 (MCP)。A2A 集成意味着您可以将 Elastic 代理提供给其他框架、服务和客户端应用，从而在各种集成中重复使用相同的数据和上下文工程逻辑。

Agent Builder 支持灵活、开放的开发，可与流行的代理框架和平台轻松集成。这些集成对于提供高效的代理至关重要。正如 Arcade.dev 的联合创始人 Sam Partee 所描述的那样，

"如今，代理系统之所以失败，是因为将 AI 与工具和数据连接起来非常复杂。Elastic Agent Builder 与 Arcade.dev 结合，为开发者提供了一种结构化且安全的方式来处理代理如何检索上下文、进行推理和采取行动，从而将代理从演示级别提升至生产级别。”

Agent Builder 还利用了 Elasticsearch 的可扩展性来处理复杂数据。正如 LlamaIndex 首席执行官 Jerry Liu 所描述的那样，

“从非结构化数据源中解锁企业上下文是建立有效代理的关键。Elastic Agent Builder 与 LlamaIndex 复杂文档处理相结合，强化了关键的上下文层，帮助团队检索、处理和准备数据，从而使代理能够更准确地推理并提供更好的结果。”

您可以构建什么？

Agent Builder 已用于各种用例。以下是一些示例和参考架构，可帮助您开始使用代理：

• 基础设施自动化：在支持场景中，代理已被用于读取、思考和聊天，但迄今为止，它们还无法触及可能需要管理的基础设施。Elastic 的工程团队在黑客马拉松中构建了一个用于自动化基础设施管理的代理。代理会主动调查应用程序基础设施的问题，并采取自动化操作。它使用工作流来优化配置、响应问题并扩展资源，所有这些都基于对基础设施日志的智能理解。
• 安全威胁分析：已使用 Elastic Agent Builder、MCP 和 Elasticsearch 开发了一个安全漏洞代理。它通过将内部安全数据与外部威胁情报关联起来，自动进行威胁分析。该代理对历史事件和配置进行语义搜索，使用实时互联网数据增加结果，并应用 LLM 推理来评估环境相关性、确定风险优先级并生成可操作的补救措施。请参阅参考架构。
• 技术客户支持：代理可以执行多项支持任务，包括案例汇总、问题重复检测和创建，以及深入的技术调查。Agent Builder 可通过多步骤混合搜索实现这一功能，仅查找最相关的相关问题、解决方案和程序，并制定根本原因假设和补救计划。Agent Builder 可以简化复杂支持系统的架构，并加快交付时间。
• 产品和内容发现：Agent Builder 简化了将复杂的产品目录用于对话式体验的过程，同时允许组织保持灵活性，以纳入其自身的业务逻辑和要求。
• 构建您自己的系统：参加 Agent Builder 黑客松活动，该活动将于 2026 年 1 月 22 日至 2 月 27 日举行。与社区合作，构建基于上下文的多步骤 AI 代理，将搜索、工作流、工具和推理相结合，以自动执行现实世界中的任务*

现在开始构建自定义代理

开始 Elastic Cloud 试用，并在此处查看文档。对于现有客户，Agent Builder 可在 Cloud Serverless 中使用，也可在 Elastic Cloud Hosted 和自主管理的企业层中使用。

*点击此处查看黑客松的完整条款、条件和资格要求

打破这层“玻璃”的一种方式，是引入语音代理 — 这种 AI 代理能够识别人类语音，并合成计算机生成的音频。随着低延迟转写、快速大型语言模型（LLM）以及听起来与人声相近的文本转语音模型的兴起，这一切已经成为可能。

语音代理还需要能够访问业务数据，才能真正发挥价值。在这篇博客中，我们将先介绍语音代理的工作原理，再通过 LiveKit 和 Elastic Agent Builder 为虚构的户外运动装备商店 ElasticSport 构建一个语音代理。我们的语音代理能够感知上下文，并与我们的数据协同工作。

运作方式

语音代理领域主要有两种范式：第一种使用语音到语音模型，第二种使用由语音转文本、LLM 和文本转语音组成的语音处理流水线。语音到语音模型有其自身优势，但语音处理流水线在所用技术、上下文管理方式以及代理行为的控制方面提供了更多自定义空间。下文将重点介绍语音处理流水线模型。

关键组件

转写（语音转文本）

转写模块是语音处理流水线的入口。转写组件以原始音频帧为输入，将语音转写为文本并输出。转写得到的文本会被缓存在系统中，直到系统检测到用户已停止说话，此时才会启动 LLM 生成。目前有多家第三方提供商提供低延迟转写服务。在选择提供商时，需要考虑延迟和转写准确性，并确保其支持流式转写。

第三方 API 示例：AssemblyAI、Deepgram、OpenAI 和 ElevenLabs

轮次检测

轮次检测是流水线中的一个组件，用于检测说话者何时讲完，从而确定何时开始生成回复。一种常见的方法是使用语音活动检测（VAD）模型，例如 Silero VAD。VAD 利用音频能量水平来检测音频中何时包含语音以及语音何时结束。但是，单独使用 VAD 无法区分暂时停顿与真正结束发言。因此，通常会将它与句末检测模型结合使用，该模型基于临时转写结果或原始音频来判断说话者是否已经说完。

示例（Hugging Face）：livekit/turn-detector、pipecat-ai/smart-turn-v3

代理

代理是语音处理流水线的核心。它负责理解用户意图、收集合适的上下文，并以文本形式生成回复。Elastic Agent Builder 凭借其内置的推理能力、工具库和工作流集成，使代理可以在您的数据之上工作，并与外部服务进行交互。

LLM（文本到文本）

在为 Elastic Agent Builder 选择 LLM 时，主要需要考虑两个指标：推理能力基准和首个 Token 时间（TTFT）。

推理基准反映 LLM 生成正确响应的能力水平。可以重点关注衡量多轮对话一致性和整体智能水平的基准，比如 MT-Bench 和 Humanity's Last Exam 等数据集。

TTFT 基准用于评估模型产出第一个输出 Token 的速度。还有其他类型的延迟基准，但 TTFT 对语音代理尤为重要，因为在收到第一个 Token 后就可以开始音频合成，从而降低轮次之间的延迟，让对话更自然。

通常需要在这两个指标之间做权衡，因为速度更快的模型在推理基准测试中的表现往往较差。

示例（Hugging Face）：openai/gpt-oss-20b、openai/gpt-oss-120b

合成（文本转语音）

流水线的最后一环是文本转语音模型。该组件负责将 LLM 输出的文本转换为可听的语音。与 LLM 类似，在选择文本转语音提供商时也需要重点关注延迟这一指标。文本转语音的延迟通过首字节时间（TTFB）来衡量。即接收到第一个音频字节所需的时间。TTFB 越低，对话轮次之间的延迟也越低。

示例： ElevenLabs、 Cartesia、 Rime

构建语音处理流水线

Elastic Agent Builder 可以在多个不同层级集成到语音处理流水线中：

1. 仅限 Agent Builder 工具：语音转文本 → LLM（使用 Agent Builder 工具） → 文本转语音
2. Agent Builder 作为 MCP：语音转文本 → LLM（通过 MCP 访问 Agent Builder）→ 文本转语音
3. Agent Builder 作为核心：语音转文本 → Agent Builder → 文本转语音

在本项目中，我选择采用“Agent Builder 作为核心”的方案。采用这种方案，可以充分利用 Agent Builder 及其工作流的全部功能。该项目使用 LiveKit 来编排语音转文本、轮次检测和文本转语音环节，并实现了一个自定义的大型语言模型节点，直接与 Agent Builder 集成。

Elastic 客服语音代理

我们将为一家名为 ElasticSport 的虚构体育用品商店构建一个自定义客服语音代理。顾客可以拨打服务热线，咨询产品推荐、查看产品详情、查询订单状态，并通过短信接收订单信息。为此，我们首先需要配置一个自定义代理，并创建用于执行 Elasticsearch 查询语言（ES|QL）查询和工作流的工具。

配置代理

提示词

提示词用于告知代理应采用怎样的人设以及如何作答。更重要的是，其中还包含一些专门针对语音场景的提示词，用于确保响应能正确合成为音频，并在出现误解时实现自然的纠正。

You are a Sales Assistant at ElasticSport, an outdoor sport shop specialized in hiking and winter equipment. 

[Profile]
- name: Iva
- company: ElasticSport
- role: Sales Assistant
- language: en-GB
- description: ElasticSport virtual sales assistant

[Context]
- Ask clarifying questions to understand the context.
- Use available tools to answer the user's question.
- Use the knowledge base to retrieve general information

[Style]
- Be informative and comprehensive.
- Maintain a professional, friendly and polite tone.
- Mimic human behavior and speech patterns.
- Be concise. Do not over explain initially

[Response Guideline]
- Present dates in spelled-out month date format (e.g., January fifteenth, two thousand and twenty-four).
- Avoid the use of unpronounceable punctuation such as bullet points, tables, emojis.
- Respond in plain text, avoid any formatting.
- Spell out numbers as words for more natural-sounding speech.
- Respond in short and concise sentences. Responses should be 1 or 2 sentences long.

[ERROR RECOVERY]
### Misunderstanding Protocol
1. Acknowledge potential misunderstanding
2. Request specific clarification

工作流

我们将添加一个小型工作流，通过 Twilio 的消息传递 API 发送短信。该工作流会作为工具提供给自定义代理，使其在通话过程中即可向来电者发送短信，从而带来顺畅的使用体验。例如，这样一来，来电者就可以询问：“你能通过短信发送更多关于 X 的详细信息吗？”

name: send sms
enabled: true
triggers:
  - type: manual
inputs:
  - name: message
    type: string
    description: The message to send to the phone number.

  - name: phone_number
    type: string
    description: The phone number to send the message to.

consts:
  TWILIO_ACCOUNT: "****"
  BASIC_AUTH: "****"
  FROM_PHONE_NNUMBER: "****"
steps:
  - name: http_step
    type: http
    with:
      url: https://api.twilio.com/2010-04-01/Accounts/{{consts.TWILIO_ACCOUNT}}/Messages.json
      method: POST
      headers:
        Content-Type: application/x-www-form-urlencoded
        Authorization: Basic {{consts.BASIC_AUTH | base64_encode}}
      body: From={{consts.FROM_PHONE_NNUMBER}}&To={{inputs.phone_number}}&Body={{inputs.message}}
      timeout: 30s

ES|QL 工具

借助以下工具，代理可以基于真实数据提供相关的回复。示例代码库包含一个设置脚本，用于将产品、订单和知识库数据集导入并初始化 Kibana。

• Product.search

产品数据集中包含 65 个虚构产品。以下是一个示例文档：

{
      "sku": "ort3M7k",
      "name": "Ortovox Free Rider 26 Backpack",
      "price": 189,
      "currency": "USD",
      "image": "https://via.placeholder.com/150",
      "description": "The Ortovox Free Rider 26 is a technical freeride backpack with a dedicated safety compartment and diagonal ski carry system. Perfect for backcountry missions.\n\nKey Features:\n- 26L capacity\n- Diagonal ski carry system\n- Safety equipment compartment\n- Helmet holder\n- Hydration system compatible",
      "category": "Accessories",
      "subCategory": "Backpacks",
      "brand": "Ortovox",
      "sizes": ["One Size"],
      "colors": ["Black", "Blue", "Orange"],
      "materials": ["Nylon", "Polyester"]
    }

通过将名称和描述字段映射为 semantic_text，LLM 就能借助 ES|QL 执行语义搜索并检索到匹配的产品。混合搜索查询会在这两个字段上执行语义匹配，并通过 boost 略微提高名称字段匹配结果的权重。

该查询首先检索按初始相关度得分排序的前 20 个结果。随后，这些结果会借助 .rerank-v1-elasticsearch 推理模型，基于描述字段重新排序，并最终缩减为最相关的前五个产品。

type: ES|QL
toolId: products.search
description: Use this tool to search through the product catalogue by keywords.
query: |
    FROM products
        METADATA _score
      | WHERE
          MATCH(name, ?query, {"boost": 0.6}) OR
            MATCH(description, ?query, {"boost": 0.4})
      | SORT _score DESC
      | LIMIT 20
      | RERANK ?query
            ON description
            WITH {"inference_id": ".rerank-v1-elasticsearch"}
      | LIMIT 5

parameters:
    query: space separated keywords to search for in catalogue

• Knowledgebase.search

知识库数据集包含以下格式的文档，其中标题和内容字段以语义文本形式存储：

{
        id: "8273645",
        createdAt: "2025-11-14",
        title: "International Orders",
        content: `International orders are processed through our international shipping partner. Below are the countries we ship to and average delivery times.
        Germany: 3-5 working days
        France: 3-5 working days
        Italy: 3-5 working days
        Spain: 3-5 working days
        United Kingdom: 3-5 working days
        United States: 3-5 working days
        Canada: 3-5 working days
        Australia: 3-5 working days
        New Zealand: 3-5 working days
        `
}

该工具使用的查询与 product.search 工具类似：

type: "ES|QL"
toolId: knowledgebase.search
description: Use this tool to search the knowledgebase.
query: |
  FROM knowledge_base
    METADATA _score
  | WHERE
      MATCH(title, ?query, {"boost": 0.6}) OR
      MATCH(content, ?query, {"boost": 0.4})
  | SORT _score DESC
  | LIMIT 20
  | RERANK ?query
      ON content
      WITH {"inference_id": ".rerank-v1-elasticsearch"}
  | LIMIT 5

parameters:
  query: space separated keywords or natural language phrase to semantically search for in the knowledge base

• Orders.search

我们要添加的最后一个工具用于通过 order_id 检索订单：

type: "ES|QL"
toolId: order.search
description: Use this tool to retrieve an order by its ID.
query: |
  FROM orders
    METADATA _score
  | WHERE order_id == ?order_id
  | SORT _score DESC
  | LIMIT 1

parameters:
  order_id: "the ID of the order"

在完成代理配置并将这些工作流和 ES|QL 工具关联到代理之后，即可在 Kibana 中对其进行测试。

除了为 ElasticSport 构建客服代理外，还可以将该代理、工作流和工具拓展到其他场景，例如甄别潜在客户的销售代理、家庭维修服务代理、餐厅预订代理或预约安排代理。

最后一部分是将刚创建的代理与 LiveKit、文本转语音模型和语音转文本模型连接起来。本博客末尾链接的代码仓库中包含一个可与 LiveKit 搭配使用的自定义 Elastic Agent Builder LLM 节点。只需将 AGENT_ID 替换为您自己的值，并将其与 Kibana 实例关联即可。

开始使用

点击此处查看代码并动手体验。

我们都见证了 AI 智能体的兴起。它们在总结文本、编写代码片段以及基于文档回答问题方面表现出色。但对于我们从事 DevOps 和网站可靠性工程 (SRE) 的人来说，一直存在一个令人沮丧的限制。大多数智能体都困于呼叫中心模式，这意味着它们可以阅读、思考和聊天，但无法触及它们本该管理的基础架构。

在最新的黑客马拉松项目中，我们决定打破这一限制。

我们构建了增强型基础架构：这是一个基础架构协同助手，它不仅能为您提供建议，还能创建、部署、监测和修复您的实时环境。

问题：复制、重新格式化、粘贴

标准智能体在孤立状态下运行。如果您的应用宕机，给公司造成 500万美元的损失，标准智能体可以为您朗读如何修复的应急预案手册。但您仍然需要亲自动手。您只能复制代码，根据环境重新格式化，然后粘贴到终端中。

我们需要一个能理解谈论 Kubernetes 和配置 Kubernetes 之间区别的智能体。

引擎：什么是 Elastic Agent Builder？

我们并不是从零开始构建的。我们是基于 Elastic Agent Builder 构建的。对于不熟悉的人来说，Elastic Agent Builder 是一个旨在快速开发智能体的框架，它充当大型语言模型 (LLM)（在我们的演示中，我们使用了 Google Gemini）与存储在 Elasticsearch 中的私有数据之间的桥梁。

Agent Builder 可以通过将 AI 与内部数据（如文档或日志）相结合，用于对话式 AI。但它最强大的功能是能够分配工具。这些工具允许 LLM 跳出聊天接口，执行特定任务。我们意识到，如果将此功能发挥到极致，我们可以将 Agent Builder 转变为一个自动化引擎。

使其运行：构建第一个版本

在项目启动之初，我们就知道要让智能体能够改变外部世界。我们当时有个想法：如果我们开发一些“运行器”软件（在主机上运行智能体能想到的任何命令）会怎样？然后：如果运行器、Elastic Agent Builder 和用户进行三方通话会怎样？

我们首先构建了一个 Python 项目“增强型基础架构运行器”，其本质是一个 while(true) 循环，每秒查询 Elastic Agent Builder 对话 API，并检查我们创建的特殊语法：

{
	"tool_name": "my_tool",
       "tool_arguments": "\{stringified json arguments\}"
}

然后我们更新了提示，以教会它我们新的工具调用语法。Bill 是 FastMCP 的维护者，FastMCP 是在 Python 中构建模型上下文协议 (MCP) 服务器的最常用框架。他开始尝试使用 FastMCP 客户端配合这个新的运行器软件，来挂载 MCP 服务器并使其工具对运行器可用。当智能体看到这个时，它会执行工具调用，并将 POST 结果返回到对话中，就像用户发送了结果一样。这会触发 LLM 对结果作出回应，然后我们开始了！

这很好，但存在两个主要问题：

1. 代理会将所有这些 JSON 直接注入到与用户的对话中。
2. 通过对话 API 能看到消息的最早时间点是一个对话轮次完成时（即 LLM 回复时）。

因此，我们着手研究如何将其移至后台。

然后我们切换到为智能体提供一个名为 call_external_tool 的工具，该工具有两个参数：tool_name 和字符串化的 JSON 工具参数。这个外部工具调用不会返回任何内容，但重要的是，它会在对对话 API 的 GET 请求中可见。然后，我们授予运行器直接将文档写入 Elasticsearch 的权限，Elastic Agent Builder 智能体可以根据需要检索这些文档。智能体总是在响应用户消息的情况下运行，所以我们需要用一个用户消息来启动智能体，这样它才会去查找结果并继续处理。因此，我们让智能体在聊天记录中插入一条简短的消息，以继续对话：

所以现在我们有了外部工具调用。然而，由于上面提到的第二个问题，我们不得不去掉最后的启动部分。否则，每个外部工具调用都需要一个完整的对话轮次来检索结果！

让它变得更好：介绍工作流

除了 Elasticsearch 查询语言 (ES|QL) 和索引搜索工具调用之外，Agent Builder 智能体还可以调用 Elastic 基于工作流的工具。Elastic 工作流提供了一种灵活且易于管理的方式来执行任意顺序和逻辑的操作。就我们的目的而言，我们只需要工作流做两件事：将外部工具请求存储到 Elasticsearch，并返回一个用于轮询结果的 ID。这产生了以下简单的工作流定义：

name: ai-tool-call
enabled: true
triggers:
  - type: manual
inputs:
  - name: runner_id
    type: string
  - name: tool_calls
    type: string

steps:
  - name: store_request
    type: elasticsearch.create
    with:
      index: distributed-tool-requests
      id: "{{inputs.runner_id}}_{{ execution.id }}"
      document:
        request_id: "{{ execution.id }}"
        runner_id: "{{inputs.runner_id}}"
        tool_call: "{{inputs.tool_calls}}"
        status: "unhandled"

  - name: output_result
    type: console
    with:
      message: "Called tool, with execution id: {{ execution.id }}. Use this ID to poll the results."

这样，运行器不再依赖将工具调用请求写入对话，而只需轮询 Elasticsearch distributed-tool-requests 索引中的新外部工具请求，并使用提供的 execution.id 将结果报告回另一个 Elasticsearch 索引。

这消除了上述两个主要问题：

1. 对话历史记录不再被外部工具调用的负载所充斥。
2. 由于运行器轮询的是 Elasticsearch 索引而非对话历史记录，它们不会因需要等待对话轮次完成以使外部工具请求可见而被阻塞。

第二点有一个巨大优势：外部工具调用的处理在智能体的思考阶段就开始了（而不是在对话轮次完成之后）。这允许我们在系统提示中指示 LLM 轮询外部工具结果，直到结果可用，从而消除了启动消息的需要。总的来说，这样做的好处是对话感觉更加自然：LLM 可以在单个对话轮次中处理多个外部工具请求（而不是每个工具请求需要一个对话轮次），因此可以一次性完成更复杂的用户请求。

将所有内容整合到一起

为了弥合 LLM 与服务器机架之间的鸿沟，我们利用 Agent Builder 的工具功能开发了一种特定的架构：

1. 增强型基础架构运行器：我们在目标环境（服务器、Kubernetes 集群、云账户）中部署了轻量级运行器。这些运行器直接连接到 Elastic，使用受保护的终端和仅每个运行器可用的密钥。
2. ES|QL 检索：该协同助手使用 Elastic 的 ES|QL 执行混合搜索。它不仅搜索知识，还会搜索功能。它查询已连接的运行器，查看哪些工具可用（例如list_ec2_instances、install_helm_chart)。
3. 工作流执行：一旦智能体决定行动方案，就会创建一个结构化的工作流。
4. 反馈循环：运行器在本地执行命令并将结果报告到 Elasticsearch。协同助手从索引中读取结果，并决定下一步。

演示：从故障到可观测性

在视频中，我们展示了两个不同的场景，彰显了该架构的支持。

场景 1：DevOps 开发运维救援

我们从一位用户因 Kubernetes 集群中的盲点导致 500 万美元宕机而惊慌失措的场景开始。

• 请求：“如何确保这种情况不再发生？”
• 行动：该智能体不只是提供了教程。它识别了集群，创建了必要的命名空间，生成了 Kubernetes 密钥，安装了 OpenTelemetry Operator，并立即提供了一个指向实时 APM 仪表板的链接。
• 结果：用户无需编写一行 YAML，即可获得完整的 Kubernetes 可观测和应用见解。

场景 2：安全交接

基础架构安全的一条基本规则是，您无法保护看不到的东西。在执行我们的 DevOps 开发运维救援时，智能体看到了改善环境安全的机会。

借助之前一次与 Elastic Observability 相关调查触发的警报，我们展示了安全从业者如何直接与其基础架构聊天：首先，列举云环境中的资产和资源；其次，部署确保环境安全的必要工具。

• 发现：协同助手为安全从业者列举了 AWS 资源，并识别出一个关键缺口：一个 Amazon Elastic Compute Cloud (EC2) 实例和一个 Amazon Elastic Kubernetes Service (EKS) 集群的公共终端缺少终端保护。
• 修复：只需简单批准，协同助手就将 Elastic Security 扩展检测与响应 (XDR) 和云检测与响应 (CDR) 部署到了易受攻击的资产上，实时保护了环境。
• 结果：已部署的 AWS 资产和资源得到了保护，实现了完整的运行时安全。

未来：增强一切

这个项目证明 Elastic Agent Builder 可以成为分布式运维的中心大脑。我们不仅限于基础架构。我们的运行器技术可以驱动：

• 增强型合成：诊断全球运行器中的 TLS 错误。
• 增强型开发：创建拉取请求并在前端服务上实现验证码。
• 增强型运维：在宕机期间自动重新配置 DNS 解析器。

亲自试用

我们认为，AI 的未来不仅仅是聊天支持，而是增强型基础架构。它关乎拥有一个可以与您并肩部署、修复、观测和保护的合作伙伴。

立即查看代码，并通过分布式运行器 (GitHub) 加上 Elastic Cloud Serverless 上的 Elastic Agent Builder 亲自尝试吧！

• 在 Elastic Cloud 上创建一个无服务器项目。
• 请将代码部署到运行器。
• 设置运行器。
• 配置您的 mcp.json。
• 启动运行器，它会自动创建您的智能体及其工具。
• 与一位能够推理、规划并在您的分布式运行器上执行操作的代理聊天！

团队：Alex、Bill、Gil、Graham 和 Norrie

为什么这很重要

绝大多数典型分析流程最终都归结为数据分组操作。无论是计算每台主机的平均字节数、统计每个用户的事件数量，还是跨维度聚合指标，其核心操作始终如一，那就是将键映射到分组并更新累计聚合值。

在小规模场景下，几乎任何合理的哈希表都能良好运行。但在大规模场景（数亿文档、数百万独立分组）中，细节决定成败。负载因素、探测策略、内存布局和缓存行为，这些因素可能让性能呈现线性增长，也可能导致严重的缓存未命中问题。

Elasticsearch 多年来一直支持这些工作负载，但我们一直在寻找机会来更新核心算法。因此，我们评估了一种受 Swiss 表启发的新方法，并将其应用于 ES|QL 如何计算统计数据。

到底什么是 Swiss 表？

Swiss 表是一类由 Google SwissTable 推广的现代哈希表系列，后被 Abseil 等资料库采纳。

传统哈希表在探测过程中需频繁追踪指针或加载键值，却发现大量不匹配情况。Swiss 哈希表的核心创新在于通过独立于键值存储的微型缓存驻留数组结构（称为控制字节），可拒绝大多数探测，从而显著降低内存流量。

每个控制字节对应一个哈希槽，在我们的应用中编码两类信息：槽是否为空，以及从哈希值派生的短指纹。这些控制字节在内存中连续存储（通常以 16 字节为一组），使其非常适合单指令多数据 (SIMD) 并行处理。

Swiss 表摒弃逐槽探测的传统方式，转而通过向量指令一次性扫描整个控制字节块。CPU 在单次操作中，将待插入键的指纹与 16 个槽位的指纹进行批量比对，并过滤掉空条目。仅当少数候选键通过这一快速通道后，才需要加载并比对实际键值。

该设计通过引入少量额外元数据，换取了更高的缓存命中率和大幅减少的随机内存访问。随着哈希表规模扩大及探测链长度增加，这些特性将愈发凸显其价值。

以SIMD为中心

真正的主角是 SIMD。

控制字节不仅结构紧凑，更专门针对向量指令处理进行优化设计。单条 SIMD 比对指令可同时校验 16 个指纹，将传统循环操作转化为数条高效宽指令处理。例如：

实际上，这意味着：

• 更少的分支。
• 更短的探针链。
• 减少键值存储的内存加载次数。
• 更好地利用了CPU的执行单元。

绝大多数查询在控制字节扫描阶段即可完成过滤。当需要进一步处理时，剩余操作高度集中且可预测，而这正是现代 CPU 所擅长的负载类型。

深入了解 SIMD

对于喜欢探究底层实现细节的读者，以下是向表中插入新键时的具体流程：我们使用 Panama Vector API 配合 128 位向量，因此可并行处理 16 个控制字节。

以下代码片段展示了在配备 AVX-512 的 Intel Rocket Lake 处理器上生成的代码。虽然这些指令反映了当前硬件环境，但该设计并不依赖 AVX-512。在其他平台上会生成等效指令（如 AVX2、SSE 或 NEON）来实现相同的高层向量操作。

; Load 16 control bytes from the control block
vmovdqu xmm0, XMMWORD PTR [r9+r10*1+0x10]

; Broadcast the 7-bit fingerprint of the new key across the vector
vpbroadcastb xmm1, r11d

; Compare all 16 control bytes to the new fingerprint
vpcmpeqb k7, xmm0, xmm1
kmovq rbx, k7

; Check if any matches were found
test rbx, rbx
jne 

每条指令在插入过程中都起着明确的作用：

• vmovdqu：将 16 个连续的控制字节加载到 128 位 xmm0 寄存器中。
• vpbroadcastb：将新键的 7 位指纹复制到xmm1寄存器的所有向量通道中。
• vpcmpeqb：将每个控制字节与广播后的指纹进行并行比较，生成潜在匹配的掩码。
• kmovq + test：将掩码移动到通用寄存器，并快速检查是否存在匹配。

最终，我们决定一次探测 16 个控制字节组，因为基准测试表明，扩展到 32 或 64 个字节并使用更宽的寄存器并没有带来明显的性能提升。

ES|QL 中的集成

在 Elasticsearch 中采用 Swiss 式哈希算法并非简单的替换操作。ES|QL 对内存核算、安全性以及与计算引擎其他部分的集成有着严苛要求。

我们将新型哈希表与 Elasticsearch 的内存管理机制深度集成，包括分页回收器和熔断器核算模块，确保内存分配始终透明且受控。Elasticsearch 的聚合数据采用密集存储方式并通过组 ID 索引，在保持内存布局紧凑、迭代高效的同时，通过支持随机访问实现了特定性能优化。

对于可变长度字节键，我们在存储组 ID 的同时缓存完整哈希值。此设计避免了探测过程中重复计算高开销的哈希码，并通过将关联元数据集中存储提升了缓存命中率。在重新哈希时，系统可直接利用缓存的哈希值和控制字节，无需检查键值本身，从而将容量调整成本降至最低。

我们实施中的一个重要简化策略是永不删除条目。这一设计消除了对“墓碑”标记（用于标识已释放槽位的占位符）的需求，使空槽保持真正空闲状态。这种优化进一步改善了探测行为，并确保控制字节扫描始终保持高效。

这样的设计在完美契合 Elasticsearch 执行模型的同时，保留了使 Swiss 表具吸引力的高性能特性。

它的表现如何？

在小规模数据量下，Swiss 表的性能与现有实现基本持平。这符合预期，当哈希表较小时，缓存效应的影响减弱，且待优化的探测操作本就较少。

随着数据规模扩大，性能特征迅速发生质变。

上方热图展示了不同键大小（8、32、64 和 128 字节）在数据规模从 1,000 至 10,000,000 组变化时的时间优化倍数。随着数据规模扩大，优化倍数呈稳定上升趋势，在均匀分布场景下最高可达 2-3 倍。

这一趋势完全符合设计预期。传统哈希表在数据规模扩大时会导致探测链长度增加，而 Swiss 式探测仍能在支持 SIMD 指令的控制字节块内完成绝大多数查询操作。

缓存行为说明了一切

为深入分析加速效果，我们在 Linux perf环境下运行相同的 JMH benchmarks基准测试，并采集缓存与 TLB 统计数据。

与原始实施相比，Swiss 版实现的总缓存引用量减少约 60%，末级缓存（LLC）加载次数下降超 4 倍，LLC 加载未命中次数更是降低超 6 倍。由于 LLC 未命中通常直接导致主存访问，仅此一项优化就解释了端到端性能提升的绝大部分原因。

在更靠近 CPU 的层级，我们观察到 L1 数据缓存未命中次数显著减少，数据 TLB 未命中次数更降低近 6 倍，这表明数据空间局部性增强且内存访问模式更具可预测性。

这正是 SIMD 友好型控制字节带来的实际效益。无需反复从分散的内存位置加载键和值，大多数探测操作仅需扫描紧凑、驻留缓存的结构体即可完成。内存访问量减少意味着缓存未命中率降低，而未命中率降低则直接提升查询速度。

总结

通过采用 Swiss 式哈希表设计并深度融合 SIMD 友好型探测机制，我们在高基数 ES|QL 统计工作负载中实现了 2-3 倍的速度提升，同时获得了更稳定且可预测的系统表现。

本研究揭示了现代 CPU 感知型数据结构如何为哈希表等老问题带来显著性能提升。该领域仍有广阔探索空间，例如扩展至更多基础数据类型的特化实现，以及在连接等高基数操作路径中的应用。这些工作均属于 Elasticsearch 内核持续现代化这一长期工程的重要组成部分。

如需了解详细信息或跟进项目进展，可查看 GitHub 上的该拉取请求及追踪进度的元议题。

祝您哈希愉快！

毕竟上下文中的所有内容都会影响 AI 的响应。“垃圾进，垃圾出”说的就是这个道理。

本文将介绍短期记忆和长期记忆对 AI 智能体的意义，具体包括：

• 短期记忆和长期记忆的区别。
• 它们与使用向量数据库（如 Elasticsearch）的检索增强生成 (RAG) 技术有何关联，以及为什么需要细致的记忆管理。
• 忽略记忆（包括上下文溢出和上下文污染）有何风险。
• 最佳实践，如上下文修剪、总结和仅检索相关内容，以保持代理的记忆既有用又安全。
• 最后，我们将探讨如何使用 Elasticsearch 在多智能体系统中共享和传播记忆，使智能体能够协作而不会产生混乱。

AI 智能体中的短期记忆与长期记忆

AI 智能体的短期记忆通常指的是即时的对话上下文或状态——其本质上是活跃会话中的当前聊天历史记录或最近消息。这包括用户的最新查询和最近的来回交流。这与一个人在进行对话时脑海中记住的信息非常相似。

AI 框架通常会将这种瞬时记忆作为智能体状态的一部分来维护（例如使用检查点进程来存储对话状态，LangGraph 的此示例就介绍了这一点）。短期记忆存在于会话范围内；也就是说，它存在于单个会话或任务中，会话结束后即重置或清除，除非明确保存在其他地方。ChatGPT 中提供的临时聊天 就是会话范围内短期记忆的一个例子。

而长期记忆指的是跨越对话或会话持续存在的信息。这是智能体日积月累保留的知识，包括早前学习的事实，或我们告知其永久记住的用户偏好或任何数据。

长期记忆通常通过从外部源（如文件或向量数据库）存储和获取来配置，这些外部源位于即时上下文窗口之外。与短期聊天历史记录不同，长期记忆并非自动包含在每个提示中。相反，基于特定场景，智能体必须在调用相关工具时回忆或检索该信息。在实践中，长期记忆可能包括用户的个人资料信息、智能体先前生成的答案或分析，或者智能体可以查询的知识库。

例如，如果您有一个旅行规划智能体，短期记忆将包含当前行程查询的详细信息（日期、目的地、预算）以及该聊天中的任何后续问题；而长期记忆可以存储用户的一般旅行偏好、过去的行程和在之前会话中分享的其他事实。当用户在后面再次访问时，智能体可以从这个长期存储中提取资源（例如，用户喜欢海滩和山脉，平均预算为 10 万卢比，有愿望清单，更喜欢体验历史和文化而非适合儿童的景点），这样就不会每次都把用户当作一张白纸。

短期记忆（聊天历史记录）提供即时的上下文和连续性，而长期记忆则提供更广泛的背景，供智能体在需要时调用。大多数先进的 AI 智能体框架都能做到这两点：它们会跟踪最近的对话以保持上下文，并提供在长期信息库中查找或存储信息的机制。管理短期记忆可确保其保持在上下文窗口内，而管理长期记忆则能帮助智能体基于以往的互动和角色来构建答案。

上下文工程中的内存和 RAG

在实践中，我们如何让 AI 智能体拥有有用的长期记忆？

语义记忆是长期记忆的一个重要方法，通常通过检索增强生成 (RAG) 来配置。这需要将 LLM 与外部知识存储或支持向量的数据存储（如 Elasticsearch）耦合。当 LLM 需要提示或其内置训练之外的信息时，它会对 Elasticsearch 执行语义检索，并将最相关的结果作为上下文注入到提示中。通过这种方式，模型的有效上下文不仅包括最近的对话（短期记忆），还包括即时获取的相关长期事实。LLM 随后根据自身推理和检索到的信息来给出答案，它有效地将短期记忆和长期记忆结合起来，从而做出更准确和更感知上下文的响应。

Elasticsearch 可用于为 AI 智能体配置长期记忆。下面是一个高级示例，演示如何从 Elasticsearch 中检索上下文以配置长期记忆。

按照这种方式，智能体通过搜索相关数据来“记忆”，而不是将所有内容存储在有限的提示中，从而导致不同的风险。

将 RAG 与 Elasticsearch 或任何向量存储结合使用可带来诸多好处：

首先，它将模型的知识扩展到了训练截止点之外。智能体可以检索 LLM 可能不知晓的最新信息或特定领域的数据。这对于询问近期事件或专业话题至关重要。

其次，按需获取上下文有助于减少幻觉，尤其是当 LLM 未针对您的细分用例进行专有或高度专业化的数据训练时，这很有可能会导致出现幻觉。正如 OpenAI 最近的一篇论文（《Why Language Models Hallucinate》）强调的那样， LLM 不是像以往所激励的那样通过评估来猜测或编造新信息，而是以 Elasticsearch 中的事实参考为基础。当然， LLM 依赖于向量存储中数据的可靠性来真正防止错误信息，并根据核心相关性措施检索相关数据。

第三，RAG 支持智能体处理的知识库远远大于提示所能容纳的任何内容。RAG 不是将整个文档（例如长篇研究论文或政策文件）推送到上下文窗口，从而导致信息过载或无关信息上下文污染，而是依赖于分块。大型文档会被分解成语义上有意义的小块，系统只检索与查询最相关的几个数据块。这样一来，模型要显得知识渊博不需要长达数百万个词元的上下文来支撑；它只需要访问更大语料库中的正确数据块。

值得注意的是，随着 LLM 上下文窗口的扩大（一些模型现在支持数十万甚至数百万个词元），关于 RAG 是否“已死”的争论也随之出现。为什么不将所有数据推送到提示中？如果您有同样的疑惑，请参阅我的同事 Jeffrey Rengifo 和 Eduard Martin 撰写的精彩文章《Longer context ≠ better: Why RAG still matters》。这避免了“垃圾进，垃圾出”的问题：LLM 始终专注于少数重要内容，而不是应付噪音。

也就是说，将 Elasticsearch 或任何向量存储集成到 AI 智能体架构中可以提供长期记忆。智能体将知识存储在外部，并在需要时将其作为记忆上下文提取出来。这可以作为一种架构来实现，在每次用户查询后，智能体都会在 Elasticsearch 上搜索相关信息，然后在调用 LLM 之前将排序靠前的结果附加到提示中。如果响应包含有用的新信息，它也会保存回长期存储中（从而形成学习的反馈循环）。通过使用这种基于检索的记忆，智能体可以随时了解最新信息，无需将所有知识塞入每个提示，尽管上下文窗口支持一百万个词元。这种技术是上下文工程的基石，结合了信息检索和生成式 AI 的优势。

下面是一个在会话期间使用 LangGraph 的检查点系统管理记忆中对话状态的示例。（请参阅我们的支持上下文工程应用程序。）

# Initialize chat memory (Note: This is in-memory only, not persistent)
memory = MemorySaver()

# Create a LangGraph agent
langgraph_agent = create_react_agent(model=llm, tools=tools, checkpointer=memory)

...
...
# Only process and display checkpoints if verbose mode is enabled
if args.verbose:
    # List all checkpoints that match a given configuration
    checkpoints = memory.list({"configurable": {"thread_id": "1"}})
    # Process the checkpoints
    process_checkpoints(checkpoints)

以下是它存储检查点的方式：

Checkpoint:
Timestamp: 2025-12-30T09:19:41.691087+00:00
Checkpoint ID: 1f0e560a-c2fa-69ec-8001-14ee5373f9cf
User: Hi I'm Som, how are you? (Message ID: ad0a8415-5392-4a58-85ad-84154875bbf2)
Agent: Hi Som! I'm doing well, thank you! How about you? (Message ID: 
56d31efb-14e3-4148-806e-24a839799ece)
Agent:  (Message ID: lc_run--019b6e8e-553f-7b52-8796-a8b1fbb206a4-0)

Checkpoint:
Timestamp: 2025-12-30T09:19:40.350507+00:00
Checkpoint ID: 1f0e560a-b631-6a08-8000-7796d108109a
User: Hi I'm Som, how are you? (Message ID: ad0a8415-5392-4a58-85ad-84154875bbf2)
Agent: Hi Som! I'm doing well, thank you! How about you? (Message ID: 
56d31efb-14e3-4148-806e-24a839799ece)

Checkpoint:
Timestamp: 2025-12-30T09:19:40.349027+00:00
Checkpoint ID: 1f0e560a-b62e-6010-bfff-cbebe1d865f6

对于长期记忆，以下是在 Elasticsearch 上执行语义搜索的方法，以便在将检查点汇总并索引到 Elasticsearch 后使用向量嵌入检索以前的相关对话。

Functions: 
retrieve_from_elasticsearch() 

# Enhanced Elasticsearch retrieval with rank_window and verbose display
def retrieve_from_elasticsearch(query: str, k: int = 5, rank_window: int = None) -> tuple[List[Dict[str, Any]], str]:
    """
    Retrieve context from Elasticsearch with score-based ranking
    
    Args:
        query: Search query
        k: Number of results to return
        rank_window: Number of candidates to retrieve before ranking (default: args.rank_window)
        
    Returns:
        Tuple of (retrieved_documents, formatted_context_string)
    """
    if not es_client or not es_index_name:
        return [], "Elasticsearch is not available. Cannot search long-term memory."
    
    if rank_window is None:
        rank_window = args.rank_window
    
    try:
        # Check if index exists and has documents
        if not es_client.indices.exists(index=es_index_name):
            return [], "No previous conversations stored in long-term memory yet."
        
        # Get document count
        try:
            doc_count = es_client.count(index=es_index_name)["count"]
            if doc_count == 0:
                return [], "Long-term memory is empty. No previous conversations to search."
        except Exception as e:
            return [], f"Error checking memory: {str(e)}"
        
        # Generate embedding for the query
        try:
            query_embedding = embeddings.embed_query(query)
        except Exception as e:
            return [], f"Error generating embedding: {str(e)}"
        
        # Perform semantic search using kNN with rank_window
        try:
            search_body = {
                "knn": {
                    "field": "vector",
                    "query_vector": query_embedding,
                    "k": k,
                    "num_candidates": rank_window  # Retrieve more candidates, then rank top k
                },
                "_source": ["text", "content", "message_type", "timestamp", "thread_id"],
                "size": k
            }
            
            response = es_client.search(index=es_index_name, body=search_body)
            
            if not response.get("hits") or len(response["hits"]["hits"]) == 0:
                return [], "No relevant previous conversations found in long-term memory."
            
            # Extract documents with scores
            retrieved_docs = []
            for hit in response["hits"]["hits"]:
                source = hit["_source"]
                score = hit["_score"]
                retrieved_docs.append({
                    "content": source.get("content", source.get("text", "")),
                    "message_type": source.get("message_type", "unknown"),
                    "timestamp": source.get("timestamp", "unknown"),
                    "thread_id": source.get("thread_id", "unknown"),
                    "score": score
                })
            
            # Format context string
            context_parts = []
            for i, doc in enumerate(retrieved_docs, 1):
                context_parts.append(doc["content"])
            
            context_string = "\n\n".join(context_parts)
            
            # Verbose display
            if args.verbose:
                rich.print(f"\n[bold yellow]🔍 RETRIEVAL ANALYSIS[/bold yellow]")
                rich.print("="*80)
                rich.print(f"[blue]Query:[/blue] {query}")
                rich.print(f"[blue]Retrieved:[/blue] {len(retrieved_docs)} documents (from {rank_window} candidates)")
                rich.print(f"[blue]Total context length:[/blue] {len(context_string)} characters\n")
                
                for i, doc in enumerate(retrieved_docs, 1):
                    rich.print(f"[cyan]📄 Document {i} | Score: {doc['score']:.4f} | Type: {doc['message_type']}[/cyan]")
                    rich.print(f"[cyan]   Timestamp: {doc['timestamp']} | Thread: {doc['thread_id']}[/cyan]")
                    content_preview = doc['content'][:200] + "..." if len(doc['content']) > 200 else doc['content']
                    rich.print(f"[cyan]   Content: {content_preview}[/cyan]")
                    rich.print("-" * 80)
            
            return retrieved_docs, context_string
            
        except Exception as e:
            return [], f"Error searching memory: {str(e)}"
            
    except Exception as e:
        return [], f"Error accessing long-term memory: {str(e)}"

既然我们已经探讨了如何利用 LangGraph 的检查点在 Elasticsearch 中索引和提取短期记忆和长期记忆，接下来让我们花点时间了解为什么索引和转储完整对话可能存在风险。

不管理上下文内存的风险

我们花了大量篇幅讨论了上下文工程以及短期和长期记忆，接下来让我们了解如果不好好管理智能体的记忆和上下文会发生什么。

遗憾的是，当 AI 的上下文变得极其庞大或包含不良信息时，很多事情都可能会出错。随着上下文窗口变大，新的失效模式也会随之出现，例如：

• 上下文污染
• 上下文干扰
• 上下文混淆
• 上下文冲突
• 上下文泄露和知识冲突
• 幻觉和错误信息

让我们来分析一下这些问题以及因上下文管理不善而产生的其他风险：

上下文污染

上下文污染指的是错误或有害信息混入上下文中，并“污染”模型的后续输出。一个常见的例子是模型产生的幻觉被当作事实并插入到对话历史记录中。然后，该模型可能会在以后的响应中以该错误为基础，从而使错误更加严重。在迭代智能体循环中，一旦虚假信息进入共享上下文（例如智能体工作笔记的摘要），它可能会被反复强化。

DeepMind 的研究人员在 Gemini 2.5 报告（TL;DR，请点击此处查看）中观察到，一个长期运行的 Pokémon 游戏智能体出现了这种情况：如果智能体产生一个错误的游戏状态幻觉，并且该状态被记录到它的上下文（它对目标的记忆）中，那么智能体就会围绕一个不可能完成的目标形成毫无意义的策略，从而陷入困境。换句话说，受污染的记忆会让智能体无限期地走上错误的道路。

上下文污染可能是无意的（误操作），也可能是恶意的，例如通过提示注入攻击，用户或第三方偷偷输入隐藏指令或错误事实，智能体随后记住并遵循这些指令或事实。

建议的应对措施：

根据来自 Wiz、Zerlo 和 Anthropic 的见解，针对上下文污染的对策主要是防止不良或误导性信息进入 LLM 的提示、上下文窗口或检索管道。关键步骤包括：

• 不断检查上下文：监测对话或检索到的文本中是否有任何可疑或有害内容，而不仅仅是监测起始提示。
• 使用可信来源：根据可信度对文档进行评分或标记，以便系统优先选择可靠的信息，并忽略低分数据。
• 发现异常数据：使用工具检测异常、不合适或被篡改的内容，并在模型使用前将其删除。
• 过滤输入和输出：添加护栏，防止有害或误导性文本进入系统或被模型重复。
• 用干净的数据不断更新模型：定期用经过验证的信息刷新系统，以纠正任何漏网的不良数据。
• 人机协同：安排人员审查重要的输出或将其与已知的可信来源进行比较。

简单的用户习惯也很有帮助，比如重置冗长的聊天记录、只分享相关信息、将复杂的任务分解成更小的步骤，以及在模型外保留干净的备注。

这些措施可共同构建多层防御，保护 LLM 免受上下文污染，并保持输出的准确性和可信度。

如果不采取这里提到的对策，智能体可能会记住一些指令，比如忽略以前的指南或攻击者插入的琐碎事实，从而导致得到有害的输出。

上下文干扰

上下文干扰是指当上下文变得过长时，模型过度关注上下文而忽视在训练过程中学到的内容。在极端情况下，这类似于灾难性遗忘；也就是说，模型会有效地“遗忘”它的底层知识，变得过分依赖摆在它面前的信息。先前的研究表明，当提示过长时，LLM 往往会失去注意力。

以 Gemini 2.5 智能体为例，它支持百万词元级别的窗口，但当其上下文增长超过一定程度时（在实验中约为 100000 个词元），它会开始专注于重复其过去的操作，而不是提出新的解决方案。从某种意义上说，该智能体成了其广泛历史的囚徒。它不停地查看以前的动作记录（上下文）并模仿它们，而不是利用其底层的训练知识来制定新颖的策略。

这只会适得其反。我们希望模型能够利用相关的上下文来帮助推理，而不是让上下文凌驾于其思考能力之上。值得注意的是，即使是那些拥有巨大窗口的模型也会表现出这种上下文腐烂：随着词元的增加，它们的性能会不均匀地下降。它们仿佛有注意力预算。就像人类工作记忆有限一样， LLM 对词元的关注能力也是有限的，随着预算捉襟见肘，其精准度和专注度会下降。

作为缓解措施，您可以通过分块、工程化正确信息、定期总结上下文以及利用评分来评估和监控响应的准确性来防止上下文干扰。

这些方法可使模型始终基于相关的上下文和其底层训练，从而降低干扰的风险，并提高整体推理质量。

上下文混淆

上下文混淆是指模型使用上下文中的多余内容生成低质量响应的情况。一个典型的例子是为智能体提供它可能会用到的大量工具或 API 定义。如果这些工具有很多与当前任务无关，模型可能仍然会试图不恰当地使用它们，仅仅因为它们出现在上下文中。实验发现，提供过多非必需的工具或文档可能会降低性能。智能体会开始出错，例如调用错误的函数或引用不相关的文本。

在一个案例中，一个小型的 Llama 3.1 8B 模型在有 46 个工具可供考虑时未能完成任务，在只有 19 个工具可供考虑时却成功完成了任务。额外的工具造成了混乱，尽管上下文的长度没有超出限制。根本问题在于，提示中的任何信息都会被模型关注。如果它不知道忽略某些内容，那么这些内容可能会以不希望的方式影响其输出。不相关的内容可能会“窃取”模型的一些注意力并将其引入歧途（例如，不相关的文档可能会导致智能体答非所问）。上下文混淆通常表现为模型做出低质量的反应，将不相关的上下文整合在一起。参考研究论文：《Less is More: Optimizing Function Calling for LLM Execution on Edge Devices》。

这提醒我们，上下文不一定越多越好，尤其是在没有进行相关性管护的情况下。

上下文冲突

上下文冲突是指上下文的某些部分相互矛盾，导致内部不一致，从而破坏模型的推理。如果智能体积累了多条相互冲突的信息，上下文冲突就会发生。

例如，想象一个智能体从两个来源获取数据：一个说 A 航班下午 5 点起飞，另一个说 A 航班下午 6 点起飞。如果两个事实都出现在上下文中，可怜的模型无法知道哪个是正确的；它可能会混淆或生成不正确或不相似的答案。

上下文冲突也经常发生在多轮对话中，因为模型前期的回答尝试会与后来完善的信息一起留在上下文中。

Microsoft 和 Salesforce 的一项研究显示，如果将复杂查询分解为多个聊天机器人回合（逐步添加细节），与在单个提示中提供所有细节相比，前者的最终准确性会显著下降。为什么？因为前期的回合包含来自模型的部分或不正确的中间答案，而这些答案会保留在上下文中。当模型后来尝试用所有信息来回答问题时，它的记忆中仍然包含那些错误的尝试，这些尝试与更正后的信息相冲突，并导致模型偏离正轨。从根本上说，对话的上下文与对话本身发生了冲突。模型可能会无意中使用已经过时的上下文（来自前期的对话轮），这些上下文在添加新信息后不再适用。

在智能体系统中，上下文冲突尤其危险，因为智能体可能会结合来自不同工具或子智能体的输出。如果这些输出不一致，则汇总的上下文就不一致。这样一来，智能体在试图调和矛盾时就会陷入困境或产生无意义的结果。防止上下文冲突需要确保上下文的新鲜度和一致性，例如清除或更新任何过时的信息，不混用未经一致性审查的来源。

上下文泄露和知识冲突

在多个智能体或用户共享记忆存储的系统中，存在信息在上下文间流失的风险。

例如，如果两个独立用户的数据嵌入存在于同一向量数据库中且没有适当的访问控制，响应用户 A 查询的智能体可能会意外检索用户 B 的部分记忆。这种跨上下文泄露可能会暴露私人信息，或在响应中造成混乱。

根据“OWASP 定义的LLM 应用十大风险”，多租户向量数据库必须防范此类泄露：

根据《LLM 08:2025 向量和嵌入弱点，常见的风险之一是上下文泄露：

在多租户环境中，多类用户或应用共享同一个向量数据库，用户或查询之间存在上下文泄露的风险。当来自多个来源的数据相互矛盾时，可能会出现数据联合知识冲突错误。当 LLM 无法使用来自检索增强的新数据取代其在训练中学到的旧知识时，这种情况也可能会发生。

另一方面，LLM 可能难以用记忆中的新信息覆盖其内置的知识。如果模型是根据某个事实进行训练的，而检索到的上下文却表明了相反的情况，那么模型可能会对应该相信哪个事实感到困惑。如果没有适当的设计，智能体可能会混淆上下文或未能用新证据更新旧知识，从而导致得出过时或不正确的答案。

幻觉和错误信息

即使没有长上下文的干扰，幻觉（LLM 编造听起来合理但实际上是虚假的信息）也已是一个老生常谈的问题，而糟糕的记忆管理会加剧这个问题。

如果智能体的记忆缺少一个关键事实，模型可能会用猜测来填补空白，如果这个猜测随后进入上下文（使其受污染），错误就会持续存在。

OWASP LLM 安全报告（LLM09:2025 错误信息）强调错误信息是一个核心漏洞：LLM 可以产生自信但虚构的答案，而用户可能会过度信任它们。一个拥有不良或过时长期记忆的智能体可能会自信地引用去年真实但现在错误的内容，除非其记忆保持更新。

过度依赖 AI 输出（无论是用户还是智能体本身在循环中过度依赖）会使情况变得更糟。如果没有人定期检查记忆中的信息，智能体可能会积累虚假信息。这就是 RAG 经常被用来减少幻觉的原因：检索权威来源，模型就不必编造事实。但如果您的检索拉取了错误的文档（比如包含错误信息的文档），或者早期幻觉没有被去除，系统可能会在所有操作中传播这些错误信息。

总之，记忆管理不善可能会导致错误和误导性的输出，这可能会造成损害，尤其是在高风险情况下（例如在金融或医疗领域提供错误建议）。智能体需要机制来验证或纠正其记忆内容，而不是无条件地信任上下文中的任何内容。

总的来说，给 AI 智能体无限长的记忆或将所有可能的东西都转储到其上下文中并非成功的秘诀。

LLM 应用程序中内存管理的最佳实践

为了避免上述陷阱，开发人员和研究人员为 AI 系统的上下文和记忆管理设计了许多最佳实践。这些做法旨在使 AI 的工作上下文保持精简、相关且更新的状态。以下是一些关键策略，以及它们如何发挥作用的示例。

RAG：使用针对性上下文

RAG 的大部分内容在前面的章节中已有介绍，所以这里仅作简要的实用提醒：

• 使用有针对性的检索，而不是批量加载：只检索最相关的片段，而不是将整个文档或完整的对话历史记录推送到提示中。
• 将 RAG 视为即时记忆调用：仅在需要时才获取上下文，而不是将所有内容跨轮次传递。
• 优先使用感知相关性的检索策略：top-k 语义搜索、倒数排序融合或工具装载过滤等方法有助于减少噪音并提高基础。
• 扩大上下文窗口并不会消除对 RAG 的需求：两个高度相关的段落几乎总是比 20 页松散相关的内容更有效。

也就是说，RAG 并不是要增加更多的上下文，而是要增加合适的上下文。

工具装载

工具装载是指只给模型提供它在执行任务时实际需要的工具。这个词源于游戏：您要选择一种适合当下情况的装备。工具太多会减慢您的速度；错误的工具会导致失败。根据研究论文《Less is more》，LLM 也是如此。当工具数量超过 30 个左右时，描述会开始重叠，模型会变得混乱。当工具数量超过约 100 个时，失败几乎是必然的。这不是一个上下文窗口问题，而是上下文混淆的问题。

RAG-MCP 是一个简单有效的解决办法。它不是将每个工具都放入提示中，而是将工具描述存储在向量数据库中，每个请求只检索最相关的工具。在实际操作中，这样可以使装载保持小型化和专注化，大幅缩短提示，并且可以将工具选择的准确性至多提高 3 倍。

小模型甚至会更快出现这样的问题。研究表明，8B 模型在装载数十种工具时会失败，但在精简装载后会变得成功。动态选择工具（有时先由 LLM 推理它认为需要的工具）可将性能提高 44% ，同时还能降低功耗和缩短延迟。关键点是，大多数智能体只需要少量工具，但随着系统的发展，设计决策需要首先考虑工具装载和 RAG-MCP。

上下文修剪：限制聊天历史记录的长度

如果对话持续了很多轮，累积的聊天历史记录可能会变得太大而无法容纳，导致上下文溢出或对模型造成过多干扰。

修剪是指随着对话的增加，以编程方式删除或缩短对话中不太重要的部分。一种简单的形式是，当您达到一定限制时，删除对话中最早的轮次，只保留最新的 N 条消息。更复杂的修剪可能涉及删除无关的题外话或以前不再需要的指令。修剪的目标是保持上下文窗口不受旧新闻干扰。

例如，如果智能体在 10 轮对话前解决了一个子问题，并且我们已经翻篇，我们可以从上下文中删除该部分历史记录（假设我们已不需要该部分）。许多基于聊天功能的实现方式都是如此：它们会维护一个滚动显示最新消息的窗口。

修剪可以很简单，比如在对话的最早部分被总结或被认为无关紧要后“忘记”这些部分。这样一来，我们就能降低上下文溢出错误的风险，也能减少上下文干扰，使模型不会被旧的或偏离主题的内容干扰。这种方法非常类似于人类可能记不住一个小时谈话中的每一个字，但会记住重点。

如果您对上下文修剪感到困惑，正如作者 Drew Breunig 在此强调的那样，使用 Provence 模型 (`naver/provence-reranker-debertav3-v1`) 可能会有所帮助。Provence 模型是一个轻量级 (1.75 GB)、高效且准确的问答上下文修剪器。它可以将大型文档裁剪为仅与给定查询最相关的文本。您可以按特定时间间隔调用它。

以下是我们在代码中调用 `provence-reranker` 模型来修剪上下文的做法：

# Context pruning with Provence
def prune_with_provence(query: str, context: str, threshold: Optional[float] = None) -> str:
    """
    Prune context using Provence reranker model
    
    Args:
        query: User's query/question
        context: Original context to prune
        threshold: Relevance threshold (0-1) for Provence reranker.
                   If None, uses args.pruning_threshold.
                   0.1 = conservative (recommended, no performance drop)
                   0.3-0.5 = moderate to aggressive pruning
    
    Returns:
        Pruned context with only relevant sentences
    """
    if provence_model is None:
        return context
    
    if threshold is None:
        threshold = args.pruning_threshold
    
    try:
        # Use Provence's process method
        provence_output = provence_model.process(
            question=query,
            context=context,
            threshold=threshold,
            always_select_title=False,
            enable_warnings=False
        )
        
        # Extract pruned context from output
        pruned_context = provence_output.get('pruned_context', context)
        reranking_score = provence_output.get('reranking_score', 0.0)
        
        # Log statistics
        original_length = len(context)
        pruned_length = len(pruned_context)
        reduction_pct = ((original_length - pruned_length) / original_length * 100) if original_length > 0 else 0
        
        if args.verbose:
            rich.print(f"[cyan]📊 Pruning stats: {pruned_length}/{original_length} chars ({reduction_pct:.1f}% reduction, threshold={threshold:.2f}, rerank_score={reranking_score:.3f})[/cyan]")
        
        return pruned_context if pruned_context else context
        
    except Exception as e:
        rich.print(f"[yellow]⚠️ Error in Provence pruning: {str(e)}[/yellow]")
        rich.print(f"[yellow]⚠️ Falling back to original context[/yellow]")
        return context

我们使用 Provence 重排序模型 (`naver/provence-reranker-debertav3-v1`) 来对句子的相关性进行评分。基于阈值的过滤功能可将句子保留在相关性阈值之上。此外，我们引入了一种回退机制，如果修剪失败，我们将返回原始上下文。最后，统计日志在详细模式下跟踪减少百分比。

上下文总结：将旧信息浓缩而非完全放弃

总结是对修剪的补充。当历史记录或知识库变得过于庞大时，您可以使用 LLM 生成重要内容的简短总结，并在未来使用该总结代替完整内容，就像我们在上面的代码中所做的那样。

例如，如果 AI 助手进行了 50 轮对话，系统不是在第 51 轮将全部 50 轮对话发送给模型（很可能容纳不下），而是选择第 1 至 40 轮，让模型用一段话对其总结，然后在下一个提示中只提供该总结和最后的 10 轮对话。这样一来，模型无需每个细节也能知道讨论的内容。早期的聊天机器人用户是手动总结的，他们问聊天机器人：“你能总结一下我们到目前为止谈过的内容吗？”然后带着总结继续进行新的会话。现在总结可以自动进行。总结不仅可以节省上下文窗口的空间，还可以通过去除多余的细节并只保留重要的事实来减少上下文混淆/干扰。

以下展示了我们如何使用 OpenAI 模型（您可以使用任何大型语言模型）来压缩上下文，同时保留所有相关信息，并消除冗余和重复。

# Context summarization
def summarize_context(query: str, context: str) -> str:
    """
    Summarize context using LLM to reduce duplication and focus on relevant information
    
    Args:
        query: User's query/question
        context: Context to summarize
        
    Returns:
        Summarized context
    """
    try:
        summary_prompt = f"""You are an expert at summarizing conversation context.

Your task: Analyze the provided conversation context and produce a condensed summary that fully answers or supports the user's specific question.

The summary must:
1. Preserve every fact, detail, and information that directly relates to the question
2. Eliminate redundancy and duplicate information
3. Maintain chronological flow when relevant
4. Focus on information that helps answer: "{query}"

Context to summarize:
{context}

Provide a concise summary that preserves all relevant information:"""

        summary = llm.invoke(summary_prompt).content
        
        if args.verbose:
            original_length = len(context)
            summary_length = len(summary)
            reduction_pct = ((original_length - summary_length) / original_length * 100) if original_length > 0 else 0
            rich.print(f"[cyan]📝 Summarization stats: {summary_length}/{original_length} chars ({reduction_pct:.1f}% reduction)[/cyan]")
        
        return summary
        
    except Exception as e:
        rich.print(f"[yellow]⚠️ Error in context summarization: {str(e)}[/yellow]")
        rich.print(f"[yellow]⚠️ Falling back to original context[/yellow]")
        return context

重要的是，当上下文得到总结后，模型被琐碎细节或过往错误牵制的可能性会降低（假设总结是准确的）。

不过，总结必须谨慎进行。糟糕的总结可能会遗漏关键细节，甚至引入错误。它本质上是对模型的另一个提示（“总结这个”），因此它可能会产生幻觉或失去细微差别。最佳做法是逐步总结，或许可以保留一些典型事实，不对它们进行总结。

尽管如此，它已经被证明非常有用。在 Gemini 智能体场景中，每隔约 10 万个词元对上下文进行总结是抵消模型重复倾向的一种方法。总结就像对话或数据的压缩记忆。作为开发人员，我们可以通过让智能体针对对话历史记录或长文档定期调用总结函数（可能是一个较小的 LLM 或一个专用例程）来实现这一点。得到的总结会在提示中替代原始内容。这种策略已被广泛使用，以便将上下文限制在一定范围内，并提炼信息。

上下文隔离：尽可能隔离上下文

这在复杂的智能体系统或多步骤工作流程中更为重要。上下文隔离的理念是将一个大任务拆分成较小的孤立任务，每个任务都有自己的上下文，这样就不会积累一个包含所有内容的庞大上下文。每个子智能体或子任务使用特定的上下文处理问题的某一部分，然后由更高级的智能体、主管或协调员整合结果。

Anthropic 的研究策略使用多个子智能体，每个子智能体研究问题的不同方面，各自拥有自己的上下文窗口，而主智能体负责阅读这些子智能体提炼的结果。这种并行的模块化方法意味着没有一个上下文窗口会变得过于臃肿。这也减少了无关信息混淆的可能性，每个线程都紧扣主题（避免上下文混淆），而且在回答具体子问题时不会携带不必要的包袱。从某种意义上说，这就像是在运行独立的思维线程，它们只分享各自的结果，而不是整个思维过程。

在多智能体系统中，这种方法至关重要。如果智能体 A 正在处理任务 A 而智能体 B 正在处理任务 B，那么除非确实需要，否则任何一个智能体都没有理由使用另一个智能体的完整上下文。智能体可以只交换必要的信息。例如，智能体 A 可以通过一个主管智能体将其发现的综合总结传递给智能体 B，同时每个子智能体都维护自己的专用上下文线程。这种设置不需要人机协同干预；它依赖于一个具有启用工具的主管智能体，并进行最小化和受控的上下文共享。

在设计系统时，尽量减少智能体或工具在运行时的必要上下文重叠，可以大大提高系统的清晰度和性能。您可以把它想象成 AI 微服务，每个组件处理自己的上下文，您以受控的方式在它们之间传递消息，而不是在一个单一的上下文中传递消息。这些最佳实践通常会结合使用。此外，这还能让您灵活地修剪琐碎的历史记录，总结重要的旧消息或对话，将详细日志卸载到 Elasticsearch 以获得长期上下文，并在需要时使用检索功能调回任何相关内容。

正如此处提到的那样，我们的指导原则是上下文是一种有限且宝贵的资源。我们希望提示中的每个词元都能发挥作用，换句话说，它应该对输出的质量有所帮助。如果记忆中的某些东西没有发挥其应有的作用（或者更糟糕的是，它们会主动造成混乱），那么我们就应该对其进行修剪、总结或将其去除。

作为开发者，我们现在可以像编写代码一样编程上下文，决定包含哪些信息，如何格式化它，以及何时删除或更新它。通过遵循这些实践，我们可以为 LLM 智能体提供所需的上下文，使其能够执行任务，而不会陷入前面描述的失败模式。其结果是，智能体能够记住应该记住的内容，忘记不需要的内容，并及时检索所需的内容。

结论

记忆不是您添加到智能体中的东西；它是您设计的一部分。短期记忆是智能体的工作记忆板，而长期记忆是其持久的知识存储。RAG 是两者之间的桥梁，将被动的数据存储（如 Elasticsearch）转变为一个主动的回忆机制，能够为输出提供依据并保持智能体的最新状态。

但记忆是把双刃剑。当您让上下文不受控制地增长时，您会导致上下文污染、干扰、混乱和冲突，在共享系统中甚至会导致数据泄露。这就是为什么最重要的记忆工作不是“多存储”，而是“更好地管护”：有选择地检索，积极修剪，仔细总结，避免混合无关的上下文（除非任务真的需要）。

在实践中，好的上下文工程看起来就像良好的系统设计：上下文更小和更充分、组件之间的交互受控、原始状态和您实际希望模型看到的提炼状态清晰分离。如果方法得当，您最终得到的不是一个什么都记得的智能体，而是一个在正确的时间，出于正确的原因，记住正确事情的智能体。

我们已为在 AWS 上运行的所有 Elastic Cloud Serverless 项目完成了一次重大基础设施升级，迁移到了更新、更快的硬件上。此更改已自动推广至所有无服务器项目。它为 AWS 上的 Elasticsearch、Elastic Observability 和 Elastic Security 无服务器项目提供了更高的吞吐量和更低的延迟。

为开发人员带来的关键性能优势

新的 AWS 硬件基础设施支撑着您使用 Elastic Cloud Serverless 所做的一切，为您的应用程序的速度和响应能力带来切实的好处。

降低查询延迟……提高吞吐量

改进后的硬件显著提升了计算资源的速度，这意味着您的搜索查询处理速度比以往任何时候都要快。

• 搜索和向量搜索：无论您是运行传统的全文本查询，还是在生成式 AI 和 Retrieval-Augmented Generation (RAG) 应用中使用尖端的向量搜索，您都会发现延迟明显减少。内部基准测试显示，搜索延迟平均减少了 35%。
• 索引速度更快：数据摄取速率得到优化，使您能够以更高的吞吐量为海量数据和复杂文档建立索引。这对于需要近实时数据可见性的应用程序至关重要。内部基准测试显示，索引吞吐量平均提高了 26%。

在负载下保持稳定性能

无论您的工作负载如何，Elastic Cloud Serverless 都能实时动态地自动扩展，以满足需求，最大限度地减少延迟。通过这次硬件升级，这种扩展性现在变得性能更强且响应更迅速。

• 轻松应对流量高峰：无论您面临的是用户流量的突然激增，还是大规模批量数据的摄取，新的基础设施都能确保您的搜索和索引资源更高效地扩展，从而保持一致的低延迟。
• 优化的计算存储解耦：无服务器架构将计算与存储分离，使工作负载能够独立扩展，从而实现最佳性能和成本效益。速度更快的硬件增强了计算层，最大限度地提高了这种解耦设计的效率。

幕后揭秘：内部基准测试结果

为了量化 AWS 基础设施升级的影响，Elastic 工程团队针对一系列无服务器工作负载进行了全面的内部基准测试。这些工作负载为性能改进提供了经验证据，无论您的用例如何，您都可以期望在应用程序中获得性能提升。

基准测试方法

我们将测试重点放在直接影响开发者体验和应用程序响应速度的关键指标上：响应时间（即延迟）和搜索与索引操作的吞吐量。

• 测试的工作负载：测试包括面向用户的应用程序中典型的高并发搜索操作、复杂的向量搜索查询以及用于可观测性和安全用例的大量数据摄取/索引。特别是，我们的测试方法使用了 Elastic 基准测试工具 Rally 的公开可用的数据集。
  • wikipedia：一个从维基百科文本内容的快照中提取的数据集，用于衡量通用文本搜索性能。
  • MSMARCO-Passage-Ranking：一个源自 Microsoft 机器阅读理解 (MS MARCO) 的数据集，用于衡量稀疏向量字段上的搜索性能。
  • OpenAI_Vector：一个源自 BEIR 的 NQ 并通过 OpenAI 的 text-embedding-ada-002 模型生成的嵌入进行丰富的数据集，用于衡量密集向量字段上的搜索性能。
• 测量：我们比较了新旧基础设施的性能，测量了第 99 百分位数 (P99) 的延迟，以捕捉最坏情况下的尾部延迟性能和每秒操作数。为确保结果的一致性，每个硬件配置文件的每条测试路径都运行了五次。
• 目标：我们的目标是验证基础设施即使在快速自动扩展期间也能持续提供更快、更可预测的全面性能的能力。

性能数据摘要

结果证实，效率和速度都有了明显提高。由于能够使用更少的计算资源完成相同的工作量，这些收益直接转化为更短的用户响应时间和更低的运营成本。

下表详细列出了数量上的改进。数值越大，吞吐量越高；数值越小，延迟越低。

搜索基准测试结果：

索引基准测试结果：

额外收获：成本降低

虽然我们的重点是提供低延迟性能，但新硬件的效率也对 Elasticsearch 项目的成本产生直接的积极影响。

Elasticsearch Serverless 的定价是基于使用量的，这意味着您只需为您所使用的摄取和搜索资源付费。由于更新、更快的硬件效率更高，您的工作负载通常能用更少的资源完成任务，从而降低大多数项目的固有成本。您无需支付高昂的价格，就能获得卓越的性能提升——这就是优化效率的定义。

这对您，开发者来说意味着什么？

此次基础设施升级完全由 Elastic 管理，因此您无需亲自操作——无需迁移，也无需更改配置。改进效果立竿见影，并自动应用于您所有基于 AWS 的无服务器项目。

此升级赋予您以下能力：

• 构建更快的应用程序：专注于功能开发速度，确保您的底层搜索平台能够提供用户所需的速度。
• 自信创新：部署新的搜索、可观测性和安全功能（包括向量搜索和相关性排序等复杂的 AI 功能），并确保平台能够以最高性能处理负载。
• 简化堆栈：使用完全托管的服务来处理基础设施管理、容量规划和扩展，这样您就可以专注于代码和数据。
  

要求

• NodeJS 18 或更高版本
• OpenAI API密钥
• Elasticsearch 8.x+ 部署

为何在生产级人机协同 (HITL) 系统里采用 LangGraph？

在先前的一篇文章中，我们介绍了 LangGraph 以及它借助 LLM 和条件边来构建 RAG 系统的优势，该系统能够自动做出决策并展示结果。然而，有时我们并不希望系统实现端到端的自主运行，而是期望用户在执行循环中能够选择选项并做出决策。这一概念被命名为“人机协同”。

人机协同或人工介入

这是一种 AI 理念，让真人与 AI 系统进行交互，从而提供更多背景信息、评估回应内容、编辑回应结果、请求更多信息等。在合规、决策制定或内容生成等容错率低的场景中，这种理念非常实用，有助于提升 LLM 输出结果的可靠性。

一个常见的例子是，当你的编程助手请求你授权在终端执行某个特定命令时，或者在开始编程前，向你展示分步思考过程以供你审批。

Elasticsearch + LangGraph：它们如何交互

LangChain 允许我们将 Elasticsearch 用作向量存储库，并在 LangGraph 应用中执行查询操作。这对于执行全文检索或语义搜索十分有用，而 LangGraph 则用于定义特定的工作流、工具以及交互方式。此外，它还引入 HITL 作为与用户的额外交互层。

实际应用：人机协同

让我们设想这样一种情形：一位律师就其近期承接的案件存在疑问。如果没有合适的工具，他需要手动查阅法律文章和判例，完整阅读后，再解读它们如何适用于自己所接的案件情况。然而，借助 LangGraph 和 Elasticsearch，我们能够构建一个系统，该系统可搜索法律判例数据库，并生成一份融入律师所提供具体细节和背景信息的案件分析报告。

工作流始于律师提交法律问题。系统在 Elasticsearch 中执行向量搜索，检索出最相关的判例，并以自然语言的形式呈现给律师供其选择。律师选择后，LLM 生成分析草案，并检查信息是否完整。此时，工作流有两条路径：如果一切清晰明确，则直接生成最终分析报告；如果存在疑问，则暂停并请求律师作出澄清。待缺失的背景信息提供完毕后，系统会综合考虑这些澄清内容，完成分析并返回结果。

以下是 LangGraph 绘制的图表，显示了应用程序在开发结束时的效果。每个节点代表一种工具或功能：

数据集

以下是为本次示例所使用的数据集。该数据集包含一系列法律判例，每个判例均描述了一起涉及服务延误的案件，涵盖法院的判决依据以及最终判决结果。

[
  {
    "pageContent": "Legal precedent: Case B - Service delay not considered breach. A consulting contract used term 'timely delivery' without specific dates. A three-week delay occurred but contract lacked explicit schedule. Court ruled no breach as parties had not defined concrete timeline and delay did not cause demonstrable harm.",
    "metadata": {
      "caseId": "CASE-B-2022",
      "contractType": "consulting agreement",
      "delayPeriod": "three weeks",
      "outcome": "no breach found",
      "reasoning": "no explicit deadline defined, no demonstrable harm",
      "keyTerms": "timely delivery, open terms, schedule definition",
      "title": "Case B: Delay Without Explicit Schedule"
    }
  },
  ...
]

摄取和索引设置

索引设置和数据摄取逻辑在 dataIngestion.ts 文件中定义，在该文件中我们列出了用于处理索引创建的函数。此设置与 LangChain 针对 Elasticsearch 的向量存储接口兼容。

注意：映射设置也包含在 dataIngestion.ts 文件中。

安装软件包并设置环境变量

让我们使用默认设置初始化一个 Node.js 项目，并引入

• @elastic/elasticsearch：这是适用于 Node.js 的 Elasticsearch 客户端，用于建立连接、创建索引以及执行查询操作。
• @langchain/community：提供对社区支持工具的集成功能，其中包含 ElasticVectorSearch 存储库。
• @langchain/core：LangChain 的核心构建模块，涵盖链、提示词以及工具函数等。
• @langchain/langgraph：增添基于图形的编排功能，支持具备节点、边以及状态管理的工作流。
• @langchain/openai：通过 LangChain 提供对 OpenAI 模型（LLM 及嵌入向量模型）的访问接口。
• dotenv：将环境变量从 .env 文件加载至 process.env 中。
• tsx：是一个用于执行 TypeScript 代码的实用工具。

在控制台中运行以下命令以安装所有相关组件：

npm install @elastic/elasticsearch @langchain/community @langchain/core @langchain/langgraph @langchain/openai dotenv --legacy-peer-deps && npm install --save-dev tsx

创建 .env 文件来设置环境变量：

ELASTICSEARCH_ENDPOINT=
ELASTICSEARCH_API_KEY=
OPENAI_API_KEY=

我们将采用 TypeScript 进行代码编写，原因在于它能提供一层类型安全保障，同时带来更优的开发体验。创建一个名为 main.ts 的 TypeScript 文件，并将下一节的代码插入其中。

软件包导入

在 main.ts 文件中，我们首先导入所需的模块，并初始化环境变量配置。这涵盖核心的 LangGraph 组件、OpenAI 模型集成以及 Elasticsearch 客户端。

我们还从 dataIngestion.ts 文件导入以下各项：

• ingestData：创建索引并摄取数据的函数。
• Document 与 DocumentMetadata：用于定义数据集文档结构的接口。

Elasticsearch 向量存储客户端、嵌入客户端以及 OpenAI 客户端

此代码将初始化向量存储、嵌入客户端和一个 OpenAI 客户端。

const VECTOR_INDEX = "legal-precedents";

const llm = new ChatOpenAI({ model: "gpt-4o-mini" });
const embeddings = new OpenAIEmbeddings({
  model: "text-embedding-3-small",
});

const esClient = new Client({
  node: process.env.ELASTICSEARCH_ENDPOINT,
  auth: {
    apiKey: process.env.ELASTICSEARCH_API_KEY ?? "",
  },
});

const vectorStore = new ElasticVectorSearch(embeddings, {
  client: esClient,
  indexName: VECTOR_INDEX,
});

应用程序工作流状态架构将有助于节点之间的通信：

const LegalResearchState = Annotation.Root({
  query: Annotation(),
  analyzedConcepts: Annotation(),
  precedents: Annotation(),
  selectedPrecedent: Annotation(),
  draftAnalysis: Annotation(),
  ambiguityDetected: Annotation(),
  userClarification: Annotation(),
  finalAnalysis: Annotation(),
});

在状态对象中，我们将传递用户查询内容、从查询中提取的概念、检索到的法律判例以及检测到的任何歧义信息至各节点。该状态对象还会跟踪用户选定的判例、过程中生成的草案分析，以及在所有澄清工作完成后生成的最终分析。

节点

searchPrecedents：此节点基于用户输入，在 Elasticsearch 向量存储库中执行相似性搜索。它最多可检索 5 份匹配文件，并打印出来供用户查看。

async function searchPrecedents(state: typeof LegalResearchState.State) {
  console.log(
    "📚 Searching for relevant legal precedents with query:\n",
    state.query
  );

  const results = await vectorStore.similaritySearch(state.query, 5);
  const precedents = results.map((d) => d as Document);

  console.log(`Found ${precedents.length} relevant precedents:\n`);

  for (let i = 0; i < precedents.length; i++) {
    const p = precedents[i];
    const m = p.metadata;
    console.log(
      `${i + 1}. ${m.title} (${m.caseId})\n` +
        `   Type: ${m.contractType}\n` +
        `   Outcome: ${m.outcome}\n` +
        `   Key reasoning: ${m.reasoning}\n` +
        `   Delay period: ${m.delayPeriod}\n`
    );
  }

  return { precedents };
}

precedentSelection：此node允许用户使用自然语言选择由最接近搜索检索到的、最匹配问题的用例。此时，应用程序中断工作流并等待用户输入。

function precedentSelection(state: typeof LegalResearchState.State) {
  console.log("\n⚖️  HITL #1: Human input needed\n");
  const question = "👨‍⚖️  Which precedent is most similar to your case? ";
  const userChoice = interrupt({ question });

  return { userChoice };
}

selectPrecedent：此节点会将用户输入内容以及检索到的文档一并发送，以供解析，进而从中选出一个文档。LLM 通过返回一个数字来完成该任务，此数字代表模型依据用户自然语言输入所推断出的文档。

async function selectPrecedent(state: typeof LegalResearchState.State) {
  const precedents = state.precedents || [];
  const userInput = (state as any).userChoice || "";

  const precedentsList = precedents
    .map((p, i) => {
      const m = p.metadata;
      return `${i + 1}. ${m.caseId}: ${m.title} - ${m.outcome}`;
    })
    .join("\n");

  const structuredLlm = llm.withStructuredOutput({
    name: "precedent_selection",
    schema: {
      type: "object",
      properties: {
        selected_number: {
          type: "number",
          description:
            "The precedent number selected by the lawyer (1-based index)",
          minimum: 1,
          maximum: precedents.length,
        },
      },
      required: ["selected_number"],
    },
  });

  const prompt = `
    The lawyer said: "${userInput}"

    Available precedents:
    ${precedentsList}

    Which precedent number (1-${precedents.length}) matches their selection?
  `;

  const response = await structuredLlm.invoke([
    {
      role: "system",
      content:
        "You are an assistant that interprets lawyer's selection and returns the corresponding precedent number.",
    },
    { role: "user", content: prompt },
  ]);

  const selectedIndex = response.selected_number - 1;
  const selectedPrecedent = precedents[selectedIndex] || precedents[0];

  console.log(`✅ Selected: ${selectedPrecedent.metadata.title}\n`);
  return { selectedPrecedent };
}

createDraft：此节点根据用户选择的判例生成初步法律分析。它借助 LLM 评估所选判例如何适用于律师提出的问题，并判断系统是否具备足够信息以继续推进后续流程。

如果判例可直接适用，该节点将生成一份草案分析，并沿着正确路径直接跳转至最终节点。若 LLM 检测到模棱两可之处，例如未明确的合同条款、缺失的时间线细节或模糊的条件，它会返回一个提示需要澄清的标识，同时附上必须提供的具体信息列表。在此情况下，歧义将触发图中的左侧路径。

async function createDraft(state: typeof LegalResearchState.State) {
  console.log("📝 Drafting initial legal analysis...\n");

  const precedent = state.selectedPrecedent;
  if (!precedent) return { draftAnalysis: "" };

  const m = precedent.metadata;

  const structuredLlm = llm.withStructuredOutput({
    name: "draft_analysis",
    schema: {
      type: "object",
      properties: {
        needs_clarification: {
          type: "boolean",
          description:
            "Whether the analysis requires clarification about contract terms or context",
        },
        analysis_text: {
          type: "string",
          description: "The draft legal analysis or the ambiguity explanation",
        },
        missing_information: {
          type: "array",
          items: { type: "string" },
          description:
            "List of specific information needed if clarification is required (empty if no clarification needed)",
        },
      },
      required: ["needs_clarification", "analysis_text", "missing_information"],
    },
  });

  const prompt = `
    Based on this precedent:
    Case: ${m.title}
    Outcome: ${m.outcome}
    Reasoning: ${m.reasoning}
    Key terms: ${m.keyTerms}

    And the lawyer's question: "${state.query}"

    Draft a legal analysis applying this precedent to the question.
    
    If you need more context about the specific contract terms, timeline details, 
    or other critical information to provide accurate analysis, set needs_clarification 
    to true and list what information is missing.
    
    Otherwise, provide the legal analysis directly.
  `;

  const response = await structuredLlm.invoke([
    {
      role: "system",
      content:
        "You are a legal research assistant that analyzes cases and identifies when additional context is needed.",
    },
    { role: "user", content: prompt },
  ]);

  let displayText: string;
  if (response.needs_clarification) {
    const missingInfoList = response.missing_information
      .map((info: string, i: number) => `${i + 1}. ${info}`)
      .join("\n");
    displayText = `AMBIGUITY DETECTED:\n${response.analysis_text}\n\nMissing information:\n${missingInfoList}`;
  } else {
    displayText = `ANALYSIS:\n${response.analysis_text}`;
  }

  console.log(displayText + "\n");

  return {
    draftAnalysis: displayText,
    ambiguityDetected: response.needs_clarification,
  };
}

图中的两条路径如下所示：

左侧路径包含一个额外的节点，用于处理澄清。

requestClarification:当系统判定草稿分析缺少关键背景信息时，此节点会触发第二轮人机协同步骤。工作流会被中断，系统会要求用户对前一节点检测到的缺失合同细节进行说明。

function requestClarification(state: typeof LegalResearchState.State) {
  console.log("\n⚖️  HITL #2: Additional context needed\n");
  const userClarification = interrupt({
    question: "👨‍⚖️  Please provide clarification about your contract terms:",
  });
  return { userClarification };
}

generateFinalAnalysis：此节点在必要时会将用户所选判例与用户提供的额外背景信息相结合，从而生成最终法律分析。借助上一轮 HITL 步骤中收集到的澄清信息，LLM 会综合判例的判决依据、用户提供的合同细节以及判定违约是否可能发生的条件，形成最终分析结果。

该节点可提供完整的分析，将法律解释和实际建议融为一体。

async function generateFinalAnalysis(state: typeof LegalResearchState.State) {
  console.log("📋 Generating final legal analysis...\n");

  const precedent = state.selectedPrecedent;
  if (!precedent) return { finalAnalysis: "" };

  const m = precedent.metadata;

  const prompt = `
    Original question: "${state.query}"
    
    Selected precedent: ${m.title}
    Outcome: ${m.outcome}
    Reasoning: ${m.reasoning}
    
    Lawyer's clarification: "${state.userClarification}"
    
    Provide a comprehensive legal analysis integrating:
    1. The selected precedent's reasoning
    2. The lawyer's specific contract context
    3. Conditions for breach vs. no breach
    4. Practical recommendations
  `;

  const response = await llm.invoke([
    {
      role: "system",
      content:
        "You are a legal research assistant providing comprehensive analysis.",
    },
    { role: "user", content: prompt },
  ]);

  const finalAnalysis = response.content as string;

  console.log(
    "\n" +
      "=".repeat(80) +
      "\n" +
      "⚖️  FINAL LEGAL ANALYSIS\n" +
      "=".repeat(80) +
      "\n\n" +
      finalAnalysis +
      "\n\n" +
      "=".repeat(80) +
      "\n"
  );

  return { finalAnalysis };
}

构建图表：

const workflow = new StateGraph(LegalResearchState)
  .addNode("analyzeQuery", analyzeQuery)
  .addNode("searchPrecedents", searchPrecedents)
  .addNode("precedentSelection", precedentSelection)
  .addNode("selectPrecedent", selectPrecedent)
  .addNode("createDraft", createDraft)
  .addNode("requestClarification", requestClarification)
  .addNode("generateFinalAnalysis", generateFinalAnalysis)
  .addEdge("__start__", "analyzeQuery")
  .addEdge("analyzeQuery", "searchPrecedents")
  .addEdge("searchPrecedents", "precedentSelection") // HITL #1
  .addEdge("precedentSelection", "selectPrecedent")
  .addEdge("selectPrecedent", "createDraft")
  .addConditionalEdges(
    "createDraft",
    (state: typeof LegalResearchState.State) => {
      // If ambiguity detected, request clarification (HITL #2)
      if (state.ambiguityDetected) return "needsClarification";
      // Otherwise, generate final analysis
      return "final";
    },
    {
      needsClarification: "requestClarification",
      final: "generateFinalAnalysis",
    }
  )
  .addEdge("requestClarification", "generateFinalAnalysis") // HITL #2
  .addEdge("generateFinalAnalysis", "__end__");

从图中，我们可以看出条件边定义了选择“最终”路径的条件。如图所示，现在的决策取决于草案分析是否检测到存在需要额外澄清的歧义。

将所有内容汇总起来执行：

await ingestData();

// Compile workflow
const app = workflow.compile({ checkpointer: new MemorySaver() });
const config = { configurable: { thread_id: "hitl-circular-thread" } };

await saveGraphImage(app);

// Execute workflow
const legalQuestion =
    "Does a pattern of repeated delays constitute breach even if each individual delay is minor?"; 

console.log(`⚖️  LEGAL QUESTION: "${legalQuestion}"\n`);

let currentState = await app.invoke({ query: legalQuestion }, config);

// Handle all interruptions in a loop
while ((currentState as any).__interrupt__?.length > 0) {
  console.log("\n💭 APPLICATION PAUSED WAITING FOR USER INPUT...");

  const interruptQuestion = (currentState as any).__interrupt__[0]?.value
    ?.question;
  const userChoice = await getUserInput(
    interruptQuestion || "👤 YOUR CHOICE: "
  );

  currentState = await app.invoke(
    new Command({ resume: userChoice }),
    config
  );
}

执行脚本：

分配好所有代码后，让我们在终端上执行 main.ts 文件，编写以下命令：

tsx main.ts

脚本执行后，问题“即便每次单独的延误都较为轻微，一连串重复出现的延误是否构成违约？”将被发送至 Elasticsearch 以执行邻近搜索，从索引中检索到的结果将予以展示。应用程序检测到多个相关判例与查询匹配，因此暂停执行，并请求用户协助明确哪个法律判例最为适用：

📚 Searching for relevant legal precedents with query:
 Does a pattern of repeated delays constitute breach even if each individual delay is minor?
Found 5 relevant precedents:

1. Case H: Pattern of Repeated Delays (CASE-H-2021)
   Type: ongoing service agreement
   Outcome: breach found
   Key reasoning: pattern demonstrated failure to perform, cumulative effect
   Delay period: multiple instances

2. Case E: Minor Delay Quality Maintained (CASE-E-2022)
   Type: service agreement
   Outcome: minor breach only
   Key reasoning: delay minimal, quality maintained, termination unjustified
   Delay period: five days

3. Case A: Delay Breach with Operational Impact (CASE-A-2023)
   Type: service agreement
   Outcome: breach found
   Key reasoning: delay affected operations and caused financial harm
   Delay period: two weeks

4. Case B: Delay Without Explicit Schedule (CASE-B-2022)
   Type: consulting agreement
   Outcome: no breach found
   Key reasoning: no explicit deadline defined, no demonstrable harm
   Delay period: three weeks

5. Case C: Justified Delay External Factors (CASE-C-2023)
   Type: construction service
   Outcome: no breach found
   Key reasoning: external factors beyond control, force majeure applied
   Delay period: one month

⚖️  HITL #1: Human input needed

💭 APPLICATION PAUSED WAITING FOR USER INPUT...
👨‍⚖️  Which precedent is most similar to your case? 

这款应用程序的有趣之处在于，我们能够使用自然语言来选择一个选项，让 LLM 解析用户输入内容，从而确定正确选择。让我们看看，若输入文本“Case H”会发生什么。

💭 APPLICATION PAUSED WAITING FOR USER INPUT...
👨‍⚖️  Which precedent is most similar to your case? Case H

✅ Selected: Case H: Pattern of Repeated Delays

📝 Drafting initial legal analysis...

AMBIGUITY DETECTED:
Based on Case H, a pattern of repeated delays can indeed constitute a breach of contract, even if each individual delay is minor. The outcome in Case H indicates that the cumulative effect of these minor delays led to a significant failure to perform the contractual obligations adequately. The reasoning emphasizes that consistent performance is critical in fulfilling the terms of a contract. Therefore, if the repeated delays create a situation where the overall performance is hindered, this pattern could be interpreted as a breach. However, the interpretation may depend on the specific terms of the contract at issue, as well as the expectations of performance set forth in that contract.

Missing information:
1. Specific contract terms regarding performance timelines
2. Details on the individual delays (duration, frequency)
3. Context on consequences of delays stated in the contract
4. Other parties' expectations or agreements related to performance


⚖️  HITL #2: Additional context needed


💭 APPLICATION PAUSED WAITING FOR USER INPUT...
👨‍⚖️  Please provide clarification about your contract terms:

模型会采纳用户的澄清信息，并将其整合进工作流，在提供足够背景信息后开展最终分析。在此步骤中，系统还会利用先前检测到的歧义：草案分析指出合同中缺失的细节，这些细节可能对法律解释产生实质性影响。这些“缺失信息”项为模型提供指引，助其确定在给出可靠最终意见前，为消除不确定性而必须获取的关键澄清内容。

用户必须在下一次输入中包含此前被要求澄清的内容。我们以如下内容为例进行尝试：“合同要求‘及时交付’，但未规定时间期限。在 6 个月内出现 8 次 2-4 天的延误。因错过 3 次客户截止日期，造成 5 万美元损失。已通知供应商，但此类情况仍持续发生。”

💭 APPLICATION PAUSED WAITING FOR USER INPUT...
👨‍⚖️  Please provide clarification about your contract terms: Contract requires "prompt delivery" without timelines. 8 delays of 2-4 days over 6 months. $50K in losses from 3 missed client deadlines. Vendor notified but pattern continued.

📋 Generating final legal analysis...

================================================================================
⚖️  FINAL LEGAL ANALYSIS
================================================================================

To analyze the question of whether a pattern of repeated minor delays constitutes a breach of contract, we need to combine insights from the selected precedent, the specifics of the lawyer's contract situation, conditions that typically govern breach versus non-breach, and practical recommendations for the lawyer moving forward.

### 1. Selected Precedent's Reasoning

The precedent case, referred to as Case H, found that a pattern of repeated delays amounted to a breach of contract. The court reasoned that even minor individual delays, when considered cumulatively, demonstrated a failure to perform as stipulated in the contract. The underlying rationale was that the cumulative effect of these minor delays could significantly undermine the purpose of the contract, which typically aims for timely performance and reliable delivery.

### 2. Lawyer's Specific Contract Context

In the lawyer's situation, the contract specified "prompt delivery" but did not provide a strict timeline. The vendor experienced 8 delays ranging from 2 to 4 days over a period of 6 months. These delays culminated in $50,000 in losses due to three missed client deadlines. The vendor was notified regarding these delays; however, the pattern of delays persisted.

Key considerations include:
- **Nature of the Obligations**: While “prompt delivery” does not define a strict timeline, it does imply an expectation for timely performance.
- **Material Impact**: The missed client deadlines indicate that these delays had a material adverse effect on the lawyer's ability to fulfill contractual obligations to third parties, likely triggering damages.

### 3. Conditions for Breach vs. No Breach

**Conditions for Breach**:
- **Pattern and Cumulative Effect**: Similar to the reasoning in Case H, evidence of a habitual pattern of delays can amount to a breach. Even if individual delays are minor, when combined, they may show a lack of diligence or reliability by the vendor.
- **Materiality**: The impact of these delays is crucial. If the cumulative delays adversely affect the contract's purpose or cause significant losses, this reinforces the case for a breach.
- **Notification and Opportunity to Cure**: The fact that the vendor was notified of the delays and failed to rectify the behavior can often be interpreted as a further indication of breach.

**Conditions for No Breach**:
- **Non-Material Delays**: If the delays did not affect the overall contractual performance or client obligations, this may lessen the likelihood of establishing a breach. However, given the risks and losses involved, this seems less relevant in this scenario.
- **Force Majeure or Justifiable Delays**: If the vendor could show that these delays were due to justify circumstances not within their control, it may potentially provide a defense against breach claims.

### 4. Practical Recommendations

1. **Assess Damages**: Document the exact nature of the financial losses incurred due to the missed deadlines to substantiate claims of damages.
  
2. **Gather Evidence**: Collect all communication regarding the delays, including any notifications sent to the vendor about the issues.

3. **Consider Breach of Contract Action**: Based on the precedent and accumulated delays, consider formalized communication to the vendor regarding a breach of contract claim, highlighting both the pattern and the impact of these repeated delays.

4. **Evaluate Remedies**: Depending upon the contract specifics, the lawyer may wish to pursue several remedies, including:
   - **Compensatory Damages**: For the financial losses due to missed deadlines.
   - **Specific Performance**: If timely delivery is critical and can still be enforced.
   - **Contract Termination**: Depending on the severity, terminating the contract and seeking replacements may be warranted.

5. **Negotiate Terms**: If continuing to work with the current vendor is strategic, the lawyer should consider renegotiating terms for performance guarantees or penalties for further delays.

6. **Future Contracts**: In future contracts, consider including explicit timelines and conditions for prompt delivery, as well as specified damages for delays to better safeguard against this issue.

By integrating the legal principles from the precedent with the specific context and conditions outlined, the lawyer can formulate a solid plan to address the repeated delays by the vendor effectively.

此输出展示了工作流的最终阶段，在该阶段，模型将所选判例 (Case H) 与律师的澄清信息相结合，以生成一份完整的法律分析报告。系统解释了延误交付很可能构成违约的原因，列举了支持这一解释的各项因素，并给出了切实可行的建议。总体而言，该输出展示了 HITL 澄清如何消除歧义，并使模型能够生成有充分依据、贴合具体情境的法律意见。

其他真实场景

这种借助 Elasticsearch、LangGraph 以及人机协同技术的应用，在其他各类应用程序中也可能颇具价值，例如：

• 在工具调用执行前对其进行审查，例如在金融交易领域，人类会在下买入/卖出订单前予以批准。
• 在需要时提供额外参数，例如在客户支持分流场景中，当 AI 对客户问题存在多种可能的解读时，人类客服人员会选择正确的问题类别。

还有大量有待发掘的用例，在这些用例中，人机协同将成为具有变革性的关键因素。

结论

借助 LangGraph 和 Elasticsearch，我们能够构建具备自主决策能力且可作为线性工作流运行的智能体，或者构建具有条件判断功能、可依据不同条件选择不同路径的智能体。引入人机协同机制后，这些智能体能在决策过程中让实际用户参与进来，以填补背景信息空白，并在容错性至关重要的系统中请求用户确认。

此方法的优势之一在于，能够借助 Elasticsearch 的功能对大规模数据集进行筛选，随后利用 LLM 获取用户所选的单一文档。若仅使用 Elasticsearch 完成最后这一步骤，难度会大得多，因为人类在运用自然语言指代某个结果时，方式多种多样。

这种方法能够确保系统保持高速运行且令牌使用高效，因为我们仅向 LLM 发送做出最终决策所需的信息，而非整个数据集。与此同时，该方法还能使系统在检测用户意图方面保持高度精准，并不断迭代，直至选定用户期望的选项。

我们的目标是转向一种自动化、自适应的方法，能够同时处理日志解析（字段提取）和日志分区（来源识别）。我们假设，大语言模型（LLM）凭借对代码语法与语义模式的理解，能够在最少人工干预的情况下自动处理这些任务。

我们很高兴地宣布，此功能已在 Streams 中正式推出！

数据集描述

我们选择了Loghub 日志集合用于概念验证。我们的调查从以下关键领域选取了代表性样本：

• 分布式系统：我们使用了 Hadoop 分布式文件系统 (HDFS) 和 Spark 数据集。这些日志混合了大数据平台典型的信息、调试和错误消息。
• 服务器与 Web 应用：Apache Web 服务器和 OpenSSH 的日志提供了访问、错误以及与安全相关事件的重要信息来源，这对于监控 Web 流量和检测潜在威胁至关重要。
• 操作系统：我们纳入了 Linux 和 Windows 日志。这些数据集代表了运维团队日常处理的常见、半结构化系统级事件。
• 移动系统：为确保模型能处理移动环境日志，我们加入了 Android 数据集。这些日志通常较为冗长，涵盖了移动设备上广泛的应用程序和系统级活动。
• 超级计算机：为测试在高性能计算环境下的表现，我们引入了 BGL 数据集，其特点是包含使用特定领域术语的高度结构化日志。

Loghub 集合的一个关键优势在于，其日志基本未经清洗处理和标注，真实模拟了具有微服务架构的、嘈杂的线上生产环境。

日志示例：

[Sun Dec 04 20:34:21 2005] [notice] jk2_init() Found child 2008 in scoreboard slot 6
[Sun Dec 04 20:34:25 2005] [notice] workerEnv.init() ok /etc/httpd/conf/workers2.properties
[Mon Dec 05 11:06:51 2005] [notice] workerEnv.init() ok /etc/httpd/conf/workers2.properties
17/06/09 20:10:58 INFO output.FileOutputCommitter: Saved output of task 'attempt_201706092018_0024_m_000083_1138' to hdfs://10.10.34.11:9000/pjhe/test/1/_temporary/0/task_201706092018_0024_m_000083
17/06/09 20:10:58 INFO mapred.SparkHadoopMapRedUtil: attempt_201706092018_0024_m_000083_1138: Committed

此外，我们还搭建了一个包含典型 Web 应用与数据库的 Kubernetes 集群，用于在最常见的场景中采集更多日志。

常见日志字段示例：时间戳、日志级别（INFO、WARN、ERROR）、来源、消息内容。

使用 LLM 进行少样本日志解析

我们的首轮实验聚焦于一个根本问题：LLM 能否可靠地识别关键字段，并生成一致的解析规则来提取它们？

我们要求模型分析原始日志样本，并以正则表达式和 Grok 格式生成解析规则。结果显示，此方法潜力巨大，但也面临显著的实现挑战。

高置信度与上下文感知

初步结果令人鼓舞。LLM 展现出强大的能力，能高置信度地生成与提供的少数样本相匹配的解析规则。除了简单的模式匹配，模型还展现出对日志的理解能力 — 它能正确识别并命名产生日志的来源服务（例如健康追踪应用、Nginx Web 应用、Mongo 数据库）。

输入样本的“恰到好处”困境

我们的实验很快暴露出一个明显的鲁棒性问题，即对输入样本极其敏感。模型的性能会根据提示中包含的具体日志样本而剧烈波动。我们观察到一个日志相似性难题：样本里的日志需要达到适中的多样性水平，从而避免：

• 过于同质（过拟合）：如果输入日志过于相似，LLM 倾向于过度具体化。它会把可变数据（例如堆栈跟踪里的具体 Java 类名）当成模板的固定部分。这导致生成的规则非常脆弱，只能覆盖极少部分日志，并提取出无用的字段。
• 过于异质（困惑）：反之，如果样本包含显著的格式差异（或更糟，包含了“垃圾日志”），模型就难以找到共同模式。它往往会生成复杂但有缺陷的正则表达式，或直接将整行内容过度泛化为一个单一的消息块字段。

上下文窗口限制

我们还遇到了上下文窗口瓶颈。当输入日志较长、异构或包含大量可提取字段时，模型的输出质量常常会下降，变得“混乱”或过长而超出输出上下文窗口。在这种情况下，分块会有所帮助。通过使用基于字符和基于实体的分隔符来分割日志，我们可以帮助模型专注于提取主要字段，而不被噪声淹没。

一致性与标准化差距

即使模型成功生成规则，我们也注意到一些细微的不一致：

• 服务命名差异：模型在不同运行中会对同一实体使用不同名称（例如将来源标记为“Spark”“Apache Spark”“Spark Log Analytics”）。
• 字段命名差异：字段名称缺乏标准化（例如，id vs. service.id vs. device.id）。我们使用标准化的 Elastic 字段命名规范对名称进行了统一。
• 解析粒度差异：字段提取的粒度因输入日志之间的相似程度而异。

日志格式指纹

为了解决日志相似性问题，我们引入了一种高性能的启发式方法：日志格式指纹（LFF）。

我们不再将原始、嘈杂的日志直接输入 LLM，而是首先应用一种确定性转换来揭示每条消息的底层结构。这个预处理步骤抽象掉变量数据，生成一个简化的“指纹”，使我们能够对相关日志进行分组。

映射逻辑很简单，以确保速度和一致性：

1. 数字抽象：任何数字序列（0–9）都会替换为单个“0”。
2. 文本抽象：任何由字母字符及其间空白组成的序列都会替换为单个“a”。
3. 空白字符规范化：所有空白字符序列被压缩为单个空格。
4. 符号保留：标点符号和特殊字符被保留，因为它们通常是日志结构最有力的指示符。

我们引入了日志映射方法。基本映射模式包括以下几种：

• 任意长度的数字（0–9）→ 替换为单个“0”。
• 任意长度的文本（字母字符及空白）→ 替换为单个“a”。
• 空格、制表符和换行符 → 合并为一个空格。

让我们看一个这种映射如何转换日志的例子。

因此我们得到如下日志“掩码”（指纹）：

请注意前两个日志的指纹。尽管时间戳、来源类名和消息内容不同，但它们的前缀（0/0/0 0:0:0 a a.a:）完全一致。这种结构上的一致性使我们能够自动将这些日志归入同一个聚类。这种结构上的一致性使我们能自动把这些日志分桶到同一个聚类中。

第三个日志会生成完全不同的指纹（0-0-0...），这使我们能够在调用 LLM 之前就用算法将其与第一组区分开来。这使我们在调用LLM 之前 ，通过算法将其与第一组分离。

奖励部分：使用 ES|QL 进行即时实施

在 Discover 中运行这条查询就能做到这一点，非常简单。

FROM loghub |
EVAL pattern = REPLACE(REPLACE(REPLACE(REPLACE(raw_message, "[ \t\n]+", " "), "[A-Za-z]+", "a"), "[0-9]+", "0"), "a( a)+", "a") |
STATS total_count = COUNT(), ratio = COUNT() / 2000.0, datasources=VALUES(filename), example=TOP(raw_message, 3, "desc") BY SUBSTRING(pattern, 0, 15) |
SORT total_count DESC |
LIMIT 100

查询解析：

FROM loghub：指向包含原始日志数据的索引。

EVAL pattern =…：核心映射逻辑。我们通过链式 REPLACE 函数执行抽象化处理（例如将数字替换为“0”、文本替换为“a”等），并将结果保存至“pattern”字段。

STATS [column1 =] expression1, … BY SUBSTRING(pattern, 0, 15):

这是一个集群步骤。我们将具有前 15 个字符相同的日志进行分组，并创建聚合字段，例如每组的日志总数、日志数据源列表、模式前缀以及 3 条日志示例。

SORT total_count DESC | LIMIT 100：显示出现频率最高的前 100 个日志模式

查询结果的可视化如下所示：

如可视化所示，这种“无需 LLM”的方法能够以很高的准确率对日志进行分区/归因分组。它（基于 LogHub 标签）在 16 个数据源中有 10 个实现了几乎完全的聚类（>90%），并在 16 个数据源中的 13 个实现了多数聚类（>60%），且无需额外清洗、预处理或微调。

日志格式指纹为日志模式分析等复杂的 ML 解决方案提供了一种务实、高效的替代与补充方案。它能立即洞察日志间的关系，并有效管理大型日志集群。

• 作为基础组件的多功能性

借助 ES|QL 实现，LFF 既可作为独立工具用于快速数据诊断/可视化，也可作为日志分析流水线中的基础构件，支撑高吞吐量场景。

• 灵活性

LFF 易于定制和扩展以捕获特定模式，例如十六进制数和 IP 地址。

• 确定性稳定性

与基于 ML 的聚类算法不同，LFF 逻辑简单且确定。新传入的日志不会追溯性地影响现有的日志聚类。

• 性能与内存

它需要最少的内存，无需训练或 GPU，非常适合实时高吞吐量环境。

结合日志格式指纹与 LLM

为了验证所提出的混合架构，每个实验都包含来自每个数据源的日志的随机 20% 子集。此约束模拟了现实世界的生产环境，在该环境中，日志是批量处理的，而不是作为一个整体的历史转储进行处理。

目标是证明 LFF 能作为有效的压缩层。我们希望证明，即使只用少量经过筛选的样本，也能生成高覆盖率的解析规则，并成功泛化到整个数据集。

执行管道

我们实现了一个多阶段流程，在数据到达 LLM 之前对其进行过滤、聚类和应用分层抽样。

1. 两阶段分层聚类

• 子类（精确匹配）：通过完全相同的指纹对日志进行聚合。同一子类的每个日志共享完全相同的格式结构。
• 异常值清理：丢弃占总日志量少于 5% 的任何子类，这确保 LLM 聚焦于主要信号，不会被噪声或格式异常的日志带偏。
• 元类（前缀匹配）：剩余的子类通过格式指纹的前 N 个字符匹配分组到元类中。这种分组策略可有效将词汇相似的格式归并到同一个大类下。当数据源未知时，我们选择 N=5 用于日志解析，N=15 用于数据源未知时的日志分区。

2. 分层抽样。一旦分层树构建完成，我们为 LLM 构建日志样本。战略目标是最大化方差覆盖，同时最小化 Token 使用。

• 我们从更广泛的元类中，为每个有效子类选取具有代表性的日志。
• 为处理子类过多的边缘情况，应用随机下采样以适应目标窗口大小。

3. 规则生成：最后，我们提示 LLM 为每个元类生成一个适用于所提供样本中所有日志的正则表达式解析规则。在概念验证中，我们使用了 GPT-4o mini 模型。

实验结果与观察

我们在 Loghub 数据集上实现了 94% 的解析准确率和 91% 的分区准确率。

混淆矩阵展示了日志分区结果。垂直轴代表实际数据源，水平轴代表预测的数据源。热图颜色深浅对应日志量，颜色越浅表示数量越多。对角线排列显示了模型在来源归因上的高保真度，且分散极少。

我们的性能基准测试洞察：

• 最佳基线：每个类别 30–40 条日志样本的上下文窗口被证明是“最佳区间”，能稳定生成稳健的 Regex 与 Grok 解析模式。
• 输入最小化：我们将每个类别的输入大小推至 10 个日志（用于正则表达式模式），仅观察到解析性能下降 2%，这证实了基于多样性的抽样比原始数量更为关键。

我们最近为 Google MCP Toolbox for Databases 开源项目做出了贡献，为其添加了对 Elasticsearch 数据库的支持。

有了这项新功能，您现在可以使用 Google MCP Toolbox 连接到 Elasticsearch，并直接与数据“对话”。

Elasticsearch

我们需要运行一个 Elasticsearch 实例。您可以在 Elastic Cloud 上激活免费试用版，或使用 start-local 脚本在本地安装：

curl -fsSL https://elastic.co/start-local | sh

这将在计算机上安装 Elasticsearch 和 Kibana，并生成用于配置 Google MCP Toolbox 的 API 密钥。

API 密钥将显示为上一条命令的输出，并存储在 elastic-start-local 文件夹的 .env 文件中。

安装示例数据集

安装完成后，您可以使用启动本地脚本（存储在 .env 文件中）生成的用户名 elastic 和密码登录 Kibana。

您可以安装 Kibana 提供的电子商务订单数据集。它包含一个名为 kibana_sample_data_ecommerce 的单个索引，其中包含来自一家电子商务网站的 4,675 个订单的信息。对于每笔订单，我们都有以下信息：

• 客户信息（姓名、ID 号码、出生日期、电子邮件等）
• 订单日期
• 订单编号
• 产品（包含价格、数量、ID、类别、折扣等信息的所有产品列表）
• SKU
• 总价（不含税，含税）
• 总数量
• 地理信息（城市、国家、洲、位置、地区）

要安装示例数据，请在 Kibana 中打开“集成”页面（在顶部搜索栏中搜索“集成”），然后安装“示例数据”。有关详细信息，请参阅此处的文档：https://www.elastic.co/docs/explore-analyze/#gs-get-data-into-kibana。

本文旨在展示如何轻松配置 Google MCP Toolbox 以连接到 Elasticsearch，并使用自然语言与 kibana_sample_data_ecommerce 索引进行交互。

Google MCP 工具箱

Google MCP Toolbox 是一款开源 MCP 服务器，旨在使应用程序和 AI 代理能够轻松、安全、高效地与数据库进行交互。该项目以前称为“GenAI Toolbox for Databases”，在与模型上下文协议 (MCP) 完全兼容后重新命名。其目的是通过在幕后处理连接池、身份验证、可观察性和其他操作问题，消除传统上需要将代理连接到数据库的繁重工作。

Toolbox 的核心功能是允许开发人员定义可重用的高级工具，封装数据库交互操作。然后，任何兼容 MCP 的客户端（如 AI 代理）都可以调用这些工具，而无需客户端执行低级 SQL 查询或管理数据库连接。这种方法大大减少了构建数据库感知代理所需的模板代码量，只需几行应用程序逻辑就能集成高级数据操作。一旦定义工具，就可以在多个代理、框架或语言之间共享（图 1）。

使用 Toolbox 的一大优势是内置的安全模型。原生支持 OAuth2 和 OIDC 等身份验证流程，使开发者避免在代理中处理或存储敏感的数据库凭据。该平台还通过 OpenTelemetry 提供可观测性功能（包括指标和跟踪），这对于调试、监控和生产部署至关重要。总而言之，MCP Toolbox 是一个统一、安全和可扩展的接口，可从任何支持 MCP 的系统与您的数据进行交互。

如何安装 MCP Toolbox

您可以使用以下命令在 Linux 上安装 MCP Toolbox 服务器：

export VERSION=0.21.0
curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox

如果您想将其安装在 macOS 或 Windows 上，您可以按照此处的详细说明进行操作。

配置适用于 Elasticsearch 的 Toolbox

要为 Elasticsearch 配置 MCP Toolbox，我们需要创建一个 tools.yaml 文件，如下所示：

sources:
  my-cluster:
    kind: elasticsearch
    addresses:
      - http://localhost:9200
    apikey: 

tools:
  customer-orders:
    kind: elasticsearch-esql
    source: my-cluster
    description: Get the orders made by a customer identified by name.
    query: |
    	FROM kibana_sample_data_ecommerce | WHERE MATCH(customer_full_name, ?name, {"operator": "AND"})
    parameters:
      - name: name
        type: string
        description: The customer name.

toolsets:
  elasticsearch-tools:
    - customer-orders

您需要使用有效的 Elasticsearch API 密钥替换 <insert-here-api-key> 值。如果您使用 start-local 在本地运行 Elasticsearch，则可以在.env 文件中找到由 start-local 生成的 API 密钥，位于 ES_LOCAL_API_KEY 变量下。如果您正在使用 Elastic Cloud，则可以按照此处所描述的步骤生成 API 密钥。

之前的工具包含以下适用于 Elasticsearch 的 ES|QL 查询：

FROM kibana_sample_data_ecommerce | WHERE MATCH(customer_full_name, ?name)

如果您不熟悉 ES|QL，它是由 Elastic 开发的一种类似于 SQL 的查询语言，可用于在一个或多个索引中进行搜索。您可以在此处的正式文档中阅读有关 ES|QL 的更多信息。

上述查询使用 ?name 参数（问号表示参数）搜索存储在 kibana_sample_data_ecommerce 索引中所有包含指定客户姓名的订单。

在之前的 YAML 配置中，客户名称使用字符串类型并附带描述“客户名称”来定义。

此工具可用于回答有关客户订单的问题——例如：客户 Foo 在 2025 年 10 月下了多少订单？

对工具及其参数的描述对于从用户的自然语言请求中提取相关信息至关重要。这种提取是通过大型语言模型 (LLM) 的函数调用功能实现的。在实践中，LLM 可以确定需要执行哪个函数（工具）以获取必要的信息，并为该函数指定适当的参数。

有关函数调用的更多信息，我们建议阅读 Ashish Tiwari 撰写的《使用 Elasticsearch 进行 OpenAI 函数调用》。

运行 Toolbox 服务器

您可以使用之前的 tools.yaml 文件，通过以下命令运行 MCP 工具箱：

./toolbox --tools-file tools.yaml --ui

—ui 参数在 http://127.0.0.1:5000/ui 上运行 Web 应用程序（图 2）。

您可以选择工具 > 客户订单，并在参数名称（例如，Gwen Sanders）中插入客户名称。然后点击“运行工具”按钮。您应该会看到如图 3 所示的 JSON 响应。

设置已完成，MCP Toolbox 可以执行客户订单工具与 Elasticsearch 进行通信，运行 ES|QL 查询。

将 MCP Toolbox 与 Gemini CLI 结合使用

我们可以使用任何 MCP 客户端与 MCP Toolbox for Databases 进行通信。例如，我们可以使用命令行工具 Gemini CLI 来使用 Gemini。您可以按照此处提供的说明安装 Gemini CLI。

Gemini CLI 为 MCP Toolbox 提供了一个预配置扩展程序，可在 gemini-cli-extensions/mcp-toolbox 上获取。您可以通过运行以下命令来安装此扩展程序：

gemini extensions install https://github.com/gemini-cli-extensions/mcp-toolbox

安装完成后，您需要进入为 MCP Toolbox 存储 tools.yaml 配置文件的目录，并按如下步骤执行 Gemini CLI（此步骤是 Gemini CLI 与 MCP Toolbox 自动配置所必需的）：

gemini

您应该会看到图 4 中所示的输出广告。

您可以使用以下命令检查 MCP Toolbox 是否已连接：

/mcp list

您应该能看到已列出客户订单工具的 mcp_toolbox（图 5）。

如果 MCP Toolbox 已连接到 Gemini CLI，我们现在可以尝试问一些问题，例如：“给我客户 Gwen Sanders 的订单。”然后，Gemini CLI 将向 mcp_toolbox 服务器请求执行客户订单工具的权限（参见图 6）。

确认后，Gemini CLI 将向 MCP Toolbox 执行请求，得到 JSON 响应结果，并使用它来格式化响应（图 7）。

Gemini CLI 的响应将报告 Gwen Sanders 只下了一个订单，包含 2 件产品，总价为 132 欧元。

MCP 工具箱 SDK

Google MCP Toolbox 还提供一个 SDK，可用于访问用 Go、Python 和 Javascript 编写的程序中的所有功能。

例如，Python SDK 可在 Github 上获取，页面如下：https://github.com/googleapis/mcp-toolbox-sdk-python。

我们需要创建一个简单的代理来连接 MCP 工具箱。我们需要安装以下软件包：

pip install toolbox-core
pip install google-adk

然后使用以下命令创建一个新的代理项目：

adk create my_agent

这会创建一个名为 my_agent 的新目录，其中包含文件 agent.py。

使用以下内容更新 my_agent/agent.py，以连接到 Toolbox：

from google.adk import Agent
from google.adk.apps import App
from toolbox_core import ToolboxSyncClient

client = ToolboxSyncClient("http://127.0.0.1:5000")

root_agent = Agent(
    name='root_agent',
    model='gemini-2.5-flash',
    instruction="You are a helpful AI assistant designed to search information about a dataset of ecommerce orders.",
    tools=client.load_toolset(),
)

app = App(root_agent=root_agent, name="my_agent")

创建一个 .env文件，其中包含您的 Google API 密钥：

echo 'GOOGLE_API_KEY="YOUR_API_KEY"' > my_agent/.env

最后，我们可以运行代理并观察结果。要执行代理，您可以运行以下命令：

adk run my_agent

或者，您也可以通过 Web 接口提供服务：

adk web --port 8000

在这两种情况下，您都可以使用问答接口与 MCP Toolbox 进行交互。例如，您可以提出前一个问题：给我客户 Gwen Sanders 的订单。

有关不同 SDK 的更多信息，可以参考此文档页面。

结论

在本文中，我们演示了 Elasticsearch 与 Google MCP Toolbox for Databases 的集成。使用简单的 YAML 配置文件，我们可以定义一组工具，这些工具使用 ES|QL 语言将自然语言问题转换为 Elasticsearch 查询。

我们展示了如何与 kibana_sample_data_ecommerce 数据集进行交互，该数据集包含来自电子商务网站的订单。通过这个配置文件，我们可以简单地运行 MCP Toolbox 服务器并从任何 MCP 客户端连接到它。

最后，我们演示了如何使用 Gemini CLI 作为客户端连接到 MCP Toolbox for Databases 并查询存储在 Elasticsearch 中的电子商务数据。我们执行了自然语言查询，以检索有关特定客户（以姓名标识）的订单信息。

随着 MCP 生态系统的不断发展，这种模式——轻量级工具定义，由安全、生产就绪的基础架构支持——为构建越来越强大、数据感知的代理提供了新的机会，且所需努力最小。无论您是在本地尝试 Elastic 的示例数据集，还是将搜索功能集成到更大的应用程序中，MCP 工具箱都为使用自然语言与 Elasticsearch 数据进行交互提供了可靠、可扩展的基础。

有关代理 AI 应用程序开发的更多信息，您可以阅读 Anish Mathur 和 Dana Juratoni 撰写的《使用 Elasticsearch 构建 AI 代理工作流》。

有关 Google MCP Toolbox 的更多信息，请访问 https://googleapis.github.io/genai-toolbox/getting-started/introduction/。

然而，当你解决这一问题时，却可能因无法手动测试所有情况而不经意间破坏其他查询的功能。但你或你的 QA 团队该如何测试，以确认某一项查询的改动是否会对其他查询产生连锁反应呢？或者更关键的是，你们要如何确保所作的改动确实优化了某项查询呢？

转向系统性评估

这个时候，判断列表就可以派上用场。与其在每次更改时依赖手动和主观测试，不如定义一组与业务案例相关的固定查询及其相关结果。

这一组（测试用例或数据）将成为基准参照。每次实施改动时，你都用它来评估搜索效果是否确实得到了提升。

这种方法的价值在于：

• 消除不确定性：无需再费心猜测所做的更改是否会影响其他查询；数据会直接告诉你答案。
• 停止人工测试：一旦判定集被记录下来，测试便会自动执行。
• 佐证更改：你可以展示出明确的指标，以佐证某项更改所带来的益处。

如何开始建立判断列表

最简单的开始方式之一是获取具有代表性的查询，并手动选择相关文件。有两种方法可以列出此列表：

• 二元判断：与查询关联的每一份文档都会被赋予一个简单标签：相关（通常标注分数为“1”）和不相关（标注分数为“0”）。
• 分级判断：在此情境下，每份文档会依据不同等级获得相应分数。例如：采用 0 至 4 分的评分量表，类似于李克特量表，其中 0 分表示“完全不相关”，4 分表示“完全相关”，中间还设有“相关”“有点相关”等不同程度表述。

当搜索意图具有明确界限时，二元判断（是/否）十分奏效，即判断该文档是否应出现在搜索结果中？

当存在模糊地带时，分级判断更为实用：某些结果相较于其他结果更优，因此你可以将结果划分为“优秀”“良好”和“毫无价值”等不同等级，并运用能体现结果排序权重及用户反馈的评估指标。然而，分级量表也存在弊端：不同评审者对评分等级的使用方式可能存在差异，这会导致判断结果的一致性降低。并且，由于分级指标对高分赋予了更大的权重，即便是一个微小的改动（比如将某项评分从 4 分改为 3 分），也可能在指标上引发远超评审者预期的巨大波动。这种额外引入的主观性使得分级判断结果更具干扰性，且随时间推移愈发难以把控。

我需要自己对文件分类吗？

不一定，因为有多种不同方法创建判定列表，且每种方法各有其优缺点：

• 明确判断：在这种情况下，领域专家会逐一审阅每个查询/文档，并手动判定其相关性（或相关程度）。尽管此方法能确保质量并实现把控，但其可扩展性较差。
• 隐式判断：采用这种方法时，你会依据真实用户行为（如点击量、跳出率、购买行为等）来推断相关文档。此方法可实现数据的自动收集，但可能存在偏差。例如，用户往往更倾向于点击排名靠前的结果，即便这些结果并不相关。
• AI 生成的判断：最后这种方法是借助模型（如 LLM）自动评估查询和文档，人们通常称之为LLM 陪审团。其优势在于速度快且易于扩展，不过数据质量取决于所用模型的性能，以及大语言模型训练数据与您业务需求的契合程度。与人工评分一样，LLM 评审团也可能引入自身偏见或出现前后不一致的情况，因此，必须对照一小部分可信判断结果来验证其输出结果。LLM 模型本质上具有概率性，所以即便将温度参数设置为 0，也常见同一结果被 LLM 模型给出不同评分的情况。

以下是一些选择最佳方法来构建判断集的建议：

• 明确界定哪些仅用户能恰当判断的要素对你而言至关重要（例如价格、品牌、语言、风格以及产品细节等）。如果这些要素至关重要，则至少需针对判断列表中的部分内容获取明确的判断结果。
• 当你的搜索引擎已有足够流量时，可运用隐式判断，即借助点击量、转化率以及停留时长等指标来洞察使用趋势。不过，你仍需谨慎解读这些数据，将其与显式判断结果进行对比，以规避潜在偏差（例如用户往往更倾向于点击排名靠前的结果，即便排名靠后的结果更具相关性）。

为解决这一问题，位置偏差消除技术会对点击数据进行调整或重新加权，以更准确地反映用户的真实兴趣。以下是一些方法：

• 结果随机排序：针对部分用户调整搜索结果的排序，以此估算结果位置对点击量的影响。
• 点击模型包括动态贝叶斯网络 DBN 和用户浏览模型 UBM。这些统计模型会借助滚动行为、停留时长、点击顺序以及返回结果页等模式，来估算用户点击行为反映真实兴趣（而非仅受结果位置影响）的概率。

示例：电影评分应用

准备工作

要运行此示例，需要一个正在运行的本地或部署在 Elastic Cloud 上（托管或无服务器）的 Elasticsearch 8.x 集群，以及访问 REST API 或 Kibana 的权限。

想象有一款应用程序，用户可以在其中上传自己对电影的看法，还可以搜索要观看的电影。由于文本由用户自己撰写，因此可能存在拼写错误和表达方式上的多种差异。因此，搜索引擎必须能够解读这种多样性，并为用户提供有用的结果。

为能在不影响整体搜索行为的前提下对查询进行迭代优化，贵公司业务团队基于最常执行的搜索查询，创建了以下二元判断集：

正在创建索引：

PUT movies
{
  "mappings": {
    "properties": {
      "text": {
        "type": "text"
      }
    }
  }
}

批量请求：

POST /movies/_bulk
{ "index": { "_id": "doc1" } }
{ "text": "DiCaprio performance in The Revenant was breathtaking." }
{ "index": { "_id": "doc2" } }
{ "text": "Inception shows Leonardo DiCaprio in one of his most iconic roles." }
{ "index": { "_id": "doc3" } }
{ "text": "Brad Pitt delivers a solid performance in this crime thriller." }
{ "index": { "_id": "doc4" } }
{ "text": "An action-packed adventure with stunning visual effects." }
{ "index": { "_id": "doc5" } }
{ "text": "A heartbreaking story of love and loss that made me cry for hours." }
{ "index": { "_id": "doc6" } }
{ "text": "One of the saddest movies ever made -- bring tissues!" }
{ "index": { "_id": "doc7" } }
{ "text": "A lighthearted comedy that will make you laugh." }
{ "index": { "_id": "doc8" } }
{ "text": "A science-fiction epic full of action and excitement." }

以下是该应用程序正在使用的 Elasticsearch 查询：

GET movies/_search
{
 "query": {
   "match": {
     "text": {
       "query": "DiCaprio performance",
       "minimum_should_match": "100%"
     }
   }
 }
}

从判断到指标

就其本身而言，判断列表并不提供太多信息；它们只是我们查询结果的期望。它们真正的优势在于，当我们使用它们来计算客观指标以衡量我们的搜索性能时。

如今，大多数常用指标包含

• 精度：衡量所有搜索结果中真正相关的结果比例。
• 召回率：衡量搜索引擎在检索出的 x 个结果中，找到的相关结果所占的比例。
• 折损累积增益（DCG）：用于衡量结果排序的质量，该指标基于最相关的结果应排在前列这一原则进行评估。
• 平均倒数排名（MRR）：用于衡量首个相关结果所处的排名位置情况 。在列表中越靠前，其分数就越高。

以同样的电影评分应用程序为例，我们将计算召回率指标，看看我们的查询是否遗漏了任何信息。

在 Elasticsearch 中，我们可以通过排名评估 API，使用判断列表来计算指标。该 API 将判断列表、查询以及想要评估的指标作为输入，并返回一个数值，该数值是对查询结果与判断列表进行对比后得出的结果。

让我们针对已提出的这两个查询运行判定列表：

POST /movies/_rank_eval
{
 "requests": [
   {
     "id": "dicaprio-performance",
     "request": {
       "query": {
         "match": {
           "text": {
             "query": "DiCaprio performance",
             "minimum_should_match": "100%"
           }
         }
       }
     },
     "ratings": [
       {
         "_index": "movies",
         "_id": "doc1",
         "rating": 1
       },
       {
         "_index": "movies",
         "_id": "doc2",
         "rating": 1
       },
       {
         "_index": "movies",
         "_id": "doc3",
         "rating": 0
       },
       {
         "_index": "movies",
         "_id": "doc4",
         "rating": 0
       }
     ]
   },
   {
     "id": "sad-movies",
     "request": {
       "query": {
         "match": {
           "text": {
             "query": "sad movies that make you cry",
             "minimum_should_match": "100%"
           }
         }
       }
     },
     "ratings": [
       {
         "_index": "movies",
         "_id": "doc5",
         "rating": 1
       },
       {
         "_index": "movies",
         "_id": "doc6",
         "rating": 1
       },
       {
         "_index": "movies",
         "_id": "doc7",
         "rating": 0
       },
       {
         "_index": "movies",
         "_id": "doc8",
         "rating": 0
       }
     ]
   }
 ],
 "metric": {
   "recall": {
     "k": 10,
     "relevant_rating_threshold": 1
     }
 }
}

我们将向 rank_eval 发送两个请求：一个针对莱昂纳多·迪卡普里奥查询，另一个针对悲伤电影查询每个请求均包含一个查询及其对应的判定列表（评分）。我们无需对所有文档进行评分，因为未纳入评分范围的文档将被视为未作判定。在进行计算时，召回率仅考虑“相关文档集”，即那些在评分中被认定为相关的文档。

在此情形下，针对莱昂纳多·迪卡普里奥的查询召回率为 1，而悲伤电影查询的召回率为 0。这意味着对于第一个查询，我们能够获取到所有相关结果，而第二个查询则未获取到任何相关结果。因此，平均召回率为 0.5。

{
 "metric_score": 0.5,
 "details": {
   "dicaprio-performance": {
     "metric_score": 1,
     "unrated_docs": [],
     "hits": [
       {
         "hit": {
           "_index": "movies",
           "_id": "doc1",
           "_score": 2.4826927
         },
         "rating": 1
       },
       {
         "hit": {
           "_index": "movies",
           "_id": "doc2",
           "_score": 2.0780432
         },
         "rating": 1
       }
     ],
     "metric_details": {
       "recall": {
         "relevant_docs_retrieved": 2,
         "relevant_docs": 2
       }
     }
   },
   "sad-movies": {
     "metric_score": 0,
     "unrated_docs": [],
     "hits": [],
     "metric_details": {
       "recall": {
         "relevant_docs_retrieved": 0,
         "relevant_docs": 2
       }
     }
   }
 },
 "failures": {}
}

或许我们对 minimum_should_match 参数设置得过于严苛了，因为要求查询中的所有词汇都必须在文档中出现，这很可能会导致我们遗漏掉一些相关结果。不妨去掉 minimum_should_match 参数，这样只要文档中包含查询语句里的任意一个词汇，该文档就会被视为相关结果。

POST /movies/_rank_eval
{
 "requests": [
   {
     "id": "dicaprio-performance",
     "request": {
       "query": {
         "match": {
           "text": {
             "query": "DiCaprio performance"
           }
         }
       }
     },
     "ratings": [
       {
         "_index": "movies",
         "_id": "doc1",
         "rating": 1
       },
       {
         "_index": "movies",
         "_id": "doc2",
         "rating": 1
       },
       {
         "_index": "movies",
         "_id": "doc3",
         "rating": 0
       },
       {
         "_index": "movies",
         "_id": "doc4",
         "rating": 0
       }
     ]
   },
   {
     "id": "sad-movies",
     "request": {
       "query": {
         "match": {
           "text": {
             "query": "sad movies that make you cry"
           }
         }
       }
     },
     "ratings": [
       {
         "_index": "movies",
         "_id": "doc5",
         "rating": 1
       },
       {
         "_index": "movies",
         "_id": "doc6",
         "rating": 1
       },
       {
         "_index": "movies",
         "_id": "doc7",
         "rating": 0
       },
       {
         "_index": "movies",
         "_id": "doc8",
         "rating": 0
       }
     ]
   }
 ],
 "metric": {
   "recall": {
     "k": 10,
     "relevant_rating_threshold": 1
     }
 }
}

如你所见，通过在两个查询中的其中一个里移除 minimum_should_match 参数，现在两个查询的平均召回率都达到了 1。

{
  "metric_score": 1,
  "details": {
    "dicaprio-performance": {
      "metric_score": 1,
      "unrated_docs": [],
      "hits": [
        {
          "hit": {
            "_index": "movies",
            "_id": "doc1",
            "_score": 2.0661702
          },
          "rating": 1
        },
        {
          "hit": {
            "_index": "movies",
            "_id": "doc3",
            "_score": 0.732218
          },
          "rating": 0
        },
        {
          "hit": {
            "_index": "movies",
            "_id": "doc2",
            "_score": 0.6271719
          },
          "rating": 1
        }
      ],
      "metric_details": {
        "recall": {
          "relevant_docs_retrieved": 2,
          "relevant_docs": 2
        }
      }
    },
    "sad-movies": {
      "metric_score": 1,
      "unrated_docs": [],
      "hits": [
        {
          "hit": {
            "_index": "movies",
            "_id": "doc7",
            "_score": 2.1307156
          },
          "rating": 0
        },
        {
          "hit": {
            "_index": "movies",
            "_id": "doc5",
            "_score": 1.3160692
          },
          "rating": 1
        },
        {
          "hit": {
            "_index": "movies",
            "_id": "doc6",
            "_score": 1.190063
          },
          "rating": 1
        }
      ],
      "metric_details": {
        "recall": {
          "relevant_docs_retrieved": 2,
          "relevant_docs": 2
        }
      }
    }
  },
  "failures": {}
}

总而言之，移除 minimum_should_match: 100% 这一条件后，我们得以使两个查询均实现完美召回率。

我们做到了！对不对？

没那么快！

通过提升召回率，我们能够获取到更广泛的结果范围。然而，每一次调整都意味着需要权衡取舍。这正是为何要定义完整的测试用例，并运用不同指标来评估各项更改的原因。

使用判断列表和指标可以防止您在进行更改时盲目行事，因为现在您有数据可以支持这些更改。验证不再是手动和重复的，您可以在多个用例中测试您的更改。此外，A/B 测试允许您实时测试哪种配置最适合您的用户和业务案例，从而实现从技术指标到实际指标的完整循环。

使用判断列表的最终建议

运用判定列表开展工作，不仅关乎评估测量，更在于构建一个能让你自信迭代优化的框架。为实现这一目标，可遵循以下建议：

1. 从小处着手，但一定要开始行动。你无需准备 10000 个查询，且每个查询都配有 50 个判断列表。你只需找出 5 到 10 个对业务场景最为关键的查询，并明确你期望在结果顶部看到的文档即可。这已经能为你提供一个基础。通常，你应优先从热门查询以及无结果的查询入手开展工作。你也可以先使用像精确率这样易于配置的指标进行测试，然后再逐步尝试更复杂的指标。
2. 与用户核实。在生产环境中通过 A/B 测试对数据指标进行补充验证。如此一来，你便能知晓那些在指标上表现良好的更改是否也切实产生了实际影响。
3. 保持列表有效性。你的商业案例会不断变化，关键问题也会随之变化。定期更新判断以反映新的需求。
4. 使其成为流程的一部分。将判断列表整合到开发管道之中。确保每次配置更改、同义词添加或文本分析操作，都能自动对照基础列表进行验证。
5. 将技术知识与战略相结合。不要仅仅满足于衡量精确率或召回率等技术指标。要利用评估结果为业务成果提供决策依据。

什么是 LangGraph

LangGraph 是一个用于构建 AI 代理，并将其编排进工作流，从而打造 AI 辅助应用的框架。LangGraph 采用节点式架构，我们可以声明代表不同任务的函数，并将这些函数指定为工作流中的节点。多个节点相互作用后形成的便是一个图结构。LangGraph 是更广泛的 LangChain 生态系统的一部分，该生态为构建模块化、可组合的 AI 系统提供了丰富的工具。

为了更直观地理解 LangGraph 有何用处，我们不妨用它来解决一个真实的业务难题。

解决方案概述

在一家风险投资公司中，投资人可以访问一个带有大量筛选条件的大型数据库，但一旦需要组合多重条件，查询就会变得既繁琐又缓慢。这可能会导致一些本应纳入投资视野的优质初创公司被漏掉。结果就是，团队要耗费大量时间去筛选最佳标的，甚至因此错失投资机会。

借助 LangGraph 和 Elasticsearch，我们能够使用自然语言进行过滤搜索，从而无需用户手动构建包含数十个筛选器的复杂请求。为了提高灵活性，工作流会根据用户输入在两种查询类型之间自动选择：

• 聚焦投资维度的查询：这类查询专注于初创公司的财务与融资维度，例如融资轮次、估值或营收等指标。示例：“查找已完成 A 轮或 B 轮融资、融资额在 800 万至 2,500 万美元之间且月收入超过 50 万美元的初创公司。”
• 聚焦市场维度的查询：这类查询侧重于行业垂直领域、目标市场或商业模式，帮助识别特定领域或地区中的投资机会。示例：“查找位于旧金山、纽约或波士顿的金融科技和医疗健康领域初创公司。”

为了让查询更稳健，我们会让 LLM 生成搜索模板，而不是直接构造完整的 DSL 查询。通过这种方式，你获得的始终是预期的查询结果，LLM 只需填入参数，而不必每次从头构建整条查询。

开始前的准备工作

• Elasticsearch API密钥
• OpenAPI API密钥
• Node 18 或更高版本

分步操作指南

在本节中，我们先来看一下这个应用的外观。为此，我们将使用 TypeScript，这是 JavaScript 的一个超集，添加了静态类型，使代码更可靠且更易维护，并能更早发现错误，同时又与现有 JavaScript 完全兼容。

节点的流程将如下所示：

上图由 LangGraph 生成，直观地呈现了工作流结构，包括各节点的执行顺序和它们之间的条件分支关系：

• decideStrategy：使用 LLM 分析用户查询，在“聚焦投资维度”与“聚焦市场维度”这两种专门搜索策略之间做出选择。
• PrepareInvestmentSearch：从查询中提取筛选值并构建一个强调财务和资金相关参数的预定义模板。
• prepareMarketSearch：同样会提取筛选条件，但重点是围绕市场、行业和地域背景，动态生成相应的搜索参数。
• ExecuteSearch：通过搜索模板将构建好的查询发送到 Elasticsearch，检索并返回所有匹配的初创公司文档。
• visualizeResults：将最终结果整理成清晰易读的摘要，呈现融资、行业、营收等关键创业公司属性。

该流程包括一个条件分支，相当于一条“if”语句，可根据用户输入决定使用投资还是市场搜索路径。这种由 LLM 驱动的决策机制让工作流具备自适应和上下文感知能力，后续章节将对这一机制进行更详细的说明。

LangGraph 状态

在查看各个节点之前，我们需要先理解节点之间的通信和数据共享方式。为此，LangGraph 可支持定义工作流状态。这个状态就是在各个节点之间传递的共享状态。

该状态相当于一个共享容器，在整个工作流中保存中间数据：从最开始的用户自然语言查询，到选定的搜索策略、为 Elasticsearch 准备好的参数、检索到的搜索结果，一直到最后的格式化输出，都会依次写入其中。

这种结构让每个节点都能读取和更新状态，确保从用户输入到可视化实现顺畅一致的信息流动。

const VCState = Annotation.Root({
  input: Annotation(), // User's natural language query
  searchStrategy: Annotation(), // Search strategy chosen by LLM
  searchParams: Annotation(), // Prepared search parameters
  results: Annotation(), // Search results
  final: Annotation(), // Final formatted response
});

设置应用程序

本节所有代码均可在 elasticsearch-labs 仓库 中找到。

在应用所在的文件夹中打开终端，并通过以下命令初始化一个 Node.js 应用：

npm init -y

现在我们可以为这个项目安装必要的依赖项：

npm install @elastic/elasticsearch @langchain/langgraph @langchain/openai @langchain/core dotenv zod && npm install --save-dev @types/node tsx typescript

• @elastic/elasticsearch：帮助我们处理 Elasticsearch 请求，例如数据摄取和检索。
• @langchain/langgraph：用于提供所有 LangGraph 工具的 JS 依赖项。
• @langchain/openai：适用于 LangChain 的 OpenAI LLM 客户端。
• @langchain/core：为 LangChain 应用提供基础构建模块，包括提示模板。
• dotenv：在 JavaScript 中使用环境变量所需的依赖项。
• zod: 对类型数据的依赖。

@types/node tsx typescript 允许我们编写和运行 TypeScript 代码。

现在创建以下文件：

• elasticsearchSetup.ts：将创建索引映射，从 JSON 文件加载数据集，并将数据摄取到 Elasticsearch。
• main.ts：将包含 LangGraph 应用。
• .env：用于存储环境变量的文件

在 .env 文件中，我们添加以下环境变量：

ELASTICSEARCH_ENDPOINT="your-endpoint-here"
ELASTICSEARCH_API_KEY="your-key-here"
OPENAI_API_KEY="your-key-here"

OpenAPI APIKey 不会直接在代码中使用，而是由 @langchain/openai 库在内部调用。

所有关于映射创建、搜索模板创建和数据集摄取的逻辑都可以在 elasticsearchSetup.ts 文件中找到。在接下来的步骤中，我们将重点关注 main.ts 文件。此外，您可以查看该数据集，以便更好地理解 dataset.json 中数据结构。

LangGraph 应用程序

在 main.ts 文件中，我们导入一些必要的依赖项来构建整个 LangGraph 应用。在此文件中，您还必须定义各个节点函数以及工作流状态的声明。在后续步骤中，我们会在 main 方法中完成这个图结构的声明。elasticsearchSetup.ts 文件中包含一组 Elasticsearch 辅助函数，我们会在后续步骤的各个节点中使用这些函数。

import { writeFileSync } from "node:fs";
import { StateGraph, Annotation, START, END } from "@langchain/langgraph";
import { ChatOpenAI } from "@langchain/openai";
import { z } from "zod";
import {
  esClient,
  ingestDocuments,
  createSearchTemplates,
  INDEX_NAME,
  INVESTMENT_FOCUSED_TEMPLATE,
  MARKET_FOCUSED_TEMPLATE,
  createIndex,
} from "./elasticsearchSetup.js";

const llm = new ChatOpenAI({ model: "gpt-4o-mini" });

如前所述，LLM 客户端将根据用户的问题生成 Elasticsearch 搜索模板参数。

async function saveGraphImage(app: any): Promise {
  try {
    const drawableGraph = app.getGraph();
    const image = await drawableGraph.drawMermaidPng();
    const arrayBuffer = await image.arrayBuffer();

    const filePath = "./workflow_graph.png";
    writeFileSync(filePath, new Uint8Array(arrayBuffer));
    console.log(`📊 Workflow graph saved as: ${filePath}`);
  } catch (error: any) {
    console.log("⚠️  Could not save graph image:", error.message);
  }
}

上面的方法会生成一张 png 格式的图结构图像，并在后台调用 Mermaid.ink API。当你希望通过一张带有样式的可视化图来直观了解应用中各个节点之间的交互时，这个功能就会非常有用。

LangGraph 节点

现在让我们看看每个节点的详细信息：

decideSearchStrategy 节点

decideSearchStrategy 节点分析用户输入，并确定是执行投资聚焦搜索还是市场聚焦搜索。它使用具有结构化输出模式（用 Zod 定义）的 LLM 对查询类型进行分类。在做出决策之前，它会通过聚合从索引中检索可用的筛选条件，确保模型掌握最新的行业、地域和融资等上下文信息。

为了提取过滤器可能的值并将其发送到 LLM，让我们使用聚合查询直接从 Elasticsearch 索引中检索它们。这个逻辑被分配到一个名为 getAvailableFilters 的方法中：

async function getAvailableFilters() {
  try {
    const response = await esClient.search({
      index: INDEX_NAME,
      size: 0,
      aggs: {
        industries: {
          terms: { field: "industry", size: 100 },
        },
        locations: {
          terms: { field: "location", size: 100 },
        },
        funding_stages: {
          terms: { field: "funding_stage", size: 20 },
        },
        business_models: {
          terms: { field: "business_model", size: 10 },
        },
        lead_investors: {
          terms: { field: "lead_investor", size: 100 },
        },
        funding_amount_stats: {
          stats: { field: "funding_amount" },
        },
      },
    });

    return response.aggregations;
  } catch (error) {
    console.error("❌ Error getting available filters:", error);
    return {};
  }
}

通过上述聚合查询，我们得到以下结果：

{
  "industries": {
    "doc_count_error_upper_bound": 0,
    "sum_other_doc_count": 0,
    "buckets": [
      {
        "key": "logistics",
        "doc_count": 5
      },
      ...
    ]
  },
  "locations": {
    "doc_count_error_upper_bound": 0,
    "sum_other_doc_count": 0,
    "buckets": [
      {
        "key": "San Francisco, CA",
        "doc_count": 4
      },
      {
        "key": "New York, NY",
        "doc_count": 3
      },
      ...
    ]
  },
  "funding_stages": {
    "doc_count_error_upper_bound": 0,
    "sum_other_doc_count": 0,
    "buckets": [
      {
        "key": "Series A",
        "doc_count": 8
      },
      ...
    ]
  },
  "business_models": {
    "doc_count_error_upper_bound": 0,
    "sum_other_doc_count": 0,
    "buckets": [
      {
        "key": "B2B",
        "doc_count": 13
      },
      ...
    ]
  },
  "lead_investors": {
    "doc_count_error_upper_bound": 0,
    "sum_other_doc_count": 0,
    "buckets": [
      {
        "key": "Battery Ventures",
        "doc_count": 1
      },
      {
        "key": "Benchmark Capital",
        "doc_count": 1
      },
      ...
    ]
  },
  "funding_amount_stats": {
    "count": 20,
    "min": 4500000,
    "max": 35000000,
    "avg": 14075000,
    "sum": 281500000
  }
}

点击此处查看所有结果。

对于这两种策略，我们将使用混合搜索来检测问题的结构化部分（过滤器）和主观部分（语义）。以下是使用搜索模板的两个查询示例：

await esClient.putScript({
      id: INVESTMENT_FOCUSED_TEMPLATE,
      script: {
        lang: "mustache",
        source: `{
          "size": 5,
          "retriever": {
            "rrf": {
              "retrievers": [
                {
                  "standard": {
                    "query": {
                      "semantic": {
                        "field": "semantic_field",
                        "query": "{{query_text}}"
                      }
                    }
                  }
                },
                {
                  "standard": {
                    "query": {
                      "bool": {
                        "filter": [
                          {"terms": {"funding_stage": {{#join}}{{#toJson}}funding_stage{{/toJson}}{{/join}}}},
                          {"range": {"funding_amount": {"gte": {{funding_amount_gte}}{{#funding_amount_lte}},"lte": {{funding_amount_lte}}{{/funding_amount_lte}}}}},
                          {"terms": {"lead_investor": {{#join}}{{#toJson}}lead_investor{{/toJson}}{{/join}}}},
                          {"range": {"monthly_revenue": {"gte": {{monthly_revenue_gte}}{{#monthly_revenue_lte}},"lte": {{monthly_revenue_lte}}{{/monthly_revenue_lte}}}}}
                        ]
                      }
                    }
                  }
                }
              ],
              "rank_window_size": 100,
              "rank_constant": 20
            }
          }
        }`,
      },
    });

查看 elasticsearchSetup.ts 文件中详细的查询。在接下来的节点中，将决定使用这两个查询中的哪一个：

// Node 1: Decide search strategy using LLM
async function decideSearchStrategy(state: typeof VCState.State) {
  // Zod schema for specialized search strategy decision
  const SearchDecisionSchema = z.object({
    search_type: z
      .enum(["investment_focused", "market_focused"])
      .describe("Type of specialized search strategy to use"),
    reasoning: z
      .string()
      .describe("Brief explanation of why this search strategy was chosen"),
  });

  const decisionLLM = llm.withStructuredOutput(SearchDecisionSchema);

  // Get dynamic filters from Elasticsearch
  const availableFilters = await getAvailableFilters();

  const prompt = `Query: "${state.input}"
    Available filters: ${JSON.stringify(availableFilters, null, 2)}

    Choose between two specialized search strategies:
    
    - investment_focused: For queries about funding stages, funding amounts, monthly revenue, lead investors, financial performance
    
    - market_focused: For queries about industries, locations, business models, market segments, geographic markets
    
    Analyze the query intent and choose the most appropriate strategy.
  `;

  try {
    const result = await decisionLLM.invoke(prompt);
    console.log(
      `🤔 Search strategy: ${result.search_type} - ${result.reasoning}`
    );

    return {
      searchStrategy: result.search_type,
    };
  } catch (error: any) {
    console.error("❌ Error in decideSearchStrategy:", error.message);
    return {
      searchStrategy: "investment_focused",
    };
  }
}

prepareInvestmentSearch 和 prepareMarketSearch 节点

两个节点都使用共享的辅助函数 extractFilterValues，该函数利用 LLM 来识别用户输入中提到的相关过滤器，例如行业、地点、资金阶段、商业模式等。我们正在使用这个架构来构建我们的 搜索模板。

// Extract all possible filter values from user input
async function extractFilterValues(input: string) {
  const FilterValuesSchema = z.object({
    // Investment-focused filters
    funding_stage: z
      .array(z.string())
      .default([])
      .describe("Funding stage values mentioned in query"),
    funding_amount_gte: z
      .number()
      .default(0)
      .describe("Minimum funding amount in USD"),
    funding_amount_lte: z
      .number()
      .default(100000000)
      .describe("Maximum funding amount in USD"),
    lead_investor: z
      .array(z.string())
      .default([])
      .describe("Lead investor values mentioned in query"),
    monthly_revenue_gte: z
      .number()
      .default(0)
      .describe("Minimum monthly revenue in USD"),
    monthly_revenue_lte: z
      .number()
      .default(10000000)
      .describe("Maximum monthly revenue in USD"),
    industry: z
      .array(z.string())
      .default([])
      .describe("Industry values mentioned in query"),
    location: z
      .array(z.string())
      .default([])
      .describe("Location values mentioned in query"),
    business_model: z
      .array(z.string())
      .default([])
      .describe("Business model values mentioned in query"),
  });

  const extractorLLM = llm.withStructuredOutput(FilterValuesSchema);
  const availableFilters = await getAvailableFilters();

  const extractPrompt = `Extract ALL relevant filter values from: "${input}"
    Available options: ${JSON.stringify(availableFilters, null, 2)}
    Extract only values explicitly mentioned in the query. Leave fields empty if not mentioned.`;

  return await extractorLLM.invoke(extractPrompt);
}

根据检测到的意图，工作流会选择以下两种路径之一：

PrepareInvestmentSearch：构建以财务为导向的搜索参数，包括融资阶段、融资金额、投资者以及营收相关信息。您可以在 elasticsearchSetup.ts 文件中找到整个查询模板：

// Node 2A: Prepare Investment-Focused Search Parameters 
async function prepareInvestmentSearch(state: typeof VCState.State) {
  console.log(
    "💰 Preparing INVESTMENT-FOCUSED search parameters with financial emphasis..."
  );

  try {
    // Extract all filter values from input
    const values = await extractFilterValues(state.input);

    let searchParams: any = {
      template_id: INVESTMENT_FOCUSED_TEMPLATE,
      query_text: state.input,
      ...values,
    };

    return { searchParams };
  } catch (error) {
    console.error("❌ Error preparing investment-focused params:", error);
    return {
      searchParams: {},
    };
  }
}

prepareMarketSearch：创建以行业、地域和商业模式为重点的市场驱动参数。在 elasticsearchSetup.ts 文件中查看完整查询：

// Node 2B: Prepare Market-Focused Search Parameters
async function prepareMarketSearch(state: typeof VCState.State) {
  console.log(
    "🔍 Preparing MARKET-FOCUSED search parameters with market emphasis..."
  );

  try {
    // Extract all filter values from input
    const values = await extractFilterValues(state.input);

    let searchParams: any = {
      template_id: MARKET_FOCUSED_TEMPLATE,
      query_text: state.input,
      ...values,
    };

    return { searchParams };
  } catch (error) {
    console.error("❌ Error preparing market-focused params:", error);
    return {};
  }
}

executeSearch 节点

该节点从状态中获取生成的搜索参数，首先将其发送到 Elasticsearch，使用_render API来可视化查询以便调试，然后发送请求以检索结果。

// Node 3: Execute Search
async function executeSearch(state: typeof VCState.State) {
  const { searchParams } = state;

  try {
    // getting formed query from template for debugging
    const renderedTemplate = await esClient.renderSearchTemplate({
      id: searchParams.template_id,
      params: searchParams,
    });

    console.log(
      "📋 Complete query:",
      JSON.stringify(renderedTemplate.template_output, null, 2)
    );

    const results = await esClient.searchTemplate({
      index: INDEX_NAME,
      id: searchParams.template_id,
      params: searchParams,
    });

    return {
      results: results.hits.hits.map((hit: any) => hit._source),
    };
  } catch (error: any) {
    console.error(`❌ ${state.searchParams.search_type} search error:`, error);
    return { results: [] };
  }
}

visualizeResults 节点

最后，此节点显示 Elasticsearch 结果。

// Node 4: Visualize results
async function visualizeResults(state: typeof VCState.State) {
  const results = state.results || [];

  let formattedResults = `🎯 Found ${results.length} startups matching your criteria:\n\n`;

  results.forEach((startup: any, index: number) => {
    formattedResults += `${index + 1}. **${startup.company_name}**\n`;
    formattedResults += `   📍 ${startup.location} | 🏢 ${startup.industry} | 💼 ${startup.business_model}\n`;
    formattedResults += `   💰 ${startup.funding_stage} - $${(
      startup.funding_amount / 1000000
    ).toFixed(1)}M\n`;
    formattedResults += `   👥 ${startup.employee_count} employees | 📈 $${(
      startup.monthly_revenue / 1000
    ).toFixed(0)}K MRR\n`;
    formattedResults += `   🏦 Lead: ${startup.lead_investor}\n`;
    formattedResults += `   📝 ${startup.description}\n\n`;
  });

  return {
    final: formattedResults,
  };
}

从程序角度来看，整个图结构如下所示：

  const workflow = new StateGraph(VCState)
    // Register nodes - these are the processing functions
    .addNode("decideStrategy", decideSearchStrategy)
    .addNode("prepareInvestment", prepareInvestmentSearch)
    .addNode("prepareMarket", prepareMarketSearch)
    .addNode("executeSearch", executeSearch)
    .addNode("visualizeResults", visualizeResults)
    // Define execution flow with conditional branching
    .addEdge(START, "decideStrategy") // Start with strategy decision
    .addConditionalEdges(
      "decideStrategy",
      (state: typeof VCState.State) => state.searchStrategy, // Conditional function
      {
        investment_focused: "prepareInvestment", // If investment focused -> RRF template preparation
        market_focused: "prepareMarket", // If market focused -> dynamic query preparation
      }
    )
    .addEdge("prepareInvestment", "executeSearch") // Investment prep -> execute
    .addEdge("prepareMarket", "executeSearch") // Market prep -> execute
    .addEdge("executeSearch", "visualizeResults") // Execute -> visualize
    .addEdge("visualizeResults", END); // End workflow

正如你所见，我们有一个条件边，应用在此决定接下来运行哪个“路径”或节点。当工作流需要分支逻辑时，例如在多个工具之间进行选择或包含人机交互步骤，此功能非常有用。

了解了 LangGraph 的核心功能后，我们可以设置代码运行的应用程序：

将所有内容在 main 方法中整合起来，在名为 workflow 的变量中声明这个包含所有元素的图结构：

async function main() {
  await createIndex();
  await createSearchTemplates();
  await ingestDocuments();

  // Create the workflow graph with shared state
  const workflow = new StateGraph(VCState)
    // Register nodes - these are the processing functions
    .addNode("decideStrategy", decideSearchStrategy)
    .addNode("prepareInvestment", prepareInvestmentSearch)
    .addNode("prepareMarket", prepareMarketSearch)
    .addNode("executeSearch", executeSearch)
    .addNode("visualizeResults", visualizeResults)
    // Define execution flow with conditional branching
    .addEdge(START, "decideStrategy") // Start with strategy decision
    .addConditionalEdges(
      "decideStrategy",
      (state: typeof VCState.State) => state.searchStrategy, // Conditional function
      {
        investment_focused: "prepareInvestment", // If investment focused -> RRF template preparation
        market_focused: "prepareMarket", // If market focused -> dynamic query preparation
      }
    )
    .addEdge("prepareInvestment", "executeSearch") // Investment prep -> execute
    .addEdge("prepareMarket", "executeSearch") // Market prep -> execute
    .addEdge("executeSearch", "visualizeResults") // Execute -> visualize
    .addEdge("visualizeResults", END); // End workflow


  const app = workflow.compile();

  await saveGraphImage(app);

  const query =
    "Find startups with Series A or Series B funding between $8M-$25M and monthly revenue above $500K";

  const marketResult = await app.invoke({ input: query });
  console.log(marketResult.final);
}

查询变量用来模拟用户在一个虚拟搜索框中输入的内容：

系统会从这句自然语言“查找已完成 A 轮或 B 轮、融资额在 800 万至 2,500 万美元之间且月收入高于 50 万美元的初创公司”中，自动抽取出所有筛选条件。

最后，调用主方法：

main().catch(console.error);

实施结果

🔍 Checking if index exists...
🏗️ Creating index...
✅ Index created successfully!
Ingesting documents...
✅ Documents ingested successfully!
✅ Investment-focused template created successfully!
✅ Market-focused template created successfully!

📊 Workflow graph saved as: ./workflow_graph.png

🔍 Query: "Find startups with Series A or Series B funding between $8M-$25M and monthly revenue above $500K"

🤔 Search strategy: investment_focused - The query specifically seeks profitable fintech startups with defined funding amounts and high monthly revenue, which aligns closely with financial performance metrics and investment-related criteria.

💰 Preparing INVESTMENT-FOCUSED search parameters with financial emphasis...

📋 Complete query: {
  "size": 5,
  "retriever": {
    "rrf": {
      "retrievers": [
        {
          "standard": {
            "query": {
              "semantic": {
                "field": "semantic_field",
                "query": "Find startups with Series A or Series B funding between $8M-$25M and monthly revenue above $500K"
              }
            }
          }
        },
        {
          "standard": {
            "query": {
              "bool": {
                "filter": [
                  {
                    "terms": {
                      "funding_stage": [
                        "Series A",
                        "Series B"
                      ]
                    }
                  },
                  {
                    "range": {
                      "funding_amount": {
                        "gte": 8000000,
                        "lte": 25000000
                      }
                    }
                  },
                  {
                    "terms": {
                      "lead_investor": []
                    }
                  },
                  {
                    "range": {
                      "monthly_revenue": {
                        "gte": 500000,
                        "lte": 0
                      }
                    }
                  }
                ]
              }
            }
          }
        }
      ],
      "rank_window_size": 100,
      "rank_constant": 20
    }
  }
}
🎯 Found 5 startups matching your criteria:

1. **TechFlow**
   📍 San Francisco, CA | 🏢 logistics | 💼 B2B
   💰 Series A - $8.0M
   👥 45 employees | 📈 $500K MRR
   🏦 Lead: Sequoia Capital
   📝 TechFlow optimizes supply chain operations using AI-powered route optimization and real-time tracking. Founded in 2023, shows remarkable growth with $500K monthly revenue.

2. **DataViz**
   📍 New York, NY | 🏢 enterprise software | 💼 B2B
   💰 Series A - $10.0M
   👥 42 employees | 📈 $450K MRR
   🏦 Lead: Battery Ventures
   📝 DataViz creates intuitive data visualization tools for enterprise customers. No-code platform allows business users to create dashboards without technical expertise.

3. **FinanceAI**
   📍 San Francisco, CA | 🏢 fintech | 💼 B2C
   💰 Series C - $25.0M
   👥 120 employees | 📈 $1200K MRR
   🏦 Lead: Tiger Global Management
   📝 FinanceAI provides AI-powered investment advisory services to retail investors. Uses machine learning to analyze market trends with over 100,000 active users.

4. **UrbanMobility**
   📍 New York, NY | 🏢 logistics | 💼 B2B2C
   💰 Series B - $15.0M
   👥 78 employees | 📈 $750K MRR
   🏦 Lead: Kleiner Perkins
   📝 UrbanMobility revolutionizes urban transportation through autonomous delivery drones and smart logistics hubs. Partners with major retailers for same-day delivery across Manhattan and Brooklyn.

5. **HealthTech Solutions**
   📍 Boston, MA | 🏢 healthcare | 💼 B2B
   💰 Series B - $18.0M
   👥 95 employees | 📈 $900K MRR
   🏦 Lead: General Catalyst
   📝 HealthTech Solutions develops medical devices and software for remote patient monitoring. Comprehensive telehealth platform reducing hospital readmissions by 30%.

✨  Done in 18.80s.

对于这条输入，应用会选择聚焦投资维度的路径，由此我们可以看到 LangGraph 工作流生成的 Elasticsearch 查询，它会从用户输入中抽取出各类数值与区间。此外，我们还能看到应用了这些提取参数后实际发送到 Elasticsearch 的查询，以及最后由 visualizeResults 节点格式化输出的结果。

现在，我们再用这条查询来测试聚焦市场维度的节点：“查找位于旧金山、纽约或波士顿的金融科技和医疗健康初创公司”：

...

🔍 Query: Find fintech and healthcare startups in San Francisco, New York, or Boston

🤔 Search strategy: market_focused - The query is focused on finding fintech startups in San Francisco that are disrupting traditional banking and payment systems, which pertains to specific industries (fintech) and locations (San Francisco). Thus, a market-focused strategy is more appropriate.

🔍 Preparing MARKET-FOCUSED search parameters with market emphasis...

📋 Complete query: {
  "size": 5,
  "retriever": {
    "rrf": {
      "retrievers": [
        {
          "standard": {
            "query": {
              "semantic": {
                "field": "semantic_field",
                "query": "Find fintech and healthcare startups in San Francisco, New York, or Boston"
              }
            }
          }
        },
        {
          "standard": {
            "query": {
              "bool": {
                "filter": [
                  {
                    "terms": {
                      "industry": [
                        "fintech",
                        "healthcare"
                      ]
                    }
                  },
                  {
                    "terms": {
                      "location": [
                        "San Francisco, CA",
                        "New York, NY",
                        "Boston, MA"
                      ]
                    }
                  },
                  {
                    "terms": {
                      "business_model": []
                    }
                  }
                ]
              }
            }
          }
        }
      ],
      "rank_window_size": 50,
      "rank_constant": 10
    }
  }
}
🎯 Found 5 startups matching your criteria:

1. **FinanceAI**
   📍 San Francisco, CA | 🏢 fintech | 💼 B2C
   💰 Series C - $25.0M
   👥 120 employees | 📈 $1200K MRR
   🏦 Lead: Tiger Global Management
   📝 FinanceAI provides AI-powered investment advisory services to retail investors. Uses machine learning to analyze market trends with over 100,000 active users.

2. **CryptoWallet**
   📍 Miami, FL | 🏢 fintech | 💼 B2C
   💰 Series B - $16.0M
   👥 73 employees | 📈 $820K MRR
   🏦 Lead: Coinbase Ventures
   📝 CryptoWallet provides secure digital wallet solutions for cryptocurrency trading and storage. Multi-chain support with enterprise-grade security features.

...

✨  Done in 7.41s.

学习经验

在写作过程中我学到了：

• 我们必须向 LLM 提供筛选器的精确取值，否则就要完全依赖用户输入这些值。对于低基数，这种方法很好，但当基数很高时，我们需要通过一些机制来过滤结果
• 使用搜索模板比让大语言模型编写 Elasticsearch 查询能使结果更加一致，而且速度也更快
• 条件边是一种强大的机制，用于构建具有多个变体和分支路径的应用程序。
• 结构化输出在使用大型语言模型生成信息时非常有用，因为它能强制执行可预测且类型安全的响应。这不仅提高了整体可靠性，还减少了对提示词的误解。

通过混合检索结合语义和结构化搜索，可以产生更好、更相关的结果，在精确性和上下文理解之间取得平衡。

结论

在这个例子中，我们将 LangGraph.js 与 Elasticsearch 结合，创建一个动态工作流，能够解释自然语言查询并决定使用金融或市场聚焦的搜索策略。这种方法减少了手工查询的复杂性，同时提升了风险投资分析师的灵活性和准确性。

变量控件是什么？

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

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

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

变量控件用例

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

筛选已选择的可视化内容

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

选择不同的时间间隔

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

更改函数

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

按不同字段分组

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

如何创建？

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

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

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

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

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

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

FROM 
| WHERE @timestamp <=?_tend and @timestamp >?_tstart
| STATS BY 

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（用于切换数据源）等操作符结合使用。好消息是什么？我们正在着手添加这些功能。

控件的未来发展趋势

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

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

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

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

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

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

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

回顾

先简单回顾一下最新动态。Elasticsearch 现已确立其作为强大向量数据库的地位，在大规模相似性搜索方面提供了丰富的功能和强劲的性能。凭借标量量化、Better Binary Quantization (BBQ)、SIMD 向量运算以及 DiskBBQ 等在磁盘利用方面更高效的算法，Elasticsearch 已经为管理向量工作负载提供了高效而灵活的多种选项。

通过将 NVIDIA cuVS 集成为可调用的向量搜索模块，我们希望大幅提升向量索引的性能和效率，从而更好地支撑大规模向量工作负载。

挑战

构建高性能向量数据库的最大挑战之一，就是构建向量索引，即 HNSW 图。随着每个向量都要与大量其他向量进行比对，索引构建很快就会被数以百万乃至数十亿次的算术运算所主导。此外，压缩、合并等索引生命周期操作还会进一步增加索引的整体计算开销。随着数据量和相关向量嵌入呈指数级增长，专为大规模并行和高吞吐量数值运算而设计的加速计算 GPU 非常适合处理这些工作负载。

进入 Elasticsearch-GPU 插件

NVIDIA cuVS是一个开源的 CUDA-X 库，用于 GPU 加速的向量搜索和数据集群，能够为 AI 和推荐工作负载快速构建索引和嵌入检索。

Elasticsearch 通过 cuvs-java 使用 cuVS，这是一个由社区开发并由 NVIDIA 维护的开源库。cuvs-java 库十分轻量，基于 cuVS C API 构建，并借助 Panama 外部函数接口，以符合 Java 习惯用法的方式暴露 cuVS 功能，同时兼具现代性和高性能。

cuvs-java 库被集成到一个新的 Elasticsearch 插件中；因此，GPU 上的向量索引可在同一 Elasticsearch 节点和同一进程内完成，无需部署任何外部组件或额外硬件。在索引构建过程中，如果已安装 cuVS 库且存在已正确配置的 GPU，Elasticsearch 会利用 GPU 加速向量索引过程。向量会被传递给 GPU，由 GPU 构建 CAGRA 图。随后将该图转换为 HNSW 格式，使其能够立即在 CPU 上用于向量搜索。构建完成的图，其最终格式与在 CPU 上构建的图完全一致；这使得在底层硬件支持的情况下，Elasticsearch 可以利用 GPU 实现高吞吐量的向量索引，同时释放 CPU 算力，用于并发搜索、数据处理等其他任务。

索引构建加速

作为将 GPU 加速集成到 Elasticsearch 的一部分，对 cuvs-java 进行了多项增强，重点是高效的数据输入/输出和函数调用。一项关键增强是使用 cuVSMatrix 对向量进行透明建模，无论它们位于 Java 堆中、堆外还是 GPU 内存中。这使数据可以在内存与 GPU 之间高效传输，避免对可能多达数十亿个向量进行不必要的复制。

由于这种底层的零拷贝抽象，数据传输到 GPU 内存以及从中检索图时都可以直接完成。在索引过程中，向量首先缓存在 Java 堆内存中，然后发送到 GPU，以构建 CAGRA 图。随后，从 GPU 中取回该图，将其转换为 HNSW 格式，并持久化到磁盘。

在合并时，向量已经存储在磁盘上，完全绕过了 Java 堆。索引文件采用内存映射，数据直接传输到 GPU 内存中。该设计还能轻松适应不同的位宽，如 float32 或 int8，并自然扩展到其他量化方案。

话不多说，那它的实际表现如何呢？

在我们探讨数字之前，了解一些背景信息会有所帮助。在索引期间，Elasticsearch 中的分段合并通常在后台自动运行，这会导致在隔离环境中进行基准测试变得十分困难。为了获得可重复的结果，我们使用了强制合并来在受控实验中明确触发分段合并。由于强制合并与后台合并执行相同的底层合并操作，因此其性能可作为预期改进的有用指标，尽管在实际索引工作负载中，具体收获可能会有所不同。

现在让我们来探讨数字。

我们的初步基准测试结果非常令人鼓舞。我们在 AWS g6.4xlarge 实例上运行了基准测试，该实例具有本地连接的 NVMe 存储。我们将单个 Elasticsearch 节点配置为使用默认的最佳索引线程数（8 个，每个物理核心一个），并关闭合并限速功能（在使用快速 NVMe 磁盘时，这一功能的适用性较低）。

对于数据集，我们使用了 OpenAI Rally 向量赛道中的 260 万个、每个具有 1,536 维的向量，将其编码为 base64 字符串，并以 float32 hnsw 结构进行索引。在所有场景中，构建的图都能达到最高约 95% 的召回率。以下是我们的发现：

• 索引吞吐量：通过在内存缓冲区刷新期间将图构建移交给 GPU 处理，我们将吞吐量提高了约 12 倍。
• 强制合并：索引完成后，GPU 继续加速分段合并，将强制合并阶段加快约 7 倍。

• CPU 使用率：将图构建任务分流到 GPU，可显著降低 CPU 的平均和峰值利用率。以下图表展示了索引和合并期间的 CPU 使用情况，凸显了在 GPU 上运行这些操作时 CPU 使用率的显著降低。GPU 索引期间降低 CPU 使用率，可释放 CPU 周期并重新分配，从而提升搜索性能。

• 召回率：在 CPU 与 GPU 的运行结果中，准确性几乎一致，而 GPU 所构建的图在召回率方面略胜一筹。

再从价格这个维度来进行比较

前面的对比特意选用了相同的硬件配置，唯一的区别只是索引时是否启用 GPU。这种设置有助于单独考察计算性能的影响，不过也可以从成本角度来进行对比。

在与 GPU 加速配置大致相同的按小时费用下，可以搭建一套仅使用 CPU 的环境，其 CPU 和内存资源大约是前者的两倍：32 个 vCPU（AMD EPYC）和 64 GB RAM，因而可将索引线程数量增加到 16

为了保持比较的公平和一致性，我们在 AWS g6.8xlarge 实例上运行了这个仅 CPU 的实验，并且明确禁用了 GPU。这使我们能够在评估 GPU 加速与仅 CPU 索引的成本-性能权衡时，保持所有其他硬件特性不变。

正如您所预期的那样，更强大的 CPU 实例与上述部分的基准测试相比，性能确实有所提高。然而，将这一性能更强的 CPU 实例与最初的 GPU 加速结果进行对比后可以看到，GPU 依然带来显著性能提升：索引吞吐量提高约 5 倍，强制合并阶段加速约 6 倍，同时构建的图其召回率最高可达 95%。

结论

在端到端场景中，使用 NVIDIA cuVS 进行的 GPU 加速使索引吞吐量提高了近 12 倍，将强制合并延迟降低到原来的 1/7，同时显著降低了 CPU 利用率。这表明向量索引和合并工作负载从 GPU 加速中受益显著。在成本调整后的对比中，GPU 加速依然带来显著的性能提升：索引吞吐量约提升 5 倍，强制合并操作的速度提升约 6 倍。

GPU 加速的向量索引目前计划在 Elasticsearch 9.3 的技术预览版中推出，该版本计划于 2026 年初发布。

敬请关注更多内容。

下面将介绍 Elasticsearch 9.2 中的功能，这些功能将利用 ES|QL 改变您的数据分析工作流。

数据关联的革命：更智能、更快速、更灵活的 Lookup Join

在 Elasticsearch 9.2 中，ES|QL 中的 LOOKUP JOIN 命令发生了重大变化，变得更加高效和多功能。LOOKUP JOIN 将 ES|QL 查询结果表中的数据与指定查找模式索引中的匹配记录结合起来。它会根据连接字段中的匹配值，将查找索引中的字段作为新列添加到结果表中。以前，连接数据仅限于单一字段和简单相等。不再是这样了！这些增强功能使您能够轻松应对复杂的数据关联方案。

Lookup Join 的主要增强功能包括：

• 多字段连接：轻松连接多个字段。例如，要将 application_logs 与 service_registry 连接到 service_name，environment 和 version:

FROM application_logs
| LOOKUP JOIN service_registry ON service_name, environment, version

• 使用表达式释放复杂的连接谓词（技术预览）：

您不再局限于简单相等。LOOKUP JOIN 现在允许您指定多个相关性标准，并纳入一系列二进制运算符，包括 ==、 !=、<、>、<= 和 >=。这意味着您可以创建高度细致的连接条件，从而能够对数据提出更复杂的问题。

示例 1：使用按服务 SLA 阈值查找应用程序指标

FROM application_metrics
| LOOKUP JOIN sla_thresholds
      ON service_name == sla_service AND response_time > sla_response_time

示例 2：此查询根据随时间变化的地区定价政策计算应付金额。它根据复杂的日期范围和相等条件连接三个数据集，计算出最终的 due_amount。第二个查找连接使用 meter_readings 索引中的measurement_date 字段和customers 索引中的region_id 字段连接到pricing_policies 索引，并为特定 region 和 measurement_date 查找正确的定价策略。

FROM meter_readings
| LOOKUP JOIN customers
      ON meter_id
| LOOKUP JOIN pricing_policies
      ON
        region_id == region AND
          measurement_date >= policy_begin_date AND
          measurement_date < policy_end_date
| EVAL due_amount = (kwh_consumed * rate_per_kwh + base_charge) * (1 + tax_rate)
| EVAL period = policy_name
| KEEP customer_name, period, due_amount, measurement_date, kwh_consumed,
    rate_per_kwh, base_charge, tax_rate
| SORT measurement_date

• 过滤连接带来的巨大性能提升：

我们提高了使用查找表条件筛选的“扩展连接”的性能。扩展连接会使每条输入行产生多个匹配项，从而产生较大的中间结果集。当后续筛选器丢弃其中许多行时，情况会变得更糟。在 9.2 中，我们通过在对查找数据应用筛选器时筛选掉不必要的行来优化这些连接，而避免处理将被丢弃的行。在某些情况下，这些连接的速度最多可以快 1000 倍！

这种优化在处理“扩展连接”时至关重要，因为在这种情况下，查找最初可能会产生许多潜在的匹配项。通过智能推送筛选器，仅处理相关数据，从而大幅缩短查询执行时间，实现对海量数据集的实时分析。这意味着，即使是大型或复杂的连接操作，您也能更快地获得见解。

Lookup Join 跨集群搜索 (CCS) 兼容性：

当 Lookup Join 在 8.19 和 9.1 版本中正式发布时，它缺少跨集群搜索 (CCS) 支持。对于在多个集群中运行的组织，LOOKUP JOIN 现在可与 9.2 中的 CCS 无缝集成。只需在要执行连接的所有远程集群上放置查找索引，ES|QL 就会自动利用这些远程查找索引来连接远程数据。这简化了分布式数据分析，并确保在整个 Elasticsearch 部署中实现一致的丰富性。

这些改进意味着您可以以前所未有的精度、速度和便捷性关联各种数据集，从而发现更深入、更具可操作性的见解，而无需复杂的替代方案或预处理步骤。

轻松丰富您的数据：适用于 Lookup 索引的 Kibana Discover 用户体验

数据丰富应该简单，而不是障碍。我们在 Kibana 的 Discover 中为创建和管理查找索引引入了绝佳的全新用户体验。

直观的工作流：Discover 全面的自动完成功能将引导您完成整个流程，并在 ES|QL 编辑器中建议查找索引和连接字段，使您可以非常轻松地将上传的数据与现有索引连接起来。键入一个不存在的查找索引名称，然后直接访问 Lookup 编辑器，只需单击一下即可创建索引。键入现有查找索引的名称，我们将为您提供编辑该索引的选项：

在线管理 (CRUD)：直接在 Discover 中使用行内编辑功能（创建、读取、更新、删除），使参考数据集保持最新状态。

轻松上传文件：现在，您可以在 Discover 中直接上传 CSV 等文件，并立即在 LOOKUP JOIN 中使用这些文件。再也不需要在 Kibana 的不同区域之间来回切换上下文了！

无论您是将用户 ID 映射到名称、添加业务元数据，还是连接静态参考文件，此功能都能让数据丰富化变得触手可及，将连接的强大功能直接交到每个用户的手中——快速、简单且集中于一处。

保留上下文：INLINE STATS 简介（技术预览）

数据聚合至关重要，但有时您需要在查看原始数据的同时查看聚合数据。我们很高兴将 INLINE STATS 作为技术预览功能推出。

STATS 命令会将输入字段替换为聚合输出，而INLINE STATS 命令则不同，它保留了所有原始输入字段，只是添加了新的聚合字段。这样，您就可以在聚合后对原始输入字段执行进一步操作，从而提供更连续、更灵活的分析工作流。

例如，要在计算平均飞行距离的同时保留单个飞行记录行：

FROM kibana_sample_data_flights
 | KEEP Carrier, Dest, DistanceMiles
 | INLINE STATS avgDist = ROUND(AVG(DistanceMiles))
       BY Dest
 | WHERE DistanceMiles > avgDist

在此查询中，将 avgDist 与我们分组的相应 Dest (ination) 添加到每一行中，然后，由于我们仍有航班信息列，我们可以将结果筛选为飞行距离大于平均值的航班。

ES|QL 中的时间序列支持（技术预览版）

Elasticsearch 使用时序数据流来存储指标。我们将通过 TS 源代码命令在 ES|QL 中添加对时间序列聚合的支持。此功能在 Elastic Cloud serverless 和 9.2 基础版中以技术预览版的形式提供。

时间序列分析主要基于聚合查询，这些查询按照一个或多个筛选维度对时间分桶的指标值进行汇总。大多数聚合查询依靠两步处理，包括：(a) 内部聚合函数对每个时间序列的值进行汇总，以及 (b) 外部聚合函数将 (a) 的结果在时间序列之间进行组合。

TS 源命令与 STATS 结合使用，为表达对时间序列的查询提供了一种简洁而有效的方法。具体来说，请考虑以下计算每个主机和每小时的总请求率的示例：

TS my_metrics
| WHERE @timestamp > NOW() - 1 day
| STATS SUM(RATE(requests))
      BY host, TBUCKET(1h)

在这种情况下，首先对每个时间序列和每个小时的时间序列聚合函数 RATE 进行评估。生成的部分聚合值随后使用 SUM 进行组合，以计算每个主机和每小时的最终聚合值。

您可以在此处查看可用的时间序列聚合函数列表。现在支持计数率，这可以说是处理计数器最重要的聚合功能。

TS 源命令旨在与STATS 结合使用，其执行经过调整，可有效支持时间序列聚合。例如，数据在进入STATS 之前要进行排序。目前不允许在 TS 和 STATS 之间执行可能丰富或改变时序数据或其顺序的处理命令，例如 FORK 或 INLINE STATS。将来可能会取消这一限制。

STATS 表格输出可使用任何适用命令进行进一步处理。例如，以下查询计算每台主机和每小时的平均 cpu_usage 与最大值的比率：

TS my_metrics
| STATS avg_usage = AVG(AVG_OVER_TIME(cpu_usage))
      BY host, time_bucket = TBUCKET(1h)
| INLINE STATS max_avg_usage = MAX(avg_usage)
      BY host
| EVAL ratio = avg_usage / max_avg_usage
| KEEP host, time_bucket, ratio
| SORT host, time_bucket DESC

时序数据存储在我们基于 Lucene 文档值的底层列式存储引擎中。TS 命令通过 ES|QL 计算引擎增加了向量化查询执行功能。与等效的DSL查询相比，查询性能往往提高一个数量级以上，并可与已建立的特定度量系统相媲美。我们将在未来提供详细的架构和性能分析，敬请期待。

扩展您的工具包：ES|QL 新功能

字符串操作：CONTAINS、MV_CONTAINS、URL_ENCODE、URL_ENCODE_COMPONENT、URL_DECODE，用于更强大的文本和 URL 处理。

时间序列和地理空间： TBUCKET用于灵活的时间分桶，TO_DENSE_VECTOR 用于矢量运算，以及一套全面的地理空间函数，如ST_GEOHASH 、 ST_GEOTILE 、 ST_GEOHEX 、 TO_GEOHASH 、 TO_GEOTILE 、 TO_GEOHEX用于高级基于位置的分析。

日期格式：使用 DAY_NAME、MONTH_NAME，以获得更易读的日期表示形式。

这些功能为您提供了一套更丰富的工具，可直接在 ES|QL 中操作和分析您的数据。

内在优势：更高的性能和效率

除了上述突出的功能外，Elasticsearch 9.2 还对 ES|QL 进行了大量性能优化。在函数能够替代多个类似 RLIKE 查询的情况下，我们使用 pushdown 加快了 RLIKE(LIST) 的执行速度。通过 RLIKE (LIST)，我们可以将这些查询合并为一个自动机，并应用一个自动机而不是多个自动机。我们还通过索引排序加快了关键字字段的加载速度，并对一般查询进行了优化——这些改进可确保您的 ES|QL 查询比以往更高效地运行。

立即开始！

Elasticsearch 9.2 标志着 ES|QL 的重大飞跃，为您的数据分析工作流带来了前所未有的强大功能和灵活性。我们鼓励您探索这些新功能，并体验它们带来的不同。

有关 Elasticsearch 9.2 中所有更改和增强功能的完整列表，请参阅正式发布说明。祝您查询愉快！

定制连接器使您能够将现有的 ChatGPT 连接器与其他数据源（如 Elasticsearch）结合，以获得全面的答案。

在本文中，我们将构建一个 MCP 服务器，将 ChatGPT 连接到包含内部 GitHub 问题和拉取请求信息的 Elasticsearch 索引。这样就可以使用 Elasticsearch 数据回答自然语言查询。

我们将在 Google Colab 上使用 FastMCP 和 ngrok 部署 MCP 服务器，以获取 ChatGPT 可以连接的公共 URL，从而省去复杂的基础架构设置。

有关 MCP 及其生态系统的全面概述，请参阅《MCP 的现状》。

准备工作

在开始之前，您需要：

• Elasticsearch 集群（8.X 或更高版本）
• Elasticsearch API密钥，具有对您的索引的读取访问权限
• Google 账户（用于 Google Colab）
• Ngrok账户 （免费套餐可用）
• 拥有专业版/企业版/商务版或教育版套餐的 ChatGPT 账户

了解 ChatGPT MCP 连接器的要求

ChatGPT MCP 连接器需要实现两个工具：search 和 fetch。有关更多详情，请参阅 OpenAI 文档。

搜索工具

根据用户查询，从 Elasticsearch 索引中返回相关结果列表。

接收的内容：

• 一个单一的字符串，包含用户的自然语言查询。
• 示例：“查找与 Elasticsearch 迁移相关的问题。”

返回的内容：

• 一个对象，其result 关键字包含一个结果对象数组。每个结果包括：
  • id - 唯一文档标识符
  • title - 问题或拉取请求标题
  • url - 链接到问题或 PR

在我们的实现中：

return {
    "results": [
        {
            "id": "PR-612",
            "title": "Fix memory leak in WebSocket notification service",
            "url": "https://internal-git.techcorp.com/pulls/612"
        },
        # ... more results
    ]
}

获取工具

获取指定文档的完整内容。

接收的内容：

• 搜索结果中包含 Elasticsearch 文档 ID 的单个字符串
• 示例：“获取 PR-578 的详细信息。”

它返回的内容：

• 一个完整的文档对象，包含：
  • id - 唯一文档标识符
  • title - 问题或拉取请求标题
  • text - 完整的问题/PR描述和详细信息
  • url - 链接到问题或 PR
  • type - 文档类型（问题、pull_request）
  • status - 当前状态（打开、进行中、已解决）
  • priority - 优先级别（低、中、高、关键）
  • assignee - 负责此问题/PR 的人员
  • created_date - 何时创建
  • resolved_date - 何时解决（如适用）
  • labels - 与文件相关的标签
  • related_pr － 相关拉取请求 ID

return {
    "id": "PR-578",
    "title": "Security hotfix: Patch SQL injection vulnerabilities",
    "text": "Description: CRITICAL SECURITY FIX for ISSUE-1889. Patches SQL...",
    "url": "https://internal-git.techcorp.com/pulls/578",
    "type": "pull_request",
    "status": "closed",
    "priority": "critical",
    "assignee": "sarah_dev",
    "created_date": "2025-09-19",
    "resolved_date": "2025-09-19",
    "labels": "security, hotfix, sql",
    "related_pr": null
}

注意：本示例使用扁平结构，其中所有字段都位于根级别。OpenAI 的要求非常灵活，还支持嵌套的元数据对象。

GitHub 问题和 PR 数据集

在本教程中，我们将使用包含问题和拉取请求的内部 GitHub 数据集。这代表了一个您希望通过 ChatGPT 查询私有、内部数据的场景。

数据集可以在此处找到。我们将使用批量 API 更新数据索引。

这个数据集包含：

• 有关描述、状态、优先级和分配人员的问题
• 包含代码更改、审查和部署信息的拉取请求
• 问题与 PR 之间的关系（例如，PR-578 修复了 ISSUE-1889）
• 标签、日期和其他元数据

索引映射

该索引使用以下映射来支持使用 ELSER 的混合搜索。text_semantic 用于语义搜索，而其他字段用于关键字搜索。

{
  "mappings": {
    "properties": {
      "id": {
        "type": "keyword"
      },
      "title": {
        "type": "text"
      },
      "text": {
        "type": "text"
      },
      "text_semantic": {
        "type": "semantic_text",
        "inference_id": ".elser-2-elasticsearch"
      },
      "url": {
        "type": "keyword"
      },
      "type": {
        "type": "keyword"
      },
      "status": {
        "type": "keyword"
      },
      "priority": {
        "type": "keyword"
      },
      "assignee": {
        "type": "keyword"
      },
      "created_date": {
        "type": "date",
        "format": "iso8601"
      },
      "resolved_date": {
        "type": "date",
        "format": "iso8601"
      },
      "labels": {
        "type": "keyword"
      },
      "related_pr": {
        "type": "keyword"
      }
    }
  }
}

构建MCP服务器

我们的 MCP 服务器按照 OpenAI 规范实现了两个工具，使用混合搜索将语义和文本匹配相结合，以获得更好的结果。

搜索工具

利用 RRF（倒数排序融合）进行混合搜索，将语义搜索与文本匹配相结合：

@mcp.tool()
    async def search(query: str) -> Dict[str, List[Dict[str, Any]]]:
        """
        Search for internal issues and PRs using hybrid search (semantic + text with RRF).
        Returns list with id, title, and url per OpenAI spec.
        """
        if not query or not query.strip():
            return {"results": []}

        logger.info(f"Searching for: '{query}'")

        try:
            # Hybrid search with RRF (Reciprocal Rank Fusion)
            response = es_client.search(
                index=ELASTICSEARCH_INDEX,
                size=10,
                source=["id", "title", "url", "type", "priority"],
                retriever={
                    "rrf": {
                        "retrievers": [
                            {
                                # Semantic search with ELSER
                                "standard": {
                                    "query": {
                                        "semantic": {
                                            "field": "text_semantic",
                                            "query": query
                                        }
                                    }
                                }
                            },
                            {
                                # Text search (BM25) for keyword matching
                                "standard": {
                                    "query": {
                                        "multi_match": {
                                            "query": query,
                                            "fields": [
                                                "title^3",
                                                "text^2",
                                                "assignee^2",
                                                "type",
                                                "labels",
                                                "priority"
                                            ],
                                            "type": "best_fields",
                                            "fuzziness": "AUTO"
                                        }
                                    }
                                }
                            }
                        ],
                        "rank_window_size": 50,
                        "rank_constant": 60
                    }
                }
            )

            results = []
            if response and 'hits' in response:
                for hit in response['hits']['hits']:
                    source = hit['_source']
                    results.append({
                        "id": source.get('id', hit['_id']),
                        "title": source.get('title', 'Unknown'),
                        "url": source.get('url', '')
                    })

            logger.info(f"Found {len(results)} results")
            return {"results": results}

        except Exception as e:
            logger.error(f"Search error: {e}")
            raise ValueError(f"Search failed: {str(e)}")

要点：

• 使用 RRF 的混合搜索：结合语义搜索 (ELSER) 和文本搜索 (BM25)，以获得更好的结果。
• 多匹配查询：在多个字段中进行搜索，并使用增强功能（标题^3、文本^2、分配人员^2）。插入符号 (^) 会乘以相关性分数，优先考虑标题中的匹配项而非内容中的匹配项。
• 模糊匹配：fuzziness: AUTO 通过允许近似匹配来处理错别字和拼写错误。
• RRF 参数调整：
  • rank_window_size: 50 - 指定在合并之前从每个检索器（语义和文本）中考虑最靠前结果的数量。
  • rank_constant: 60 - 该值决定了单个结果集中的文档对最终排序结果的影响程度。
• 仅返回必填字段：根据 OpenAI 规范返回 id、title、url，避免不必要地暴露其他字段。

获取工具

按文档 ID（如果存在）检索文档详细信息：

@mcp.tool()
    async def fetch(id: str) -> Dict[str, Any]:
        """
        Retrieve complete issue/PR details by ID.
        Returns id, title, text, url.
        """
        if not id:
            raise ValueError("ID is required")

        logger.info(f"Fetching: {id}")

        try:
            # Search by the 'id' field (not _id) since IDs are stored as a field
            response = es_client.search(
                index=ELASTICSEARCH_INDEX,
                body={
                    "query": {
                        "term": {
                            "id": id  # Search by your custom 'id' field
                        }
                    },
                    "size": 1
                }
            )

            if not response or not response['hits']['hits']:
                raise ValueError(f"Document with id '{id}' not found")

            hit = response['hits']['hits'][0]
            source = hit['_source']

            result = {
                "id": source.get('id', id),
                "title": source.get('title', 'Unknown'),
                "text": source.get('text', ''),
                "url": source.get('url', ''),
                "type": source.get('type', ''),
                "status": source.get('status', ''),
                "priority": source.get('priority', ''),
                "assignee": source.get('assignee', ''),
                "created_date": source.get('created_date', ''),
                "resolved_date": source.get('resolved_date', ''),
                "labels": source.get('labels', ''),
                "related_pr": source.get('related_pr', '')
            }

            logger.info(f"Fetched: {result['title']}")
            return result

        except Exception as e:
            logger.error(f"Fetch error: {e}")
            raise ValueError(f"Failed to fetch '{id}': {str(e)}")

要点：

• 按文档 ID 字段进行搜索：使用自定义 id 字段上的术语查询
• 返回完整文档：包含完整的 text 字段及其所有内容
• 扁平结构：所有字段均位于根级别，与 Elasticsearch 的文档结构相匹配。

在 Google Colab 上部署

我们将使用 Google Colab 来运行 MCP 服务器，并使用 ngrok 将其公开，以便 ChatGPT 可以连接到它。

步骤 1：打开 Google Colab 笔记本

访问我们预配置的笔记本适用于 ChatGPT 的 Elasticsearch MCP。

步骤 2：配置您的凭据

您需要三项信息：

• Elasticsearch URL：您的 Elasticsearch 集群 URL。
• Elasticsearch API 密钥：具有索引读取权限的 API 密钥。
• Ngrok 身份验证令牌：来自 ngrok 的免费令牌。我们将使用 ngrok 将 MCP URL 公开到互联网，以便 ChatGPT 可以连接到它。

获取 ngrok 令牌

1. 在 ngrok 注册免费账户
2. 前往您的 ngrok 仪表板
3. 复制您的身份验证令牌

为 Google Colab 添加机密

在 Google Colab 笔记本中：

1. 点击左侧边栏中的“密钥图标”以打开“机密”。
2. 添加这三个秘密：

ELASTICSEARCH_URL=https://your-cluster.elastic.com:443
ELASTICSEARCH_API_KEY=your-api-key
NGROK_TOKEN=your-ngrok-token

3. 为每个机密启用笔记本访问权限

步骤 3：运行 Notebook

1. 点击“运行时”，然后点击“全部运行”，以执行所有单元格
2. 等待服务器启动（约30秒）
3. 查找显示您的公开 ngrok URL 的输出

4. 该输出将显示如下内容：

连接 ChatGPT

现在我们将 MCP 服务器连接到您的 ChatGPT 账户。

1. 打开 ChatGPT，前往“设置”。
2. 导航到“连接器”。如果您使用的是专业版账户，则需要在连接器中打开“开发者模式”。

如果您使用的是 ChatGPT 企业版或商业版，您需要将连接器发布到您的工作场所。

3. 点击“创建”。

注意：在商业版、企业版和教育版工作区中，只有工作区所有者、管理员和已启用相应设置（针对企业版/教育版）的用户才能添加自定义连接器。具有普通成员角色的用户无法自行添加自定义连接器。

一旦连接器被所有者或管理员用户添加并启用，工作区中的所有成员即可使用该连接器。

4. 输入所需信息和以 /sse/ 结尾的 ngrok URL。请注意“sse”后面的“/”。没有它就无法正常工作：

• 名字： Elasticsearch MCP
• 描述：用于搜索和获取 GitHub 内部信息的自定义 MCP。

5. 按下“创建”保存自定义 MCP。

如果您的服务器正在运行，则连接是即时的。无需额外的身份验证，因为 Elasticsearch API 密钥已在服务器中配置。

测试 MCP 服务器

在提问之前，您需要先选择 ChatGPT 应该使用的连接器。

提示 1: 搜索问题

提问：“查找与 Elasticsearch 迁移相关的问题”并确认操作工具调用。

ChatGPT 将调用search 工具处理您的查询。你可以看到它正在查找可用工具，并准备调用 Elasticsearch 工具，在对该工具执行任何操作之前与用户确认。

工具调用请求：

{
  "query": "Elasticsearch migration issues"
}

工具响应：

{
  "results": [
    {
      "id": "PR-598",
      "title": "Elasticsearch 8.x migration - Application code changes",
      "url": "https://internal-git.techcorp.com/pulls/598"
    },
    {
      "id": "ISSUE-1712",
      "title": "Migrate from Elasticsearch 7.x to 8.x",
      "url": "https://internal-git.techcorp.com/issues/1712"
    },
    {
      "id": "RFC-045",
      "title": "Design Proposal: Microservices Migration Architecture",
      "url": "https://internal-git.techcorp.com/rfcs/045"
    }
    // ... 7 more results
  ]
}

ChatGPT 会处理这些结果，并以自然对话的形式呈现。

幕后

提示：“查找与 Elasticsearch 迁移相关的问题”

1. ChatGPT 调用 search(“Elasticsearch migration”)

2. Elasticsearch 执行混合搜索。

• 语义搜索能理解“升级”和“版本兼容性”等概念。
• 文本搜索可查找与“Elasticsearch”和“迁移”完全匹配的内容。
• RRF 将两种方法的结果进行合并和排序

3. 返回与 id、title 匹配度最高的 10 个事件。 url

4. ChatGPT 将“ISSUE-1712：从 Elasticsearch 7.x 迁移到 8.x”作为最相关的结果

提示 2：获取完整的详细信息

问：“请提供有关 ISSUE-1889 的详细信息”

ChatGPT 识别到您需要有关特定问题的详细信息，并调用 fetch 工具，在对该工具采取任何行动前与用户确认。

工具调用请求：

{
  "id": "ISSUE-1889"
}

工具响应：

{
  "id": "ISSUE-1889",
  "title": "SQL injection vulnerability in search endpoint",
  "text": "Description: Security audit identified SQL injection vulnerability in /api/v1/search endpoint. User input from query parameter is not properly sanitized before being used in raw SQL query. Severity: HIGH - Immediate action required Affected Code: - File: services/search/query_builder.py - Line: 145-152 - Issue: String concatenation used instead of parameterized queries Investigation: - @security_team_alice: Confirmed exploitable with UNION-based injection - @sarah_dev: Checking all other endpoints for similar patterns - @john_backend: Found 3 more instances in legacy codebase Remediation: - Rewrite using SQLAlchemy ORM or parameterized queries - Add input validation and sanitization - Implement WAF rules as additional layer - Security regression tests Comments: - @tech_lead_mike: Stop all other work, this is P0 - @sarah_dev: PR-578 ready with fixes for all 4 vulnerable endpoints - @alex_devops: Deployed hotfix to production 2025-09-19 at 14:30 UTC - @security_team_alice: Verified fix, conducting full pentest next week Resolution: All vulnerable endpoints patched. Added pre-commit hooks to catch raw SQL queries. Security training scheduled for team.",
  "url": "https://internal-git.techcorp.com/issues/1889",
  "type": "issue",
  "status": "closed",
  "priority": "critical",
  "assignee": "sarah_dev",
  "created_date": "2025-09-18",
  "resolved_date": "2025-09-19",
  "labels": "security, vulnerability, bug, sql",
  "related_pr": "PR-578"
}

ChatGPT 会整合信息并清晰呈现。

幕后

提示：“获取有关 ISSUE-1889 的详细信息”

1. ChatGPT 调用 fetch(“ISSUE-1889”)
2. Elasticsearch 会检索完整文档
3. 返回一个包含所有字段在根级别的完整文档
4. ChatGPT会综合信息并提供正确的引用。

结论

在本文中，我们构建了一个自定义 MCP 服务器，使用专用的搜索和获取 MCP 工具将 ChatGPT 连接到 Elasticsearch，从而实现对私有数据的自然语言查询。

这种 MCP 模式适用于任何您想通过自然语言查询的 Elasticsearch 索引、文档、产品、日志或其他数据。

代理 RAG 简介

检索增强生成（RAG）已成为基于 LLM 的应用的基石，它使模型能够根据用户查询检索相关上下文，从而提供最佳答案。RAG 系统通过从应用程序接口或数据存储中获取外部信息，而不是局限于预先训练的 LLM 知识，从而提高了 LLM 响应的准确性和上下文。另一方面，人工智能代理可自主运行，为实现指定目标做出决策并采取行动。

代理 RAG 是一个将检索增强生成和代理推理的优势结合在一起的框架。它将 RAG 集成到代理的决策过程中，使系统能够动态地选择数据源，改进查询以获得更好的上下文检索，生成更准确的响应，并应用反馈循环来不断提高输出质量。

代理 RAG 的主要特点

代理 RAG 框架标志着传统 RAG 系统的重大进步。它不再遵循固定的检索流程，而是利用能够实时规划、执行和优化结果的动态代理。

让我们来看看代理 RAG 管道的一些主要特点：

• 动态决策：Agentic RAG 使用推理机制来理解用户的意图，并将每个查询路由到最相关的数据源，从而生成准确且能感知上下文的响应。
• 全面的查询分析：Agentic RAG 深入分析用户查询，包括子问题及其总体意图。它能评估查询的复杂性，并动态选择最相关的数据源来检索信息，确保准确和完整的响应。
• 多阶段协作：该框架通过专业代理网络实现多阶段协作。每个代理处理更大目标中的特定部分，依次或同时工作，以实现协调一致的结果。
• 自我评估机制：代理式 RAG 管道利用自我反思来评估检索到的文档和生成的回复。它可以检查检索到的信息是否完全符合查询要求，然后审查输出信息的准确性、完整性和事实一致性。
• 与外部工具集成：该工作流程可与外部应用程序接口、数据库和实时信息源交互，纳入最新信息并动态适应不断变化的数据。

代理 RAG 的工作流程模式

工作流模式定义了代理人工智能如何以可靠、高效的方式构建、管理和协调基于 LLM 的应用程序。一些框架和平台，如 LangChain 、 LangGraph 、 CrewAI 和 LlamaIndex ，可用于实现这些代理工作流。

1. 顺序检索链：顺序工作流将复杂的任务划分为简单、有序的步骤。每一步都会改进下一步的输入，从而取得更好的结果。例如，在创建客户档案时，一名代理可能会从客户关系管理中获取基本信息，另一名代理可能会从交易数据库中检索购买历史记录，最后一名代理可能会将这些信息结合起来，生成一份完整的客户档案，用于推荐或报告。
2. 路由检索链：在这种工作流程模式中，路由器代理分析输入，并将其导向最合适的流程或数据源。当存在多个不同的数据源且重叠程度极低时，这种方法尤为有效。例如，在客户服务系统中，路由器代理会对收到的请求（如技术问题、退款或投诉）进行分类，并将其路由到相应的部门进行有效处理。
3. 并行检索链：在这种工作流程模式中，多个独立的子任务同时执行，然后将其输出汇总，生成最终响应。这种方法大大缩短了处理时间，提高了工作流程效率。例如，在客户服务并行工作流程中，一名代理检索过去的类似请求，另一名则查阅相关的知识库文章。然后，聚合器将这些输出合并起来，生成一份综合决议。
4. Orchestrator 工作链：这种工作流程与并行化有相似之处，因为它利用了独立的子任务。然而，一个关键的区别在于集成了一个协调代理。该代理负责分析用户查询，在运行期间将查询动态地划分为子任务，并确定制定准确回复所需的适当流程或工具。

从零开始建立代理 RAG 管道

为了说明代理 RAG 的原理，让我们使用 LangChain 和 Elasticsearch 设计一个工作流程。该工作流程采用基于路由的架构，多个代理协作分析查询、检索相关信息、评估结果并生成一致的回复。您可以参考这个Jupyter 笔记本来学习这个示例。

工作流程从路由器代理开始，路由器代理分析用户的查询，选择最佳检索方法，即vectorstore 、websearch 或composite 方法。矢量存储处理传统的基于 RAG 的文档检索，网络搜索获取未存储在矢量存储中的最新信息，而复合方法则在需要来自多个来源的信息时将两者结合起来。

如果文件被认为合适，摘要代理就会生成清晰且与上下文相符的回复。但是，如果文档不足或不相关，查询重写代理就会重新制定查询，以改进搜索。修改后的查询会重新启动路由过程，使系统能够改进搜索并提高最终输出结果。

准备工作

该工作流程依靠以下核心组件来有效执行示例：

• Python 3.10
• Jupyter 笔记本
• Azure OpenAI
• Elasticsearch
• LangChain

在继续之前，系统会提示您配置本例所需的以下环境变量。

AZURE_OPENAI_ENDPOINT="Add your azure openai endpoint"
AZURE_OPENAI_KEY="Add your azure openai key"
AZURE_OPENAI_DEPLOYMENT="gpt-4.1"
AZURE_OPENAI_API_VERSION="Add your azure openai api version"

ES_ENDPOINT = "Add your Elasticsearch ENDPOINT"
ES_API_KEY = "Add your Elasticsearch API KEY"

数据来源

本工作流程使用 AG 新闻数据集的一个子集进行说明。数据集包含不同类别的新闻文章，如国际、体育、商业和科学/技术。

dataset = load_dataset("ag_news", split="train[:1000]")
docs = [
    Document(
        page_content=sample["text"],
        metadata={"category": sample["label"]}
    )
    for sample in dataset
]

从langchain_elasticsearch 开始使用ElasticsearchStore 模块作为我们的向量存储。在检索方面，我们采用 Elastic 专有的嵌入模型ELSER，实施 SparseVectorStrategy。在启动向量存储之前，必须确认 ELSER 模型已正确安装并部署到 Elasticsearch 环境中。

elastic_vectorstore = ElasticsearchStore.from_documents(
    docs,
    es_url=ES_ENDPOINT,
    es_api_key=ES_API_KEY,
    index_name=index_name,
    strategy=SparseVectorStrategy(model_id=".elser_model_2"),
)

elastic_vectorstore.client.indices.refresh(index=index_name)

网络搜索功能是利用 LangChain 社区工具中的DuckDuckGoSearchRun实现的，它能让系统高效地从网上检索实时信息。您还可以考虑使用其他搜索 API，它们可能会提供更相关的结果。之所以选择该工具，是因为它无需 API 密钥即可进行搜索。

duckduckgo = DuckDuckGoSearchRun(description= "A custom DuckDuckGo search tool for finding latest news stories.", verbose=True)
def websearch_retriever(query):
    results = duckduckgo.run(f"{query}")
    return results

复合检索器专为需要结合多种来源的查询而设计。它通过同时检索网络上的实时数据和查询矢量存储中的历史新闻，提供全面、准确的响应。

def composite_retriever(query):
    related_docs = vectorstore_retriever(query)
    related_docs += websearch_retriever(query)
    return related_docs

设置代理

下一步，将定义 LLM 代理，以便在该工作流程中提供推理和决策能力。我们将创建的 LLM 链包括router_chain,grade_docs_chain,rewrite_query_chain, 和summary_chain 。

路由器代理使用 LLM 助手，在运行时为给定查询确定最合适的数据源。分级代理对检索到的文档进行相关性评估。如果文件被认为是相关的，它们就会被传递给摘要代理，以生成摘要。否则，重写查询代理会重新制定查询，并将其发送回路由过程，进行另一次检索尝试。您可以在笔记本的 LLM chains 部分找到所有代理的说明。

class RouteQuery(BaseModel):
    datasource: Literal["vectorstore", "websearch", "composite"] = Field(
        ...,
        description="Choose to route the query to web search, vectorstore or composite."
    )

router_prompt = ChatPromptTemplate.from_template("""You are an assistant that decides the best data source for questions based on news articles.
Choose one of the following options:
- 'vectorstore': for general, background, or historical news articles.
- 'websearch': for recent discoveries, 'latest', 'current', or '2025' type queries.
- 'composite': when the question needs both historical and current knowledge on news articles.

Question: {query}

Return one word: 'vectorstore', 'websearch', or 'composite'.
""")
router_structured = llm.with_structured_output(RouteQuery)
router_chain: RunnableSequence = router_prompt | router_structured

llm.with_structured_output 约束模型的输出，使其遵循RouteQuery 类下 BaseModel 定义的预定义模式，确保结果的一致性。第二行通过连接router_prompt 和router_structured 来组成RunnableSequence ，形成一个流水线，在这个流水线中，语言模型对输入提示进行处理，产生结构化的、符合模式的结果。

定义图形节点

这部分包括定义图形的状态，这些状态代表系统不同组件之间流动的数据。对这些状态的明确说明可确保工作流程中的每个节点都知道自己可以访问和更新哪些信息。

class RAGState(TypedDict):
    query: str
    docs: List[Document]
    router: str
    summary: str
    self_reflection: bool
    retry_count: int = 0

一旦定义了状态，下一步就是定义图的节点。节点就像图中的功能单元，可对数据执行特定操作。我们的管道中有 7 个不同的节点。

def router(state: RAGState):
   router = router_chain.invoke({'query': state["query"]})
   logger.info(f"Router selected the datasource: {router.datasource}")
   logger.info(f"User query: {state['query']}")
   return {"router": router.datasource}

def vectorstore(state: RAGState):
   return {"docs": vectorstore_retriever(state["query"])}

def websearch(state: RAGState):
   return {"docs": websearch_retriever(state["query"])}

def composite(state: RAGState):
   return {"docs": composite_retriever(state["query"])}

def self_reflection(state: RAGState):
   evaluation = grade_docs_chain.invoke(
       {"query": state["query"], "docs": state["docs"]}
   )
   if evaluation.binary_score:
       logger.info(f"Self-reflection passed -- binary_score={evaluation.binary_score}")
   else:
       logger.info(f"Self-reflection failed -- binary_score={evaluation.binary_score}")

   return {
       "self_reflection": evaluation.binary_score,
   }

def query_rewriter(state: RAGState):
   retry_count = state.get("retry_count", 0) + 1
   new_query = rewrite_query_chain.invoke({"query": state["query"]})
   logger.info(f"Query rewritten: {new_query}, retry_count: {retry_count}")
   return {
       "query": new_query,
       "retry_count": retry_count,
   }

def summarize(state: RAGState):
   summary = summarize_chain.run(
       query=state["query"],
       docs=state["docs"],
   )
   return {"summary": summary}

query_rewriter 节点在工作流程中有两个作用。首先，当自我反思代理评估的文档被认为不充分或不相关时，它会使用rewrite_query_chain 重写用户查询，以改进检索。其次，它还可以作为一个计数器，跟踪查询被重写的次数。

每次调用节点时，都会递增存储在工作流状态中的retry_count 。这种机制可防止工作流程进入无限循环。如果retry_count 超过预定义的阈值，系统就会退回到错误状态、默认响应或您选择的任何其他预定义条件。

编制图表

最后一步是定义图的边，并在编译前添加必要的条件。每个图都必须从指定的起始节点开始，作为工作流程的入口点。图中的边代表节点之间的数据流，有两种类型：

• 直边：它们定义了从一个节点到另一个节点的直接、无条件的流动。每当第一个节点完成任务后，工作流程就会自动沿直线进入下一个节点。
• 条件边：这些边允许工作流根据节点的当前状态或计算结果进行分支。下一个节点根据评估结果、路由决定或重试次数等条件动态选择。

graph.add_edge(START, "router")

def after_router(state: RAGState):
   route = state.get("router", None)
   if route == "vectorstore":
       return "vectorstore"
   elif route == "websearch":
       return "websearch"
   else:
       return "composite"

def after_self_reflection(state: RAGState):
   if state["self_reflection"]:
           return "summarize"
   return "query_rewriter"

def after_query_rewriter(state: RAGState):
   while state['retry_count'] <= 3:
           return "router"
   raise RuntimeError("Maximum retries (3) reached -- evaluation failed.")

graph.add_conditional_edges(
   "router",
   after_router,
   {
       "vectorstore": "vectorstore",
       "websearch": "websearch",
       "composite": "composite"
   }
)

graph.add_edge("vectorstore", "self_reflection")
graph.add_edge("websearch", "self_reflection")
graph.add_edge("composite", "self_reflection")
graph.add_conditional_edges(
   "self_reflection",
   after_self_reflection,
   {
       "summarize": "summarize",
       "query_rewriter": "query_rewriter"
   }
)
graph.add_conditional_edges("query_rewriter", after_query_rewriter, {"router": "router"})
graph.add_edge("summarize", END)
agent=graph.compile()

这样，第一个代理 RAG 管道就准备就绪，可以使用编译后的代理进行测试了。

result = agent.invoke({"query": query1})
logger.info(f"\nFinal Summary:\n: {result['summary']}")

测试代理 RAG 管道

现在，我们将使用以下三种不同类型的查询对该管道进行测试。请注意，结果可能各不相同，下面的例子只是说明了一种可能的结果。

query1="What are the latest AI models released this month?"
query2="What technological innovations are discussed in Sci/Tech news?"
query3="Compare a Sci/Tech article from the dataset with a current web article about AI trends."

对于第一次查询，路由器选择websearch 作为数据源。如输出所示，该查询未通过自我反省评估，随后被重定向到查询重写阶段。

INFO     | __main__:router:11 - Router selected the datasource: websearch
INFO     | __main__:router:12 - User query: What are the latest AI models released this month?
Latest Singapore news, including the city state's relationships with Malaysia and Mahathir, China and Xi Jinping, and the rest of Southeast Asia. 3 days ago · The latest military news, insights and analysis from China. All the latest news, opinions and analysis on Hong Kong, China, Asia and around the world Latest news, in-depth features and opinion on Malaysia, covering politics, economy, society and the Asean member-nation's relationships with China, Singapore, and other Southeast Asian ... Oct 12, 2025 · Brics (an acronym for Brazil, Russia, India, China and South Africa) refers to an association of 10 leading emerging markets. The other member states are Egypt, Ethiopia, ...
INFO     | __main__:self_reflection:31 - Self-reflection failed -- binary_score=False
INFO     | __main__:query_rewriter:40 - Query rewritten: query='Which AI models have been officially released in June 2024?', retry_count: 1
INFO     | __main__:router:11 - Router selected the datasource: websearch
INFO     | __main__:router:12 - User query: query='Which AI models have been officially released in June 2024?'
Dream Machine is a text-to-video model created by Luma Labs and launched in June 2024 . It generates video output based on user prompts or still images. Dream Machine has been noted for its ability to realistically capture motion... Released in June 2023. In June 2024 , Baidu announced Ernie 4.0 Turbo. In April 2025, Ernie 4.5 Turbo and X1 Turbo were released . These models are optimized for faster response times and lower operational costs.[28][29]. The meaning of QUERY is question, inquiry. How to use query in a sentence. Synonym Discussion of Query. QUERY definition: 1. a question, often expressing doubt about something or looking for an answer from an authority.... Learn more. Query definition: a question; an inquiry.. See examples of QUERY used in a sentence.
INFO     | __main__:self_reflection:29 - Self-reflection passed -- binary_score=True
INFO     | __main__::2 - 
Final Summary:
: In June 2024, two AI models were officially released: Dream Machine, a text-to-video model launched by Luma Labs, and Ernie 4.0 Turbo, announced by Baidu, which is optimized for faster response times and lower operational costs.

接下来，我们以第二个查询为例，对使用vectorstore 检索的示例进行研究。

INFO     | __main__:router:11 - Router selected the datasource: vectorstore
INFO     | __main__:router:12 - User query: What technological innovations are discussed in Sci/Tech news?
INFO     | __main__:self_reflection:29 - Self-reflection passed -- binary_score=True
INFO     | __main__::2 - 
Final Summary:
: Recent Sci/Tech news highlights several technological innovations: NASA is collaborating with Silicon Valley firms to build a powerful Linux-based supercomputer to support theoretical research and shuttle engineering; new chromatin transfer techniques have enabled the cloning of cats; cybersecurity advancements are being discussed in relation to protecting personal technology; Princeton University scientists assert that existing technologies can be used immediately to stabilize global warming; and a set of GameBoy micro-games has been recognized for innovation in game design.

最后的查询被导向复合检索，它同时利用了矢量存储和网络搜索。

INFO     | __main__:router:11 - Router selected the datasource: composite
INFO     | __main__:router:12 - User query: Compare a Sci/Tech article from the dataset with a current web article about AI trends.
Atlas currently only available on macOS, built on Chromium with planned features like ad-blocking still in development. OpenAI's Atlas browser launched with bold promises of AI -powered web browsing, but early real-world testing reveals a different story. Career-long data are updated to end-of-2024 and single recent year data pertain to citations received during calendar year 2024. The selection is based on the top 100,000 scientists by c-score (with and without self-citations) or a percentile rank of 2% or above in the sub-field. In this article I list 45 AI tools across 21 different categories. After exploring all the available options in each category, I've carefully selected the best tools based on my personal experience. Reading a complex technical article ? Simply highlight confusing terminology and ask "what's this?" to receive instant explanations. compare browsers. Comparison showing traditional browser navigation versus OpenAI Atlas AI -powered workflows. After putting Gemini, ChatGPT, Grok, and DeepSeek through rigorous testing in October 2025, it's clear that there isn't one AI that reigns supreme across all categories.
INFO     | __main__:self_reflection:29 - Self-reflection passed -- binary_score=True
INFO     | __main__::2 - 
Final Summary:
: A Sci/Tech article from the dataset highlights NASA's development of robust artificial intelligence software for planetary rovers, aiming to make them more self-reliant and capable of decision-making during missions. In contrast, a current web article about AI trends focuses on the proliferation of AI-powered tools across various categories, including browsers like OpenAI Atlas, and compares leading models such as Gemini, ChatGPT, Grok, and DeepSeek, noting that no single AI currently excels in all areas. While the NASA article emphasizes specialized AI applications for autonomous robotics in space exploration, the current trends article showcases the broadening impact of AI across consumer and professional technologies, with ongoing competition and rapid innovation among major AI platforms.

在上述工作流程中，代理 RAG 可以在检索用户查询的信息时智能地确定使用哪个数据源，从而提高响应的准确性和相关性。您可以创建更多示例来测试代理，并查看输出结果是否产生了任何有趣的结果。

构建代理 RAG 工作流程的最佳实践

既然我们已经了解了代理 RAG 的工作原理，那么让我们来看看构建这些工作流程的一些最佳实践。遵循这些准则将有助于保持系统的效率和易于维护。

• 做好后备准备：提前规划后备策略，以应对工作流程中任何步骤出现故障的情况。这可能包括返回默认答案、触发错误状态或使用替代工具。这可确保系统从容应对故障，而不会破坏整体工作流程。
• 实施全面的日志记录：尝试在工作流程的每个阶段实施日志记录，如重试、生成输出、路由选择和查询重写。这些日志有助于提高透明度，方便调试，并有助于随着时间的推移完善提示、代理行为和检索策略。
• 选择合适的工作流程模式：检查您的使用案例，选择最适合您需求的工作流程模式。使用顺序工作流进行逐步推理，使用并行工作流处理独立数据源，使用协调器-工作器模式处理多工具或复杂查询。
• 纳入评估战略：在工作流程的不同阶段纳入评估机制。这可以包括自我反思代理、对检索到的文件进行分级或自动质量检查。评估有助于验证检索到的文件是否相关、响应是否准确，以及复杂查询的所有部分是否都得到了处理。

挑战

虽然代理 RAG 系统在适应性、精确性和动态推理方面具有显著优势，但它们在设计和实施阶段也面临着一些必须解决的挑战。一些主要挑战包括

• 复杂的工作流程：随着代理和决策点的增加，整个工作流程会变得越来越复杂。这可能导致运行时出现错误或故障的几率增加。在可能的情况下，消除多余的代理和不必要的决策点，优先简化工作流程。
• 可扩展性：要扩展代理 RAG 系统以处理大型数据集和高查询量，可能具有挑战性。采用高效的索引、缓存和分布式处理策略，以保持大规模性能。
• 协调和计算开销：使用多个代理执行工作流需要高级协调。这包括谨慎的调度、依赖管理和代理协调，以防止出现瓶颈和冲突，所有这些都会增加整个系统的复杂性。
• 评估的复杂性：对这些工作流程进行评估本身就存在挑战，因为每个阶段都需要不同的评估策略。例如，RAG 阶段必须对检索文件的相关性和完整性进行评估，而生成的摘要则需要检查其质量和准确性。同样，查询重写的有效性也需要一个单独的评估逻辑，以确定重写后的查询是否改善了检索结果。

结论

在这篇博文中，我们介绍了代理 RAG 的概念，并强调了它如何通过结合代理人工智能的自主能力来增强传统的 RAG 框架。我们探索了代理 RAG 的核心功能，并通过一个实践案例演示了这些功能，即使用 Elasticsearch 作为向量存储和 LangChain 创建代理框架来构建一个新闻助手。

此外，我们还讨论了在设计和实施代理 RAG 管道时需要考虑的最佳实践和主要挑战。这些见解旨在指导开发人员创建稳健、可扩展和高效的代理系统，将检索、推理和决策有效地结合起来。

未来发展

我们建立的工作流程非常简单，为改进和实验留下了足够的空间。我们可以通过尝试各种嵌入模型和改进检索策略来加强这一点。此外，集成一个重新排序代理来确定检索文件的优先次序也是有益的。另一个探索领域涉及为代理框架制定评估战略，特别是确定适用于不同类型框架的通用和可重复使用的方法。最后，在大型和更复杂的数据集上试验这些框架。

与此同时，如果您也有类似的实验，欢迎与我们分享！欢迎提供反馈意见，或通过我们的社区 Slack 频道或论坛与我们联系。

资源

• Self-RAG：通过自我反思学会检索、生成和批判
• 代理检索-增强生成：关于代理 RAG 的调查

分数范围问题

首先，让我们回顾一下混合搜索困难的主要原因之一：不同的分数范围。我们的老朋友BM25会产生无限制的分数。换句话说，BM25 可以生成从接近 0 到（理论上）无穷大的分数。与此相反，针对dense_vector 字段的查询会产生介于 0 和 1 之间的分数。由于semantic_text 混淆了用于索引嵌入的字段类型，因此除非您对索引和推理端点配置有详细了解，否则很难说清查询的分数范围。这在试图交错使用词汇和语义搜索结果时会带来问题，因为即使语义结果更相关，词汇结果也可能优先于语义结果。对于这个问题，普遍接受的解决方案是在交织结果之前对分数进行归一化处理。Elasticsearch 为此提供了两种工具：线性检索器和RRF检索器。

RRF检索器采用RRF 算法，将文档排名作为衡量相关性的标准，并舍弃分数。由于不考虑分数，因此分数范围不匹配不是问题。

线性检索器使用线性组合来确定文档的最终得分。这包括获取文档中每个组件查询的得分，对其进行归一化处理，然后求和生成总分。在数学上，这一操作可以表示为

Total Score = 𝚺(N(Sx))

其中N 是归一化函数，SX 是查询 X 的得分。归一化功能在这里非常关键，因为它将每个查询的得分转换为使用相同的范围。您可以在这里了解有关线性寻回猎犬的更多信息。

分解

用户可以利用这些工具实现有效的混合搜索，但需要对索引有一定的了解。让我们看一个使用线性检索器的示例，在这个示例中，我们将查询一个包含两个字段的索引：

PUT linear_retriever_example
{
  "mappings": {
    "properties": {
      "semantic_text_field": { <1>
        "type": "semantic_text",
        "inference_id": ".multilingual-e5-small-elasticsearch"
      },
      "text_field": { <2>
        "type": "text"
      }
    }
  }
}

1.semantic_text_field 是一个semantic_text 字段，使用文本嵌入模型E5

text_field 是一个标准的text 字段

GET linear_retriever_example/_search
{
  "retriever": {
    "linear": {
      "retrievers": [
        {
          "retriever": {
            "standard": {
              "query": {
                "match": { <1>
                  "semantic_text_field": "foo"
                }
              }
            }
          },
          "normalizer": "minmax"
        },
        {
          "retriever": {
            "standard": {
              "query": {
                "match": {
                  "text_field": "foo"
                }
              }
            }
          },
          "normalizer": "minmax"
        }
      ]
    }
  }
}

1.我们在 字段上使用 查询，我们 在 Elasticsearch 8.18/9.0 中添加了对match 该查询的 支持semantic_text

在构建查询时，我们需要牢记semantic_text_field 使用的是文本嵌入模型，因此对它的任何查询都会产生 0 到 1 之间的分数。我们还需要知道text_field 是一个标准的text 字段，因此对它的查询将产生一个无限制的分数。为了创建具有适当相关性的结果集，我们需要使用一种检索器，在合并查询得分之前将其归一化。在本例中，我们使用了minmax 归一化的线性检索器，它将每个查询的得分归一化为介于 0 和 1 之间的值。

本例中的查询结构相当简单，因为只涉及两个字段。然而，随着字段的增加和类型的变化，它很快就会变得复杂。这表明，要编写有效的混合搜索查询，往往需要对所查询的索引有更深入的了解，这样才能在组合之前对组件查询得分进行适当的归一化处理。这对混合搜索的广泛应用构成了障碍。

查询分组

让我们扩展一下示例：如果我们想查询一个text 字段和两个semantic_text 字段，该怎么办？我们可以构建这样一个查询：

GET linear_retriever_example/_search
{
  "retriever": {
    "linear": {
      "retrievers": [
        {
          "retriever": {
            "standard": {
              "query": {
                "semantic": {
                  "field": "semantic_text_field_1",
                  "query": "foo"
                }
              }
            }
          },
          "normalizer": "minmax"
        },
        {
          "retriever": {
            "standard": {
              "query": {
                "semantic": {
                  "field": "semantic_text_field_2",
                  "query": "foo"
                }
              }
            }
          },
          "normalizer": "minmax"
        },
        {
          "retriever": {
            "standard": {
              "query": {
                "match": {
                  "text_field": "foo"
                }
              }
            }
          },
          "normalizer": "minmax"
        }
      ]
    }
  }
}

这表面上看起来不错，但也有潜在的问题。现在，semantic_text 场比赛占总分的⅔：

Total Score = N(semantic_text_field_1 score) + N(semantic_text_field_2 score) + N(text_field score)

这可能不是你想要的结果，因为这会造成分数不平衡。在只有 3 个字段的示例中，这种影响可能并不明显，但如果查询的字段较多，就会出现问题。例如，大多数索引包含的词法字段远远多于语义字段（即dense_vector,sparse_vector, 或semantic_text) 。如果我们使用上述模式查询一个包含 9 个词法字段和 1 个语义字段的索引呢？词性匹配将占得分的 90% ，从而削弱语义搜索的有效性。

解决这一问题的常用方法是将查询分为词汇和语义两个类别，并对两者进行平均加权。这就避免了任一类别在总分中占主导地位。

让我们付诸实践。在使用线性检索器时，本例中的分组查询方法会是怎样的？

GET linear_retriever_example/_search
{
  "retriever": {
    "linear": {
      "retrievers": [
        {
          "retriever": {
            "linear": {
              "retrievers": [
                {
                  "retriever": {
                    "standard": {
                      "query": {
                        "semantic": {
                          "field": "semantic_text_field_1",
                          "query": "foo"
                        }
                      }
                    }
                  },
                  "normalizer": "minmax"
                },
                {
                  "retriever": {
                    "standard": {
                      "query": {
                        "semantic": {
                          "field": "semantic_text_field_2",
                          "query": "foo"
                        }
                      }
                    }
                  },
                  "normalizer": "minmax"
                }
              ]
            }
          },
          "normalizer": "minmax"
        },
        {
          "retriever": {
            "standard": {
              "query": {
                "match": {
                  "text_field": "foo"
                }
              }
            }
          },
          "normalizer": "minmax"
        }
      ]
    }
  }
}

哇，真是啰嗦！您甚至可能需要上下滚动多次才能查看整个查询！在这里，我们使用两级标准化来创建查询组。数学上可以表示为

Total Score = N(N(semantic_text_field_1 score) + N(semantic_text_field_2 score)) + N(text_field score)

这第二级规范化可确保semantic_text 字段和text 字段的查询权重均匀。请注意，在本例中，我们省略了text_field 的二级规范化，因为只有一个词法字段，这样可以避免更多的繁琐。

这种查询结构已经很笨重了，而且我们只查询三个字段。随着查询字段的增多，即使是经验丰富的搜索从业人员也越来越难以驾驭。

多字段查询格式

我们在 Elasticsearch 8.19、9.1 和 无服务器 中为线性和 RRF 检索器添加了 多字段查询格式 ，以简化所有这些操作。现在，您只需使用"...... "即可执行与上述相同的查询：

GET linear_retriever_example/_search
{
  "retriever": {
    "linear": {
      "fields": [ "semantic_text_field_1", "semantic_text_field_2", "text_field" ],
      "query": "foo",
      "normalizer": "minmax"
    }
  }
}

这将查询从 55 行缩减到 9 行！Elasticsearch 自动将索引映射用于

• 确定每个查询字段的类型
• 将每个字段归入一个词汇或语义类别
• 在最终得分中平均分配每个类别的权重

这样，任何人都可以执行有效的混合搜索查询，而无需了解有关索引或所用推理端点的详细信息。

使用 RRF 时，可以省略normalizer ，因为排名是相关性的代表：

GET rrf_retriever_example/_search
{
  "retriever": {
    "rrf": {
      "fields": [ "semantic_text_field_1", "semantic_text_field_2", "text_field" ],
      "query": "foo"
    }
  }
}

每场增强

在使用线性检索器时，您可以应用每个字段增强功能来调整某些字段中匹配的重要性。例如，假设您要查询四个字段：两个semantic_text 字段和两个text 字段：

GET linear_retriever_example/_search
{
  "retriever": {
    "linear": {
      "fields": [ "semantic_text_field_1", "semantic_text_field_2", "text_field_1", "text_field_2" ],
      "query": "foo",
      "normalizer": "minmax"
    }
  }
}

默认情况下，每个字段在其组（词法或语义）中的权重相同。比分细目如下

换句话说，每个字段占总分的 25% 。

我们可以使用field^boost 语法为任何字段添加每个字段的提升。让我们将semantic_text_field_1 和text_field_1 提升 2：

GET linear_retriever_example/_search
{
  "retriever": {
    "linear": {
      "fields": [ "semantic_text_field_1^2", "semantic_text_field_2", "text_field_1^2", "text_field_2" ]
      "query": "foo",
      "normalizer": "minmax"
    }
  }
}

现在的比分是这样的

每个查询组的权重仍然相同，但组内字段的权重发生了变化：

• semantic_text_field_1 是语义查询组得分的 66% ，是总分的 33%
• text_field_1 是词法查询组得分的 66% ，是总分的 33%

通配符分辨率

您可以在fields 参数中使用* 通配符来匹配多个字段。继续上面的例子，这个查询在功能上等同于明确查询emantic_text_field_1,semantic_text_field_2, 和text_field_1 ：

GET linear_retriever_example/_search
{
  "retriever": {
    "linear": {
      "fields": [ "semantic_text_field_*", "*_field_1" ],
      "query": "foo",
      "normalizer": "minmax"
    }
  }
}

值得注意的是，*_field_1 模式同时匹配text_field_1 和semantic_text_field_1 。查询将自动执行，就像明确查询每个字段一样。semantic_text_field_1 同时匹配两种模式也没有问题；在执行查询之前，所有匹配的字段名称都会被去除重复。

您可以通过多种方式使用通配符：

• 前缀匹配（例如：*_text_field)
• 内联匹配 (ex:semantic_*_field)
• 后缀匹配（例如：semantic_text_field_*)

您还可以使用多个通配符来应用上述组合，例如*_text_field_* 。

默认查询字段

多字段查询格式还允许您查询您一无所知的索引。如果省略fields 参数，它将查询由index.query.default_field 索引设置指定的所有字段：

GET linear_retriever_example/_search
{
  "retriever": {
    "linear": {
      "query": "foo",
      "normalizer": "minmax"
    }
  }
}

默认情况下，index.query.default_field 设置为* 。该通配符将解析索引中支持术语查询的所有字段类型，其中大多数字段类型都支持术语查询。例外情况是

• dense_vector 领域
• rank_vector 领域
• 几何领域：geo_point, shape

当你想在第三方提供的索引上执行混合搜索查询时，该功能尤其有用。多字段查询格式可让您以简单的方式执行适当的查询。只需排除fields 参数，就能查询所有适用字段。

结论

分数范围问题会让有效的混合搜索实施起来很头疼，尤其是在对所查询的索引或所使用的推理端点了解有限的情况下。线性和 RRF 检索器的多字段查询格式将基于查询分组的自动混合搜索方法打包到简单易用的应用程序接口中，从而减轻了这种痛苦。附加功能（如按字段增强、通配符解析和默认查询字段）扩展了功能，涵盖了多种使用情况。

立即试用多字段查询格式

您可以通过 免费试用 ，在完全托管的 Elasticsearch Serverless 项目中使用多字段查询格式检查线性检索器和 RRF 检索器。它还提供从 8.19& 9.1 开始的堆栈版本。

只需一条命令，几分钟即可在本地环境中开始使用：

curl -fsSL https://elastic.co/start-local | sh

本文将向您展示如何使用GPT-OSS和 Elastic Agent Builder 为人力资源部门构建人工智能代理。代理可以回答你的问题，而无需向 OpenAI、Anthropic 或任何外部服务发送数据。

我们将使用 LM Studio 在本地为 GPT-OSS 提供服务，并将其连接到 Elastic Agent Builder。

本文结束时，您将拥有一个定制的人工智能代理，可以回答有关员工数据的自然语言问题，同时保持对信息和模型的完全控制。

准备工作

这篇文章需要

• 弹性云托管 9.2，无服务器或本地部署
• 建议使用 32GB 内存的机器（GPT-OSS 20B 最低 16GB 内存）
• 已安装LM 工作室
• 已安装Docker 桌面

为什么使用 GPT-OSS？

有了本地 LLM，您就可以将其部署到自己的基础设施中，并根据自己的需求进行微调。当然，您也不必向外部供应商支付许可费。

作为对开放模型生态系统承诺的一部分，OpenAI 于 2025 年 8 月 5 日发布了 GPT-OSS。

20B 参数模型提供

• 工具使用能力
• 高效推理
• 兼容 OpenAI SDK
• 与代理工作流程兼容

基准比较：

解决方案架构

该架构完全在本地计算机上运行。Elastic（在 Docker 中运行）通过 LM Studio 与本地 LLM 直接通信，Elastic Agent Builder 利用这种连接创建可查询员工数据的自定义人工智能代理。

有关详细信息，请参阅本文档。

为人力资源部门建立人工智能代理：步骤

我们将把实施分为 5 个步骤：

1. 使用本地模型配置 LM 工作室
2. 使用 Docker 部署本地弹性
3. 在 Elastic 中创建 OpenAI 连接器
4. 将员工数据上传到 Elasticsearch
5. 构建并测试人工智能代理

步骤 1：使用 GPT-OSS 20B 配置 LM Studio

LM Studio 是一款用户友好型应用程序，可让您在本地计算机上运行大型语言模型。它提供了与 OpenAI 兼容的 API 服务器，无需复杂的设置过程即可轻松与 Elastic 等工具集成。有关详细信息，请参阅LM Studio 文档。

首先，从官方网站下载并安装LM Studio。安装完成后，打开应用程序。

在 LM Studio 界面：

1. 转到搜索选项卡，搜索 "GPT-OSS
2. 从 OpenAI 选择openai/gpt-oss-20b
3. 点击下载

该模型的大小约为12.10GB。下载可能需要几分钟时间，具体取决于您的网络连接。

下载模型后

1. 转到本地服务器选项卡
2. 选择 openai/gpt-oss-20b
3. 使用默认端口 1234
4. 在右侧面板上，转到 "加载 "，将上下文长度设置为40K或更高

5.单击启动服务器

如果服务器正在运行，您应该会看到这个提示。

[LM STUDIO SERVER] Success! HTTP server listening on port 1234
[LM STUDIO SERVER] Supported endpoints:
[LM STUDIO SERVER] ->	GET  http://localhost:1234/v1/models
[LM STUDIO SERVER] ->	POST http://localhost:1234/v1/responses
[LM STUDIO SERVER] ->	POST http://localhost:1234/v1/chat/completions
[LM STUDIO SERVER] ->	POST http://localhost:1234/v1/completions
[LM STUDIO SERVER] ->	POST http://localhost:1234/v1/embeddings
Server started.

第 2 步：使用 Docker 部署本地弹性

现在，我们将使用 Docker 在本地设置 Elasticsearch 和 Kibana。Elastic 提供了一个方便的脚本来处理整个设置过程。更多详情，请参阅官方文档。

运行启动本地脚本

在终端中执行以下命令

curl -fsSL https://elastic.co/start-local | sh

该脚本将

• 下载并配置 Elasticsearch 和 Kibana
• 使用 Docker Compose 启动两个服务
• 自动激活 30 天白金试用版许可证

预期产出

只需等待以下信息并保存显示的密码和 API 密钥；访问 Kibana 时需要它们：

🎉 Congrats, Elasticsearch and Kibana are installed and running in Docker!
🌐 Open your browser at http://localhost:5601
   Username: elastic
   Password: KSUlOMNr
🔌 Elasticsearch API endpoint: http://localhost:9200
🔑 API key: cnJGX0pwb0JhOG00cmNJVklUNXg6cnNJdXZWMnM4bncwMllpQlFlUTlWdw==
Learn more at https://github.com/elastic/start-local

访问 Kibana

打开浏览器并导航至

http://localhost:5601

使用终端输出中获得的证书登录。

启用代理生成器

登录 Kibana 后，导航至管理 > AI > Agent Builder 并激活 Agent Builder。

第 3 步：在 Elastic 中创建 OpenAI 连接器

现在，我们将配置 Elastic 以使用本地 LLM。

接入连接器

1. 在 Kibana 中
2. 转到项目设置 > 管理
3. 在"警报和洞察 "下，选择 "连接器
4. 单击创建连接器

配置连接器

从连接器列表中选择OpenAI。LM Studio 使用 OpenAI SDK，因此与 OpenAI 兼容。

用这些值填写字段：

• 连接器名称： LM Studio - GPT-OSS 20B
• 选择 OpenAI 提供商： 其他（OpenAI 兼容服务）
• URL： http://host.docker.internal:1234/v1/chat/completions
• 默认型号： openai/gpt-oss-20b
• API 密钥：testkey-123（任何文本都可以，因为 LM Studio 服务器不要求验证。）

要完成配置，请单击保存& 测试。

重要：打开 "启用本地函数调用"；这是使代理生成器正常工作的必要条件。如果不启用，就会出现No tool calls found in the response 错误。

测试连接

Elastic 会自动测试连接。如果一切配置正确，您将看到如下成功信息：

响应：

{
  "status": "ok",
  "data": {
    "id": "chatcmpl-flj9h0hy4wcx4bfson00an",
    "object": "chat.completion",
    "created": 1761189456,
    "model": "openai/gpt-oss-20b",
    "choices": [
      {
        "index": 0,
        "message": {
          "role": "assistant",
          "content": "Hello! 👋 How can I assist you today?",
          "reasoning": "Just greet.",
          "tool_calls": []
        },
        "logprobs": null,
        "finish_reason": "stop"
      }
    ],
    "usage": {
      "prompt_tokens": 69,
      "completion_tokens": 23,
      "total_tokens": 92
    },
    "stats": {},
    "system_fingerprint": "openai/gpt-oss-20b"
  },
  "actionId": "ee1c3aaf-bad0-4ada-8149-118f52dad757"
}

第 4 步：将员工数据上传到 Elasticsearch

现在，我们将上传人力资源员工数据集，以演示代理如何处理敏感数据。我用这种结构生成了一个虚构的数据集。

数据集结构

{
  "employee_id": "0f4dce68-2a09-4cb1-b2af-6bcb4821539b",
  "full_name": "Daffi Stiebler",
  "email": "lscutchings0@huffingtonpost.com",
  "date_of_birth": "1975-06-20T15:39:36Z",
  "hire_date": "2025-07-28T00:10:45Z",
  "job_title": "Physical Therapy Assistant",
  "department": "HR",
  "salary": "108455",
  "performance_rating": "Needs Improvement",
  "years_of_experience": 2,
  "skills": "Java",
  "education_level": "Master's Degree",
  "manager": "Carl MacGibbon",
  "emergency_contact": "Leigha Scutchings",
  "home_address": "5571 6th Park"
}

使用映射创建索引

首先，创建具有适当映射的索引。请注意，我们对一些关键字段使用了semantic_text 字段；这样就能为我们的索引提供语义搜索功能。

​​PUT hr-employees
{
  "mappings": {
    "properties": {
      "@timestamp": {
        "type": "date"
      },
      "employee_id": {
        "type": "keyword"
      },
      "full_name": {
        "type": "text",
        "copy_to": "employee_semantic"
      },
      "email": {
        "type": "keyword"
      },
      "date_of_birth": {
        "type": "date",
        "format": "iso8601"
      },
      "hire_date": {
        "type": "date",
        "format": "iso8601"
      },
      "job_title": {
        "type": "text",
        "copy_to": "employee_semantic"
      },
      "department": {
        "type": "text",
        "copy_to": "employee_semantic"
      },
      "salary": {
        "type": "double"
      },
      "performance_rating": {
        "type": "text",
        "copy_to": "employee_semantic"
      },
      "years_of_experience": {
        "type": "long"
      },
      "skills": {
        "type": "text",
        "copy_to": "employee_semantic"
      },
      "education_level": {
        "type": "text",
        "copy_to": "employee_semantic"
      },
      "manager": {
        "type": "text",
        "copy_to": "employee_semantic"
      },
      "emergency_contact": {
        "type": "keyword"
      },
      "home_address": {
        "type": "keyword"
      },
      "employee_semantic": {
        "type": "semantic_text"
      }
    }
  }
}

使用批量 API 索引

将数据集复制并粘贴到 Kibana 的 Dev Tools 中并执行：

POST hr-employees/_bulk
{"index": {}}
{"employee_id": "57728b91-e5d7-4fa8-954a-2384040d3886", "full_name": "Filide Gane", "email": "vhallahan1@booking.com", "job_title": "Business Systems Development Analyst", "department": "Marketing", "salary": "$52330.27", "performance_rating": "Meets Expectations", "years_of_experience": 12, "skills": "Java", "education_level": "Bachelor's Degree", "date_of_birth": "2000-02-07T16:49:32Z", "hire_date": "2023-11-07T13:03:16Z", "manager": "Freedman Kings", "emergency_contact": "Vilhelmina Hallahan", "home_address": "75 Dennis Junction"}
{"index": {}}
{"employee_id": "...", ...}

验证数据

运行查询进行验证：

GET hr-employees/_search

第 5 步：构建并测试人工智能代理

一切配置完成后，就可以使用 Elastic Agent Builder 创建自定义人工智能代理了。有关详细信息，请参阅Elastic 文档。

添加连接器

在创建新代理之前，我们必须将代理生成器设置为使用名为LM Studio - GPT-OSS 20B 的自定义连接器，因为默认连接器是Elastic Managed LLM。为此，我们需要进入 "项目设置"> "管理"> "GenAI 设置"；现在选择我们创建的设置，然后单击 "保存"。

访问代理生成器

1. 前往代理商
2. 点击创建新代理

配置代理

要创建新代理，必须填写代理 ID、显示名称和显示说明。

但还有更多的自定义选项，比如 "自定义指令"，它可以指导代理如何与工具进行交互，类似于系统提示，但适用于我们的自定义代理。标签可帮助您组织代理人、头像颜色和头像符号。

我根据数据集为我们的代理选择的代理编号是：

Agent ID： hr_assistant

自定义说明：

You are an HR Analytics Assistant that helps answer questions about employee data.
When responding to queries:
- Provide clear, concise answers
- Include relevant employee details (name, department, salary, skills)
- Format monetary values with currency symbols
- Be professional and maintain data confidentiality

标签：Human Resources 和 GPT-OSS

显示名称： HR Analytics Assistant

显示说明：

A specialized AI assistant for Human Resources that helps analyze employee data, compensation, performance metrics, and talent management. Ask questions about employees, departments, salaries, or performance analytics.

有了所有数据，我们就可以点击 "保存新代理"。

测试代理

现在，您可以就员工数据提出自然语言问题，GPT-OSS 20B 将理解您的意图并生成适当的回复。

提示：

Which employee is the one with the highest salary in the hr-employees index?

请回答：

代理过程是

1.使用 GPT-OSS 连接器了解您的问题

2.生成适当的 Elasticsearch 查询（使用内置工具或自定义ES|QL）

3.检索匹配的员工记录

4.以自然语言和适当的格式呈现结果

与传统的词法搜索不同，由 GPT-OSS 支持的代理可以理解意图和上下文，从而在不知道确切字段名称或查询语法的情况下更容易找到信息。有关代理人思维过程的更多详情，请参阅本文。

结论

在本文中，我们使用 Elastic 的代理生成器（Agent Builder）构建了一个自定义人工智能代理，以连接到本地运行的 OpenAI GPT-OSS 模型。通过在本地机器上部署 Elastic 和 LLM，这种架构可以让您利用生成式人工智能功能，同时保持对数据的完全控制，而无需向外部服务发送信息。

我们使用 GPT-OSS 20B 作为实验，但此处参考了官方推荐的 Elastic Agent Builder 模型。如果您需要更高级的推理能力，还可以选择120B 参数变体，它在复杂情况下的表现更好，不过需要更高级的机器才能在本地运行。更多详情，请参阅OpenAI 官方文档。

几周前，我们有幸赞助了Cal Hacks 12.0，这是规模最大的个人黑客马拉松之一，有来自世界各地的 2000 多名参赛者。我们为在 Serverless 上最佳使用 Elastic Agent Builder 设立了专门的奖项，反响非常好。在短短 36 小时内，我们就收到了 29 份以创造性方式使用 Agent Builder 的提交，其中包括构建野火情报工具和 StackOverflow 验证器。

除了令人印象深刻的项目之外，Cal Hacks 12.0 还为我们带来了同样宝贵的经验：首次接触我们 Stack 的开发人员提供了快速、未经过滤的反馈。黑客马拉松是一种独特的压力测试，时间紧迫，事先完全不熟悉，还有不可预知的障碍（比如臭名昭著的 WiFi 中断）。它们准确地揭示了开发人员体验的闪光点和仍需改进的地方。随着开发人员越来越多地通过 LLM 驱动的工作流，以新的方式与 Elastic Stack 进行交互，这一点现在变得更加重要。在这篇博文中，我们将深入探讨参与者使用 Agent Builder 构建的内容，以及我们在此过程中学到的东西。

获奖项目

第一名AgentOverflow

为 LLM 和代理时代重建的 Stack Overflow。

点击此处了解有关 AgentOverflow 的更多信息。

AgentOverflow 解决了大多数人工智能开发人员遇到的问题：LLM 会产生幻觉，聊天记录会消失，开发人员会浪费时间重新解决同样的问题。

AgentOverflow 可以捕捉、验证和重新浮现真实的问题-解决方案对，因此开发人员可以打破幻觉漩涡，更快地完成开发。

如何使用

1.共享 JSON--"解决方案模式"。

从克劳德共享中点击一下，就能刮取、提取并组装一个共享解决方案 JSON，这是一种结构化格式，其中包含：

• 问题
• 上下文
• 代码
• 标记
• 验证解决方案步骤。

验证器（LAVA）检查并强制执行结构，用户添加一行额外的上下文，然后在 Elasticsearch 中进行存储和索引。

2.查找解决方案

当您遇到困难时，点击Find Solution ，AgentOverflow 就会抓取您当前的对话，利用它建立一个查询，然后运行混合 Elasticsearch 搜索，使其浮出水面：

• 排名靠前、经过社区验证的修复方案
• 最初解决问题的确切提示

这样，开发人员就可以快速复制、粘贴和解除对当前会话的封锁。

3.MCP - LLM 的上下文注入

通过 MCP（模型上下文协议）连接到 Elasticsearch 中存储的结构化解决方案，LLM 可在运行时获得高信号上下文（代码、日志、配置、先前的修复），而不会产生额外的噪音。

AgentOverflow 使用 Agent Builder 和 Elasticsearch 作为结构化内存层，将相关上下文注入 LLM。这就使它们从被动的聊天机器人转变为能感知上下文的问题解决者。

亚军MarketMind

由六个弹性代理提供支持的可实时解释的市场能量视图。

点击此处了解有关 MarketMind 的更多信息。

MarketMind 通过为新手交易者提供一个平台，将零散的市场数据转换成清晰的实时信号，赢得了自己的一席之地。MarketMind 将所有这些信息整合到一个平台中，帮助交易者获得可操作的洞察力，而不是在不同的工具中纠缠价格走势、基本面、情绪和波动性。该项目在构建代理时还使用了一些复杂的 ES|QL 查询。

如何使用

1.收集实时市场数据

MarketMind 从雅虎财经中提取价格-行动、基本面、情绪、波动性和风险指标。这些数据被摄取并组织到多个 Elasticsearch 索引中。

2.六家专业代理商分析市场

使用 Agent Builder 创建的每个代理都专注于不同的市场层。它们从 Elasticsearch 索引中读取数据，计算自己特定领域的指标，并生成包含分数和推理的标准化 JSON 输出。

3.将信号汇总为统一的 "市场能量 "模型

综合输出显示为每只股票周围的发光脉冲，说明势头是否正在形成、风险是否正在上升、情绪是否正在转变。

4.可视化洞察力

前端采用 React 和 Next.js ，使用 TypeScript、SVG 物理视觉效果和 Chart. js 制作实时蜡烛图。这将原始分析转化为实时可操作的反馈。

其他有趣的项目

以下是在其堆栈的不同部分使用 Elastic 的其他一些有力竞争者：

点击此处查看提交给我们赛道的全部项目清单。

我们从开发人员那里学到了什么

• 代理生成器方便用户使用：

大多数团队以前从未使用过 Elastic，但仍能在几乎没有支持的情况下快速建立代理。我们为那些需要更多指导的人举办了一次研讨会，但大多数人都能获取他们的数据，并建立一个代理对这些数据执行操作。

• 法律硕士擅长 kNN 查询，但在生成 ES|QL 方面仍需要指导：

要求 ChatGPT-5 生成 ES|QL 查询会返回不正确的信息，通常会混淆 ES|QL 和 SQL。在标记文件中向 LLM 提供文档似乎是一个可行的解决方案。

• 仅快照 ES|QL 函数泄露到文档中：

即将推出的FIRST 和LAST 聚合函数无意中滑入了我们的 ES|QL 文档。因为我们将这些文档提供给了 ChatGPT，所以该模型会尽职尽责地使用这些函数，尽管它们在无服务器中还不可用。多亏了该小组的反馈意见，工程设计人员迅速打开并合并了一个修复程序，从发布的文档中删除了这些功能（PR #137341）。

• 缺少针对服务器的指导：

一个小组尝试在一个不是以查找模式创建的索引上启用LOOKUP JOIN 。错误信息让他们追逐 Serverless 上不存在的命令。我们将这一情况反映给了产品团队，他们立即启动了一个针对无服务器的可执行消息的修复程序。从长远来看，我们的目标是完全隐藏重新索引的复杂性（问题编号 4838）。

• 现场活动的价值：

在线黑客马拉松固然很棒，但没有什么能比得上与建设者并肩调试时获得的快速反馈回路。我们看到各团队在不同的使用案例中集成了代理生成器，发现了开发人员使用 ES|QL 的体验可以改进的地方，并比尝试通过异步渠道更快地修复了问题。

结论

Cal Hacks 12.0 为我们带来的不仅仅是一个周末的酷炫演示，它还让我们深入了解了新开发人员如何与 Elastic Stack 交互。在短短 36 个小时内，我们看到各个团队开始使用 Agent Builder，将数据导入 Elasticsearch，设计多代理系统，并以各种方式测试我们的功能。这次活动还提醒我们，为什么面对面的活动很重要。快速的反馈循环、真实的对话和亲自动手的调试帮助我们了解了当前开发人员的需求。我们很高兴能把学到的东西带回工程团队。我们下次黑客马拉松再见。

本文是 "在 Elasticsearch 中使用 A2A 协议和 MCP 创建 LLM 代理新闻室！"一文的配套文章，该文章介绍了在同一个代理中同时实施 A2A 和 MCP 架构的好处，以真正获得这两种框架的独特优势。如果您希望自行运行演示，我们还提供了一个资源库。

让我们来看看我们的新闻室代理是如何使用 A2A 和 MCP 协作来制作一篇新闻文章的。可在此处查看随附的存储库，了解代理的运行情况。

步骤 1：故事任务

新闻主管（作为客户）指定一篇报道：

{
  "message_type": "task_request",
  "sender": "news_chief",
  "receiver": "reporter_agent",
  "payload": {
    "task_id": "story_renewable_energy_2024",
    "assignment": {
      "topic": "Renewable Energy Adoption in Europe",
      "angle": "Policy changes driving solar and wind expansion",
      "target_length": 1200,
      "deadline": "2025-09-30T18:00:00Z"
    }
  }
}

第 2 步：记者要求进行研究

报告代理认识到它需要背景信息，并通过 A2A 委托给研究代理：

{
  "message_type": "task_request",
  "sender": "reporter_agent",
  "receiver": "researcher_agent",
  "payload": {
    "task_id": "research_eu_renewable_2024",
    "parent_task_id": "story_renewable_energy_2024",
    "capability": "fact_gathering",
    "parameters": {
      "queries": [
        "EU renewable energy capacity 2024",
        "Solar installations growth Europe",
        "Wind energy policy changes 2024"
      ],
      "depth": "comprehensive"
    }
  }
}

第 3 步：报告人请求存档代理提供历史背景信息

记者代理认识到，历史背景会加强故事性。它通过 A2A 委托档案代理（由Elastic 的 A2A 代理提供支持）搜索新闻编辑室由 Elasticsearch 支持的文章档案：

{
  "message_type": "task_request",
  "sender": "reporter_agent",
  "receiver": "archive_agent",
  "payload": {
    "task_id": "archive_search_renewable_2024",
    "parent_task_id": "story_renewable_energy_2024",
    "capability": "search_archive",
    "parameters": {
      "query": "European renewable energy policy changes and adoption trends over past 5 years",
      "focus_areas": ["solar", "wind", "policy", "Germany", "France"],
      "time_range": "2019-2024",
      "result_count": 10
    }
  }
}

步骤 4：归档代理使用带有 MCP 的弹性 A2A 代理

存档代理使用 Elastic 的 A2A 代理，而 A2A 代理又使用 MCP 访问 Elasticsearch 工具。这展示了混合架构，其中 A2A 实现了代理协作，而 MCP 提供了工具访问：

# Archive Agent using Elastic A2A Agent
async def search_historical_articles(self, query_params):
    # The Archive Agent sends a request to Elastic's A2A Agent
    elastic_response = await self.a2a_client.send_request(
        agent="elastic_agent",
        capability="search_and_analyze",
        parameters={
            "natural_language_query": query_params["query"],
            "index_pattern": "newsroom-articles-*",
            "filters": {
                "topics": query_params["focus_areas"],
                "date_range": query_params["time_range"]
            },
            "analysis_type": "trend_analysis"
        }
    )
    
    # Elastic's A2A Agent internally uses MCP tools:
    # - platform.core.search (to find relevant articles)
    # - platform.core.generate_esql (to analyze trends)
    # - platform.core.index_explorer (to identify relevant indices)
    
    return elastic_response

存档代理从 Elastic 的 A2A 代理接收全面的历史数据，并将其返回给报告器：

{
  "message_type": "task_response",
  "sender": "archive_agent",
  "receiver": "reporter_agent",
  "payload": {
    "task_id": "archive_search_renewable_2024",
    "status": "completed",
    "archive_data": {
      "historical_articles": [
        {
          "title": "Germany's Energiewende: Five Years of Solar Growth",
          "published": "2022-06-15",
          "key_points": [
            "Germany added 7 GW annually 2020-2022",
            "Policy subsidies drove 60% of growth"
          ],
          "relevance_score": 0.94
        },
        {
          "title": "France Balances Nuclear and Renewables",
          "published": "2023-03-20",
          "key_points": [
            "France increased renewable target to 40% by 2030",
            "Solar capacity doubled 2021-2023"
          ],
          "relevance_score": 0.89
        }
      ],
      "trend_analysis": {
        "coverage_frequency": "EU renewable stories increased 150% since 2019",
        "emerging_themes": ["policy incentives", "grid modernization", "battery storage"],
        "coverage_gaps": ["Small member states", "offshore wind permitting"]
      },
      "total_articles_found": 47,
      "search_confidence": 0.91
    }
  }
}

这一步骤演示了 Elastic 的 A2A Agent 如何集成到新闻编辑室的工作流程中。Archive Agent（新闻编辑室专用代理）与 Elastic 的 A2A Agent（第三方专家）协调，以利用 Elasticsearch 强大的搜索和分析功能。Elastic 的代理在内部使用 MCP 访问 Elasticsearch 工具，显示了代理协调 (A2A) 和工具访问 (MCP) 之间的明确分离。

步骤 5：研究人员使用 MCP 服务器

研究员代理访问多个 MCP 服务器以收集信息：

# Researcher Agent using MCP to access tools
async def gather_facts(self, queries):
    results = []
    
    # Use News API MCP Server
    news_data = await self.mcp_client.invoke_tool(
        server="news_api_mcp",
        tool="search_articles",
        parameters={
            "query": queries[0],
            "date_range": "2024-01-01 to 2024-09-30",
            "sources": ["reuters", "bloomberg", "euractiv"]
        }
    )
    
    # Use Statistics MCP Server
    stats_data = await self.mcp_client.invoke_tool(
        server="eurostat_mcp",
        tool="get_energy_statistics",
        parameters={
            "metrics": ["solar_capacity_mw", "wind_capacity_mw"],
            "countries": ["EU27"],
            "year": 2024
        }
    )
    
    # Use Fact-Checking MCP Server
    verified_facts = await self.mcp_client.invoke_tool(
        server="factcheck_mcp",
        tool="verify_claims",
        parameters={
            "claims": [
                "EU solar capacity increased 40% in 2024",
                "Germany leads in wind installations"
            ]
        }
    )
    
    return self._synthesize_research(news_data, stats_data, verified_facts)

步骤 6：研究人员将数据返回给报告人

研究员代理通过 A2A 发送综合研究结果：

{
  "message_type": "task_response",
  "sender": "researcher_agent",
  "receiver": "reporter_agent",
  "payload": {
    "task_id": "research_eu_renewable_2024",
    "status": "completed",
    "research_data": {
      "key_facts": [
        {
          "claim": "EU solar capacity reached 260 GW in 2024",
          "source": "Eurostat Q3 2024 Report",
          "confidence": 0.95,
          "verified": true
        },
        {
          "claim": "Germany installed 12 GW of wind capacity in 2024",
          "source": "German Federal Network Agency",
          "confidence": 0.92,
          "verified": true
        }
      ],
      "statistics": {
        "solar_growth_rate": "35%",
        "wind_growth_rate": "28%"
      },
      "sources_count": 15
    }
  }
}

第 7 步：记者撰写文章

报告代理利用研究数据和自身的 LLM 能力撰写文章。在撰写过程中，记者使用 MCP 服务器获取样式和模板：

# Reporter Agent writing with MCP assistance
async def write_article(self, research_data, assignment):
    # Get style guidelines via MCP
    style_guide = await self.mcp_client.get_resource(
        server="newsroom_mcp",
        resource="style://editorial/ap_style_guide"
    )
    
    # Get article template via MCP
    template = await self.mcp_client.get_resource(
        server="newsroom_mcp",
        resource="template://articles/news_story"
    )
    
    # Generate article using LLM + research + style
    draft = await self.llm.generate(
        prompt=f"""
        Write a news article following these guidelines:
        {style_guide}
        
        Using this template:
        {template}
        
        Based on this research:
        {research_data}
        
        Assignment: {assignment}
        """
    )
    
    # Self-evaluate confidence in claims
    confidence_check = await self._evaluate_confidence(draft)
    
    return draft, confidence_check

第 8 步：信心不足引发重新研究

报告代理评估了其草稿，发现有一项索赔的可信度较低。它会向研究员代理发送另一个请求：

{
  "message_type": "collaboration_request",
  "sender": "reporter_agent",
  "receiver": "researcher_agent",
  "payload": {
    "request_type": "fact_verification",
    "claims": [
      {
        "text": "France's nuclear phase-down contributed to 15% increase in renewable capacity",
        "context": "Discussing policy drivers for renewable growth",
        "current_confidence": 0.45,
        "required_confidence": 0.80
      }
    ],
    "urgency": "high"
  }
}

研究员使用事实核查 MCP 服务器核实索赔，并返回更新的信息：

{
  "message_type": "collaboration_response",
  "sender": "researcher_agent",
  "receiver": "reporter_agent",
  "payload": {
    "verified_claims": [
      {
        "original_claim": "France's nuclear phase-down contributed to 15% increase...",
        "verified_claim": "France's renewable capacity increased 18% in 2024, partially offsetting reduced nuclear output",
        "confidence": 0.88,
        "corrections": "Percentage was 18%, not 15%; nuclear phase-down is gradual, not primary driver",
        "sources": ["RTE France", "French Energy Ministry Report 2024"]
      }
    ]
  }
}

第 9 步：记者修改并提交给编辑

记者将核实的事实纳入其中，并通过 A2A 将完成的草稿发送给编辑代理：

{
  "message_type": "task_request",
  "sender": "reporter_agent",
  "receiver": "editor_agent",
  "payload": {
    "task_id": "edit_renewable_story",
    "parent_task_id": "story_renewable_energy_2024",
    "content": {
      "headline": "Europe's Renewable Revolution: Solar and Wind Surge 30% in 2024",
      "body": "[Full article text...]",
      "word_count": 1185,
      "sources": [/* array of sources */]
    },
    "editing_requirements": {
      "check_style": true,
      "check_facts": true,
      "check_seo": true
    }
  }
}

步骤 10：编辑使用 MCP 工具进行审查

编辑代理使用多个 MCP 服务器来审核文章：

# Editor Agent using MCP for quality checks
async def review_article(self, content):
    # Grammar and style check
    grammar_issues = await self.mcp_client.invoke_tool(
        server="grammarly_mcp",
        tool="check_document",
        parameters={"text": content["body"]}
    )
    
    # SEO optimization check
    seo_analysis = await self.mcp_client.invoke_tool(
        server="seo_mcp",
        tool="analyze_content",
        parameters={
            "headline": content["headline"],
            "body": content["body"],
            "target_keywords": ["renewable energy", "Europe", "solar", "wind"]
        }
    )
    
    # Plagiarism check
    originality = await self.mcp_client.invoke_tool(
        server="plagiarism_mcp",
        tool="check_originality",
        parameters={"text": content["body"]}
    )
    
    # Generate editorial feedback
    feedback = await self._generate_feedback(
        grammar_issues, 
        seo_analysis, 
        originality
    )
    
    return feedback

编辑批准文章并将其转发：

{
  "message_type": "task_response",
  "sender": "editor_agent",
  "receiver": "reporter_agent",
  "payload": {
    "status": "approved",
    "quality_score": 9.2,
    "minor_edits": [
      "Changed 'surge' to 'increased' in paragraph 3 for AP style consistency",
      "Added Oxford comma in list of countries"
    ],
    "approved_content": "[Final edited article]"
  }
}

第 11 步：发布者通过 CI/CD 发布

最后，打印机代理使用 CMS 和 CI/CD 管道的 MCP 服务器发布已批准的文章：

# Publisher Agent publishing via MCP
async def publish_article(self, content, metadata):
    # Upload to CMS via MCP
    cms_result = await self.mcp_client.invoke_tool(
        server="wordpress_mcp",
        tool="create_post",
        parameters={
            "title": content["headline"],
            "body": content["body"],
            "status": "draft",
            "categories": metadata["categories"],
            "tags": metadata["tags"],
            "featured_image_url": metadata["image_url"]
        }
    )
    
    post_id = cms_result["post_id"]
    
    # Trigger CI/CD deployment via MCP
    deploy_result = await self.mcp_client.invoke_tool(
        server="cicd_mcp",
        tool="trigger_deployment",
        parameters={
            "pipeline": "publish_article",
            "environment": "production",
            "post_id": post_id,
            "schedule": "immediate"
        }
    )
    
    # Track analytics
    await self.mcp_client.invoke_tool(
        server="analytics_mcp",
        tool="register_publication",
        parameters={
            "post_id": post_id,
            "publish_time": datetime.now().isoformat(),
            "story_id": metadata["story_id"]
        }
    )
    
    return {
        "status": "published",
        "post_id": post_id,
        "url": f"https://newsroom.example.com/articles/{post_id}",
        "deployment_id": deploy_result["deployment_id"]
    }

出版商确认通过 A2A 出版：

{
  "message_type": "task_complete",
  "sender": "printer_agent",
  "receiver": "news_chief",
  "payload": {
    "task_id": "story_renewable_energy_2024",
    "status": "published",
    "publication": {
      "url": "https://newsroom.example.com/articles/renewable-europe-2024",
      "published_at": "2025-09-30T17:45:00Z",
      "post_id": "12345"
    },
    "workflow_metrics": {
      "total_time_minutes": 45,
      "agents_involved": ["reporter", "researcher", "archive", "editor", "printer"],
      "iterations": 2,
      "mcp_calls": 12
    }
  }
}

下面是随附的资料库中使用上述相同代理的 A2A 工作流程的完整序列。

结论

A2A 和 MCP 在现代增强型 LLM 基础设施范例中都可以发挥重要作用。A2A 为复杂的多代理系统提供了灵活性，但潜在的可移植性较差，操作复杂性较高。MCP 提供了一种标准化的工具集成方法，更易于实施和维护，但它并不是为处理多代理协调而设计的。

选择不是二元对立的。正如我们的新闻编辑室示例所示，最复杂、最有效的 LLM 支持系统往往将这两种方法结合在一起：代理通过 A2A 协议进行协调和专业化，同时通过 MCP 服务器访问其工具和资源。这种混合架构在提供多代理系统的组织优势的同时，还提供了 MCP 的标准化和生态系统优势。这表明可能根本不需要做出选择：只需将两者都作为标准方法使用即可

作为开发人员或架构师，您需要测试并确定这两种解决方案的最佳组合，从而为您的特定用例创造正确的结果。了解每种方法的优势、局限性和适当应用，将使您能够构建更有效、可维护和可扩展的人工智能系统。

无论您是要建立数字新闻编辑室、客户服务平台、研究助手，还是其他任何由 LLM 驱动的应用程序，仔细考虑您的协调需求 (A2A) 和工具访问要求 (MCP) 都将使您走上成功之路。

其他资源

• Elasticsearch 代理生成器 ：https://www.elastic.co/docs/solutions/search/elastic-agent-builder
• A2A 规格 ： https://a2a-protocol.org/latest/specification/
• A2A 和 MCP 集成 ：https://a2a-protocol.org/latest/topics/a2a-and-mcp/
• 模型上下文协议 ： https://modelcontextprotocol.io

搜索并未消亡，只是转移了位置

因此，我们已经从主要通过文本框搜索上下文，然后使用返回的信息（上下文）自己构建答案，转变为现在使用自然语言告诉代理我们想要什么，然后让它自动研究并为我们编译答案。科技界的许多人都指出了这一转变，并宣称 "搜索已死"（搜索引擎优化和广告词的世界 肯定 在 变化 ： GEO 谁知道？

以前，人类是主观相关性的主要仲裁者：每个用户都有自己进行搜索的理由，他们的个人经验会影响搜索结果的相对准确性。如果我们要相信代理能得出与我们相同（或更好）的结论，我们就必须确保代理能获得的上下文信息尽可能接近我们的主观意图。为了实现这一目标，我们必须设计为法律硕士提供的环境！

利用混合搜索检索生成上下文

在此提醒大家，Elastic 的混合搜索结合了传统基于关键字搜索的优势（语法灵活性、关键字精确度和相关性评分）和向量相似性搜索的语义理解，并提供了多种重排技术。这种协同作用（这个词从未有过如此真实的用法）这样就能获得高度相关的结果，查询内容的针对性也会更加细致。这不仅仅是说你可以将主观相关性作为检索阶段之一，而是说第一阶段检索可以同时包括相关性评分和所有其他模式。

卓越的精度& 效率

使用可提供分布式搜索、检索和重新排序的数据平台作为主要的上下文检索引擎非常有意义。您可以使用高级查询语法来添加主观意图的缺失部分，并过滤掉可能干扰或混淆所返回的上下文信息价值的内容。您可以从任何可用的单独语法选项中进行选择，也可以将各种模式组合成一个单一的搜索，以其最能理解的方式针对每种类型的数据进行搜索，然后通过重新排序对其进行组合/重新排序。您可以对响应进行过滤，使其只包含您想要的字段/值，从而避免无关数据。在为代理提供服务时，这种目标定位的灵活性可让您构建的工具在检索上下文时极为准确。

语境细化（聚合和非内容信号）

聚合在塑造工具向上下文窗口提供的内容方面特别有用。聚合自然会提供有关返回的上下文数据形状的基于数字的事实，这使得 LLM 的推理更容易、更准确。由于聚合可以分层嵌套，因此很容易为 LLM 增加多层次的细节，从而产生更细致入微的理解。聚合还有助于管理上下文窗口的大小--您可以轻松地将 10 万个文档的查询结果减少到几百个聚合洞察的标记。

非内容信号是数据中的固有指标，它们能告诉你所查看内容的全貌；它们是结果的附加特征，如受欢迎程度、新鲜度、地理位置、类别、主机多样性或价格带。这些信息可以为代理如何权衡所接收到的上下文的重要性提供有用信息。一些简单的例子也许最能说明这一点：

• 提升近期发布的热门内容--想象一下，您有一个文章知识库。您希望找到与用户查询相关的文章，但同时也希望推广那些最近发表的、对其他用户有帮助的文章（例如，具有较高"likes" 数量的文章）。在这种情况下，我们可以使用混合搜索来查找相关文章，然后根据文章的发表日期和受欢迎程度对其进行排序。
• 带有销售和库存调整功能的电子商务搜索- 在电子商务环境中，您希望向客户展示与其搜索词相匹配的产品，但同时也希望推广销售良好且有库存的产品。您可能还想把库存少的产品降级，以避免客户失望。
• 在错误跟踪器中确定高严重性问题的优先级--对于软件开发团队来说，在搜索问题时，首先浮现高严重性、高优先级和最近更新的问题至关重要。您可以使用 "关键性 "和 "讨论最多 "等非信号来独立权衡不同的因素，确保最关键和讨论最活跃的问题排在最前面

这些示例查询和更多内容可在随附的 Elasticsearch Labs内容页面中找到。

安全执法

利用 Elastic 等搜索驱动的速度层进行上下文工程的一个重要优势是其内置的安全框架。Elastic 的平台通过细粒度的基于角色的访问控制（RBAC）和基于属性的访问控制（ABAC），确保向代理和生成式人工智能操作提供的上下文尊重并保护敏感的私人信息。这意味着不仅能高效处理查询，还能根据代理或发起请求的用户的特定权限对结果进行过滤。

代理以认证用户的身份运行，因此通过平台内置的安全功能隐式地应用了安全功能：

• 细粒度权限：在文档、字段甚至术语级别定义访问权限，确保人工智能代理只接收他们有权查看的数据。
• 基于角色的访问控制（RBAC）：为代理或用户分配角色，根据其定义的职责授予对特定数据集或功能的访问权限。
• 基于属性的访问控制（ABAC）：根据数据、用户或环境的属性实施动态访问策略，从而实现高度适应性和上下文感知的安全性。
• 文档级安全（DLS）和字段级安全（FLS）：这些功能可确保即使在检索的文档中，也只能看到授权部分，从而防止敏感信息外泄。
• 与企业安全集成：与现有身份管理系统（如 LDAP、SAML、OIDC）无缝集成，在整个组织内执行一致的安全策略。

通过将这些安全措施直接集成到上下文检索机制中，Elastic 成为了一个安全的看门人，确保人工智能代理在定义的数据边界内运行，防止未经授权的数据暴露，并维护数据隐私法规的合规性。这对于在处理机密或专有信息的人工智能代理系统中建立信任至关重要。

此外，通过在企业数据源上使用统一的数据速度层，还可以减轻代理工具在这些资源库上产生的意外临时查询负载。您只需在一个地方就能近乎实时地搜索所有内容，并在一个地方应用安全和治理控制。

基于搜索的混合工具

Elastic 平台的一些核心功能（更多功能将陆续推出）能极大地促进情境工程的发展。这里最主要的是，该平台提供了多种实现方法，随着人工智能生态系统的发展，可以灵活地调整、改变和扩展方法。

代理生成器介绍

ElasticAgent Builder是我们在代理式人工智能工具领域的首次尝试，该工具可与您已存储在 Elastic 中的数据聊天。Agent Builder 提供了一个聊天界面，使用户能够在 Kibana 中创建和管理自己的代理和工具。它内置 MCP 和 A2A 服务器、编程 API 和一套预置系统工具，用于查询和探索 Elasticsearch 索引，以及从自然语言生成 ES|QL 查询。代理生成器允许您创建自定义工具，通过富有表现力的ES|QL查询语法，瞄准并雕琢返回给代理的上下文数据。

你会问，ES|QL 如何执行混合搜索？核心功能是通过结合 semantic_text 字段 类型和 FORK/FUSE 命令来实现的（FUSE 默认使用 RRF 来合并每个分叉的结果）。下面是一个虚构产品搜索的简单示例：

FROM products
| FORK
  (MATCH description "high performance gaming laptop" | EVAL search_type = "bm25"),
  (MATCH description_semantic "high performance gaming laptop" | EVAL search_type = "semantic")
| FUSE 
| LIMIT 20
| KEEP product_name, description, _score, search_type

在上面的示例中，每个 FORK 分支都包含了 EVAL 子句，但 EVAL 子句并不是绝对必要的；包含 EVAL 子句只是为了演示如何跟踪给定结果是从哪种搜索模式返回的。

搜索模板

假设您想将自己的外部代理工具指向 Elastic 部署。您希望使用多级检索器或重新使用已开发的现有 DSL 语法，而不是 ES|QL，还希望能够控制查询接受的输入、执行搜索时使用的语法以及输出中返回的字段。搜索模板允许用户为常用搜索模式定义预定义结构，从而提高检索数据的效率和一致性。这对与搜索应用程序接口交互的代理工具尤其有利，因为它们有助于规范模板代码，加快搜索逻辑的迭代速度。如果您需要调整其中任何一个因素，只需更新搜索模板，就可以实现更改。如果您正在寻找搜索模板与代理工具配合使用的示例，可以看看 Elasticsearch 实验室的博客 "MCP for intelligentsearch"，它在来自外部 MCP 服务器的工具调用背后使用了搜索模板。

集成工作流程（FTW!）

在我们新的代理人工智能世界中，最难驾驭的事情之一就是半自主、自导自演的 "推理 "代理的非确定性。情境工程是代理人工智能的一门关键学科：这些技术有助于将我们的代理可能得出的结论缩小到我们所知道的基本事实。即使有了高度准确和相关的上下文窗口（当我们跳出数字事实的范畴时），我们仍然缺少一点保证，即代理的反应是完全可重复和可靠的。

当您多次向代理运行同一个请求时，得到的答案可能基本相同，只是在响应上有那么一点点差别。对于简单的查询来说，这通常没什么问题，也许几乎不会引起注意，我们可以尝试使用上下文工程技术来塑造输出。但是，随着我们要求代理完成的任务变得越来越复杂，一个或多个子任务就更有可能带来差异，从而稍微改变最终结果。随着我们开始更多地依赖代理与代理之间的通信，这种情况可能会变得更糟，而这些差异也会累积起来。这再次说明，与我们的代理互动的工具需要非常灵活，并可进行调整，以精确瞄准上下文数据，而且它们应该以预期的输出格式做出响应。这也表明，在许多使用案例中，我们需要指导代理和工具之间的交互--这就是工作流的作用所在！

Elastic 将很快在平台核心中内置完全可定制的工作流程。这些工作流程将能以双向方式与代理和工具一起运行，因此工作流程将能呼叫代理和工具，代理和工具也能呼叫工作流程。将这些功能完全集成到同一搜索人工智能平台中，您的所有数据都将在该平台中存活，这将是一场变革，工作流程的潜力令人无比振奋！很快，很快就会到来！

作为统一记忆库的弹性

Elastic 是一个分布式数据平台，专为近乎实时的搜索而设计，因此能自然而然地为代理型人工智能系统提供长期记忆功能。通过内置的 Agent Builder 聊天体验，我们还可以跟踪和管理短期记忆和聊天记录。由于整个平台以 API 为先，因此利用 Elastic 作为平台来持久化工具的上下文输出（并能在稍后参考）非常容易，而这些输出可能会淹没代理的上下文窗口；这种技术在上下文工程领域有时被称为 "记笔记"。

在同一个搜索平台上同时拥有短期和长期记忆会带来很多内在的好处：试想一下，我们可以将聊天记录和持久化的上下文回复作为语义影响因素的一部分，用于未来的聊天互动，或用于执行威胁分析，或用于创建从频繁重复的工具调用中自动生成的持久化数据产品......这种可能性是无穷无尽的！

结论

大型语言模型的出现改变了我们匹配内容的方式，也改变了我们查询数据的方法。在我们的世界里，人类正在迅速地从研究、背景考虑和逻辑推理来回答自己的问题，转变为这些步骤在很大程度上通过代理人工智能实现自动化。为了让我们相信所收到的生成答案，我们需要确保代理在生成答案时考虑了所有 最相关的信息（包括主观相关性因素）。我们使代理人工智能值得信赖的主要方法是，通过 RAG 和上下文工程技术将检索额外上下文的工具落地，但这些工具如何进行初始检索对响应的准确性至关重要。

Elastic Search 人工智能平台提供了混合搜索的灵活性和优势，同时还提供了多项内置功能，有助于代理式人工智能的准确性、性能和可扩展性；换句话说，Elastic 是语境工程多个方面的绝佳平台！通过搜索平台将上下文检索标准化，我们在多个方面简化了代理工具的操作--与 "放慢速度才能更快 "的矛盾论类似，上下文生成层的简化意味着代理人工智能更快、更可信。

与数据交互的新方式

生成式人工智能（genAI）和代理式人工智能的工作方式与传统搜索不同。过去，我们开始研究信息的方式是搜索（"让我谷歌一下......"），而基因人工智能和代理的发起行动通常是通过在聊天界面输入自然语言。聊天界面是与 LLM 的讨论，LLM 利用其语义理解能力将我们的问题转化为经过提炼的答案，这种经过总结的回答似乎来自一个对各种信息都有广泛了解的神谕。真正的卖点在于，法学硕士能够产生连贯、深思熟虑的句子，将浮现的知识点串联起来--即使不准确或完全是幻觉，也有其真实性。

我们习惯于使用的老式搜索栏，可以看作是我们自己作为推理代理时使用的 RAG 引擎。现在，即使是互联网搜索引擎也正在将我们习以为常的 "猎取和啄食 "词条搜索体验转变为人工智能驱动的概述，通过对结果的总结来回答查询，帮助用户避免自己点击和评估单个结果。

生成式人工智能& RAG

生成式人工智能试图利用其对世界的语义理解来解析聊天请求中表达的主观意图，然后利用其推理能力即时创建专家答案。生成式人工智能交互由几个部分组成：首先是用户的输入/询问，聊天会话中之前的对话可用作额外的上下文，然后是指导性提示，告诉 LLM 如何推理以及在构建回复时应遵循哪些程序。提示已从简单的""像五岁小孩一样解释给我听 "类型的指导发展到如何处理请求的完整细分。这些细目通常包括不同的部分，详细描述人工智能的角色/作用、生成前的推理/内部思维过程、客观标准、限制条件、输出格式、受众，以及有助于展示预期结果的示例。

除了用户查询和系统提示外，检索增强生成（RAG）还在所谓的 "上下文窗口 "中提供额外的上下文信息。RAG 是该架构的重要补充；我们用它来告知 LLM 在其对世界的语义理解中缺失的部分。

背景窗口在提供内容、地点和数量方面可能有点挑剔。当然，选择哪种上下文非常重要，但所提供上下文的信噪比以及窗口的长度也很重要。

信息太少

在查询、提示或上下文窗口中提供过少的信息可能会导致幻觉，因为 LLM 无法准确判断正确的语义上下文，从而生成响应。文件块大小的矢量相似性也存在问题--一个简短、简单的问题可能与我们矢量化知识库中丰富、详细的文件在语义上不一致。目前已开发出假设文档嵌入（HyDE）等查询扩展技术，利用 LLM 生成比简短查询更丰富、更具表现力的假设答案。当然，这里的危险在于，假定的文件本身就是一种幻觉，它使法律硕士更加偏离正确的语境。

信息太多

就像我们人类一样，上下文窗口中过多的信息会让法律硕士不知所措，不知道哪些是重要部分。上下文溢出（或 "上下文腐烂"）会影响生成式人工智能操作的质量和性能；它会极大地影响 LLM 的 "注意力预算"（其工作记忆），并稀释许多竞争标记的相关性。语境轮换 "的概念还包括这样一个观察结果，即语言学习者往往有一种位置偏差--他们更喜欢语境窗口开头或结尾的内容，而不是中间部分的内容。

分散注意力或相互冲突的信息

上下文窗口越大，就越有可能包含多余或相互冲突的信息，从而分散 LLM 的注意力，使其无法选择和处理正确的上下文。在某种程度上，这就成了一个 "垃圾进/垃圾出 "的问题：只需将一组文档结果倒入上下文窗口，就能为 LLM 提供大量信息供其咀嚼（可能太多），但根据上下文的选择方式，更有可能渗入相互冲突或无关的信息。

智能体 AI

我告诉过你有很多内容要讲，但我们做到了--我们终于开始讨论代理人工智能话题了！代理式人工智能（Agentic AI）是 LLM 聊天界面的一种非常令人兴奋的新用法，它扩展了生成式人工智能（我们可以称之为 "传统 "人工智能吗？）的能力，即根据自身知识和您提供的上下文信息合成回复。随着生成式人工智能变得越来越成熟，我们意识到可以让 LLM 执行一定程度的任务和自动化操作，这些操作最初被归类为乏味的低风险活动，可以很容易地由人工进行检查/验证。在很短的时间内，最初的范围就扩大了：一个 LLM 聊天窗口现在可以成为一个火花，让一个人工智能代理去自主规划、执行、迭代评估和调整其计划，以实现指定的目标。代理可以访问其 LLM 自身的推理、聊天历史和思维记忆（比如说），他们还可以利用特定的工具来实现这一目标。我们现在看到的架构还允许一个顶级代理作为多个 子代理 的协调者，每个 子代理 都有自己的逻辑链、指令集、上下文和工具。

代理是大部分自动化工作流程的切入点：它们是自主的，能够与用户聊天，然后使用 "逻辑 "来决定有哪些工具可以帮助回答用户的问题。与代理相比，工具通常被认为是被动的，是为完成一种任务而构建的。工具可以执行的任务类型是无限的（这确实令人兴奋！），但工具执行的一项主要任务是收集上下文信息，供代理在执行工作流程时考虑。

作为一项技术，代理人工智能仍处于起步阶段，很容易患上法学硕士的注意力缺陷症--很容易忘记要求它做的事情，经常跑去做其他根本不在任务范围内的事情。在表面神奇的背后，LLM 的 "推理 "能力仍然是基于预测序列中下一个最有可能的标记。要使推理（或有朝一日的人工通用智能（AGI））变得可靠和值得信赖，我们需要能够验证，在获得正确、最新的信息时，它们会按照我们所期望的方式进行推理（也许还会给我们提供我们自己可能没有想到的更多信息）。要做到这一点，代理架构需要具备清晰的通信能力（协议），遵守我们赋予它们的工作流程和约束条件（护栏），记住它们在任务中的位置（状态），管理可用的内存空间，以及验证它们的响应是否准确并符合任务标准。

用我能听懂的语言跟我说话

在新的开发领域（尤其是在 LLM 领域），代理与工具之间的通信最初有很多方法，但很快就趋同于模型上下文协议（MCP），将其作为事实上的标准。模型上下文协议的定义其实就在名字里--它是 模型 用来请求和接收 上下文 信息的 协议 。MCP 是 LLM 代理连接外部工具和数据源的通用适配器；它简化了应用程序接口并使之标准化，这样不同的 LLM 框架和工具就能轻松互操作。这就使得 MCP 成为一种支点，它介于协调逻辑和系统提示与发送给工具的操作之间，前者要求代理为实现其目标而自主执行，而后者则要求代理以更孤立的方式执行（至少与启动代理隔离）。

这个生态系统是如此之新，以至于每个扩展方向都像是一个新领域。我们有类似的协议用于代理与代理之间的交互 （Agent2Agent (A2A) natch!），也有其他项目用于改进代理的推理记忆 （ReasoningBank ），为手头的工作选择最佳的 MCP 服务器 （RAG-MCP ），以及使用语义分析 （ 如输入和输出的零点分类和模式检测）作为控制代理操作内容的 Guardrails 。

您可能已经注意到，这些项目的根本目的都是为了提高返回到代理/人工智能上下文窗口的信息的质量和控制？虽然人工智能代理生态系统将继续发展更好地处理上下文信息（对其进行控制、管理和操作）的能力，但始终需要检索最相关的上下文信息，作为代理的研磨材料。

欢迎使用情境工程！

如果你熟悉生成式人工智能术语，你可能听说过 "提示工程"--在这一点上，它几乎是一门伪科学。提示工程用于找到最佳和最有效的方法，主动描述您希望 LLM 在生成响应时使用的行为。上下文工程"将 "提示工程 "技术从代理侧扩展到 MCP 协议工具侧的可用上下文源和系统，并包括上下文管理、处理和生成等广泛主题：

• 上下文管理 - 与在长期运行和/或更复杂的代理工作流程中保持状态和上下文效率有关。对任务和工具的调用进行迭代规划、跟踪和协调，以实现代理的目标。由于代理工作的 "注意力预算 "有限，上下文管理主要涉及帮助完善上下文窗口的技术，以捕捉最全面和最重要的上下文信息（精确度与召回率！）。这些技术包括压缩、归纳，以及持续保留先前步骤或工具调用的上下文，以便在工作记忆中为后续步骤中的额外上下文留出空间。
• 上下文处理 --对从不同来源获取的上下文进行整合、规范化或细化的逻辑步骤，希望这些步骤主要是程序性的，以便代理能够以某种统一的方式对所有上下文进行推理。底层工作是让所有来源（提示、RAG、记忆等）的上下文都能被代理尽可能高效地消耗掉。
• 上下文生成 --如果上下文处理的目的是让代理可以使用检索到的上下文，那么上下文生成就赋予了代理随意请求和接收附加上下文信息的能力，但同时也有限制条件。

LLM 聊天应用程序的各种历时直接（有时以重叠的方式）映射到上下文工程的这些高级功能：

• 指令/系统提示--提示是生成式（或代理式）人工智能活动如何引导其思维实现用户目标的支架。提示本身就是一种语境；它们不仅仅是音调指令，还经常包含任务执行逻辑和规则，如 "逐步思考 "或 "深呼吸"，然后再做出回应，以验证答案是否完全满足用户的要求。最近的测试表明，标记语言在框定提示的不同部分时非常有效，但也要注意在过于模糊和过于具体之间调整指示；我们希望提供足够的指示，让 LLM 找到正确的上下文，但又不能过于规范，以至于错过意想不到的见解。
• 短期记忆（状态/历史）--短期记忆主要是用户与 LLM 之间的聊天会话互动。这些信息有助于在现场会议中完善上下文，并可保存起来供今后检索和继续使用。
• 长时记忆--长时记忆应包含在多个时段都有用的信息。通过 RAG 访问的不仅仅是特定领域的知识库，最近的研究还利用以前的代理/生成式人工智能请求的结果，在当前的代理互动中进行学习和参考。在长期记忆领域，一些最有趣的创新与调整状态的存储和链接方式有关，这样，代理就能从他们离开的地方继续前进。
• 结构化输出--认知需要花费精力，因此，即使拥有推理能力，LLM（就像人类一样）也希望在思考时花费更少的精力，这一点不足为奇。在没有定义好的应用程序接口或协议的情况下，有一个如何读取工具调用返回数据的地图（模式）是非常有用的。将 "结构化输出 "作为代理框架的一部分，有助于使这些机器与机器之间的交互更快、更可靠，同时减少思维驱动的解析。
• 可用工具- 工具可以做各种各样的事情，从收集额外信息（如向企业数据存储库或通过在线 API 发出 RAG 查询）到代表代理执行自动操作（如根据代理请求的标准预订酒店房间）。工具也可以是子代理，有自己的代理处理链。
• 检索增强生成（RAG）--我非常喜欢将 RAG 描述为 "动态知识集成"。如前所述，RAG 是一种提供 LLM 在接受训练时无法获得的额外信息的技术，或者说是重申我们认为对获得正确答案最重要的想法--与我们的主观疑问最相关的想法。