explosion/spacy

💫 Industrial-strength Natural Language Processing (NLP) in Python

How Data Flows Through the System

Text enters through the Language.nlp() method, gets tokenized into a Doc object, then flows through a configurable pipeline of components (tagger, parser, NER, etc.) that progressively add linguistic annotations. During training, the system loads Example objects containing gold annotations, computes predictions through the same pipeline, calculates losses, and updates model weights through backpropagation.

1. Text Tokenization — The Tokenizer splits raw text into Token objects using language-specific rules, exceptions, and Unicode segmentation, creating a Doc container with shared Vocab for string interning (config: tokenizer)
2. Pipeline Processing — The Language orchestrator passes the Doc through each enabled pipeline component (tagger, parser, NER) in sequence, with each component adding annotations in-place [Doc → Doc] (config: nlp.pipeline, components)
3. Training Data Loading — Corpus reader loads training files in .spacy/.json/.conllu formats, creates Example objects with predicted and reference Doc pairs for supervised learning (config: training.train_corpus, training.dev_corpus)
4. Batch Formation — Training examples are grouped into batches of configurable size with proper alignment and padding for efficient neural network processing [Example → TrainingBatch] (config: training.batcher)
5. Forward Pass — TrainablePipe components process batched examples through their neural networks, computing predictions and intermediate representations [TrainingBatch → Predictions] (config: components.*.model)
6. Loss Computation — Each component compares predictions against gold annotations to compute task-specific losses (cross-entropy for classification, structured loss for parsing) [Predictions → Loss Values] (config: training.dropout)
7. Gradient Update — The optimizer (Adam, SGD, etc.) computes gradients from losses and updates model parameters according to the configured learning rate and schedule [Loss Values → Updated Parameters] (config: training.optimizer, training.learning_rate)

Data Models

The data structures that flow between stages — the contracts that hold the system together.

Hidden Assumptions

Things this code relies on but never validates. These are the things that cause silent failures when the system changes.

System Behavior

How the system operates at runtime — where data accumulates, what loops, what waits, and what controls what.

Data Pools

Feedback Loops

• Training Loop (training-loop, reinforcing) — Trigger: Training command with configured max_epochs. Action: Process batch, compute loss, update weights, evaluate on dev set. Exit: Max epochs reached or early stopping criteria met.
• Gradient Accumulation (gradient-accumulation, balancing) — Trigger: Batch size smaller than accumulation steps. Action: Accumulate gradients across mini-batches before updating parameters. Exit: Accumulation steps reached.
• Learning Rate Schedule (convergence, balancing) — Trigger: Evaluation score plateau detection. Action: Reduce learning rate by configured factor. Exit: Minimum learning rate reached.
• Early Stopping (convergence, balancing) — Trigger: No improvement in dev score for patience steps. Action: Monitor evaluation metrics and count stagnant steps. Exit: Training terminates early.

Delays

• Model Loading (warmup, ~1-10 seconds) — Initial pipeline instantiation and weight loading from disk before first prediction
• Training Evaluation (scheduled-job, ~varies by data size) — Periodic evaluation on dev set pauses training at configured intervals
• Checkpoint Saving (checkpoint-save, ~1-30 seconds) — Serializing model state to disk blocks training progress temporarily
• Data Loading (batch-window, ~milliseconds per batch) — Reading and parsing training files creates small delays between batches

Control Points

• Pipeline Components (architecture-switch) — Controls: Which NLP components are loaded and in what order. Default: nlp.pipeline
• Batch Size (hyperparameter) — Controls: Number of examples processed together, affecting memory usage and gradient stability. Default: training.batcher
• Learning Rate (hyperparameter) — Controls: Step size for gradient updates, critical for training convergence. Default: training.optimizer
• GPU Usage (device-selection) — Controls: Whether to use GPU acceleration for training and inference. Default: training.gpu_allocator
• Dropout Rate (hyperparameter) — Controls: Regularization strength during training to prevent overfitting. Default: training.dropout
• Model Architecture (architecture-switch) — Controls: Neural network structure and size for each pipeline component. Default: components.*.model
• Evaluation Frequency (threshold) — Controls: How often to evaluate on dev set during training (in steps). Default: training.eval_frequency

Technology Stack

Key Components

• Language (orchestrator) — Main orchestrator that loads models, manages the processing pipeline, and coordinates text processing through sequential component stages spacy/language.py
• CLI App (dispatcher) — Typer-based command dispatcher that routes CLI commands to appropriate handlers for training, evaluation, debugging, and data management spacy/cli/_util.py
• TrainablePipe (processor) — Base class for neural pipeline components that can be trained, updated, and serialized with consistent interfaces for prediction and learning spacy/pipeline/
• Corpus (loader) — Data loader that reads training files in various formats (.spacy, .json, .conllu) and yields Example objects for training spacy/training/corpus.py
• Config System (registry) — Configuration registry that maps string identifiers to Python functions for components, optimizers, and other configurable objects using Thinc's registry spacy/util.py
• Tokenizer (transformer) — Language-specific text segmentation that splits raw text into Token objects using rules, exceptions, and character patterns spacy/tokenizer.py
• Training Loop (executor) — Main training orchestrator that manages epochs, batching, gradient updates, evaluation, and checkpoint saving with configurable optimization spacy/cli/train.py
• DocBin (serializer) — Efficient binary serialization format for Doc objects that preserves annotations while enabling fast loading and minimal disk usage spacy/tokens/docbin.py
• Matcher (processor) — Rule-based pattern matching system that finds token sequences based on lexical attributes, POS tags, and dependency relations spacy/matcher/

Related Library Repositories

Frequently Asked Questions

Analyzed on April 20, 2026 by CodeSea. Written by Karolina Sarna.