rust-bert

Rust-native state-of-the-art Natural Language Processing models and pipelines. Port of Hugging Face's Transformers library, using tch-rs or onnxruntime bindings and pre-processing from rust-tokenizers. Supports multi-threaded tokenization and GPU inference. This repository exposes the model base architecture, task-specific heads (see below) and ready-to-use pipelines. Benchmarks are available at the end of this document.

Get started with tasks including question answering, named entity recognition, translation, summarization, text generation, conversational agents and more in just a few lines of code:

    let qa_model = QuestionAnsweringModel::new(Default::default ()) ?;

let question = String::from("Where does Amy live ?");
let context = String::from("Amy lives in Amsterdam");

let answers = qa_model.predict( & [QaInput { question, context }], 1, 32);

Output:

[Answer { score: 0.9976, start: 13, end: 21, answer: "Amsterdam" }]

The tasks currently supported include:

• Translation
• Summarization
• Multi-turn dialogue
• Zero-shot classification
• Sentiment Analysis
• Named Entity Recognition
• Part of Speech tagging
• Question-Answering
• Language Generation
• Masked Language Model
• Sentence Embeddings
• Keywords extraction

Getting started

This library relies on the tch crate for bindings to the C++ Libtorch API. The libtorch library is required can be downloaded either automatically or manually. The following provides a reference on how to set-up your environment to use these bindings, please refer to the tch for detailed information or support.

Furthermore, this library relies on a cache folder for downloading pre-trained models. This cache location defaults to ~/.cache/.rustbert, but can be changed by setting the RUSTBERT_CACHE environment variable. Note that the language models used by this library are in the order of the 100s of MBs to GBs.

Manual installation (recommended)

1. Download libtorch from https://pytorch.org/get-started/locally/. This package requires v2.4: if this version is no longer available on the "get started" page, the file should be accessible by modifying the target link, for example https://download.pytorch.org/libtorch/cu124/libtorch-cxx11-abi-shared-with-deps-2.4.0%2Bcu124.zip for a Linux version with CUDA12. NOTE: When using rust-bert as dependency from crates.io, please check the required LIBTORCH on the published package readme as it may differ from the version documented here (applying to the current repository version).
2. Extract the library to a location of your choice
3. Set the following environment variables

Linux:

export LIBTORCH=/path/to/libtorch
export LD_LIBRARY_PATH=${LIBTORCH}/lib:$LD_LIBRARY_PATH

Windows

$Env:LIBTORCH = "X:\path\to\libtorch"
$Env:Path += ";X:\path\to\libtorch\lib"

macOS + Homebrew

brew install pytorch jq
export LIBTORCH=$(brew --cellar pytorch)/$(brew info --json pytorch | jq -r '.[0].installed[0].version')
export LD_LIBRARY_PATH=${LIBTORCH}/lib:$LD_LIBRARY_PATH

Automatic installation

Alternatively, you can let the build script automatically download the libtorch library for you. The download-libtorch feature flag needs to be enabled. The CPU version of libtorch will be downloaded by default. To download a CUDA version, please set the environment variable TORCH_CUDA_VERSION to cu124. Note that the libtorch library is large (order of several GBs for the CUDA-enabled version) and the first build may therefore take several minutes to complete.

Verifying installation

Verify your installation (and linking with libtorch) by adding the rust-bert dependency to your Cargo.toml or by cloning the rust-bert source and running an example:

git clone git@github.com:guillaume-be/rust-bert.git
cd rust-bert
cargo run --example sentence_embeddings

ONNX Support (Optional)

ONNX support can be enabled via the optional onnx feature. This crate then leverages the ort crate with bindings to the onnxruntime C++ library. We refer the user to this page project for further installation instructions/support.

1. Enable the optional onnx feature. The rust-bert crate does not include any optional dependencies for ort, the end user should select the set of features that would be adequate for pulling the required onnxruntime C++ library.
2. The current recommended installation is to use dynamic linking by pointing to an existing library location. Use the load-dynamic cargo feature for ort.
3. set the ORT_DYLIB_PATH to point to the location of downloaded onnxruntime library (onnxruntime.dll/libonnxruntime.so/libonnxruntime.dylib depending on the operating system). These can be downloaded from the release page of the onnxruntime project

