Kibana 仪表板构建器是什么？

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

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

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

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

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

随后，AI 会：

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

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

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

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

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

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

单个图表的内联预览

由 ES|QL 提供支持

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

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

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

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

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

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

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

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

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

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

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

导出到 Kibana

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

将此仪表板导出到 Kibana

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

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

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

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

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

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

从 Kibana 导入

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

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

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

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

自定义主题和颜色

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

类型

适用场景

示例

条形图

类别比较

按地理来源划分的请求数

折线图

随时间变化的趋势

每小时传输的字节数

区域

随时间变化的数据量

随时间变化的请求量

饼图

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

响应代码分布

指标

带迷你图的单一 KPI

总请求数及每小时趋势

热力图

跨两个维度的模式

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

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

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

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

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

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

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

然后开始构建：

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

剩下的交给 AI 即可。😉

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

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

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

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

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

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

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

GitHub：elastic/example-mcp-dashbuilder

致谢

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

常见问题解答

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

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

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

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

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

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

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

正如我们在之前的帖子中看到的，函数调用提供的一致性不仅仅是一种不错的优化手段，它还是至关重要的。一旦我们从评估循环中消除了结构性错误，标准场景（例如第 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”，毕竟谁不喜欢一个好听的缩写词呢。

还有哪些其他用例可以从这种模式中受益？需要信任、透明和可辩护推理的系统是当然的候选者。未来在这一领域的工作应该会像我们在这里看到的结果一样引人注目，我很期待看到社区接下来会有什么新的发展。

下一步：亲自试用

想看看终极挑战的实际操作吗？请查看终极挑战笔记本，它通过实际实现、详细解释和动手示例，提供了完整的实践指南。

完整的实体解析管道展示了生产使用所需的核心概念和架构。您可以将其用作构建系统的基础，这些系统可以监测新闻文章、跟踪实体提及情况，并回答有关哪些实体出现在哪些文章中的问题，同时还能保持透明度和可解释性。

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 进行评估，结构化输出的失败可能会抑制接受率和召回率，即使检索环节工作正常。

指标

值

精确率

83.8%

召回

62.6%

F1 分数

71.7%

找到的总匹配数

344

LLM 接受率

44.8%

错误率

30.2%

错误率问题

回顾一下，我们在原型中采取的第一步是使用 Elasticsearch 创建潜在的匹配对。每个这样的潜在匹配都需要由 LLM 进行评估。为了高效地处理所有这些匹配项，我们将 LLM 调用批量组合在一起。这降低了 API 成本和延迟，但也增加了在输出中得到格式错误 JSON 的风险。随着批量大小的增加，JSON 变得更长、更复杂，使得 LLM 更有可能生成无效的 JSON。这就是 30% 错误率的来源。在评估中，我们每个请求使用 5 个匹配项的批量大小。即使采用这个保守的批量大小，我们仍然遇到 JSON 解析失败的情况，这显著地影响了评估结果。

下一步：优化 LLM 集成

现在，我们已经使用语义搜索和 LLM 判断匹配了实体，我们拥有了一个完整的实体解析管道。然而，这种方法引入了一种新的故障模式：当模型的判断正确，但其输出却不可用时。我们可以优化 LLM 集成以获得更好的可靠性和成本效益。在下一篇文章中，我们将探讨如何使用函数调用来实现结构化输出，这可以在减少错误和成本的同时，提供有保障的结构和类型安全。

亲自试用

想亲眼看看实体匹配是如何运作的吗？请查看实体匹配笔记本，它通过实际实现、详细解释和动手示例，提供了完整的实践指南。该笔记本精确地向您展示了如何使用三步搜索、带有 RRF 的混合搜索以及由 LLM 驱动的带推理的判断来匹配实体。

请记住：这是一个教育原型，旨在教授这些概念。在构建生产系统时，需要考虑额外的因素，如模型选择、成本优化、延迟要求、质量验证、错误处理和监控等，而这些在本学习重点的原型中并未涵盖。

备注

1. 这些数据集是合成的，专为教育目的设计；它们模拟了真实的挑战，但不代表任何单一的生产环境领域。

我们的目标是转向一种自动化、自适应的方法，能够同时处理日志解析（字段提取）和日志分区（来源识别）。我们假设，大语言模型（LLM）凭借对代码语法与语义模式的理解，能够在最少人工干预的情况下自动处理这些任务。

我们很高兴地宣布，此功能已在 Streams 中正式推出！

数据集描述

我们选择了Loghub日志集合用于概念验证。我们的调查从以下关键领域选取了代表性样本：

• 分布式系统：我们使用了 Hadoop 分布式文件系统 (HDFS) 和 Spark 数据集。这些日志混合了大数据平台典型的信息、调试和错误消息。

• 服务器与 Web 应用：Apache Web 服务器和 OpenSSH 的日志提供了访问、错误以及与安全相关事件的重要信息来源，这对于监控 Web 流量和检测潜在威胁至关重要。

• 操作系统：我们纳入了 Linux 和 Windows 日志。这些数据集代表了运维团队日常处理的常见、半结构化系统级事件。

• 移动系统：为确保模型能处理移动环境日志，我们加入了 Android 数据集。这些日志通常较为冗长，涵盖了移动设备上广泛的应用程序和系统级活动。

• 超级计算机：为测试在高性能计算环境下的表现，我们引入了 BGL 数据集，其特点是包含使用特定领域术语的高度结构化日志。

Loghub 集合的一个关键优势在于，其日志基本未经清洗处理和标注，真实模拟了具有微服务架构的、嘈杂的线上生产环境。

日志示例：

此外，我们还搭建了一个包含典型 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 函数执行抽象化处理（例如将数字替换为“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%，这证实了基于多样性的抽样比原始数量更为关键。

什么是 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 准备好的参数、检索到的搜索结果，一直到最后的格式化输出，都会依次写入其中。

这种结构让每个节点都能读取和更新状态，确保从用户输入到可视化实现顺畅一致的信息流动。

设置应用程序

本节所有代码均可在 elasticsearch-labs 仓库 中找到。

在应用所在的文件夹中打开终端，并通过以下命令初始化一个 Node.js 应用：

现在我们可以为这个项目安装必要的依赖项：

• @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 文件中，我们添加以下环境变量：

OpenAPI APIKey 不会直接在代码中使用，而是由 @langchain/openai 库在内部调用。

所有关于映射创建、搜索模板创建和数据集摄取的逻辑都可以在 elasticsearchSetup.ts 文件中找到。在接下来的步骤中，我们将重点关注 main.ts 文件。此外，您可以查看该数据集，以便更好地理解 dataset.json 中数据结构。

LangGraph 应用程序

在 main.ts 文件中，我们导入一些必要的依赖项来构建整个 LangGraph 应用。在此文件中，您还必须定义各个节点函数以及工作流状态的声明。在后续步骤中，我们会在 main 方法中完成这个图结构的声明。elasticsearchSetup.ts 文件中包含一组 Elasticsearch 辅助函数，我们会在后续步骤的各个节点中使用这些函数。

如前所述，LLM 客户端将根据用户的问题生成 Elasticsearch 搜索模板参数。

上面的方法会生成一张 png 格式的图结构图像，并在后台调用 Mermaid.ink API。当你希望通过一张带有样式的可视化图来直观了解应用中各个节点之间的交互时，这个功能就会非常有用。

LangGraph 节点

现在让我们看看每个节点的详细信息：

decideSearchStrategy 节点

decideSearchStrategy 节点分析用户输入，并确定是执行投资聚焦搜索还是市场聚焦搜索。它使用具有结构化输出模式（用 Zod 定义）的 LLM 对查询类型进行分类。在做出决策之前，它会通过聚合从索引中检索可用的筛选条件，确保模型掌握最新的行业、地域和融资等上下文信息。

为了提取过滤器可能的值并将其发送到 LLM，让我们使用聚合查询直接从 Elasticsearch 索引中检索它们。这个逻辑被分配到一个名为 getAvailableFilters 的方法中：

通过上述聚合查询，我们得到以下结果：

点击此处查看所有结果。

对于这两种策略，我们将使用混合搜索来检测问题的结构化部分（过滤器）和主观部分（语义）。以下是使用搜索模板的两个查询示例：

查看 elasticsearchSetup.ts 文件中详细的查询。在接下来的节点中，将决定使用这两个查询中的哪一个：

prepareInvestmentSearch 和 prepareMarketSearch 节点

两个节点都使用共享的辅助函数 extractFilterValues，该函数利用 LLM 来识别用户输入中提到的相关过滤器，例如行业、地点、资金阶段、商业模式等。我们正在使用这个架构来构建我们的 搜索模板。

根据检测到的意图，工作流会选择以下两种路径之一：

PrepareInvestmentSearch：构建以财务为导向的搜索参数，包括融资阶段、融资金额、投资者以及营收相关信息。您可以在 elasticsearchSetup.ts 文件中找到整个查询模板：

prepareMarketSearch：创建以行业、地域和商业模式为重点的市场驱动参数。在 elasticsearchSetup.ts 文件中查看完整查询：

executeSearch 节点

该节点从状态中获取生成的搜索参数，首先将其发送到 Elasticsearch，使用_render API来可视化查询以便调试，然后发送请求以检索结果。

visualizeResults 节点

最后，此节点显示 Elasticsearch 结果。

从程序角度来看，整个图结构如下所示：

正如你所见，我们有一个条件边，应用在此决定接下来运行哪个“路径”或节点。当工作流需要分支逻辑时，例如在多个工具之间进行选择或包含人机交互步骤，此功能非常有用。

了解了 LangGraph 的核心功能后，我们可以设置代码运行的应用程序：

将所有内容在 main 方法中整合起来，在名为 workflow 的变量中声明这个包含所有元素的图结构：

查询变量用来模拟用户在一个虚拟搜索框中输入的内容：

系统会从这句自然语言“查找已完成 A 轮或 B 轮、融资额在 800 万至 2,500 万美元之间且月收入高于 50 万美元的初创公司”中，自动抽取出所有筛选条件。

最后，调用主方法：

实施结果

对于这条输入，应用会选择聚焦投资维度的路径，由此我们可以看到 LangGraph 工作流生成的 Elasticsearch 查询，它会从用户输入中抽取出各类数值与区间。此外，我们还能看到应用了这些提取参数后实际发送到 Elasticsearch 的查询，以及最后由 visualizeResults 节点格式化输出的结果。

现在，我们再用这条查询来测试聚焦市场维度的节点：“查找位于旧金山、纽约或波士顿的金融科技和医疗健康初创公司”：

学习经验

在写作过程中我学到了：

• 我们必须向 LLM 提供筛选器的精确取值，否则就要完全依赖用户输入这些值。对于低基数，这种方法很好，但当基数很高时，我们需要通过一些机制来过滤结果

• 使用搜索模板比让大语言模型编写 Elasticsearch 查询能使结果更加一致，而且速度也更快

• 条件边是一种强大的机制，用于构建具有多个变体和分支路径的应用程序。

• 结构化输出在使用大型语言模型生成信息时非常有用，因为它能强制执行可预测且类型安全的响应。这不仅提高了整体可靠性，还减少了对提示词的误解。

通过混合检索结合语义和结构化搜索，可以产生更好、更相关的结果，在精确性和上下文理解之间取得平衡。

结论

在这个例子中，我们将 LangGraph.js 与 Elasticsearch 结合，创建一个动态工作流，能够解释自然语言查询并决定使用金融或市场聚焦的搜索策略。这种方法减少了手工查询的复杂性，同时提升了风险投资分析师的灵活性和准确性。

本文将向您展示如何使用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.单击启动服务器

如果服务器正在运行，您应该会看到这个提示。

第 2 步：使用 Docker 部署本地弹性

现在，我们将使用 Docker 在本地设置 Elasticsearch 和 Kibana。Elastic 提供了一个方便的脚本来处理整个设置过程。更多详情，请参阅官方文档。

运行启动本地脚本

在终端中执行以下命令

该脚本将

• 下载并配置 Elasticsearch 和 Kibana

• 使用 Docker Compose 启动两个服务

• 自动激活 30 天白金试用版许可证

预期产出

只需等待以下信息并保存显示的密码和 API 密钥；访问 Kibana 时需要它们：

访问 Kibana

打开浏览器并导航至

使用终端输出中获得的证书登录。

启用代理生成器

登录 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 会自动测试连接。如果一切配置正确，您将看到如下成功信息：

响应：

第 4 步：将员工数据上传到 Elasticsearch

现在，我们将上传人力资源员工数据集，以演示代理如何处理敏感数据。我用这种结构生成了一个虚构的数据集。

数据集结构

使用映射创建索引

首先，创建具有适当映射的索引。请注意，我们对一些关键字段使用了semantic_text 字段；这样就能为我们的索引提供语义搜索功能。

使用批量 API 索引

将数据集复制并粘贴到 Kibana 的 Dev Tools 中并执行：

验证数据

运行查询进行验证：

第 5 步：构建并测试人工智能代理

一切配置完成后，就可以使用 Elastic Agent Builder 创建自定义人工智能代理了。有关详细信息，请参阅Elastic 文档。

添加连接器

在创建新代理之前，我们必须将代理生成器设置为使用名为LM Studio - GPT-OSS 20B 的自定义连接器，因为默认连接器是Elastic Managed LLM。为此，我们需要进入 "项目设置"> "管理"> "GenAI 设置"；现在选择我们创建的设置，然后单击 "保存"。

访问代理生成器

1. 前往代理商

2. 点击创建新代理

配置代理

要创建新代理，必须填写代理 ID、显示名称和显示说明。

但还有更多的自定义选项，比如 "自定义指令"，它可以指导代理如何与工具进行交互，类似于系统提示，但适用于我们的自定义代理。标签可帮助您组织代理人、头像颜色和头像符号。

我根据数据集为我们的代理选择的代理编号是： Agent ID： hr_assistant

自定义说明：

标签：Human Resources 和 GPT-OSS

显示名称： HR Analytics Assistant

显示说明：

有了所有数据，我们就可以点击 "保存新代理"。

测试代理

现在，您可以就员工数据提出自然语言问题，GPT-OSS 20B 将理解您的意图并生成适当的回复。

提示：

请回答：

代理过程是

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 还为我们带来了同样宝贵的经验：首次接触我们 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：故事任务

新闻主管（作为客户）指定一篇报道：

第 2 步：记者要求进行研究

报告代理认识到它需要背景信息，并通过 A2A 委托给研究代理：

第 3 步：报告人请求存档代理提供历史背景信息

记者代理认识到，历史背景会加强故事性。它通过 A2A 委托档案代理（由Elastic 的 A2A 代理提供支持）搜索新闻编辑室由 Elasticsearch 支持的文章档案：

步骤 4：归档代理使用带有 MCP 的弹性 A2A 代理

存档代理使用 Elastic 的 A2A 代理，而 A2A 代理又使用 MCP 访问 Elasticsearch 工具。这展示了混合架构，其中 A2A 实现了代理协作，而 MCP 提供了工具访问：

存档代理从 Elastic 的 A2A 代理接收全面的历史数据，并将其返回给报告器：

这一步骤演示了 Elastic 的 A2A Agent 如何集成到新闻编辑室的工作流程中。Archive Agent（新闻编辑室专用代理）与 Elastic 的 A2A Agent（第三方专家）协调，以利用 Elasticsearch 强大的搜索和分析功能。Elastic 的代理在内部使用 MCP 访问 Elasticsearch 工具，显示了代理协调 (A2A) 和工具访问 (MCP) 之间的明确分离。

步骤 5：研究人员使用 MCP 服务器

研究员代理访问多个 MCP 服务器以收集信息：

步骤 6：研究人员将数据返回给报告人

研究员代理通过 A2A 发送综合研究结果：

第 7 步：记者撰写文章

报告代理利用研究数据和自身的 LLM 能力撰写文章。在撰写过程中，记者使用 MCP 服务器获取样式和模板：

第 8 步：信心不足引发重新研究

报告代理评估了其草稿，发现有一项索赔的可信度较低。它会向研究员代理发送另一个请求：

研究员使用事实核查 MCP 服务器核实索赔，并返回更新的信息：

第 9 步：记者修改并提交给编辑

记者将核实的事实纳入其中，并通过 A2A 将完成的草稿发送给编辑代理：

步骤 10：编辑使用 MCP 工具进行审查

编辑代理使用多个 MCP 服务器来审核文章：

编辑批准文章并将其转发：

第 11 步：发布者通过 CI/CD 发布

最后，打印机代理使用 CMS 和 CI/CD 管道的 MCP 服务器发布已批准的文章：

出版商确认通过 A2A 出版：

下面是随附的资料库中使用上述相同代理的 A2A 工作流程的完整序列。

#

来自

至

行动

规程

描述

1

用户

新闻主管

指定故事

HTTP POST

用户提交故事主题和角度

2

新闻主管

内部

创建故事

-

创建具有唯一 ID 的故事记录

3

新闻主管

记者

代表任务

A2A

通过 A2A 协议发送故事任务

4

记者

内部

接受任务

-

内部存储任务

5

记者

MCP 服务器

生成大纲

MCP/HTTP

创建文章大纲和研究问题

6a

记者

研究员

申请研究

A2A

发送问题（与 6b 并行）

6b

记者

档案员

搜索档案

A2A JSONRPC

搜索历史文章（与 6a 并行）

7

研究员

MCP 服务器

研究问题

MCP/HTTP

通过 MCP 使用人类学来回答问题

8

研究员

记者

返回研究

A2A

返回研究答案

9

档案员

Elasticsearch

搜索索引

ES REST API

查询 news_archive 索引

10

档案员

记者

返回存档

A2A JSONRPC

返回历史搜索结果

11

记者

MCP 服务器

生成文章

MCP/HTTP

创建具有研究/档案背景的文章

12

记者

内部

商店草案

-

内部保存草稿

13

记者

新闻主管

提交草案

A2A

提交完成的草稿

14

新闻主管

内部

更新故事

-

存储草稿，将状态更新为"draft_submitted"

15

新闻主管

编辑

审查草案

A2A

自动路由至编辑器以供审核

16

编辑

MCP 服务器

评论文章

MCP/HTTP

通过 MCP 使用 Anthropic 分析内容

17

编辑

新闻主管

返回评论

A2A

发送编辑反馈和建议

18

新闻主管

内部

商店评论

-

存储编辑反馈

19

新闻主管

记者

应用编辑

A2A

将审查反馈意见转达给报告人

20

记者

MCP 服务器

应用编辑

MCP/HTTP

根据反馈意见修改文章

21

记者

内部

更新草案

-

对草案进行修订更新

220

记者

新闻主管

返回修订版

A2A

返回修订后的文章

23

新闻主管

内部

更新故事

-

存储修订草案，状态为"修订版"

24

新闻主管

出版商

发表文章

A2A

出版商自动路由

25

出版商

MCP 服务器

生成标签

MCP/HTTP

创建标记和类别

26

出版商

Elasticsearch

索引文章

ES REST API

将文章索引到 news_archive 索引

27

出版商

文件系统

保存标记

文件输入/输出

将文章保存为 .md文件在 /articles

28

出版商

新闻主管

确认出版

A2A

返回成功状态

29

新闻主管

内部

更新故事

-

将故事状态更新为"已发布"

结论

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

与数据交互的新方式

生成式人工智能（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 在接受训练时无法获得的额外信息的技术，或者说是重申我们认为对获得正确答案最重要的想法--与我们的主观疑问最相关的想法。

惊人的宇宙力量，微不足道的生活空间！

代理人工智能有许多迷人而令人兴奋的新领域有待探索！我们仍有许多传统的数据检索和处理问题需要解决，但同时也面临着全新的挑战，这些挑战现在才在新的 LLM 时代暴露出来。我们今天要解决的许多紧迫问题都与情境工程有关，即如何在不占用有限工作记忆空间的前提下，为 LLM 提供所需的额外情境信息。

半自主代理可以使用一系列工具（和其他代理），其灵活性为人工智能的实施带来了许多新思路，我们很难想象会有什么不同的方法可以将这些碎片组合在一起。目前的大部分研究都属于上下文工程学领域，主要集中在构建能够处理和跟踪大量上下文的内存管理结构上，这是因为我们真正希望 LLM 能够解决的深度思考问题具有更高的复杂性和更长的多阶段思考步骤，在这些问题中，记忆极为重要。

该领域正在进行的许多实验都是为了找到最佳的任务管理和工具配置，以满足代理的需求。代理推理链中的每次工具调用都会产生累积成本，既包括执行工具功能所需的计算量，也包括对有限上下文窗口的影响。为 LLM 代理管理上下文的一些最新技术造成了意想不到的连锁效应，如 "上下文崩溃"，在这种情况下，压缩/汇总长期运行任务的累积上下文会造成过多损失。理想的结果是工具能够返回简洁准确的上下文，而不会让无关信息渗入宝贵的上下文窗口内存空间。

太多/太多种可能性

我们希望职责分离，并能灵活地重复使用工具/组件，因此创建专用的代理工具来连接特定的数据源是完全合理的--每种工具都可以专门查询一种类型的存储库、一种类型的数据流，甚至一种使用案例。但要注意：为了节省时间/金钱/证明某些事情是可行的，我们会受到强烈的诱惑，把 LLM 用作联盟工具......尽量不要这样做，我们以前走过这条路！联合查询就像一个 "通用翻译器"，它将输入的查询转换成远程存储库能理解的语法，然后以某种方式将多个来源的结果合理化为一个连贯的响应。联盟作为一种技术，在小范围内效果 还可以，但在大范围内，特别是当数据是多模态的时候，联盟试图弥合的差距就太大了。

在代理世界中，代理将是联合器，而工具（通过 MCP）将是人工定义的与不同资源的连接。使用专用工具跨未连接的数据源进行访问，看似是在每次查询的基础上动态联合不同数据流的强大新方法，但使用工具向多个数据源提出相同的问题，最终可能会造成更多问题，而不是解决问题。每个数据源下面都可能有不同类型的存储库，每个存储库都有自己的数据检索、排序和安全功能。当然，资源库之间的差异或 "阻抗不匹配 "会增加处理负荷。它们还可能引入相互冲突的信息或信号，看似无关紧要的评分失准可能会严重影响对返回上下文的重视程度，并最终影响生成回复的相关性。

计算机也很难进行上下文切换

当你派出一名特工执行任务时，他们的首要任务往往是找到其可以访问的所有相关数据。就像人类一样，如果代理连接的每个数据源都给出了不同的分类回复，那么从检索到的内容中提取显著的上下文信息就会产生认知负荷（尽管不是完全相同的类型）。这需要时间/计算，而在代理逻辑链中，每一点都是累加的。由此得出的结论是，就像正在讨论的MCP 一样，大多数代理工具的行为应该更像应用程序接口（API）--具有已知输入和输出的孤立函数，经过调整以支持不同类型代理的需求。哎呀，我们甚至意识到，语言学硕士需要上下文语境--他们在连接语义点方面做得更好，尤其是在将自然语言翻译成结构化语法这样的任务中，当他们有模式可参考时（确实是 RTFM！）。

第 7 局

现在，我们已经介绍了LLM 对数据检索和查询的影响，以及聊天窗口如何逐渐成为人工智能代理体验。让我们把这两个主题放在一起，看看如何利用新式搜索和检索功能来改进上下文工程的结果。进入第三部分：混合搜索在情境工程中的威力！

当前由 LLM 支持的系统正在迅速发展，超越了单一模型应用，成为复杂的网络，其中专门的代理共同完成现代计算前所未有的任务。随着这些系统的复杂性不断增加，使代理通信和工具访问成为可能的基础设施成为开发的重点。为满足这些需求，出现了两种互补的方法：用于多代理协调的代理2代理（A2A）协议，以及用于标准化工具和资源访问的模型上下文协议（MCP）。

了解在什么情况下可以同时使用和不使用这两种方法，会对应用程序的可扩展性、可维护性和有效性产生重大影响。本文以数字新闻编辑室为例，探讨了A2A的概念和实现方法，在数字新闻编辑室中，专门的 LLM 代理合作研究、撰写、编辑和发布新闻文章。

我们将在文章最后的第 5 部分探讨 A2A 的具体应用实例。

准备工作

资源库由 A2A 代理的 Python 实现组成。Flask 提供了一个 API 服务器，以及一个名为 Event Hub 的自定义 Python 消息传递服务，用于路由日志和 UI 更新消息。最后，还提供了一个 React UI，用于独立使用新闻编辑室的功能。所有内容都包含在一个 Docker 镜像中，以便于实施。如果您想直接在机器上运行服务，则需要确保安装了这些技术：

语言和运行时

• Python 13.12 - 核心后端语言

• Node.js 18+ - 可选 React UI

核心框架和 SDKS：

• A2A SDK 0.3.8 - Agent 协调与通信

• Anthropic SDK--克劳德集成人工智能生成器

• Uvicorn - 用于运行代理的 ASGI 服务器

• FastMCP 2.12.5+ - MCP 服务器实施

• React 18.2 - 前端用户界面框架

数据& 搜索

• Elasticsearch 9.1.1+- 文章索引和搜索

Docker 部署（可选，但建议使用）

• Docker 28.5.1+

第 1 部分：什么是 Agent2Agent（A2A）？

定义和核心概念

Agent2Agent(A2A) 是独立 LLM 代理 之间进行交互的标准化协议。A2A 不是由一个单一的系统来处理所有任务，而是让多个专业代理进行沟通、协调和协作，以完成复杂的工作流程，而这些工作流程对于任何单一代理来说都是难以高效处理、速度缓慢或根本不可能完成的。

官方规格 ：https://a2a-protocol.org/latest/specification/

起源与进化

Agent2Agent 通信或多代理系统的概念源于几十年前的分布式系统、微服务和多代理研究。分布式人工智能的早期工作为能够进行协商、协调和协作的代理奠定了基础。这些早期系统专门用于大规模社会模拟、学术研究和电网管理。

在谷歌和更广泛的人工智能研究界的支持下，随着 LLM 的出现和运行成本的降低，多代理系统开始进入 "专业消费者 "市场。现在，A2A 协议被称为 Agent2Agent 系统，它已发展成为一个现代标准，专为多个大型语言模型协调工作和任务的时代而设计。

A2A 协议将一致的标准和原则应用于 LLM 连接和通信的交互点，从而确保代理之间的无缝通信和协调。这种标准化使来自不同开发商、使用不同底层模型的代理能够有效地协同工作。

通信协议并非新生事物，在互联网上进行的几乎所有数字交易中都有广泛的应用。如果您键入https://www.elastic.co/search-labs在浏览器中访问这篇文章时，很有可能 TCP/IP、HTTP 传输和 DNS 查询协议都已执行，从而确保我们获得一致的浏览体验。

主要特点

A2A 系统建立在几个基本原则之上，以确保通信顺畅。以这些原则为基础，可以确保基于不同 LLM、框架和编程语言的不同代理都能无缝互动。

以下是四项主要原则：

• 信息传递：代理通过具有明确属性和格式的结构化信息进行通信

• 协调：代理通过相互委派任务和管理依赖关系来协调复杂的工作流程，而不会阻塞其他代理

• 专业化：每个代理都专注于某一特定领域或能力，成为该领域的专家，并根据技能组合完成任务

• 分布式状态：状态和知识分布在各个代理之间，而不是集中在一起，代理之间能够相互更新任务状态和部分回报（工件）的进展情况

新闻编辑室运行范例

试想一个由人工智能代理驱动的数字新闻编辑室，每个代理都擅长新闻业的不同方面：

• 新闻主管（协调员/客户）：分配报道任务并监督工作流程

• 记者代理：根据研究和采访撰写文章

• 研究员代理：收集事实、统计数据和背景信息

• 档案代理：使用 Elasticsearch 搜索历史文章并确定趋势

• 编辑代理：对文章的质量、风格和搜索引擎优化进行审核

• 发布者代理：通过 CI/CD 将批准的文章发布到博客平台上

当新闻主管指派一篇关于可再生能源应用的报道时，记者需要研究员收集统计数据，编辑需要审阅草稿，出版商需要出版最终稿件。这种协调是通过 A2A 协议进行的。

第 2 节：了解 A2A 架构

客户代理和远程代理角色

在 A2A 架构中，代理主要扮演两种角色。客户代理负责制定任务并将任务传达给系统中的其他代理。它能识别远程代理及其能力，并利用这些信息就任务授权做出明智的决策。客户代理负责协调整个工作流程，确保任务分配得当，系统朝着目标前进。

而远程代理则负责执行客户委托的任务。它根据请求提供信息或采取具体行动，但不会独立发起行动。远程代理还可以根据需要与其他远程代理进行通信，以履行其指定职责，从而创建一个具有专业能力的协作网络。

在我们的新闻编辑室，新闻主管充当客户代理，而记者、研究员、编辑和出版商则是远程代理，负责响应请求并相互协调。

A2A 核心能力

A2A 协议定义了几种实现多代理协作的功能：

1.发现

A2A 服务器必须公布其功能，以便客户知道何时以及如何利用它们完成特定任务。这可以通过描述代理能力、输入和输出的代理卡--JSON 文档来实现。代理卡在一致的知名端点（如推荐的/.well-known/agent-card.json 端点）上提供，允许客户在启动协作之前发现并查询代理的能力。

以下是 Elastic 定制存档代理"Archie Archivist" 的代理卡示例。请注意，Elastic 等软件提供商会托管其 A2A 代理，并提供一个 url 供访问：

该代理卡揭示了 Elastic 档案代理的几个重要方面。该代理将自己定位为"Archie Archivist" ，并明确说明了自己的目的：帮助在 Elasticsearch 索引中查找历史新闻文档。该卡指定了提供商（Elastic）和协议版本（0.3.0），以确保与其他 A2A 兼容代理的兼容性。最重要的是，skills 数组列举了该代理提供的具体功能，包括强大的搜索功能和智能索引探索。每种技能都定义了它所支持的输入和输出模式，使客户能够准确了解如何与该代理进行通信。该代理源于 Elastic 的代理生成器服务，它提供了一套本地 LLM 支持的工具和 API 端点，用于与数据存储对话，而不仅仅是从存储中检索。可在此处访问 Elasticsearch 中的 A2A 代理。

2.谈判

客户和代理需要就交流方式达成一致--无论互动是通过文本、表单、iframe 还是音频/视频进行，以确保适当的用户互动和数据交换。这种协商发生在代理合作的开始阶段，并确立了整个工作流程中的交互协议。例如，语音客户服务代理可能会协商通过音频流进行通信，而数据分析代理可能更喜欢结构化的 JSON。谈判过程可确保双方以适合自身能力和当前任务要求的形式有效交换信息。

上述 JSON 代码段中列出的功能都有输入和输出模式；这些模式设定了如何与其他代理交互。

3.任务和状态管理

在整个任务执行过程中，客户端和代理需要有机制来交流任务状态、变化和依赖关系。这包括管理任务从创建、分配到进度更新和状态更改的整个生命周期。典型的状态包括待处理、进行中、已完成或失败状态。系统还必须跟踪任务之间的依赖关系，以确保在依赖任务开始之前完成前提工作。错误处理和重试逻辑也是必不可少的组成部分，可让系统从容地从故障中恢复，并继续朝着主要目标前进。

任务信息示例：

这个任务信息示例展示了 A2A 通信的几个关键方面。

• 信息结构包括元数据，如唯一的信息标识符、发送的信息类型、发送方和接收方标识，以及用于跟踪和调试的时间戳。

• 有效载荷包含实际的任务信息，指明远程代理正在调用的功能，并提供执行该功能所需的参数。

• 上下文部分提供了更多信息，帮助接收代理了解更广泛的工作流程，包括截止日期和优先级，告知代理应如何分配资源和安排工作。

4.合作

客户端和代理必须支持动态但有条理的交互，使代理能够要求客户端、其他代理或用户提供说明、信息或子操作。这就创造了一个协作环境，代理可以在初始指令不明确时提出后续问题，要求提供更多的背景信息以做出更好的决策，将子任务委托给其他具有更合适专业知识的代理，并在继续执行完整任务之前提供中间结果以获得反馈。这种多向沟通可确保代理商不是孤立地工作，而是参与到持续的对话中，从而取得更好的成果。

