在本篇文章中，我们将探讨如何使用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 上获取，请随意克隆和修补。现在，去赢得梦幻联赛吧！

我们将审查

• 生产最佳实践

  • 错误处理能力

  • 测试

• 无服务器环境

  • 在 Elastic Serverless 上运行客户端

  • 在功能即服务环境中运行客户端

您可以 在这里查看示例的源代码 。

生产最佳实践

Elasticsearch 中的错误处理

Node.js 中 Elasticsearch 客户端的一个有用功能是，它为 Elasticsearch 中可能出现的错误提供了对象，因此您可以用不同的方式验证和处理这些错误。

要查看全部内容，请执行此操作：

让我们回到搜索示例，处理一些可能出现的错误：

ResponseError 尤其是当答案为4xx 或5xx 时，即表示请求不正确或服务器不可用。

我们可以通过生成错误查询来测试这类错误，比如尝试在文本类型字段上进行术语查询：

默认错误：

定制错误：

我们还可以以某种方式捕捉和处理每种类型的错误。例如，我们可以在TimeoutError 中添加重试逻辑。

测试

测试是保证应用程序稳定性的关键。为了以一种与 Elasticsearch 隔离的方式测试代码，我们可以在创建集群时使用elasticsearch-js-mock库。

通过该库，我们可以实例化一个与真实客户端非常相似的客户端，但只需将客户端的 HTTP 层替换为模拟层，其他部分与原始客户端保持一致，就能满足我们的配置要求。

我们将安装 mocks 库和用于自动测试的AVA。

npm install @elastic/elasticsearch-mock

npm install --save-dev ava

我们将配置package.json 文件以运行测试。确保它看起来是这样的：

现在，让我们创建test.js 文件并安装我们的模拟客户端：

现在，为语义搜索添加一个模拟：

现在我们可以为代码创建一个测试，确保 Elasticsearch 部分始终返回相同的结果：

让我们进行测试。

npm run test

完成！从现在起，我们就可以测试我们的应用程序，100% 专注于代码而不是外部因素。

无服务器环境

如何在 Elastic Serverless 上运行客户端

我们介绍了在云端或内部运行 Elasticsearch 的情况；不过，Node.js 客户端也支持与Elastic Cloud Serverless 的连接。

Elastic Cloud Serverless 允许您创建一个项目，在这个项目中，您无需担心基础设施问题，因为 Elastic 会在内部处理这些问题，您只需担心您想索引的数据以及您想在多长时间内访问这些数据。

从使用角度来看，Serverless 将计算与存储分离，为搜索和索引提供了自动扩展功能。这样，您就可以只增长实际需要的资源。

客户端会进行以下调整，以连接到无服务器：

• 关闭嗅探，忽略任何与嗅探相关的选项

• 忽略配置中传递的除第一个节点外的所有节点，并忽略任何节点过滤和选择选项

• 启用压缩和 "TLSv1_2_method"（与为弹性云配置时相同）

• 为所有请求添加 "elastic-api-version "HTTP 头信息

• 默认使用 "云连接池"，而不是 "加权连接池

• 关闭卖方 "内容类型 "和 "接受 "标头，转而使用标准 MIME 类型

要连接无服务器项目，需要使用参数 serverMode：serverless。

如何在函数即服务环境中运行客户端

在示例中，我们使用了 Node.js 服务器，但您也可以使用功能即服务环境连接 AWS lambda、GCP Run 等功能。

另一个例子是连接像 Vercel 这样的服务，它也是无服务器的。您可以查看这个完整的示例，了解如何做到这一点，但搜索端点最相关的部分如下所示：

该端点位于 /api 文件夹中，从服务器端运行，因此客户端只能控制与搜索词相对应的 "文本 "参数。

使用 "功能即服务 "的意义在于，与全天候运行的服务器不同，功能只启动运行该功能的机器，一旦完成，机器就会进入休息模式，以减少资源消耗。

