deep-searcher

---

DeepSearcher combines cutting-edge LLMs (OpenAI o3, Qwen3, DeepSeek, Grok 4, Claude 4 Sonnet, Llama 4, QwQ, etc.) and Vector Databases (Milvus, Zilliz Cloud etc.) to perform search, evaluation, and reasoning based on private data, providing highly accurate answer and comprehensive report. This project is suitable for enterprise knowledge management, intelligent Q&A systems, and information retrieval scenarios.

🚀 Features

• Private Data Search: Maximizes the utilization of enterprise internal data while ensuring data security. When necessary, it can integrate online content for more accurate answers.
• Vector Database Management: Supports Milvus and other vector databases, allowing data partitioning for efficient retrieval.
• Flexible Embedding Options: Compatible with multiple embedding models for optimal selection.
• Multiple LLM Support: Supports DeepSeek, OpenAI, and other large models for intelligent Q&A and content generation.
• Document Loader: Supports local file loading, with web crawling capabilities under development.

---

🎉 Demo

📖 Quick Start

Installation

Install DeepSearcher using one of the following methods:

Option 1: Using pip

Create and activate a virtual environment(Python 3.10 version is recommended).

python -m venv .venv
source .venv/bin/activate

Install DeepSearcher

pip install deepsearcher

For optional dependencies, e.g., ollama:

pip install "deepsearcher[ollama]"

Option 2: Install in Development Mode

We recommend using uv for faster and more reliable installation. Follow the offical installation instructions to install it.

Clone the repository and navigate to the project directory:

git clone https://github.com/zilliztech/deep-searcher.git && cd deep-searcher

Synchronize and install dependencies:

uv sync
source .venv/bin/activate

For more detailed development setup and optional dependency installation options, see CONTRIBUTING.md.

Quick start demo

To run this quick start demo, please prepare your OPENAI_API_KEY in your environment variables. If you change the LLM in the configuration, make sure to prepare the corresponding API key.

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

config = Configuration()

# Customize your config here,
# more configuration see the Configuration Details section below.
config.set_provider_config("llm", "OpenAI", {"model": "o1-mini"})
config.set_provider_config("embedding", "OpenAIEmbedding", {"model": "text-embedding-ada-002"})
init_config(config = config)

# Load your local data
from deepsearcher.offline_loading import load_from_local_files
load_from_local_files(paths_or_directory=your_local_path)

# (Optional) Load from web crawling (`FIRECRAWL_API_KEY` env variable required)
from deepsearcher.offline_loading import load_from_website
load_from_website(urls=website_url)

# Query
result = query("Write a report about xxx.") # Your question here

Configuration Details:

LLM Configuration

Embedding Model Configuration

Vector Database Configuration

File Loader Configuration

Web Crawler Configuration

Python CLI Mode

Load

deepsearcher load "your_local_path_or_url"
# load into a specific collection
deepsearcher load "your_local_path_or_url" --collection_name "your_collection_name" --collection_desc "your_collection_description"

Example loading from local file:

deepsearcher load "/path/to/your/local/file.pdf"
# or more files at once
deepsearcher load "/path/to/your/local/file1.pdf" "/path/to/your/local/file2.md"

Example loading from url (Set FIRECRAWL_API_KEY in your environment variables, see FireCrawl for more details):

deepsearcher load "https://www.wikiwand.com/en/articles/DeepSeek"

Query

deepsearcher query "Write a report about xxx."

More help information

deepsearcher --help

For more help information about a specific subcommand, you can use deepsearcher [subcommand] --help.

deepsearcher load --help
deepsearcher query --help

Deployment

Configure modules

You can configure all arguments by modifying config.yaml to set up your system with default modules. For example, set your OPENAI_API_KEY in the llm section of the YAML file.

Start service

The main script will run a FastAPI service with default address localhost:8000.

$ python main.py

Access via browser

You can open url http://localhost:8000/docs in browser to access the web service. Click on the button "Try it out", it allows you to fill the parameters and directly interact with the API.

---

❓ Q&A

Q1: Why I failed to parse LLM output format / How to select the LLM?

A1: Small LLMs struggle to follow the prompt to generate a desired response, which usually cause the format parsing problem. A better practice is to use large reasoning models e.g. deepseek-r1 671b, OpenAI o-series, Claude 4 sonnet, etc. as your LLM.

---

Q2: OSError: We couldn't connect to 'https://huggingface.co' to load this file, couldn't find it in the cached files and it looks like GPTCache/paraphrase-albert-small-v2 is not the path to a directory containing a file named config.json. Checkout your internet connection or see how to run the library in offline mode at 'https://huggingface.co/docs/transformers/installation#offline-mode'.

A2: This is mainly due to abnormal access to huggingface, which may be a network or permission problem. You can try the following two methods:

1. If there is a network problem, set up a proxy, try adding the following environment variable.

export HF_ENDPOINT=https://hf-mirror.com

2. If there is a permission problem, set up a personal token, try adding the following environment variable.

export HUGGING_FACE_HUB_TOKEN=xxxx

---

Q3: DeepSearcher doesn't run in Jupyter notebook.

A3: Install nest_asyncio and then put this code block in front of your jupyter notebook.

pip install nest_asyncio

import nest_asyncio
nest_asyncio.apply()

---

🔧 Module Support

🔹 Embedding Models

• Open-source embedding models
• OpenAI (OPENAI_API_KEY env variable required)
• VoyageAI (VOYAGE_API_KEY env variable required)
• Amazon Bedrock (AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY env variable required)
• FastEmbed
• PPIO (PPIO_API_KEY env variable required)
• Novita AI (NOVITA_API_KEY env variable required)
• IBM watsonx.ai (WATSONX_APIKEY, WATSONX_URL, WATSONX_PROJECT_ID env variables required)
• Jiekou.AI (JIEKOU_API_KEY env variable required)

🔹 LLM Support

• OpenAI (OPENAI_API_KEY env variable required)
• DeepSeek (DEEPSEEK_API_KEY env variable required)
• XAI Grok (XAI_API_KEY env variable required)
• Anthropic Claude (ANTHROPIC_API_KEY env variable required)
• SiliconFlow Inference Service (SILICONFLOW_API_KEY env variable required)
• PPIO (PPIO_API_KEY env variable required)
• TogetherAI Inference Service (TOGETHER_API_KEY env variable required)
• Google Gemini (GEMINI_API_KEY env variable required)
• SambaNova Cloud Inference Service (SAMBANOVA_API_KEY env variable required)
• Ollama
• Novita AI (NOVITA_API_KEY env variable required)
• IBM watsonx.ai (WATSONX_APIKEY, WATSONX_URL, WATSONX_PROJECT_ID env variable required)
• Jiekou.AI (JIEKOU_API_KEY env variable required)

🔹 Document Loader

• Local File
  • PDF(with txt/md) loader
  • Unstructured (under development) (UNSTRUCTURED_API_KEY and UNSTRUCTURED_URL env variables required)
• Web Crawler
  • FireCrawl (FIRECRAWL_API_KEY env variable required)
  • Jina Reader (JINA_API_TOKEN env variable required)
  • Crawl4AI (You should run command crawl4ai-setup for the first time)

🔹 Vector Database Support

• Milvus and Zilliz Cloud (fully managed Milvus)
• Qdrant

---

📊 Evaluation

See the Evaluation directory for more details.

---

📌 Future Plans

• Enhance web crawling functionality
• Support more vector databases (e.g., FAISS...)
• Add support for additional large models
• Provide RESTful API interface (DONE)

We welcome contributions! Star & Fork the project and help us build a more powerful DeepSearcher! 🎯