DEFAME: Dynamic Evidence-based FAct-checking with Multimodal Experts

This is the implementation of Dynamic Evidence-based FAct-checking with Multimodal Experts (DEFAME), a strong multimodal claim verification system. DEFAME decomposes the fact-checking task into a dynamic 6-stage pipeline, leveraging an MLLM to accomplish sub-tasks like planning, reasoning, and evidence summarization.

Table of Contents

• Installation
• Prepare Benchmarks
• Usage
• Tools and Integrations
• API
• Web Interface
• License
• Cite this Work

Installation

You can install DEFAME either via Docker or manually. In any case, you first need to clone the repository:

git clone https://github.com/multimodal-ai-lab/DEFAME
cd DEFAME

Option A: Docker (Easiest, Fastest)

Choose this option if you're interested in executing rather than modifying DEFAME.

If you have Docker installed, from the project root simply run

docker compose up -d
docker compose exec defame bash

This will download and execute the latest images we have built for you. It opens a shell. You can continue with Usage from here.

Option B: Manual Installation (Most Flexible)

Choose this option if you want to modify rather than just execute DEFAME.

Follow these steps:

1. Optional: Set up a virtual environment and activate it:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

2. Install all required packages:

   pip install -r requirements.txt
   python -c "import nltk; nltk.download('wordnet')"

   If you have a CUDA-enabled GPU and the CUDA toolkit installed, also run:

   pip install -r requirements_gpu.txt

Prepare Benchmarks

If you want to evaluate DEFAME on a benchmark, you need to do the following:

1. Download the needed benchmarks. We use:

   1. AVeriTeC: Supports auto-download during runtime, no manual download needed.
   2. MOCHEG
   3. VERITE
   4. ClaimReview2024+: Supports automatic download during runtime. Ensure to be logged in via huggingface-cli login and that you've got access to the dataset.

2. Order the first three benchmarks in the following directory structure:

   your_dataset_folder/
   ├── AVeriTeC/
   │   ├── train.json
   │   ├── dev.json
   │   └── ...
   ├── MOCHEG/
   │   ├── images/
   │   ├── train/
   │   └── ...
   └── VERITE/
       ├── images/
       ├── VERITE.csv
       └── ...
   

3. Include the path to your_dataset_folder in the data_base_dir variable inside config/globals.py. DEFAME will automatically locate and process the datasets when needed.

Usage

All execution scripts are located in (subfolders of) scripts/.

Hardware requirements: CPU-only is sufficient if you refrain from using a local LLM and disable the geolocator.

Output location: All generated reports, statistics, logs etc. will be saved in out/ by default. You may change this in the config/globals.py file.

Run Your Own Fact-Check

With scripts/run.py, you can fact-check any image-text claim. The script already contains an example. Execute it with

python -m scripts.run

It will run DEFAME with the default configuration (using GPT-4o). When running this command the first time, you'll be prompted to enter API keys. Just enter the ones you need. (See Tools and Integrations for which keys DEFAME requires.)

Run a Benchmark Evaluation

Benchmark evaluations can be run in two different ways. We recommend to use YAML configuration files. See config/verite for a bunch of examples. After you configured your own config, just copy the config's file path into run_config.py and run

python -m scripts.run_config

Tools and Integrations

DEFAME uses a Large Language Model (LLM) as the backbone which natively cannot retrieve evidence (reliably). Therefore, DEFAME leverages tools for evidence retrieval. A Tool can be anything that implements an I/O operation, executed via an Action. The implementations of each Tool can be found in defame/evidence_retrieval/tools.

Often, a Tool requires access to an external API, e.g., the Searcher tool needs SerperAPI to run web searches. All external API integrations (wrappers, HTTP request handling etc.) are implemented inside defame/evidence_retrieval/integrations. All API keys go into config/api_keys.yaml.

Some tools require additional setup. See the tool-specific setup guidelines below for any extra setup needed.

Integrated APIs

Here's an overview of all APIs that are integrated into DEFAME.