如果应用程序没有收到太多请求，这种配置会很方便；否则，成本会很高。您还需要考虑函数的生命周期和运行时间（在某些情况下可能只有几秒钟）。

结论

在本文中，我们学习了如何处理错误，这在生产环境中至关重要。我们还介绍了在模拟 Elasticsearch 服务的过程中测试应用程序的方法，无论集群的状态如何，这种方法都能提供可靠的测试，让我们专注于我们的代码。

最后，我们演示了如何通过配置 Elastic Cloud Serverless 和 Vercel 应用程序来启动完全无服务器堆栈。

在第一部分中，我们将回顾

• 环境

  • 前端、后端还是无服务器？

  • 连接客户端

• 编制文件索引

  • Elasticsearch 客户端

  • 语义映射

  • 批量助手

• 搜索数据

  • 词法查询

  • 语义查询

  • 混合查询

您可以 在这里查看示例的源代码 。

什么是 Elasticsearch Node.js 客户端？

Elasticsearch Node.js 客户端是一个 JavaScript 库，它将 Elasticsearch API 的 HTTP REST 调用放到了 JavaScript 中。这样就能更轻松地处理和使用帮助程序，简化批量编制文档索引等任务。

环境

前端、后端还是无服务器？

要使用 JavaScript 客户端创建搜索应用程序，我们至少需要两个组件：Elasticsearch 集群和运行客户端的 JavaScript 运行时。

JavaScript 客户端支持所有 Elasticsearch 解决方案（云、on-prem 和 Serverless），它们之间没有重大区别，因为客户端内部会处理所有变化，所以你不必担心使用哪一种。

不过，JavaScript 运行时必须从服务器运行，而不能直接从浏览器运行。

这是因为从浏览器调用 Elasticsearch 时，用户可能会获得敏感信息，如集群 API 密钥、主机或查询本身。Elasticsearch 建议永远不要将集群直接暴露在互联网上 ，而是使用一个中间层来抽象所有这些信息，这样用户只能看到参数。您可以在这里了解更多相关信息。

我们建议使用这样的模式：

在这种情况下，客户端只向服务器发送搜索条件和验证密钥，而服务器则完全控制查询和与 Elasticsearch 的通信。

连接客户端

首先，按照以下步骤创建一个 API 密钥。

按照前面的示例，我们将创建一个简单的 Express 服务器，并使用 Node.JS 服务器的客户端连接到该服务器。

我们将使用 NPM 初始化项目，并安装 Elasticsearch 客户端和Express。后者是一个在 Node.js 中调用服务器的库。使用 Express，我们可以通过 HTTP 与后端交互。

让我们初始化项目：

npm init -y

安装依赖项：

npm install @elastic/elasticsearch express split2 dotenv

让我来为你分析一下：

• @elastic/elasticsearch：它是 Node.js 的官方客户端

• 快递：它将使我们能够运行一个轻量级的 nodejs 服务器，以暴露 Elasticsearch

• split2： 将文本行分割成数据流。每次处理一行 ndjson 文件时非常有用

• dotenv：允许我们使用 .env 管理环境变量文件

创建 .env文件，并添加以下几行：

这样，我们就可以使用dotenv 软件包导入这些变量。

创建server.js 文件：

这段代码设置了一个基本的 Express.js 服务器，该服务器监听端口 3000，并使用 API 密钥进行身份验证，连接到 Elasticsearch 集群。它包括一个 /ping 端点，通过 GET 请求访问时，可使用 Elasticsearch 客户端的.info() 方法查询 Elasticsearch 集群的基本信息。

如果查询成功，会以 JSON 格式返回群集信息；否则会返回错误信息。服务器还使用 body-parser 中间件来处理 JSON 请求体。

运行文件，启动服务器：

node server.js

答案应该是这样的

现在，让我们查阅端点/ping ，检查 Elasticsearch 集群的状态。

编制文件索引