分布式点对点通信

A2A 实现了分布式通信，其中代理可能由不同的组织托管，一些代理由内部维护，另一些则由第三方服务提供。这些代理可以在不同的基础设施上运行，可能跨越多个云提供商或内部数据中心。它们可能使用不同的底层 LLM，一些代理采用 GPT 模型，另一些采用 Claude 模型，还有一些采用开源替代模型。代理甚至可以跨越不同的地理区域运行，以符合数据主权要求或减少延迟。尽管存在这种多样性，但所有代理都同意使用共同的通信协议来交换信息，从而确保了互操作性，而不管实施细节如何。这种分布式架构为系统的构建和部署提供了灵活性，使企业能够根据自身的具体需求，混合和匹配最佳的代理和基础设施。

这就是新闻编辑室应用程序的最终架构：

第 3 节：模型上下文协议（MCP）

定义和目的

模型上下文协议（MCP）是 Anthropic 开发的一种标准化协议，旨在通过用户定义的工具、资源和提示，以及其他补充代码库增添的内容，来增强单个 LLM 的功能和能力。MCP 在语言模型和它们有效完成任务所需的外部资源之间提供了一个通用接口。本文通过用例、新兴趋势和 Elastic 自身的实施，概述了 MCP 的现状。

MCP 核心概念

MCP 采用客户服务器架构，由三个主要部分组成：

• 客户端：连接到 MCP 服务器以访问其功能的应用程序（如 Claude Desktop 或自定义 AI 应用程序）。

• 服务器：向语言模型提供资源、工具和提示的应用程序。每个服务器都专门提供对特定功能或数据源的访问。

  • 工具：用户定义的函数，模型可调用这些函数进行操作，如搜索数据库、调用外部应用程序接口或对数据执行转换等。

  • 资源：模型可以读取的数据源，提供动态或静态数据，并通过 URI 模式访问（类似于 REST 路由）。

  • 提示： 可重复使用的提示模板，带有变量，可指导模型完成特定任务。

请求-响应模式

MCP 采用熟悉的请求-响应交互模式，类似于 REST API。客户端（LLM）请求资源或调用工具，然后 MCP 服务器处理请求并返回结果，LLM 利用该结果继续执行任务。与点对点代理通信相比，这种带有外围服务器的集中模式提供了一种更简单的集成模式。

新闻编辑室中的 MCP

在我们的新闻编辑室示例中，各个代理使用 MCP 服务器访问他们需要的工具和数据：

• 研究员代理使用：

  • 新闻 API MCP 服务器（访问新闻数据库）

  • 事实核查 MCP 服务器（根据可信来源核查声明）

  • 学术数据库 MCP 服务器（学术文章和研究）

• 记者代理用途：

  • 风格指南 MCP 服务器（新闻编辑室写作标准）

  • 模板 MCP 服务器（文章模板和格式）

  • 图片库 MCP 服务器（图片库照片和图形）

• 编辑器代理使用：

  • 语法检查程序 MCP 服务器（语言质量工具）

  • 剽窃检测 MCP 服务器（原创性验证）

  • 搜索引擎优化分析 MCP 服务器（标题和关键词优化）

• 出版商代理使用：

  • 内容管理系统 MCP 服务器（内容管理系统 API）

  • CI/CD MCP 服务器（部署管道）

  • 分析 MCP 服务器（跟踪和监控）

第 4 部分：架构比较

何时使用 A2A

A2A 架构在需要真正多代理协作的场景中表现出色。需要协调的多步骤工作流从 A2A 中受益匪浅，尤其是当任务涉及多个连续或并行步骤、需要迭代和改进的工作流以及需要检查点和验证的流程时。在我们的新闻编辑室示例中，报道工作流程要求记者撰写，但如果对某些事实的信心不足，可能需要返回研究员，然后再返回编辑，最后返回出版商。

跨越多个领域的特定领域专业化是 A2A 的另一个强大用例。当需要不同领域的多位专家来完成一项更大的任务时，每个代理都会带来深厚的领域知识和针对不同方面的专门推理能力，A2A 提供了建立这些联系所需的协调框架。新闻编辑室完美地体现了这一点：研究员擅长信息收集，记者擅长写作，编辑擅长质量控制--每个人都有自己独特的专长。

对自主代理行为的需求使得 A2A 尤其有价值。在 A2A 架构中，能够 根据不断变化的条件做出独立决策、表现出积极主动行为并能动态适应工作流程要求的代理可茁壮成长。专业化功能的横向扩展是另一个关键优势--多个专业化代理协同工作，而不是只有一个万能代理，同一代理的多个实例可以异步处理子任务。例如，在我们的新闻编辑室报道突发新闻时，多名记者代理可能会同时从不同角度报道同一新闻。

最后，需要真正多代理协作的任务是 A2A 的理想选择。这包括法律硕士即评审团的评估机制、建立共识和投票系统，以及需要多角度达成最佳结果的协作式问题解决方法。

何时使用 MCP

模型上下文协议是扩展单一人工智能模型功能的理想选择。当单个人工智能模型需要访问多个工具和数据源时，MCP 提供了完美的解决方案，集中式推理与分布式工具和直接的工具集成相结合。在我们的新闻编辑室示例中，研究员代理（一种模式）需要访问多个数据源，包括新闻 API、事实核查服务和学术数据库--所有这些都通过标准化的 MCP 服务器访问。

当工具集成的广泛共享和可重用性变得非常重要时，标准化工具集成就成了优先事项。MCP 凭借其预构建的 MCP 服务器生态系统大放异彩，大大缩短了常见集成的开发时间。当需要简单性和可维护性时，MCP 的请求-响应模式是开发人员所熟悉的，比分布式系统更容易理解和调试，操作复杂性也更低。

最后，软件供应商通常会提供 MCP，以方便与其系统进行远程通信。这些由供应商提供的 MCP 服务器大大缩短了入网和开发时间，同时为专有系统提供了标准化接口，使集成比定制 API 开发更加简单。

何时同时使用两种方法（A2A ❤️ 的 MCP）

正如 A2A 有关 MCP 集成的文档 所指出的，许多复杂的系统都能从 A2A 和 MCP 的 结合中受益。既需要协调又需要标准化的系统是混合方法的理想选择。A2A 处理代理协调和工作流程协调，而 MCP 则为单个代理提供工具访问。在我们的新闻编辑室示例中，代理通过 A2A 进行协调；工作流程从记者到研究员，再到编辑，最后到出版商。不过，每个代理都使用 MCP 服务器来管理其专用工具，从而实现了干净利落的架构分离。

多个专门的代理，每个都使用 MCP 进行工具访问，这代表了一种常见的模式，即代理协调层由 A2A 处理，工具访问层由 MCP 管理。这种明确的分工使系统更容易理解和维护。

将这两种方法结合起来的好处是巨大的。您可以获得多代理系统的组织优势，包括专业化、自主性和并行处理，同时还可以享受 MCP 的标准化和生态系统优势，如工具集成和资源访问。代理协调（A2A）和资源访问（MCP）之间有明确的分离，而且重要的是，A2A 不需要单独用于 API 访问等较小的任务，MCP 可以高效地处理这些任务，而不需要多代理协调的开销。

常见问题：A2A 与 MCP--使用案例

功能

Agent2Agent (A2A)

模型上下文协议（MCP）

混合型（A2A + MCP）

首要目标

多代理协调：使专业代理团队能够在复杂的多步骤工作流程中协同工作。

单一代理增强：利用外部工具、资源和数据扩展单一 LLM/Agent 的能力。

综合实力：A2A 负责团队的工作流程，而 MCP 则为每个团队成员提供工具。

新闻编辑室团队范例

工作流程链：新闻主管 → 记者 → 研究员 → 编辑 → 出版商。这是协调层。

单个代理的工具：记者代理访问样式指南服务器和模板服务器（通过 MCP）。这是工具访问层。

完整的系统：记者与编辑（A2A）协调，记者使用图像库 MCP 服务器为报道寻找图片。

何时使用

当您需要真正的协作、迭代和改进，或需要多个代理分担专业知识时。

当单个代理需要访问多个工具和数据源或需要与专有系统进行标准化集成时。

当您需要多代理系统的组织优势以及 MCP 的标准化和生态系统优势时。

核心效益

自主性和扩展性：代理可以独立做出决定，系统允许专门功能的横向扩展。

简单化和标准化：由于集中推理，调试和维护更容易，并为资源提供了通用接口。

明确区分关注点：使系统更易于理解：A2A = 团队合作，MCP = 工具使用。

结论

这是两篇文章的第一部分，内容涉及基于 A2A 的代理的实施，并通过 MCP 服务器提供支持和外部数据及工具访问。下一篇文章将探讨实际代码，以演示它们如何共同模拟在线新闻编辑室的活动。虽然这两种框架本身都具有极强的能力和灵活性，但当它们协同工作时，你就会发现它们之间的互补性有多大。

什么是递归分块？

递归分块法会遍历所提供的分块模式列表，逐步将文档分成更小的分块，直到达到所需的最大分块大小。

如何配置递归分块？

以下是用户为递归分块提供的可配置值：

• (必填）max_chunk_size ：字块中的最大字数。

• 任选其一：

  • separators:用于将文档分割成块的 regex 字符串模式列表。

  • separator_group:一个字符串，它将映射到 Elastic 定义的默认分隔符列表，用于特定类型的文档。目前，markdown 和plaintext 。

递归分块是如何工作的？

递归分块的过程如下：给定输入文档、max_chunk_size （以字数为单位）和分隔符字符串列表：

1. 如果输入文档已经在最大分块大小范围内，则返回一个涵盖整个输入文档的分块。

2. 根据分隔符的出现次数，将文本分割成潜在的文本块。对于每个潜在的数据块

   1. 如果潜在数据块在最大数据块大小范围内，则将其添加到要返回给用户的数据块列表中。

   2. 否则，从第 2 步开始重复，只使用潜在文本块中的文本，并使用列表中的下一个分隔符进行分割。如果没有其他分隔符可以尝试，就退回到基于句子的分块。

配置递归分块的示例

除了分块大小，递归分块的主要配置是选择应使用哪些分隔符来分割文档。如果您不确定从哪里开始，Elasticsearch 提供了一些默认的分离器组，可用于常见的使用情况。

利用分离器组

要使用分隔组，只需在配置分块设置时提供要使用的组名即可。例如

这样就可以利用分隔符列表["(?<!\\n)\\n\\n(?!\\n)", "(?<!\\n)\\n(?!\\n)")] 来实现递归分块策略。对于一般的纯文本应用程序，这种方法效果很好，可以在 2 个换行符后再分隔出 1 个换行符。

我们还提供一个分隔符组markdown ，它将利用分隔符列表：

这个分隔符列表可以很好地适用于一般的标记符使用情况，在 6 个标题层次和分节符上分别进行分隔。

创建资源（推理端点/语义文本字段）时，与当时分隔符组相对应的分隔符列表将存储在您的配置中。如果以后更新了分隔符组，也不会改变已创建资源的行为。

使用自定义分隔符列表

如果预定义的分隔符组不适合您的使用情况，您可以定义一个符合您需求的自定义分隔符列表。请注意，可以在分隔符列表中提供正则表达式。以下是使用自定义分隔符配置分块设置的示例：

上述分块策略将在 2 个换行符、1 个换行符和一个字符串“<my-custom-separator>” 上进行分割。

递归分块的实际应用示例

让我们来看一个递归分块的实例。在本示例中，我们将使用以下分块设置和自定义分隔符列表，使用顶部两层标题分割标记符文档：

让我们来看看一个简单的未分块 Markdown 文档：

现在，让我们使用上面定义的分块设置对文档进行分块：

注意：每个分块（分块 3 除外）末尾的换行符不会突出显示，而是包含在实际分块边界内。

今天就开始使用递归分块技术！

有关使用该功能的更多信息，请查看有关配置分块设置的文档。

为此，我们使用谷歌的 SigLIP-2 为图像和文本生成矢量嵌入，并将其存储在 Elasticsearch 矢量数据库中。在查询时，我们将搜索输入（文本或图像）转换为嵌入，并运行快速的 kNN 向量搜索来检索结果。这种设置可实现高效的文本到图像和图像到图像搜索。Streamlit 用户界面为我们提供了一个前端，不仅可以进行基于文本的搜索，从相册中查找并查看匹配的照片，还可以从上传的图片中识别山峰，并查看相册中该山峰的其他照片，从而使该项目栩栩如生。我们还介绍了为提高搜索准确性而采取的措施，以及实用技巧和窍门。为便于进一步探索，我们提供了GitHub 存储库和Colab 笔记本。

如何开始

这篇博文的灵感来自于一个 10 岁的孩子，他让我给他们看我在珠峰大本营徒步旅行时拍摄的阿玛达布拉姆山的所有照片。在翻阅相册时，我还被要求辨认其他几座山峰，其中一些我还叫不出名字。

这让我想到，这可以成为一个有趣的计算机视觉项目。我们的目标

• 按名称查找山峰图片

• 从图片中猜测山峰名称，并在相册中找到类似的山峰

• 让概念查询发挥作用（人、河流、祈祷旗 等）

组建梦之队：SigLIP-2、Elasticsearch& Streamlit

很快我们就发现，要想实现这一目标，我们需要将文字（"阿玛达布拉姆"）和图像（我相册中的照片）都转化为可以进行有意义比较的矢量，即在同一个矢量空间中。一旦我们做到了这一点，搜索就只是 "寻找最近的邻居"。

为了生成图像嵌入，我们使用了多语言 视觉语言编码器，因此山峰的照片和 "Ama Dablam "这样的短语会出现在同一个向量空间中。

谷歌最近发布的SigLIP-2 在这方面非常适合。它可以在没有特定任务训练的情况下生成嵌入式（零镜头设置），并能很好地适用于我们的使用案例：未标记的照片和具有不同名称和语言的山峰。由于它是针对文本与图像匹配进行训练的，因此即使查询语言或拼写不同，徒步旅行中的山峰图片和简短的文字提示最终也能接近嵌入。

SigLIP-2 在质量与速度之间实现了很好的平衡，支持多种输入分辨率，并可在 CPU 和 GPU 上运行。SigLIP-2 在设计上比以前的型号（如最初的 CLIP）更适合户外拍摄。在我们的测试中，SigLIP-2 始终能生成可靠的结果。此外，它还得到了很好的支持，因此是本项目的不二之选。

接下来，我们需要一个向量数据库来存储嵌入和强力搜索。它不仅应支持对图像嵌入进行余弦 kNN 搜索，还应在单个查询中应用地理围栏和文本过滤器。Elasticsearch 在这方面非常适合：它能很好地处理向量（在 dense_vector 字段上使用 HNSW kNN），支持结合文本、向量和地理查询的混合搜索，并提供开箱即用的过滤和排序功能。它还可以横向扩展，因此很容易从少量照片扩展到数千张照片。最后，我们需要一个轻量级前端，以便输入搜索查询并查看结果。对于基于 Python 的快速演示，Streamlit 非常适合。它提供了我们所需的基本功能--文件上传、响应式图像网格以及用于排序和地理围栏的下拉菜单。它很容易克隆并在本地运行，也可以在 Colab 笔记本中使用。

实施

Elasticsearch 索引设计和索引策略

我们将在这个项目中使用两个索引：peaks_catalog 和photos 。

峰值_目录索引

该索引是珠峰大本营徒步旅行期间可看到的著名山峰的简明目录。该索引中的每份文件都对应一座山峰，如珠穆朗玛峰。对于每个山峰文档，我们都会存储名称/别名、可选的经纬度坐标以及由 SigLIP-2 文本提示（+ 可选的参考图片）混合而成的单一原型向量。

索引映射：

现场

类型

示例

目的/说明

矢量/索引

本我

关键词

阿玛-达布拉姆

稳定的弹头/ID

-

姓名

文本 + 关键字子字段

["Ama Dablam","Amadablam"]

别名/多语言名称；names.raw 用于精确筛选

-

纬纶

地理点

{"lat":27.8617,"lon":86.8614}

以经纬度组合形式显示的山顶 GPS 坐标（可选）

-

海拔_m

整数

6812

海拔（可选）

-

嵌入文本

dense_vector

768

该山峰的混合原型（提示和可选的 1-3 幅参考图片

index:true, similarity:"cosine", index_options：{type:"hnsw", m:16, ef_construction:128}

该索引主要用于图像到图像的搜索，例如从图像中识别山峰。我们还使用该索引来增强文本到图片的搜索结果。

总之，peaks_catalog 将问题""这是什么山？" "转化为一个重点突出的 "最近邻问题"，有效地将概念理解与图像数据的复杂性分离开来。

peaks_catalog 索引的索引策略： 首先，我们创建了一份在 EBC 徒步旅行中可见的最突出山峰的列表。对于每个山峰，我们都会在yaml 文件中存储其地理位置、名称、同义词和海拔高度。下一步是 生成 每个峰值的 嵌入 值，并将其存储在text_embed 字段中。为了生成稳健的嵌入，我们使用了以下技术：

• 创建文本原型：

  • 山峰名称

  • 提示组合（使用多个不同的提示来尝试回答同一个问题），例如

    • "尼泊尔喜马拉雅山脉山峰的自然照片{name} "

    • "{name} 昆布地区的地标性山峰，高山景观"

    • "{name} 山顶，积雪，岩石山脊线"

  • 可选的反概念（告诉 SigLIP-2 什么不能匹配）：为 "绘画、插图、海报、地图、徽标 "减去一个小矢量，这样我们就偏向于真实照片。

• 如果提供了峰值的参考图像，可选择创建图像原型。

然后，我们混合文本和图像原型，生成最终的嵌入。最后，文件将被索引到所有必填字段：

peaks_catalog 索引中的文件样本：

照片索引

该主索引存储相册中所有照片的详细信息。每份文档代表一张照片，包含以下信息：

• 相册中照片的相对路径。可用于查看匹配图像或在搜索用户界面中加载图像。

• 图片的 GPS 和时间信息。

• SigLIP-2 生成的图像编码密集矢量。

• predicted_peaks 可让我们根据峰名进行筛选。索引映射

现场

类型

示例

目的/说明

矢量/索引

路径

关键词

data/images/IMG_1234.HEIC

用户界面如何打开缩略图/全图

-

剪贴图片

dense_vector

768

SigLIP-2 图像嵌入

index:true, similarity:"cosine", index_options：{type:"hnsw", m:16, ef_construction:128}

预测峰值

关键词

["ama-dablam","pumori"]

索引时的 Top-K 猜想（廉价用户体验过滤器/面）

-

全球定位系统

地理点

{"lat":27.96,"lon":86.83}

启用地理筛选器

-

拍摄时间

date

2023-10-18T09:41:00Z

捕捉时间：排序/过滤

-

照片索引的索引策略： 对于相册中的每张照片，我们会采取以下措施： 从图像元数据中提取图像shot_time 和gps 信息。

• SigLIP-2 图像嵌入：通过模型传递图像并对向量进行 L2 归一化。将嵌入内容存储在clip_image 字段中。

• 预测峰值并将其存储在predicted_peaks 字段中。为此，我们首先获取上一步生成的照片图像向量，然后针对peaks_catalog 索引中的 text_embed 字段快速运行 kNN 搜索。我们保留顶部的 3-4 个山峰，忽略其余的。

• 我们通过对图片名称和路径进行散列计算_id 字段。这可以确保我们在多次运行后不会出现重复。

一旦我们确定了照片的所有字段，就会使用 批量 索引对照片文件进行 批量 索引：

照片索引中的样本文件：

总之，照片索引是相册中所有照片的快速、可过滤、kNN 就绪存储。它的映射结构非常简单，只需足够的结构就能快速检索、清晰显示，并按空间和时间对结果进行切分。该索引可同时满足这两种搜索用途。创建这两个索引的 Python 脚本可在此处找到。

下面的 Kibana 地图可视化将相册中的文档显示为绿色圆点，将peaks_catalog 索引中的山峰显示为红色三角形，其中绿色圆点与珠峰大本营徒步路线非常吻合。

搜索用例

按名称搜索（文本到图像）：该功能可让用户使用文本查询查找山峰照片（甚至是 "祈祷旗 "等抽象概念）。为此，使用 SigLIP-2 将文本输入转换为文本向量。为了生成稳健的文本向量，我们采用了与在peaks_catalog 索引中创建文本嵌入相同的策略： 将 文本输入与小型 提示集合 相结合 ，减去次要的 反概念向量 ，并应用 L2 归一化 生成最终的查询向量。然后在photos.clip_image 字段上执行 kNN查询，根据余弦相似度检索匹配度最高的峰值，从而找到最接近的图像。作为查询的一部分，还可选择应用地理和日期筛选器和/或photos.predicted_peaks 术语筛选器来提高搜索结果的相关性（见下文查询示例）。这有助于排除在徒步过程中看不到的相似山峰。

带有地理过滤器的 Elasticsearch 查询：

按图像搜索（图像到图像）：通过该功能，我们可以识别照片中的某座山，并在相册中查找该座山的其他图像。图像上传后，将由 SigLIP-2 图像编码器处理，生成图像矢量。然后在peaks_catalog.text_embed 字段上进行kNN 搜索，以确定最匹配的峰值名称。随后，根据这些匹配的山峰名称 生成 一个 文本向量 ，并在照片索引中进行另一次 kNN 搜索 ，以找到相应的照片。

Elasticsearch 查询：

第 1 步：找到匹配的山峰名称

第 2 步：在photos 索引上进行搜索，找到匹配的图片（与文本到图片搜索用例中的查询相同）：

流光 UI

为了将所有功能整合在一起，我们创建了一个简单的 Streamlit 用户界面，让我们可以同时执行两种搜索用例。左侧栏显示可滚动的峰值列表（从photos.predicted_peaks 中汇总），并带有复选框和小地图/地理过滤器。顶部有一个按姓名搜索框和一个从照片上传识别按钮。中心窗格采用响应式缩略图网格，显示 kNN 分数、预测峰值徽章和捕获时间。每张图片都有一个查看图片按钮，用于全分辨率预览。

通过上传图片进行搜索：我们会预测峰值，并从相册中找到匹配的峰值。

文本搜索从文本中查找相册中匹配的峰值

结论

我们能看看 阿玛-达布拉姆 的照片吗？变成了一个可运行的小型多模态搜索系统。我们采集了原始的徒步旅行照片，将其转化为SigLIP-2 嵌入，并使用Elasticsearch对向量进行快速的kNN处理，再加上简单的地理/时间过滤器，根据意义浮现出正确的图像。在此过程中，我们将两个索引的关注点分开：一个是混合原型的小peaks_catalog （用于识别），另一个是图像向量和 EXIF 的可扩展photos 索引（用于检索）。它实用、可复制、易扩展。

如果您想对其进行调整，有几项设置可供使用：

• 查询时间设置： k （您希望返回多少个邻居）和num_candidates （最终评分前的搜索范围）。这些设置将在此处的博客中讨论。

• 索引时间设置： m （图形连接性）和ef_construction （构建时间精度与内存）。对于查询，也可以尝试使用ef_search --更高通常意味着更高的召回率，但需要权衡一定的延迟。有关这些设置的更多详情，请参阅本博客。

展望未来，用于多模态和多语言搜索的本地模型/路由器即将登陆 Elastic生态系统，这将使图像/文本检索和混合排名功能更加强大。

如果你想亲自尝试一下：

• GitHub 代码库 ： https://github.com/navneet83/multimodal-mountain-peak-search

• Colab 快速入门 ：https://github.com/navneet83/multimodal-mountain-peak-search/blob/main/notebooks/multimodal_mountain_peak_search.ipynb

我们的旅程就此结束，是时候飞回去了。希望这对你有帮助，如果你改动（或改进）了它，我很乐意听听你的改动。

但是，当你能将这些定制的、数据感知工具带入你花费时间最多的环境中时，真正的奇迹就发生了。如果您的代码编辑器代理可以安全地访问组织的私人知识库，那会怎样？

这就是模型上下文协议（MCP）的作用所在。Elastic Agent Builder 内置 MCP 服务器，可访问平台中的工具。

为什么要使用 Elastic Agent Builder MCP 服务器？

人工智能代理的功能非常强大，但它们的知识通常仅限于它们接受过训练的数据以及它们可以在公共互联网上主动搜索的信息。他们不了解贵公司的内部设计文档、团队的特定部署运行手册或应用程序日志的独特结构。

我们面临的挑战是如何为人工智能助手提供其所需的专业背景。这正是 MCP 所要解决的问题。MCP 是一种开放标准，允许人工智能模型或代理发现和使用外部工具。

为了实现这一点，Elastic Agent Builder 通过内置的 MCP 服务器本机公开了您的自定义工具。这意味着您可以轻松地将任何与 MCP 兼容的客户端（如Cursor、VS Code 或Claude Desktop）与您使用 Elastic Agent Builder 创建的专门的数据感知工具连接起来。

何时使用 MCP（何时不使用）

Elastic Agent Builder 包含多种协议，可支持不同的集成模式。选择正确的人工智能工作流是建立有效人工智能工作流的关键。

• 使用 MCP通过专业工具来增强人工智能代理（如在Cursor或VS Code 中）。这是"自带工具" 方法，通过安全访问您的私人数据来增强您已经使用的助手。只有工具是通过 MCP 服务器公开的，Elastic 的代理是独立于 MCP 服务器的。

• 使用 A2A 协议，让您的完整自定义弹性代理与其他自主代理协作（如谷歌的双子座企业版）。这是针对代理对代理的委托，即每个代理都作为同行来解决问题。

• 在从头开始构建自定义应用程序时，使用 代理生成器应用程序接口（API）实现完全的编程控制。

对于希望在不离开集成开发环境的情况下从内部文档中获得答案的开发人员来说，MCP 是最合适的选择。

示例：在 Cursor 中使用代理生成器 MCP 服务器的自定义工具

让我们来看一个我每天都在使用的实际例子。首先，我将我们的内部工程文档抓取并编入一个名为elastic-dev-docs 的 Elasticsearch 索引。虽然我们可以使用 Agent Builder 中的通用内置工具，但我们将创建自己的自定义工具来查询这个特定的知识库。

定制工具的原因很简单：控制和精度。这种方法使我们能够直接针对elastic-dev-docs 索引运行快速语义查询。我们可以完全控制具体针对哪个索引以及如何检索数据。

现在，我们来看看如何在 Cursor 等人工智能驱动的代码编辑器中使用自定义知识库。

第 1 步：在 Agent Builder 中创建自定义知识库工具

首先，在 Agent Builder 中创建一个新工具。清晰而具体的工具描述非常重要，因为这是任何人工智能代理（无论是内部的弹性代理还是通过 MCP 连接的外部工具，如 Cursor）发现并为正确的任务选择工具的方式。

有力的描述应该是明确的。例如"在 elastic-dev-docs 索引上执行语义搜索，以查找内部工程文档、运行手册和发布程序"。

有了这些，就可以对工具进行配置，以便针对我们的特定索引执行语义搜索。一旦保存，就可以立即食用。

在连接到外部世界之前，您可以直接在用户界面中进行测试。只需单击 "测试"按钮，手动填写参数，模拟 LLM 的工作，然后检查结果，确认一切工作正常。

第 2 步：将光标连接到弹性 MCP 服务器

Elastic Agent Builder 可通过安全的 MCP 端点自动公开所有可用工具。您可以在 Kibana 的工具用户界面中找到唯一的服务器 URL。

要连接到 Cursor，我们只需将此 URL 添加到其配置文件中，同时添加一个用于身份验证的 Elastic API 密钥（了解如何创建 ES API 密钥）。我们使用 API 密钥进行授权，因为它能确保工具只在您授予的权限内执行，并尊重您的所有访问控制规则。

Cursor's~/.cursor/mcp.json 中的 MCP 配置如下所示：

保存配置后，你应该能在光标中看到 Elastic Agent Builder MCP 服务器工具。

第三步：提问！

建立连接后，Cursor 代理现在可以调用您的自定义工具来回答您的问题或指导代码生成过程。

让我们提出一个具体问题：

"从弹性搜索组织的工程内部文档中查找释放爬虫服务的步骤"

在幕后，神奇的事情发生了：

1. 光标代理决定如何以最佳方式回答您的问题，并决定调用 engineering_documentation_internal_search

2. 它通过自然语言查询调用该工具

3. 该工具根据elastic-dev-docs 索引执行语义搜索，并返回最相关的最新程序。

我们无需离开代码编辑器，就能根据内部文档得到准确、可信的答案。这种体验天衣无缝、功能强大。

轮到您建造

您现在已经了解了如何使用 Elastic Agent Builder 中的内置 MCP 服务器来扩展人工智能助手，使其能够安全地访问您的私人数据。将模型建立在自己的信息基础上是使其真正有用的关键。

概括地说，我们介绍了核心步骤：

• 根据需要选择合适的协议（MCP）。

• 构建自定义知识库工具

• 将该工具与 Cursor 等集成开发环境助手连接起来。

您的代理和工具不再需要与最有价值的环境脱节。希望本指南能帮助您创建更有效的数据感知工作流程。快乐建筑

在 Elastic Stack 中，有许多由 LLM 驱动的代理应用程序，例如 Agent Builder 中即将推出的 Elastic AI Agent（目前处于技术预览阶段）和 Attack Discovery （ 8.18 和 9.0+ 中的 GA ），还有更多正在开发中。在开发过程中，甚至在部署之后，回答这些问题都非常重要：

• 我们如何估算这些人工智能应用的响应质量？

• 如果我们做出改变，如何保证这种改变是真正的改进，而不会导致用户体验下降？

• 如何以可重复的方式轻松测试这些结果？

与传统的软件测试不同，评估生成式人工智能应用涉及统计方法、细致的定性审查以及对用户目标的深刻理解。

本文详细介绍了 Elastic 开发人员团队进行评估、确保部署前变更的质量以及监控系统性能的流程。我们的目标是确保每一项变革都有据可依，从而取得可信和可验证的成果。这一过程的一部分直接集成到了 Kibana 中，体现了我们对透明度的承诺，这也是我们开源精神的一部分。通过公开分享我们的部分评估数据和指标，我们力求促进社区信任，并为开发人工智能代理或使用我们产品的任何人提供一个清晰的框架。

产品示例

本文档中使用的方法是我们迭代和改进 "攻击发现 "和 "弹性人工智能代理 "等解决方案的基础。分别对两者进行简要介绍：

弹性安全的攻击发现

攻击发现使用 LLM 来识别和总结 Elastic 中的攻击序列。在给定的时间范围（默认 24 小时）内收到 Elastic Security 警报后，Attack Discovery 的代理工作流程会自动查找是否发生了攻击，以及重要信息，如哪台主机或用户受到了攻击，哪些警报促成了这一结论。

我们的目标是，基于 LLM 的解决方案所产生的输出结果至少与人类的输出结果一样好。

弹性人工智能代理

Elastic Agent Builder是我们的新平台，用于构建可利用我们所有搜索功能的上下文感知人工智能代理。它配备了Elastic AI Agent，这是一个预构建的通用代理，旨在通过对话式交互帮助用户理解数据并从中获得答案。

该代理通过自动识别 Elasticsearch 或连接的知识库中的相关信息，并利用一套预建工具与之交互，来实现这一目标。这使得 Elastic AI Agent 能够响应各种用户查询，从单个文档的简单 Q&A 到需要在多个索引中进行聚合和单步或多步搜索的复杂请求。

通过实验衡量改进

就人工智能代理而言，实验是对系统进行的结构化、可测试的更改，旨在提高系统在明确定义的维度（如有用性、正确性、延迟）上的性能。我们的目标是明确回答"如果我们合并这一改动，能否保证它是真正的改进，不会降低用户体验？

我们进行的大多数实验通常包括

• 假设：一个具体的、可证伪的主张。例如"增加对攻击发现工具的访问权限，可提高安全相关查询的正确性"。

