DOCSEARCHbyAlgolia
Submit Docs

OpenDeepSearch Documentation

repository·main·Indexed 26 days ago

https://github.com/sentient-agi/opendeepsearch

A lightweight search tool for AI agents that enables deep web search and retrieval through semantic search and reranking. Optimized for the Hugging Face SmolAgents ecosystem, it supports search providers like Serper.dev and SearXNG, and reranking solutions including Jina AI and self-hosted Infinity servers. It features two search modes (Default and Pro) and integrates with LiteLLM for various LLM providers.

Tokens
8.1K
Snippets
15
Records
54
Agent score
85%

What's inside OpenDeepSearch

  1. Understand OpenDeepSearch Search Modes

    main

    OpenDeepSearch provides two modes to balance speed and depth:

    1. Default Mode ⚡

      • Uses SERP-based interaction.
      • Minimal processing overhead.
      • Best for single-hop, straightforward queries and fast information retrieval.

    2. Pro Mode 🔍

      • Involves comprehensive web scraping.
      • Implements semantic reranking and advanced post-processing.
      • Best for multi-hop queries, complex requirements, and detailed information gathering requiring cross-reference verification.

  3. Run Task Evaluations with parallel processing

    main

    Run evaluations on datasets using parallel workers. You can specify the model, model type, agent action type, and the number of trials.

    Parameters:

    • --date: Optional date for the evaluation.
    • --eval-tasks: List of paths to CSV files containing evaluation tasks. Defaults to ["./evals/datasets/frames_test_set.csv", "./evals/datasets/simple_qa_test_set.csv"].
    • --search-model-id: Model ID for the search tool. Defaults to fireworks_ai/accounts/fireworks/models/llama-v3p3-70b-instruct.
    • --model-type: Type of model to use: LiteLLMModel or HfApiModel. Defaults to LiteLLMModel.
    • --model-id: ID of the model to use. Defaults to fireworks_ai/accounts/fireworks/models/qwq-32b.
    • --agent-action-type: Type of agent action: codeact, tool-calling, or vanilla. Defaults to codeact.
    • --parallel-workers: Number of parallel workers to use. Defaults to 8.
    • --num-trials: Number of evaluation trials to run. Defaults to 1.
    python ./evals/eval_tasks.py --parallel-workers=8 --num-trials=1 --eval-tasks=./evals/datasets/frames_test_set.csv ./evals/datasets/simple_qa_test_set.csv

  4. Run the OpenDeepSearch Gradio Demo

    main

    Launch a local web interface to interactively test search queries and modes using the provided Gradio demo script.

    Basic command:

    python gradio_demo.py

    Customization via CLI flags:

    • --model-name: LLM model to use for search
    • --orchestrator-model: LLM model for the agent orchestrator
    • --reranker: Reranker to use (jina or infinity)
    • --search-provider: Search provider to use (serper or searxng)
    • --searxng-instance: SearXNG instance URL (required if using searxng)
    • --searxng-api-key: SearXNG API key (optional)
    • --serper-api-key: Serper API key (optional, defaults to env var)
    • --openai-base-url: OpenAI API base URL (optional, defaults to OPENAI_BASE_URL env var)
    # Using Serper (default)
python gradio_demo.py --model-name "openrouter/google/gemini-2.0-flash-001" --reranker "jina"

# Using SearXNG
python gradio_demo.py --model-name "openrouter/google/gemini-2.0-flash-001" --reranker "jina" \
  --search-provider "searxng" --searxng-instance "https://your-searxng-instance.com" \
  --searxng-api-key "your-api-key-here"

  5. Install OpenDeepSearch

    main

    You can install OpenDeepSearch using pip or uv. Ensure you have torch installed on your system before proceeding.

    pip install -e .
pip install -r requirements.txt

    Alternatively, using uv is recommended for faster dependency resolution:

    uv pip install -e .
uv pip install -r requirements.txt

  6. Install OpenDeepSearch using PDM

    main

    If you prefer using PDM as your package manager, follow these steps:

    1. Install PDM:
    curl -sSL https://raw.githubusercontent.com/pdm-project/pdm/main/install-pdm.py | python3 -
    1. Initialize the project:
    pdm init
    1. Install dependencies:
    pdm install
    1. Activate the virtual environment:
    eval "$(pdm venv activate)"
    curl -sSL https://raw.githubusercontent.com/pdm-project/pdm/main/install-pdm.py | python3 -
