# zilliztech/deep-searcher: a Python RAG agent for reports over private data

> DeepSearcher wires a reasoning LLM to a Milvus vector store so you can load local files and ask for a written report instead of a snippet. It is a library, not a hosted product, and the README leaves a few things unsaid.

**zilliztech/deep-searcher** — Open Source Deep Research Alternative to Reason and Search on Private Data. Written in Python.

- Repository: https://github.com/zilliztech/deep-searcher
- Website: https://zilliztech.github.io/deep-searcher/
- Stars: 8,291 · Forks: 804
- Language: Python
- License: Apache-2.0
- Published: 2026-09-28 · Updated: 2026-09-28 · Language: en
- Canonical page: https://hysenlabs.com/projects/zilliztech-deep-searcher

## The problem deep-searcher targets: reports, not retrieval snippets

Most retrieval stacks stop at the chunk. You embed a corpus, run a similarity search, and hand the top matches to a model that writes a paragraph. DeepSearcher aims one step further out: the README describes it as performing search, evaluation and reasoning over private data to produce a "highly accurate answer and comprehensive report". The named use cases are enterprise knowledge management, intelligent Q&A, and information retrieval. The audience is therefore a Python team that already has internal documents and wants a longer written artifact back, not a ranked list. The project is explicit about the data boundary: it says it maximizes the use of enterprise internal data while ensuring data security, and only reaches for online content "when necessary". That framing matters. If your question can be answered by a keyword search over a wiki, this is more machinery than you need.

## How the pieces fit: configuration, loaders, vector store, query

The repository layout exposes the pipeline. deepsearcher/configuration.py holds a Configuration object and an init_config function that registers providers by name. deepsearcher/offline_loading.py contains the ingestion side, with load_from_local_files and load_from_website as the two entry points shown in the README. deepsearcher/online_query.py exposes query, which is what you call at the end. Documents are split with langchain-text-splitters, embedded through the embedding provider you selected, and written into a vector database, with pymilvus as a hard dependency in pyproject.toml. Partitioning is called out as a feature, so a single Milvus collection can be divided by data source rather than mixed. The provider registry is the part worth understanding before you write code: both the LLM and the embedding model are chosen by string name plus an arguments dictionary, which means swapping DeepSeek for OpenAI is a two-line change and not a refactor. The README lists the LLM names as DeepSeek, OpenAI, XAI, SiliconFlow, Aliyun, PPIO, TogetherAI, Gemini, Ollama, Novita and Jiekou.AI.

## Installing deep-searcher and running a first report

The README recommends Python 3.10 and a virtual environment. The first block creates one and activates it, then installs the published package. Optional providers ship as extras, so an Ollama user installs the bracketed form instead.

```bash
python -m venv .venv
source .venv/bin/activate
pip install deepsearcher
```

The README also documents a development install with uv, which is the route the Dockerfile takes. Cloning and running uv sync pulls the locked dependency set from uv.lock, then activates the environment uv created.

```bash
git clone https://github.com/zilliztech/deep-searcher.git && cd deep-searcher
uv sync
source .venv/bin/activate
```

The quick start demo needs OPENAI_API_KEY set in the environment. The README states that if you change the LLM in the configuration you must prepare the corresponding API key instead. The snippet below is the README's own example: it builds a Configuration, overrides the LLM and embedding providers, calls init_config, loads a local path, and finally calls query. Note that load_from_local_files takes a paths_or_directory argument, and that the web loader needs FIRECRAWL_API_KEY.

```python
from deepsearcher.configuration import Configuration, init_config
from deepsearcher.online_query import query

config = Configuration()
config.set_provider_config("llm", "OpenAI", {"model": "o1-mini"})
config.set_provider_config("embedding", "OpenAIEmbedding", {"model": "text-embedding-ada-002"})
init_config(config=config)

from deepsearcher.offline_loading import load_from_local_files
load_from_local_files(paths_or_directory=your_local_path)

result = query("Write a report about xxx.")
```

What you should see is a string returned from query rather than a stream of tokens. The README does not document what that string looks like, how long it takes, or what it costs, so treat the first run as an experiment on one small folder. There is also a command-line entry point declared in pyproject.toml as deepsearcher = "deepsearcher.cli:main", and a Dockerfile that exposes port 8000, runs main.py with --enable-cors true, and health-checks http://localhost:8000/docs. The README does not describe the HTTP API those serve, so read main.py before you depend on it.