• 成功标准：明确界定 "成功 "含义的阈值。例如"在安全数据集上，正确性得分提高了 +5% ，其他方面没有降低"。

• 评估计划：我们如何衡量成功（衡量标准、数据集、比较方法）

成功的实验是一个系统的探究过程。从细微的提示调整到重大的架构转变，每一项改变都要遵循这七个步骤，以确保结果是有意义和可操作的：

• 第 1 步：确定问题

• 第 2 步：确定衡量标准

• 步骤 3：提出明确的假设

• 步骤 4：准备评估数据集

• 步骤 5：运行实验

• 第 6 步：分析结果 + 反复试验

• 第 7 步：做出决定并记录在案

图 1 举例说明了这些步骤。下面的小节将对每个步骤进行说明，我们将在接下来的文件中详细介绍每个步骤的技术细节。

使用真实的 Elastic 示例逐步讲解

第 1 步：确定问题

这一变化究竟要解决什么问题？

攻击发现示例：摘要有时不完整，或者良性活动被错误地标记为攻击（误报）。

弹性人工智能代理示例：代理的工具选择，尤其是分析查询工具的选择，不够理想且不一致，经常导致选择错误的工具。这反过来又增加了令牌成本和延迟。

第 2 步：确定衡量标准

使问题可测量，以便我们能将变化与当前状态进行比较。

常用指标包括精确度和召回率、语义相似性、事实性等。根据不同的使用情况，我们使用代码检查来计算指标，例如匹配警报 ID 或正确检索的 URL，或者使用 LLM-as-judge 等技术来计算更自由的答案。

以下是实验中使用的一些指标示例（并非详尽无遗）：

Attack Discovery

公制

描述

精确度& 召回率

在实际输出和预期输出之间匹配警报 ID，以衡量检测准确性。

相似性

使用 BERTScore 比较回复文本的语义相似性。

事实性

是否存在关键的 IOC（妥协指标）？是否正确反映了 MITRE 战术（行业攻击分类）？

攻击链一致性

比较发现的次数，检查是否存在多报或少报攻击事件的情况。

弹性人工智能代理

公制

描述

精确度& 召回率

将代理为回答用户查询而检索的文档/信息与回答查询所需的实际信息或文档进行匹配，以衡量信息检索的准确性。

事实性

是否存在回答用户查询所需的关键事实？程序性查询的事实顺序是否正确？

回应相关性

回复是否包含与用户查询无关的信息？

答复完整性

回复是否回答了用户查询的所有部分？回复是否包含地面实况中的所有信息？

ES|QL 验证

生成的 ES|QL 语法正确吗？它在功能上是否与地面实况 ES|QL 相同？

步骤 3：提出明确的假设

利用问题和上文定义的衡量标准，制定明确的成功标准。

弹性人工智能代理示例：

1. 对 relevance_search 和 nl_search 工具的说明进行修改，以明确定义其具体功能和用例。

2. 我们预测，我们的 工具调用准确率 将 提高 25% 。

3. 我们将通过确保不对其他指标产生负面影响来验证这是否是一个净积极因素，例如事实性和完整性。

4. 我们相信这将行之有效，因为精确的工具描述将帮助代理针对不同查询类型更准确地选择和应用最合适的搜索工具，从而减少错误应用，提高整体搜索效率。

步骤 4：准备评估数据集

为了衡量系统的性能，我们使用了能捕捉真实世界场景的数据集。

根据我们所进行的评估类型，我们可能需要不同类型的数据格式，例如反馈给 LLM 的原始数据（例如："......"）。攻击发现的攻击场景）和预期产出。如果应用程序是聊天机器人，那么输入可能是用户查询，输出可能是聊天机器人的正确回复、本应检索到的正确链接等。

攻击发现示例

10 种新颖的攻击情景

8 集 Oh My Malware (ohmymalware.com)

4 种多重攻击情景（通过组合前两类攻击而创建）

3 种良性情景

弹性人工智能代理评估数据集示例（Kibana 数据集链接）：

14 使用开放源码数据集模拟 KB 中多个来源的指数。

5 种查询类型（分析型、文本检索型、混合型...）

7 查询意图类型（程序、事实--分类、调查......）

步骤 5：运行实验

执行实验，根据评估数据集生成现有代理和修改版代理的响应。计算事实性等指标（见第 2 步）。

我们根据步骤 2 中要求的指标，将各种评估混合在一起：

• 基于规则的评估（如使用 Python/TypeScript 检查 .json 是否有效）。

• 法学硕士即法官（询问另一位法学硕士某项答复是否与源文件的事实相符）

• 人在回路中审查，进行细微差别质量检查

第 6 步：分析结果 + 反复试验

现在我们有了衡量标准，可以对结果进行分析。即使结果符合步骤 3 中定义的成功标准，在将变更合并到生产之前，我们仍要进行人工审核；如果结果不符合标准，则要进行迭代并修复问题，然后在新变更上运行评估。

我们预计，在合并之前，需要反复几次才能找到最佳修改。与在推送提交之前运行本地软件测试类似，离线评估也可与本地变更或多个建议变更一起运行。自动保存实验结果、综合分数和可视化效果，简化分析过程，非常有用。

第 7 步：做出决定并记录在案

根据决策框架和验收标准，决定是否合并变更，并将实验记录在案。决策是多方面的，可以考虑评估数据集以外的因素，如检查其他数据集的回归情况，或权衡拟议变更的成本效益。

举例说明：在测试和比较几次迭代后，选择得分最高的变更，发送给产品经理和其他相关利益者审批。附上前几个步骤的结果，以帮助指导决策。有关攻击发现方面的更多示例，请参阅《Elastic Security 的生成式人工智能功能幕后》。

结论

在这篇博客中，我们介绍了实验工作流程的端到端过程，说明了我们如何在向 Elastic 用户发布代理系统变更之前对其进行评估和测试。我们还提供了一些在 Elastic 中改进基于代理的工作流的示例。在随后的博文中，我们将详细介绍不同步骤的细节，例如如何创建一个好的数据集、如何设计可靠的度量标准，以及在涉及多个度量标准时如何做出决策。

但是，如果您想将自定义代理与您已经依赖的应用程序和生产力工具一起使用，该怎么办？

这就是代理对代理（A2A）协议的作用所在。A2A 是互操作性的开放标准，允许来自不同平台的代理进行通信和协作。我们已将其直接内置到弹性代理生成器中。

今天，我们将向您展示如何将您创建的自定义代理与其他服务（特别是Gemini Enterprise ，前身为 Agentspace）进行交互。

开放标准的力量：A2A 为何重要

在博文 "你的第一个弹性代理"中，我们展示了如何构建自定义代理，例如可安全访问市场数据的财务助理代理。但是，如果你不能在其他环境（如双子座企业版）中使用其洞察力，而又不重建你的工作，那么它的价值就会受到限制。

这种互操作性的挑战正是阻碍人工智能发展的原因。代理需要一种跨平台交流的通用语言，这正是 A2A 协议的作用所在。它提供了一个标准通信层，不仅可以让您与代理直接互动，还能开启未来，让整个组织的专业代理都能协作并分享见解。

为了实现这一点，Elastic Agent Builder 通过两个标准端点为所有代理提供 A2A 协议本机支持：

1. Agent Card 端点 (GET {your-kibana-url}/api/agent_builder/a2a/{agentId}.json )- 这是您的自定义代理名片。它向任何 A2A 兼容服务提供有关代理的元数据（名称、描述、功能等）。

2. A2A 协议端点 (POST {your-kibana-url}/api/agent_builder/a2a/{agentId} ) - 这是通信通道。其他代理在此发送请求，您的代理处理请求并返回响应，所有这些都遵循A2A 协议规范。

使用 A2A 检查员测试您的代理

在将我们的代理连接到生产系统之前，最好检查一下它的通信是否正确。最简单的方法是使用A2A 检查器，这是一款专门用于测试和调试 A2A 集成的工具。

检查器的运行非常简单。您可以克隆a2a-inspector软件源，然后按照 README 说明运行应用程序。启动后，用户界面默认在http://localhost:5001/ 上可用。

要将 A2A 检查员与您的代理联系起来，您需要提供两条关键信息：

• 代理卡 URL：这是描述代理的端点。对于上一个职位中的财务助理代理而言，这个 URL 将是{your-kibana-url}/api/agent_builder/a2a/financial_assistant.json 。

• 验证头：我们将使用标准 API 密钥进行身份验证。

在检查员用户界面输入这些详细信息后，您就可以立即连接并开始与您的代理聊天。

这一简单的验证让我们确信，我们的代理已正确配置并准备好进行下一步操作。

开始直播您在双子座企业中的定制代理

现在是激动人心的部分：在 Gemini Enterprise（前身为 Agentspace）中启用我们的定制财务顾问代理。该集成由 Elastic AI Agent 提供支持 ，它可在谷歌云市场上购买 。

连接后，Gemini Enterprise 使用 A2A 协议与您的代理直接通信。这就是互操作性的真正威力所在：用户现在可以访问来自自定义 Elasticsearch 代理的深度数据驱动洞察，而无需离开他们熟悉的环境。你可以在代理列表中看到你的自定义弹性代理：

想象一下，双子座企业的用户会问

"我担心市场情绪。您能告诉我哪些客户最容易受到坏消息的影响吗？"

在幕后，Gemini Enterprise 通过 A2A 协议将此查询路由到您的自定义弹性代理。然后，您的代理会使用其专业工具查询您的数据、制定答案并将其发送回来。对于最终用户来说，这种体验是无缝的。

而且还不止于此！使用弹性代理获取的答案现在可以用作下一个问题的上下文，这些问题可能会触发不同的专门代理（例如您的投资平台代理，以调整对上市公司的投资）。无需离开搜索栏。

通过在具有 A2A 功能的 Gemini Enterprise 上部署弹性代理，您可以统一访问、协调和工作流，通过提供用户与其数据和工具对话的单一用户界面，消除人工智能、搜索和企业系统之间的摩擦--所有这些都在上下文中进行。对用户来说，这意味着更少的工具切换和更直观、更有能力的人工智能助手。对组织而言，这意味着协调一致的管理、可扩展性和内置的互操作性。

轮到您建造

您现在拥有了让您的弹性代理随时随地可用的工具。通过利用开放式 A2A 协议，您可以扩展自定义数据感知代理的覆盖范围。

在本篇文章中，我们将向您介绍关键步骤：

• 通过 A2A 代理卡和协议端点公开代理。

• 测试与 A2A 检查员的连接。

• 将代理实时集成到外部服务中，如 Google 的 Gemini Enterprise。

您的代理商不再需要与世隔绝。我们迫不及待地想看到你们创建的强大的互联系统。快乐建筑

最简单的入门方法是在谷歌云市场上进行 Elastic Cloud 免费试用

想象一下，一位财务经理需要在与客户会面之前加快速度。现在，他们只需向定制的代理直接提问，而无需手动挖掘新闻源和交叉参考投资组合仪表板。这就是"聊天优先" 方法的好处。经理与他们的数据直接对话，询问诸如"ACME 公司的最新消息是什么，它对我客户的持股有何影响？"并在几秒钟内得到综合的专家答复。

今天，我们正在打造一个金融专家，其应用就像您的数据一样多种多样。同样的能力可以造就一名网络安全分析师来寻找威胁，造就一名现场可靠性工程师来诊断故障，或者造就一名营销经理来优化营销活动。无论在哪个领域，核心任务都是一样的：将您的数据转化为您可以与之交谈的专家。

步骤 0：我们的数据集

我们当前的数据集是一个基于金融的合成数据集，包含金融账户、资产头寸、新闻和财务报告。虽然它是合成的，但复制了真实金融数据集的简化版本。

financial_accounts:具有风险特征的客户组合

financial_holdings:有购买记录的股票/ETF/债券仓位

financial_asset_details:股票/ETF/债券的详细信息

financial_news:人工智能生成的带有情感分析的市场文章

financial_reports:公司收益和分析师报告

您可以根据此处的随附笔记本自行加载该数据集。

步骤 1：基础--作为 ES|QL 的业务逻辑

每一项人工智能技能都以坚实的逻辑为起点。对于我们的财务经理代理，我们需要教它如何回答一个常见问题："我担心市场情绪。你能告诉我哪些客户最容易受到坏消息的影响吗？这个问题超出了简单的搜索范围。这要求我们将市场情绪与客户投资组合联系起来。

我们需要找到负面文章中提到的资产，识别持有这些资产的每一位客户，计算其风险敞口的当前市值，然后对结果进行排序，优先考虑风险最高的客户。这种复杂的多连接分析是我们先进的 ES|QL 工具的完美工作。

下面是我们要使用的完整查询。它看起来令人印象深刻，但概念却简单明了。

分解：接合点和护栏

在这个查询中，有两个重要的概念使代理生成器发挥作用。

1.查找联接

多年来，Elasticsearch 最受欢迎的功能之一就是根据一个共同的键来连接来自不同索引的数据。有了 ES|QL，LOOKUP JOIN 。

在我们的新查询中，我们会执行一连串的三个LOOKUP JOIN's：首先将负面新闻与资产详细信息连接起来，然后将这些资产与客户持有的资产连接起来，最后再与客户的账户信息连接起来。这样，在一次高效的查询中，就能从四个不同的索引中获得极其丰富的结果。这意味着我们可以将不同的数据集结合起来，创建一个具有洞察力的单一答案，而无需事先将所有数据反规范化为一个巨大的索引。

2.作为 LLM 护栏的参数

您会发现查询使用了?time_duration 。这不仅是一个变量，还是人工智能的护栏。虽然大型语言模型 (LLM) 是生成查询的好帮手，但让它们自由支配数据可能会导致查询效率低下甚至错误。

通过创建参数化查询，我们迫使 LLM 按照人类专家已经定义的经过测试、高效且正确的业务逻辑工作。这与多年来开发人员使用搜索模板安全地向应用程序公开查询功能的方式类似。代理可以解释用户的请求，如"this week" 来填充time_duration 参数，但它必须使用我们的查询结构来获取答案。这使我们在灵活性和控制性之间取得了完美的平衡。

最终，这种查询可以让了解数据的专家将其知识封装到一个工具中。其他人和人工智能代理只需提供一个参数，就能使用该工具获得相关结果，而无需了解底层的复杂性。

步骤 2：技能--将查询转化为可重复使用的工具

在我们将 ES|QL 查询注册为工具之前，它只是一个文本。在代理生成器中，工具不仅仅是一个已保存的查询；它还是一个"技能" ，人工智能代理可以理解并选择使用。神奇之处在于我们提供的自然语言描述。该描述是连接用户问题和底层查询逻辑的桥梁。让我们注册一下刚刚创建的查询。

用户界面路径

在 Kibana 中创建工具的过程非常简单。

1.导航至代理

• 单击 " 工具 "或 "管理工具"，然后单击 "新建工具"按钮。

2.在表格中填写以下详细信息：

• 工具 ID： find_client_exposure_to_negative_news

i.这是工具的唯一 ID

• 描述 "查找客户投资组合受负面新闻影响的情况。该工具会扫描最近的新闻和报道，查找负面情绪，识别相关资产，并找到持有该资产的所有客户。它会返回一个按头寸当前市值排序的列表，以突出潜在风险最高的头寸。"

i.法律硕士就是通过阅读这些内容来判断这个工具是否适合这项工作。

• 标签：retrieval 和 risk-analysis

标签用于帮助对多个工具进行分组

• 配置：粘贴步骤 1 中的完整 ES|QL 查询

i.这是代理将使用的搜索

3.单击从查询中推断参数。用户界面会自动查找?time_duration ，并将其列在下面。为每项功能添加一个简单的说明，以帮助代理（和其他用户）了解其用途。

• time_duration:搜索负面新闻的时间范围。格式为"X 小时" 默认为 8760 小时

4.测试一下！

• 单击保存& 测试。

• 您将看到一个新的快捷方式，可以在此测试查询，以确保其工作符合预期。

i.在time_duration 中输入所需的范围，这里我们使用 "8760 小时"。

• 点击 "提交"，如果一切顺利，您将看到一个 JSON 响应。要确保它按预期运行，请向下滚动并查看values 对象。这就是返回实际匹配文档的地方。

5.点击右上角的 "X "关闭测试窗口。现在，您的新工具将出现在列表中，随时可以分配给代理。

应用程序接口路径

对于喜欢自动化或需要以编程方式管理工具的开发人员来说，只需调用一个 API 就能实现同样的效果。只需向带有工具定义的/api/agent_builder/tools 端点发送POST 请求即可。

步骤 3：大脑--创建您的定制代理

我们开发了一种可重复使用的技能（工具）。现在，我们需要创建代理，即实际使用它的角色。代理是一个 LLM 的组合，是你授予它访问权限的一套特定工具，最重要的是，它还包含一套自定义指令，作为它的章程，定义了它的个性、规则和目的。

提示的艺术

要创建一个可靠的专业代理，最重要的一点就是要及时。一套精心设计的指令是普通聊天机器人与专注、专业的助手之间的区别所在。在这里，你可以设置防护栏、定义输出并赋予代理任务。

对于Financial Manager 代理，我们将使用以下提示。

让我们来分析一下为什么这个提示如此有效：

• 它定义了一个成熟的角色： 第一句话立即将代理人定位为"专业的数据智能助理，" 定下了专业、干练的基调。

• 它提供了一个推理框架： 通过告诉代理"Understand（理解）、Plan（计划）、Execute（执行）和 Synthesize（综合），" ，我们给了它一个标准的操作程序。这提高了它处理复杂、多步骤问题的能力。

• 它促进了互动对话： "提出澄清性问题的指令" 使代理更加稳健。这将最大限度地减少对模棱两可的请求做出不正确的假设，从而获得更准确的答复。

用户界面路径

1.导航至代理。

• 单击 " 工具 "或 "管理工具"，然后单击 "新建工具"按钮。

2.填写基本信息：

• 代理编号： financial_assistant.

• 说明 复制上面的提示。

• 标签 Finance.

• 显示名称： Financial Assistant 。

• 显示说明： An assistant for analyzing and understanding your financial data 。

3.回到顶部，点击 "工具"。

• 勾选find_client_exposure_to_negative_news 工具旁边的复选框。

4.单击保存。

应用程序接口路径

您可以通过POST 请求/api/agent_builder/agents 端点来创建完全相同的代理。请求正文包含所有相同的信息：ID、名称、描述、全套指令以及允许代理使用的工具列表。

步骤 4：回报--进行对话

我们已将业务逻辑封装在一个工具和一个"大脑" 中，准备在我们的 Agent 中使用它。是时候见证这一切了。现在，我们可以使用专门的代理与数据聊天了。

用户界面路径

1. 导航至 Kibana 中的代理 。

2. 使用聊天窗口右下角的下拉菜单，从默认的Elastic AI 代理切换到我们新创建的财务助理 代理。

3. 请提出一个问题，以便代理人使用我们的专业工具：

   1. 我担心市场情绪。您能告诉我哪些客户最容易受到坏消息的影响吗？

片刻之后，代理将返回一个格式完美、内容完整的答案。由于法律硕士的性质，您的答案格式可能会略有不同，但这次运行中，代理返回的答案是一样的：

刚刚发生了什么？代理人的推理

该特工并不只是"知道" 答案。它以选择最佳工具为中心，执行了一个多步骤计划。下面我们来看看它的思考过程：

• 识别意图：它将您问题中的关键字，如"风险" 和"负面新闻、" 与find_client_exposure_to_negative_news 工具的描述相匹配。

• 执行计划：它从您的请求中提取了时间范围，并对该专业工具进行了一次调用。

• 委托工作：然后，该工具就能完成所有繁重的工作：链式连接、值计算和排序。

• 合成结果：最后，代理按照提示规则，将来自工具的原始数据格式化为清晰、人类可读的摘要。

如果我们拓展思维，看到更多细节，我们就不只是猜测了。

应用程序接口路径

您也可以通过编程来启动同样的对话。只需将输入问题发送到converse API 端点，确保指定我们的financial_manager 的agent_id 。

致开发人员：与应用程序接口集成

虽然 Kibana UI 为构建和管理代理提供了美妙而直观的体验，但您今天所看到的一切也都可以通过编程来实现。代理生成器基于一套应用程序接口（API）构建，允许您将此功能直接集成到自己的应用程序、CI/CD 管道或自动化脚本中。

您将使用的三个核心端点是

• /api/agent_builder/tools:创建、列出和管理可重复使用的技能的终端。

• /api/agent_builder/agents:角色：定义代理角色的终端，包括重要的说明和工具分配。

• /api/agent_builder/converse:与代理互动、开始对话和获取答案的终端。

有关使用这些应用程序接口执行本教程中每一步的完整实践演示，请查看我们 GitHub 软件仓库中的配套Jupyter Notebook 。

总结：轮到你来建设

我们首先使用 ES|QL 查询，并将其转换为可重复使用的技能。然后，我们建立了一个专门的人工智能代理，赋予它明确的任务和规则，并赋予它这种技能。它是一个复杂的助手，能够理解复杂的问题，并执行多步骤分析，提供精确的数据驱动型答案。

这一工作流程是 Elastic 中新的代理生成器的核心。它的设计足够简单，非技术用户可以通过用户界面创建代理，但又足够细致，开发人员可以在我们的应用程序接口基础上构建定制的人工智能驱动应用程序。最重要的是，它可以让您安全可靠地将 LLM 连接到自己的数据，由您定义的专家逻辑进行管理，并与您的数据进行聊天。

准备好使用代理与您的数据聊天了吗？

巩固所学知识的最好方法就是动手实践。在我们的免费互动实践研讨会上，尝试我们今天讨论的所有内容。您将在专门的沙盒环境中经历整个流程以及更多。

在今后的博客中，我们将向您展示如何使用独立应用程序与我们的Financial Assistant 代理交互，并深入探讨使这一切成为可能的模型上下文协议 (MCP)。在另一篇博客中，我们将讨论 Agent Builder 对开发中的 Agent2Agent（或 A2A）协议的支持。

敬请期待，祝您建筑愉快！

代理生成器：构建数据驱动型人工智能代理的基础

人工智能代理的承诺很简单：给它一个目标，它就能完成工作。但对于开发商来说，现实却是一系列复杂的挑战。首先，代理的能力取决于其对环境的感知以及为实现用户目标而提供的工具。那么，如何从纷繁复杂的企业数据中提供正确的上下文是一项巨大的挑战。最后，所有这一切都必须由一个可靠的推理循环来协调，该循环可以进行规划、执行和学习。

为了解决这个问题，开发人员需要从头开始构建一个复杂而脆弱的堆栈。如今的代理架构需要将多个不同的部分拼接在一起：一个 LLM、一个向量数据库、一个元数据存储、用于日志记录和跟踪的独立系统，以及一些评估它们是否都能正常工作的方法。这不仅复杂，而且成本高昂、容易出错，并且难以建立用户所需的高质量、值得信赖的人工智能系统。

因此，我们想让它变得更简单。为此，我们的方法是将有效的上下文驱动型代理的重要部分直接集成到 Elasticsearch 的核心中，并提供一套名为Elastic AI Agent Builder 的新功能。这一新层提供了一个框架，其中包含创建由 Elasticsearch 支持的人工智能代理所需的所有基本构件：一套开放的基元、基于标准的协议和对数据的安全访问--因此您可以根据真实世界的数据和要求构建代理系统：

提供人工智能体验：这是终极目标。以我们的搜索人工智能平台和您的数据为基础，您可以构建任何类型的生成式人工智能应用程序：从定制聊天界面到与 LangChain 等代理框架或 Salesforce 等业务应用程序的集成。

由 Agents& 工具提供支持：在平台之上，我们提供了一个简洁的抽象层。您可以直接与代理和工具互动，并根据具体需求进行定制。您还可以通过强大的应用程序接口和开放标准（如 MCP 和 A2A）访问平台的功能。

由搜索人工智能平台支持：这是我们集成了各种组件的核心引擎。先进的矢量数据库、代理逻辑、查询结构、安全功能、评估跟踪都在这里，由 Elastic 管理和优化。

释放数据的力量：任何优秀代理商的基础都是优秀的数据。我们的平台首先能够摄取或联合访问您的所有企业数据

平台中的代理建设

Agent Builder 集成到搜索人工智能平台中，为代理开发提供了一个完整的框架。它建立在五个关键支柱之上，每个支柱都旨在解决构建和部署生产级人工智能系统的一个关键方面。让我们来分析一下，代理如何定义目标，工具如何提供功能，开放标准如何确保互操作性，评估如何提供透明度，安全如何提供信任。

代理商

代理是 Elasticsearch 这一新层中最高级别的构建模块。代理定义了要实现的目标、可用于执行的工具集以及可操作的数据源。代理并不局限于对话式交互，它们还可以支持完整的工作流、任务自动化或面向用户的体验。

当一项查询被提交给代理机构时，它遵循一个结构化的循环：

1. 解释您的意见和目标

2. 选择正确的执行工具和参数

3. 工具响应的原因

4. 决定是返回结果还是继续进一步调用工具

Elastic 负责这一循环的协调、上下文和执行。开发人员专注于定义代理应该做什么：目标、工具和数据，而系统则管理如何进行推理和执行工作流程。

默认代理

我们在该平台上构建的第一个代理是 Kibana 中的原生会话代理，让您能够立即与数据进行交互。它在提供即用体验的同时，还具有完全的可扩展性，无需额外配置即可立即开始与数据交互。

您可以直接在 Kibana 中通过新的聊天用户体验或通过 API 与此体验进行交互。

通过 API 查询默认代理只需一次调用：

由于会话是有状态的，因此您可以使用会话 ID 继续与代理交互，或检索完整的会话历史记录：

海关代理

开发人员还可以通过简单的应用程序接口创建自己的定制代理。代理封装了指令、工具和数据访问，创建了量身定制的推理引擎。

创建自定义代理只需调用一次应用程序接口。下面的示例显示了一个例子，"配置 "字段包含所有关键细节，如说明或可用工具：

一旦创建，就可以直接查询代理：

这种方法将代理从一个需要从头开始构建的复杂系统转变为一个简单、声明式的业务逻辑单元，使您能够更快地交付智能自动化。

如需深入了解如何从头开始构建专门的代理，请参阅我们的详细分步指南：您的第一个弹性代理：从单一查询到人工智能驱动的聊天。

工具

如果说代理确定了要完成的任务，那么工具则确定了如何完成。

工具为代理执行和检索信息或执行操作暴露了特定的弹性核心功能。工具可以包括获取索引或获取映射等核心功能，也可以包括从自然语言到 ES|QL 等更高级的功能。

Elasticsearch 随附一套针对常见需求进行了优化的默认工具。但真正的灵活性来自于自己的创造。通过定义工具，您可以决定将哪些查询、索引和字段通过 ES|QL 暴露给代理，从而对速度、准确性和安全性进行精确控制。

注册新工具也很简单，只需调用一次应用程序接口。您可以创建一个工具，利用我们的ES|QL（Elasticsearch 查询语言）查找特定金融资产的相关新闻：

注册后，您就可以将新工具分配给您的自定义代理，为他们提供一套经过精心设计的能力，让他们在合适的时候进行推理和调用。

我们提供了一个平台，可根据您的特定需求创建定制工具，例如使用 ES|QL，将代理从通用代理转变为特定领域的专家，立足于您独特的数据和业务领域。

开放标准和互操作性

Elasticsearch 代理和工具通过开放式标准 API 公开，因此很容易作为基础模块集成到更广泛的代理框架生态系统中。我们的方法很简单：没有黑盒子。我们希望您能够利用 Elastic 在搜索方面的核心优势，并将其与互补功能和其他代理系统搭配使用。

为了实现这一点，我们正在通过应用程序接口、新兴协议和开放标准公开我们的能力。

模型上下文协议（MCP）

模型上下文协议（MCP）正迅速成为跨系统连接工具的开放标准。通过支持 MCP，Elasticsearch 可以将对话式人工智能与您的数据库、索引和外部 API 相连接。通过 Elastic Stack 内置的远程 MCP 服务器，任何兼容 MCP 的客户端都可以访问 Elastic 的工具，并将其用作大型代理工作流程的构建模块。

这不是一条单行道。您还可以从外部 MCP 服务器导入工具，使其在 Elasticsearch 中可用。不久之后，MCP 服务器将可能适用于几乎所有功能，而且比我们自己创建的任何功能都要全面得多。Elastic 提供大规模的搜索和检索功能，您可以将其与其他平台的专业功能相结合，构建有效的代理。

代理对代理（A2A）

我们还在努力提供代理对代理 (A2A) 支持。MCP 是连接工具，而 A2A 则是连接代理。有了 A2A 服务器，您构建的 Elastic 代理就能与其他系统的代理直接对话：共享上下文、委派任务和协调工作流。

将其视为推理层的互操作性。您的弹性代理可以处理搜索和检索，然后将任务交给专门的支持或 IT 代理，并无缝地返回结果。这样就形成了一个由合作代理组成的生态系统，每个代理都在做自己最擅长的事情。

最终，采用 MCP 和 A2A 加强了我们对 Elasticsearch 作为一流公民角色的承诺，确保在更广泛的代理生态系统中实现开放式集成。

追踪和评估

随着搜索与代理的整合，有效评估的挑战变得至关重要。要在真实的企业环境中自信地部署代理，就必须确保代理不仅准确，而且高效可靠。如何衡量性能、诊断不良响应或改进基线？一切从可见度开始。

因此，我们从一开始就设计了透明的代理 API。考虑一下这个简单的代理互动：

回复不仅包括最终答案，还包括完整的执行跟踪，详细说明代理选择了哪些工具、使用了哪些参数以及每一步的结果。

全面的跟踪和日志记录对持续改进循环至关重要，不久之后，您就可以直接在 Elasticsearch 中存储和查看这些代理跟踪。更妙的是，这些跟踪记录是基于 OpenTelemetry 协议构建的，确保了它们的标准化和可移植性，以便与您选择的可观测性平台集成。

这种详细程度是真正持续改进循环的基础。它使您能够建立一套全面的测试、调试故障、识别失败模式以防止回归，并捕捉成功模式以微调性能。归根结底，这种数据驱动的方法是将有前途的原型转化为生产级、值得信赖的人工智能系统的关键。

安全性

随着代理和工具的功能越来越强大，安全性不再是可有可无的，而是基础性的。要公开应用程序接口、自动执行任务和工作流程，就必须信任企业系统。特别是当代理开始自动执行更多的工作流程时，确保这些流程安全并满足企业要求的能力就显得尤为重要。

上述功能都继承了 Elastic 目前已有的控制功能，包括针对 API 调用和 API 密钥管理的基于角色的访问控制 (RBAC)。我们还将同样的控制扩展到 MCP 等新协议。这意味着支持 OAuth 等标准，以及插入自定义身份验证机制的能力。

我们的目标是让您灵活地尝试使用代理和工具，同时保持组织所需的安全性、合规性和管理水平。

下一步行动

我们不仅要增加功能，还要扩展 Elasticsearch 的代理上下文工程。我们计划在这些原则的基础上继续发展：

1.致力于开放源码& 标准

我们致力于开放源代码和开放标准，确保这些功能与外部代理框架保持互操作性。您始终能够在生态系统中连接、扩展和组成代理，同时将数据和工作流程置于您的控制之下。

2.背景的价值

人工智能代理的背景是其最大的资产。在代理执行搜索和工作流操作时管理上下文是一项极具挑战性的任务。我们正在利用 Elastic 的核心优势来解决上下文工程问题，确保您的代理始终可以获得最相关的信息。

3.关注代理数据流

展望未来，代理将成为越来越大的数据源，包括代理的输出（生成的文档、报告、可视化）和代理的执行轨迹（其思维、工具调用、内存/上下文）。Elastic 非常适合处理此类数据，我们正在研究如何利用这些数据进行分析、评估和自动改进。

4.设计的安保和安全

人工智能代理带来了全新的安全保障挑战。Elastic 一直是安全解决方案的领导者，我们将继续构建企业级防护、访问控制和"零信任" 原则。

