spaCy v2.2 features improved statistical models, new pretrained models for Norwegian and Lithuanian, better Dutch NER, as well as a new mechanism for storing language data that makes the installation about 5-10× smaller on disk. We’ve also added a new class to efficiently serialize annotations, an improved and 10× faster phrase matching engine, built-in scoring and CLI training for text classification, a new command to analyze and debug training data, data augmentation during training and more. For the full changelog, see the release notes on GitHub.

For more details and a behind-the-scenes look at the new release, see our blog post.

Better pretrained models and more languages

The new version also features new and re-trained models for all languages and resolves a number of data bugs. The Dutch model has been retrained with a new and custom-labelled NER corpus using the same extended label scheme as the English models. It should now produce significantly better NER results overall. We’ve also added new core models for Norwegian (MIT) and Lithuanian (CC BY-SA).

Text classification scores and CLI training

When training your models using the spacy train command, you can now also include text categories in the JSON-formatted training data. The Scorer and nlp.evaluate now report the text classification scores, calculated as the F-score on positive label for binary exclusive tasks, the macro-averaged F-score for 3+ exclusive labels or the macro-averaged AUC ROC score for multilabel classification.

New DocBin class to efficiently serialize Doc collections

If you’re working with lots of data, you’ll probably need to pass analyses between machines, either to use something like Dask or Spark, or even just to save out work to disk. Often it’s sufficient to use the Doc.to_array functionality for this, and just serialize the numpy arrays – but other times you want a more general way to save and restore Doc objects.

The new DocBin class makes it easy to serialize and deserialize a collection of Doc objects together, and is much more efficient than calling Doc.to_bytes on each individual Doc object. You can also control what data gets saved, and you can merge pallets together for easy map/reduce-style processing.

Serializable lookup tables and smaller installation

The new Lookups API lets you add large dictionaries and lookup tables to the Vocab and access them from the tokenizer or custom components and extension attributes. Internally, the tables use Bloom filters for efficient lookup checks. They’re also fully serializable out-of-the-box. All large data resources like lemmatization tables have been moved to a separate package, spacy-lookups-data that can be installed alongside the core library. This allowed us to make the spaCy installation 5-10× smaller on disk (depending on your platform). Pretrained models now include their data files, so you only need to install the lookups if you want to build blank models or use lemmatization with languages that don’t yet ship with pretrained models.

CLI command to debug and validate training data

The new debug-data command lets you analyze and validate your training and development data, get useful stats, and find problems like invalid entity annotations, cyclic dependencies, low data labels and more. If you’re training a model with spacy train and the results seem surprising or confusing, debug-data may help you track down the problems and improve your training data.

Backwards incompatibilities

• The lemmatization tables have been moved to their own package, spacy-lookups-data, which is not installed by default. If you’re using pretrained models, nothing changes, because the tables are now included in the model packages. If you want to use the lemmatizer for other languages that don’t yet have pretrained models (e.g. Turkish or Croatian) or start off with a blank model that contains lookup data (e.g. spacy.blank("en")), you’ll need to explicitly install spaCy plus data via pip install spacy[lookups].
• Lemmatization tables (rules, exceptions, index and lookups) are now part of the Vocab and serialized with it. This means that serialized objects (nlp, pipeline components, vocab) will now include additional data, and models written to disk will include additional files.
• The Lemmatizer class is now initialized with an instance of Lookups containing the rules and tables, instead of dicts as separate arguments. This makes it easier to share data tables and modify them at runtime. This is mostly internals, but if you’ve been implementing a custom Lemmatizer, you’ll need to update your code.
• The Dutch model has been trained on a new NER corpus (custom labelled UD instead of WikiNER), so their predictions may be very different compared to the previous version. The results should be significantly better and more generalizable, though.
• The spacy download command does not set the --no-deps pip argument anymore by default, meaning that model package dependencies (if available) will now be also downloaded and installed. If spaCy (which is also a model dependency) is not installed in the current environment, e.g. if a user has built from source, --no-deps is added back automatically to prevent spaCy from being downloaded and installed again from pip.
• The built-in biluo_tags_from_offsets converter is now stricter and will raise an error if entities are overlapping (instead of silently skipping them). If your data contains invalid entity annotations, make sure to clean it and resolve conflicts. You can now also use the new debug-data command to find problems in your data.
• Pipeline components can now overwrite IOB tags of tokens that are not yet part of an entity. Once a token has an ent_iob value set, it won’t be reset to an “unset” state and will always have at least O assigned. list(doc.ents) now actually keeps the annotations on the token level consistent, instead of resetting O to an empty string.
• The default punctuation in the Sentencizer has been extended and now includes more characters common in various languages. This also means that the results it produces may change, depending on your text. If you want the previous behavior with limited characters, set punct_chars=[".", "!", "?"] on initialization.
• The PhraseMatcher algorithm was rewritten from scratch and it’s now 10× faster. The rewrite also resolved a few subtle bugs with very large terminology lists. So if you were matching large lists, you may see slightly different results – however, the results should now be fully correct. See this PR for more details.
• The Serbian language class (introduced in v2.1.8) incorrectly used the language code rs instead of sr. This has now been fixed, so Serbian is now available via spacy.lang.sr.
• The "sources" in the meta.json have changed from a list of strings to a list of dicts. This is mostly internals, but if your code used nlp.meta["sources"], you might have to update it.

Migrating from spaCy 2.1

Lemmatization data and lookup tables

If you application needs lemmatization for languages with only tokenizers, you now need to install that data explicitly via pip install spacy[lookups] or pip install spacy-lookups-data. No additional setup is required – the package just needs to be installed in the same environment as spaCy.

The same applies to blank models that you want to update and train – for instance, you might use spacy.blank to create a blank English model and then train your own part-of-speech tagger on top. If you don’t explicitly install the lookups data, that nlp object won’t have any lemmatization rules available. spaCy will now show you a warning when you train a new part-of-speech tagger and the vocab has no lookups available.

Lemmatizer initialization

This is mainly internals and should hopefully not affect your code. But if you’ve been creating custom Lemmatizers, you’ll need to update how they’re initialized and pass in an instance of Lookups with the (optional) tables lemma_index, lemma_exc, lemma_rules and lemma_lookup.

Converting entity offsets to BILUO tags

If you’ve been using the biluo_tags_from_offsets helper to convert character offsets into token-based BILUO tags, you may now see an error if the offsets contain overlapping tokens and make it impossible to create a valid BILUO sequence. This is helpful, because it lets you spot potential problems in your data that can lead to inconsistent results later on. But it also means that you need to adjust and clean up the offsets before converting them:

Serbian language data

If you’ve been working with Serbian (introduced in v2.1.8), you’ll need to change the language code from rs to the correct sr: