Skip to content

Commit e97c015

Browse files
do-medo-me
authored
docs: Updated readme with badges, better examples, and citation info (#12)
1 parent 480ec98 commit e97c015

File tree

1 file changed

+134
-42
lines changed

1 file changed

+134
-42
lines changed

‎README.md‎

Lines changed: 134 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -1,92 +1,168 @@
1-
21
<div align="center">
32
<picture>
4-
<img width="35%" alt="Model2Vec logo" src="assets/images/model2vec_rs_logo.png">
3+
<!-- Assuming this is the correct path for the Rust version's logo -->
4+
<img width="35%" alt="Model2Vec Rust logo" src="assets/images/model2vec_rs_logo.png">
55
</picture>
66
</div>
77

88
<div align="center">
9+
<h2>Fast State-of-the-Art Static Embeddings in Rust</h2>
10+
</div>
11+
12+
<div align="center">
13+
<!-- Badges: crates.io version, downloads, license, docs.rs -->
14+
<a href="https://crates.io/crates/model2vec-rs"><img src="https://img.shields.io/crates/v/model2vec-rs.svg" alt="Crates.io"></a>
15+
<a href="https://crates.io/crates/model2vec-rs"><img src="https://img.shields.io/crates/d/model2vec-rs.svg" alt="Downloads"></a>
16+
<a href="https://docs.rs/model2vec-rs"><img src="https://docs.rs/model2vec-rs/badge.svg" alt="Docs.rs"></a>
17+
<a href="https://discord.gg/4BDPR5nmtK">
18+
<img src="https://img.shields.io/badge/Join-Discord-5865F2?logo=discord&logoColor=white" alt="Join Discord">
19+
</a>
20+
<a href="https://github.com/MinishLab/model2vec-rs/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License: MIT"></a>
21+
<!-- Optional: Add a build status badge if CI is set up -->
22+
<!-- <a href="YOUR_CI_LINK_HERE"><img src="YOUR_CI_BADGE_LINK_HERE" alt="Build Status"></a> -->
23+
</div>
924

10-
[Quickstart](#quickstart) •
11-
[Models](#models) •
12-
[Performance](#performance)
25+
<div align="center">
26+
<p>
27+
<a href="#quickstart"><strong>Quickstart</strong></a> •
28+
<a href="#features"><strong>Features</strong></a> •
29+
<a href="#models"><strong>Models</strong></a> •
30+
<a href="#performance"><strong>Performance</strong></a> •
31+
<a href="#relation-to-python-model2vec"><strong>Relation to Python Model2Vec</strong></a>
32+
</p>
1333
</div>
1434

15-
This crate provides a lightweight Rust implementation for loading and inference of [Model2Vec](https://github.com/MinishLab/model2vec) static embedding models. For distillation and training, the [Python Model2Vec package](https://github.com/MinishLab/model2vec) can be used.
35+
`model2vec-rs` is a Rust crate providing an efficient implementation for inference with [Model2Vec](https://github.com/MinishLab/model2vec) static embedding models. Model2Vec is a technique for creating compact and fast static embedding models from sentence transformers, achieving significant reductions in model size and inference speed. This Rust crate is optimized for performance, making it suitable for applications requiring fast embedding generation.
36+
37+
## Quickstart
38+
39+
You can utilize `model2vec-rs` in two ways:
1640

41+
1. **As a library** in your Rust projects
42+
2. **As a standalone Command-Line Interface (CLI) tool** for quick terminal-based inferencing
1743

44+
---
1845

19-
## Quick Start
46+
### 1. Using `model2vec-rs` as a Library
2047

21-
Add the crate:
48+
Integrate `model2vec-rs` into your Rust application to generate embeddings within your code.
49+
50+
**a. Add `model2vec-rs` as a dependency:**
2251

2352
```bash
2453
cargo add model2vec-rs
2554
```
2655

27-
Make embeddings:
28-
56+
**b. Load a model and generate embeddings:**
2957
```rust
3058
use anyhow::Result;
3159
use model2vec_rs::model::StaticModel;
3260

3361
fn main() -> Result<()> {
34-
// Load a model from the Hugging Face Hub or a local path
35-
// args = (repo_or_path, token, normalize, subfolder)
36-
let model = StaticModel::from_pretrained("minishlab/potion-base-8M", None, None, None)?;
62+
// Load a model from the Hugging Face Hub or a local path.
63+
// Arguments: (repo_or_path, hf_token, normalize_embeddings, subfolder_in_repo)
64+
let model = StaticModel::from_pretrained(
65+
"minishlab/potion-base-8M", // Model ID from Hugging Face or local path to model directory
66+
None, // Optional: Hugging Face API token for private models
67+
None, // Optional: bool to override model's default normalization. `None` uses model's config.
68+
None // Optional: subfolder if model files are not at the root of the repo/path
69+
)?;
3770

38-
// Prepare a list of sentences
3971
let sentences = vec![
4072
"Hello world".to_string(),
4173
"Rust is awesome".to_string(),
4274
];
4375

44-
// Create embeddings
76+
// Generate embeddings using default parameters
77+
// (Default max_length: Some(512), Default batch_size: 1024)
4578
let embeddings = model.encode(&sentences);
46-
println!("Embeddings: {:?}", embeddings);
79+
// `embeddings` is a Vec<Vec<f32>>
80+
println!("Generated {} embeddings.", embeddings.len());
81+
82+
// To generate embeddings with custom arguments:
83+
let custom_embeddings = model.encode_with_args(
84+
&sentences,
85+
Some(256), // Optional: custom max token length for truncation
86+
512, // Custom batch size for processing
87+
);
88+
println!("Generated {} custom embeddings.", custom_embeddings.len());
4789

4890
Ok(())
4991
}
5092
```
5193

94+
---
5295

53-
Make embeddings with the CLI:
96+
### 2. Using the `model2vec-rs` CLI
5497

55-
```rust
56-
# Single sentence
57-
cargo run -- encode "Hello world" minishlab/potion-base-8M
58-
59-
# Multiple lines from a file
60-
echo -e "Hello world\nRust is awesome" > input.txt
61-
cargo run -- encode input.txt minishlab/potion-base-8M --output embeds.json
98+
**a. Install the CLI tool:**
99+
This command compiles the crate in release mode (for speed) and installs the `model2vec-rs` executable to Cargo's binary directory `~/.cargo/bin/`.
100+
```bash
101+
cargo install model2vec-rs
62102
```
103+
Ensure `~/.cargo/bin/` is in your system's `PATH` to run `model2vec-rs` from any directory.
63104

105+
**b. Generate embeddings via CLI:**
106+
The compiled binary installed via `cargo install` is significantly faster (often >10x) than running via `cargo run -- ...` without release mode.
64107

65-
Make embeddings with custom encode args:
108+
* **Encode a single sentence:**
109+
```shell
110+
model2vec-rs encode "Hello world" "minishlab/potion-base-8M"
111+
```
112+
Embeddings will be printed to the console in JSON format. This command should take less than 0.1s to execute.
66113

67-
```rust
68-
let embeddings = model.encode_with_args(
69-
&sentences, // input texts
70-
Some(512), // max length
71-
1024, // batch size
72-
);
114+
* **Encode multiple lines from a file and save to an output file:**
115+
```shell
116+
echo -e "This is the first sentence.\nThis is another sentence." > my_texts.txt
117+
model2vec-rs encode my_texts.txt "minishlab/potion-base-8M" --output embeddings_output.json
118+
```
119+
120+
**c. (Alternative for Developers) Running CLI from a cloned repository:**
121+
122+
```shell
123+
# Clone and navigate to the repository directory
124+
git clone https://github.com/MinishLab/model2vec-rs.git
125+
cd model2vec-rs
126+
127+
# Build and run with release optimizations (recommended for better performance):
128+
cargo run --release -- encode "Hello world" "minishlab/potion-base-8M"
129+
130+
# For quicker development cycles instead (slower execution):
131+
cargo run -- encode "Hello world" "minishlab/potion-base-8M"
132+
133+
# Alternatively, build the executable first:
134+
cargo build --release
135+
136+
# Then run with:
137+
./target/release/model2vec-rs encode "Hello world" "minishlab/potion-base-8M"
73138
```
74139

75-
## Models
140+
## Features
76141

77-
We provide a number of models that can be used out of the box. These models are available on the [HuggingFace hub](https://huggingface.co/collections/minishlab/model2vec-base-models-66fd9dd9b7c3b3c0f25ca90e) and can be loaded using the `from_pretrained` method. The models are listed below.
142+
* **Fast Inference:** Optimized Rust implementation for fast embedding generation.
143+
* **Hugging Face Hub Integration:** Load pre-trained Model2Vec models directly from the Hugging Face Hub using model IDs, or use models from local paths.
144+
* **Model Formats:** Supports models with f32, f16, and i8 weight types stored in `safetensors` files.
145+
* **Batch Processing:** Encodes multiple sentences in batches.
146+
* **Configurable Encoding:** Allows customization of maximum sequence length and batch size during encoding.
78147

148+
## What is Model2Vec?
79149

150+
Model2Vec is a technique to distill large sentence transformer models into highly efficient static embedding models. This process significantly reduces model size and computational requirements for inference. For a detailed understanding of how Model2Vec works, including the distillation process and model training, please refer to the [main Model2Vec Python repository](https://github.com/MinishLab/model2vec) and its [documentation](https://github.com/MinishLab/model2vec/blob/main/docs/what_is_model2vec.md).
80151

81-
| Model | Language | Sentence Transformer | Params | Task |
82-
|-----------------------------------------------------------------------|------------|-----------------------------------------------------------------|---------|-----------|
83-
| [potion-base-32M](https://huggingface.co/minishlab/potion-base-32M) | English | [bge-base-en-v1.5](https://huggingface.co/BAAI/bge-base-en-v1.5) | 32.3M | General |
84-
| [potion-base-8M](https://huggingface.co/minishlab/potion-base-8M) | English | [bge-base-en-v1.5](https://huggingface.co/BAAI/bge-base-en-v1.5) | 7.5M | General |
85-
| [potion-base-4M](https://huggingface.co/minishlab/potion-base-4M) | English | [bge-base-en-v1.5](https://huggingface.co/BAAI/bge-base-en-v1.5) | 3.7M | General |
86-
| [potion-base-2M](https://huggingface.co/minishlab/potion-base-2M) | English | [bge-base-en-v1.5](https://huggingface.co/BAAI/bge-base-en-v1.5) | 1.8M | General |
87-
| [potion-retrieval-32M](https://huggingface.co/minishlab/potion-retrieval-32M) | English | [bge-base-en-v1.5](https://huggingface.co/BAAI/bge-base-en-v1.5) | 32.3M | Retrieval |
88-
| [M2V_multilingual_output](https://huggingface.co/minishlab/M2V_multilingual_output) | Multilingual | [LaBSE](https://huggingface.co/sentence-transformers/LaBSE) | 471M | General |
152+
This `model2vec-rs` crate provides a Rust-based engine specifically for **inference** using these Model2Vec models.
89153

154+
## Models
155+
156+
A variety of pre-trained Model2Vec models are available on the [HuggingFace Hub (MinishLab collection)](https://huggingface.co/collections/minishlab/model2vec-base-models-66fd9dd9b7c3b3c0f25ca90e). These can be loaded by `model2vec-rs` using their Hugging Face model ID or by providing a local path to the model files.
157+
158+
| Model | Language | Distilled From (Original Sentence Transformer) | Params | Task |
159+
|-----------------------------------------------------------------------|-------------|-----------------------------------------------------------------|---------|-----------|
160+
| [potion-base-32M](https://huggingface.co/minishlab/potion-base-32M) | English | [bge-base-en-v1.5](https://huggingface.co/BAAI/bge-base-en-v1.5) | 32.3M | General |
161+
| [potion-base-8M](https://huggingface.co/minishlab/potion-base-8M) | English | [bge-base-en-v1.5](https://huggingface.co/BAAI/bge-base-en-v1.5) | 7.5M | General |
162+
| [potion-base-4M](https://huggingface.co/minishlab/potion-base-4M) | English | [bge-base-en-v1.5](https://huggingface.co/BAAI/bge-base-en-v1.5) | 3.7M | General |
163+
| [potion-base-2M](https://huggingface.co/minishlab/potion-base-2M) | English | [bge-base-en-v1.5](https://huggingface.co/BAAI/bge-base-en-v1.5) | 1.8M | General |
164+
| [potion-retrieval-32M](https://huggingface.co/minishlab/potion-retrieval-32M) | English | [bge-base-en-v1.5](https://huggingface.co/BAAI/bge-base-en-v1.5) | 32.3M | Retrieval |
165+
| [M2V_multilingual_output](https://huggingface.co/minishlab/M2V_multilingual_output) | Multilingual| [LaBSE](https://huggingface.co/sentence-transformers/LaBSE) | 471M | General |
90166

91167
## Performance
92168

@@ -99,7 +175,23 @@ We compared the performance of the Rust implementation with the Python version o
99175

100176
The Rust version is roughly **1.7×** faster than the Python version.
101177

178+
## Relation to Python `model2vec`
179+
180+
* **`model2vec-rs` (This Crate):** High-performance Rust engine for 1.7x faster **Model2Vec inference**.
181+
* **[`model2vec`](https://github.com/MinishLab/model2vec) (Python-based):** Handles model **distillation, training, fine-tuning**, and slower Python-based inference.
102182

103183
## License
104184

105-
MIT
185+
MIT
186+
187+
## Citing Model2Vec
188+
189+
If you use the Model2Vec methodology or models in your research or work, please cite the original Model2Vec project:
190+
```bibtex
191+
@article{minishlab2024model2vec,
192+
author = {Tulkens, Stephan and {van Dongen}, Thomas},
193+
title = {Model2Vec: Fast State-of-the-Art Static Embeddings},
194+
year = {2024},
195+
url = {https://github.com/MinishLab/model2vec}
196+
}
197+
```

0 commit comments

Comments
 (0)