5.嵌入平台

构建人工智能代理的功能已嵌入 Elasticsearch 平台。这意味着平台级功能，如跟踪、评估、可视化和分析，都适用于代理。希望根据代理执行情况开发仪表板--这是内置功能。希望通过情感分析来评估人工智能代理的性能--该平台可以实现这一点。这样就能围绕人工智能体验构建一个完整的生命周期。

Elastic 的目标是为您提供建立对话式人工智能和自动化工作流程的接口，这些接口完全集成、可扩展并以您的数据为基础。更多技术细节和进展情况将很快与大家分享。

代理生成器 "现已推出私人预览版。与我们联系，申请访问。有问题或反馈？在我们的Slack 工作区或讨论区与我们的开发人员社区联系。

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

步骤：

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

2. 准备数据

3. LLM 配置

4. 应用功能

后台& 应用程序工作流程

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

我们尝试了几种型号：

• 双子座 2.5 pro

• GPT o3 / o4-mini-high / 4.1

• 克劳德 4 号十四行诗

• Grok 3

• Deepseek (Deepthink R1)

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

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

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

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

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

申请工作流程如下：

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

准备工作

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

1. Python 3.8 或更高版本

2. VenvPython 环境

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

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

准备数据

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

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

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

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

LLM 配置

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

我们安装依赖项：

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

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

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

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

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

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

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

让我们来分析一下提示：

部门

原因

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

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

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

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

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

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

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

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

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

处理 LLM 答复

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

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

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

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

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

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

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

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

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

最终结果将是这样的

结论

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

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

在本篇文章中，我们将探讨如何使用Mastra和一个轻量级 JavaScript 网络应用程序来构建一个代理 RAG 助手，并与其进行交互。通过将该代理连接到 Elasticsearch，我们可以让它访问结构化的球员数据，并能够运行实时统计汇总，从而为您提供基于球员统计数据的推荐。请访问 GitHub软件源，了解如何克隆和运行应用程序；README提供了相关说明。

下面是全部组装好后的样子：

注：本博文以 "使用 AI SDK 和 Elastic 构建 AI 代理"为基础。如果您是第一次接触人工智能代理及其用途，请从这里开始。

结构概述

该系统的核心是一个大型语言模型（LLM），它充当了代理的推理引擎（大脑）。它能解释用户输入，决定调用哪些工具，并协调生成相关响应所需的步骤。

代理本身由 JavaScript 生态系统中的代理框架 Mastra 搭建脚手架。Mastra 将 LLM 与后端基础设施封装在一起，将其作为 API 端点公开，并提供了一个用于定义工具、系统提示和代理行为的接口。

在前端，我们使用Vite快速搭建了一个 React 网络应用程序，它提供了一个聊天界面，用于向代理发送查询并接收其回复。

最后，我们还有 Elasticsearch，它存储了代理可以查询和汇总的球员统计数据和对阵数据。

背景

让我们来回顾一下几个基本概念：

什么是代理 RAG？

人工智能代理可以与其他系统互动，独立运行，并根据其定义的参数执行操作。代理式 RAG 将人工智能代理的自主性与检索增强生成的原则相结合，使 LLM 能够选择调用哪些工具和使用哪些数据作为上下文来生成响应。点击此处了解有关 RAG 的更多信息。

选择框架，为什么要超越 AI-SDK？

目前有许多人工智能代理框架，你可能听说过CrewAI、AutoGen和LangGraph 等比较流行的框架。这些框架大多有一套共同的功能，包括支持不同的模型、工具使用和内存管理。

下面是哈里森-蔡斯（LangChain 首席执行官）的框架比较表。

让我对 Mastra 产生兴趣的是，它是一个 JavaScript 优先框架，专为全栈开发人员设计，可以轻松地将代理集成到他们的生态系统中。Vercel 的 AI-SDK 也能实现大部分功能，但 Mastra 的优势在于当项目包含更复杂的代理工作流程时。Mastra 增强了 AI-SDK 设置的基本模式，在本项目中，我们将同时使用它们。

框架和模型选择考虑因素

虽然这些框架可以帮助您快速构建人工智能代理，但也有一些缺点需要考虑。例如，在使用人工智能代理或任何抽象层之外的其他框架时，你会失去一些控制权。如果 LLM 没有正确使用工具，或者做了一些你不希望它做的事情，抽象化就会增加调试难度。不过，在我看来，这种折衷还是值得的，尤其是因为这些框架的发展势头越来越好，而且还在不断迭代。

同样，这些框架与模型无关，这意味着您可以即插即用不同的模型，但请记住，模型在不同的数据集上训练出来的结果是不同的，反过来，它们给出的响应也是不同的。有些型号甚至不支持工具调用。因此，可以切换和测试不同的型号，看看哪种型号能给您带来最好的响应，但请记住，您很可能需要为每种型号重写系统提示。例如，使用 Llama3.3与 GPT-4o 相比，它需要更多的提示和具体指令才能得到您想要的回应。

NBA 梦幻篮球

梦幻篮球就是和你的一群朋友组成一个联盟（警告，这可能会影响你们的友谊，这取决于你们的竞争有多激烈），通常会涉及到一些金钱问题。然后，你们每个人起草一支由 10 名球员组成的队伍，每周轮流与另一位朋友的 10 名球员比赛。您的总得分取决于您的每位球员在一周内与对手的对战情况。

如果您队中有球员受伤、停赛等，会有一份自由球员名单供您选择。这也是梦幻体育中最难思考的地方，因为你只有有限的选择权，而每个人都在不断地寻找最好的球员。

这正是我们的 NBA AI 助手大显身手的地方，尤其是在您必须迅速决定选择哪位球员的情况下。助手无需手动查找球员在与特定对手比赛时的表现，而是可以快速找到这些数据并比较平均值，从而为您提供明智的建议。

现在，您已经了解了代理 RAG 和 NBA 梦幻篮球的一些基本知识，让我们来看看它的实际应用。

建设项目

如果您遇到任何问题或不想从头开始构建，请参考软件仓库。

我们的内容

1. 为项目搭建脚手架：

   1. 后端（Mastra）：使用 npx create mastra@latest 构建后端并定义代理逻辑。

   2. 前端（Vite + React）：使用 npm create vite@latest 构建与代理交互的前端聊天界面。

2. 设置环境变量

   1. 安装 dotenv 来管理环境变量。

   2. 创建 .env文件，并提供所需的变量。

3. 设置 Elasticsearch

   1. 启动 Elasticsearch 集群（本地或云端）。

   2. 安装官方 Elasticsearch 客户端。

   3. 确保环境变量可访问。

   4. 建立与客户端的连接。

4. 将 NBA 数据批量导入 Elasticsearch

   1. 创建具有适当映射的索引，以启用聚合。

   2. 将 CSV 文件中的玩家游戏统计数据批量导入 Elasticsearch 索引。

5. 定义 Elasticsearch 聚合

   1. 查询计算与特定对手的历史平均值。

   2. 查询计算对特定对手的赛季平均分。

6. 播放器比较实用程序文件

   1. 整合辅助函数和 Elasticsearch 聚合。

7. 建立代理

   1. 添加代理定义和系统提示。

   2. 安装 zod 和定义工具。

   3. 添加中间件设置以处理 CORS。

8. 整合前端

   1. 使用 AI-SDK 的 useChat 与代理互动。

   2. 创建用户界面，以保存格式正确的对话。

9. 运行应用程序

   1. 同时启动后端（Mastra 服务器）和前端（React 应用程序）。

   2. 查询和使用示例。

10. 下一步是什么？让代理更智能

    1. 增加语义搜索功能，提供更具洞察力的建议。

    2. 将搜索逻辑移至 Elasticsearch MCP（模型上下文协议）服务器，从而启用动态查询。

准备工作

• Node.js 和 npm：后端和前端都在 Node 上运行。确保已安装 Node 18+ 和 npm v9+（与 Node 18+ 绑定）。

• Elasticsearch 集群：本地或云端的活动 Elasticsearch 集群。

• OpenAI API 密钥：在OpenAI 开发人员门户网站的 API 密钥页面上生成一个。

项目结构

步骤 1：为项目搭建脚手架

1. 首先，创建目录 nba-ai-assistant-js，并在其中导航：

后台

1. 使用 Mastra 创建工具并执行命令：

2.你的终端应该会收到一些提示，第一个提示是命名项目后台：

3.接下来，我们将保留存储 Mastra 文件的默认结构，因此输入src/.

4.然后，我们将选择 OpenAI 作为默认的 LLM 提供商。

5.最后，它会要求你提供 OpenAI API 密钥。现在，我们选择跳过选项，稍后在 .env 文件中提供。

前台

1. 返回根目录，使用此命令运行Vite 创建工具： npm create vite@latest frontend -- --template react

这将创建一个名为frontend 的轻量级 React 应用程序，并为 React 提供特定模板。

如果一切顺利，在你的项目目录中，你应该会看到一个存放 Mastra 代码的后台目录和一个存放 React 应用程序的frontend 目录。

步骤 2：设置环境变量

1. 为了管理敏感键，我们将使用dotenv 软件包从 .env 中加载环境变量。锉刀导航至后台目录，安装dotenv ：

2.在后台目录中，会提供一个 example.env 文件，其中包含需要填写的相应变量。如果您自己创建，请确保包含以下变量：

注意：通过在.gitignore 中添加.env ，确保将此文件排除在版本控制之外。

第 3 步：设置 Elasticsearch

首先，您需要一个活动的 Elasticsearch 集群。有两种选择：

• 选项 A：使用 Elasticsearch 云

  • 注册弹性云

  • 创建新的部署

  • 获取端点 URL 和 API 密钥（已编码）

• 选项 B：在本地运行 Elasticsearch

  • 在本地安装并运行 Elasticsearch

  • 使用 http://localhost:9200 作为终端

  • 生成 API 密钥

在后台安装 Elasticsearch 客户端：

1. 首先，在后台目录中安装 Elasticsearch 官方客户端：

2.然后创建一个 lib 目录来存放可重复使用的函数，并导航进入该目录：

3.在其中创建一个名为elasticClient.js 的新文件。该文件将初始化 Elasticsearch 客户端，并在整个项目中公开使用。

4.由于我们使用的是 ECMAScript 模块 (ESM)，因此无法使用__dirname and __文件名。为确保您的环境变量能从 .env文件，将此设置添加到文件顶部：

5.现在，使用环境变量初始化 Elasticsearch 客户端并检查连接：

现在，我们可以将此客户端实例导入任何需要与 Elasticsearch 集群交互的文件。

第 4 步：将 NBA 数据批量导入 Elasticsearch

数据集：

在本项目中，我们将引用软件版本中后端/数据目录下的数据集。我们的 NBA 助手将以这些数据为知识基础，进行统计比较并生成建议。

