mirror of
https://github.com/explosion/spaCy.git
synced 2024-12-29 11:26:28 +03:00
354 lines
14 KiB
Cython
354 lines
14 KiB
Cython
# cython: infer_types=True, profile=True, binding=True
|
|
from typing import Iterable, Iterator, Optional, Dict, Tuple, Callable
|
|
import srsly
|
|
from thinc.api import set_dropout_rate, Model, Optimizer
|
|
import warnings
|
|
|
|
from ..tokens.doc cimport Doc
|
|
|
|
from ..training import validate_examples
|
|
from ..errors import Errors, Warnings
|
|
from .pipe import Pipe, deserialize_config
|
|
from .. import util
|
|
from ..vocab import Vocab
|
|
from ..language import Language
|
|
from ..training import Example
|
|
|
|
|
|
cdef class TrainablePipe(Pipe):
|
|
"""This class is a base class and not instantiated directly. Trainable
|
|
pipeline components like the EntityRecognizer or TextCategorizer inherit
|
|
from it and it defines the interface that components should follow to
|
|
function as trainable components in a spaCy pipeline.
|
|
|
|
DOCS: https://spacy.io/api/pipe
|
|
"""
|
|
def __init__(self, vocab: Vocab, model: Model, name: str, **cfg):
|
|
"""Initialize a pipeline component.
|
|
|
|
vocab (Vocab): The shared vocabulary.
|
|
model (thinc.api.Model): The Thinc Model powering the pipeline component.
|
|
name (str): The component instance name.
|
|
**cfg: Additional settings and config parameters.
|
|
|
|
DOCS: https://spacy.io/api/pipe#init
|
|
"""
|
|
self.vocab = vocab
|
|
self.model = model
|
|
self.name = name
|
|
self.cfg = dict(cfg)
|
|
|
|
def __call__(self, Doc doc) -> Doc:
|
|
"""Apply the pipe to one document. The document is modified in place,
|
|
and returned. This usually happens under the hood when the nlp object
|
|
is called on a text and all components are applied to the Doc.
|
|
|
|
docs (Doc): The Doc to process.
|
|
RETURNS (Doc): The processed Doc.
|
|
|
|
DOCS: https://spacy.io/api/pipe#call
|
|
"""
|
|
error_handler = self.get_error_handler()
|
|
try:
|
|
scores = self.predict([doc])
|
|
self.set_annotations([doc], scores)
|
|
return doc
|
|
except Exception as e:
|
|
error_handler(self.name, self, [doc], e)
|
|
|
|
def pipe(self, stream: Iterable[Doc], *, batch_size: int=128) -> Iterator[Doc]:
|
|
"""Apply the pipe to a stream of documents. This usually happens under
|
|
the hood when the nlp object is called on a text and all components are
|
|
applied to the Doc.
|
|
|
|
stream (Iterable[Doc]): A stream of documents.
|
|
batch_size (int): The number of documents to buffer.
|
|
error_handler (Callable[[str, List[Doc], Exception], Any]): Function that
|
|
deals with a failing batch of documents. The default function just reraises
|
|
the exception.
|
|
YIELDS (Doc): Processed documents in order.
|
|
|
|
DOCS: https://spacy.io/api/pipe#pipe
|
|
"""
|
|
error_handler = self.get_error_handler()
|
|
for docs in util.minibatch(stream, size=batch_size):
|
|
try:
|
|
scores = self.predict(docs)
|
|
self.set_annotations(docs, scores)
|
|
yield from docs
|
|
except Exception as e:
|
|
error_handler(self.name, self, docs, e)
|
|
|
|
def predict(self, docs: Iterable[Doc]):
|
|
"""Apply the pipeline's model to a batch of docs, without modifying them.
|
|
Returns a single tensor for a batch of documents.
|
|
|
|
docs (Iterable[Doc]): The documents to predict.
|
|
RETURNS: Vector representations of the predictions.
|
|
|
|
DOCS: https://spacy.io/api/pipe#predict
|
|
"""
|
|
raise NotImplementedError(Errors.E931.format(parent="TrainablePipe", method="predict", name=self.name))
|
|
|
|
def set_annotations(self, docs: Iterable[Doc], scores):
|
|
"""Modify a batch of documents, using pre-computed scores.
|
|
|
|
docs (Iterable[Doc]): The documents to modify.
|
|
scores: The scores to assign.
|
|
|
|
DOCS: https://spacy.io/api/pipe#set_annotations
|
|
"""
|
|
raise NotImplementedError(Errors.E931.format(parent="TrainablePipe", method="set_annotations", name=self.name))
|
|
|
|
def update(self,
|
|
examples: Iterable["Example"],
|
|
*,
|
|
drop: float=0.0,
|
|
sgd: Optimizer=None,
|
|
losses: Optional[Dict[str, float]]=None) -> Dict[str, float]:
|
|
"""Learn from a batch of documents and gold-standard information,
|
|
updating the pipe's model. Delegates to predict and get_loss.
|
|
|
|
examples (Iterable[Example]): A batch of Example objects.
|
|
drop (float): The dropout rate.
|
|
sgd (thinc.api.Optimizer): The optimizer.
|
|
losses (Dict[str, float]): Optional record of the loss during training.
|
|
Updated using the component name as the key.
|
|
RETURNS (Dict[str, float]): The updated losses dictionary.
|
|
|
|
DOCS: https://spacy.io/api/pipe#update
|
|
"""
|
|
if losses is None:
|
|
losses = {}
|
|
if not hasattr(self, "model") or self.model in (None, True, False):
|
|
return losses
|
|
losses.setdefault(self.name, 0.0)
|
|
validate_examples(examples, "TrainablePipe.update")
|
|
if not any(len(eg.predicted) if eg.predicted else 0 for eg in examples):
|
|
# Handle cases where there are no tokens in any docs.
|
|
return losses
|
|
set_dropout_rate(self.model, drop)
|
|
scores, bp_scores = self.model.begin_update([eg.predicted for eg in examples])
|
|
loss, d_scores = self.get_loss(examples, scores)
|
|
bp_scores(d_scores)
|
|
if sgd not in (None, False):
|
|
self.finish_update(sgd)
|
|
losses[self.name] += loss
|
|
return losses
|
|
|
|
def rehearse(self,
|
|
examples: Iterable[Example],
|
|
*,
|
|
sgd: Optimizer=None,
|
|
losses: Dict[str, float]=None,
|
|
**config) -> Dict[str, float]:
|
|
"""Perform a "rehearsal" update from a batch of data. Rehearsal updates
|
|
teach the current model to make predictions similar to an initial model,
|
|
to try to address the "catastrophic forgetting" problem. This feature is
|
|
experimental.
|
|
|
|
examples (Iterable[Example]): A batch of Example objects.
|
|
sgd (thinc.api.Optimizer): The optimizer.
|
|
losses (Dict[str, float]): Optional record of the loss during training.
|
|
Updated using the component name as the key.
|
|
RETURNS (Dict[str, float]): The updated losses dictionary.
|
|
|
|
DOCS: https://spacy.io/api/pipe#rehearse
|
|
"""
|
|
pass
|
|
|
|
def get_loss(self, examples: Iterable[Example], scores) -> Tuple[float, float]:
|
|
"""Find the loss and gradient of loss for the batch of documents and
|
|
their predicted scores.
|
|
|
|
examples (Iterable[Examples]): The batch of examples.
|
|
scores: Scores representing the model's predictions.
|
|
RETURNS (Tuple[float, float]): The loss and the gradient.
|
|
|
|
DOCS: https://spacy.io/api/pipe#get_loss
|
|
"""
|
|
raise NotImplementedError(Errors.E931.format(parent="TrainablePipe", method="get_loss", name=self.name))
|
|
|
|
def create_optimizer(self) -> Optimizer:
|
|
"""Create an optimizer for the pipeline component.
|
|
|
|
RETURNS (thinc.api.Optimizer): The optimizer.
|
|
|
|
DOCS: https://spacy.io/api/pipe#create_optimizer
|
|
"""
|
|
return util.create_default_optimizer()
|
|
|
|
def initialize(self, get_examples: Callable[[], Iterable[Example]], *, nlp: Language=None):
|
|
"""Initialize the pipe for training, using data examples if available.
|
|
This method needs to be implemented by each TrainablePipe component,
|
|
ensuring the internal model (if available) is initialized properly
|
|
using the provided sample of Example objects.
|
|
|
|
get_examples (Callable[[], Iterable[Example]]): Function that
|
|
returns a representative sample of gold-standard Example objects.
|
|
nlp (Language): The current nlp object the component is part of.
|
|
|
|
DOCS: https://spacy.io/api/pipe#initialize
|
|
"""
|
|
raise NotImplementedError(Errors.E931.format(parent="TrainablePipe", method="initialize", name=self.name))
|
|
|
|
def add_label(self, label: str) -> int:
|
|
"""Add an output label.
|
|
For TrainablePipe components, it is possible to
|
|
extend pretrained models with new labels, but care should be taken to
|
|
avoid the "catastrophic forgetting" problem.
|
|
|
|
label (str): The label to add.
|
|
RETURNS (int): 0 if label is already present, otherwise 1.
|
|
|
|
DOCS: https://spacy.io/api/pipe#add_label
|
|
"""
|
|
raise NotImplementedError(Errors.E931.format(parent="Pipe", method="add_label", name=self.name))
|
|
|
|
@property
|
|
def is_trainable(self) -> bool:
|
|
return True
|
|
|
|
@property
|
|
def is_resizable(self) -> bool:
|
|
return getattr(self, "model", None) and "resize_output" in self.model.attrs
|
|
|
|
def _allow_extra_label(self) -> None:
|
|
"""Raise an error if the component can not add any more labels."""
|
|
nO = None
|
|
if self.model.has_dim("nO"):
|
|
nO = self.model.get_dim("nO")
|
|
elif self.model.has_ref("output_layer") and self.model.get_ref("output_layer").has_dim("nO"):
|
|
nO = self.model.get_ref("output_layer").get_dim("nO")
|
|
if nO is not None and nO == len(self.labels):
|
|
if not self.is_resizable:
|
|
raise ValueError(Errors.E922.format(name=self.name, nO=self.model.get_dim("nO")))
|
|
|
|
def set_output(self, nO: int) -> None:
|
|
if self.is_resizable:
|
|
self.model.attrs["resize_output"](self.model, nO)
|
|
else:
|
|
raise NotImplementedError(Errors.E921)
|
|
|
|
def use_params(self, params: dict):
|
|
"""Modify the pipe's model, to use the given parameter values. At the
|
|
end of the context, the original parameters are restored.
|
|
|
|
params (dict): The parameter values to use in the model.
|
|
|
|
DOCS: https://spacy.io/api/pipe#use_params
|
|
"""
|
|
with self.model.use_params(params):
|
|
yield
|
|
|
|
def finish_update(self, sgd: Optimizer) -> None:
|
|
"""Update parameters using the current parameter gradients.
|
|
The Optimizer instance contains the functionality to perform
|
|
the stochastic gradient descent.
|
|
|
|
sgd (thinc.api.Optimizer): The optimizer.
|
|
|
|
DOCS: https://spacy.io/api/pipe#finish_update
|
|
"""
|
|
self.model.finish_update(sgd)
|
|
|
|
def _validate_serialization_attrs(self):
|
|
"""Check that the pipe implements the required attributes. If a subclass
|
|
implements a custom __init__ method but doesn't set these attributes,
|
|
they currently default to None, so we need to perform additonal checks.
|
|
"""
|
|
if not hasattr(self, "vocab") or self.vocab is None:
|
|
raise ValueError(Errors.E899.format(name=util.get_object_name(self)))
|
|
if not hasattr(self, "model") or self.model is None:
|
|
raise ValueError(Errors.E898.format(name=util.get_object_name(self)))
|
|
|
|
def to_bytes(self, *, exclude=tuple()):
|
|
"""Serialize the pipe to a bytestring.
|
|
|
|
exclude (Iterable[str]): String names of serialization fields to exclude.
|
|
RETURNS (bytes): The serialized object.
|
|
|
|
DOCS: https://spacy.io/api/pipe#to_bytes
|
|
"""
|
|
self._validate_serialization_attrs()
|
|
serialize = {}
|
|
if hasattr(self, "cfg") and self.cfg is not None:
|
|
serialize["cfg"] = lambda: srsly.json_dumps(self.cfg)
|
|
serialize["vocab"] = lambda: self.vocab.to_bytes(exclude=exclude)
|
|
serialize["model"] = self.model.to_bytes
|
|
return util.to_bytes(serialize, exclude)
|
|
|
|
def from_bytes(self, bytes_data, *, exclude=tuple()):
|
|
"""Load the pipe from a bytestring.
|
|
|
|
exclude (Iterable[str]): String names of serialization fields to exclude.
|
|
RETURNS (TrainablePipe): The loaded object.
|
|
|
|
DOCS: https://spacy.io/api/pipe#from_bytes
|
|
"""
|
|
self._validate_serialization_attrs()
|
|
|
|
def load_model(b):
|
|
try:
|
|
self.model.from_bytes(b)
|
|
except AttributeError:
|
|
raise ValueError(Errors.E149) from None
|
|
|
|
deserialize = {}
|
|
if hasattr(self, "cfg") and self.cfg is not None:
|
|
deserialize["cfg"] = lambda b: self.cfg.update(srsly.json_loads(b))
|
|
deserialize["vocab"] = lambda b: self.vocab.from_bytes(b, exclude=exclude)
|
|
deserialize["model"] = load_model
|
|
util.from_bytes(bytes_data, deserialize, exclude)
|
|
return self
|
|
|
|
def to_disk(self, path, *, exclude=tuple()):
|
|
"""Serialize the pipe to disk.
|
|
|
|
path (str / Path): Path to a directory.
|
|
exclude (Iterable[str]): String names of serialization fields to exclude.
|
|
|
|
DOCS: https://spacy.io/api/pipe#to_disk
|
|
"""
|
|
self._validate_serialization_attrs()
|
|
serialize = {}
|
|
if hasattr(self, "cfg") and self.cfg is not None:
|
|
serialize["cfg"] = lambda p: srsly.write_json(p, self.cfg)
|
|
serialize["vocab"] = lambda p: self.vocab.to_disk(p, exclude=exclude)
|
|
serialize["model"] = lambda p: self.model.to_disk(p)
|
|
util.to_disk(path, serialize, exclude)
|
|
|
|
def from_disk(self, path, *, exclude=tuple()):
|
|
"""Load the pipe from disk.
|
|
|
|
path (str / Path): Path to a directory.
|
|
exclude (Iterable[str]): String names of serialization fields to exclude.
|
|
RETURNS (TrainablePipe): The loaded object.
|
|
|
|
DOCS: https://spacy.io/api/pipe#from_disk
|
|
"""
|
|
self._validate_serialization_attrs()
|
|
|
|
def load_model(p):
|
|
try:
|
|
with open(p, "rb") as mfile:
|
|
self.model.from_bytes(mfile.read())
|
|
except AttributeError:
|
|
raise ValueError(Errors.E149) from None
|
|
|
|
deserialize = {}
|
|
if hasattr(self, "cfg") and self.cfg is not None:
|
|
deserialize["cfg"] = lambda p: self.cfg.update(deserialize_config(p))
|
|
deserialize["vocab"] = lambda p: self.vocab.from_disk(p, exclude=exclude)
|
|
deserialize["model"] = load_model
|
|
util.from_disk(path, deserialize, exclude)
|
|
return self
|
|
|
|
@property
|
|
def save_activations(self):
|
|
return self._save_activations
|
|
|
|
@save_activations.setter
|
|
def save_activations(self, save_activations: bool):
|
|
self._save_activations = save_activations
|