OpenSearch-VL is a fully open recipe for training frontier multimodal deep-research agents with agentic reinforcement learning. In contrast to standard VLMs that answer in a single forward pass, the agent operates as a closed loop: it inspects the image, crops or enhances the regions of interest, issues web and image searches, visits the retrieved pages, and only then writes an answer grounded in the gathered evidence.
Reproducing top-tier multimodal search agents has so far been difficult because the underlying training data, trajectory-synthesis pipelines, and training recipes remain proprietary. This release aims to close that gap: we open-source the data, code, and model checkpoints required to reproduce the paper end-to-end.
The recipe addresses three challenges that we found to be largely independent in practice:
Data. A curation pipeline built on top of the Wikipedia hyperlink graph synthesizes image-grounded multi-hop VQA. Fuzzy entity rewriting and source-anchored visual grounding are used to suppress shortcut solutions in which a single retrieval step is sufficient. The pipeline yields two open datasets: SearchVL-SFT-36k for supervised fine-tuning and SearchVL-RL-8k for reinforcement learning.
Tools. A unified visual and retrieval tool environment (crop, layout_parsing, text_search, image_search, web_search, visit, perspective_correct, super_resolution, sharpen, python_interpreter) is shared across SFT data generation, RL rollout, and inference. This allows the agent both to recover from imperfect visual inputs and to acquire external knowledge through a consistent interface.
Algorithm. A multi-turn fatal-aware GRPO algorithm explicitly handles cascading tool failures during long rollouts. Tokens that follow a fatal step are masked out of the policy gradient, while one-sided advantage clamping preserves the credit assigned to valid pre-failure reasoning rather than penalizing the entire trajectory.
Across seven knowledge-intensive multimodal benchmarks—SimpleVQA, VDR, MMSearch, LiveVQA, BrowseComp-VL, FVQA, and InfoSeek—OpenSearch-VL improves the average score by more than 10 points over the corresponding agentic baselines, and at the 30B / 32B scale matches the accuracy of strong proprietary systems.
🗺️ Overview
This repository provides everything needed to reproduce, fine-tune, and evaluate OpenSearch-VL:
Data Curation Pipeline.
Starting from the English Wikipedia hyperlink graph, we sample multi-hop entity paths and convert them into multi-hop VQA instances by (a) extracting canonical question–answer pairs along the path, (b) rewriting each intermediate entity into a fuzzy descriptor while certifying answer invariance and uniqueness, and (c) anchoring the question on a representative image of the source node — not the answer node — so that single-hop image lookup shortcuts are eliminated. The pipeline finishes with staged tool-demanding filtering and an enhancement subset (random degradations paired with the corresponding restoration tools) before synthesizing multi-turn expert trajectories with answer- and process-level rejection sampling.
Data Curation Pipeline
RL Training Pipeline.
Starting from the SFT-initialized checkpoint, we sample a group of multi-turn trajectories against the real environment $\mathcal{E}$. Each trajectory is scored by a composite reward combining final-task accuracy ($r_{\text{acc}}$), process-level search-query quality ($r_{\text{query}}$), and a multiplicative format gate ($r_{\text{fmt}}$). To preserve valid reasoning when a trajectory eventually triggers cascading tool failures, we apply fatal-aware token masking to truncate the sequence at the fatal step $f_i$ and one-sided advantage clamping ($\hat{A}_i = \max(\widetilde{r}_i, 0)$ for fatal trajectories) during policy optimization, preventing the suppression of viable early reasoning.
RL Pipeline
📊 Main Results
OpenSearch-VL is built on three Qwen3-VL variants and evaluated on 7 multimodal knowledge-intensive QA / web-search benchmarks under the same Pass@1 + GPT-4o judge protocol as VDR-Bench.
Highlights.OpenSearch-VL-8B is the strongest open 8B agent (+3.9 Avg over SenseNova-MARS-8B). OpenSearch-VL-30B-A3B improves the Qwen3-VL agentic baseline by +13.8 Avg, with large gains on VDR (+13.3), MMSearch (+24.5), FVQA (+10.2), and InfoSeek (+16.2). OpenSearch-VL-32B surpasses Gemini-2.5-Pro and Claude-4-Sonnet direct-reasoning baselines on most benchmarks.
Fatal-aware GRPO ablation.
Vanilla search-augmented GRPO improves SFT 64.6 → 67.6 Avg; the hard-masking baseline of Vision-DeepResearch saturates at 67.7; fatal masking alone reaches 69.1; our full method with one-sided advantage clamping reaches 71.8 — a +4.2 gain over vanilla GRPO and the best score on every benchmark.
turn_acc_combined
Fatal-aware GRPO sustains a higher number of tool-use turns and a higher batch accuracy than vanilla GRPO and the Hard-Mask baseline — encouraging productive exploration rather than prematurely suppressing difficult rollouts.
🔎 Case Study
The example below illustrates a representative OpenSearch-VL trajectory on a knowledge-intensive visual question: “In what year did this bridge open?” The answer cannot be read directly from the image or reliably produced by parametric knowledge alone. Instead, the agent progressively grounds the query through tool use.
OpenSearch-VL case study
Tool-use flow.
Visual inspection — The agent identifies the roadside sign as the most useful visual clue.
Crop — It zooms into the sign to obtain a cleaner local view.
Image search — The cropped region helps identify the structure as the Kessock Bridge.
Text search / verification — A targeted search verifies the official opening year as 1982.
This case highlights the core behavior encouraged by OpenSearch-VL: the agent does not guess from a single model pass, but chains visual perception, image retrieval, and textual evidence acquisition until the answer is grounded.
≥ 1× H100 / H800 / A100-80GB for 8B (multi-node for 30B / 32B)
NCCL / RDMA
InfiniBand / RoCE recommended for multi-node; see RL/rllm/.env.example
The three components share most of their Python dependencies (PyTorch, transformers, transformer_engine, flash-attn, deepspeed, ray, qwen-vl-utils, sglang) — we recommend installing each sub-project into its own virtual environment.
External API keys
All keys are optional; components gracefully no-op if unset.
Local checkpoints for the three Qwen3-VL variants (overrideable via --checkpoint).
FVQA_IMAGE_DIR
infer
Optional fallback directory of <case_id>.<ext> images used when a benchmark URL is unreachable.
WANDB_API_KEY
SFT, RL
W&B logging.
Two templates are provided: RL/rllm/.env.example for the RL workers, and infer/.env.example for inference + judge. Copy whichever applies and source it before launching.
🏋️ Agentic SFT · code/SFT
Cold-starts the base VLM on 7 tool-use datasets (FVQA, Palace, WebQA, LiveVQA, WikiArt, Wiki-zh, Wiki-en — together forming SearchVL-SFT-36k, with an average of 6.3 tool-invocation turns per trajectory). We perform a full-parameter fine-tune of the LLM + vision tower + projector with DeepSpeed ZeRO-3, distributed via Ray.
Download the SearchVL-SFT-36k bundle from the HuggingFace collection and place the 7 sub-sets under code/SFT/data/ so that the relativefile_name values in data/dataset_info.json resolve:
Asynchronous agentic RLOO / GRPO / PPO on top of the SFT checkpoint, using rLLM's AgentWorkflowEngine, verl as the policy-optimization backend, and Megatron-LM + mbridge for large-scale model parallelism. Trajectories are rolled out by sglang; Megatron handles actor / ref updates.
cp RL/rllm/.env.example RL/rllm/.env # edit keys as needed
Data preparation
The workflow expects rllm.data.DatasetRegistry to hold a dataset named Vision-DeepResearch-QA (i.e. SearchVL-RL-8k). Two helpers in RL/rllm/vision_deepresearch_async_workflow/data_prepare/ handle the conversion:
bash
1cd RL/rllm/vision_deepresearch_async_workflow/data_prepare
23# 1) Extract embedded image bytes → PNG + JSONL4DATA_ROOT=./data/Vision-DeepResearch-RL-Data \5bash convert_parquet2jsonl.sh
67# 2) Register it with rLLM as "Vision-DeepResearch-QA" (90 / 10 split)8JSONL_PATH=./data/Vision-DeepResearch-RL-Data/vision-deepresearch_RL_Demo_1k.jsonl \9bash register_rl_dataset.sh
Launch
All run scripts cd into rllm/, auto-source .env, and call python -m vision_deepresearch_async_workflow.train_deepresearch_workflow_megatron with the right Hydra overrides.
bash
1# Primary configuration in the paper: 8B dense, 8 nodes × 8 GPU2bash RL/rllm/vision_deepresearch_async_workflow/run/qwen3-vl-8b-multi-node.sh
34# Other presets:5bash RL/rllm/vision_deepresearch_async_workflow/run/qwen3-vl-8b-single-node.sh # 1-node smoke test6bash RL/rllm/vision_deepresearch_async_workflow/run/qwen3-vl-30b-3b-multi-node.sh # 30B-A3B MoE7bash RL/rllm/vision_deepresearch_async_workflow/run/qwen3-vl-32b-multi-node.sh # 32B dense
Checkpoints go to checkpoints/${project_name}/${exp_name}/; trajectories can be dumped to $TRAJ_DUMP_DIR (default ./trajectory_dumps/<exp>/).
Reproducing the paper
Variant
Script
Cluster
OpenSearch-VL-8B
qwen3-vl-8b-multi-node.sh
8 × 8 H100 / H800
OpenSearch-VL-30B-A3B
qwen3-vl-30b-3b-multi-node.sh
8 × 8 H100 / H800
OpenSearch-VL-32B
qwen3-vl-32b-multi-node.sh
16 × 8 H100 / H800
Full details, environment variables, and cluster notes: code/RL/README.md.
📊 Inference & Evaluation · code/infer
Modular Python package that drives the trained model as a tool-using Visual Investigation Agent, plus a GPT-4o judge for standardized benchmark scoring. The same agent loop, tool environment and search/visual utilities are shared across all three Qwen3-VL backends and the optional Claude Opus 4.5 backend; the variant is selected with a single --model flag.
Claude Opus 4.5 via HMAC gateway (no GPU required)
Multi-GPU model parallelism is enabled automatically when --gpus 0,1,... lists more than one device (device_map="auto"); single-GPU placement uses device_map={"": "cuda:N"}. The MoE scatter dtype patch for 30B-A3B is applied automatically.
bash
1# Source the env template first; only the entries you need have to be filled in.2cp infer/.env.example ~/.opensearch-vl.env
3source ~/.opensearch-vl.env
45# Dense Qwen3-VL-8B on a single GPU6python infer/run_infer.py --model 8b --gpus 0\7 --data-path /path/to/benchmark.parquet \8 --output-dir ./outputs/opensearch_vl_8b \9 --start 0 --end 10001011# MoE Qwen3-VL-30B-A3B with 4-way model parallel (auto-applies the scatter dtype patch)12python infer/run_infer.py --model 30b-a3b --gpus 0,1,2,3 \13 --checkpoint /path/to/OpenSearch-VL-30B-A3B \14 --data-path /path/to/benchmark.parquet \15 --output-dir ./outputs/opensearch_vl_30b_a3b
1617# Claude Opus 4.5 (CLAUDE_API_HOST / _USER / _KEY required)18python infer/run_infer.py --model claude \19 --data-path /path/to/benchmark.parquet \20 --output-dir ./outputs/claude_opus
The shell wrapper infer/run_infer.sh reads the same parameters from environment variables (MODEL, GPUS, DATA_PATH, OUTPUT_DIR, LIMIT, CATEGORY, ...) for one-line invocations.
Benchmark evaluation
eval_with_gpt4o.py consumes the trajectory directory produced above and calls a GPT-4o-class judge to compute per-sample correctness using the VDR-Bench evaluation prompt:
--answer_file is required for VDR-Bench (pass the .parquet with id / answer columns).
run_eval.sh is a thin driver that chains the five reported evaluations (BrowseComp-VL L1, BrowseComp-VL L2, HLE, VDR-Bench testmini × 2 models). Configure trajectory directories via env variables (TRAJ_BC_VL_LEVEL1, TRAJ_BC_VL_LEVEL2, TRAJ_HLE, TRAJ_VDR_PRIMARY, TRAJ_VDR_SECONDARY, VDR_ANSWER_PARQUET) and run:
