Sarah

KO | EN

gitlite — search

#python #javascript #reactjs #api #react #css #aws #docker #deep-learning #html #go #swift

★ 32 Open GitHub ↗

No description available.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

## Sarah: Hallucination Detection for Large Vision Language Models with Semantic Information Locator and Purifier in Uncertainty Quantification Method

This repository contains the official implementation of the paper **[“Sarah: Hallucination Detection for Large Vision Language Models with Semantic Information Locator and Purifier in Uncertainty Quantification Method (IMAVIS2026)”](https://www.sciencedirect.com/science/article/pii/S0262885626000442)**.
We provide a complete pipeline from answer generation of LVLMs to semantic information localization, uncertainty-based hallucination detection, and final evaluation on multiple benchmarks.

👉 **[Click here for Sarah's demo](https://yuefang0211.github.io/publication/sarah)**

Contents:
- **Installation**: Environment setup
- **Dataset**: Dataset download and directory structure
- **Quick Start**: End-to-end pipeline using scripts (`run_{model_name}.sh` → `semantic_information_locator.sh` → `hallucination_detection_*.sh`)
- **Evaluation**: Evaluation scripts (`eval_{dataset_name}.sh`)

---

## Installation

### Requirements

- **Python** ≥ 3.8
- We recommend using **conda** or **virtualenv** to create an isolated environment.
- Supported models include GPT-4, LLaVA, Llama 3.2 Vision, mPLUG-Owl3, DeepSeek, etc. (exact usage is defined in `hal-detector/model_run/` and `hal-detector/scripts/run_*.sh`).

### Installation Steps

```bash
# 1. Clone this repository
git clone <this-repo-url>
cd Sarah

# 2. Create and activate a virtual environment (example: conda)
conda create -n sarah python=3.10 -y
conda activate sarah

# 3. Install dependencies
pip install -r requirements.txt
```

> To use specific LVLMs (e.g., LLaVA, Llama 3.2-Vision, mPLUG-Owl3), please follow their official documentation to prepare model weights and place them under `weights/` or other paths referenced by the `--model_path` argument in the scripts.

---

## Dataset

This project mainly uses the following datasets / benchmarks:

- **Bingo Benchmark** (a multimodal hallucination detection benchmark)
- **COCO Caption / VQA v2** (for image captioning and visual question answering)
- Preprocessed JSONL files stored under `playground/`

### Recommended Directory Structure (aligned with scripts)

```text
Sarah/
  playground/
    Bingo_benchmark/
      images/                     # Bingo images (if applicable)
      answers/                    # Raw LVLM answers (generated by run_{model_name}.sh)
      semantic_locate_result/     # Semantic localization results (generated by semantic_information_locator.sh)
      uncertainty_result/         # Uncertainty & hallucination detection results
      gpt4_ground_truth/          # GPT-4-based pseudo ground-truth (as described in the paper)

Coco_Caption/
      val2014/                    # COCO val2014 images
      captions/                   # Annotation / preprocessed files (if applicable)

vqa_v2/
      val2014_qa_sample1000.jsonl # Example VQA QA file
      answers/                    # Answers from different models on VQA
      semantic_locate_result/
      uncertainty_result/
```

### Dataset Download

- **Bingo Benchmark**: Please download it from the official link or from the paper’s appendix and unzip it under `playground/Bingo_benchmark/`.
link:https://github.com/gzcch/Bingo
- **COCO / VQA v2**:
  - Download COCO 2014 images and VQA v2 annotations from the official websites.
  - Extract the images into `playground/Coco_Caption/val2014/`, `playground/vqa_v2/`, etc., to match the paths used in the scripts.
link:https://cocodataset.org/#home
link:https://huggingface.co/datasets/lmms-lab/VQAv2
- Make sure the paths in the scripts (`--input-file`, `--image-folder`, `--output-file`, etc.) match your local directory structure, and modify them if necessary.

---

## Quick Start

We recommend the following end-to-end pipeline order:

1. **Generate model answers**: `hal-detector/scripts/run_{model_name}.sh`
2. **Semantic Information Localization**: `hal-detector/scripts/semantic_information_locator.sh`
3. **Uncertainty-based hallucination detection**: `hal-detector/scripts/hallucination_detection_*.sh`

### 1. Run different models to generate answers: `run_{model_name}.sh`

The relevant scripts are in `hal-detector/scripts/`:

- `run_gpt4_r1.sh`
- `run_llava_r1.sh`
- `run_llama32_vision_r1.sh`
- `run_mplug_owl3_r1.sh`
- `run_deepseek_r1.sh`

Take GPT-4 as an example (generating answers on VQA v2 / Bingo, with input/output specified in the script):

```bash
cd Sarah
bash hal-detector/scripts/run_gpt4_r1.sh
```

This script calls `hal-detector/model_run/model_run_gpt4.py` and writes results to, for example:

- `./playground/vqa_v2/answers/gpt4o_val2014_answers.jsonl`
- or `./playground/Bingo_benchmark/answers/answer-gpt4-bingo.jsonl` (depending on the script settings).

You can run other models similarly:

```bash
bash hal-detector/scripts/run_llava_r1.sh
bash hal-detector/scripts/run_llama32_vision_r1.sh
bash hal-detector/scripts/run_mplug_owl3_r1.sh
bash hal-detector/scripts/run_deepseek_r1.sh
```

### 2. Semantic Information Localization: `semantic_information_locator.sh`

This step calls `hal-detector/semantic_information_locator/stochastic_semantic_perturbation.py` to perform semantic perturbation and importance estimation on model answers.

```bash
bash hal-detector/scripts/semantic_information_locator.sh
```

Example (from the script):

- Input: `./playground/Bingo_benchmark/answers/answer-gpt4-bingo.jsonl`
- Output: `./playground/Bingo_benchmark/semantic_locate_result/under.jsonl`
- Dependency: `UD_English-EWT/en_ewt-ud-test.conllu` (UD Treebank for syntactic analysis)

Please modify `--input_file` / `--output_file` in the script as needed.

### 3. Hallucination Detection / Uncertainty Computation: `hallucination_detection_*.sh`

After semantic localization is completed, use the corresponding hallucination detection script for each dataset:

- `hallucination_detection_bingo.sh`
- `hallucination_detection_coco.sh`
- `hallucination_detection_vqav2.sh`

For example, on Bingo:

```bash
bash hal-detector/scripts/hallucination_detection_bingo.sh
```

Internally, these scripts call, for example:

- `hal-detector/uncertainty_quantification/se_hallucination_detection_gpt4.py`
- `hal-detector/uncertainty_quantification/hallucination_detection.py`

They read from:

- `uncertainty_result/gpt4-token_entropy-*.jsonl`
- `semantic_locate_result/semantic_locate_result-*.jsonl`

and write out the final reweighted uncertainty and hallucination predictions, e.g.  
  `./playground/Bingo_benchmark/uncertainty_result/gpt4-reweigh_token_entropy-under.jsonl`

---

## Evaluation

The evaluation scripts are located in `hal-detector/scripts/`, mainly:

- `eval_bingo.sh`
- `eval_coco.sh`

They compare:

- Predicted hallucination / uncertainty results (`uncertainty_result/*.jsonl`)
- GPT-4-based or human-annotated ground-truth (`gpt4_ground_truth/*.jsonl`)

### 1. Bingo Benchmark Evaluation

```bash
bash hal-detector/scripts/eval_bingo.sh
```

This script typically calls `hal-detector/experiment/eval.py` or related evaluation utilities and reports performance on the Bingo benchmark (e.g., AUC, F1, etc.; see the code or paper for details).

### 2. COCO / Other Datasets Evaluation

```bash
bash hal-detector/scripts/eval_coco.sh
```

Similarly, this evaluates performance on COCO-related data. Please make sure:

- Answers, semantic localization results, and uncertainty results under `playground/Coco_Caption/` have been generated.
- The input paths in `eval_coco.sh` match your local files.
  ## Citation

Please kindly cite our report if they are helpful for your research.

```bibtex
@article{Sarah,
  title={Sarah: Hallucination Detection for Large Vision Language Models with Semantic Information Locator and Purifier in Uncertainty Quantification Method},
  author={Fang Yue, Zhang Yang, Liu Yawen, Yu Yetian},
  url={https://github.com/YUEFANG0211/Sarah},
  year={2025}
}

Sarah

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README