| ---
|
| title: GenSearcher + FireRed
|
| emoji: 🔍
|
| colorFrom: blue
|
| colorTo: purple
|
| sdk: docker
|
| pinned: false
|
| suggested_hardware: a100-large
|
| ---
|
|
|
| # GenSearcher + FireRed-Image-Edit-1.1
|
|
|
| This Space runs the **official** [Gen-Searcher](https://github.com/tulerfeng/Gen-Searcher) image workflow (`GenImageDeepResearchWorkflow` + `create_gen_image_tools`) against an OpenAI-compatible **GenSearcher-8B** server, then calls **FireRed-Image-Edit-1.1** through the same HTTP `/generate` contract as the upstream Qwen image API.
|
|
|
| ## Architecture
|
|
|
| 1. **Agent** — vendored `vision_deepresearch_async_workflow` from Gen-Searcher (unchanged `create_gen_image_tools`).
|
| 2. **LLM** — `OPENAI_BASE_URL` + `GEN_EVAL_MODEL` (default `Gen-Searcher-8B`).
|
| 3. **Browse summaries** — `BROWSE_SUMMARY_BASE_URL` + `BROWSE_SUMMARY_MODEL` with `BROWSE_GENERATE_ENGINE=vllm` (see [`.env.gen_image`](https://github.com/tulerfeng/Gen-Searcher/blob/main/Gen-DeepResearch-RL/rllm/.env.gen_image)).
|
| 4. **Image generation** — local FastAPI adapter at `QWEN_EDIT_APP_URL` (default `http://127.0.0.1:8765`), compatible with `call_qwen_edit_to_generate_image` in upstream `gen_image_deepresearch_reward.py`.
|
|
|
| ## Space secrets / environment
|
|
|
| Configure in the Space **Settings → Variables and secrets** (or a mounted `.env.gen_image`):
|
|
|
| | Variable | Purpose |
|
| |----------|---------|
|
| | `SERPER_KEY_ID` | Optional. Serper API key for Google web + image search. If **unset**, text and image search use **DuckDuckGo** (no key; quality and availability vary, and some datacenter IPs may be rate-limited). |
|
| | `JINA_API_KEYS` | Optional. Jina reader for `r.jina.ai`. If **unset**, the visit tool uses a **direct HTTP GET** and strips HTML to text (many sites block bots or return paywalls). |
|
| | `WEB_TEXT_SEARCH_PROVIDER` | Override text search: `duckduckgo` or `serper` (default is **auto**: Serper when `SERPER_KEY_ID` is set, else DuckDuckGo). |
|
| | `WEB_IMAGE_SEARCH_PROVIDER` | Override image search: `duckduckgo` or `serper` (same auto rule using `SERPER_KEY_ID`). |
|
| | `BROWSE_READ_ENGINE` | Override page fetch: `direct` or `jina` (default is **auto**: Jina when `JINA_API_KEYS` is set, else direct). |
|
| | `OPENAI_BASE_URL` | OpenAI-compatible base URL for GenSearcher-8B (e.g. `https://.../v1`) |
|
| | `OPENAI_API_KEY` | API key for that endpoint (use `EMPTY` if unused) |
|
| | `GEN_EVAL_MODEL` | Served model name (default `Gen-Searcher-8B`) |
|
| | `BROWSE_SUMMARY_BASE_URL` | OpenAI-compatible base for Qwen3-VL browse summarizer |
|
| | `BROWSE_SUMMARY_MODEL` | Model id (e.g. `Qwen3-VL-30B-A3B-Instruct`) |
|
| | `BROWSE_SUMMARY_API_KEY` | Key for browse server (`EMPTY` if none) |
|
| | `BROWSE_GENERATE_ENGINE` | Set to `vllm` for OpenAI-compatible servers |
|
|
|
| If the FireRed adapter runs **inside** this container (default), you usually do **not** need to set `QWEN_EDIT_APP_URL` (the entrypoint sets it to `http://127.0.0.1:8765`).
|
|
|
| See [`dotenv.example`](./dotenv.example) for a full template.
|
|
|
| ## Hardware
|
|
|
| - **Minimum practical:** 1× GPU for FireRed + Gradio, with **external** vLLM endpoints for GenSearcher and browse (set `START_VLLM_GENSEARCHER=0`, `START_VLLM_BROWSE=0` — defaults).
|
| - **Full local (as in upstream scripts):** multiple GPUs — enable `START_VLLM_GENSEARCHER=1`, `START_VLLM_BROWSE=1`, and set `GENSEARCHER_CUDA_VISIBLE_DEVICES`, `BROWSE_CUDA_VISIBLE_DEVICES`, `FIRERED_CUDA_VISIBLE_DEVICES` to disjoint GPU indices.
|
|
|
| ## Troubleshooting: `Connection error` / model call failed
|
|
|
| The agent talks to your LLM over HTTP (OpenAI-compatible). A **connection error** almost always means **nothing is listening** at `OPENAI_BASE_URL`, or the URL is wrong for where the Space runs.
|
|
|
| 1. **Default `http://127.0.0.1:8002/v1`** only works if **vLLM for GenSearcher-8B** is started **inside the same container** (`START_VLLM_GENSEARCHER=1` and enough GPU). On a typical 1×GPU Space with only FireRed running, **127.0.0.1:8002 is empty** → connection error.
|
|
|
| 2. **Fix:** Set Space secret **`OPENAI_BASE_URL`** to a **reachable** HTTPS (or HTTP) base URL that ends with **`/v1`**, where you host [GenSearcher/Gen-Searcher-8B](https://huggingface.co/GenSearcher/Gen-Searcher-8B) behind vLLM, Text Generation Inference, or any OpenAI-compatible stack. The UI shows an **endpoint check** on load; use **Re-check endpoints** after you change secrets.
|
|
|
| 3. **Browse tool:** If `BROWSE_GENERATE_ENGINE=vllm`, set **`BROWSE_SUMMARY_BASE_URL`** the same way (not localhost unless you run that vLLM in-container with `START_VLLM_BROWSE=1`).
|
|
|
| ## Local build
|
|
|
| ```bash
|
| cd hf-space
|
| docker build -t gensearcher-firered .
|
| docker run --gpus all -p 7860:7860 --env-file .env.gen_image gensearcher-firered
|
| ```
|
|
|
| ## Deploy to your Hugging Face account
|
|
|
| ```bash
|
| hf auth login
|
| hf repos create JSCPPProgrammer/gensearcher-firered --type space --sdk docker --private
|
| # from hf-space/
|
| hf upload JSCPPProgrammer/gensearcher-firered . .
|
| ```
|
|
|
| Then set Space GPU and secrets in the Hub UI.
|
|
|
| ## References
|
|
|
| - [Gen-Searcher](https://github.com/tulerfeng/Gen-Searcher)
|
| - [GenSearcher/Gen-Searcher-8B](https://huggingface.co/GenSearcher/Gen-Searcher-8B)
|
| - [FireRed-Image-Edit-1.1](https://huggingface.co/FireRedTeam/FireRed-Image-Edit-1.1)
|
| |
