Python 同时适配 Elasticsearch 与 Easysearch 实战复盘

1. Easysearch（极限科技，ES 兼容）

用户在前端选择搜索引擎后，后端要能正确连接并执行 DSL，且要处理 HTTPS 自签名证书等常见问题。

unsetunset二、核心结论（先给结论）unsetunset

推荐做法：

使用 elasticsearch==7.13.1 作为唯一客户端，可同时连接 Elasticsearch 8.x/9.x 和 Easysearch。

unsetunset三、问题拆解unsetunset

3.1 产品兼容性校验

从 elasticsearch-py 7.14 起，客户端会校验服务端是否为“官方 Elasticsearch”，连接 Easysearch、OpenSearch 等会抛出类似：

UnsupportedProductError / "The client noticed that the server is not a supported distribution of Elasticsearch"

• 7.13.1：没有该校验，可连接任意 ES 兼容服务
• 8.x：校验更严格，只认官方 Elasticsearch

官方文档明确说明：

https://elasticsearch-py.readthedocs.io/en/7.x/transports.html

所以若希望同一套代码同时支持 ES 和 Easysearch，应锁定到 7.13.1。

3.2 NumPy 2.0 兼容

NumPy 2.0 移除了 np.float_ 和 np.int_，而 elasticsearch 7.13 仍在使用，需要在导入 elasticsearch 之前做兼容：

import numpy as _npifnot hasattr(_np, "float_"):    _np.float_ = _np.float64ifnot hasattr(_np, "int_"):    _np.int_ = _np.int64from elasticsearch import Elasticsearch

这样在 NumPy 2.0 下也能正常使用。

3.3 HTTPS 自签名证书

使用 HTTPS 且证书自签名时，常见错误：

SSLError: certificate verify failed: self-signed certificate in certificate chain

处理方式：在创建客户端时关闭证书校验（仅适合内网 / 自建环境）：

kwargs = {"hosts": [{"host": host, "port": port, "scheme": scheme}],"timeout": 30,"max_retries": 3,"retry_on_timeout": True,}if scheme == "https"andnot verify_certs:    kwargs["verify_certs"] = False# 如 7.x 的默认 Transport 仍报错，可改用 RequestsHttpConnectionfrom elasticsearch import RequestsHttpConnectionclient = Elasticsearch(    hosts=hosts,    connection_class=RequestsHttpConnection,    http_auth=http_auth,    use_ssl=True,    verify_certs=False,    timeout=30,)

并配合 urllib3.disable_warnings() 抑制 SSL 告警。

3.4 依赖约束

elasticsearch==7.13.1numpy<2   # 若使用 NumPy 2.0，则需上面的补丁requests>=2.26.0

unsetunset四、我们走过的几种方案unsetunset

方案 A：双客户端（ES 8.x + opensearch-py）

• Elasticsearch：使用 elasticsearch>=8
• Easysearch：使用 opensearch-py

问题：两个包、两套 API、分支多，维护成本高，我也明确不希望引入 opensearch。

方案 B：单客户端 8.x + 禁用产品校验

尝试在 8.x 中通过自定义 Transport 或 monkey-patch 禁用产品校验。

问题：依赖非官方实现，升级风险大，不够稳妥。

方案 C：单客户端 7.13.1（最终采用）

• 固定使用 elasticsearch==7.13.1

• 同时连接 Elasticsearch 8.x / 9.x 和 Easysearch

• 无产品校验，API 稳定，依赖简单

结论：方案 C 最符合当前需求。

unsetunset五、示例：统一的客户端创建逻辑unsetunset

# 1. NumPy 兼容（若使用 NumPy 2.0）import numpy as _npifnot hasattr(_np, "float_"):    _np.float_ = _np.float64ifnot hasattr(_np, "int_"):    _np.int_ = _np.int64from elasticsearch import Elasticsearchfrom elasticsearch.helpers import bulk as helpers_bulkdefcreate_es_client(host, port, scheme="http", http_auth=None, verify_certs=True):    hosts = [{"host": host, "port": port, "scheme": scheme}]    kwargs = {"hosts": hosts,"timeout": 30,"max_retries": 3,"retry_on_timeout": True,    }if http_auth:        kwargs["http_auth"] = http_authif scheme == "https"andnot verify_certs:        kwargs["verify_certs"] = Falsetry:        client = Elasticsearch(**kwargs)except TypeError:# 某些 7.x 版本参数不同        kwargs.pop("verify_certs", None)from elasticsearch import RequestsHttpConnectionimport urllib3        urllib3.disable_warnings()        client = Elasticsearch(            hosts=hosts,            connection_class=RequestsHttpConnection,            http_auth=http_auth,            use_ssl=True,            verify_certs=False,            timeout=30,        )ifnot client.ping():        client.info()  # 兜底return client

前端/配置中只需区分 product: "elasticsearch" 或 "easysearch"，后端都用同一套 elasticsearch 7.13.1 客户端即可。

unsetunset六、总结unsetunset

1. 单客户端：

elasticsearch==7.13.1 可同时支持 Elasticsearch 8.x/9.x 和 Easysearch。

1. 产品校验：

7.13.1 无校验，7.14+ 会校验，这是选 7.13.1 的核心原因。

1. NumPy：

在 NumPy 2.0 下需补回 np.float_ / np.int_。

1. HTTPS：

自签名证书时设置 verify_certs=False，必要时用 RequestsHttpConnection。

1. 不引入 opensearch-py：

减少依赖和复杂度，保持实现简单。

如果后续需要同时使用 8.x 的新特性并支持 Easysearch，再考虑引入 opensearch-py 或按产品类型切换不同客户端会比较合适；

目前以兼容性和维护成本为主时，7.13.1 单客户端方案是更稳妥的选择。

Text2DSL v2.0完整代码：https://t.zsxq.com/n2LB9

Text2DSL——自然语言转 Elasticsearch / Easysearch DSL 神器

基于 Easysearch + Flip 的多模态图像搜索引擎系统实战指南

Easysearch Python 客户端企业级实战——从 0 到 1 解决兼容性与连接难题

Codebuddy 实现：云端 Elasticsearch 到 本地 Easysearch 跨集群迁移 Python 小工具

用 Python 优雅地玩转 Elasticsearch：实用技巧与最佳实践

更短时间更快习得更多干货！

和全球 2100+ Elastic 爱好者一起精进！