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

unsetunset一、背景与目标unsetunset

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

Elasticsearch 8.x / 9.x

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

Easysearch （极限科技，ES 兼容）

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

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

方案	适用场景	优缺点
elasticsearch 7.13.1	同时连 ES 和 Easysearch	无产品校验，兼容性好，需 NumPy 2.0 兼容补丁
elasticsearch 8.x/9.x	仅连接官方 Elasticsearch	有产品校验，会拒绝 Easysearch
opensearch-py	仅连 Easysearch/OpenSearch	需多一个依赖，增加复杂度

推荐做法：

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

unsetunset三、问题拆解unsetunset

3.1 产品兼容性校验

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

go 复制代码

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 之前做兼容：

go 复制代码

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 且证书自签名时，常见错误：

go 复制代码

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

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

go 复制代码

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 依赖约束

go 复制代码

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

go 复制代码

# 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