## Where deep-searcher is the wrong tool

The honest limitation is the release history. The only recent release listed is tagged embedding_model, dated 2025-02-20, and the package version in pyproject.toml is still 0.0.2. A 0.0.x version number is a statement about API stability, and the README's own configuration examples are the surface most likely to move. The last push to the repository was on 2026-09-22, so the code is current, but that is activity, not a compatibility promise. Second, the documentation is uneven. Web crawling is listed under features as "under development", and the README does not document rollback, re-indexing, deletion of a loaded document, or how to point at an existing Milvus collection rather than creating one. Third, the dependency set is broad. pyproject.toml pins firecrawl-py, ibm-watsonx-ai and pdfplumber as core dependencies even if you never touch Firecrawl or Watson, and the all extra pulls in docling, crawl4ai, sentence-transformers and more. In an air-gapped environment that is a real install problem. Finally, if your corpus is small enough to fit in a context window, a reasoning model with the documents pasted in will be simpler and cheaper than standing up Milvus.

## Alternatives and the difference in approach

The closest comparison inside this repository's own world is a plain RAG chain built from LangChain or LlamaIndex. Those frameworks give you the retriever, the prompt template and the chain, and you assemble the reasoning loop yourself; deep-searcher ships the loop as a library with a provider registry on top. The trade is control for convention. A second alternative is a hosted deep research product. Those need no vector database and no API key management on your side, but the documents leave your infrastructure, which is the exact boundary deep-searcher is built around. A third option is Milvus plus a hand-written script: pymilvus is already a dependency here, so if your real need is similarity search with a thin wrapper, the vector database is doing the work and deep-searcher is the part you would be adding. The distinguishing claim in the README is the evaluation and reasoning stage over private data with optional online augmentation, not the retrieval itself.

## Licence, maintenance and what an upgrade costs you

The project is Apache-2.0, declared both in the README badge and in pyproject.toml as license = { file = "LICENSE"}. That is a permissive licence with an explicit patent grant, and it does not oblige you to publish your own code. It also means no vendor can relicense the code out from under you. This is not legal advice; read LICENSE and your own counsel's view before shipping. On maintenance: the last push was on 2026-09-22 and the repository is not archived, so the code is being touched. But the version number and the single recent release mean you should pin. The dev tooling is ruff for lint and format, exposed through the Makefile as lint and format targets, and pytest for tests. Upgrading means re-reading the provider registry: because LLMs and embeddings are selected by string name, a renamed provider or a changed argument key breaks at init_config time rather than at import time, which is at least a loud failure. Budget for re-running ingestion after an embedding model change, since vectors from a different model do not mix in one collection.

## Conclusion

Adopt it if you already keep documents in Milvus or Zilliz Cloud and you want a Python library that returns a written answer rather than a list of chunks. Skip it if you need a maintained web UI, a stable public API, or a project with a release history you can point at. Before committing, install it in a virtual environment, run the quick start against one small folder, and check the CLI at deepsearcher.cli:main for the flags your deployment actually needs.

## FAQ

### What exactly is zilliztech/deep-searcher?

It is a Python library that combines an LLM with a vector database to search, evaluate and reason over private data, returning an answer and a report. The README names enterprise knowledge management, intelligent Q&A and information retrieval as its scenarios.

### Can I use zilliztech/deep-searcher for free?

The library itself is Apache-2.0, so the code is free to use. The LLM and embedding providers you configure are separate services with their own keys and billing, and the README tells you to prepare the matching API key for whichever provider you select.

### Is zilliztech/deep-searcher real or a fake project?

It is a real repository under the zilliztech organization, with a published pip package, a Dockerfile, tests and an Apache-2.0 licence file. The package version in pyproject.toml is 0.0.2, so expect early-stage APIs rather than a finished product.

## Sources

- [License: Apache-2.0](https://github.com/zilliztech/deep-searcher/blob/master/LICENSE)
- [Project website](https://zilliztech.github.io/deep-searcher/)
- [README](https://github.com/zilliztech/deep-searcher/blob/master/README.md)
- [Releases](https://github.com/zilliztech/deep-searcher/releases)
- [zilliztech/deep-searcher on GitHub](https://github.com/zilliztech/deep-searcher)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/zilliztech-deep-searcher