Mammoth Multilingual Translation Model

A multilingual transformer translation model (6 encoder + 3 decoder layers, dimension 768) covering 37 source and 37 target languages, trained on 170 translation directions (tasks).

The model is stored as separate components — one per language embedding, per encoder/decoder layer stack, and so on — each stored once even when many directions share it. When you choose a direction, only the components it uses are downloaded and assembled into a model.

Setup

No Mammoth installation is needed. Create an environment and fetch the inference script from this repo:

python -m venv .venv && source .venv/bin/activate
pip install transformers torch huggingface_hub safetensors
hf download Helsinki-NLP/mammoth-eng_spa-g3a3-l3-h4d768 inference.py --local-dir .

inference.py downloads the model files it needs on first use (into the Hugging Face cache).

Translate

# A trained direction
python inference.py --model-dir Helsinki-NLP/mammoth-eng_spa-g3a3-l3-h4d768 --task eng-bos --sentences "Helsinki is the capital of Finland."

# A direction that was never trained (zero-shot): combine a source and a target language
python inference.py --model-dir Helsinki-NLP/mammoth-eng_spa-g3a3-l3-h4d768 --src bos --tgt bul --input-file input.bos.txt

Options

Choosing a Direction

Trained directions — --task <source>-<target>. These 170 directions were trained directly and are listed in the table below.

Zero-shot directions — --src <source> --tgt <target>. Any source language can be combined with any target language, including pairs that were never trained together (1162 more directions). The source language brings its encoder and the target language its decoder. Quality of untrained pairs varies; check the output before relying on it.

Choosing layer stacks yourself — --encoder ... --decoder ... takes one id per layer stack (see the Encoder / Decoder columns below). Only stack combinations that some trained direction used can be loaded.

Languages

Encoder / Decoder show the layer-stack ids used for the language (one id per stack); — means the language is not available on that side.

Using the Model from Python

inference.py is also a module (it must be in the current directory or on sys.path):

from inference import load_model, translate

src_tok, tgt_tok, model = load_model("Helsinki-NLP/mammoth-eng_spa-g3a3-l3-h4d768", task="eng-bos")
print(translate(src_tok, tgt_tok, model, ["Helsinki is the capital of Finland."]))

load_model also takes src= / tgt= (and encoder= / decoder=), like the command line. translate() takes num_beams and max_new_tokens. model is a standard transformers model, so model.generate() also works if you need more control.

Offline Use

To keep a copy in a folder of your choice instead of the Hugging Face cache, use the shipped model_downloader.py:

hf download Helsinki-NLP/mammoth-eng_spa-g3a3-l3-h4d768 model_downloader.py --local-dir .

# Everything
python model_downloader.py --repo-id Helsinki-NLP/mammoth-eng_spa-g3a3-l3-h4d768 --local-dir ./model

# Only the files needed for one task
python model_downloader.py --repo-id Helsinki-NLP/mammoth-eng_spa-g3a3-l3-h4d768 --local-dir ./eng-bos --task eng-bos

The downloaded folder contains inference.py; pass the folder as --model-dir:

python ./eng-bos/inference.py --model-dir ./eng-bos --task eng-bos --input-file in.txt

Notes

• Mammoth uses a separate vocabulary per language, so each direction has a source tokenizer (for the input) and a target tokenizer (for the output). inference.py and load_model() pick the right pair for you.
• The model code is shipped in this repo (modeling_mammoth.py, native_transformer.py, ...), which is why loading uses trust_remote_code=True.
• Trained with MAMMOTH.