pdm init
pdm install
eval "$(pdm venv activate)"

  8. Deploy an Infinity reranker server via Docker

    main

    For high-performance local reranking, you can run an Infinity server. This requires an NVIDIA GPU with Compute Capability $\ge$ 8.0 and approximately 16-32GB of VRAM.

    Use the following command to start a server using the Alibaba-NLP/gte-Qwen2-7B-instruct model on port 7997:

    docker run \
-v $PWD/data:/app/.cache --gpus "0" -p "7997":"7997" \
michaelf34/infinity:0.0.68-trt-onnx \
v2 --model-id Alibaba-NLP/gte-Qwen2-7B-instruct --revision "refs/pr/38" \
--dtype bfloat16 --batch-size 8 --device cuda --engine torch --port 7997 \
--no-bettertransformer

    Key Parameters:

    • --model-id: The Hugging Face model ID.
    • --dtype: Inference data type (e.g., bfloat16).
    • --batch-size: Inference batch size.
    • --port: The port to expose the server on.

    Available Docker Images:

    • latest-cpu: For CPU-only inference.
    • latest-rocm: For AMD ROCm GPUs.
    • latest-trt-onnx: For NVIDIA GPUs with TensorRT/ONNX optimizations.

  9. Configure LiteLLM Provider and Models

    main

    OpenDeepSearch uses LiteLLM to interface with various LLM providers (OpenAI, Anthropic, Google, etc.).

    API Keys

    Set your provider's API key as an environment variable:

    export <PROVIDER>_API_KEY='your-api-key-here' # e.g., OPENAI_API_KEY, ANTHROPIC_API_KEY

    Custom Endpoints

    For OpenAI-compatible proxies or self-hosted endpoints:

    export OPENAI_BASE_URL='https://your-custom-openai-endpoint.com'

    Model Selection via Environment Variables

    You can set default model IDs for specific tasks:

    • LITELLM_MODEL_ID: General fallback model.
    • LITELLM_SEARCH_MODEL_ID: Model used for search tasks.
    • LITELLM_ORCHESTRATOR_MODEL_ID: Model used for agent orchestration.
    • LITELLM_EVAL_MODEL_ID: Model used for evaluation tasks.

    Example:

    export LITELLM_MODEL_ID='openrouter/google/gemini-2.0-flash-001'

  10. Configure Search Providers

    main

    OpenDeepSearch supports two main search provider options:

    Serper.dev

    Retrieve an API key from serper.dev and set it as an environment variable:

    export SERPER_API_KEY='your-api-key-here'

    SearXNG

    Use a self-hosted or public SearXNG instance by specifying the URL and an optional API key:

    export SEARXNG_INSTANCE_URL='https://your-searxng-instance.com'
export SEARXNG_API_KEY='your-api-key-here'
    export SERPER_API_KEY='your-api-key-here'
# OR
export SEARXNG_INSTANCE_URL='https://your-searxng-instance.com'
export SEARXNG_API_KEY='your-api-key-here'

  12. Integrate OpenDeepSearch with SmolAgents

    main

    OpenDeepSearch is designed to be used as a tool within the smolagents framework. You can pass an OpenDeepSearchTool instance into a CodeAgent or a ToolCallingAgent to enable reasoning and code-generation-based search capabilities.

    from opendeepsearch import OpenDeepSearchTool
from smolagents import CodeAgent, LiteLLMModel
import os

# Setup environment
os.environ["SERPER_API_KEY"] = "your-serper-api-key-here"
os.environ["OPENROUTER_API_KEY"] = "your-openrouter-api-key-here"
os.environ["JINA_API_KEY"] = "your-jina-api-key-here"

# Initialize OpenDeepSearch tool
search_agent = OpenDeepSearchTool(
    model_name="openrouter/google/gemini-2.0-flash-001",
    reranker="jina"
)

# Initialize SmolAgents model
model = LiteLLMModel(
    "openrouter/google/gemini-2.0-flash-001",
    temperature=0.2
)

# Create agent with the search tool
code_agent = CodeAgent(tools=[search_agent], model=model)
query = "How long would a cheetah at full speed take to run the length of Pont Alexandre III?"
result = code_agent.run(query)

print(result)