• sample_player_game_stats.csv- NBA 球员职业生涯的球员比赛统计数据样本（如得分、篮板、抢断等）。我们将使用该数据集进行聚合。(注：这是模拟数据，为演示目的而预先生成，并非来自 NBA 官方来源）。

• playerAndTeamInfo.js- 替代通常由应用程序接口调用提供的球员和球队元数据，以便代理能将球员和球队名称与 ID 匹配。由于我们使用的是样本数据，我们不希望从外部应用程序接口获取数据造成开销，因此我们硬编码了一些代理可以引用的值。

实施：

1. 在backend/lib 目录中，创建名为playerDataIngestion.js 的文件。

2. 设置导入、解析 CSV 文件路径并设置解析。同样，由于我们使用的是 ESM，因此需要重构__dirname 来解析 CSV 样本的路径。此外，我们还将导入Node.js的内置模块fs 和readline 逐行解析给定的 CSV 文件。

这样，当我们进入批量摄取步骤时，就能高效地读取和解析 CSV。

3.创建具有适当映射的索引。虽然 Elasticsearch 可以通过动态映射自动推断字段类型，但我们希望在此明确说明，以便每个统计信息都被视为数字字段。这一点很重要，因为稍后我们将使用这些字段进行聚合。我们还希望对得分、篮板等统计数据使用float 类型，以确保包含小数值。最后，我们要添加映射属性dynamic: 'strict' ，这样 Elasticsearch 就不会动态映射未识别的字段。

4.添加将 CSV 数据批量导入 Elasticsearch 索引的函数。在代码块内，我们跳过标题行。然后，用逗号分隔每个行项目，并将其推入文档对象。这一步骤还可以清洁它们，并确保它们是正确的类型。接下来，我们将文档连同索引信息一起推送到 bulkBody 数组中，作为批量摄取到 Elasticsearch 的有效载荷。

5.然后，我们可以通过elasticClient.bulk() 使用 Elasticsearch 的批量 API，在一次请求中摄取多个文档。下面的错误处理结构可以让你计算有多少文档未能被摄取，有多少文档被成功摄取。

6.运行下面的main() 函数，依次运行createIndex() 和bulkIngestCsv() 函数。

如果看到控制台日志显示批量摄取成功，请在 Elasticsearch 索引上执行快速检查，查看是否确实成功摄取了文档。

步骤 5：定义 Elasticsearch 聚合和合并

这些将是我们为人工智能代理定义工具时使用的主要功能，以便对球员的统计数据进行比较。

1.导航至backend/lib 目录，创建名为elasticAggs.js 的文件。

2.添加下面的查询，计算球员对特定对手的历史平均分。该查询使用bool 过滤器，其中包含两个条件：一个匹配player_id ，另一个匹配opponent_team_id ，以便只检索相关游戏。我们不需要返回任何文档，我们只关心聚合，因此我们设置size:0 。在aggs 块下，我们在points, rebounds, assists, steals, blocks 和fg_percentage 等字段上并行运行多个度量聚合，以计算它们的平均值。LLM 的计算可能会出现偏差，而这一功能可将计算过程卸载到 Elasticsearch，确保我们的 NBA AI 助手能够访问准确的数据。

3.要计算一名球员对阵特定对手的赛季平均值，我们将使用与历史查询几乎相同的查询方式。该查询的唯一区别是bool 过滤器对game_date 附加了一个条件。game_date 必须在当前 NBA 赛季的范围内。在这种情况下，范围介于2024-10-01 和2025-06-30 之间。下面这个额外的条件确保了后面的汇总将只分离出本赛季的比赛。

步骤 6：球员比较实用程序

为了保持代码的模块化和可维护性，我们将创建一个实用程序文件来整合元数据辅助函数和 Elasticsearch 聚合。这将为特工使用的主要工具提供动力。稍后再详述：

1.在backend/lib 目录中新建一个文件comparePlayers.js。

2.添加下面的函数，将元数据助手和 Elasticsearch 聚合逻辑合并为一个函数，为代理使用的主要工具提供动力。

步骤 7：建立代理

现在，您已经创建了前端和后端脚手架，摄取了 NBA 游戏数据，并建立了与 Elasticsearch 的连接，我们可以开始将所有部件组装在一起以构建代理。

定义代理

1.导航至backend/src/mastra/agents 目录中的index.ts文件并添加代理定义。您可以指定以下字段

• 名称：给代理起一个名字，在前台调用时用作参考。

• 指令/系统提示： 系统提示为 LLM 提供交互过程中需要遵循的初始环境和规则。它类似于用户通过聊天框发出的提示，但这个提示是在用户输入之前发出的。同样，这也会根据您选择的机型而变化。

• 模型：使用哪种 LLM（Mastra 支持 OpenAI、Anthropic、本地模型等）。

• 工具：代理可调用的工具功能列表。

• 记忆：（可选）如果我们希望代理记住对话历史等。为了简单起见，我们可以不使用持久内存，尽管 Mastra 支持持久内存。

定义工具

1. 导航至backend/src/mastra/tools 目录中的index.ts文件。

2. 使用命令安装 Zod：

3.添加工具定义。请注意，我们将comparePlayers.js 文件中的函数导入为代理在调用该工具时将使用的主函数。使用 Mastra 的createTool() 功能，我们将注册playerComparisonTool 。这些领域包括

• id:这是一种自然语言描述，用于帮助代理理解工具的功能。

• input schema:为了定义工具的输入形状，Mastra 使用了Zod模式，这是一个 TypeScript 模式验证库。Zod 可确保代理输入结构正确的输入，并在输入结构不匹配时阻止工具执行。

• description:这是一种自然语言描述，帮助代理了解何时呼叫和使用工具。

• execute:调用工具时运行的逻辑。在本例中，我们使用一个导入的辅助函数来返回性能统计信息。

添加中间件处理 CORS

在 Mastra 服务器中添加中间件以处理CORS。俗话说，人生有三件事无法避免：死亡、税收，而对于网络开发人员来说，就是 CORS。简而言之，跨源资源共享是一种浏览器安全功能，可阻止前台向运行在不同域或端口的后台发出请求。尽管我们在 localhost 上运行后端和前端，但它们使用不同的端口，从而触发了 CORS 策略。我们需要添加Mastra 文档中指定的中间件，以便我们的后端允许来自前端的请求。

1.导航至backend/src/mastra 目录中的index.ts文件，并添加 CORS 配置：

• origin: ['http://localhost:5173']

  • 只允许来自该地址的请求（Vite 默认地址）

• allowMethods: ["GET", "POST"]

  • 允许使用的 HTTP 方法。大多数情况下，它将使用 POST。

• allowHeaders: ["Content-Type", "Authorization", "x-mastra-client-type, "x-highlight-request", "traceparent"],

  • 它们决定了哪些自定义标头可以在请求中使用

步骤 8：整合前端

这个 React 组件提供了一个简单的聊天界面，可使用@ai-sdk/react 中的useChat()钩子连接到 Mastra AI 代理。我们还将使用此钩子来显示标记的使用情况、工具调用情况并渲染对话。在上面的系统提示中，我们还要求代理以 markdown 格式输出响应，因此我们将使用react-markdown 来正确格式化响应。

1.在前端目录中，安装 @ai-sdk/react 软件包以使用 useChat() 钩子。

2.在同一目录下，安装 React Markdown，这样我们就能正确格式化代理生成的响应。

3.实施useChat() 。此钩子将管理前台与人工智能代理后台之间的交互。它可以处理消息状态、用户输入和状态，并为您提供生命周期钩子，以实现可观察性。我们提供的选项包括

• api: 这定义了 Mastra AI 代理的端点。默认端口为 4111，我们还要添加支持流式响应的路由。

• onToolCall:在代理调用工具时执行；我们用它来跟踪代理调用了哪些工具。

• onFinish:在代理完成完整响应后执行。尽管我们启用了流式传输，但onFinish 仍将在收到完整报文后运行，而不是在每个分块后运行。在这里，我们用它来跟踪令牌的使用情况。这对监控 LLM 成本和优化成本很有帮助。

4.最后，前往frontend/components 目录中的ChatUI.jsx组件，创建用户界面来进行对话。接下来，用ReactMarkdown 组件封装响应，以便正确格式化来自代理的响应。

步骤 9：运行应用程序

祝贺你现在就可以运行应用程序了。按照以下步骤启动后台和前台。

1. 在终端窗口中，从根目录开始，导航到后台目录并启动 Mastra 服务器：

2.在另一个终端窗口中，从根目录开始，导航到前端目录并启动 React 应用程序：

3.打开浏览器，导航到

http://localhost:5173

您应该可以看到聊天界面。试试这些提示样本：

• "对比勒布朗-詹姆斯和斯蒂芬-库里"

• "我应该在杰森-塔图姆和卢卡-东契奇之间选谁？"

下一步是什么？让代理更智能

为了让助手更具代理能力，建议更具洞察力，我将在下一次迭代中添加一些关键升级。

NBA 新闻的语义搜索

有很多因素会影响球员的表现，其中很多并不会在原始数据中体现出来。像伤病报告、阵容变化，甚至赛后分析，你只能在新闻报道中找到。为了捕捉这些额外的上下文，我将添加语义搜索功能，这样代理就可以检索相关的 NBA 文章，并将这些叙述纳入其推荐中。

使用 Elasticsearch MCP 服务器进行动态搜索

MCP（模型上下文协议）正迅速成为代理连接数据源的标准。我将把搜索逻辑迁移到 Elasticsearch MCP 服务器中，这样代理就可以动态建立查询，而不是依赖我们提供的预定义搜索功能。这使我们能够使用更多的自然语言工作流，并减少了手动编写每个搜索查询的需要。点击此处了解有关 Elasticsearch MCP 服务器和生态系统现状的更多信息。

这些更改正在进行中，敬请期待！

结论

在本博客中，我们使用 JavaScript、Mastra 和 Elasticsearch 构建了一个代理 RAG 助手，为您的梦幻篮球队提供量身定制的建议。我们报道了

• 代理 RAG 的基本原理，以及如何将人工智能代理的自主性与有效使用 RAG 的工具相结合，从而产生更细致入微、更具活力的代理。

• Elasticsearch 及其数据存储能力和强大的本地聚合功能如何使其成为法律硕士知识库的最佳合作伙伴。

• Mastra 框架及其如何为 javaScript 生态系统中的开发人员简化这些代理的构建。

无论你是篮球迷，还是在探索如何构建人工智能代理，或者像我一样两者兼而有之，我都希望这篇博客能为你提供一些入门的基础知识。完整的软件源可在GitHub 上获取，请随意克隆和修补。现在，去赢得梦幻联赛吧！

这篇博文介绍了如何使用 Elasticsearch 和 Azure Open AI 创建一个示例应用程序，演示如何在搜索非常具体的房地产物业时找到准确的结果，同时在没有具体匹配结果时仍然提供相关结果。我们将介绍创建 Elasticsearch 索引和搜索模板所需的所有步骤。然后，我们将介绍如何创建一个应用程序，使用 Azure OpenAI 接收用户查询并将其转换为 Elasticsearch 搜索模板查询，从而生成令人惊叹的自定义结果的整个过程。

下面列出了我们在创建房地产搜索应用程序示例时要用到的所有资源：

• Elasticsearch 索引和搜索模板

• Azure OpenAI

• Azure 地图 API

• Codespaces Jupyter 笔记本

• 语义内核

• 使用 Blazor 前端的 C# 应用程序

智能查询工作流程

该工作流程将 LLM、LLM 工具和搜索结合起来，将自然语言查询转化为结构化的相关搜索结果：

• LLM（大型语言模型）--解释复杂的用户查询并协调工具以提取搜索意图和丰富上下文。

• LLM 工具- 每个 LLM 工具都是我们为本职位创建的 C# 程序。有三种工具：

  • 参数提取工具：从查询中提取卧室、浴室、功能和价格等关键属性。

  • 地理编码工具：将地点名称转换为经纬度，以便进行空间筛选。

  • 搜索工具：使用查询参数填充 Elasticsearch 搜索模板并执行搜索。混合搜索- 利用内置 ML 推理执行混合搜索（全文 + 密集向量）。这种分层方法可确保终端用户获得更智能、更能感知上下文的查询体验。

应用架构

下面是示例应用程序的系统架构图。我们将使用 Codespaces Jupyter Notebook 与 Elastic Cloud 进行交互。

准备工作

您只需要浏览器，因为我们将使用 GitHub Codespaces 来克隆示例应用程序、配置并运行它。对于解决方案的弹性部分，我们将使用Elastic Cloud创建一个 Elasticsearch Serverless 项目。我们将使用Azure 门户来处理 Azure 资源。

在 Codespaces 中克隆示例应用程序 repo

首先克隆示例应用程序的代码。GitHub Codespaces 提供了克隆和运行应用程序的方法。单击新建代码空间。

然后，在 Repository 下拉菜单中选择 repo jwilliams-elastic/msbuild-intelligent-query-demo ，然后单击 Create Codespace 。

创建 .env文件

我们将使用 Python Jupyter Notebook 访问 Elastic Cloud 并与之交互，它使用存储在配置文件中的配置值进行访问和交互。笔记本配置文件的文件名应为.env您现在就可以创建它。

1. 在 GitHub 代码空间中，单击 "新建文件 "按钮，添加一个名为.env的文件

2. 在新创建的.env中添加以下内容文件

正如您所看到的，我们需要在.env 中添加几个缺失值，即 ELASTIC_URL 和 ELASTIC_API_KEY。锉刀现在，让我们创建一个 Elasticsearch 无服务器项目，将其作为后端，为我们示例应用的搜索功能提供动力。

创建弹性无服务器项目

1. 访问cloud.elastic.co，点击创建新的无服务器项目

2. 单击 "下一步 "查看Elasticsearch解决方案

3. 选择优化的载体

4. 将云提供商设置为Azure

5. 点击创建无服务器项目

6. 单击主导航菜单中的 "入门"，然后向下滚动以复制 "连接详情"。

7. 单击 "复制"按钮，从 " 连接详细信息"中复制 Elasticsearch 端点 。

8. 更新.env文件，将ELASTIC_URL设置为复制的Elasticsearch 端点

创建弹性 API 密钥

1. 打开 Elasticsearch 入门 页面，单击添加 API 密钥 部分中的 新建

2. 输入密钥名称

3. 单击 创建 API 密钥

4. 单击 "复制 "按钮复制 API 密钥值

5. 回到Codespaces，在这里我们有.env打开编辑文件，粘贴复制的值以设置 ELASTIC_API_KEY

打开 Codespaces 笔记本并安装依赖库

在文件资源管理器中，选择VectorDBSetup.ipynb文件，打开笔记本。加载笔记本后，找到笔记本中 标题为 " 安装库" 的部分 。点击章节播放按钮。

如果这是你第一次在 GitHub Codespaces 中运行笔记本，系统会提示你选择 Codespaces 内核并配置 Python 环境。

使用 Codespaces Notebook 定义导入和加载环境变量

转到笔记本的下一节，标题为 " 定义导入和加载环境变量"。点击章节播放按钮。

这段代码导入了 Notebook 使用的 Python 库，并从.env 中加载了环境变量。 您之前创建的

使用 Codespaces Notebook 创建 Elastic ML 推理端点

转到下一个笔记本部分，标题为 创建 ML 推理端点。点击章节播放按钮。

这将在 Elasticsearch 项目中创建一个新的 ML 推理端点，我们将用它从数据中生成文本嵌入。文本嵌入是文本的向量表示，将存储在 Elasticsearch 中以支持语义搜索。

使用 Codespaces Notebook 创建 Elasticsearch 索引

转到下一个笔记本部分，标题为 创建 Elasticsearch 索引。点击章节播放按钮。

这将创建 Elasticsearch 索引，用于存储示例数据和通过 ML 推理端点生成的任何相关向量数据。

使用 Codespaces Notebook 创建 Elasticsearch 搜索模板

继续下一个笔记本部分，标题为 " 搜索模板"。点击章节播放按钮。

这样就创建了一个搜索模板，我们的示例应用程序将使用它作为模板，其中填充了从用户搜索查询中解析出的单词。这样，我们就可以配置和控制在 Elasticsearch 索引中查询数据时的特定程度。

使用 Codespaces Notebook 将数据输入 Elasticsearch 索引

转到笔记本的下一部分，标题为 " 输入属性数据"。点击章节运行按钮。

运行该代码段将批量加载properties.jsonl 文件中包含的示例数据。几分钟后，您应该会看到程序成功完成的确认信息。您可以访问 Elastic Cloud 中的 "索引管理"部分，确认索引包含预期记录。

创建 appsetting.json 以配置 C# 应用程序

创建了 Elasticsearch 索引并填充了数据后，我们现在就可以配置示例应用程序，使其与 Elastic 和 Azure Cloud 协同工作。C# 示例应用程序使用名为appsettings.json的文件来存储和加载 API 密钥等访问信息。现在，您将使用 Codespaces 中的编辑器创建appsettings.json文件。

1.在 HomeFinderApp 文件夹中创建 appsettings.json

2.将以下代码粘贴到appsettings.json文件中

3.查找 ElasticSettings 部分下的 Url 和 ApiKey 值。将它们设置为与在.env文件。

创建 Azure OpenAI 服务

我们的示例应用程序将使用 Azure OpenAI 来解析应用程序用户的查询，然后通过填充搜索模板向 Elasticsearch 提交请求，以尝试灵活地传达用户正在搜索的内容。

1. 打开新的浏览器选项卡，转到 Azure 门户中的 AI Foundry | Azure OpenAI 。点击+创建

2. 在创建表格中，选择一个资源组。

3. 输入名称

4. 选择定价层级

5. 点击下一步

6. 在网络选项卡上，单击 下一步

7. 在 "标签"选项卡上，单击 "下一步

8. 在 "审核和提交"选项卡上，单击 "创建

9. 创建完成后，单击转到资源

10. 从左侧导航菜单中选择密钥和端点

11. 复制端点并将其粘贴到在浏览器标签页中创建的appsettings.json文件中，该标签页已打开 Codespaces 编辑器。

12. 然后返回包含 Azure OpenAI密钥和端点页面的浏览器选项卡。单击关键字 1 的复制按钮，然后将复制的值粘贴到appsettings.json文件中，回到打开 Codespaces 编辑器的浏览器标签页。

为 Azure Open AI 服务添加 gpt-4o 模型部署

很好，我们现在已经有了一个正在运行的 Azure OpenAI 服务，但它仍然需要一个模型部署，以提供我们的示例应用程序所需的 LLM 功能。有多种型号可供选择。既然已在创建的 appsettings.json 文件中指定了 gpt-4o ，那就部署它吧。

1. 转到Azure AI Foundry并单击创建部署

2. 搜索gpt-4o，并从结果中选择它

3. 单击确认选择

4. 单击 "部署"来部署模型

成功部署gpt-4o模型后，可以从左侧导航菜单中选择 "部署"，确认gpt-4o部署的状态为 "已成功"。

创建 Azure 地图账户

我们希望我们示例应用程序的用户能够搜索特定区域的房地产，但又不必太具体。如果有人想搜索当地农贸市场附近的房产，OpenAI LLM 可以使用 Azure 地图服务来获取市场的纬度和经度坐标。然后，在发送给 Elasticsearch 的基于搜索模板的请求中可以包含这些坐标，以便用户查询包含特定位置和地理距离的信息。

1. 单击 Azure 地图账户 中的 创建

2. 选择资源组

3. 输入名称

4. 同意许可和隐私声明

5. 单击审查并创建

6. 点击创建

7. 账户创建完成后，单击转到资源

8. 单击左侧导航菜单中的身份验证

9. 复制 主键值并粘贴到包含 Codespaces 编辑器的浏览器选项卡上，使其成为 appsettings.json 文件中 AzureMapsSettings 部分的 ApiKey 值

试用示例应用程序

现在是有趣的部分。是时候运行示例应用程序了。我们已经掌握了所有配置细节，以及为应用程序提供动力所需的 Elastic Cloud 和 Azure Cloud 资源。

1.在 Codespaces 编辑器中打开终端窗口。

2.使用以下命令将活动目录更改为示例应用程序文件夹。

3.使用以下dotnet命令运行应用程序。

4.出现 "在浏览器中打开 "按钮时，单击该按钮。

5.测试默认搜索，然后尝试一些自己的自定义搜索。如果想查看后台生成搜索结果的更多详细信息，可以单击 工具调用 旁边的显示 链接。

奖励： 如果你真的想测试 GPT-4o，请尝试以下搜索：我正在寻找佛罗里达州迪斯尼世界附近的房产，有 30 多间卧室、20 多间浴室、游泳池和车库，靠近海滩，价格在 20 万以下。 该查询将在多次调用搜索工具后返回结果。

Elastic 是您的搜索人工智能解决方案

运行中的应用程序是 Gen AI LLM 引导搜索的一个示例，它通过搜索模板使用 Elasticsearch 作为基础数据源。请随意尝试和定制示例应用程序，以创建精确而灵活的搜索体验，帮助用户找到他们想要的内容。

感谢您的阅读。试试弹性云。

什么是模型上下文协议（MCP）？

对于不熟悉的人来说，模型上下文协议是一种开放标准，它提供了一种结构化的双向方式，将人工智能模型连接到各种数据源和工具中，使其能够生成更相关、更明智的响应。它通常被称为 "用于人工智能应用的 USB-C 端口"。

下面的结构图突出了它的双向性：

这对人工智能从业人员来说是一个重大转变，因为扩展人工智能应用的主要挑战之一就是必须为每个新数据源建立自定义集成。MCP 提供了一个可持续、可重复使用的架构，用于管理和提供模型的上下文。它与模型无关，与服务器无关，并且完全开源。

MCP 是一系列 API 规范的最新版本，旨在实现应用程序之间集成的标准化。过去，我们有用于 RESTful 服务的 OpenAPI、用于数据查询的 GraphQL 和用于微服务通信的 gRPC。MCP 不仅在结构上与这些旧规范一样严谨，而且还将其带入了生成式人工智能环境，使其更容易将代理插入不同的系统，而无需定制连接器。在许多方面，MCP 的目标都是为人工智能代理做 HTTP 为网络所做的事情。正如 HTTP 标准化了浏览器和网站之间的通信一样，MCP 试图标准化人工智能代理与周围数据世界的交互方式。

MCP 与其他代理协议的比较

代理协议的范围正在迅速扩大，有十多种新兴标准竞相定义代理的交互方式。来自 LlamaIndex 的Laurie Voss介绍说，大多数协议可分为两类：侧重于代理相互对话的代理间协议和侧重于向 LLM 提供结构化上下文的面向上下文的协议（如 MCP）。

其他流行的协议，如谷歌的A2A（代理对代理）、思科和 IBM 的ACP（代理通信协议）以及Agora，都旨在实现代理对代理的协商、联盟建设甚至分散式身份系统。在这方面，MCP 采取了更加务实的方法，因为它关注的是代理如何访问工具和数据，而不一定是代理之间如何对话（尽管 MCP 在未来也可以通过不同的方式实现这一点）。

目前，MCP 的与众不同之处在于其牵引力和动力。与前端框架早期的 React 一样，MCP 也是从一个利基问题开始的，现在已成为实践中最常用、最具扩展性的代理协议之一。

峰会回顾：MCP 不断变化的优先事项

此次峰会的演讲者来自 Anthropic、Okta、OpenAI、AWS、GitHub 等公司。会谈内容从核心协议的改进到现实世界的实施，并概述了当前和长期的优先事项。这些会谈反映了从早期实验和简单的工具调用到以 MCP 为基础构建可信、可扩展和模块化的人工智能系统的转变。

几位发言人预言，在未来，MCP 不仅仅是协议管道，它还能成为人工智能原生网络的基础。就像 JavaScript 能让用户点击网页并与之互动一样，MCP 也能让代理代表我们执行同样的操作。例如，在电子商务中，用户无需手动导航到网站购物，只需告诉代理登录、找到特定产品、将其添加到购物车并结账即可。

这也不是纯粹的猜测和炒作；PayPal 在峰会上展示了他们新的代理工具包和 MCP 服务器，可以实现这种确切的代理商务体验。有了 MCP 提供的对工具和数据源的安全可靠访问，代理商将不仅仅是阅读网络，他们还将能够对其采取行动。如今，MCP 已经成为一个强大的标准，发展势头迅猛，未来可能成为全网人工智能增强型用户交互的标准。

MCP 项目更新：运输、征询和结构化工具

MCP 的核心贡献者杰罗姆-斯旺纳克（Jerome Swannack）分享了过去 6 个月中协议规范的一些更新。这些变化的主要目标是

1. 添加可流 HTTP 后启用远程 MCP

2. 通过增加诱导和工具输出模式，建立更丰富的代理交互模型

由于 MCP 是开放源代码，开发人员已经可以实现流式 HTTP 等更改。激发和工具输出示意图目前尚未发布；它们正处于草案阶段，可能会有所变化。

可流 HTTP （发布于 03-26-2025）：一个有影响的技术更新是引入了可流 HTTP 作为新的传输机制。它以一种更具可扩展性的双向模式取代了服务器发送事件（SSE），该模式支持分块传输编码和通过单个 HTTP 连接渐进式信息传输。这使您能够在 AWS Lambda 等云基础设施上部署 MCP 服务器，并支持企业网络限制，而无需长期连接或轮询。

诱导 （ Elicitation ） （发布于 06-18-2025 ） ： 诱导允许服务器定义一个模式，说明他们希望如何从客户端获得上下文结构。从根本上说，服务器可以描述它需要什么以及它期望的输入类型。这将产生一些影响：对于服务器构建者来说，他们可以构建更复杂的代理交互。对于客户端构建者来说，他们可以实现适应这些模式的动态用户界面。不过，不应利用诱导来获取用户的敏感信息或个人身份信息。开发人员应遵循最佳实践，确保诱导提示安全、适当，尤其是随着 MCP 的成熟。这与我们稍后将讨论的更广泛的安全问题有关。

工具输出示意图 （发布于 06-18-2025）： 这一概念允许客户和 LLM 提前了解工具输出形状。工具输出模式可让开发人员描述工具预期返回的内容。这些模式解决了直接调用工具的一个主要局限性，即上下文窗口的使用效率低下。上下文窗口被认为是使用 LLM 时最重要的资源之一，当你直接调用一个工具时，它返回的原始内容会全部推送到 LLM 的上下文中。工具输出模式可让 MCP 服务器提供结构化数据，从而帮助您更好地利用标记和上下文窗口。以下是一些有关工具的一般最佳实践。

这些新的更新和未来的新增功能将共同帮助 MCP 成为一个更加模块化、类型化和生产就绪的代理协议。

未充分利用的动力特性：采样和根

虽然 MCP 规范并不新鲜，但在主题演讲中，采样和根都得到了强调。这两个基本原理目前被忽视，也未得到充分探索，但却能极大地促进代理之间更丰富、更安全的交互。

取样 - 服务器可从客户端请求完成： 取样允许 MCP 服务器向客户端 LLM 请求完成。这就增加了协议的双向性，即服务器不只是响应请求，还可以提示并要求客户端的模型生成响应。这样，客户就可以完全控制成本、安全性以及 MCP 服务器使用的模型。因此，在使用带有预配置模型的外部 MCP 服务器的情况下，您无需提供自己的 API 密钥或配置自己对该模型的订阅，因为服务器可以直接提示已连接到客户端的模型。这使得代理行为更加复杂，互动性更强。

根 - 资源的范围访问： 根的设计目的是为客户端提供一种方法，让服务器了解相关的资源和工作区。这对于设定服务器的运行范围非常有效。值得注意的是，根是 "信息性的，而不是严格执行的"，这意味着它们并不定义 MCP 服务器或代理的权利或权限。换句话说，不能仅靠根来阻止服务器或代理执行某些工具或执行写入操作。有了根，权限仍应通过用户批准机制在客户端处理。此外，开发人员仍应注意使用在设计上尊重根设置的界限并采用最佳实践的服务器。

代理身份验证：OAuth 2.1 和受保护的元数据

本节重点介绍 OAuth 2.1，它是 OAuth 2.0 的最新迭代版本，删除了不安全流程并整合了最佳实践。

OAuth 支持是一个备受期待的话题，尤其是因为安全性和可扩展性被视为阻碍 MCP 成为将代理连接到工具的标准的主要障碍。Aaron Parecki（Okta 的 OAuth 2.1 编辑和身份标准专家）讨论了 MCP 如何采用简洁、可扩展的 OAuth 流程，从服务器开发人员那里卸载大部分复杂性。官方 OAuth 2.1 授权规范最近于2025 年 6 月 18 日发布了最新的协议修订版。

在这种实现方式中，OAuth 的责任可由 MCP 客户端和服务器分担。大部分身份验证流程都由 MCP 客户端启动和处理，只有服务器在最后才参与接收和验证安全令牌。这种拆分有助于解决一个关键的扩展问题，即如何在不要求开发人员配置每个连接的情况下跨多个工具进行身份验证，并确保 MCP 服务器开发人员不必成为 OAuth 专家。

讲座的两大亮点

1. 受保护资源元数据：MCP 服务器可发布一个 JSON 文件，描述其目的、端点和验证方法。这样，客户端只需输入服务器 URL 就能启动 OAuth 流程，从而简化了连接过程。了解更多信息：让我们修复 MCP 中的 OAuth

2. 支持 IDP 和 SSO：企业可以整合身份提供商，集中管理访问。这对用户体验和安全性来说都是双赢。用户无需点击 10 个不同的同意屏幕，安全团队也可以观察到每个连接。

通过将 OAuth 逻辑推送到客户端并依赖服务器的元数据，MCP 生态系统避免了一个主要瓶颈。这使 MCP 与当今生产环境中现代应用程序接口的安全保护方式更加一致。

补充阅读：OAuth 2 简化版

可组合生态系统中的安全挑战

新的发展也带来了新的攻击面。思科公司的 Arjun Sambamoorthy 列出了 MCP 环境中的几个主要威胁，包括

威胁

描述

补救& 最佳做法

及时注射& 工具中毒

在 LLM 系统上下文或工具描述中注入恶意提示的方法，导致 LLM 执行读取文件或泄漏数据等意外操作。

使用 MCP 扫描等工具对工具元数据进行检查。在提示中包含说明和参数前对其进行验证。最后，考虑对高风险工具实施用户审批。有关详细信息，请参阅表格下方附加阅读列表中的 OWASP 提示注入指南。

采样攻击

就 MCP 而言，采样为 MCP 服务器对 LLM 进行提示注入攻击打开了大门。

对不信任的服务器禁用取样功能，并考虑对取样请求增加人工在环审批。

恶意 MCP 服务器

在目前收集的 MCP 服务器中，很难逐一审查以确保安全。流氓服务器会悄悄收集你的数据，并将其暴露给恶意行为者。

仅从受信任的注册表或内部列表中连接到 MCP 服务器。在具有沙箱功能的容器中运行第三方服务器。

恶意 MCP 安装工具

命令行安装程序和脚本可方便地快速实施 MCP 服务器或工具，但最终可能会安装未经验证的加密代码。

在沙箱环境中安装并验证软件包签名。切勿从未经验证的来源自动更新。

为了进一步解决这个问题，Arjun 建议使用可信的 MCP 注册表来处理所有验证（这是一个前沿和中心话题--更多详情，请参阅下面阅读清单中的前两项），以及使用这份安全检查清单。

补充阅读：

• 官方 MCP 安全最佳实践

• OWASP 法律硕士申请 10 强

• 隐藏层威胁研究

• MCP 扫描

• OWASP 提示注入指南

下一步：注册、管理和生态系统

一个集中的 MCP 注册中心正在开发中，这也是峰会上讨论最多的话题之一。当前的服务器生态系统存在分散、信任度低和可发现性差等问题。开发人员很难找到 MCP 服务器、验证它们的功能并安全安装，尤其是在元数据可能不完整或被欺骗的分散生态系统中。

集中式注册表可作为可信的真相来源，提高可发现性，确保服务器元数据的完整性，降低安装恶意工具的风险，从而直接解决这些痛点。

登记册的目标是

• 为服务器元数据（服务器的功能、如何验证、安装和调用）提供单一真实来源

• 消除不完整的第三方注册表和碎片，这样当服务器想要注册时，就不必更新互联网上的所有其他注册表。

• 提供服务器注册流程，其中包括 CLI 工具和包含上述元数据的 server.json 文件。

更广泛的希望是，可信的注册表将有助于安全地扩展生态系统，使开发人员能够放心地构建和共享新工具。

对 Anthropic 来说，治理是另一个首要问题。他们明确表示，MCP 应保持开放和社区驱动，但这种管理模式的推广仍在进行中。他们目前正在寻求这方面的帮助，并希望任何有开源协议管理经验的人伸出援手。这就引出了我想说的另一个话题。在整个活动中，发言人都强调，只有内部开发人员做出贡献，生态系统才能发展壮大。为了使 MCP 成为新的网络标准，并从其他流行的代理协议中脱颖而出，我们需要集中精力。

现实世界中的 MCP：案例研究和演示

一些组织分享了如何在实际应用中使用 MCP：

• PayPal - 用于代理商务的 MCP 服务器： PayPal 展示了其新的代理工具包和 MCP 服务器，它们可以从根本上改变用户的购物体验。用户无需在社交媒体上搜索商品、比较价格和结账，而是可以与连接到 PayPal MCP 服务器的代理聊天，处理所有这些操作。

• EpicAI.pro - 贾维斯：MCP 的发展让我们越来越接近拥有一个现实生活中的 Jarvis 型助手。对于那些不熟悉《钢铁侠》电影的人来说，Jarvis 是一个人工智能助手，它使用自然语言，能对多模式输入做出响应，响应零延迟，能主动预测用户需求，自动管理集成，并能在设备和位置之间进行上下文切换。如果我们把贾维斯想象成一个物理机器人助手，那么 MCP 就赋予了贾维斯 "双手 "或处理复杂任务的能力。

• Postman - MCP 服务器生成器： 为 API 请求提供购物车体验，您可以挑选不同的 API 请求，将其放入购物篮，然后将整个购物篮下载为 MCP 服务器。

• 彭博社 - 彭博社 解决了企业 GenAI 开发中的一个关键瓶颈。他们拥有近 10,000 名工程师，需要一种标准化的方法来跨团队集成工具和代理。通过 MCP，他们将内部工具转变为模块化、远程优先的组件，代理可以在统一界面上轻松调用。这使他们的工程师能够在整个组织内贡献工具，而人工智能团队则专注于构建代理，而不是定制集成。Bloomberg 现在支持可扩展的安全代理工作流，可实现与 MCP 生态系统的完全互操作性。彭博社没有链接任何公共资源，但这是他们在峰会上公开展示的内容。

• Block- -Block使用MCP为内部人工智能代理Goose提供支持，使员工能够自动执行工程、销售、营销等方面的任务。他们为 Git、Snowflake、Jira 和 Google Workspace 等工具构建了 60 多个 MCP 服务器，以实现与日常使用的系统进行自然语言交互。现在，Block 公司的员工可以使用 Goose 查询数据、检测欺诈、管理事件、浏览内部流程等，而无需编写代码。MCP 在短短 2 个月内就帮助 Block 在许多工作职能中推广了人工智能。

• AWS - AWS MCP 服务器： AWS 推出了一款以《龙与地下城》为主题的有趣 MCP 服务器，该服务器可模拟掷骰子，跟踪过去的掷骰子情况，并使用可流式 HTTP 返回结果。这个轻量级示例强调了使用 Lambda 和 Fargate 等 AWS 工具和基础设施构建和部署 MCP 服务器是多么容易。他们还介绍了Strands SDK，这是一个用于构建与 MCP 服务器交互的多模式代理的开源工具包。

弹性代理生成器支持 MCP

您现在就可以使用Elastic Agent Builder开始尝试使用 MCP，它是直接在您的数据之上构建代理的最简单方法。代理生成器可让您将由 Elasticsearch 支持的工具暴露给兼容 MCP 的代理，它已配备了一些功能强大的内置工具，包括

• platform.core.search - 使用完整的 Elasticsearch 查询 DSL 执行搜索

• platform.core.list_indices - 列出 Elasticsearch 中所有可用的索引（帮助代理发现存在的数据）

• platform.core.get_index_mapping - 检索特定索引的字段映射（帮助代理了解数据的形状和类型）

• platform.core.get_document_by_id - 按 ID 抓取特定文件（用于精确检索）

只需使用这些工具，您就能为您的代理提供企业级搜索和相关性，这是建立可靠的人工智能代理的核心。

使 Agent Builder 功能更加强大的是，它能够根据应用程序的需要，定义和公开您自己的定制工具。这对意见性或可重复的工作流特别有用，因为在这种情况下，你希望代理针对特定索引执行特定类型的搜索，而不必每次都重新发现该逻辑。您可以将这种意图直接编码到工具中，从而使您的代理更快、更可靠、更具成本效益，而不必为得出相同的结论而花费大量时间进行规划和推理。

在代理生成器用户界面中，下面是一个使用 ES|QL 的自定义工具定义示例：

定义好自定义工具后，点击Manage MCP 下拉菜单并复制 MCP 服务器 URL，就可以使用 MCP 公开这些工具（以及内置的本地工具）。

现在，您可以将此 MCP 端点导入任何使用 MCP 的客户端，使其连接到 Agent Builder，并访问所有可用工具。更多信息，请阅读Agent Builder 简介。

结论

MCP Dev 峰会清楚地表明，MCP 正在塑造这些人工智能代理彼此互动以及与周围数据世界互动的方式。无论您是将代理连接到企业数据，还是设计完全自主的代理，MCP 都能提供一种标准化、可组合的集成方式，并迅速在大规模应用中发挥作用。从传输协议和安全模式到注册和管理，MCP 生态系统正在迅速成熟。MCP 将继续保持开放性和社区驱动，因此现在的开发人员有机会塑造其发展。

什么是春季人工智能？

Spring AI 1.0 是 Java 中人工智能工程的全面解决方案，在经历了人工智能领域快速发展的重要开发阶段后，现已面世。该版本为人工智能工程师提供了许多重要的新功能。

Java 和 Spring 在人工智能浪潮中处于有利位置。很多公司都在 Spring Boot 上运行他们的产品，这使得将人工智能插入到他们已经在做的事情中变得非常容易。您基本上可以将您的业务逻辑和数据直接与这些人工智能模型连接起来，而不会有太多麻烦。

Spring AI 为各种人工智能模型和技术提供支持，例如

• 图像模型：根据文字提示生成图像。

• 转录模型：获取音频源并将其转换为文本。

• 嵌入模型： 将任意数据转换为矢量，矢量是为语义相似性搜索而优化的数据类型。

• 聊天模式： 这些应该很熟悉！毫无疑问，你甚至在某个地方与他们进行过简短的交谈。

在人工智能领域，聊天模型似乎最受关注，这也是理所当然的，因为它们非常棒！你可以让他们帮你修改文件或写诗。(只是先别让他们讲笑话......）。它们很棒，但也存在一些问题。

应对人工智能挑战的春季人工智能解决方案

让我们来看看 Spring AI 中的一些问题及其解决方案。

问题

解决方案

一致性

聊天模式思想开放，容易分心

您可以给它们一个系统提示，以规范它们的整体形状和结构

内存

人工智能模型没有内存，因此无法将某个用户的一条信息与另一条信息关联起来

您可以为他们提供一个记忆系统，存储对话的相关部分

隔离

人工智能模型生活在与世隔绝的小沙箱中，但如果你能让它们使用一些工具--在它们认为必要时可以调用的功能，它们就能做出非常了不起的事情

Spring AI 支持工具调用，让你可以告诉 AI 模型其环境中的工具，然后它可以要求你调用这些工具。这种多轮互动都是透明处理的

私人数据

人工智能模型很聪明，但并非无所不知！他们不知道你专有数据库中的内容，我们认为你也不希望他们知道！

您需要通过填充提示来告知他们的回复--基本上就是在模型查看所提问题之前，使用强大的字符串连接运算符将文本放入请求中。背景资料，如果你愿意的话。如何决定哪些应该发送，哪些不应该发送？使用矢量存储，只选择相关数据并将其继续发送。这被称为检索增强生成，或 RAG

幻觉

人工智能聊天模型喜欢，嗯，聊天！有时，他们自信到可以胡编乱造

您需要使用评估--使用一个模型来验证另一个模型的输出--来确认合理的结果

当然，任何人工智能应用都不是一座孤岛。如今，现代人工智能系统和服务在与其他系统和服务集成时效果最佳。通过模型上下文协议(MCP)，可以将人工智能应用程序与其他基于 MCP 的服务连接起来，无论这些服务是用什么语言编写的。您可以将所有这些集合到代理 工作流程中，以实现更大的目标。

最棒的是什么？您可以在熟悉的成语和抽象基础上完成所有这些工作，Spring Boot 开发人员都会期待这些成语和抽象：Spring Initializr上提供了方便的启动依赖项，基本上所有东西都可以使用。

Spring AI 提供方便的 Spring Boot 自动配置，为您提供您所熟知和期待的 "惯例重于配置 "设置。Spring AI 通过 Spring Boot 的 Actuator 和 Micrometer 项目支持可观察性。它还能很好地与 GraalVM 和虚拟线程配合使用，让您可以构建超快、高效的人工智能应用程序，并进行扩展。

为什么选择 Elasticsearch

Elasticsearch 是一个全文搜索引擎，这一点你可能知道。那么，我们为什么要在这个项目中使用它呢？嗯，这也是一家矢量商店！数据与全文并存，相当不错。其他显著优势

• 设置超级简单

• 开源

• 可横向扩展

• 您企业的大部分自由格式数据可能已经存在于 Elasticsearch 集群中

• 具有完整的搜索引擎功能

• 完全集成到 Spring AI 中！

综上所述，Elasticsearch 符合优秀矢量存储的所有条件，因此让我们对其进行设置，然后开始构建我们的应用程序！

Elasticsearch 入门

我们需要 Elasticsearch 和 Kibana，这是用户界面控制台，用于与数据库中的数据交互。

借助 Docker 镜像和Elastic.co 主页，您可以在本地机器上尝试一切。访问该网站，向下滚动找到curl 命令，运行该命令并将其直接导入 shell：

这只需为 Elasticsearch 和 Kibana 提取和配置 Docker 映像，几分钟后，它们就会在本地计算机上运行，并提供完整的连接凭据。

您还可以使用两个不同的 URL 与 Elasticsearch 实例交互。按提示操作，将浏览器指向http://localhost:5601。

请注意打印在控制台上的用户名elastic 和密码：登录时需要使用这两个用户名和密码（在上面的输出示例中，它们分别是elastic 和w1GB15uQ ）。

整合应用程序

转到Spring Initializr页面并生成一个新的 Spring AI 项目，其中包含以下依赖项：

• Elasticsearch Vector Store

• Spring Boot Actuator

• GraalVM

• OpenAI

• Web

确保选择最新、最好的 Java 版本（最好是 Java 24（截至本文撰写之时）或更高版本）和您所选择的构建工具。本例中我们使用 Apache Maven。

单击Generate ，然后解压缩项目并将其导入您选择的集成开发环境。(我们使用的是 IntelliJ IDEA）。

首先：让我们为 Spring Boot 应用程序指定连接细节。在application.properties, 中写下以下内容：

我们还将利用 Spring AI 的向量存储功能来初始化 Elasticsearch 端所需的数据结构，请具体说明：

在本演示中，我们将使用OpenAI，特别是嵌入模型和聊天模型 （只要Spring AI 支持，您可以随意使用自己喜欢的服务）。

在将数据存储到 Elasticsearch 之前，我们需要嵌入模型来创建数据的嵌入。为了让 OpenAI 正常工作，我们需要指定API key ：

您可以将其定义为一个环境变量，如SPRING_AI_OPENAI_API_KEY ，以避免在源代码中存储凭据。

我们将上传文件，因此请务必自定义可上传至 servlet 容器的数据量：

我们快到了在开始编写代码之前，让我们先预览一下它是如何工作的。

在我们的机器上，我们下载了以下文件（一个棋盘游戏的规则列表），将其重命名为test.pdf 并放入~/Downloads/test.pdf.

文件将被发送到/rag/ingest 端点（根据本地设置替换相应路径）：

这可能需要几秒钟...

在幕后，数据被发送到 OpenAI，OpenAI 正在创建数据嵌入；然后，数据（包括向量和原始文本）被写入 Elasticsearch。

这些数据以及其中的所有嵌入式数据，就是神奇之处。然后，我们就可以使用VectorStore 界面查询 Elasticsearch。

整个流程是这样的

• HTTP 客户端会将您选择的 PDF 上传到 Spring 应用程序。

• Spring AI 负责从我们的 PDF 中提取文本，并将每页分成 800 个字符的小块。

• OpenAI 会为每个块生成向量表示。

• 然后，分块文本和嵌入都会存储在 Elasticsearch 中。

最后，我们将发出一个查询：

我们会得到相关的答案：

不错！这一切是如何运作的？

• HTTP 客户端将问题提交给 Spring 应用程序。

• Spring AI 从 OpenAI 获取问题的向量表示。

• 有了这种嵌入，它就能在存储的 Elasticsearch 块中搜索相似文档，并检索出最相似的文档。

• 然后，Spring AI 将问题和检索到的上下文发送给 OpenAI，以生成 LLM 答案。

• 最后，它会返回生成的答案和检索到的上下文的引用。

让我们深入 Java 代码，看看它到底是如何工作的。

首先是Main类：它是 Spring Boot 应用程序的标准主类。

没什么好看的。继续...

接下来是基本 HTTP 控制器：

控制器只是调用我们构建的一项服务，以处理文件摄取并将其写入 Elasticsearch 向量存储，然后方便对同一向量存储进行查询。

让我们来看看服务：

这段代码将处理所有的输入：给定一个 Spring FrameworkResource ，它是一个围绕字节的容器，我们使用 Spring AI 的PagePdfDocumentReader 读取 PDF 数据（假定是一个.PDF 文件--在接受任意输入之前，请确保您验证了这一点！），然后使用 Spring AI 的TokenTextSplitter 对其进行标记化，最后将生成的List<Document>s 添加到VectorStore 的实现ElasticsearchVectorStore 中。

您可以使用 Kibana 进行确认：向/rag/ingest 端点发送文件后，打开浏览器localhost:5601 ，然后在左侧菜单中导航至Dev Tools 。在这里，你可以发出查询，与 Elasticsearch 实例中的数据交互。

发出这样的查询

现在，有趣的事情来了：我们怎样才能在响应用户查询时将数据返回？

下面是查询的初步实现，方法名为directRag 。

代码非常简单，但让我们把它分成多个步骤：

1. 使用VectorStore 进行相似性搜索。

2. 给定所有结果后，获取底层 Spring AIDocuments 并提取其文本，将所有结果串联成一个结果。

3. 将VectorStore 的结果发送给模型，同时发送一个提示，指示模型如何处理这些结果以及用户提出的问题。等待回复并返回。

这就是RAG--检索增强生成。这就是我们使用矢量存储的数据为模型的处理和分析提供信息的理念。既然你已经知道怎么做了，那就希望你永远都不必这么做！反正不是这样的：Spring AI顾问将进一步简化这一过程。

除了在应用程序和矢量存储之间提供一个抽象层外，Advisors 还允许你对给定模型的请求进行预处理和后处理。在构建过程中添加以下依赖项

在类中添加另一个名为advisedRag(String question) 的方法：

所有 RAG 模式逻辑都封装在QuestionAnswerAdvisor 中。其他一切都与向ChatModel 提出的任何请求一样！不错！

你可以从 GitHub 获取完整的代码。

结论

在这个演示中，我们使用了 Docker 镜像，并在本地机器上完成了所有操作，但我们的目标是构建可投入生产的人工智能系统和服务。为了实现这一目标，您可以做几件事。

首先，你可以添加Spring Boot Actuator来监控令牌的消耗。代币代表了特定请求对模型造成的复杂性成本（有时是美元和美分）。

您已经在类路径上安装了 Spring Boot Actuator，因此只需指定以下属性即可显示所有指标（由宏伟的Micrometer.io项目捕获）：

重新启动应用程序。进行查询，然后转到： http://localhost:8080/actuator/metrics。搜索 "token"，就能看到应用程序使用的令牌信息。请务必留意这一点。当然，您也可以使用 Micrometer与 Elasticsearch 的集成来推送这些指标，并让 Elasticsearch 作为您选择的时间序列数据库！

因此，您应该考虑到，每次我们向 Elasticsearch 等数据存储、OpenAI 或其他网络服务发出请求时，我们都在进行 IO，而且 IO 经常会阻塞执行它的线程。Java 21 及更高版本配备了非阻塞虚拟线程，大大提高了可扩展性。使用

最后，您还需要将应用程序和数据托管在一个能够使其蓬勃发展和扩展的地方。我们相信，您可能已经考虑好在哪里运行应用程序了，但在哪里托管您的数据呢？我们可以推荐弹性云吗？它安全、私密、可扩展，功能齐全。我们最喜欢的部分？如果你愿意，还可以购买无服务器版，在无服务器版中，Elastic 会为你佩戴传呼机，而不是你！

本博客主要介绍如何使用 LangGraph Studio 和 LangGraph CLI 运行和定制 LangChain 检索代理模板。该模板为利用 Elasticsearch 等各种检索后端构建检索增强生成 (RAG) 应用程序提供了一个框架。

我们将指导您设置、配置环境，并使用 Elastic 高效执行模板，同时定制代理流程。

准备工作

在继续之前，请确保已安装以下设备：

• Elasticsearch 云部署或内部部署（或在 Elastic Cloud 上创建 14 天免费试用版 ）- 版本 8.0.0 或更高

• Python 3.9+

• 访问 LLM 提供商，如Cohere（本指南中使用）、OpenAI 或Anthropic/Claude

创建 LangGraph 应用程序

1.安装 LangGraph CLI

2.根据检索代理模板创建 LangGraph 应用程序

您将看到一个交互式菜单，可以从可用模板列表中进行选择。 为检索代理选择 4，为 Python 选择 1，如下图所示：

• 故障排除：如果遇到以下错误："urllib.error.URLError:<urlopen error [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1000)>"

请运行 Python 的安装证书命令来解决问题，如下所示。

3.安装依赖项

在新 LangGraph 应用程序的根目录下创建虚拟环境，并以edit 模式安装依赖项，这样服务器就会使用本地更改：

设置环境

1.创建 .环境文件

.env 文件包含 API 密钥和配置，因此应用程序可以连接到您选择的 LLM 和检索提供商。复制示例配置，生成新的.env 文件：

2.配置 .env文件

.env 文件带有一组默认配置。您可以根据设置添加必要的 API 密钥和值来更新它。任何与使用案例无关的键都可以保持不变或删除。

• .env 文件示例（使用弹性云和 Cohere）

下面是.env 配置示例，用于将Elastic Cloud用作检索提供商，将Cohere用作 LLM，本博客对此进行了演示：

注：本指南使用 Cohere 进行响应生成和嵌入，您也可以 根据自己的使用情况使用 其他 LLM 提供商，如 OpenAI、 Claude，甚至本地 LLM 模型。请确保您打算使用的每个密钥都已存在，并在 .env 文件中正确设置 。

3.更新配置文件 -configuration.py

使用适当的 API 密钥设置.env 文件后，下一步就是更新应用程序的默认模型配置。更新配置可确保系统使用您在.env 文件中指定的服务和模型。

导航至配置文件：

configuration.py 文件包含检索代理用于三项主要任务的默认模型设置：

• 嵌入模型--将文件转换为矢量表示

• 查询模型- 将用户的查询转化为矢量

• 响应模型- 生成最终响应

默认情况下，代码使用OpenAI（如openai/text-embedding-3-small ）和Anthropic（如anthropic/claude-3-5-sonnet-20240620 and anthropic/claude-3-haiku-20240307 ）的模型。在本博客中，我们将改用 Cohere 模型。如果您已经在使用 OpenAI 或 Anthropic，则无需更改。

更改示例（使用 Cohere）：

打开configuration.py 并修改模型默认值，如下图所示：

使用 LangGraph CLI 运行检索代理

1.启动 LangGraph 服务器

这将在本地启动 LangGraph API 服务器。如果运行成功，你应该会看到类似的内容：

开放工作室用户界面 URL。

有两种图表可供选择：

• 检索图：从 Elasticsearch 中检索数据，并使用 LLM 响应查询。

• 索引图：将文档索引到 Elasticsearch，并使用 LLM 生成嵌入。

2.配置索引图

• 打开索引图。

• 单击管理助手。

  • 点击"添加新助手"，输入指定的用户详细信息，然后关闭窗口。

3.为样本文件编制索引

• 为以下样本文件编制索引，这些文件是消费与工业专用技术公司的假设季度报告：

文件索引完成后，你会在线程中看到一条删除信息，如下图所示。

4.运行检索图

• 切换到检索图。

• 输入以下搜索查询：

系统将返回相关文件，并根据索引数据提供准确答案。

自定义检索代理

为了提升用户体验，我们在检索图中引入了一个定制步骤，以预测用户可能提出的下三个问题。这一预测的依据是

• 从检索到的文件中获取上下文

• 以前的用户互动

• 最后一次用户查询

实施查询预测功能需要更改以下代码：

1.更新 graph.py

• 添加predict_query 功能：

• 修改respond 函数，以返回response 对象，而不是消息：

• 更新图结构，为 predict_query 添加新节点和边：

2.更新 prompts.py

• 在prompts.py 中进行guery预测的工艺提示：

3.更新 configuration.py

• 添加predict_next_question_prompt ：

4.更新 state.py

• 添加以下属性

5.重新运行检索图

• 再次输入以下搜索查询：

系统将处理输入信息，并预测用户可能提出的三个相关问题，如下图所示。

结论

在 LangGraph Studio 和 CLI 中集成检索代理模板有几个主要好处：

• 加速开发：模板和可视化工具简化了检索工作流的创建和调试，缩短了开发时间。

• 无缝部署：对 API 和自动扩展的内置支持可确保跨环境的顺利部署。

• 易于更新：修改工作流程、添加新功能和集成其他节点都很简单，从而更容易扩展和增强检索流程。

• 持久记忆：系统保留代理状态和知识，提高一致性和可靠性。

• 灵活的工作流程建模：开发人员可针对特定用例定制检索逻辑和通信规则。

• 实时交互和调试：通过与运行中的代理互动，可以高效地进行测试和解决问题。

利用这些功能，企业可以建立强大、高效和可扩展的检索系统，从而提高数据的可访问性和用户体验。

该项目的完整源代码可在GitHub 上获取。

关于亚马逊新星

Amazon Nova 是亚马逊人工智能模型系列，可在亚马逊 Bedrock 上使用，旨在提供高性能和高成本效益。这些模型可使用文本、图像和视频输入，生成文本输出，并针对不同的精度、速度和成本需求进行了优化。

亚马逊 Nova 主要型号

• 亚马逊 Nova Micro：该机型专门针对文本，速度快、性价比高，是翻译、推理、代码补全和解决数学问题的理想之选。其生成速度超过每秒 200 个令牌，非常适合需要即时响应的应用。

• Amazon Nova Lite：一款低成本多模态模型，能够快速处理图像、视频及文本数据。该模型以其速度和准确性脱颖而出，适用于成本因素显著的大流量交互式应用场景。

• 亚马逊新星专业版：最先进的选择，集高精度、高速度和高性价比于一身。是视频摘要、问答、软件开发和人工智能代理等复杂任务的理想选择。专家评论证明了它在文本和视觉理解方面的卓越表现，以及它遵循指令和执行自动工作流程的能力。

亚马逊 Nova 模型适用于各种应用，从内容创建和数据分析到软件开发和人工智能驱动的流程自动化。

下面，我们将演示如何结合 Elasticsearch 使用 Amazon Nova 模型进行自动产品评论分析。

我们将做什么

1. 通过 Inference API 创建一个端点，将 Amazon Bedrock 与 Elasticsearch 集成在一起。

2. 使用推理处理器创建一个管道，该管道将调用推理 API 端点。

3. 索引产品评论，并使用管道自动生成评论分析。

4. 分析整合结果。

使用 Amazon Nova Lite 在推理 API 中创建终端

首先，我们配置 Inference API，将 Amazon Bedrock 与 Elasticsearch 集成。我们定义了亚马逊 Nova Lite，id 为amazon.nova-lite-v1:0、因为它在速度、准确性和成本之间取得了平衡。

注意：使用 Amazon Bedrock 需要有效凭证。您可以在此处查看获取访问密钥的文档：

创建审查分析管道

现在，我们创建一个处理管道，使用推理处理器来执行审查分析提示。此提示将把评论数据发送到 Amazon Nova Lite，由其执行：

• 情绪分类（积极、消极或中性）。

• 审查总结。

• 关键词生成。

• 真实性测量（真实 | 可疑 | 一般）。

索引审查

现在，我们使用批量 API 对产品评论进行索引。先前创建的管道将自动应用，将 Nova 模型生成的分析添加到索引文档中。

查询和分析结果

最后，我们运行一个查询，看看亚马逊 Nova Lite 模型是如何对评论进行分析和分类的。通过运行 GET products/_search，我们可以获得已经用评论内容生成的字段充实过的文档。

该模型可识别主要情绪（正面、中性或负面），生成简明摘要，提取相关关键词，并估计每条评论的真实性。这些字段有助于了解客户的意见，而无需阅读全文。

为了解释结果，我们研究了

• 情感，表示消费者对产品的总体看法。

• 摘要，突出了所述要点。

• 关键词，可用于对类似评论进行分组或识别反馈模式。

• 真实性，表示评论是否可信。这对策划或管理非常有用。

总结

Amazon Nova Lite 与 Elasticsearch 的整合展示了语言模型如何将原始评论转化为结构化的有价值信息。通过管道处理评论，我们能够自动、一致地提取情感、真实性、摘要和关键词。

结果表明，该模型可以理解评论的上下文，对用户意见进行分类，并突出每个体验中最相关的要点。这将创建一个更丰富的数据集，可用于提高搜索能力。

模型上下文协议 (MCP) 使之成为可能。它能将对话式人工智能与数据库和外部应用程序接口无缝连接，将复杂的请求转化为自然的对话。虽然现代 LLM 在理解语言方面非常出色，但当它们与现实世界的系统集成时，才能释放出真正的潜力。MCP 在两者之间架起了一座桥梁，使数据交互更直观、更高效。

在本篇文章中，我们将探讨

• MCP 架构 - 引擎盖下的工作原理

• 连接到 Elasticsearch 的 MCP 服务器的优势

• 构建由 Elasticsearch 支持的 MCP 服务器

激动人心的时刻即将到来！MCP 与 Elastic 协议栈的集成改变了您与信息交互的方式，使复杂的查询就像日常对话一样直观。

模型上下文协议

模型上下文协议（MCP）由 Anthropic 开发，是一种开放标准，可通过安全的双向渠道将人工智能模型与外部数据源连接起来。它解决了人工智能的一个主要限制：实时访问外部系统，同时保留对话语境。

MCP 架构

模型上下文协议架构由两个关键部分组成：

• MCP 客户端--代表用户请求信息或执行任务的人工智能助理和聊天机器人。

• MCP 服务器- 数据存储库、搜索引擎和 API，用于检索相关信息或执行请求的操作（如调用外部 API）。

MCP 服务器向客户端提供四种主要功能：

• 资源- 结构化数据、文件和内容，可检索并用作 LLM 交互的上下文。这样，人工智能助理就能从数据库、搜索索引或其他来源获取相关信息。

• 工具- 可执行的功能，使 LLM 能够与外部系统交互、执行计算或采取实际行动。这些工具将人工智能的功能扩展到文本生成之外，使助理能够触发工作流、调用应用程序接口或动态处理数据。

• 提示- 可重复使用的提示模板和工作流程，用于标准化和共享常见的 LLM 互动。

• 取样--通过客户端请求完成 LLM，以实现复杂的代理行为，同时维护安全性和隐私性。

MCP 服务器 + Elasticsearch

传统的检索-增强生成（RAG）系统根据用户查询检索文档，而 MCP 则更进一步：它使人工智能代理能够实时动态地构建和执行任务。这样，用户就可以提出自然语言问题，如

• "给我看上个月所有超过 500 美元的订单。"

• "哪些产品获得的五星好评最多？"

无需编写任何查询，即可获得即时、准确的答案。

MCP 通过以下方式实现这一目标

• 动态工具选择 - 代理商根据用户意图，通过 MCP 服务器智能选择合适的工具。"更聪明的 "法律硕士通常更善于根据上下文选择合适的工具，并提出适当的论据。

• 双向通信--代理和数据源可流畅地交换信息，并根据需要改进查询（如先查找索引映射，然后才构建 ES 查询）。

• 多工具协调--工作流程可同时利用多个 MCP 服务器的工具。

• 持续的上下文--代理可记住以前的互动，保持对话的连续性。

连接到 Elasticsearch 的 MCP 服务器可释放强大的实时检索架构。人工智能代理可按需探索、查询和分析 Elasticsearch 数据。您的数据可以通过一个简单的聊天界面进行搜索。

除了检索数据外，MCP 还能采取行动。它可与其他工具集成，以触发工作流、实现流程自动化，并将见解反馈到分析系统中。通过将搜索与执行分离，MCP 可使人工智能驱动的应用程序保持灵活、与时俱进，并无缝集成到代理工作流中。

实际操作：与 Elasticsearch 数据聊天的 MCP 服务器

要通过 MCP 服务器与 Elasticsearch 交互，我们至少需要以下功能：

• 检索指数

• 获取映射

• 使用 Elasticsearch 的查询 DSL 执行搜索

我们的服务器是用 TypeScript 编写的，我们将使用官方的MCP TypeScript SDK。安装时，我们建议安装 Claude Desktop App（免费版即可），因为它内置了 MCP 客户端。我们的 MCP 服务器本质上是通过 MCP 工具公开官方JavaScript Elasticsearch 客户端。

让我们从定义 Elasticsearch 客户端和 MCP 服务器开始：

我们将使用以下可与 Elasticsearch 交互的 MCP 服务器工具：

• 索引列表(list_indices)：该工具可检索所有可用的 Elasticsearch 索引，并提供索引名称、健康状态和文档数量等详细信息。

• 获取映射（get_mappings）：该工具可获取指定 Elasticsearch 索引的字段映射，帮助用户了解存储文档的结构和数据类型。

• 搜索（search）：该工具使用提供的查询 DSL 执行 Elasticsearch 搜索。它可自动启用文本字段的高亮显示，从而更容易识别相关搜索结果。

完整的 Elasticsearch MCP 服务器实现可在elastic/mcp-server-elasticsearchrepo 中找到。

与您的索引聊天

让我们来探讨一下如何设置 Elasticsearch MCP 服务器，以便就数据提出自然语言问题，例如"查找上个月所有超过 500 美元的订单。"

配置您的克劳德桌面应用程序

• 打开克劳德桌面应用程序

• 导航至设置> 开发人员> MCP 服务器

• 单击"Edit Config" ，将此配置添加到claude_desktop_config.json ：

注意：此设置使用 Elastic 发布的@elastic/mcp-server-elasticsearchnpm 软件包。如果您想在本地进行开发，可在此处了解有关安装 Elasticsearch MCP 服务器的更多详情。

填充 Elasticseach 索引

• 您可以使用我们的示例数据来填充"订单" 索引，用于此演示

• 这样您就可以尝试查询，如"查找上个月所有超过 500 美元的订单"

开始使用

• 在克劳德桌面应用程序中打开新对话

• MCP 服务器将自动连接

• 开始询问有关 Elasticsearch 数据的问题！

查看此演示，了解使用自然语言查询 Elasticsearch 数据有多简单：

工作原理是什么？

当被问及 "查找上个月所有超过 500 美元的订单 "时，LLM 会根据指定的约束条件识别搜索 Elasticsearch 索引的意图。要进行有效的搜索，特工需要：

• 找出索引名称： orders

• 了解orders 索引的映射关系

• 构建与索引映射兼容的查询 DSL，最后执行搜索请求

这种互动可以表示为

结论

模型上下文协议增强了您与 Elasticsearch 数据的交互方式，实现了自然语言对话，而不是复杂的查询。通过将人工智能功能与您的数据连接起来，MCP 可创建一个更直观、更高效的工作流程，在整个互动过程中保持上下文关联。

Elasticsearch MCP 服务器以公共 npm 包（@elastic/mcp-server-elasticsearch）的形式提供，开发人员可以直接集成。只需极少的设置，您的团队就可以开始探索数据、触发工作流，并通过简单的对话获得洞察力。

准备好亲自体验了吗？现在就试用Elasticsearch MCP 服务器，开始与您的数据聊天吧。

多式联运 RAG 管道是如何运作的？

1. 收集线索→ 哥谭市犯罪现场的图像、音频、文本和深度图。

2. 生成嵌入→使用 ImageBind 多模态模型将每个文件转换为矢量。

3. 在 Elasticsearch 中建立索引→ 存储向量以便高效检索。

4. 通过相似性检索→ 给出一条新线索，检索最相似的向量。

5. LLM 分析证据→ GPT-4 模型综合反应并确定嫌疑人！

使用的技术

• ImageBind→ 为各种模式生成统一的嵌入。

• Elasticsearch→ 实现快速高效的矢量搜索。

• LLM (GPT-4, OpenAI)→ 分析证据并生成最终报告。

这个博客为谁而设？

• 对多模式向量搜索感兴趣的弹性用户。

• 希望在实践中了解多模式 RAG 的开发人员。

• 任何人都在寻找可扩展的解决方案来分析来自多个来源的数据。

多模式 RAG 的先决条件：设置环境

要在哥谭市破案，您需要建立自己的技术环境。请按照本指南逐步操作：

1.技术要求

组件

规格

系统操作系统

Linux、macOS 或 Windows

Python

3.10 或更高版本

内存

最低 8GB（建议 16GB）。

GPU

可选，但建议用于 ImageBind

2.设立项目

所有调查材料均可在 GitHub 上获取，我们将使用 Jupyter Notebook（Google Colab）进行此次互动式犯罪侦破体验。请按照以下步骤开始操作：

使用 Jupyter Notebook（Google Colab）进行设置

1.访问笔记本

• 打开我们随时可用的 Google Colab 笔记本：使用 Elasticsearch 的多模式 RAG。

• 这本笔记本包含了您需要的所有代码和解释，以便您能跟上进度。

2.克隆版本库

3.安装依赖项

4.配置证书

注意：第一次运行时将自动下载 ImageBind 模型（~2GB）。

现在，一切准备就绪，让我们深入细节，破案吧！

简介高谭市的犯罪

在哥谭市的一个雨夜，一起令人震惊的犯罪事件震惊了整个城市。戈登局长需要你的帮助来揭开谜底。线索分散在不同的格式中：模糊的图像、神秘的音频、加密的文本，甚至深度图。您准备好使用最先进的人工智能技术破案了吗？

在本博客中，我们将逐步引导您建立一个多模态 RAG（检索-增强生成）系统，将不同类型的数据（图像、音频、文本和深度图）统一到一个搜索空间中。我们将使用ImageBind生成多模态嵌入，使用Elasticsearch存储和检索这些嵌入，并使用大型语言模型 (LLM)分析证据和生成最终报告。

基础知识：多模式 RAG 架构

什么是多模式 RAG？

检索-增强一代（RAG）多模态的兴起正在彻底改变我们与人工智能模型的交互方式。传统上，RAG 系统只处理文本，先从数据库中检索相关信息，然后再生成回复。然而，世界并不局限于文字，图像、视频和音频也蕴含着宝贵的知识。这也是多模态架构日益突出的原因，它允许人工智能系统将来自不同格式的信息结合起来，从而做出更丰富、更精确的反应。

多模式 RAG 的三种主要方法

要实施多模式 RAG，通常采用三种策略。每种方法都有自己的优势和局限性，具体取决于使用情况：

1.共享向量空间

利用 ImageBind 等多模态模型将不同模态的数据映射到一个共同的向量空间。这样，文本查询就可以检索图像、视频和音频，而无需进行明确的格式转换。

优势

• 实现跨模式检索，无需明确的格式转换。

• 提供不同模式之间的流畅整合，允许直接检索文本、图像、音频和视频。

• 可对各种数据类型进行扩展，因此适用于大规模检索应用。

缺点

• 训练需要大型多模态数据集，而这些数据集并不总是可用的。

• 共享的嵌入空间可能会带来语义漂移，即模态之间的关系没有得到完美的保留。

• 多模态模型的偏差会影响检索的准确性，这取决于数据集的分布情况。

2.单一接地方式

在检索之前，所有模式都会转换为单一格式，通常是文本格式。例如，通过自动生成的标题对图像进行描述，并将音频转录为文本。

优势

• 由于所有内容都转换为 统一的文本表示 ，因此 简化了检索 。

• 与现有的文本搜索引擎配合良好，无需专门的多模式基础设施。

• 由于检索结果采用人类可读格式，因此可提高可解释性。

缺点

• 信息丢失：文本描述可能无法完全捕捉某些细节（如图像中的空间关系、音频中的音调）。

• 取决于字幕/转录质量：自动注释中的错误会降低检索效率。

• 对于纯视觉或听觉查询来说并不是最佳选择，因为转换过程可能会删除重要的上下文。

3.单独检索

为每种模式维护不同的模型。系统对每种数据类型分别进行搜索，然后合并 搜索 结果。

优势

• 允许对每种模式进行自定义优化，提高每类数据的检索准确性。

• 减少对复杂的多模态模型的依赖，从而更容易整合现有的检索系统。

• 由于可以动态组合不同模式的结果，因此可以对排序和重新排序进行精细控制。

缺点

• 需要对结果进行融合，使检索和排序过程更加复杂。

• 如果不同模式返回的信息相互冲突，可能会产生不一致的响应。

• 计算成本较高，因为要对每种模式进行独立搜索，增加了处理时间。

我们的选择：使用 ImageBind 共享矢量空间

在这些方法中，我们选择了共享矢量空间，这一策略完全符合高效多模式搜索的需求。我们的实现基于 ImageBind ，它是一种能够在 通用矢量空间 中表示多种模式 （文本、图像、音频和视频 ）的模型。这使我们能够

• 在不同媒体格式之间进行跨模式搜索，无需将所有内容转换为文本。

• 使用表现力极强的嵌入式技术来捕捉不同模态之间的关系。

• 确保可扩展性和效率，存储优化嵌入，以便在 Elasticsearch 中快速检索。

通过采用这种方法，我们建立了一个强大的多模态搜索管道，文本查询可以直接检索图像或音频，而无需额外的预处理。这种方法的实际应用范围从大型资料库的智能搜索扩展到先进的多模式推荐系统。

下图说明了多模态 RAG 管道中的数据流，突出显示了基于多模态数据的索引、检索和响应生成过程：

嵌入空间如何运作？

传统上，文本嵌入来自语言模型（如 BERT、GPT）。现在，有了 Meta AI 的ImageBind 等本地多模态模型，我们就有了为多种模态生成向量的骨干：

• 文本：将句子和段落转换为相同维度的向量。

• 图像（视觉）：像素被映射到与文本相同的维度空间中。

• 音频声音信号被转换成与图像和文本类似的嵌入信息。

• 深度地图：深度数据经过处理后也会形成矢量。

因此，任何线索（文本、图像、音频、深度）都可以通过余弦相似度等矢量相似度量进行比较。如果笑声音频样本和嫌疑人面部图像在这个空间中 "接近"，我们就可以推断出某种相关性（例如，相同的身份）。

第 1 阶段--收集犯罪现场线索

在分析证据之前，我们需要收集证据。高谭市的犯罪留下的痕迹可能隐藏在图像、音频、文本甚至深度数据中。让我们把这些线索组织起来，输入我们的系统。

我们有什么？

戈登局长给我们发来了以下文件，其中包含从犯罪现场收集到的四种不同模式的证据：

轨道说明和模式

a) 图片（2 张照片）

• crime_scene1.jpg, crime_scene2.jpg → 在犯罪现场拍摄的照片。显示地面上的可疑痕迹。

• suspect_spotted.jpg → 监控录像显示一个人影逃离现场。

b) 音频（1 次录音）

• joker_laugh.wav → 犯罪现场附近的麦克风捕捉到了一个阴险的笑声。

c) 文本（1 条信息）

• Riddle.txt, note2.txt → 在现场发现了一些神秘的纸条，可能是罪犯留下的。

d) 深度（1 幅深度图）