一旦连接起来，我们就可以使用语义_文本（用于语义搜索）和文本（用于全文查询）等映射对文档进行索引。有了这两种字段类型，我们还可以进行混合搜索。

我们将创建一个新的load.js 文件来生成映射并上传文件。

Elasticsearch 客户端

我们首先需要对客户端进行实例化和身份验证：

语义映射

我们将创建一个包含兽医院数据的索引。我们将保存主人、宠物和访问详情的信息。

我们要进行全文搜索的数据，如名称和描述，将以文本形式存储。类别中的数据，如动物的种类或品种，将以关键字的形式存储。

此外，我们还将把所有字段的值复制到一个 semantic_text 字段中，以便也能针对这些信息运行语义搜索。

批量助手

客户端的另一个优势是，我们可以使用批量助手来分批建立索引。通过批量辅助器，我们可以轻松处理并发、重试等问题，以及如何处理通过函数成功或失败的每个文档。

该助手的一个吸引人的特点是可以使用数据流。该功能允许您逐行发送文件，而不是将整个文件存储在内存中并一次性发送到 Elasticsearch。

要将数据上传到 Elasticsearch，请在项目根目录下创建名为 data.ndjson 的文件，并添加以下信息（也可以从此处下载包含数据集的文件）：

我们使用 split2 对文件行进行流式处理，而批量助手则将它们发送到 Elasticsearch。

上面的代码读取 .ndjson文件，并使用helpers.bulk 方法将每个 JSON 对象批量索引到指定的 Elasticsearch 索引中。它使用createReadStream 和split2 对文件进行流式处理，为每个文件设置索引元数据，并记录处理失败的文件。完成后，它会记录成功索引的项目数。

除indexData 功能外，您还可以使用 Kibana 直接通过用户界面上传文件，并使用上传数据文件用户界面。

我们运行文件，将文件上传到 Elasticsearch 集群。

node load.js

在 Elasticsearch 中搜索数据

回到server.js 文件，我们将创建不同的端点来执行词法、语义或混合搜索。

简而言之，这些类型的搜索并不相互排斥，而是取决于您需要回答的问题类型。

查询类型

用例

问题示例

词法查询

问题中的单词或词根很可能出现在索引文件中。问题与文件之间的标记相似性。

我在找一件蓝色运动 T 恤。

语义查询

问题中的词语不可能出现在文件中。问题与文件之间的概念相似性。

我在寻找适合寒冷天气穿的衣服。

混合搜索

问题包含词汇和/或语义成分。问题与文档之间的标记和语义相似性。

我想为海滩婚礼找一件 S 码的礼服。

问题的词汇 部分很可能是标题和说明的一部分，或者是类别名称，而语义 部分则是与这些领域相关的概念。蓝色可能是一个类别名称或描述的一部分，海滩婚礼不太可能是，但可以与亚麻服装在语义上相关。

词法查询 (/search/lexic?q=<query_term>)

词法搜索也称全文搜索，是指基于标记的相似性进行搜索；也就是说，经过分析后，将返回包含搜索标记的文档。

您可以点击此处查看我们的词法搜索实践教程。

我们测试：修剪指甲

请回答：

语义查询 (/search/semantic?q=<query_term>)

语义搜索与词汇搜索不同，它通过矢量搜索找到与搜索词含义相似的结果。

您可以点击这里查看我们的语义搜索实践教程。

我们进行测试：谁做了修脚？

请回答：

混合查询 (/search/hybrid?q=<query_term>)

混合搜索允许我们将语义搜索和词法搜索结合起来，从而获得两全其美的效果：既能获得标记搜索的精确性，又能获得语义搜索的意义接近性。

我们以 "谁做了修脚或牙科治疗？"

响应：

结论

在本系列的第一部分中，我们介绍了如何按照客户端/服务器最佳实践设置环境并创建带有不同搜索端点的服务器，以查询 Elasticsearch 文档。查看我们系列的第二部分，您将了解生产最佳实践以及如何在无服务器环境中运行 Elasticsearch Node.js 客户端。