//- 💫 DOCS > USAGE > PIPELINE

include ../../_includes/_mixins

+h(2, "101") Pipelines 101

include _spacy-101/_pipelines

+h(2, "pipelines") How pipelines work

p
    |  spaCy makes it very easy to create your own pipelines consisting of
    |  reusable components – this includes spaCy's default vectorizer, tagger,
    |  parser and entity regcognizer, but also your own custom processing
    |  functions. A pipeline component can be added to an already existing
    |  #[code nlp] object, specified when initialising a #[code Language] class,
    |  or defined within a
    |  #[+a("/docs/usage/saving-loading#models-generating") model package].

p
    |  When you load a model, spaCy first consults the model's
    |  #[+a("/docs/usage/saving-loading#models-generating") meta.json] for its
    |  #[code setup] details. This typically includes the ID of a language class,
    |  and an optional list of pipeline components. spaCy then does the
    |  following:

+aside-code("meta.json (excerpt)", "json").
    {
        "name": "example_model",
        "description": "Example model for spaCy",
        "setup": {
            "lang": "en",
            "pipeline": ["token_vectors", "tagger"]
        }
    }

+list("numbers")
    +item
        |  Look up #[strong pipeline IDs] in the available
        |  #[strong pipeline factories].
    +item
        |  Initialise the #[strong pipeline components] by calling their
        |  factories with the #[code Vocab] as an argument. This gives each
        |  factory and component access to the pipeline's shared data, like
        |  strings, morphology and annotation scheme.
    +item
        |  Load the #[strong language class and data] for the given ID via
        |  #[+api("util.get_lang_class") #[code get_lang_class]].
    +item
        |  Pass the path to the #[strong model data] to the #[code Language]
        |  class and return it.

p
    |  So when you call this...

+code.
    nlp = spacy.load('en')

p
    | ... the model tells spaCy to use the pipeline
    |  #[code ["vectorizer", "tagger", "parser", "ner"]]. spaCy will then look
    |  up each string in its internal factories registry and initialise the
    |  individual components. It'll then load #[code spacy.lang.en.English],
    |  pass it the path to the model's data directory, and return it for you
    |  to use as the #[code nlp] object.

p
    |  When you call #[code nlp] on a text, spaCy will #[strong tokenize] it and
    |  then #[strong call each component] on the #[code Doc], in order.
    |  Components all return the modified document, which is then processed by
    |  the component next in the pipeline.

+code("The pipeline under the hood").
    doc = nlp.make_doc(u'This is a sentence')
    for proc in nlp.pipeline:
        doc = proc(doc)

+h(2, "creating") Creating pipeline components and factories

p
    |  spaCy lets you customise the pipeline with your own components. Components
    |  are functions that receive a #[code Doc] object, modify and return it.
    |  If your component is stateful, you'll want to create a new one for each
    |  pipeline. You can do that by defining and registering a factory which
    |  receives the shared #[code Vocab] object and returns a component.

+h(3, "creating-component") Creating a  component

p
    |  A component receives a #[code Doc] object and
    |  #[strong performs the actual processing] – for example, using the current
    |  weights to make a prediction and set some annotation on the document. By
    |  adding a component to the pipeline, you'll get access to the #[code Doc]
    |  at any point #[strong during] processing – instead of only being able to
    |  modify it afterwards.

+aside-code("Example").
    def my_component(doc):
        # do something to the doc here
        return doc

+table(["Argument", "Type", "Description"])
    +row
        +cell #[code doc]
        +cell #[code Doc]
        +cell The #[code Doc] object processed by the previous component.

    +footrow
        +cell returns
        +cell #[code Doc]
        +cell The #[code Doc] object processed by this pipeline component.

p
    |  When creating a new #[code Language] class, you can pass it a list of
    |  pipeline component functions to execute in that order. You can also
    |  add it to an existing pipeline by modifying #[code nlp.pipeline] – just
    |  be careful not to overwrite a pipeline or its components by accident!

+code.
    # Create a new Language object with a pipeline
    from spacy.language import Language
    nlp = Language(pipeline=[my_component])

    # Modify an existing pipeline
    nlp = spacy.load('en')
    nlp.pipeline.append(my_component)

+h(3, "creating-factory") Creating a factory

p
    |  A factory is a #[strong function that returns a pipeline component].
    |  It's called with the #[code Vocab] object, to give it access to the
    |  shared data between components – for example, the strings, morphology,
    |  vectors or annotation scheme. Factories are useful for creating
    |  #[strong stateful components], especially ones which
    |  #[strong depend on shared data].

+aside-code("Example").
    def my_factory(vocab):
        # load some state
        def my_component(doc):
            # process the doc
            return doc
        return my_component

+table(["Argument", "Type", "Description"])
    +row
        +cell #[code vocab]
        +cell #[coce Vocab]
        +cell
            |  Shared data between components, including strings, morphology,
            |  vectors etc.

    +footrow
        +cell returns
        +cell callable
        +cell The pipeline component.

p
    |  By creating a factory, you're essentially telling spaCy how to get the
    |  pipeline component #[strong once the vocab is available]. Factories need to
    |  be registered via #[+api("spacy#set_factory") #[code set_factory()]] and
    |  by assigning them a unique ID. This ID can be added to the pipeline as a
    |  string. When creating a pipeline, you're free to mix strings and
    |  callable components:

+code.
    spacy.set_factory('my_factory', my_factory)
    nlp = Language(pipeline=['my_factory', my_other_component])

