README.md

metadata

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 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).
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 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 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

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

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
• GenSearcher/Gen-Searcher-8B
• FireRed-Image-Edit-1.1