{"id":7735,"library":"spacy-transformers","title":"spaCy Transformers: Integrate Hugging Face Models","description":"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.","status":"active","version":"1.4.0","language":"python","source_language":"en","source_url":"https://github.com/explosion/spacy-transformers","tags":["spaCy","transformers","NLP","BERT","embedding","machine learning","Hugging Face"],"install":[{"cmd":"pip install 'spacy[transformers]'\npython -m spacy download en_core_web_trf","lang":"bash","label":"CPU Installation and Model Download"},{"cmd":"pip install 'spacy[transformers,cudaXX]' # Replace XX with your CUDA version (e.g., cuda113)\npython -m spacy download en_core_web_trf","lang":"bash","label":"GPU Installation (PyTorch with CUDA) and Model Download"}],"dependencies":[{"reason":"Core NLP library; spacy-transformers requires spaCy v3.0+ and has specific minor version compatibility.","package":"spacy","optional":false},{"reason":"The underlying library providing access to pre-trained transformer models from Hugging Face.","package":"transformers","optional":false},{"reason":"Backend deep learning framework for transformer models. PyTorch is typically installed automatically but specific CUDA versions may require manual installation.","package":"torch","optional":false},{"reason":"Provides GPU support for spaCy's Thinc (and thus spacy-transformers) when using CUDA, installed via spaCy's `[cudaXX]` extras.","package":"cupy","optional":true}],"imports":[{"wrong":"from spacy_transformers import Transformer","symbol":"Transformer","correct":"from spacy_transformers import Transformer"}],"quickstart":{"code":"import spacy\n\n# Ensure you have downloaded a transformer-backed model, e.g., using:\n# python -m spacy download en_core_web_trf\n\nnlp = spacy.load(\"en_core_web_trf\")\ntext = \"Apple is acquiring a London-based AI startup for $200M.\"\ndoc = nlp(text)\n\nprint(f\"Text: {text}\")\nprint(f\"Entities: {[(ent.text, ent.label_) for ent in doc.ents]}\")\n\n# Accessing transformer output (e.g., pooled vector for the doc)\n# Note: Raw transformer outputs are typically stored in doc._.trf_data or doc.tensor\nif doc.has_annotation(\"SENT_START\"): # Check if sentencizer is in pipeline\n    print(f\"Document vector (first token of first sentence): {doc[0].vector[:5]}\") # First 5 elements of vector","lang":"python","description":"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."},"warnings":[{"fix":"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.","message":"`spacy-transformers` underwent a significant refactoring for spaCy v3.0+. Versions 0.6.x and earlier (for spaCy v2.x) are incompatible with v1.x and later (for spaCy v3.x). Pipelines trained with v0.x will not work with v1.x.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"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.","message":"Strict version compatibility exists between `spacy-transformers` and `spaCy`. For example, `spacy-transformers` v1.2.x requires `spaCy` v3.5.0+. Installing incompatible versions can lead to unexpected errors or warnings about pipeline incompatibility.","severity":"gotcha","affected_versions":"All versions"},{"fix":"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.","message":"The `Transformer` component in `spacy-transformers` acts as a feature extractor, providing contextual embeddings to downstream spaCy components. It does not natively expose task-specific heads (e.g., for text classification or token classification) from the Hugging Face model for direct inference or training.","severity":"gotcha","affected_versions":"All versions"},{"fix":"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.","message":"Transformer models are computationally intensive and memory-hungry. Training and inference, especially with larger models or long documents, are significantly slower on CPU and often require a GPU (with CUDA) for practical performance. Memory issues ('CUDA out of memory') are common.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'-2':48 '1.4.0':73 'access':37 'advanc':88 'align':78 'architectur':16,44 'art':43 'bert':46,92 'compon':14 'configur':62 'conveni':36 'current':70 'embed':93 'enabl':35 'extens':61 'face':5,27,97 'general':77 'gpt':47 'hug':4,26,96 'integr':3,19 'learn':68,95 'leverag':55 'librari':11,30,87 'like':45 'machin':94 'major':82 'model':6,24 'multi':66 'multi-task':65 'nlp':53,91 'pipelin':33 'power':59 'pre':21 'pre-train':20 'provid':12 'releas':75 'seamless':18 'spaci':1,9,13,32,56,80,89 'spacy-transform':8 'state':40 'state-of-the-art':39 'system':63 'task':54,67 'train':22 'transform':2,10,23,29,86,90 'updat':84 'v3':57 'various':52 'version':71,83 'xlnet':50","created_at":"2026-04-16T14:11:08.464203+00:00","updated_at":"2026-04-16T14:11:08.464203+00:00","problems":{"verify_error":"Traceback (most recent call last):\n  File \"<string>\", line 1, in <module>\n  File \"/tmp/tmp08_hhkvb/venv/lib/python3.12/site-packages/spacy_transformers/__init__.py\", line 1, in <module>\n    from . import architectures\n  File \"/tmp/tmp08_hhkvb/venv/lib/python3.12/site-packages/spacy_transformers/arch"},"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.4.0","cli_name":"","cli_version":null,"type":"library","homepage":"https://spacy.io","github":null,"docs":null,"changelog":null,"pypi":"https://pypi.org/project/spacy-transformers/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["ai-ml","llm-agents"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"import_fail","verified_at":"2026-07-03","last_verified":"2026-07-03","next_check":"2026-07-10","install_tag":null}}