• depth_suspect.png → 带有深度传感器的监控摄像头捕捉到附近巷子里的一名嫌疑人。

• jdancing-depth.png → 带有深度感应器的监控摄像头捕捉到一名嫌疑人从地铁站走下来。

这些证据的格式不同，无法以相同的方式直接进行分析。我们需要将它们转化为嵌入式数字向量，以便进行跨模态比较。

文件组织

在开始处理之前，我们需要确保所有线索都在 data/ 目录中组织妥当，以便管道顺利运行。

预期目录结构：

验证线索组织的代码

在继续之前，让我们确保所有所需文件都在正确的位置。

运行文件

预期输出（如果所有文件都正确）：

预期输出（如果缺少任何文件）：

在我们开始生成嵌入并将其索引到 Elasticsearch 之前，该脚本有助于防止错误的发生。

第 2 阶段--整理证据

使用 ImageBind 生成嵌入

为了统一这些线索，我们需要将它们转化为嵌入式向量表征，以捕捉每种模态的含义。我们将使用ImageBind，它是 Meta AI 的一个模型，可在共享向量空间内生成不同数据类型（图像、音频、文本和深度图）的嵌入。

ImageBind 如何工作？

要比较不同类型的证据（图像、音频、文本和深度图），我们需要使用ImageBind 将它们转换成数字向量。这种模式允许将任何类型的输入转换为相同的嵌入格式，从而实现不同模态之间的跨模态搜索。

以下是经过优化的代码 (src/embedding_generator.py) ，可使用适合各种模态的处理器为任何类型的输入生成嵌入：

张量是机器学习和深度学习中的一种基本数据结构，尤其是在使用 ImageBind 等模型时。就我们而言

在这里，张量表示将输入数据（图像、音频或文本）转换成模型可以处理的数学格式。具体来说

• 对于图像：张量以数值的多维矩阵（按高度、宽度和颜色通道排列的像素）来表示图像。

• 音频张量将声波表示为随时间变化的振幅序列。

• 对于文本：张量将单词或标记表示为数字向量。

测试嵌入生成：

让我们用下面的代码测试一下嵌入生成。将其保存在 02-stage/test_embedding_generation.py 中，并使用此命令执行：

预期输出：

现在，图像已转换成1024 维向量。

第 3 阶段 - Elasticsearch 中的存储和搜索

既然我们已经生成了证据的嵌入，就需要将它们存储到向量数据库中，以便进行高效搜索。为此，我们将使用Elasticsearch，它支持密集向量 (dense_vector) 并允许进行相似性搜索。

这一步骤包括两个主要过程：

• 索引嵌入→ 将生成的向量存储在 Elasticsearch 中。

• 相似性搜索→ 检索与新证据最相似的记录。

在 Elasticsearch 中索引证据

ImageBind处理的每个证据（图像、音频、文本或深度）都会转换成1024 维向量。我们需要在Elasticsearch中存储这些向量，以便将来进行搜索。

下面的代码 (src/elastic_manager.py) 在 Elasticsearch 中创建了一个索引，并配置了映射以存储嵌入。

运行索引

现在，让我们用一个证据来检验这个过程。

Elasticsearch 中的预期输出（索引文档的摘要）：

要为所有多模式证据编制索引，请执行以下 Python 命令：

现在，证据存储在Elasticsearch中，需要时可随时检索。

验证索引编制过程

运行索引脚本后，让我们验证一下 Elasticsearch 中是否正确存储了所有证据。您可以使用Kibana 的开发工具运行一些验证查询：

1.首先，检查是否创建了索引：

2.然后，验证每种模式的文件数量：

3.最后，检查索引文档结构：

预期成果：

• 应存在名为 `multimodal_content` 的索引。

• 约 7 份文件分布于不同的模式（视觉、音频、文本、深度）。

• 每个文档都应包含：嵌入、模式、描述、元数据和内容路径字段。

这一验证步骤可确保我们在进行相似性搜索之前正确建立证据数据库。

在 Elasticsearch 中搜索类似证据

既然证据已经编入索引，我们就可以进行搜索，找出与新线索最相似的记录。这种搜索使用向量相似性来返回嵌入空间中最接近的记录。

以下代码将执行此搜索。

测试搜索 - 使用音频作为多模态结果的查询方式

现在，让我们用一个可疑的音频文件来测试一下证据搜索功能。我们需要以同样的方式生成文件的嵌入，并搜索类似的嵌入：

终端中的预期输出：

现在，我们可以对检索到的证据进行分析，确定其与案件的相关性。

音频之外--探索多模态搜索

颠倒角色：任何方式都可以是"问题"

在我们的多模态 RAG系统中，每一种模态都是一个潜在的搜索查询。除了音频示例，让我们来探讨一下其他数据类型如何启动调查。

1.文本搜索（破译罪犯的纸条）

情景：您发现了一条加密短信，希望找到相关证据。

预期成果：

2.图像搜索（追踪可疑犯罪现场）

情景：一个新的犯罪现场(crime_scene2.jpg) 需要与其他证据进行比较。

输出：

3.深度图搜索（三维追踪）

场景： 深度图(jdancing-depth.png) 揭示了图像 逃逸模式。

输出

这有什么关系？

每种方式都能揭示独特的联系：

• 文本→ 嫌疑犯的语言模式。

• 图像→ 识别地点和物体。

• 深度→ 3D 场景重建。

现在，我们在 Elasticsearch 中拥有了一个 结构化的证据数据库 ，使我们能够 高效地存储和检索多模态证据 。

工作总结

• 在 Elasticsearch 中存储多模态嵌入。

• 进行相似性搜索，找到与新线索相关的证据。

• 使用可疑音频文件测试搜索，确保系统正常运行。

下一步：我们将使用LLM（大型语言模型）分析检索到的证据，并生成最终报告。

第 4 阶段--与法律硕士联系起来

现在，证据已经被索引到 Elasticsearch中，并可以通过相似性进行检索，我们需要一个LLM（大型语言模型） 对其进行分析，并生成最终报告发送给戈登局长。法学硕士将负责根据检索到的证据确定模式、串联线索并提出可能的嫌疑人。

对于这项任务，我们将使用GPT-4 Turbo，制定详细的提示，以便模型能够有效地解释结果。

LLM 整合

为了将 LLM 集成到我们的系统中，我们创建了 LLMAnalyzer 类src/llm_analyzer.py ()，该类从 Elasticsearch 中接收 检索到的证据 ，并以这些证据为提示语境生成 法证报告 。

LLM 分析中的温度设置

对于我们的取证分析系统，我们使用 0.5 的适度温度。选择这种平衡设置的原因是

• 它是确定性（过于死板）和高度随机输出之间的中间地带；

• 在 0.5 时，模型保持足够的结构，以提供合乎逻辑和合理的法医结论；

• 这种设置使模型能够识别模式并建立联系，同时保持在合理的法证分析参数范围内；

• 它既能提供一致、可靠的输出结果，又能进行深入分析。

这种适度的温度设置有助于确保我们的法证分析既可靠又有洞察力，避免得出过于僵化和过于臆测的结论。

进行证据分析

既然我们已经集成了LLM，就需要一个脚本来连接所有系统组件。该脚本将

• 在Elasticsearch中搜索类似证据 。

• 使用 LLM 分析检索到的证据 ，生成 最终报告。

代码证据分析脚本

预期学习成果

结论案件侦破

通过对所有线索的收集和分析，多模式 RAG 系统锁定了一名嫌疑人：小丑

通过使用 ImageBind 将 图像、音频、文本和深度图 整合到一个 共享的矢量空间 ，该系统能够 检测出 人工无法识别的 连接 。Elasticsearch确保了快速高效的搜索，而LLM则将证据综合成了一份清晰的结论性报告。

然而，该系统的真正威力 远不止于高谭市。多模式 RAG 架构为众多实际应用打开了大门：

• 城市监控：根据图像、音频和传感器数据识别嫌疑人。

• 法医分析：将多个来源的证据相互关联，以解决复杂的犯罪问题。

• 多媒体推荐： 创建能够理解 多模态语境的 推荐系统 （例如，根据图像或文本推荐 音乐 ）。

• 社交媒体趋势：通过不同的数据格式检测流行话题。

既然您已经学会了如何构建多模态 RAG 系统，为什么不用自己的线索来测试它呢？

与我们分享您的发现，帮助社区在多模态人工智能领域取得进步！

特别感谢

我要感谢 Adrian Cole 在定义本代码的部署架构过程中所做的宝贵贡献和审查。

参考资料

• 利用 KNN 搜索和 CLIP 嵌入构建多模态图像检索系统

• k-Nearest Neighbor (kNN) 搜索

• PyTorch 关于张量的官方文档

• ImageBind："连接 "人工智能与各种感官的新方法

Elasticsearch 允许用户使用开放推理 API 连接到 LLM，并支持 Amazon Bedrock、Cohere、Google AI、Azure AI Studio、HuggingFace - as a service 等提供商。

Ollama是一款允许您使用自己的基础设施（本地机器/服务器）下载和执行 LLM 模型的工具。在这里，您可以找到与 Ollama 兼容的可用型号列表。

如果你想托管和测试不同的开源模型，Ollama 是一个不错的选择，因为 Ollama 会处理好一切，让你不必担心每个模型的不同设置方式，也不必担心如何创建 API 来访问模型功能。

由于 Ollama API 与 OpenAI API 兼容，我们可以轻松集成推理模型，并使用 Playground 创建 RAG 应用程序。

准备工作

1. Elasticsearch 8.17

2. Kibana 8.17

3. Python

步长

1. 设置 Ollama LLM 服务器

2. 创建映射

3. 索引数据

4. 使用 Playground 提问

设置 Ollama LLM 服务器

我们将设置一个 LLM 服务器，使用 Ollama 将其连接到 Playground 实例。我们需要

• 下载并运行 Ollama。

• 使用 ngrok 通过互联网访问托管 Ollama 的本地网络服务器

下载并运行 Ollama

要使用 Ollama，我们首先需要下载它。Ollama 支持 Linux、Windows 和 macOS，因此只需 在这里 下载与你的操作系统兼容的 Ollama 版本即可 。安装好 Ollama 后，我们可以从支持的 LLM列表中选择一个模型。在本例中，我们将使用llama3.2 模型，这是一个通用的多语言模型。在设置过程中，您将启用 Ollama 的命令行工具。下载完成后，您就可以运行下面一行：

将输出

安装完成后，可以使用此命令进行测试：

我们来提个问题：

模型运行后，Ollama 会启用一个默认在"11434" 端口运行的 API。让我们按照官方文档，向该应用程序接口提出请求：

这就是我们得到的答复：

请注意，该端点的特定响应是流式响应。

使用 ngrok 将终端接入互联网

由于我们的端点在本地环境中运行，因此无法通过互联网从另一个点（如我们的弹性云实例）进行访问。ngrok允许我们公开提供公共 IP 的端口。在 ngrok 中创建账户，并按照官方设置指南进行操作。

安装并配置好 ngrok 代理后，我们就可以公开 Ollama 正在使用的端口：

注意： --host-header="localhost:11434"头 保证请求中的"Host" 头与"localhost:11434 匹配。"

执行该命令将返回一个公共链接，只要 ngrok 和 Ollama 服务器在本地运行，该链接就能正常工作。

在"Forwarding" 中，我们可以看到 ngrok 生成了一个 URL。留着以后用吧。

让我们再次尝试使用 ngrok 生成的 URL 向端点发出 HTTP 请求：

答复应与前一个答复类似。

创建映射

ELSER 端点

在本示例中，我们将使用 Elasticsearch 推理 API 创建一个推理端点。此外，我们还将使用ELSER生成嵌入。

在这个例子中，我们假设有一家药店出售两种药物：

• 需要处方的药物。

• 无需处方的药物。

这些信息将包含在每种药物的描述字段中。

LLM 必须对该字段进行解释，因此这就是我们要使用的数据映射：

字段text_description 将存储描述的纯文本，而作为语义_文本字段类型的semantic_field 将存储由 ELSER 生成的嵌入。

属性copy_to将把字段名和text_description 中的内容复制到语义字段中，以便为这些字段生成嵌入内容。

索引数据

现在，让我们使用_bulk API 为数据建立索引。

响应：

使用 Playground 提问

Playground是一款 Kibana 工具，可让您使用 Elasticsearch 索引和 LLM 提供商快速创建 RAG 系统。您可以阅读本文了解更多信息。

将当地的法律硕士与游乐场连接起来

我们首先需要创建一个连接器，使用我们刚刚创建的公共 URL。在 Kibana 中，转到搜索>Playground，然后点击"连接到 LLM" 。

此操作将显示 Kibana 界面左侧的菜单。在那里，点击"OpenAI" 。

