Local Deep Research 接入 Elasticsearch 实战指南本地文档索引、搜索与 Web UI 集成【免费下载链接】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本指南以 examples/elasticsearch/README.md 为骨架结合仓库内完整的 docker-compose 编排、示例脚本、底层工具类ElasticsearchManager与搜索引擎实现ElasticsearchSearchEngine展开完整演示如何在 Local Deep Research 中启动本地 Elasticsearch、索引文档并将其注册为检索工具让你能够基于私有文档库进行本地化、可加密的深度研究。概述为什么在 Local Deep Research 中使用 ElasticsearchLocal Deep Research 是一个支持本地与云端大模型的深度研究系统其搜索层除了 arXiv、PubMed 等 10 余种外部检索引擎外还支持将 Elasticsearch 这类本地文档仓库作为研究素材来源。通过 Elasticsearch 集成你可以在完全本地、私有的 Elasticsearch 集群中索引自己的文档PDF、TXT、DOCX、Markdown 等让研究 Agent 直接检索这些文档作为深度研究的事实依据全程数据不出本机契合Everything Local Encrypted的项目定位。从源码分类看Elasticsearch 搜索引擎被标记为is_local True、is_lexical True且needs_llm_relevance_filter True见 search_engine_elasticsearch.py即它是一条本地、词法匹配型检索链路命中结果会再经 LLM 相关性过滤最终汇入研究流程。快速开始四步完成本地集成按照 README.md 的 Quick Start从 examples/elasticsearch 目录出发即可完成全流程。第 1 步启动 Elasticsearch 容器# 在 examples/elasticsearch 目录下执行 sudo docker compose up -d # 后台启动 # 或者前台启动方便观察启动日志 sudo docker compose up对应的编排文件 docker-compose.yml 内容如下# WARNING: This configuration disables Elasticsearch security (xpack.security.enabledfalse) # and is intended for LOCAL DEVELOPMENT ONLY. Do not use in production without enabling # authentication and TLS. services: elasticsearch: image: docker.elastic.co/elasticsearch/elasticsearch:8.11.0 container_name: elasticsearch-local environment: - discovery.typesingle-node - xpack.security.enabledfalse # Development only — enable for production - ES_JAVA_OPTS-Xms512m -Xmx512m ports: - 9200:9200 volumes: - elasticsearch_data:/usr/share/elasticsearch/data volumes: elasticsearch_data: driver: local关键配置项说明配置项值作用imagedocker.elastic.co/elasticsearch/elasticsearch:8.11.0使用官方 8.11.0 镜像与项目使用的elasticsearchPython 客户端兼容discovery.typesingle-node单节点模式免去集群发现的额外配置适合本地开发xpack.security.enabledfalse仅限本地开发关闭认证与 TLS。生产环境必须开启安全功能并配置认证详见文件头部注释提示的 Elasticsearch 官方安全最小化配置指南ES_JAVA_OPTS-Xms512m -Xmx512m固定 JVM 堆为 512MB避免容器内存膨胀ports9200:9200将 REST 接口映射到宿主机供 Web UI 与示例脚本访问volumeselasticsearch_data命名卷持久化索引数据容器销毁后数据不丢失注意关闭xpack.security后示例脚本与 Web UI 默认配置http://localhost:9200、无认证即可直接连通无需额外凭据。第 2 步索引示例文档python search_example.py该脚本 search_example.py 完成三件事创建索引通过ElasticsearchManager.create_index(documents)建立documents索引已存在则跳过并告警批量写入 5 篇示例文档涵盖 Elasticsearch 简介、Python 编程基础、NLP、深度学习、向量数据库比较等主题每个文档包含title、content、tags、category字段使用bulk_index_documents(..., refreshTrue)立即刷新让文档立即可搜执行基础搜索与高级搜索示例分别对elasticsearch、深度学习进行搜索并演示查询字符串语法与 DSL 查询详见下文高级检索一节。脚本基于项目封装的两个核心类ElasticsearchManager索引管理工具类负责建索引、删索引、单条/批量写入、文件/目录索引与基础检索ElasticsearchSearchEngine搜索引擎实现被研究 Agent 调用负责两阶段检索先取预览再取全文。第 3 步在 Web UI 中配置 Elasticsearch启动 Local Deep Research 的 Web UI 后进入Settings → Search Engines → ElasticsearchHost URLs默认[http://localhost:9200]Elasticsearch 服务器地址JSON 数组格式支持配置多个节点作为故障转移Index Name默认documents与示例脚本写入的索引名保持一致其余认证参数Username / Password / API Key / Cloud ID本地开发时可留空。配置项的完整定义与取值范围见 elasticsearch.json其中可编辑参数如下配置键UI 名称默认值说明search.engine.web.elasticsearch.default_params.hostsElasticsearch Host URLs[http://localhost:9200]服务器地址JSON 数组可配置多个节点做故障转移search.engine.web.elasticsearch.default_params.index_nameIndex Namedocuments要检索的索引名search.engine.web.elasticsearch.default_params.usernameUsername空基础认证用户名可选search.engine.web.elasticsearch.default_params.passwordPassword空基础认证密码可选密码框输入search.engine.web.elasticsearch.default_params.api_keyAPI Key空API Key 认证可选密码框输入search.engine.web.elasticsearch.default_params.cloud_idCloud ID空Elastic Cloud 托管集群的 Cloud ID可选search.engine.web.elasticsearch.default_params.max_resultsMax Results10单次返回结果数上限范围 1100search.engine.web.elasticsearch.default_params.search_fieldsSearch Fields[content,title,description,text]参与检索的字段JSON 数组search.engine.web.elasticsearch.default_params.highlight_fieldsHighlight Fields[content,title]需要高亮片段的字段JSON 数组search.engine.web.elasticsearch.reliabilityReliability0.95引擎可靠性评分0.01.0步进 0.05影响引擎选择策略search.engine.web.elasticsearch.requires_api_keyRequires Api Keyfalse本地 ES 无需 API Keysearch.engine.web.elasticsearch.requires_llmRequires LLMtrue命中结果需经 LLM 相关性过滤search.engine.web.elasticsearch.supports_full_searchSupports Full Searchtrue支持全文检索search.engine.web.elasticsearch.agent_enabledAvailable to Research Agenttrue是否作为 langgraph 研究 Agent 的专用工具暴露不依赖出口策略集合级开关优先search.engine.web.elasticsearch.use_in_auto_searchInclude in Auto Searchfalse是否纳入自动搜索模式按需开启第 4 步停止 Elasticsearchsudo docker compose down容器停止后命名卷elasticsearch_data中的数据依然保留下次up -d可直接复用索引。连通性自检脚本仓库提供了 test_elasticsearch.sh可一键验证环境是否就绪检测宿主机是否安装 Docker若有则自动启动容器并最多等待 60 秒30 次 × 2 秒轮询直到http://localhost:9200返回 HTTP 200无 Docker 时给出提示并检查是否已有 Elasticsearch 直接运行在本机连接成功后输出集群信息通过curl http://localhost:9200 | python3 -m json.tool并提示后续操作运行示例脚本、配置 Web UI、停止容器。# 赋予执行权限后运行README 未显式给出建议在 examples/elasticsearch 目录下执行 bash test_elasticsearch.sh深入源码ElasticsearchManager 的索引能力默认映射与分片设置调用create_index(index_name)而不传映射时es_utils.py 会使用内置默认映射与设置# 默认 mappings { properties: { title: {type: text, analyzer: standard, fields: {keyword: {type: keyword, ignore_above: 256}}}, content: {type: text, analyzer: standard}, url: {type: keyword}, source: {type: keyword}, timestamp: {type: date}, metadata: {type: object, enabled: True}, } } # 默认 settings { number_of_shards: 1, number_of_replicas: 0, analysis: {analyzer: {standard: {type: standard}}} }其中title额外配置了keyword子字段供 DSL 中的term精确过滤使用示例脚本即用category.keyword做精确过滤单分片、零副本适合本地单节点场景避免资源浪费。若需自定义分词如中文 IK 分词可向create_index传入自定义mappings与settings。三种写入方式方法用途关键参数index_document写入单篇文档document_id可选缺省自动生成、refresh是否立即刷新bulk_index_documents批量写入id_field用文档中某字段作 ID、refresh内部调用elasticsearch.helpers.bulk(..., stats_onlyTrue)返回成功数量index_file/index_directory索引本地文件/目录依赖unstructured的partition做本地解析自动抽取正文并附带source、filename、file_extension元数据目录索引默认匹配*.txt、*.pdf、*.docx、*.md批量写入是示例脚本采用的路径把 5 篇文档组装为{_index: ..., _source: ...}的 action 列表一次性提交性能远优于逐条写入。检索接口ElasticsearchManager.search使用multi_matchbest_fields类型、tie_breaker0.3在指定字段中检索并支持highlight高亮em标签包裹命中片段。注意该方法是底层管理工具研究流程实际调用的是ElasticsearchSearchEngine。深入源码ElasticsearchSearchEngine 的两阶段检索与安全策略两阶段检索设计ElasticsearchSearchEngine 继承了BaseSearchEngine检索分两步_get_previews预览阶段对search_fields执行multi_match查询配合highlight提取命中片段无高亮时截取content前SNIPPET_LENGTH_SHORT字符作为摘要。结果封装为含id、title、link、snippet、score的 preview 列表其中link优先取文档url字段否则回退为elasticsearch://index/id形式的内部链接_get_full_content全文阶段仅对通过 LLM 相关性过滤的相关项按id调用client.get拉取完整文档合并content与全部元数据后交给后续研究流程避免为无关文档浪费上下文窗口。另外引擎提供两种高级检索方法search_by_query_string使用 Elasticsearch Query String 语法如content:深度学习 OR title:elasticsearchsearch_by_dsl直接提交完整 DSL 查询体例如示例脚本中的 bool 组合查询must匹配contentfilter用category.keyword精确过滤。可用性探测与注册机制为避免 ES 未启动时 Agent 每次工具调用都报连接错误引擎实现了is_available类方法对配置的 hosts 做轻量 TCP 连接探测非完整 HTTP 握手单主机 1 秒超时、总预算 2 秒并带 60 秒 TTL 缓存探测失败期间不再重复连接连接前还会通过 SSRF 校验器validate_url允许 localhost 与内网 IP拦截不合规主机。该引擎已在 engine_registry.py 注册module_path.engines.search_engine_elasticsearchclass_nameElasticsearchSearchEngine因此在 Web UI 开启对应配置后即可被研究 Agent 选用。安全与隐私边界数据出口分类引擎标记egress_sensitivity SENSITIVE、egress_exposure CONTAINED并声明url_setting search.engine.web.elasticsearch.default_params.hosts——当配置的 hosts 解析为公网地址如 Elastic Cloud时出口策略会将引擎重新归类为公开从而在PRIVATE_ONLY等私密模式下禁止其被选用保证本地数据不外泄cloud_id 拦截cloud_id指向的必然是公网端点当生效出口范围禁止公网出口时__init__会直接抛出PolicyDeniedError拒绝连接fails closed敏感信息脱敏_secret_attrs (_api_key, _password)错误信息中出现的密钥会被_scrub_error脱敏后再记录/抛出。文件清单与前置要求本示例包含的文件文件作用docker-compose.ymlElasticsearch 容器编排单节点、无安全认证仅本地开发、512MB 堆、9200 端口、持久化卷search_example.py示例脚本建索引、批量写入 5 篇示例文档、基础搜索、Query String 与 DSL 高级搜索test_elasticsearch.sh自检脚本验证 Docker 与 Elasticsearch 连通性输出集群信息与后续操作提示前置要求Docker 与 Docker Compose用于拉起 Elasticsearch 8.11.0 容器若未安装 Docker也可直接在本机安装 Elasticsearch自检脚本内附有基于官方 apt 源的安装命令提示Python 环境已安装项目依赖含elasticsearch、loguru、langchain-core等示例脚本运行时会把项目根目录加入sys.path从而导入src.local_deep_research下的工具类与搜索引擎类。常见问题排查连接报错 Could not connect to Elasticsearch确认容器已通过docker compose up -d启动且http://localhost:9200返回 200Elasticsearch 首次冷启动需要约 3060 秒可用test_elasticsearch.sh轮询等待索引已存在告警create_index检测到索引存在时会跳过创建并记录 warning重复运行示例脚本不会重建索引如需干净环境可手动删除索引后重跑DSL 的term过滤不生效精确匹配需使用带.keyword子字段的字段如category.keyword因为category默认被 standard 分词器拆分生产环境安全示例配置关闭了xpack.security生产部署必须启用认证与 TLS并按需在 Web UI 中填写 Username / Password / API Key避免数据被未授权访问。至此你已具备在 Local Deep Research 中完整落地 Elasticsearch 本地检索的能力从容器编排、示例数据索引到 Web UI 参数配置与底层两阶段检索、出口安全策略的源码级理解。接下来即可将自有文档批量索引index_directory后作为研究 Agent 的私有知识源投入实际深度研究。【免费下载链接】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），仅供参考