Most architectures (including encoders, decoders and encoder-decoders) are supported. the library aims at keeping compatibility with models exported using the Optimum library. A detailed guide on how to export a Transformer model to ONNX using Optimum is available at https://huggingface.co/docs/optimum/main/en/exporters/onnx/usage_guides/export_a_model The resources used to create ONNX models are similar to those based on Pytorch, replacing the pytorch by the ONNX model. Since ONNX models are less flexible than their Pytorch counterparts in the handling of optional arguments, exporting a decoder or encoder-decoder model to ONNX will usually result in multiple files. These files are expected (but not all are necessary) for use in this library as per the table below:

Note that the computational efficiency will drop when the decoder with past file is optional but not provided since the model will not used cached past keys and values for the attention mechanism, leading to a high number of redundant computations. The Optimum library offers export options to ensure such a decoder with past model file is created. The base encoder and decoder model architecture are available (and exposed for convenience) in the encoder and decoder modules, respectively.

Generation models (pure decoder or encoder/decoder architectures) are available in the models module. ost pipelines are available for ONNX model checkpoints, including sequence classification, zero-shot classification, token classification (including named entity recognition and part-of-speech tagging), question answering, text generation, summarization and translation. These models use the same configuration and tokenizer files as their Pytorch counterparts when used in a pipeline. Examples leveraging ONNX models are given in the ./examples directory

Ready-to-use pipelines

Based on Hugging Face's pipelines, ready to use end-to-end NLP pipelines are available as part of this crate. The following capabilities are currently available:

Disclaimer The contributors of this repository are not responsible for any generation from the 3rd party utilization of the pretrained systems proposed herein.

Benchmarks

For simple pipelines (sequence classification, tokens classification, question answering) the performance between Python and Rust is expected to be comparable. This is because the most expensive part of these pipeline is the language model itself, sharing a common implementation in the Torch backend. The End-to-end NLP Pipelines in Rust provides a benchmarks section covering all pipelines.

For text generation tasks (summarization, translation, conversation, free text generation), significant benefits can be expected (up to 2 to 4 times faster processing depending on the input and application). The article Accelerating text generation with Rust focuses on these text generation applications and provides more details on the performance comparison to Python.

Loading pretrained and custom model weights

The base model and task-specific heads are also available for users looking to expose their own transformer based models. Examples on how to prepare the date using a native tokenizers Rust library are available in ./examples for BERT, DistilBERT, RoBERTa, GPT, GPT2 and BART. Note that when importing models from Pytorch, the convention for parameters naming needs to be aligned with the Rust schema. Loading of the pre-trained weights will fail if any of the model parameters weights cannot be found in the weight files. If this quality check is to be skipped, an alternative method load_partial can be invoked from the variables store.

Pretrained models are available on Hugging face's model hub and can be loaded using RemoteResources defined in this library.

A conversion utility script is included in ./utils to convert Pytorch weights to a set of weights compatible with this library. This script requires Python and torch to be set-up, and can be used as follows: python ./utils/convert_model.py path/to/pytorch_model.bin where path/to/pytorch_model.bin is the location of the original Pytorch weights.

python3 -m venv .venv
source .venv/bin/activate

pip install -r requirements.txt

python utils/convert_model.py path/to/pytorch_model.bin

Citation

If you use rust-bert for your work, please cite End-to-end NLP Pipelines in Rust:

@inproceedings{becquin-2020-end,
    title = "End-to-end {NLP} Pipelines in Rust",
    author = "Becquin, Guillaume",
    booktitle = "Proceedings of Second Workshop for NLP Open Source Software (NLP-OSS)",
    year = "2020",
    publisher = "Association for Computational Linguistics",
    url = "https://www.aclweb.org/anthology/2020.nlposs-1.4",
    pages = "20--25",
}

Acknowledgements

Thank you to Hugging Face for hosting a set of weights compatible with this Rust library. The list of ready-to-use pretrained models is listed at https://huggingface.co/models?filter=rust.