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

unsetunset一、背景与目标unsetunset

需要在同一个 Python 项目中同时支持：

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

用户在前端选择搜索引擎后，后端要能正确连接并执行 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 _np
if not hasattr(_np, "float_"):
    _np.float_ = _np.float64
if not hasattr(_np, "int_"):
    _np.int_ = _np.int64
from 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 仍报错，可改用 RequestsHttpConnection
from elasticsearch import RequestsHttpConnection
client = 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.1
numpy<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 _np
ifnot hasattr(_np, "float_"):
    _np.float_ = _np.float64
ifnot hasattr(_np, "int_"):
    _np.int_ = _np.int64

from elasticsearch import Elasticsearch
from elasticsearch.helpers import bulk as helpers_bulk

def create_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_auth
    if scheme == "https"andnot verify_certs:
        kwargs["verify_certs"] = False

    try:
        client = Elasticsearch(**kwargs)
    except TypeError:
        # 某些 7.x 版本参数不同
        kwargs.pop("verify_certs", None)
        from elasticsearch import RequestsHttpConnection
        import 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

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

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

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

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

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

如果后续需要同时使用 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 爱好者一起精进！

比同事抢先一步学习进阶干货！