OpenAI API

You will need the OpenAI API if you want to use any of OpenAI's GPT models.

🤗 Hugging Face

Required for the usage of open source LLMs on 🤗 Hugging Face, like Llama and Llava.

Serper API

The Serper API serves standard Google Search as well as Google Image Search. If you don't want to use DuckDuckGo (which has restrictive rate limits, unfortunately), you will need this API.

Google Vision API

The Google Cloud Vision API is required to perform Reverse Image Search. Follow these steps, to set it up:

1. In the Google Cloud Console, create a new Project.
2. Go to the Service Account overview and add a new Service Account.
3. Open the new Service Account, go to "Keys" and generate a new JSON key file.
4. Save the downloaded key file at the path config/google_service_account_key.json.

Add a Custom Tool

To extend the fact-checker with an own Tool, follow these steps:

0. Only if needed: Implement the integration

   If your tool requires calling external resources, integrate the external resource by implementing a respective module inside defame/evidence_retrieval/integrations.

1. Implement the Tool and Action(s)

   Inside defame/evidence_retrieval/tools, create a new file and implement the tool, inheriting from the abstract Tool class. Make sure to implement all required methods and add a respective Action. Caution: Action docstrings are used 1:1 as a description of the tool to inform the LLM planning module about the action's purpose and how the action is used. See other tools and actions for examples.

2. Register Your Tool in defame/evidence_retrieval/tools/__init__.py

   Incorporate the new tool into the TOOL_REGISTRY list and its actions into the ACTION_REGISTRY set.

3. Add the tool configuration to the hyperparameters

   Don't forget to specify the tool in the DEFAME hyperparameters or, alternatively, in your configuration (the YAML file that goes into config/).

4. Optional: Register the Tool in Benchmarks

   This step is required only if you want to use your tool for evaluation on one of the benchmarks. To this end, navigate to the respective benchmark file under defame/eval/<benchmark_name>/benchmark.py. There, in the available_actions list, add your Tool.

Web Scraping

This project uses Firecrawl as the default web scraping service. If Firecrawl is not available, DEFAME falls back to a simple BeautifulSoup implementation. Firecrawl runs automatically if you used docker compose to install DEFAME.

Manual Firecrawl Setup

If you installed DEFAME manually, you also need to run Firecrawl manually by executing

docker run -d -p 3002:3002 tudamailab/firecrawl

DEFAME will automatically locate Firecrawl. If you use custom, non-standard ports or URLs, you must also update the firecrawl_url inside config/globals.py.

If you really want to set up Firecrawl manually and without Docker, follow the Firecrawl Documentation. We do not recommend that because, in our experience, that setup procedure is rather involving. Therefore, we recommend to use the Firecrawl Docker Image we provide for this project. (You may modify and re-build the Firecrawl Image via the Dockerfile stored in third_party/firecrawl.)

API

DEFAME ships with its own API backend, allowing the user to access DEFAME's functionalities through HTTP requests. Simply execute the script scripts/run_api.py to activate the server which will be accessible at http://0.0.0.0:3003. The API documentation is then available under http://0.0.0.0:3003/docs.

Don't forget to run Firecrawl if you want to use it.

Web Interface

DEFAME provides a web-based graphical user interface, supporting the input and verification of textual and visual content. As of now, our hosted web interface is not public, but you can host it yourself using this repository. (You also need to run the DEFAME API.)

License

This repository and all its contents (except for the contents inside third_party/) are licensed under the Apache 2.0 License.

Cite this Work

Please use the following BibTeX to refer to the authors:

@inproceedings{braun2025defame,
   title = {{DEFAME: Dynamic Evidence-based FAct-checking with Multimodal Experts}}, 
   author = {Tobias Braun and Mark Rothermel and Marcus Rohrbach and Anna Rohrbach},
   booktitle = {Proceedings of the 42nd International Conference on Machine Learning},
   year = {2025},
   url = {https://arxiv.org/abs/2412.10510},
}