AnglE: angle-optimized sentence embeddings where the pooler and the prompt both depend on the backbone
Train and Infer Powerful Sentence Embeddings with AnglE | 🔥 SOTA on STS and MTEB Leaderboard
At a glance
- What is it?
- AnglE is a library and inference framework for training and running BERT and LLM sentence embeddings, built on the ACL 2024 paper of the same name, with four objectives and four published model families. Encoding is asymmetric on purpose, the pooler is cls for BERT models and last token for Llama adapters, and bidirectional LLM support is switched on by an environment variable read before the model loads.
- Who is it for?
- AnglE is a good default if you are building sentence embeddings rather than consuming them, because the framework removes the two mistakes that quietly ruin a search index: encoding both sides of a pair with the same prompt, and pooling a Llama adapter the way you pool a BERT model. Both are one-argument differences here, and both are documented explicitly.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Activity is slowing. The repository last received commits 7 months ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- SeanLee97/AnglE576 ★ · +3
| Repository | 2026-09-11 | 2026-11-15 |
|---|---|---|
| SeanLee97/AnglE | 573 | 576 |
3 Stars in the last 65 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
Encoding is asymmetric, and that is the whole retrieval contract
The first thing the inference examples teach is that a query and a document are encoded differently, and the difference is one argument. With prompts, for retrieval tasks, the query goes through encode with a prompt and the documents go through the same call without one:
from angle_emb import AnglE, Prompts
from angle_emb.utils import cosine_similarity
# Load model
angle = AnglE.from_pretrained('WhereIsAI/UAE-Large-V1', pooling_strategy='cls').cuda()
# Encode query with prompt, documents without prompt
qv = angle.encode(['what is the weather?'], to_numpy=True, prompt=Prompts.C)
doc_vecs = angle.encode([
'The weather is great!',
'it is rainy today.',
'i am going to bed'
], to_numpy=True)
# Calculate similarity
for dv in doc_vecs:
print(cosine_similarity(qv[0], dv))Prompts are templates with a text placeholder, and the available set is discoverable at runtime through a listing call rather than hard-coded in the examples. If you swap the prompt to the wrong side, nothing errors; you simply get an index that does not match its queries, which is the single most common way a retrieval system built on embeddings looks broken for no visible reason. The second example drops the prompt entirely for similarity tasks and compares every document against every other, which is the right shape when both sides of your pair are natural language utterances rather than a question and a candidate passage.
cls for BERT, last token for Llama, 512 tokens versus 4096
The model tables separate on two axes, and neither is interchangeable between families. The BERT-based models all use cls pooling with a 512 token maximum: a general English model, a code similarity model, and two medical models at base and large size. The LLM-based entries are different on both counts. They are shipped as LoRA weights over a Llama 2 backbone rather than as complete models, they pool on the last token, and their maximum context is 4096 tokens. So a model identifier tells you nothing on its own about how it pools, and the Llama adapters do not exist without the backbone they were trained against, which is why the load call takes both a backbone and a LoRA path. There is also a third family for bidirectional LLMs, referencing a separate project for the technique and supported by its own flag on the load call. The practical consequence for anyone wiring this into a service is that pooling strategy, maximum context and model kind are three separate things to get right per model, and only one of them is enforced for you: the framework is told is_llm, and it does not check the pooler you chose against the family you named.
Bidirectional support is switched on by an environment variable, not an argument
The bidirectional LLM path is the part most likely to surprise someone. Two arguments enable it on the load call, one to apply the bidirectional attention change and one to name the model class the runtime should instantiate, and the example passes a Llama causal language model class with float16 precision and last-token pooling. Before any of that, the example sets an environment variable to the value 31, labelled as the BiLLM start index. That is the knob that decides where bidirectional attention begins in the sequence, and it lives in the process environment rather than in the constructor call. A multi-tenant service that loads one backbone for some tenants and a bidirectional variant for others therefore has to set the variable per process rather than per request, which means two model variants cannot coexist in one interpreter as written. The flag name also carries a prefix that suggests it is specific to the BiLLM project rather than a general knob, so a reader has to know where it comes from. None of this is wrong, but it is the one part of the loading path where the configuration lives somewhere you would not look for it.
Four objectives, two papers and one loss with two names
The training side offers four objectives, and the naming around one of them is worth unpacking. The signature loss is the one from the paper this library accompanies, accepted at ACL 2024. Alongside it sit a plain contrastive loss, CoSENT, and an Espresso loss from ICLR 2025, which the feature list immediately parenthesises with an alternative name, 2DMSE, and points at a separate document for detail. There is a second readme at the root with that alternative name in its title as well as the canonical one, so the same objective is discoverable under either spelling. That is helpful for people arriving from the paper and mildly confusing for people arriving from the library. The backbones are equally broad in a specific way: the list is not a fixed set of supported models but a shape, BERT-style encoders including RoBERTa and ModernBERT, decoder-only models including LLaMA, Mistral and Qwen, and bidirectional variants of the same decoder family plus OpenELMo. Training runs on a single GPU or several, and a console entry point named angle-trainer is installed alongside the library.
Three exact pins on the machine learning stack, and floors on everything else
The dependency list explains a lot about the support model. Three packages are pinned with exact equality: the transformer library at one specific version, the parameter-efficient fine-tuning library at another, and the bits and bytes backend at a third. Everything else takes a lower bound, including scikit-learn, scipy, datasets, einops, boltons and prettytable, and Python 3.10 or newer is the floor. Exact pins on the model and fine-tuning libraries are defensible: those are the components where a version change alters training behaviour or adapter loading, and where a silent upgrade would change your embeddings. What the pattern tells you operationally is that upgrades here are deliberate events rather than routine maintenance, which matters for a library whose whole job is producing vectors you are about to index and keep. The manifest classifies the package as production stable and as intended for developers, which is a stronger claim than the one release cadence supports. Two extra dependency groups exist for development tooling and for experiment tracking, and neither is installed by default.
The package is angle_emb, the install flag is angle-emb, and the licences disagree
Three small inconsistencies live in the same manifest and all three will bite someone. The distribution is named angle_emb with an underscore, while the documented install command uses the hyphenated form, which pip and uv normalise to the same thing but which will confuse anyone reading a requirements file or a Dockerfile. The project classifiers declare the licence as an OSI approved BSD licence, the repository metadata reports MIT, and the manifest has no licence field at all, so which terms apply depends on whether you ask the repository or the classifier. And the supported Python versions in the classifiers stop at 3.12 while the requirement itself is 3.10 or newer, so an environment on a newer interpreter is allowed by the manifest and undocumented by the metadata. None of these is serious on its own. Together they are the signature of a project whose readme, manifest and repository have drifted at slightly different rates, which is a reason to read the version you install rather than the readme you found.
Two leaderboard numbers, four hundredths apart, from 2023 and 2024
The achievements section is a dated log rather than a benchmark, and reading it as the latter will mislead you. In December 2023 the project's own universal embedding model reached a top position on the MTEB leaderboard with an average of 64.64, and in March 2024 a third-party embedding from Mixedbread reached one with an average of 64.68, with both entries credited to training with AnglE. Neither number is a current leaderboard position; they are points on a curve that has moved considerably since. The gap between them is 0.04 points, which is a reminder that leaderboard averages at that level are decided by differences far smaller than the change between checkpoints. What the log does establish is provenance: the models with the best reported scores were trained with this objective, including one produced by a commercial sponsor whose badge sits at the top of the readme. The underlying papers have their own record, with the AnglE paper accepted at ACL 2024 and a related bidirectional embedding paper accepted at NAACL 2024.
Examples are named after the benchmarks they reproduce
The examples directory is organised the way the literature is, which is the clearest available guide to what the library can be used for. Four notebooks are named for the benchmarks they reproduce, covering antonym and synonym tests, Chinese question matching and paraphrase identification, and a cross-lingual paraphrase set. Alongside them sit four directories with broader purposes: one for training, one for natural language inference data, one for the universal embedding models, and one for fully sharded data parallel setups. A single script handles multi-GPU inference. That spread tells you the library was built to reproduce published numbers rather than to be a convenient client, and the presence of the data-parallel example directory is a hint that training setup was part of the original workflow rather than an afterthought. There is also a migration guide at the root and a separate readme for the universal embedding models, so the repository treats itself as having at least two eras of API. The three published releases are spread across late 2024, early 2025 and late 2025, while the last commit is from March 2026.
Editorial conclusion
AnglE is a good default if you are building sentence embeddings rather than consuming them, because the framework removes the two mistakes that quietly ruin a search index: encoding both sides of a pair with the same prompt, and pooling a Llama adapter the way you pool a BERT model. Both are one-argument differences here, and both are documented explicitly. What it is not is a general inference framework with a stable interface: three dependencies on the machine learning stack are pinned with exact equality, the model table spans three families with three different configurations, the bidirectional path depends on an environment variable rather than a constructor argument, and the manifest disagrees with the repository about the licence while naming the package one way and the install flag another. The published quality claims also deserve care, since the two leaderboard numbers are from December 2023 and March 2024 and differ by four hundredths of a point. Before you build on it, confirm three things: which pooling strategy and prompt each of your models actually needs, whether the exact-pinned transformers and peft versions work with your GPU, and what you intend to run in production, since the newest release tag is nearly half a year older than the last commit.
Frequently asked questions
How do I install AnglE?
With uv, using uv pip install -U angle-emb, or with pip, using pip install -U angle-emb. The distribution is named angle_emb with an underscore and normalises to the same thing. Python 3.10 or newer is required, and the manifest pins the transformer, fine-tuning and bitsandbytes packages to exact versions.
Do I use a prompt when encoding documents for search with AnglE?
No. For retrieval you encode the query with a prompt and the documents without one. Prompts are templates with a text placeholder, and the available set is discoverable at runtime through Prompts.list_prompts(). Getting this backwards produces an index that does not match its queries without raising an error.
What is the difference between cls and last token pooling in AnglE?
It depends on the backbone family. The BERT-based models in the project pool on cls with a 512 token maximum, while the LLM-based models are LoRA adapters over a Llama 2 backbone that pool on the last token with a 4096 token maximum. The pooler is passed at load time and is not checked against the model kind.
Why does AnglE need is_llm set to true?
Because the LLM adapters are not standalone models; they are LoRA weights that need their backbone named as well. The load call takes the backbone and the LoRA path, and the is_llm flag tells the runtime how to treat it. Bidirectional variants add a separate flag plus the model class to instantiate, and read a start index for the bidirectional attention from a process environment variable.
Which training losses does AnglE provide?
Four: the AnglE loss from the ACL 2024 paper of the same name, a contrastive loss, CoSENT, and the Espresso loss from ICLR 2025, which is also called 2DMSE and has its own document at the repository root. Training runs on one GPU or several, and a fully sharded data parallel example is included.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/seanlee97-angle)Star history chart for your README
[](https://hysenlabs.com/projects/seanlee97-angle)Was this useful?