现在我们可以开始配置 OpenAI 连接器了。

访问"Connector settings" ，并为 OpenAI 提供商选择"Other (OpenAI Compatible Service)" ：

现在，让我们配置其他字段。在本例中，我们将模型命名为"medicines-llm" 。在 URL 字段中，使用 ngrok 生成的 URL (/v1/chat/completions)。在"Default model" 字段中，选择"llama3.2" 。我们不会使用 API 密钥，因此只需输入任意文本即可：

点击"保存" 并点击"添加数据源" 添加索引药物：

好极了现在，我们可以使用本地运行的 LLM 作为 RAG 引擎访问 Playground。

在测试之前，让我们给代理添加更具体的指令，并将发送给模型的文件数量增加到 10 份，以便答案有尽可能多的可用文件。由于使用了 copy_to 属性，上下文字段将是semantic_field ，其中包括药品的名称和描述。

现在我们来问一个问题：没有处方可以购买氯硝西泮吗？看看会发生什么：

不出所料，我们得到了正确答案。

后续步骤

下一步是创建自己的应用程序！Playground 提供了一个 Python 代码脚本，你可以在自己的机器上运行，并根据自己的需要进行定制。例如，将其置于FastAPI服务器之后，创建一个由用户界面使用的 QA 药品聊天机器人。

点击 Playground 右上方的 "查看代码"按钮即可找到该代码：

然后使用Endpoints& API 密钥生成代码中所需的ES_API_KEY 环境变量。

本例的代码如下：

要使其与 Ollama 兼容，必须更改 OpenAI 客户端，使其连接到 Ollama 服务器，而不是 OpenAI 服务器。您可以在这里找到 OpenAI 示例和兼容端点的完整列表。

在调用完成方法时，将模型更改为 llama3.2：

让我们补充一个问题：我可以在没有处方的情况下购买氯硝西泮吗？ 至 Elasticsearch 查询：

此外，我们还在完成调用中打印了一些内容，以便确认我们将 Elasticsearch 结果作为问题上下文的一部分发送：

现在运行命令

pip install -qU elasticsearch openai

python main.py

你应该看到这样的内容：

结论

在本文中，当我们将 Ollama 等工具与 Elasticsearch 推论 API 和 Playground 结合使用时，我们可以看到它们的强大功能和多功能性。

经过几个简单的步骤后，我们就拥有了一个可运行的 RAG 应用程序，它可以聊天，使用 LLM 在我们自己的基础设施中运行，成本为零。这也使我们能够对资源和敏感信息有更多的控制权，此外，我们还可以使用各种模型来完成不同的任务。

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

使用 Ollama 设置本地推理

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

在裸机上运行 Ollama

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

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

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

在容器中运行 Ollama

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

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

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

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

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

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

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

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

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

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

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

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

将 Ollama 连接到 Kibana

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

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

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

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

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

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

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

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

创建连接器

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

用以下设置配置连接器

• 连接器名称：Deepseek（Ollama）

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

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

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

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

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

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

我们的连接器如下所示：

将向量嵌入数据导入 Elasticsearch

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

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

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

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

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

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

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

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

在 Playground 中测试 RAG

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

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

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

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

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

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

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

测试对齐限制

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

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

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

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

那么我们学到了什么？

总而言之：

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

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

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

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

切面搜索是电子商务平台的一个强大工具。它有助于根据显示项目的特征来组织和完善搜索结果。虽然滤镜经常被混淆，但切面的工作原理是不同的。筛选器是固定属性，由索引中始终存在的信息定义，如产品类别或格式。而面则是动态的，由执行搜索后返回的结果生成。

试想一下服装目录："类别" （如 T 恤、裤子）或"性别" （如男、女）等字段是帮助缩小结果范围的过滤器。而面则反映了结果中出现的产品的具体特征，如常见颜色、可用尺寸或材料。这使得搜索体验更具适应性和情境性。

下面是一张图片，我们与一个切面进行交互，可以看到由切面筛选出的搜索结果。

人工智能如何改善面的生成

人工智能通常与语义搜索和嵌入相关联，那么面呢？如何利用人工智能，使面面俱到对每次搜索更有用，并针对具体情况？

一个引人入胜的可能性是利用人工智能创建新的分类，超越索引中的传统分类。通过分析内容的具体特征，这些新类别可以提供更丰富、更精确的上下文，使面更相关、更符合用户需求。与原始文件类别相比，这使得结果的细化更有意义。

人工智能如何完善电影分类以提高搜索效果

让我们来分析一下以下影片，它们目前都被归类为剧情片类型：

• 梦之安魂曲 简历：四个科尼岛人吸毒成瘾后，他们的乌托邦被打破了。

• 美国丽人 简历：一位在性方面受挫的郊区父亲在迷恋上女儿最好的朋友后，陷入了中年危机。

• Good Will Hunting 简历：威尔-亨廷是麻省理工学院的看门人，他有数学天赋，但需要心理学家的帮助才能找到人生方向。

这种类型划分无法捕捉到每部影片的细微差别或独特背景。通过利用人工智能分析故事梗概和中心主题，我们可以创建新的类别，更好地反映每部电影的真实背景。例如

• 梦之安魂曲 - 新类别："成瘾与依赖"

• 美国丽人》 - 新类别："中年危机"

• Good Will Hunting - 新类别："智力斗争"

这些新类别使搜索更加精确，同时为用户提供了更有意义的筛选器来完善搜索结果。当原始分类过于笼统时，这种方法尤为有效，能让用户更轻松地准确找到他们要找的内容。

使用 GPT-4 创建新类别：面搜索示例

在这个例子中，我们将展示如何利用人工智能模型来创建新的电影类别，使其更加精确，并与每部作品的背景相一致。为了演示这一过程，我们将使用 Elastic 仿真管道和 OpenAI 推断服务。我们将创建一个由多个处理器组成的流水线，其中包括脚本处理器，它将负责创建提示语，并在推理处理器中执行，从而确定新的类别。其他处理器将用于处理流水线执行过程中产生的数据和辅助字段。值得一提的是，这一逻辑也可应用于其他类似的工具或模型。

首先，我们需要创建推理端点，将服务定义为 OpenAI、访问服务所需的令牌以及模型。在本例中，我使用的是 gpt-4-mini。有关 OpenAI 推断服务的更多详情，请点击此处。

端点创建完成后，我们就可以用它来创建新类别了。下面是一个处理文档数据操作和提示生成整个过程的管道。我将详细解释每个处理器的功能。

第一个处理器将负责建立提示。明确详细的说明非常重要，这样人工智能才能正确分析和识别主题。在本提示中，我要求根据对电影标题、描述和类型的分析来确定 2 个主题。

下一个管道是推理管道，它将接收提示并将其发送到我们的generate_topics_ia端点。模型生成的响应将存储在结果字段中。

接下来，除了删除我创建的临时字段外，我们还有 3 个处理器用于处理响应并将其设置到主题字段中。

执行该流水线后，我们将得到以下结果：

请注意，尽管有些影片最初属于同一类型，但我们有了与影片背景更加相关的新类别。

现在，我们可以使用这些新类别，并将它们与文档一起编入索引。这样，在生成切面时，除了主类别外，我们还可以根据影片的背景情况，生成更具体的子类别。

此外，还可以将这些新类别矢量化，并将其用于矢量搜索。这意味着，新的类别不仅可以用作过滤器，还可以用来计算与搜索词的语义相似性，从而进一步提高搜索结果的相关性。

完整的管道：

结论

利用人工智能改进面，可以使搜索结果更具体、更符合上下文，从而改变搜索体验。固定类别通常比较宽泛，而人工智能生成的类别则不同，它能更好地反映背景情况。例如，在对电影进行重新分类时，我们可以捕捉到主要类别所忽略的背景，从而提供更相关的分组。

将这些新的类别添加到索引中，不仅可以改进分面，还可以实现矢量搜索。其结果是搜索体验更加高效，筛选器更加符合上下文。

参考资料

https://www.elastic.co/guide/en/elasticsearch/reference/current/infer-service-openai.html

https://www.elastic.co/guide/en/elasticsearch/reference/current/simulate-pipeline-api.html

https://www.elastic.co/guide/en/elasticsearch/reference/current/script-processor.html

开箱即用的Semantic Kernel Elasticsearch向量存储连接器（Vector Store Connector）支持Semantic Kernel向量存储抽象，这使得开发人员在构建人工智能代理时能够非常容易地将Elasticsearch作为向量存储插件。

Elasticsearch 在开源社区拥有坚实的基础，最近采用了AGPL 许可证。这些工具与开源的微软语义内核（Microsoft Semantic Kernel）相结合，可提供强大的企业级解决方案。您可以通过运行此命令curl -fsSL https://elastic.co/start-local | sh ，在几分钟内启动 Elasticsearch（详情请参考start-local），然后在生产人工智能代理的同时，迁移到云托管或自托管版本。

在本篇博客中，我们将探讨在使用Semantic Kernel（语义内核）时，如何使用Semantic Kernel Elasticsearch向量存储连接器。该连接器的 Python 版本将在未来推出。

高级应用场景：利用 Semantic Kernel& Elasticsearch 构建 RAG 应用程序

下面我们将举例说明。在高层次上，我们正在构建一个 RAG（检索增强生成）应用程序，它将用户的问题作为输入，并返回一个答案。我们将使用 Azure OpenAI （ 也可使用 本地 LLM ）作为 LLM，Elasticsearch 作为向量存储，Semantic Kernel (.net) 作为将所有组件连接在一起的框架。

如果您不熟悉 RAG 架构，可以通过以下文章快速了解： https://www.elastic.co/search-labs/blog/retrieval-augmented-generation-rag。

答案由 LLM 生成，LLM 从 Elasticsearch 向量存储中获取与问题相关的上下文。答复还包括法律硕士用作背景的资料来源。

RAG 示例

在这个具体例子中，我们创建了一个应用程序，允许用户就内部酒店数据库中存储的酒店提出问题。例如，用户可以根据不同标准搜索特定酒店，或要求提供酒店列表。

在示例数据库中，我们生成了一个包含 100 个条目的酒店列表。为了让您尽可能轻松地试用连接器演示，我们特意设置了较小的样本量。在实际应用中，Elasticsearch 连接器将显示出其优于其他选项（如 "InMemory "向量存储实现）的优势，尤其是在处理超大数据量时。

完整的演示应用程序可在 Elasticsearch 向量存储连接器存储库中找到。

让我们先将所需的 NuGet 软件包和指令添加到项目中：

现在，我们可以创建我们的数据模型，并为其提供语义内核（Semantic Kernel）的特定属性，以定义存储模型模式和文本搜索的一些提示：

存储模型模式属性（`VectorStore*`）与 Elasticsearch 向量存储连接器的实际使用最为相关，即

• VectorStoreRecordKey 来标记记录类上的一个属性，作为记录存储在向量存储中的键。

• VectorStoreRecordData 将记录类的一个属性标记为 "数据"。

• VectorStoreRecordVector 将记录类的一个属性标记为矢量。

所有这些属性都接受各种可选参数，可用于进一步定制存储模型。以VectorStoreRecordKey 为例，可以指定不同的距离函数或不同的索引类型。

文本搜索属性 (TextSearch*) 在本示例的最后一步中非常重要。我们稍后再谈。

下一步，我们将初始化语义内核引擎，并获取核心服务的引用。在实际应用中，应使用依赖注入而不是直接访问服务集合。同样的道理也适用于硬编码的配置和秘密，它们应该使用配置提供程序来读取：

现在可以使用vectorStoreCollection 服务创建数据集，并摄取一些演示记录：

由此可见，语义内核（Semantic Kernel）是如何将向量存储的使用及其复杂性简化为几个简单的方法调用的。

在 Elasticsearch 中创建一个新索引，并创建所有必要的属性映射。然后，我们的数据集会完全透明地映射到存储模型中，并最终存储到索引中。下面是映射在 Elasticsearch 中的显示方式。

embeddings.GenerateEmbeddingsAsync() 会透明地调用已配置的 Azure AI 嵌入生成服务。

在这个演示的最后一个步骤中，我们还可以看到更多的神奇之处。

当用户就数据提问时，只需调用InvokePromptAsync ，就能执行以下所有操作：

1.为用户的问题生成嵌入代码

2.在矢量存储器中搜索相关条目

3.将查询结果插入提示模板

4.最终提示形式的实际查询将发送到人工智能聊天完成服务

还记得我们之前在数据模型上定义的TextSearch* 属性吗？有了这些属性，我们就能在提示模板中使用相应的占位符，这些占位符会根据向量存储中的条目信息自动填充。

对于我们的问题"，请告诉我所有拥有屋顶酒吧的酒店。" ，最终答复如下：

正确答案是指 hotels.csv 中的以下条目

这个例子很好地说明了微软语义内核的使用是如何通过其深思熟虑的抽象功能大大降低复杂性，并实现高度灵活性的。例如，只需修改一行代码，就可以更换向量存储或所使用的人工智能服务，而无需重构代码的任何其他部分。

同时，该框架还提供了大量高级功能，如 "InvokePrompt "函数或模板或搜索插件系统。

完整的演示应用程序可在 Elasticsearch 向量存储连接器存储库中找到。

Elasticsearch 还能做什么

• Elasticsearch 新语义文本映射：简化语义搜索

• 利用检索器在 Elasticsearch 中进行语义重排

• 高级 RAG 技术第 1 部分：数据处理

• 高级 RAG 技术第 2 部分：查询和测试

• 使用 Llama 3 开放源代码和 Elastic 构建 RAG

• 使用 LangGraph、LLaMA3 和 Elasticsearch 向量存储从零开始构建本地代理的教程

Elasticsearch& Semantic Kernel（语义内核）：下一步是什么？

• 我们展示了在.NET中构建GenAI应用时，如何将Elasticsearch向量存储轻松插入Semantic Kernel。敬请期待下一步的 Python 集成。

• 由于Semantic Kernel（语义内核）为混合搜索等高级搜索功能建立了抽象，Elasticsearch连接将使.NET开发人员能够在使用Semantic Kernel（语义内核）的同时轻松实现这些功能。

• 与法律硕士进行讨论，实施ChatLanguageModel 和 ChatMemory

• 在记忆中保留聊天记录，以便回忆起之前与一位法律硕士讨论的背景情况

本博文将介绍如何

• 根据文本示例创建向量嵌入

• 将向量嵌入存储在 Elasticsearch 嵌入存储中

• 搜索类似载体

创建嵌入

要创建嵌入式，我们需要定义一个EmbeddingModel 。例如，我们可以使用上一篇文章中使用过的相同的 mistral 模型。它和奥拉马一起跑：

模型能够从文本中生成向量。在这里，我们可以检查模型生成的维数：

要从文本中生成向量，我们可以使用

或者，如果我们还想提供元数据，以便对文本、价格、发布日期等内容进行筛选，我们可以使用Metadata.from().NET。例如，我们在这里添加游戏名称作为元数据字段：

如果您想运行这段代码，请查看Step5EmbedddingsTest.java类。

添加 Elasticsearch 来存储向量

LangChain4j 提供内存嵌入存储。这对运行简单测试非常有用：

但是，这显然不能用于更大的数据集，因为该数据存储将所有内容都存储在内存中，而我们的服务器上没有无限的内存。因此，我们可以将嵌入式数据存储到 Elasticsearch 中，根据定义，Elasticsearch 是"elastic" ，可以随着数据的扩展而扩展。为此，让我们在项目中添加 Elasticsearch：

正如你所注意到的，我们还在项目中添加了 Elasticsearch TestContainers 模块，这样我们就可以从测试中启动 Elasticsearch 实例：

要将 Elasticsearch 用作嵌入式存储，"，" ，就必须从 LangChain4j 内存数据存储切换到 Elasticsearch 数据存储：

这将在 Elasticsearch 中以default 索引的形式存储向量。您还可以将索引名称改为更有意义的名称：

如果您想运行此代码，请查看Step6ElasticsearchEmbedddingsTest.java类。

搜索类似载体

要搜索相似向量，我们首先需要使用之前使用过的相同模型，将问题转换为向量表示。我们已经做到了，所以再做一次并不难。请注意，在这种情况下我们不需要元数据：

我们可以用问题的这种表示法建立一个搜索请求，并要求嵌入式存储空间找出最前面的向量：

现在，我们可以遍历结果并打印一些信息，如来自元数据的游戏名称和得分：

正如我们所预料的那样，"Out Run" 作为第一击：

如果您想运行这段代码，请查看Step7SearchForVectorsTest.java类。

幕后花絮

Elasticsearch 嵌入存储的默认配置是在后台使用近似 kNN 查询。

但这可以通过向嵌入存储区提供默认配置 (ElasticsearchConfigurationKnn) 以外的另一种配置 (ElasticsearchConfigurationScript) 来改变：

ElasticsearchConfigurationScriptscript_score执行程序使用cosineSimilarity 函数 在后台运行 查询 。

基本上，打电话时

现在呼叫

在这种情况下，结果并不会因为"order" 而发生变化，只是分数会有所调整，因为cosineSimilarity 调用并不使用任何近似值，而是计算每个匹配向量的余弦值：

如果您想运行这段代码，请查看Step7SearchForVectorsTest.java类。

结论

我们已经介绍了如何从文本中轻松生成嵌入，以及如何使用两种不同的方法在 Elasticsearch 中存储和搜索近邻：

• 使用ElasticsearchConfigurationKnn 默认选项进行近似和快速knn 查询

• 使用ElasticsearchConfigurationScript 选项进行精确但较慢的script_score 查询

下一步将根据我们在这里学到的知识，构建一个完整的 RAG 应用程序。

LangChain4j 提供了一种标准的方法：

• 根据给定内容（例如文本）创建嵌入向量

• 将嵌入式存储在嵌入式存储库中

• 在嵌入存储中搜索相似向量

• 与法律硕士讨论

• 使用聊天记忆功能，记住与法律硕士讨论的来龙去脉

此列表并不详尽，LangChain4j 社区一直在实施新功能。

本帖将介绍该框架的第一个主要部分。

将 LangChain4j OpenAI 添加到我们的项目中

与所有 Java 项目一样，这只是一个依赖关系问题。这里我们将使用 Maven，但任何其他依赖管理器也可以实现同样的功能。

作为构建项目的第一步，我们将使用 OpenAI，因此只需添加langchain4j-open-ai 工具：

在其余代码中，我们将使用自己的 API 密钥（可通过注册OpenAI 账户获得），或者 LangChain4j 项目提供的 API 密钥（仅供演示使用）：

现在我们可以创建 ChatLanguageModel 的实例：

最后，我们可以问一个简单的问题，并得到答案：

给出的答案可能是这样的

如果您想运行这段代码，请查看Step1AiChatTest.java类。

使用 langchain4j 提供更多语境

让我们添加langchain4j 手工艺品：

它提供了一个工具集，可以帮助我们建立更高级的 LLM 集成，以构建我们的助手。在这里，我们只需创建一个Assistant 接口，该接口提供的chat 方法将自动调用我们之前定义的ChatLanguageModel ：

我们只需请求 LangChain4jAiServices 类为我们构建一个实例：

然后调用chat(String) 方法：

这与之前的行为相同。那么，我们为什么要修改代码呢？首先，它更优雅，但更重要的是，你现在可以使用简单的注释向 LLM 发出一些指示：

这就是现在的奉献：

如果您想运行这段代码，请查看Step2AssistantTest.java类。

转到另一个 LLM：langchain4j-ollama

我们可以利用伟大的奥拉马项目。在本地计算机上运行 LLM 会有帮助。

让我们添加langchain4j-ollama 手工艺品：

由于我们要使用测试来运行示例代码，因此让我们在项目中添加Testcontainers：

现在我们可以启动/停止 Docker 容器了：

我们只需"，" ，将model 对象改为OllamaChatModel ，而不是之前使用的OpenAiChatModel ：

请注意，提取图像及其模型可能需要一些时间，但一段时间后，您就可以得到答案了：

记忆力更好

如果我们提出多个问题，系统默认情况下不会记住之前的问题和答案。因此，如果我们在第一个问题之后提问"他是什么时候出生的？" 、我们的应用程序会回答：

这是无稽之谈。相反，我们应该使用聊天记忆：

现在运行同样的问题就能得到有意义的答案：

结论

在下一篇文章中，我们将了解如何使用 Elasticsearch 作为嵌入存储，向我们的私有数据集提问。这将为我们提供一种方法，使我们的应用程序搜索工作更上一层楼。

欢迎阅读我们关于高级 RAG 技术文章的第二部分！在本系列的第 1 部分中，我们建立、讨论并实施了高级 RAG 管道的数据处理组件：

在这一部分，我们将继续查询和测试我们的实现。让我们直奔主题！

目录

• 搜索和检索，生成答案

  • 用同义词丰富查询

  • HyDE（假设文档嵌入）

  • 混合搜索

• 实验

  • 结果摘要

  • 测试 1：谁审核了 Elastic？

    • AdvancedRAG

    • SimpleRAG

  • 测试 2：2023 年总收入

    • AdvancedRAG

    • SimpleRAG

  • 测试 3：增长主要依赖于什么产品？多少钱？

    • AdvancedRAG

    • SimpleRAG

  • 测试 4：说明员工福利计划

    • AdvancedRAG

    • SimpleRAG

  • 测试 5：Elastic 收购了哪些公司？

    • AdvancedRAG

    • SimpleRAG

• 结论

• 附录

  • 提示

    • RAG 问题解答提示

    • 弹性查询生成器提示

    • 潜在问题生成器提示

    • HyDE 生成器提示

  • 混合搜索查询示例

搜索和检索，生成答案

让我们提出第一个问题，最好是主要在年度报告中找到的一些信息。怎么样？

现在，让我们运用一些技术来增强查询。

用同义词丰富查询

首先，让我们增强查询措辞的多样性，并将其转化为可轻松处理成 Elasticsearch 查询的形式。我们将借助 GPT-4o 将查询转换为 OR 子句列表。让我们来写下这个提示：

当应用到我们的查询时，GPT-4o 会生成基本查询和相关词汇的同义词。

在ESQueryMaker 类中，我定义了一个分割查询的函数：

它的作用是将这串 OR 子句拆分成一个术语列表，使我们能够对关键文档字段进行多重匹配：

最后得出了这个疑问：

这比原始查询涵盖的范围更广，有望降低因忘记同义词而错过搜索结果的风险。但我们可以做得更多。

返回顶部

HyDE（假设文档嵌入）

让我们再次利用 GPT-4o 来实现HyDE。

HyDE 的基本前提是生成一个假设文档--一种可能包含原始查询答案的文档。文件的真实性或准确性并不重要。有鉴于此，让我们写下下面的提示：

由于矢量搜索通常是通过余弦矢量相似性进行操作的，因此 HyDE 的前提是，我们可以通过文档与文档的匹配，而不是查询与文档的匹配，来获得更好的结果。

我们关心的是结构、流程和术语。事实性不强。GPT-4o 可以输出这样的 HyDE 文档：

它看起来非常可信，是我们希望索引的文档类型的理想候选者。我们将把它嵌入并用于混合搜索。

返回顶部

混合搜索

这是我们搜索逻辑的核心。我们的词法搜索组件将是生成的 OR 子句字符串。我们的密集矢量组件将是嵌入式 HyDE 文档（又称搜索矢量）。我们使用 KNN 来有效识别与搜索向量最接近的几个候选文档。我们将词法搜索组件默认称为TF-IDF 和 BM25 评分。最后，将采用Wang 等人推荐的 30/70 比例合并词性和密集向量得分。

最后，我们可以拼凑出一个 RAG 函数。我们的 RAG（从询问到答复）将遵循这一流程：

1. 将查询转换为 OR 子句。

2. 生成 HyDE 文档并嵌入。

3. 将二者作为混合搜索的输入。

4. 检索前 N 个结果，将它们倒转，使最相关的得分是 LLM 上下文内存中"最近的" （反向打包） 反向打包示例：查询："Elasticsearch 查询优化技术" 检索文档（按相关性排序）： LLM 上下文的反向顺序： 通过颠倒顺序，最相关的信息(1)会出现在上下文的最后，从而可能在生成答案时受到 LLM 的更多关注。

   1. "使用 bool 查询可有效组合多个搜索条件。"

   2. "实施缓存策略，缩短查询响应时间。"

   3. "优化索引映射，提高搜索性能。"

   4. "优化索引映射，提高搜索性能。"

   5. "实施缓存策略，缩短查询响应时间。"

   6. "使用 bool 查询可有效组合多个搜索条件。"

5. 将上下文传递给 LLM 生成。

让我们运行查询并得到答案：

不错。没错。

返回顶部

实验

现在有一个重要问题需要回答。我们在这些实施中投入了如此多的精力和额外的复杂性，究竟得到了什么？

让我们来做个小小的比较。我们实施的 RAG 管道与基线混合搜索相比，没有任何增强功能。我们将进行一系列小测试，看看是否会发现任何实质性差异。我们将把刚刚实现的 RAG 称为 AdvancedRAG，把基本管道称为 SimpleRAG。

结果摘要

本表总结了两种 RAG 管道的五次测试结果。我根据答案的细节和质量来判断每种方法的相对优劣，但这完全是主观判断。现将实际答案转载于下表，供您参考。说了这么多，让我们来看看他们的表现如何！

SimpleRAG 无法回答问题 1& 5。AdvancedRAG 对问题 2、3 和 4 的回答也要详细得多。基于更多的细节，我认为 AdvancedRAG 的答案质量更高。

测试

问题

高级 RAG 性能

SimpleRAG 性能

AdvancedRAG 延迟

SimpleRAG 延迟

优胜者

1

谁审核 Elastic？

正确确定普华永道为审计员。

未能确定审计员。

11.6s

4.4s

AdvancedRAG

2

2023 年的总收入是多少？

提供了正确的收入数字。包括往年收入的补充情况。

提供了正确的收入数字。

13.3s

2.8s

AdvancedRAG

3

增长主要依靠什么产品？多少钱？

正确指出弹性云是关键驱动因素。包括总体收入情况& 。

正确指出弹性云是关键驱动因素。

14.1s

12.8s

AdvancedRAG

4

说明员工福利计划

全面介绍了退休计划、医疗计划和其他福利。包括不同年份的具体捐款额。

提供了很好的福利概览，包括薪酬、退休计划、工作环境和 Elastic Cares 计划。

26.6s

11.6s

AdvancedRAG

5

Elastic 收购了哪些公司？

正确列出了报告中提到的近期收购（CmdWatch、Build Security 和 Optimyze）。提供了一些收购日期和收购价格。

未能从提供的上下文中检索到相关信息。

11.9s

2.7s

AdvancedRAG

测试 1：谁审核了 Elastic？

AdvancedRAG

SimpleRAG

摘要：SimpleRAG 没有将普华永道确定为审计机构

好吧，这其实挺让人惊讶的。这看起来像是 SimpleRAG 的搜索失败。没有检索到与审计有关的文件。让我们在下一个测试中降低难度。

测试 2：2023 年总收入

AdvancedRAG

SimpleRAG

摘要：两个 RAG 都得到了正确答案：2023 年总收入为 1,068,989,000 美元

他们都在这里。看来，AdvancedRAG 可能获得了更多的文件？当然，答案会更加详细，并包含往年的信息。考虑到我们所做的改进，这是意料之中的，但现在下结论还为时过早。

让我们提高难度。

测试 3：增长主要依赖于什么产品？多少钱？

AdvancedRAG

SimpleRAG

摘要：两个 RAG 都正确地将弹性云确定为主要增长动力。不过，AdvancedRAG 包含更多细节，将订阅收入和客户增长考虑在内，并明确提及其他 Elastic 产品。

测试 4：说明员工福利计划

AdvancedRAG

SimpleRAG

摘要：AdvancedRAG 更深入、更详细地介绍了美国员工的 401K 计划，以及美国以外地区的缴费计划。报告还提到了 "健康与福利计划"，但没有提到 SimpleRAG 提到的 "Elastic Cares 计划"。

测试 5：Elastic 收购了哪些公司？

AdvancedRAG

SimpleRAG

摘要：SimpleRAG 无法检索到任何有关收购的相关信息，导致回答失败。AdvancedRAG 正确地列出了 CmdWatch、Build Security 和 Optimyze，它们是报告中列出的主要收购项目。

返回顶部

结论

根据我们的测试，我们的先进技术似乎增加了所提供信息的范围和深度，有可能提高 RAG 答案的质量。

此外，可靠性也可能有所提高，因为 AdvancedRAG 可以正确回答Which companies did Elastic acquire? 和Who audits Elastic 等措辞含糊的问题，而 SimpleRAG 则不能。

不过，值得注意的是，在 5 个案例中的 3 个案例中，基本的 RAG 管道（包括混合搜索，但不包括其他技术）设法得出了能够捕捉到大部分关键信息的答案。

我们应该注意到，由于在数据准备和查询阶段加入了 LLM，AdvancedRAG 的延迟一般是 SimpleRAG 的 2-5 倍。这是一笔不小的费用，可能使 AdvancedRAG 只适用于优先考虑应答质量而不是延迟的情况。

在数据准备阶段，使用 Claude Haiku 或 GPT-4o-mini 等更小巧、更便宜的 LLM，就能减轻巨大的延迟成本。将高级模型留待生成答案时使用。

这与 Wang 等人的研究结果一致。结果表明，任何改进都是相对渐进的。简而言之，简单的基线 RAG 就能让您获得大部分体面的最终产品，而且成本更低，速度更快。对我来说，这是一个有趣的结论。对于速度和效率至关重要的使用案例，SimpleRAG 是明智的选择。对于需要榨取每一滴性能的使用案例，AdvancedRAG 中包含的技术可能会提供一条出路。

返回顶部

附录

提示

RAG 问题解答提示

提示 LLM 根据查询和上下文生成答案。

弹性查询生成器提示

提示使用同义词丰富查询内容，并将其转换为 OR 格式。

潜在问题生成器提示

提示生成潜在问题，丰富文件元数据。

HyDE 生成器提示

使用 HyDE 生成假设文档的提示

混合搜索查询示例

最近发表的论文《在检索增强生成中寻找最佳实践》对各种 RAG 增强技术的功效进行了实证评估，目的是为 RAG 找到一套最佳实践。

我们将实施其中一些建议的最佳实践，即旨在提高搜索质量的实践（句子分块、HyDE、反向打包）。

为简洁起见，我们将省略那些侧重于提高效率的技术（查询分类和摘要）。

我们还将实施一些未涉及但我个人认为有用且有趣的技术（元数据包含、复合多字段嵌入、查询丰富化）。

最后，我们将进行一个简短的测试，看看搜索结果和生成答案的质量与基线相比是否有所提高。让我们开始吧！

RAG 概览

RAG 的目的是通过检索外部知识库中的信息来丰富生成的答案，从而增强 LLM。通过提供特定领域的信息，LLM 可以快速适应训练数据范围之外的用例；比微调成本低得多，也更容易保持更新。

提高 RAG 质量的措施通常集中在两个方面：

1. 提高知识库的质量和清晰度。

2. 提高搜索查询的覆盖面和针对性。

这两项措施将实现提高法律硕士获得相关事实和信息的几率的目标，从而减少产生幻觉或利用自身知识的可能性--这些知识可能已经过时或不相关。

方法的多样性难以用几句话说清楚。为了更清楚地说明问题，让我们直接进入实施阶段。

目录

• 概述

  • 目录

• 设置

• 摄取、处理和嵌入文件

  • 数据采集

  • 句子级标记分块

  • 元数据的纳入和生成

    • 通过 TextRank 提取的关键词

    • GPT-4o 提出的潜在问题

    • Spacy 提取的实体

  • 复合多场嵌入

    • 索引至弹性

• 猫休息

• 附录

  • 定义

设置

所有代码均可 在 Searchlabs 软件仓库中找到 。

先说第一件事。您需要以下材料

1. 弹性云部署

2. LLM 应用程序接口--我们在本笔记本中使用了 Azure OpenAI 上的 GPT-4o 部署

