facebookresearch/vizseq

VizSeq – Visual Analysis Toolkit for Text‑Generation

What it is – VizSeq is a Python library that helps researchers and engineers inspect the output of any text‑generation system (machine translation, summarisation, image captioning, speech translation, video description, etc.). It takes the source data, reference texts and model predictions, computes a range of automatic metrics, and presents the results in interactive visualisations that can be explored from a Jupyter notebook or a lightweight web app.

Why it matters – Modern generation models produce large amounts of output, and raw metric scores (BLEU, ROUGE, BERTScore…) often hide systematic errors. VizSeq lets you browse examples, compare multiple systems side‑by‑side, and drill down into per‑sentence scores, error types, and embedding‑based similarity, all with multi‑process speedups. This speeds up debugging, model selection and paper writing.

Key features

• Multi‑modal support – works with plain text, image‑captioning, speech/audio files, and video description data.
• Rich metric suite – classic n‑gram metrics (BLEU, METEOR, TER, ROUGE, CIDEr, …) plus embedding‑based scores (LASER, BERTScore). All metrics are parallelised for speed.
• Interactive visualisation – notebooks show sortable tables, scatter plots and example‑by‑example views; the bundled web server offers the same UI in a browser.
• Fairseq integration – plug directly into Facebook’s Fairseq training pipeline to visualise results without extra conversion code.
• Extensible – optional extras add audio handling, Google‑Translate lookup, or the heavy‑weight embedding scorers that pull in PyTorch.

Typical workflow

1. Install the package (pip install vizseq) and any optional extras you need.
2. Prepare a folder containing:
   • source files (text, image paths, audio files, …)
   • reference texts
   • model predictions
3. Run the provided scorers (e.g., vizseq-score) to generate a JSON/TSV report.
4. Launch the visualiser:
   • In a notebook: import vizseq; vizseq.show(report_path)
   • Or start the web server: vizseq-server --port 9001 --data-root ./examples/data and open the URL in a browser.
5. Use the UI to filter by score, sort by length, compare multiple systems, and export figures for papers.

Installation

# Core package (Python 3.11+)
pip install vizseq

# Optional extras (choose as needed)
pip install vizseq[embeddings]   # LASER, BERTScore (adds torch)
pip install vizseq[audio]        # .wav/.flac/.sph support
pip install vizseq[translate]    # Google Translate API
pip install vizseq[all]          # everything

You can also install from source with pip install -e . after cloning the repo.

Documentation & examples – The project hosts a full docs site (https://facebookresearch.github.io/vizseq) with step‑by‑step notebooks for basic usage, multimodal MT, multilingual MT, and speech translation. A quick‑start web‑app demo is also provided.

License – MIT (permissive, commercial‑friendly).

Citation – If you use VizSeq in a publication, cite the EMNLP‑2019 system demo:

@inproceedings{wang2019vizseq,
  title = {VizSeq: A Visual Analysis Toolkit for Text Generation Tasks},
  author = {Changhan Wang and Anirudh Jain and Danlu Chen and Jiatao Gu},
  booktitle = {Proceedings of EMNLP 2019: System Demonstrations},
  year = {2019}
}

Contact – Changhan Wang (changhan@fb.com) and Jiatao Gu (jgu@fb.com).