博客

适用 Elasticsearch 的 Gemini CLI 扩展及工具和技能

Elastic 推出了适用于谷歌 Gemini CLI 的扩展，用于在开发人员和智能体工作流中搜索、检索和分析 Elasticsearch 数据。

Walter RafelsbergerEnrico Zimuel
集成智能体 AI

我们很高兴地宣布， Elastic 发布了适用于 Google 的 Gemini CLI 扩展，将 Elasticsearch 和 Elastic Agent Builder 的全部功能直接引入您的 AI 开发工作流。此扩展还提供几种最近开发的智能体技能，用于与 Elasticsearch 交互。

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

Gemini CLI 是什么？如何安装？

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

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

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

npm install -g @google/gemini-cli

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

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

gemini

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

Gemini CLI 的屏幕截图。

图 1：Gemini CLI 屏幕截图。

配置 Elasticsearch

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

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

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

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

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

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

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

安装 Elasticsearch 扩展

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

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

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

/extensions list

您应该看到 Elasticsearch 扩展可用。

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

  • 从智能体处获取 MCP 服务器 URL > 查看所有工具 > 管理 MCP > 复制 MCP 服务器 URL。

  • URL 将如下所示：https://your-kibana-instance/api/agent_builder/mcp

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

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

  • 在 Kibana 中：Stack Management > Security > API 密钥 > 创建 API 密钥。

  • 我们建议仅设置 API 密钥的读取权限，并启用 feature_agentBuilder.read 权限，详见此处。

  • 复制已编码的 API 密钥值。

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

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

安装示例数据集

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

  • 客户信息（姓名、ID 号码、出生日期、电子邮件等）。

  • 订单日期。

  • 订单编号。

  • 产品（包含价格、数量、ID、类别、折扣和其他详情的所有产品列表）

  • SKU。

  • 总价（不含税，含税）。

  • 总数量。

  • 地理信息（城市、国家、洲、位置、地区）。

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

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

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

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

/mcp list

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

`elastic-agent-builder` MCP 服务器及其工具列表。

图 2：elastic-agent-builder MCP 服务器及其工具列表。

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

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

  • Give me the list of all the indexes available in Elasticsearch.

  • How many customers are based in the USA in the kibana_sample_data_ecommerce index of Elasticsearch?

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

/elastic 命令

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

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

可用的 `/elastic` 命令。

图3：可用的 /elastic 命令。

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

/elastic:get-mapping kibana_sample_data_ecommerce

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

如何使用 Elasticsearch 的技能？

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

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

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

esql 技能的功能：

  • 发现索引和模式：智能体可以使用该技能的内置工具列出可用索引并获取字段映射。例如，在为电子商务数据集编写查询之前，智能体可以在 kibana_sample_data_ecommerce 上运行模式检查，以了解可用的字段，如 taxful_total_price 或 category。

  • 无缝自然语言翻译：该技能不仅仅为智能体提供了一个简单的参考手册；它还提供了一个专门的指南，用于解读用户意图。当您用自然语言输入请求（如“按服务分组显示平均响应时间”）时，智能体会使用技能捆绑的模式匹配功能，将您的文字立即转换为正确的 ES|QL 聚合、筛选条件和命令。

  • 自我纠正：如果查询失败（例如由于类型不匹配或语法错误），该技能会返回生成的查询以及确切的 Elasticsearch 错误信息，使智能体能够立即修复查询并再次尝试，而无需您进行干预。

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

/mcp disable elastic-agent-builder

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

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

代理将：

  • 认识到 esql 技能的必要性。

  • 检查 kibana_sample_data_ecommerce 的模式。

  • 构建一个 ES|QL 查询，比如：FROM kibana_sample_data_ecommerce | STATS total_revenue = SUM(taxful_total_price) BY category.keyword | SORT total_revenue DESC | LIMIT 5。

  • 针对 Elasticsearch API 执行查询。

  • 直接在终端中向您展示最终答案。

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

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

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

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

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

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

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

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

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

 ✓  Shell 

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

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

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

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

结论

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

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

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

相关内容

Kibana开发者体验集成

Kibana 仪表板 API：为每种面板类型提供稳定的 API 规范，正式发布前已经过 50 多个团队测试

Teresa Alvarez Soler
集成

为 Elasticsearch 注入活力：添加对原生 Prometheus API 的支持

Felix Barnsteiner

准备好打造最先进的搜索体验了吗？

足够先进的搜索不是一个人的努力就能实现的。Elasticsearch 由数据科学家、ML 操作员、工程师以及更多和您一样对搜索充满热情的人提供支持。让我们联系起来，共同打造神奇的搜索体验，让您获得想要的结果。

亲自试用