p
    |  If spaCy comes across a string in the pipeline, it will try to resolve it
    |  by looking it up in the available factories. The factory will then be
    |  initialised with the #[code Vocab]. Providing factory names instead of
    |  callables also makes it easy to specify them in the model's
    |  #[+a("/docs/usage/saving-loading#models-generating") meta.json]. If you're
    |  training your own model and want to use one of spaCy's default components,
    |  you won't have to worry about finding and implementing it either – to use
    |  the default tagger, simply add #[code "tagger"] to the pipeline, and
    |  #[strong spaCy will know what to do].


+infobox("Important note")
    |  Because factories are #[strong resolved on initialisation] of the
    |  #[code Language] class, it's #[strong not possible] to add them to the
    |  pipeline afterwards, e.g. by modifying #[code nlp.pipeline]. This only
    |  works with individual component functions. To use factories, you need to
    |  create a new #[code Language] object, or generate a
    |  #[+a("/docs/usage/saving-loading#models-generating") model package] with
    |  a custom pipeline.

+h(2, "example1") Example: Custom sentence segmentation logic

+aside("Real-world examples")
    |  To see real-world examples of pipeline factories and components in action,
    |  you can have a look at the source of spaCy's built-in components, e.g.
    |  the #[+src(gh("spacy")) tagger], #[+src(gh("spacy")) parser] or
    |  #[+src(gh("spacy")) entity recognizer].

p
    |  Let's say you want to implement custom logic to improve spaCy's sentence
    |  boundary detection. Currently, sentence segmentation is based on the
    |  dependency parse, which doesn't always produce ideal results. The custom
    |  logic should therefore be applied #[strong after] tokenization, but
    |  #[strong before] the dependency parsing – this way, the parser can also
    |  take advantage of the sentence boundaries.

+code.
    def sbd_component(doc):
        for i, token in enumerate(doc[:-2]):
            # define sentence start if period + titlecase token
            if token.text == '.' and doc[i+1].is_title:
                doc[i+1].sent_start = True
        return doc

p
    |  In this case, we simply want to add the component to the existing
    |  pipeline of the English model. We can do this by inserting it at index 0
    |  of #[code nlp.pipeline]:

+code.
    nlp = spacy.load('en')
    nlp.pipeline.insert(0, sbd_component)

p
    |  When you call #[code nlp] on some text, spaCy will tokenize it to create
    |  a #[code Doc] object, and first call #[code sbd_component] on it, followed
    |  by the model's default pipeline.

+h(2, "example2") Example: Sentiment model

p
    |  Let's say you have trained your own document sentiment model on English
    |  text. After tokenization, you want spaCy to first execute the
    |  #[strong default vectorizer], followed by a custom
    |  #[strong sentiment component] that adds a #[code .sentiment]
    |  property to the #[code Doc], containing your model's sentiment precition.

p
    |  Your component class will have a #[code from_disk()] method that spaCy
    |  calls to load the model data. When called, the component will compute
    |  the sentiment score, add it to the #[code Doc] and return the modified
    |  document. Optionally, the component can include an #[code update()] method
    |  to allow training the model.

+code.
    import pickle
    from pathlib import Path

    class SentimentComponent(object):
        def __init__(self, vocab):
            self.weights = None

        def __call__(self, doc):
            doc.sentiment = sum(self.weights*doc.vector) # set sentiment property
            return doc

        def from_disk(self, path): # path = model path + factory ID ('sentiment')
            self.weights = pickle.load(Path(path) / 'weights.bin') # load weights
            return self

        def update(self, doc, gold): # update weights – allows training!
            prediction = sum(self.weights*doc.vector)
            self.weights -= 0.001*doc.vector*(prediction-gold.sentiment)

p
    |  The factory will initialise the component with the #[code Vocab] object.
    |  To be able to add it to your model's pipeline as #[code 'sentiment'],
    |  it also needs to be registered via
    |  #[+api("spacy#set_factory") #[code set_factory()]].

+code.
    def sentiment_factory(vocab):
        component = SentimentComponent(vocab) # initialise component
        return component

    spacy.set_factory('sentiment', sentiment_factory)

p
    |  The above code should be #[strong shipped with your model]. You can use
    |  the #[+api("cli#package") #[code package]] command to create all required
    |  files and directories. The model package will include an
    |  #[+src(gh("spacy-dev-resources", "templates/model/en_model_name/__init__.py")) __init__.py]
    |  with a #[code load()] method, that will initialise the language class with
    |  the model's pipeline and call the #[code from_disk()] method to load
    |  the model data.

p
    |  In the model package's meta.json, specify the language class and pipeline
    |  IDs in #[code setup]:

+code("meta.json (excerpt)", "json").
    {
        "name": "my_sentiment_model",
        "version": "1.0.0",
        "spacy_version": ">=2.0.0,<3.0.0",
        "setup": {
            "lang": "en",
            "pipeline": ["vectorizer", "sentiment"]
        }
    }

p
    |  When you load your new model, spaCy will call the model's #[code load()]
    |  method. This will return a #[code Language] object with a pipeline
    |  containing the default vectorizer, and the sentiment component returned
    |  by your custom #[code "sentiment"] factory.

+code.
    nlp = spacy.load('my_sentiment_model')
    doc = nlp(u'I love pizza')
    assert doc.sentiment

+infobox("Saving and loading models")
    |  For more information and a detailed guide on how to package your model,
    |  see the documentation on
    |  #[+a("/docs/usage/saving-loading#models") saving and loading models].