3. Python 3.12.4 或更高版本

我们将运行 main.ipynb 笔记本 中的所有代码 。

继续 git 克隆该 repo，导航至 supporting-blog-content/Advanced-rag-techniques，然后运行以下命令：

完成后，创建一个.env文件，并填写以下字段（在.env.example 中引用）。感谢我的合著者 Claude-3.5 提出的有益意见。

接下来，我们将选择要摄取的文档，并将其放在文档文件夹中。在本文中，我们将使用 Elastic N.V. 的《 2023 年年度报告》 。这是一份相当具有挑战性的密集文件，非常适合对我们的 RAG 技术进行压力测试。

现在我们都准备好了，开始摄入。打开main.ipynb，执行前两个单元格以导入所有软件包并初始化所有服务。

返回顶部

摄取、处理和嵌入文件

数据采集

• 个人感言：LlamaIndex 的便利性令我震惊。在还没有 LLM 和 LlamaIndex 的年代，录入各种格式的文档是一个痛苦的过程，需要从各处收集深奥的软件包。现在只需调用一个函数。狂野

SimpleDirectoryReader 将加载directory_path. 文件中的每个文档。对于.pdf 文件，它会返回一个文档对象列表，我将其转换为 Python 字典，因为我觉得它们更容易处理。

每个字典都包含text 字段中的关键内容。它还包含有用的元数据，如页码、文件名、文件大小和类型。

返回顶部

句子级标记分块

首先要做的是将我们的文件缩减成标准长度的块状（以确保一致性和可管理性）。嵌入模型有独特的标记限制（可处理的最大输入尺寸）。标记是模型处理文本的基本单位。为防止信息丢失（内容截断或遗漏），我们应提供不超过这些限制的文本（将较长的文本分割成较小的片段）。

分块对性能有重大影响。在理想情况下，每个信息块都代表一个独立的信息片段，捕捉有关单个主题的上下文信息。分块方法包括字级分块（按字数分割文档）和语义分块（使用 LLM 识别逻辑断点）。

单词级的分块处理成本低、速度快、操作简单，但存在拆分句子从而破坏上下文的风险。语义分块的速度越来越慢，成本越来越高，尤其是在处理像116页的《弹性年度报告》这样的文档时。

让我们选择一种中间路线。句子级分块仍然简单，但比单词级分块能更有效地保留上下文，而且成本更低，速度更快。此外，我们还将采用一个滑动窗口来捕捉周围的一些上下文，并减轻分割段落的影响。

Chunker 类采用嵌入模型的标记化器对文本进行编码和解码。现在，我们将构建每块 512 个令牌的分块，其中有 20 个令牌重叠。为此，我们会将文本分割成句子，对这些句子进行标记化处理，然后将标记化处理后的句子添加到当前语块中，直到无法在不超出标记限制的情况下添加更多句子为止。

最后，将句子解码回原始文本进行嵌入，将其存储在名为original_text 的字段中。数据块存储在一个名为chunk 的字段中。为了减少噪音（又称无用文件），我们将丢弃长度小于 50 个 token 的文件。

让我们在文件上运行一下：

然后得到类似这样的文本块：

返回顶部

元数据的纳入和生成

我们已将文件分块。现在是丰富数据的时候了。我想生成或提取额外的元数据。这些附加元数据可用于影响和提高搜索性能。

我们将定义一个DocumentEnricher 类，它的作用是接收文档列表（Python 字典）和处理器函数列表。这些函数将在文档的original_text 列中运行，并将其输出存储在新字段中。

首先，我们使用TextRank 提取关键词。TextRank 是一种基于图的算法，它能根据词与词之间的关系对关键短语和句子的重要性进行排序，从而从文本中提取关键短语和句子。

接下来，我们将使用 GPT-4o 生成 potential_questions。

最后，我们将使用 Spacy 提取实体 。

由于每项工作的代码都相当冗长和复杂，我就不在此赘述了。如果您感兴趣，这些文件已在下面的代码示例中标出。

让我们运行数据浓缩：

看看结果吧：

通过 TextRank 提取的关键词

这些关键短语是大块核心主题的替身。如果查询与网络安全有关，这块内容的得分就会提高。

GPT-4o 提出的潜在问题

这些潜在问题可能与用户查询直接匹配，从而提高得分。我们会提示 GPT-4o 生成一些问题，这些问题可以用当前语块中的信息来回答。

Spacy 提取的实体

这些实体的作用与关键词类似，但可以捕捉到组织和个人的名称，而关键词提取可能会遗漏这些名称。

返回顶部

复合多场嵌入

现在，我们已经用更多的元数据丰富了我们的文档，我们可以利用这些信息创建更强大、更能感知上下文的嵌入。

让我们回顾一下目前的进程。我们在每份文档中都有四个关注领域。

每个字段都代表了对文件背景的不同看法，可能突出了法律硕士应重点关注的关键领域。

我们的计划是嵌入每个字段，然后创建嵌入的加权和，即复合嵌入。

幸运的话，除了引入另一个可调整的超参数来控制搜索行为外，这种复合嵌入还能让系统变得更加了解上下文。

首先，让我们使用在 main.ipynb 笔记本开头导入的本地定义的嵌入模型，嵌入每个字段并就地更新每个文档。

每个嵌入函数都会返回嵌入的字段，即带有_embedding 后缀的原始输入字段。

现在我们来定义复合嵌入的权重：

通过权重，您可以根据用例和数据质量为每个组件分配优先级。直观地说，这些权重的大小取决于每个组件的语义值。由于大块文本本身的内容迄今为止最为丰富，我将其权重定为 70% 。由于实体最小，只是一个组织或个人名称列表，因此我将其权重定为 5% 。这些值的精确设置必须根据具体情况，根据经验来确定。

最后，让我们编写一个函数来应用权重，并创建我们的复合嵌入。为了节省空间，我们还将删除所有的组件嵌入。

至此，我们完成了文件处理工作。现在我们有了一个文档对象列表，看起来像这样：

索引至弹性

让我们将文档批量上传到 Elastic Search。为此，我很早就在elastic_helpers.py 中定义了一组 Elastic Helper 函数。这是一段非常冗长的代码，所以我们还是只看函数调用。

es_bulk_indexer.bulk_upload_documents 利用 Elasticsearch 方便的动态映射，可以处理任何字典对象列表。

前往 Kibana，确认所有文件都已编入索引。应该有 224 个。对于这么大的文件来说，还算不错！

返回顶部

猫休息

我们休息一下吧，文章有点沉重，我知道。看看我的猫

真可爱帽子不见了，我半信半疑是她偷藏起来的：(

祝贺你们走到这一步 :)

请看第二部分，了解我们对 RAG 管道的测试和评估！

附录

定义

1.句子分块

• RAG 系统中使用的一种预处理技术，用于将文本划分为更小的、有意义的单元。

• 过程：

  1. 输入：大段文本（如文档、段落）

  2. 输出：较小的文本片段（通常是句子或小句子组）

• 目的是

  • 创建细粒度、针对特定上下文的文本片段

  • 允许更精确的索引和检索

  • 提高 RAG 系统检索信息的相关性

• 特点

  • 分段具有语义意义

  • 可独立索引和检索

  • 通常保留一些上下文，以确保独立的可理解性

• 优势：

  • 提高检索精度

  • 使 RAG 管道的扩容更有针对性

2.HyDE（假设文档嵌入）

• 在 RAG 系统中使用 LLM 生成用于查询扩展的假设文档的技术。

• 过程：

  1. 向 LLM 输入查询

  2. LLM 生成回答查询的假设文档

  3. 嵌入生成的文件

  4. 使用嵌入进行向量搜索

• 主要区别

  • 传统 RAG：将查询与文档匹配

  • HyDE：将文档匹配到文档

• 目的是

  • 提高检索性能，尤其是复杂或模糊查询的检索性能

  • 捕捉比简短查询更丰富的语义上下文

• 优势：

  • 利用 LLM 的知识扩展查询

  • 有可能提高检索文件的相关性

• 挑战：

  • 需要额外的 LLM 推理，增加了延迟和成本

  • 性能取决于生成的假设文件的质量

3.反向包装

• RAG 系统中使用的一种技术，用于在将搜索结果传递给 LLM 之前对其重新排序。

• 过程：

  1. 搜索引擎（如 Elasticsearch）按相关性降序返回文档。

  2. 顺序颠倒，将最相关的文件放在最后。

• 目的是

  • 利用 LLM 的新旧偏差，LLM 往往更关注其上下文中的最新信息。

  • 确保最相关的信息"最新鲜的" 在 LLM 的上下文窗口中。

• 举例说明：原始顺序：[最相关、第二最相关、第三最相关、......] 倒序：[......，最重要的第三项，最重要的第二项，最相关的］

4.查询分类

• 通过确定查询是需要 RAG 还是可以直接由 LLM 回答来优化 RAG 系统效率的技术。

• 过程：

  1. 针对使用中的 LLM 开发定制数据集

  2. 训练专门的分类模型

  3. 使用模型对收到的查询进行分类

• 目的是

  • 避免不必要的 RAG 处理，提高系统效率

  • 将查询引导至最合适的响应机制

• 要求：

  • LLM 专用数据集和模型

  • 不断改进以保持准确性

• 优势：

  • 减少简单查询的计算开销

  • 有可能缩短非 RAG 查询的响应时间

5.总结

• 在 RAG 系统中压缩检索文档的技术。

• 过程：

  1. 检索相关文件

  2. 生成每份文件的简明摘要

  3. 在 RAG 管道中使用摘要而非完整文件

• 目的是

  • 关注基本信息，提高 RAG 性能

  • 减少不相关内容的噪音和干扰

• 优势：

  • 有可能提高 LLM 答复的相关性

  • 允许在上下文限制内纳入更多文件

• 挑战：

  • 总结时有可能丢失重要细节

  • 生成摘要的额外计算开销

6.元数据的纳入

• 一种用额外的上下文信息来丰富文档的技术。

• 元数据类型：

  • 关键词

  • 标题

  • 日期

  • 作者详细信息

  • 简介

• 目的是

  • 增加 RAG 系统可用的背景信息

  • 让法律硕士更清楚地了解文件内容和相关性

• 优势：

  • 有可能提高检索的准确性

  • 提高法律硕士评估文件实用性的能力

• 实施：

  • 可在文件预处理过程中完成

  • 可能需要额外的数据提取或生成步骤

7.复合多字段嵌入

• RAG 系统的高级嵌入技术，可为不同的文档组件创建单独的嵌入。

• 过程：

  1. 确定相关字段（例如标题、关键词、简介、主要内容）

  2. 为每个字段生成单独的嵌入

  3. 合并或存储这些嵌入信息，以用于检索

• 与标准方法的区别：

  • 传统：对整个文档进行单一嵌入

  • 复合：针对不同文档方面的多重嵌入

• 目的是

  • 创建更细致入微、更能感知上下文的文档表示法

  • 在文件中获取更多来源的信息

• 优势：

  • 有可能提高模糊或多方面查询的性能

  • 允许在检索中更灵活地加权不同的文件内容

• 挑战：

  • 嵌入存储和检索流程的复杂性增加

  • 可能需要更复杂的匹配算法

8.丰富查询

• 一种用相关术语扩展原始查询以提高搜索覆盖率的技术。

• 过程：

  1. 分析原始查询

  2. 生成同义词和语义相关的短语

  3. 用这些附加术语来扩展查询

• 目的是

  • 增加文件语料库中潜在匹配的范围

  • 提高使用特定或技术语言查询的检索性能

• 优势：

  • 可能检索到与原始查询条件不完全匹配的相关文档

  • 有助于克服查询和文档之间的词汇不匹配问题

• 挑战：

  • 如果不认真执行，则有查询偏移的风险

  • 可能会增加检索过程中的计算开销

返回顶部

在本篇文章中，我们将探讨在 RAG（检索增强生成）流程中使用公共 LLM 时保护个人身份信息 (PII) 和敏感数据的方法。我们将探索使用开源库和正则表达式屏蔽 PII 和敏感数据，以及在调用公共 LLM 之前使用本地 LLM 屏蔽数据。

在开始之前，让我们回顾一下我们在本篇文章中使用的一些术语。

术语

LlamaIndex是用于构建 LLM（大型语言模型）应用程序的领先数据框架。LlamaIndex 为构建 RAG（检索增强生成）应用程序的各个阶段提供了抽象概念。像 LlamaIndex 和 LangChain 这样的框架提供了抽象，因此应用程序不会与任何特定 LLM 的应用程序接口紧密耦合。

Elasticsearch由Elastic 提供。Elastic 是 Elasticsearch 背后的行业领导者，Elasticsearch 是一个可扩展的数据存储和矢量数据库，支持精确的全文搜索、语义理解的矢量搜索以及两全其美的混合搜索。Elasticsearch 是一个分布式 RESTful 搜索和分析引擎、可扩展数据存储和矢量数据库。我们在本博客中使用的 Elasticsearch 功能在 Elasticsearch 的免费开放版本中提供。

检索增强生成（RAG）是一种人工智能技术/模式，在这种模式下，LLM 可以利用外部知识生成对用户查询的回复。这样，法律硕士的答复就可以根据具体情况量身定做，而不是泛泛而谈。

嵌入是文本/媒体意义的数字表示。它们是高维信息的低维表示。

RAG 和数据保护

一般来说，大型语言模型（LLM）善于根据模型中的可用信息生成响应，而这些信息可能是在互联网数据上训练出来的。然而，对于那些模型中没有信息的查询，则需要向法律硕士提供模型中没有的外部知识或具体细节。这些信息可能存在于您的数据库或内部知识系统中。检索增强生成（RAG）是一种技术，对于给定的用户查询，首先从外部（LLM）系统（如数据库）检索相关的上下文/信息，然后将上下文与用户查询一起发送给 LLM，以生成更具体、更相关的响应。

这使得 RAG 技术在问题解答、内容创建以及任何有利于深入理解上下文和细节的应用中都非常有效。

因此，在 RAG 管道中，您有可能将 PII（个人身份信息）等内部信息和敏感信息（如姓名、出生日期、账号等）暴露给公共 LLM。

虽然在使用 Elasticsearch 等矢量数据库时，数据是安全的（通过各种杠杆，如基于角色的访问控制、文档级安全等），但在向外部公共 LLM 发送数据时必须小心谨慎。

在使用大型语言模型 (LLM) 时，出于多种原因，保护个人身份信息 (PII) 和敏感数据至关重要：

• 隐私合规：许多地区都有严格的法规，如欧洲的《通用数据保护条例》（GDPR）或美国的《加利福尼亚消费者隐私法》（CCPA），这些法规都要求保护个人数据。要避免法律后果和罚款，就必须遵守这些法律。

• 用户信任：确保敏感信息的保密性和完整性可建立用户信任。用户更愿意使用他们认为能保护其隐私的系统，并与之互动。

• 数据安全：防止数据泄露至关重要。如果没有足够的保障措施，暴露在法律硕士面前的敏感数据很容易被窃取或滥用，从而导致身份被盗或金融欺诈等潜在危害。

• 道德方面的考虑：从道德角度讲，尊重用户隐私并负责任地处理他们的数据非常重要。对 PII 处理不当会导致歧视、侮辱或其他负面社会影响。

• 企业声誉：未能保护敏感数据的公司可能会声誉受损，这可能会对其业务造成长期负面影响，包括失去客户和收入。

• 减少滥用风险：安全处理敏感数据有助于防止对数据或模型的恶意使用，例如在有偏见的数据上训练模型，或利用数据操纵或伤害个人。

总之，为了确保法律合规、维护用户信任、确保数据安全、坚持道德标准、保护企业声誉和降低滥用风险，必须对 PII 和敏感数据进行强有力的保护。

快速回顾

在上一篇文章中，我们讨论了如何使用 RAG 技术，将 Elasticsearch 作为向量数据库，同时使用 LlamaIndex 和本地运行的 Mistral LLM 来实现 Q&A 体验。在此基础上，我们将继续努力。

阅读上一篇文章是可有可无的，因为我们现在将快速讨论/复述上一篇文章中的内容。

我们有一个样本数据集，内容是一家虚构的家庭保险公司的座席人员与客户之间的呼叫中心对话。我们开发了一个简单的 RAG 应用程序，可以回答 "客户因哪些与水有关的问题而提出索赔 "等问题。

从高度上看，流程是这样的。

在索引阶段，我们使用 LlamaIndex 管道加载并索引文档。文档被分块并连同其嵌入一起存储在 Elasticsearch 向量数据库中。

在查询阶段，当用户提出问题时，LlamaIndex 会检索与查询相关的前 K 个相似文档。这些排名前 K 位的相关文档连同查询结果被发送到本地运行的 Mistral LLM，然后由其生成响应并发送回用户。请随时查看上一篇文章或探索代码。

在上一篇文章中，我们在本地运行了 LLM。不过，在生产过程中，您可能希望使用OpenAI、Mistral、Anthropic等公司提供的外部 LLM。这可能是因为您的使用案例需要一个更大的基础模型，或者由于企业生产的需要（如可扩展性、可用性、性能等），在本地运行不是一种选择。

在 RAG 管道中引入外部 LLM 会使您面临不慎将敏感和 PII 泄露给 LLM 的风险。在本篇文章中，我们将探讨如何在将文档发送给外部法律硕士之前，将 PII 信息屏蔽作为 RAG 管道的一部分。

持有公共法学硕士学位的 RAG

在讨论如何在 RAG 管道中保护 PII 和敏感信息之前，我们将首先使用 LlamaIndex、Elasticsearch 向量数据库和 OpenAI LLM 构建一个简单的 RAG 应用程序。

准备工作

我们需要以下材料

• 运行Elasticsearch作为向量数据库来存储嵌入。按照上一篇文章中关于安装 Elasticsearch 的说明进行操作。

• 开放人工智能应用程序接口密钥。

简单的 RAG 应用

整个代码可在Github Repository（branch:protection-pii）中找到，以供参考。克隆该 repo 是可选的，因为我们将在下文中详细介绍代码。

在您最喜欢的集成开发环境中，用以下 3 个文件创建一个新的 Python 应用程序。

• index.py 与索引数据有关的代码的位置。

• query.py 与查询和 LLM 交互相关的代码都放在这里。

• .env 配置属性（如 API 密钥）的位置。

我们需要安装一些软件包。首先，我们要在应用程序的根文件夹中创建一个新的 python虚拟环境。

激活虚拟环境并安装以下所需软件包。

在 .env 中配置 OpenAI 和 Elasticsearch 连接属性锉刀

索引数据

下载conversations.json文件，其中包含客户与我们虚构的房屋保险公司呼叫中心座席之间的对话。将该文件与 2 个 python 文件和 .env 文件一起放在应用程序的根目录中。文件。下面是该文件内容的示例。

在index.py 中粘贴下面的代码，该代码负责索引数据。

运行上述代码可看到在 Elasticsearch 中创建了一个索引，将嵌入信息存储在名为convo_index 的 Elasticsearch 索引中。

如果您需要有关 LlamaIndex IngestionPipeline 的解释，请参阅上一篇文章中的创建 IngestionPipeline 部分。

查询

在上一篇文章中，我们使用了本地 LLM 进行查询。

在本篇文章中，我们将使用公共 LLM OpenAI，如下所示。

上述代码将打印 OpenAI 的响应如下。

客户提出了各种与水有关的索赔，包括地下室水渍、水管爆裂、冰雹对屋顶造成的损坏等问题，以及由于未及时通知、维护问题、逐渐磨损和原有损坏等原因造成的拒赔。在每个案例中，客户都对索赔被拒表示沮丧，并寻求对其索赔进行公平的评估和决定。

在 RAG 中屏蔽 PII

到目前为止，我们所做的工作是将文档原样连同用户查询一起发送给 OpenAI。

在 RAG 管道中，从矢量存储中检索到相关上下文后，我们有机会在将查询和上下文发送到 LLM 之前屏蔽 PII 和敏感信息。

在向外部法律硕士发送 PII 信息之前，有多种方法可以掩盖 PII 信息，每种方法都有自己的优点。下面我们来看看其中的一些选择

1. 使用 spacy.io 或Presidio（微软维护的开源库）等 NLP 库。

2. 使用开箱即用的 LlamaIndex NERPIINodePostprocessor.

3. 通过 PIINodePostprocessor

使用上述任何一种方法实现屏蔽逻辑后，您就可以使用后处理器（您自己定制的后处理器或 LlamaIndex 开箱即用的后处理器）配置 LlamaIndex 的 IngestionPipeline。

使用 NLP 库

作为 RAG 管道的一部分，我们可以使用 NLP 库屏蔽敏感数据。我们将在本演示中使用 spacy.io 软件包。

创建一个新文件query_masking_nlp.py 并添加以下代码。

法律硕士的答复如下。

在上述代码中，当创建 Llama 索引查询引擎时，我们提供了一个 CustomPostProcessor。

QueryEngine 调用的逻辑在CustomPostProcessor 的_postprocess_nodes 方法中定义。我们正在使用 SpaCy.io 库来检测文件中的命名实体，然后使用一些正则表达式来替换这些名称以及敏感信息，然后再将文件发送到 LLM。

以下是自定义 PostProcessor 创建的原始会话和屏蔽会话的部分示例。

原文如此：

由 CustomPostProcessor 生成的屏蔽文本。

请注意：

识别和屏蔽 PII 和敏感信息并不是一项简单的任务。要涵盖敏感信息的各种格式和语义，就必须充分了解自己的领域和数据。虽然上述代码可能适用于某些使用情况，但您可能需要根据自己的需求和测试情况进行修改。

使用开箱即用的 LlamaIndex NERPIINodePostprocessor

LlamaIndex 通过引入以下功能，使保护 RAG 管道中的 PII 信息变得更加容易 NERPIINodePostprocessor.

答复如下

通过 PIINodePostprocessor

我们还可以利用本地或专用网络中运行的 LLM，在将数据发送到公共 LLM 之前完成屏蔽工作。

我们将使用运行在本地机器 Ollama 上的 Mistral 来进行屏蔽。

本地运行 Mistral

下载并安装Ollama。安装 Ollama 后，运行此命令下载并运行mistral

首次下载并在本地运行模型可能需要几分钟时间。通过提出类似下面 "写一首关于云的诗 "的问题来验证 mistral 是否在运行，并验证诗歌是否符合您的要求。保持 ollama 运行，因为我们稍后需要通过代码与 mistral 模型交互。

新建一个名为query_masking_local_LLM.py 的文件，并添加以下代码。

响应如下所示

结论

在这篇文章中，我们介绍了在 RAG 流程中使用公共 LLM 时如何保护 PII 和敏感数据。我们展示了实现这一目标的多种方法。强烈建议在采用这些方法之前，根据您的用例和需求对其进行测试。

在开始之前，我们先来了解一些术语。

术语

LlamaIndex是用于构建 LLM（大型语言模型）应用程序的领先数据框架。LlamaIndex 为构建 RAG（检索增强生成）应用程序的各个阶段提供了抽象概念。像 LlamaIndex 和 LangChain 这样的框架提供了抽象，因此应用程序不会与任何特定 LLM 的应用程序接口紧密耦合。

Elasticsearch由Elastic 提供。Elastic 是 Elasticsearch 背后的行业领导者，Elasticsearch 是一个搜索和分析引擎，支持精确的全文搜索、语义理解的矢量搜索以及两全其美的混合搜索。Elasticsearch 是一种可扩展的数据存储和矢量数据库。我们在本博客中使用的 Elasticsearch 功能在 Elasticsearch 的免费开放版本中提供。

检索增强生成（RAG）是一种人工智能技术/模式，它为 LLM 提供外部知识，以生成对用户查询的回复。这样，法律硕士的答复就可以根据具体情况量身定做，答复也更加具体。

Mistral提供开源和优化的企业级 LLM 模型。在本教程中，我们将使用可在笔记本电脑上运行的开源模型mistral-7b。如果你不想在笔记本电脑上运行模型，也可以使用他们的云版本，在这种情况下，你必须修改本博客中的代码，以使用正确的 API 密钥和软件包。

Ollama可帮助您在笔记本电脑上本地运行 LLM。我们将使用 Ollama 在本地运行开源的 Mistral-7b 模型。

嵌入是文本/媒体意义的数字表示。它们是高维信息的低维表示。

使用 LlamaIndex、Elasticsearch& Mistral 构建 RAG 应用程序：场景概述

场景

我们有一个样本数据集（JSON 文件），内容是一家虚构的家庭保险公司的座席人员与客户之间的呼叫中心对话。我们将建立一个简单的 RAG 应用程序，它可以回答以下问题

Give me summary of water related issues.

高位流量

我们使用 Ollama 在本地运行 Mistral LLM。

接下来，我们以Documents 的形式将 JSON 文件中的对话加载到ElasticsearchStore（由 Elasticsearch 支持的 VectorStore）中。在加载文档时，我们使用本地运行的 Mistral 模型创建嵌入。我们将这些嵌入和对话一起存储在 LlamaIndex Elasticsearch 向量存储（ElasticsearchStore）中。

我们配置一个 LlamaIndex IngestionPipeline，并向其提供我们使用的本地 LLM，在本例中是通过 Ollama 运行的 Mistral。

当我们提出 "请简要介绍与水有关的问题 "这样的问题时、Elasticsearch 可进行语义搜索，并返回与水问题有关的对话。这些对话与原始问题一起发送给本地运行的 LLM，以生成答案。

建立 RAG 应用程序的步骤

本地运行 Mistral

下载并安装Ollama。安装 Ollama 后，运行此命令下载并运行mistral

首次下载并在本地运行模型可能需要几分钟时间。通过提出类似下面 "写一首关于云的诗 "的问题来验证 mistral 是否在运行，并验证诗歌是否符合您的要求。保持 ollama 运行，因为我们稍后需要通过代码与 mistral 模型交互。

安装 Elasticsearch

通过创建云部署（在此说明）或在 docker 中运行（在此说明），启动并运行 Elasticsearch。您也可以从这里开始创建生产级的 Elasticsearch 自托管部署。

假设您使用的是云部署，请按照说明中的要求获取部署的 API 密钥和云 ID。我们稍后将使用它们。

RAG 申请

整个代码可在此Github 代码库中找到，以供参考。克隆 repo 是可选项，因为我们将在下文中介绍代码。

在您最喜欢的集成开发环境中，用以下 3 个文件创建一个新的 Python 应用程序。

• index.py 与索引数据有关的代码的位置。

• query.py 与查询和 LLM 交互相关的代码都放在这里。

• .env 配置属性（如 API 密钥）的位置。

我们需要安装一些软件包。首先，我们要在应用程序的根文件夹中创建一个新的 python虚拟环境。

激活虚拟环境并安装以下所需软件包。

索引数据

下载conversations.json文件，其中包含客户与我们 fictionaly 房屋保险公司呼叫中心座席之间的对话。将该文件与 2 个 python 文件和 .env 文件一起放在应用程序的根目录中。文件。下面是该文件内容的示例。

我们在index.py 中定义了一个名为get_documents_from_file 的函数，用于读取 json 文件并创建文档列表。文档对象是 LlamaIndex 处理信息的基本单位。

创建摄取管道

首先，将在Install Elasticsearch 部分获得的 Elasticsearch CloudID 和 API 密钥添加到.env 文件中。.env 文件应如下所示（使用真实值）。

通过 LlamaIndexIngestionPipeline，您可以使用多个组件组成一个管道。在index.py 文件中添加以下代码。

如前所述，LlamaIndex IngestPipeline 可由多个组件组成。我们将在pipeline = IngestionPipeline(... 行的管道中添加 3 个组件。

• SentenceSplitter：从get_documents_from_file() 的定义中可以看出，每个文档都有一个文本字段，用来保存 json 文件中的对话内容。该文本字段是一段较长的文本。为了使语义搜索工作顺利进行，需要将其分解成小块文本。SentenceSplitter类可以帮我们做到这一点。这些块在 LlamaIndex 术语中称为节点。节点中的元数据指向它们所属的文档。或者，也可以使用 Elasticsearch Ingestpipeline 进行分块，如本博客所示。

• OllamaEmbedding：嵌入模型可将一段文字转换成数字（也称为向量）。有了数字表示法，我们就可以进行语义搜索，搜索结果与词义相匹配，而不仅仅是进行文本搜索。我们为 IngestionPipeline 提供OllamaEmbedding("mistral") 。使用 SentenceSplitter 分割的语块会通过 Ollama 发送到本地机器上运行的 Mistral 模型，然后 mistral 会为这些语块创建嵌入。

• ElasticsearchStoreLlamaIndex ElasticsearchStore 向量存储会将正在创建的嵌入式内容备份到 Elasticsearch 索引中。ElasticsearchStore 负责创建和填充指定 Elasticsearch 索引的内容。在创建 ElasticsearchStore（由es_vector_store 引用）时，我们提供要创建的 Elasticsearch 索引的名称（本例中为calls ）、索引中要存储嵌入的字段（本例中为conversation_vector ）以及要存储文本的字段（本例中为conversation ）。总之，根据我们的配置ElasticsearchStore 在 Elasticsearch 中创建了一个新索引，并将conversation_vector 和conversation 作为字段（以及其他自动创建的字段）。

将这一切联系起来，我们通过调用pipeline.run(documents=documents) 运行管道。

运行 index.py 脚本执行摄取管道：

管道运行完成后，我们应该会在 Elasticsearch 中看到一个名为calls 的新索引。使用开发控制台运行一个简单的 elasticsearch 查询，就能看到数据和嵌入式内容一起加载。

概括地说，我们从 JSON 文件创建了文档，将文档分割成块，为这些块创建了嵌入，并将嵌入（和文本对话）存储在向量存储（ElasticsearchStore）中。

查询

llamaIndexVectorStoreIndex可以让你检索相关文档和查询数据。默认情况下，VectorStoreIndex 会将嵌入存储在SimpleVectorStore 的内存中。不过，也可以使用外部向量存储（如ElasticsearchStore）来使嵌入持久化。

打开query.py 并粘贴以下代码

我们定义了一个本地 LLM (local_llm) 来指向在 Ollama 上运行的 Mistral 模型。接下来，我们从之前创建的 ElasticssearchStore 向量存储中创建一个 VectorStoreIndex (index)，然后从索引中获取一个查询引擎。在创建查询引擎时，我们会引用本地 LLM 来进行响应，我们还会提供 (similarity_top_k=10) 来配置应从向量存储中检索并发送给 LLM 以获得响应的文档数量。

运行query.py 脚本执行 RAG 流程：

我们发送查询Give me summary of water related issues （可随意定制query ），法律硕士的回复应与提供的相关文件类似。

注意事项

这篇博文是关于使用 Elasticsearch 的 RAG 技术的初学者介绍，因此省略了一些功能配置，而这些功能配置将使您能够将这一起点应用到生产中。在构建生产用例时，您需要考虑更复杂的方面，如使用文档级安全保护数据，将数据分块作为 ElasticsearchIngest 管道的一部分，甚至在用于 GenAI/Chat/Q&A 用例的相同数据上运行其他ML 作业。

您还可以考虑使用Elastic Connectors 从各种外部来源（如 Azure Blob Storage、Dropbox、Gmail 等）获取数据并创建嵌入。

Elastic 可实现上述所有功能，并为 GenAI 用例及其他应用提供全面的企业级解决方案。

接下来呢？

• 您可能已经注意到，我们正在将 10 个相关会话与用户问题一起发送给 LLM，以便制定回复。这些对话可能包含 PII（个人身份信息），如姓名、出生日期、地址等。在我们的案例中，LLM 是本地的，因此数据泄漏不是问题。但是，如果您想使用在云中运行的 LLM（例如 OpenAI），则不宜发送包含 PII 信息的文本。在后续博客中，我们将介绍如何在向 RAG 流程中的外部 LLM 发送 PII 信息之前完成屏蔽。

• 在本篇文章中，我们使用了本地 LLM，在接下来的文章 "在 RAG 中屏蔽 PII 数据 "中，我们将介绍如何轻松地从本地 LLM 切换到公共 LLM。