The `spacy-transformers` library provides spaCy components and architectures to seamlessly integrate pre-trained transformer models from Hugging Face's `transformers` library into spaCy pipelines. It enables convenient access to state-of-the-art architectures like BERT, GPT-2, and XLNet for various NLP tasks, leveraging spaCy v3's powerful and extensible configuration system for multi-task learning. The current version is 1.4.0, and releases are generally aligned with spaCy's major version updates and `transformers` library advancements.
pip install 'spacy[transformers]'
python -m spacy download en_core_web_trfVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates loading a pre-trained, transformer-backed spaCy model (like `en_core_web_trf`) and processing text to extract entities, showcasing the integration. It also briefly touches on accessing the transformer's vector outputs, which power subsequent spaCy components.
Upgrade your spaCy installation to v3.0+ and then install `spacy-transformers` v1.x. Retrain any custom pipelines or download compatible `_trf` models for spaCy v3.
Always check the `spacy-transformers` documentation or `pyproject.toml` for the exact `spaCy` version requirements. Use `pip install 'spacy[transformers]'` to let pip resolve compatible versions. Run `python -m spacy validate` to check installed package compatibility.
To use task-specific heads, either train separate spaCy components (like `textcat` or `ner`) that consume the transformer features, or consider `spacy-huggingface-pipelines` for direct integration of task-specific Hugging Face models.
For GPU, ensure `spacy[transformers,cudaXX]` is installed with the correct PyTorch CUDA build. Reduce `batch_size` and `max_length` in your config. Consider smaller transformer models (e.g., DistilBERT). For very long documents, `spacy-transformers` handles sentence splitting internally, but excessive length can still be an issue. Use `nlp.pipe(texts, batch_size=...)` for efficient batch processing.