- π Introduction
- πΊοΈ Overview
- π Method Overview
- π Main Results
- π Case Study
- π Repository Layout
- π οΈ Prerequisites
- ποΈ Agentic SFT Β·
code/SFT - π Agentic RL Β·
code/RL - π Inference & Evaluation Β·
opensearch_vl - π§ TODO
- π Acknowledgements
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.
This repository provides everything needed to reproduce, fine-tune, and evaluate OpenSearch-VL:
| Component | Path | Description |
|---|---|---|
| SFT Training | SFT/ |
Agentic cold-start with LLaMA-Factory + Ray + ZeRO-3 (full-parameter fine-tune of LLM + ViT + projector) |
| RL Training | RL/ |
Asynchronous agentic RLOO/GRPO on top of SFT, built on rLLM + verl + Megatron-LM + sglang |
| Inference & Evaluation | opensearch_vl/ |
Unified run_infer.py --model {8b,30b-a3b,32b,claude} rollout + GPT-4o judge for BrowseComp-VL, HLE, VDR-Bench |
| Models | OpenSearch-VL | OpenSearch-VL-{8B, 30B-A3B, 32B} checkpoints |
| Datasets | OpenSearch-VL | SearchVL-SFT-36k (cold-start) and SearchVL-RL-8k (RL) |
ββββββββββββββββββ ββββββββββββββββββ ββββββββββββββββββββββ
β Qwen3-VL base β βββ β Agentic SFT β βββ β Async Agentic RL β ββββΆ OpenSearch-VL
β (HF weights) β β (code/SFT) β β (code/RL) β
ββββββββββββββββββ ββββββββββββββββββ ββββββββββββββββββββββ
β β
βΌ βΌ
SearchVL-SFT-36k SearchVL-RL-8k
7-domain tool-use Vision-DeepResearch-QA
cold-start trajectories (RLOO / GRPO + fatal-aware)
OpenSearch-VL is equipped with a heterogeneous tool set
| Category | Tools | Purpose |
|---|---|---|
|
Retrieval ( |
text_search, image_search, web_search, visit
|
Acquire external textual / visual evidence and visit pages |
|
Image Enhancement ( |
sharpen, super_resolution, perspective_correct
|
Repair blurry, low-resolution, or skewed inputs before retrieval |
|
Attention & Parsing ( |
crop, layout_parsing (OCR) |
Localize regions of interest and decode fine-grained content |
| Computation | python_interpreter |
Numerical / programmatic computation on retrieved evidence |
- Get started β Prerequisites
- Train your own SFT model β Agentic SFT
- Run agentic RL β Agentic RL
- Inference & benchmark β Inference & Evaluation
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.
RL Training Pipeline.
Starting from the SFT-initialized checkpoint, we sample a group of multi-turn trajectories against the real environment
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.
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.
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.
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.
code/
βββ SFT/ # agentic supervised fine-tuning (LLaMA-Factory fork)
β βββ examples/agentic_full/ # training YAMLs for Qwen2.5-VL / Qwen3-VL / Qwen3.5-VL
β βββ examples/deepspeed/ # ZeRO-2 / ZeRO-3 configs
β βββ data/dataset_info.json # 7 agentic-SFT datasets (relative paths)
β βββ src/llamafactory/ # LLaMA-Factory source (trainer, data loader, CLI)
β βββ README.md # SFT-specific instructions
β
βββ RL/ # reinforcement learning on the SFT checkpoint
β βββ rllm/ # rLLM + verl + vision_deepresearch_async_workflow/
β βββ Megatron-LM/ # Megatron backend
β βββ mbridge/ # HF β Megatron parallelism bridge
β βββ README.md # RL-specific instructions
β
βββ opensearch_vl/ # inference + benchmark evaluation (first-party package)
β βββ run_infer.py # unified entrypoint (--model 8b|32b|30b-a3b|claude)
β βββ run_infer.sh # env-driven launcher around run_infer.py
β βββ eval_with_gpt4o.py # GPT-4o judge for BrowseComp-VL / HLE / VDR-Bench
β βββ run_eval.sh # env-driven judge driver across all benchmarks
β βββ .env.example # template for inference / judge / search keys
β βββ opensearch_infer/ # modular package: config, prompts, auth, tools,
β # search, runners (Claude + Qwen3-VL dense / MoE),
β # message converters, multi-turn pipeline
β
βββ README.md # (this file)
| Component | Minimum |
|---|---|
| Python | 3.10+ |
| CUDA | 12.1+ (12.4 recommended) |
| PyTorch | β₯ 2.4 with CUDA support |
| GPU | β₯ 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.
All keys are optional; components gracefully no-op if unset.
| Variable | Used by | Purpose |
|---|---|---|
API_GATEWAY_HOST / API_GATEWAY_USER / API_GATEWAY_KEY |
RL | Optional HMAC-secured gateway that proxies Serper + Jina behind one credential (set on RL workers). |
API_HOST / API_USER / API_KEY |
opensearch_vl | Same gateway, named to match the inference package's env vars. |
SERPER_API_KEY |
RL, opensearch_vl | Serper.dev text & image search (used when no gateway is configured). |
JINA_API_KEY |
RL, opensearch_vl | Jina AI reader (page visit / content extraction). |
QWEN_API_BASE / QWEN_MODEL_NAME |
opensearch_vl | OpenAI-compatible chat-completions server used for search summarization (defaults to a local Qwen3-32B). |
LAYOUT_PARSING_API_URL / LAYOUT_PARSING_TOKEN |
RL, opensearch_vl | PP-StructureV3-compatible OCR / layout endpoint. |
CLAUDE_API_HOST / CLAUDE_API_USER / CLAUDE_API_KEY |
opensearch_vl | Optional HMAC-secured gateway for the Claude Opus 4.5 backend. |
JUDGE_API_BASE_URL / JUDGE_APP_ID / JUDGE_APP_KEY / JUDGE_MODEL_MARKER |
opensearch_vl | OpenAI-compatible GPT-4o judge used by eval_with_gpt4o.py. |
QWEN3VL_8B_PATH / QWEN3VL_32B_PATH / QWEN3VL_30B_A3B_PATH |
opensearch_vl | Local checkpoints for the three Qwen3-VL variants (overrideable via --checkpoint). |
FVQA_IMAGE_DIR |
opensearch_vl | 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 opensearch_vl/.env.example for inference + judge. Copy whichever applies and source it before launching.
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.
cd code/SFT
pip install -e ".[torch,metrics,deepspeed,ray]"
pip install qwen-vl-utils pillow av decord torchvision flash-attnDownload the SearchVL-SFT-36k bundle from the HuggingFace collection and place the 7 sub-sets under code/SFT/data/ so that the relative file_name values in data/dataset_info.json resolve:
SFT/data/
βββ dataset_info.json
βββ new_fvqa/fvqa_llama_factory_clean.json
βββ palace/palace_llama_factory_filtered.json
βββ WebQA/webqa_llama_factory_filtered.json
βββ new_livevqa/livevqa_llama_factory_filtered.json
βββ wikiart/wikiart_llama_factory_filtered.json
βββ wiki_en/wiki_en_llama_factory_filtered.json
βββ wiki_zh/wiki_zh_llama_factory_filtered.json
Each JSON is in ShareGPT format with conversations, images, system, and tools columns.
cd code/SFT
# Multi-node Ray (16 nodes Γ 8 GPU by default):
USE_RAY=1 llamafactory-cli train \
examples/agentic_full/qwen3_vl_full_sft_8b_ray.yaml
# Single-node smoke test:
FORCE_TORCHRUN=1 NNODES=1 NPROC_PER_NODE=8 llamafactory-cli train \
examples/agentic_full/qwen3_vl_full_sft_8b_ray.yamlEdit ray_num_workers, placement_strategy, and NCCL / IB vars to match your cluster.
| YAML | Model | # workers |
|---|---|---|
qwen3_vl_full_sft_8b_ray.yaml |
Qwen3-VL-8B-Instruct | 256 |
qwen3_vl_full_sft_30_3b_ray.yaml |
Qwen3-VL-30B-A3B-Instruct | 256 |
qwen3_vl_full_sft_32b_ray.yaml |
Qwen3-VL-32B-Instruct | 256 |
qwen3_5vl_full_sft_27b_ray.yaml |
Qwen3.5-VL-27B-Instruct | 256 |
qwen3_5vl_full_sft_35b_3b_ray.yaml |
Qwen3.5-VL-35B-A3B | 256 |
qwen2_5_vl_full_sft_7b_ray.yaml |
Qwen2.5-VL-7B-Instruct | 256 |
qwen2_5_vl_full_sft_32b_ray.yaml |
Qwen2.5-VL-32B-Instruct | 256 |
qwen2_5_vl_full_sft_72b_ray.yaml |
Qwen2.5-VL-72B-Instruct | 256 |
| Hyperparameter | Value |
|---|---|
| Cutoff length | 32000 |
| Precision | bf16 |
| Learning rate | 2e-5 (cosine, warmup_ratio=0.1) |
| Epochs | 8 |
| Per-device batch | 1 (with gradient_checkpointing: true) |
| DeepSpeed | ZeRO-3 (examples/deepspeed/ds_z3_config.json) |
| Frozen modules | none (freeze_vision_tower: false, freeze_multi_modal_projector: false) |
Checkpoints land in saves/<model>/full/sft_data_v1/ (override via output_dir / ray_storage_path in the YAML).
Full details, dataset format, and cluster notes:
code/SFT/README.md.
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.
cd code/RL/rllm && pip install -e .
cd ../Megatron-LM && pip install -e .
cd ../mbridge && pip install -e .
pip install "sglang[all]" transformer_engine flash-attn \
ray==2.34.* hydra-core omegaconf wandb \
pillow requests python-dotenvCopy the env template:
cp RL/rllm/.env.example RL/rllm/.env # edit keys as neededThe 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:
cd RL/rllm/vision_deepresearch_async_workflow/data_prepare
# 1) Extract embedded image bytes β PNG + JSONL
DATA_ROOT=./data/Vision-DeepResearch-RL-Data \
bash convert_parquet2jsonl.sh
# 2) Register it with rLLM as "Vision-DeepResearch-QA" (90 / 10 split)
JSONL_PATH=./data/Vision-DeepResearch-RL-Data/vision-deepresearch_RL_Demo_1k.jsonl \
bash register_rl_dataset.shAll 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.
# Primary configuration in the paper: 8B dense, 8 nodes Γ 8 GPU
bash RL/rllm/vision_deepresearch_async_workflow/run/qwen3-vl-8b-multi-node.sh
# Other presets:
bash RL/rllm/vision_deepresearch_async_workflow/run/qwen3-vl-8b-single-node.sh # 1-node smoke test
bash RL/rllm/vision_deepresearch_async_workflow/run/qwen3-vl-30b-3b-multi-node.sh # 30B-A3B MoE
bash RL/rllm/vision_deepresearch_async_workflow/run/qwen3-vl-32b-multi-node.sh # 32B dense| Field | Value |
|---|---|
| Advantage estimator |
rloo (set grpo / reinforce_plus_plus to swap) |
| KL coefficient | 0.001 |
| Clip ratio (high) | 0.28 |
| Train prompt batch |
256 (group size n_resp_per_prompt=8, mini-batch 64) |
| Max prompt / response length |
4096 / 70000
|
| Megatron parallelism |
TP=4 / PP=2 / CP=8 (dense) |
| sglang rollout |
TP=4, gpu_memory_utilization=0.85
|
| Reward composition | |
| Fatal threshold |
3 consecutive tool-execution errors |
Checkpoints go to checkpoints/${project_name}/${exp_name}/; trajectories can be dumped to $TRAJ_DUMP_DIR (default ./trajectory_dumps/<exp>/).
| 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.
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.
opensearch_vl/
βββ run_infer.py # unified entrypoint (--model 8b|32b|30b-a3b|claude)
βββ run_infer.sh # env-driven wrapper around run_infer.py
βββ run_eval.sh # env-driven judge driver across all benchmarks
βββ eval_with_gpt4o.py # GPT-4o judge for BrowseComp-VL / HLE / VDR-Bench
βββ .env.example # full env-variable template
βββ opensearch_infer/
βββ config.py # env-driven settings + ModelSpec registry
βββ prompts.py # Visual Investigation Agent system prompt
βββ auth.py # HMAC helper + Claude gateway client
βββ cos_upload.py # optional COS uploader bootstrap
βββ image_io.py # image download / decode / cache utilities
βββ image_engines.py # PIL + OpenCV crop / OCR / enhance pipelines
βββ search.py # text_search / image_search / layout_parsing
βββ tools.py # JSON tool schema + parsing + dispatcher
βββ messages.py # Gemini β Claude / Qwen3-VL converters
βββ runners.py # ClaudeRunner + Qwen3VLRunner (dense + MoE)
βββ pipeline.py # per-case multi-turn agent loop
One entrypoint, four backends. Each call accepts a parquet of questions + images and writes one trajectory JSON per sample:
--model |
Backend |
|---|---|
8b |
OpenSearch-VL-8B (Qwen3-VL-8B base, dense) |
32b |
OpenSearch-VL-32B (Qwen3-VL-32B base, dense) |
30b-a3b |
OpenSearch-VL-30B-A3B (Qwen3-VL-30B-A3B base, MoE) |
claude |
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.
# Source the env template first; only the entries you need have to be filled in.
cp opensearch_vl/.env.example ~/.opensearch-vl.env
source ~/.opensearch-vl.env
# Dense Qwen3-VL-8B on a single GPU
python opensearch_vl/run_infer.py --model 8b --gpus 0 \
--data-path /path/to/benchmark.parquet \
--output-dir ./outputs/opensearch_vl_8b \
--start 0 --end 1000
# MoE Qwen3-VL-30B-A3B with 4-way model parallel (auto-applies the scatter dtype patch)
python opensearch_vl/run_infer.py --model 30b-a3b --gpus 0,1,2,3 \
--checkpoint /path/to/OpenSearch-VL-30B-A3B \
--data-path /path/to/benchmark.parquet \
--output-dir ./outputs/opensearch_vl_30b_a3b
# Claude Opus 4.5 (CLAUDE_API_HOST / _USER / _KEY required)
python opensearch_vl/run_infer.py --model claude \
--data-path /path/to/benchmark.parquet \
--output-dir ./outputs/claude_opusThe shell wrapper opensearch_vl/run_infer.sh reads the same parameters from environment variables (MODEL, GPUS, DATA_PATH, OUTPUT_DIR, LIMIT, CATEGORY, ...) for one-line invocations.
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:
python opensearch_vl/eval_with_gpt4o.py \
--traj_dir ./outputs/opensearch_vl_8b/bc_vl_level1 \
--benchmark bc_vl # one of: hle | bc_vl | vdr
--max_workers 20--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:
bash opensearch_vl/run_eval.sh --workers 20Full inference details:
opensearch_vl/README.md.
- Release OpenSearch-VL-{8B, 30B-A3B, 32B} checkpoints on the HuggingFace collection.
- Release SearchVL-SFT-36k and SearchVL-RL-8k datasets (full bundle + image assets).
- Release the data curation pipeline (Wikipedia path sampling, fuzzy entity rewriting, source-anchor visual grounding) as a standalone toolkit.
- Public demo for interactive multi-turn deep-research rollouts.
All artifacts have entered the final approval stage. Stay tuned β once the approval process is complete, we will release them ASAP.
This repository bundles and builds on several outstanding open-source projects; each sub-directory retains its upstream LICENSE:
- LLaMA-Factory β SFT trainer and CLI (
code/SFT/). - rLLM and verl β agentic RL framework (
code/RL/rllm/). - Megatron-LM and mbridge β model-parallel backend (
code/RL/Megatron-LM/,code/RL/mbridge/). - sglang β async rollout engine.
- Qwen-VL β base VLM checkpoints.
- We also thank the authors of Search-R1 and Vision-DeepResearch whose ideas inspired our multi-turn search-augmented RL formulation.
Project-specific additions are released under the root LICENSE (Apache 2.0).




