尧图网页设计 
Local Deep Research 接入 Elasticsearch私有文档库全文检索与两阶段深度搜索实战指南【免费下载链接】local-deep-research~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10 search engines - arXiv, PubMed, your private documents. Everything Local Encrypted.项目地址: https://gitcode.com/GitHub_Trending/lo/local-deep-research本文围绕 Local Deep Research 项目中 Elasticsearch 搜索引擎的完整接入方案展开覆盖从依赖安装、索引构建ElasticsearchManager到引擎配置、基础/高级搜索Query String 与 DSL、LLM 相关性过滤再到可用性探测、SSRF 校验与云出口策略等源码级细节。读完本文你将掌握如何在本地或云端 Elasticsearch 上建立可被深度研究 Agent 调用的私有知识库搜索通道并能独立排查连接失败、空结果等常见问题。概述为什么在 Local Deep Research 中使用 ElasticsearchLocal Deep Research 是一个本地优先的深度研究框架其搜索子系统通过统一的BaseSearchEngine抽象接入多种数据源arXiv、PubMed、通用搜索引擎等。Elasticsearch 引擎允许你直接搜索 Elasticsearch 索引中的文档非常适合处理大量结构化或非结构化文本数据的私有语料——例如企业知识库、论文 PDF 合集、个人文档目录等。从源码看搜索引擎实现 将引擎声明为is_local True、is_lexical True、needs_llm_relevance_filter True并明确标注为 two-phase approach两阶段方法这意味着它同时具备本地词法检索不依赖外部 API与 LLM 二次相关性过滤的能力适合与本地大模型如 Qwen、llama.cpp 等组合成完全离线的检索增强链路。前提条件接入 Elasticsearch 搜索引擎前需要满足两个条件运行中的 Elasticsearch 服务器本地或远程均可默认连接地址为http://localhost:9200Elasticsearch Python 客户端库要求版本elasticsearch8.10.0。引擎在__init__中会调用self.client.info()验证连接并打印集群名称与版本信息源码连接失败会抛出ConnectionError。因此即使跳过手动探活初始化阶段也能第一时间暴露集群不可达的问题。安装若你是从源代码安装 Local Deep Research需单独安装 Elasticsearch 客户端pip install elasticsearch8.10.0此外若要使用ElasticsearchManager.index_file/index_directory的“文件自动提取内容”能力索引 PDF、DOCX 等还需安装unstructured包——index_file内部通过unstructured.partition.auto.partition完成文本抽取未安装时会打印明确错误并返回Nonees_utils.py 源码。基本用法在代码中使用引擎创建引擎实例并执行搜索的最小代码如下与官方文档保持一致from local_deep_research.web_search_engines.engines.search_engine_elasticsearch import ElasticsearchSearchEngine # 创建搜索引擎实例 es_search ElasticsearchSearchEngine( hosts[http://localhost:9200], # Elasticsearch 服务器地址 index_namemy_index, # 要搜索的索引名称 usernameuser, # 可选认证用户名 passwordpass, # 可选认证密码 max_results10 # 返回结果数量 ) # 执行搜索 results es_search.run(你的搜索查询) # 处理结果 for result in results: print(f标题: {result.get(title)}) print(f片段: {result.get(snippet)}) print(f内容: {result.get(content)})引擎返回的每条结果字典包含title、snippet、content等字段同时携带id、link、score、_index等元信息见 响应处理源码。其中link优先取文档源字段url缺失时回退为elasticsearch://index/id形式的内部协议地址。两阶段搜索预览、相关性过滤与全文拉取run()背后的实际执行链路并非一次查询那么简单。从源码结构可以推断其两阶段设计引擎实现预览阶段_get_previews以multi_matchbest_fields模式tie_breaker0.3在search_fields指定的字段上检索按sizemax_results返回带高亮的预览结果若配置了filter_query则用bool查询将其包装为filter子句相关性过滤可选引擎声明needs_llm_relevance_filter True当传入llm参数并设置max_filtered_results时基类会用 LLM 对预览结果做相关性判定压缩进入下一步的候选集对应参数表中的llm、max_filtered_results两列全文拉取_get_full_content对通过过滤的相关项按_id调用client.get取回完整content并把_source中的其余元数据合并进结果单篇拉取失败时保留预览数据兜底不中断整批结果。这种“先粗筛、后精读”的编排使 LLM 只对真正进入候选集的少量文档做全文级处理兼顾检索质量与 token 开销。高级搜索除基础的自然语言查询外引擎还提供了两种高级检索入口源码# 使用 Elasticsearch 查询字符串语法字段级、布尔、通配等表达式 results es_search.search_by_query_string(title:关键词 AND content:内容) # 使用 Elasticsearch DSL领域特定语言可组合 bool / match / term / range 等 results es_search.search_by_dsl({ query: { bool: { must: {match: {content: 搜索词}}, filter: {term: {category: 技术}} } } })search_by_query_string会把查询字符串包装进query_string查询并限定在self.search_fields字段范围内执行同时附加高亮配置search_by_dsl则把传入的 DSL 字典原样作为查询体提交适合复用 Kibana 调试好的复杂查询两个方法的返回结果与run()一致均经过预览→全文的完整处理见 响应处理与全文拉取。配置说明搜索引擎参数参数类型默认值说明hostsList[str][http://localhost:9200]Elasticsearch 服务器地址列表既支持 URL 字符串也支持{host:..., port:...}字典形式探测逻辑 兼容两种写法index_namestrdocuments要搜索的索引名称usernameOptional[str]None认证用户名与password同时提供时启用basic_authpasswordOptional[str]None认证密码作为敏感信息参与错误信息脱敏_secret_attrsapi_keyOptional[str]NoneAPI 密钥认证同样被列入脱敏白名单cloud_idOptional[str]NoneElastic Cloud ID在私有出口策略下会被拒绝见下文安全小节max_resultsint10最大结果数highlight_fieldsList[str][content, title]要高亮显示的字段结果中用em.../em包裹命中片段search_fieldsList[str][content, title]要搜索的字段multi_match与query_string均以此为限filter_queryOptional[Dict]None可选的过滤查询ES DSL 格式以bool.filter形式与检索条件叠加llmOptional[BaseLLM]None用于相关性过滤的语言模型LangChain 的BaseLLM子类max_filtered_resultsOptional[int]None过滤后的最大结果数几点源码层面的细节补充hosts 规范化参数可能以 JSON 字符串来自设置系统或真实列表传入引擎统一通过_ensure_list归一化源码认证优先级basic_auth、api_key、cloud_id三者互斥组合——同时传 username/password 时启用 Basic Auth仅传api_key时走 API Keycloud_id则用于 Elastic Cloud多主机故障转移hosts 列表会原样交给官方客户端任意一个主机可达即视为引擎可用与 ES 客户端的内置 failover 行为一致。设置项默认配置JSON 设置文件仓库在 elasticsearch.json 设置文件 中为该引擎声明了完整的可编辑配置项与程序化参数一一对应可直接在 UI 或设置系统中修改search.engine.web.elasticsearch.default_params.hostsJSON 数组格式默认[http://localhost:9200]search.engine.web.elasticsearch.default_params.index_name默认documentssearch.engine.web.elasticsearch.default_params.username/password/api_key/cloud_id可选认证信息search.engine.web.elasticsearch.default_params.max_results数值输入取值范围1100默认 10search.engine.web.elasticsearch.default_params.search_fields默认搜索字段为[content, title, description, text]注意设置文件默认值比引擎构造参数的默认值多了description与text两个字段search.engine.web.elasticsearch.default_params.highlight_fields默认[content, title]search.engine.web.elasticsearch.reliability可靠性权重范围 0.01.0步长 0.05默认0.95search.engine.web.elasticsearch.requires_api_key默认falsesearch.engine.web.elasticsearch.requires_llm默认true与引擎声明needs_llm_relevance_filter True一致search.engine.web.elasticsearch.supports_full_search默认truesearch.engine.web.elasticsearch.use_in_auto_search是否纳入自动搜索模式默认falsesearch.engine.web.elasticsearch.agent_enabled是否作为 langgraph 研究 Agent 的专用工具暴露默认true被选为search.tool的引擎始终保留通用 web_search 工具此开关只控制额外的专用工具strengths/weaknesses声明引擎的优势快速全文搜索、可扩展分布式、丰富查询 DSL、支持聚合、实时搜索与局限需运行 ES 实例、需正确索引配置、数据需预索引。索引数据使用 ElasticsearchManager为了便于使用项目提供了ElasticsearchManager工具类es_utils.py封装了索引与集群管理能力from local_deep_research.utilities.es_utils import ElasticsearchManager # 创建 ES 管理器同样支持 username/password、api_key、cloud_id 认证参数 es_manager ElasticsearchManager( hosts[http://localhost:9200] ) # 创建索引可自定义 mappings 与 settings es_manager.create_index(my_index) # 索引单个文档可指定 document_idrefreshTrue 可立即生效 es_manager.index_document( index_namemy_index, document{ title: 文档标题, content: 文档内容..., } ) # 批量索引文档返回成功条数 documents [ {title: 文档1, content: 内容1}, {title: 文档2, content: 内容2} ] es_manager.bulk_index_documents(my_index, documents) # 索引文件自动提取内容基于 unstructured需先安装 es_manager.index_file(my_index, path/to/document.pdf) # 索引整个目录中的文件按 glob 模式过滤 es_manager.index_directory( my_index, path/to/docs, file_patterns[*.pdf, *.docx, *.txt] )各方法的行为要点均有源码佐证create_index索引已存在时跳过创建并返回True未传mappings时使用内置默认映射——title为带keyword子字段ignore_above: 256的text字段content为text另含url、source、timestampdate、metadataobject字段默认映射源码默认设置为 1 分片、0 副本、标准分词器。提示默认number_of_replicas: 0适合本地单节点开发生产多节点集群请自行通过settings参数调整delete_index索引不存在时安全返回Trueindex_document调用官方client.index返回文档_id失败返回Nonebulk_index_documents基于elasticsearch.helpers.bulkstats_onlyTrue支持通过id_field指定文档中哪个字段作为_id返回成功条数index_file用unstructured本地分区解析文件将各元素以空行拼接为content并自动写入title文件名、source、file_extension、filename等元数据index_directory对目录执行 glob 匹配默认[*.txt, *.pdf, *.docx, *.md]逐个调用index_file并统计成功数search管理器自身也内置一个带高亮开关的multi_match搜索方法可直接用于快速验证索引数据。示例完整可运行脚本仓库中的完整示例位于 examples/elasticsearch/search_example.py文档原引用的examples/elasticsearch_search_example.py在仓库实际路径中位于examples/elasticsearch/目录下。该脚本完整演示了“建索引 → 批量写入 5 篇中文示例文档 → 基础搜索 → 高级搜索Query String 与 DSL”的端到端流程并打印每条结果的标题、片段与相关性分数。运行示例确保 Elasticsearch 正在运行默认地址http://localhost:9200然后执行python examples/elasticsearch/search_example.py运行前请先完成依赖安装pip install elasticsearch8.10.0示例中的 DSL 查询演示了一个值得注意的细节对category这类字段使用term精确过滤时需要查询其.keyword子字段如category.keyword因为默认映射下普通text字段会被分词无法直接term匹配。工程化机制可用性探测、SSRF 与出口策略除功能本身外该引擎还集成了 Local Deep Research 的多项安全与可靠性机制理解它们有助于在生产环境正确配置可用性探测与缓存is_available使用裸 TCP 连接不做完整 ES 握手探测 hosts任一路径可达即返回可用探测结果按主机列表键缓存60 秒_AVAILABILITY_TTL_SECONDS负结果同样缓存避免集群故障时每个研究任务都白白付出一次 TCP 往返探测源码对cloud_id配置则直接放行fail-open由__init__中的client.info()暴露真实错误SSRF 防护每次 TCP 探测前都会调用validate_urlallow_localhostTrue, allow_private_ipsTrue不合规的主机会被跳过并告警探测总预算 2.0 秒单主机超时上限 1 秒实现出口策略与云 ID 拒绝引擎静态标记为本地敏感/受限Sensitivity.SENSITIVE、Exposure.CONTAINED但 hosts 若解析到公网端点如 Elastic Cloud会被策略决策点PDP重新归类为公开。当生效出口范围为PRIVATE_ONLY/STRICT时cloud_id配置在初始化阶段即抛出PolicyDeniedError并安全失败fail-closed防止“数据在本地、查询却流出公网”egress 校验源码错误信息脱敏api_key、password通过_secret_attrs声明连接或查询异常日志会自动脱敏避免凭据泄漏到日志与 Agent 提示词中。故障排除无法连接到 Elasticsearch确保 Elasticsearch 服务器正在运行可先执行curl http://localhost:9200验证检查主机地址和端口是否正确默认http://localhost:9200配置了hosts设置时注意该设置以 JSON 数组形式保存验证认证凭据如果需要usernamepassword或api_key二选一检查网络连接和防火墙设置确保目标主机在 SSRF 校验允许范围内若使用cloud_id且出口策略为私有/严格模式引擎会在初始化时被拒绝此时需改为局域网内 Elasticsearch 地址。搜索结果为空确保索引存在并且包含数据——用es_manager.create_index建索引后index_document/bulk_index_documents默认refreshFalse刚写入的数据需要等刷新周期或显式传refreshTrue才能被搜到检查搜索字段是否正确search_fields必须与索引中实际存在的字段名一致默认映射中全文字段是title、content尝试使用更简单的查询例如仅用单个关键词而非复杂布尔表达式检查 Elasticsearch 日志获取更多信息如分词器、映射冲突导致的异常若配置了llm相关性过滤可临时降低max_filtered_results或检查过滤阈值确认是否为“检索到但被过滤掉”的场景。延伸阅读引擎实现与两阶段搜索search_engine_elasticsearch.py索引管理工具类es_utils.py设置项默认配置elasticsearch.json完整可运行示例examples/elasticsearch/search_example.py单元测试覆盖初始化、认证选项、预览/全文、Query String 与 DSL 搜索tests/web_search_engines/engines/test_search_engine_elasticsearch.py、tests/search_engines/test_search_engine_elasticsearch.py【免费下载链接】local-deep-research~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10 search engines - arXiv, PubMed, your private documents. Everything Local Encrypted.项目地址: https://gitcode.com/GitHub_Trending/lo/local-deep-research创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Local Deep Research 接入 Elasticsearch：私有文档库全文检索与两阶段深度搜索实战指南
Local Deep Research 接入 Elasticsearch私有文档库全文检索与两阶段深度搜索实战指南【免费下载链接】local-deep-research~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10 search engines - arXiv, PubMed, your private documents. Everything Local Encrypted.项目地址: https://gitcode.com/GitHub_Trending/lo/local-deep-research本文围绕 Local Deep Research 项目中 Elasticsearch 搜索引擎的完整接入方案展开覆盖从依赖安装、索引构建ElasticsearchManager到引擎配置、基础/高级搜索Query String 与 DSL、LLM 相关性过滤再到可用性探测、SSRF 校验与云出口策略等源码级细节。读完本文你将掌握如何在本地或云端 Elasticsearch 上建立可被深度研究 Agent 调用的私有知识库搜索通道并能独立排查连接失败、空结果等常见问题。概述为什么在 Local Deep Research 中使用 ElasticsearchLocal Deep Research 是一个本地优先的深度研究框架其搜索子系统通过统一的BaseSearchEngine抽象接入多种数据源arXiv、PubMed、通用搜索引擎等。Elasticsearch 引擎允许你直接搜索 Elasticsearch 索引中的文档非常适合处理大量结构化或非结构化文本数据的私有语料——例如企业知识库、论文 PDF 合集、个人文档目录等。从源码看搜索引擎实现 将引擎声明为is_local True、is_lexical True、needs_llm_relevance_filter True并明确标注为 two-phase approach两阶段方法这意味着它同时具备本地词法检索不依赖外部 API与 LLM 二次相关性过滤的能力适合与本地大模型如 Qwen、llama.cpp 等组合成完全离线的检索增强链路。前提条件接入 Elasticsearch 搜索引擎前需要满足两个条件运行中的 Elasticsearch 服务器本地或远程均可默认连接地址为http://localhost:9200Elasticsearch Python 客户端库要求版本elasticsearch8.10.0。引擎在__init__中会调用self.client.info()验证连接并打印集群名称与版本信息源码连接失败会抛出ConnectionError。因此即使跳过手动探活初始化阶段也能第一时间暴露集群不可达的问题。安装若你是从源代码安装 Local Deep Research需单独安装 Elasticsearch 客户端pip install elasticsearch8.10.0此外若要使用ElasticsearchManager.index_file/index_directory的“文件自动提取内容”能力索引 PDF、DOCX 等还需安装unstructured包——index_file内部通过unstructured.partition.auto.partition完成文本抽取未安装时会打印明确错误并返回Nonees_utils.py 源码。基本用法在代码中使用引擎创建引擎实例并执行搜索的最小代码如下与官方文档保持一致from local_deep_research.web_search_engines.engines.search_engine_elasticsearch import ElasticsearchSearchEngine # 创建搜索引擎实例 es_search ElasticsearchSearchEngine( hosts[http://localhost:9200], # Elasticsearch 服务器地址 index_namemy_index, # 要搜索的索引名称 usernameuser, # 可选认证用户名 passwordpass, # 可选认证密码 max_results10 # 返回结果数量 ) # 执行搜索 results es_search.run(你的搜索查询) # 处理结果 for result in results: print(f标题: {result.get(title)}) print(f片段: {result.get(snippet)}) print(f内容: {result.get(content)})引擎返回的每条结果字典包含title、snippet、content等字段同时携带id、link、score、_index等元信息见 响应处理源码。其中link优先取文档源字段url缺失时回退为elasticsearch://index/id形式的内部协议地址。两阶段搜索预览、相关性过滤与全文拉取run()背后的实际执行链路并非一次查询那么简单。从源码结构可以推断其两阶段设计引擎实现预览阶段_get_previews以multi_matchbest_fields模式tie_breaker0.3在search_fields指定的字段上检索按sizemax_results返回带高亮的预览结果若配置了filter_query则用bool查询将其包装为filter子句相关性过滤可选引擎声明needs_llm_relevance_filter True当传入llm参数并设置max_filtered_results时基类会用 LLM 对预览结果做相关性判定压缩进入下一步的候选集对应参数表中的llm、max_filtered_results两列全文拉取_get_full_content对通过过滤的相关项按_id调用client.get取回完整content并把_source中的其余元数据合并进结果单篇拉取失败时保留预览数据兜底不中断整批结果。这种“先粗筛、后精读”的编排使 LLM 只对真正进入候选集的少量文档做全文级处理兼顾检索质量与 token 开销。高级搜索除基础的自然语言查询外引擎还提供了两种高级检索入口源码# 使用 Elasticsearch 查询字符串语法字段级、布尔、通配等表达式 results es_search.search_by_query_string(title:关键词 AND content:内容) # 使用 Elasticsearch DSL领域特定语言可组合 bool / match / term / range 等 results es_search.search_by_dsl({ query: { bool: { must: {match: {content: 搜索词}}, filter: {term: {category: 技术}} } } })search_by_query_string会把查询字符串包装进query_string查询并限定在self.search_fields字段范围内执行同时附加高亮配置search_by_dsl则把传入的 DSL 字典原样作为查询体提交适合复用 Kibana 调试好的复杂查询两个方法的返回结果与run()一致均经过预览→全文的完整处理见 响应处理与全文拉取。配置说明搜索引擎参数参数类型默认值说明hostsList[str][http://localhost:9200]Elasticsearch 服务器地址列表既支持 URL 字符串也支持{host:..., port:...}字典形式探测逻辑 兼容两种写法index_namestrdocuments要搜索的索引名称usernameOptional[str]None认证用户名与password同时提供时启用basic_authpasswordOptional[str]None认证密码作为敏感信息参与错误信息脱敏_secret_attrsapi_keyOptional[str]NoneAPI 密钥认证同样被列入脱敏白名单cloud_idOptional[str]NoneElastic Cloud ID在私有出口策略下会被拒绝见下文安全小节max_resultsint10最大结果数highlight_fieldsList[str][content, title]要高亮显示的字段结果中用em.../em包裹命中片段search_fieldsList[str][content, title]要搜索的字段multi_match与query_string均以此为限filter_queryOptional[Dict]None可选的过滤查询ES DSL 格式以bool.filter形式与检索条件叠加llmOptional[BaseLLM]None用于相关性过滤的语言模型LangChain 的BaseLLM子类max_filtered_resultsOptional[int]None过滤后的最大结果数几点源码层面的细节补充hosts 规范化参数可能以 JSON 字符串来自设置系统或真实列表传入引擎统一通过_ensure_list归一化源码认证优先级basic_auth、api_key、cloud_id三者互斥组合——同时传 username/password 时启用 Basic Auth仅传api_key时走 API Keycloud_id则用于 Elastic Cloud多主机故障转移hosts 列表会原样交给官方客户端任意一个主机可达即视为引擎可用与 ES 客户端的内置 failover 行为一致。设置项默认配置JSON 设置文件仓库在 elasticsearch.json 设置文件 中为该引擎声明了完整的可编辑配置项与程序化参数一一对应可直接在 UI 或设置系统中修改search.engine.web.elasticsearch.default_params.hostsJSON 数组格式默认[http://localhost:9200]search.engine.web.elasticsearch.default_params.index_name默认documentssearch.engine.web.elasticsearch.default_params.username/password/api_key/cloud_id可选认证信息search.engine.web.elasticsearch.default_params.max_results数值输入取值范围1100默认 10search.engine.web.elasticsearch.default_params.search_fields默认搜索字段为[content, title, description, text]注意设置文件默认值比引擎构造参数的默认值多了description与text两个字段search.engine.web.elasticsearch.default_params.highlight_fields默认[content, title]search.engine.web.elasticsearch.reliability可靠性权重范围 0.01.0步长 0.05默认0.95search.engine.web.elasticsearch.requires_api_key默认falsesearch.engine.web.elasticsearch.requires_llm默认true与引擎声明needs_llm_relevance_filter True一致search.engine.web.elasticsearch.supports_full_search默认truesearch.engine.web.elasticsearch.use_in_auto_search是否纳入自动搜索模式默认falsesearch.engine.web.elasticsearch.agent_enabled是否作为 langgraph 研究 Agent 的专用工具暴露默认true被选为search.tool的引擎始终保留通用 web_search 工具此开关只控制额外的专用工具strengths/weaknesses声明引擎的优势快速全文搜索、可扩展分布式、丰富查询 DSL、支持聚合、实时搜索与局限需运行 ES 实例、需正确索引配置、数据需预索引。索引数据使用 ElasticsearchManager为了便于使用项目提供了ElasticsearchManager工具类es_utils.py封装了索引与集群管理能力from local_deep_research.utilities.es_utils import ElasticsearchManager # 创建 ES 管理器同样支持 username/password、api_key、cloud_id 认证参数 es_manager ElasticsearchManager( hosts[http://localhost:9200] ) # 创建索引可自定义 mappings 与 settings es_manager.create_index(my_index) # 索引单个文档可指定 document_idrefreshTrue 可立即生效 es_manager.index_document( index_namemy_index, document{ title: 文档标题, content: 文档内容..., } ) # 批量索引文档返回成功条数 documents [ {title: 文档1, content: 内容1}, {title: 文档2, content: 内容2} ] es_manager.bulk_index_documents(my_index, documents) # 索引文件自动提取内容基于 unstructured需先安装 es_manager.index_file(my_index, path/to/document.pdf) # 索引整个目录中的文件按 glob 模式过滤 es_manager.index_directory( my_index, path/to/docs, file_patterns[*.pdf, *.docx, *.txt] )各方法的行为要点均有源码佐证create_index索引已存在时跳过创建并返回True未传mappings时使用内置默认映射——title为带keyword子字段ignore_above: 256的text字段content为text另含url、source、timestampdate、metadataobject字段默认映射源码默认设置为 1 分片、0 副本、标准分词器。提示默认number_of_replicas: 0适合本地单节点开发生产多节点集群请自行通过settings参数调整delete_index索引不存在时安全返回Trueindex_document调用官方client.index返回文档_id失败返回Nonebulk_index_documents基于elasticsearch.helpers.bulkstats_onlyTrue支持通过id_field指定文档中哪个字段作为_id返回成功条数index_file用unstructured本地分区解析文件将各元素以空行拼接为content并自动写入title文件名、source、file_extension、filename等元数据index_directory对目录执行 glob 匹配默认[*.txt, *.pdf, *.docx, *.md]逐个调用index_file并统计成功数search管理器自身也内置一个带高亮开关的multi_match搜索方法可直接用于快速验证索引数据。示例完整可运行脚本仓库中的完整示例位于 examples/elasticsearch/search_example.py文档原引用的examples/elasticsearch_search_example.py在仓库实际路径中位于examples/elasticsearch/目录下。该脚本完整演示了“建索引 → 批量写入 5 篇中文示例文档 → 基础搜索 → 高级搜索Query String 与 DSL”的端到端流程并打印每条结果的标题、片段与相关性分数。运行示例确保 Elasticsearch 正在运行默认地址http://localhost:9200然后执行python examples/elasticsearch/search_example.py运行前请先完成依赖安装pip install elasticsearch8.10.0示例中的 DSL 查询演示了一个值得注意的细节对category这类字段使用term精确过滤时需要查询其.keyword子字段如category.keyword因为默认映射下普通text字段会被分词无法直接term匹配。工程化机制可用性探测、SSRF 与出口策略除功能本身外该引擎还集成了 Local Deep Research 的多项安全与可靠性机制理解它们有助于在生产环境正确配置可用性探测与缓存is_available使用裸 TCP 连接不做完整 ES 握手探测 hosts任一路径可达即返回可用探测结果按主机列表键缓存60 秒_AVAILABILITY_TTL_SECONDS负结果同样缓存避免集群故障时每个研究任务都白白付出一次 TCP 往返探测源码对cloud_id配置则直接放行fail-open由__init__中的client.info()暴露真实错误SSRF 防护每次 TCP 探测前都会调用validate_urlallow_localhostTrue, allow_private_ipsTrue不合规的主机会被跳过并告警探测总预算 2.0 秒单主机超时上限 1 秒实现出口策略与云 ID 拒绝引擎静态标记为本地敏感/受限Sensitivity.SENSITIVE、Exposure.CONTAINED但 hosts 若解析到公网端点如 Elastic Cloud会被策略决策点PDP重新归类为公开。当生效出口范围为PRIVATE_ONLY/STRICT时cloud_id配置在初始化阶段即抛出PolicyDeniedError并安全失败fail-closed防止“数据在本地、查询却流出公网”egress 校验源码错误信息脱敏api_key、password通过_secret_attrs声明连接或查询异常日志会自动脱敏避免凭据泄漏到日志与 Agent 提示词中。故障排除无法连接到 Elasticsearch确保 Elasticsearch 服务器正在运行可先执行curl http://localhost:9200验证检查主机地址和端口是否正确默认http://localhost:9200配置了hosts设置时注意该设置以 JSON 数组形式保存验证认证凭据如果需要usernamepassword或api_key二选一检查网络连接和防火墙设置确保目标主机在 SSRF 校验允许范围内若使用cloud_id且出口策略为私有/严格模式引擎会在初始化时被拒绝此时需改为局域网内 Elasticsearch 地址。搜索结果为空确保索引存在并且包含数据——用es_manager.create_index建索引后index_document/bulk_index_documents默认refreshFalse刚写入的数据需要等刷新周期或显式传refreshTrue才能被搜到检查搜索字段是否正确search_fields必须与索引中实际存在的字段名一致默认映射中全文字段是title、content尝试使用更简单的查询例如仅用单个关键词而非复杂布尔表达式检查 Elasticsearch 日志获取更多信息如分词器、映射冲突导致的异常若配置了llm相关性过滤可临时降低max_filtered_results或检查过滤阈值确认是否为“检索到但被过滤掉”的场景。延伸阅读引擎实现与两阶段搜索search_engine_elasticsearch.py索引管理工具类es_utils.py设置项默认配置elasticsearch.json完整可运行示例examples/elasticsearch/search_example.py单元测试覆盖初始化、认证选项、预览/全文、Query String 与 DSL 搜索tests/web_search_engines/engines/test_search_engine_elasticsearch.py、tests/search_engines/test_search_engine_elasticsearch.py【免费下载链接】local-deep-research~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10 search engines - arXiv, PubMed, your private documents. Everything Local Encrypted.项目地址: https://gitcode.com/GitHub_Trending/lo/local-deep-research创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考