mirror of
https://github.com/explosion/spaCy.git
synced 2025-07-18 12:12:20 +03:00
Add span predictor docs
This commit is contained in:
Paul O'Leary McCann
parent
57165f9631
commit
14eb20f07a
|
|
@ -92,9 +92,9 @@ shortcut for this and instantiate the component using its string name and
|
||||||
Apply the pipe to one document. The document is modified in place and returned.
|
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
|
This usually happens under the hood when the `nlp` object is called on a text
|
||||||
and all pipeline components are applied to the `Doc` in order. Both
|
and all pipeline components are applied to the `Doc` in order. Both
|
||||||
[`__call__`](/api/entitylinker#call) and [`pipe`](/api/entitylinker#pipe)
|
[`__call__`](/api/coref#call) and [`pipe`](/api/coref#pipe) delegate to the
|
||||||
delegate to the [`predict`](/api/entitylinker#predict) and
|
[`predict`](/api/coref#predict) and
|
||||||
[`set_annotations`](/api/entitylinker#set_annotations) methods.
|
[`set_annotations`](/api/coref#set_annotations) methods.
|
||||||
|
|
||||||
> #### Example
|
> #### Example
|
||||||
>
|
>
|
||||||
|
|
@ -197,7 +197,7 @@ Modify a batch of documents, saving coreference clusters in `Doc.spans`.
|
||||||
## CoreferenceResolver.update {#update tag="method"}
|
## CoreferenceResolver.update {#update tag="method"}
|
||||||
|
|
||||||
Learn from a batch of [`Example`](/api/example) objects. Delegates to
|
Learn from a batch of [`Example`](/api/example) objects. Delegates to
|
||||||
[`predict`](/api/entitylinker#predict).
|
[`predict`](/api/coref#predict).
|
||||||
|
|
||||||
> #### Example
|
> #### Example
|
||||||
>
|
>
|
||||||
|
|
|
||||||
340
website/docs/api/span-predictor.md
Normal file
340
website/docs/api/span-predictor.md
Normal file
|
|
@ -0,0 +1,340 @@
|
||||||
|
---
|
||||||
|
title: SpanPredictor
|
||||||
|
tag: class
|
||||||
|
source: spacy/pipeline/span_predictor.py
|
||||||
|
new: 3.4
|
||||||
|
teaser: 'Pipeline component for resolving tokens into spans'
|
||||||
|
api_base_class: /api/pipe
|
||||||
|
api_string_name: span_predictor
|
||||||
|
api_trainable: true
|
||||||
|
---
|
||||||
|
|
||||||
|
A `SpanPredictor` component takes in tokens (represented as `Span`s of length
|
||||||
|
|
||||||
|
1. and resolves them into `Span`s of arbitrary length. The initial use case is
|
||||||
|
as a post-processing step on word-level [coreference resolution](/api/coref).
|
||||||
|
The input and output keys used to store `Span`s are configurable.
|
||||||
|
|
||||||
|
## Assigned Attributes {#assigned-attributes}
|
||||||
|
|
||||||
|
Predictions will be saved to `Doc.spans` as [`SpanGroup`s](/api/spangroup).
|
||||||
|
|
||||||
|
Input token spans will be read in using an input prefix, by default
|
||||||
|
`"coref_head_clusters"`, and output spans will be saved using an output prefix
|
||||||
|
(default `"coref_clusters"`) plus a serial number starting from zero. The
|
||||||
|
prefixes are configurable.
|
||||||
|
|
||||||
|
| Location | Value |
|
||||||
|
| ------------------------------------------------- | ------------------------------------------- |
|
||||||
|
| `Doc.spans[output_prefix + "_" + cluster_number]` | One group of predicted spans. ~~SpanGroup~~ |
|
||||||
|
|
||||||
|
## Config and implementation {#config}
|
||||||
|
|
||||||
|
The default config is defined by the pipeline component factory and describes
|
||||||
|
how the component should be configured. You can override its settings via the
|
||||||
|
`config` argument on [`nlp.add_pipe`](/api/language#add_pipe) or in your
|
||||||
|
[`config.cfg` for training](/usage/training#config). See the
|
||||||
|
[model architectures](/api/architectures) documentation for details on the
|
||||||
|
architectures and their arguments and hyperparameters.
|
||||||
|
|
||||||
|
> #### Example
|
||||||
|
>
|
||||||
|
> ```python
|
||||||
|
> from spacy.pipeline.span_predictor import DEFAULT_SPAN_PREDICTOR_MODEL
|
||||||
|
> config={
|
||||||
|
> "model": DEFAULT_SPAN_PREDICTOR_MODEL,
|
||||||
|
> "span_cluster_prefix": DEFAULT_CLUSTER_PREFIX,
|
||||||
|
> },
|
||||||
|
> nlp.add_pipe("span_predictor", config=config)
|
||||||
|
> ```
|
||||||
|
|
||||||
|
| Setting | Description |
|
||||||
|
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||||
|
| `model` | The [`Model`](https://thinc.ai/docs/api-model) powering the pipeline component. Defaults to [SpanPredictor](/api/architectures#SpanPredictor). ~~Model~~ |
|
||||||
|
| `input_prefix` | The prefix to use for input `SpanGroup`s. Defaults to `coref_head_clusters`. ~~str~~ |
|
||||||
|
| `output_prefix` | The prefix for predicted `SpanGroup`s. Defaults to `coref_clusters`. ~~str~~ |
|
||||||
|
|
||||||
|
```python
|
||||||
|
%%GITHUB_SPACY/spacy/pipeline/span_predictor.py
|
||||||
|
```
|
||||||
|
|
||||||
|
## SpanPredictor.\_\_init\_\_ {#init tag="method"}
|
||||||
|
|
||||||
|
> #### Example
|
||||||
|
>
|
||||||
|
> ```python
|
||||||
|
> # Construction via add_pipe with default model
|
||||||
|
> span_predictor = nlp.add_pipe("span_predictor")
|
||||||
|
>
|
||||||
|
> # Construction via add_pipe with custom model
|
||||||
|
> config = {"model": {"@architectures": "my_span_predictor.v1"}}
|
||||||
|
> span_predictor = nlp.add_pipe("span_predictor", config=config)
|
||||||
|
>
|
||||||
|
> # Construction from class
|
||||||
|
> from spacy.pipeline import SpanPredictor
|
||||||
|
> span_predictor = SpanPredictor(nlp.vocab, model)
|
||||||
|
> ```
|
||||||
|
|
||||||
|
Create a new pipeline instance. In your application, you would normally use a
|
||||||
|
shortcut for this and instantiate the component using its string name and
|
||||||
|
[`nlp.add_pipe`](/api/language#add_pipe).
|
||||||
|
|
||||||
|
| Name | Description |
|
||||||
|
| --------------- | --------------------------------------------------------------------------------------------------- |
|
||||||
|
| `vocab` | The shared vocabulary. ~~Vocab~~ |
|
||||||
|
| `model` | The [`Model`](https://thinc.ai/docs/api-model) powering the pipeline component. ~~Model~~ |
|
||||||
|
| `name` | String name of the component instance. Used to add entries to the `losses` during training. ~~str~~ |
|
||||||
|
| _keyword-only_ | |
|
||||||
|
| `input_prefix` | The prefix to use for input `SpanGroup`s. Defaults to `coref_head_clusters`. ~~str~~ |
|
||||||
|
| `output_prefix` | The prefix for predicted `SpanGroup`s. Defaults to `coref_clusters`. ~~str~~ |
|
||||||
|
|
||||||
|
## SpanPredictor.\_\_call\_\_ {#call tag="method"}
|
||||||
|
|
||||||
|
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 pipeline components are applied to the `Doc` in order. Both
|
||||||
|
[`__call__`](#call) and [`pipe`](#pipe) delegate to the [`predict`](#predict)
|
||||||
|
and [`set_annotations`](#set_annotations) methods.
|
||||||
|
|
||||||
|
> #### Example
|
||||||
|
>
|
||||||
|
> ```python
|
||||||
|
> doc = nlp("This is a sentence.")
|
||||||
|
> span_predictor = nlp.add_pipe("span_predictor")
|
||||||
|
> # This usually happens under the hood
|
||||||
|
> processed = span_predictor(doc)
|
||||||
|
> ```
|
||||||
|
|
||||||
|
| Name | Description |
|
||||||
|
| ----------- | -------------------------------- |
|
||||||
|
| `doc` | The document to process. ~~Doc~~ |
|
||||||
|
| **RETURNS** | The processed document. ~~Doc~~ |
|
||||||
|
|
||||||
|
## SpanPredictor.pipe {#pipe tag="method"}
|
||||||
|
|
||||||
|
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 pipeline components are
|
||||||
|
applied to the `Doc` in order. Both [`__call__`](/api/span-predictor#call) and
|
||||||
|
[`pipe`](/api/span-predictor#pipe) delegate to the
|
||||||
|
[`predict`](/api/span-predictor#predict) and
|
||||||
|
[`set_annotations`](/api/span-predictor#set_annotations) methods.
|
||||||
|
|
||||||
|
> #### Example
|
||||||
|
>
|
||||||
|
> ```python
|
||||||
|
> span_predictor = nlp.add_pipe("span_predictor")
|
||||||
|
> for doc in span_predictor.pipe(docs, batch_size=50):
|
||||||
|
> pass
|
||||||
|
> ```
|
||||||
|
|
||||||
|
| Name | Description |
|
||||||
|
| -------------- | ------------------------------------------------------------- |
|
||||||
|
| `stream` | A stream of documents. ~~Iterable[Doc]~~ |
|
||||||
|
| _keyword-only_ | |
|
||||||
|
| `batch_size` | The number of documents to buffer. Defaults to `128`. ~~int~~ |
|
||||||
|
| **YIELDS** | The processed documents in order. ~~Doc~~ |
|
||||||
|
|
||||||
|
## SpanPredictor.initialize {#initialize tag="method"}
|
||||||
|
|
||||||
|
Initialize the component for training. `get_examples` should be a function that
|
||||||
|
returns an iterable of [`Example`](/api/example) objects. The data examples are
|
||||||
|
used to **initialize the model** of the component and can either be the full
|
||||||
|
training data or a representative sample. Initialization includes validating the
|
||||||
|
network,
|
||||||
|
[inferring missing shapes](https://thinc.ai/docs/usage-models#validation) and
|
||||||
|
setting up the label scheme based on the data. This method is typically called
|
||||||
|
by [`Language.initialize`](/api/language#initialize).
|
||||||
|
|
||||||
|
> #### Example
|
||||||
|
>
|
||||||
|
> ```python
|
||||||
|
> span_predictor = nlp.add_pipe("span_predictor")
|
||||||
|
> span_predictor.initialize(lambda: [], nlp=nlp)
|
||||||
|
> ```
|
||||||
|
|
||||||
|
| Name | Description |
|
||||||
|
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
|
||||||
|
| `get_examples` | Function that returns gold-standard annotations in the form of [`Example`](/api/example) objects. ~~Callable[[], Iterable[Example]]~~ |
|
||||||
|
| _keyword-only_ | |
|
||||||
|
| `nlp` | The current `nlp` object. Defaults to `None`. ~~Optional[Language]~~ |
|
||||||
|
|
||||||
|
## SpanPredictor.predict {#predict tag="method"}
|
||||||
|
|
||||||
|
Apply the component's model to a batch of [`Doc`](/api/doc) objects, without
|
||||||
|
modifying them. Predictions are returned as a list of `MentionClusters`, one for
|
||||||
|
each input `Doc`. A `MentionClusters` instance is just a list of lists of pairs
|
||||||
|
of `int`s, where each item corresponds to an input `SpanGroup`, and the `int`s
|
||||||
|
correspond to token indices.
|
||||||
|
|
||||||
|
> #### Example
|
||||||
|
>
|
||||||
|
> ```python
|
||||||
|
> span_predictor = nlp.add_pipe("span_predictor")
|
||||||
|
> spans = span_predictor.predict([doc1, doc2])
|
||||||
|
> ```
|
||||||
|
|
||||||
|
| Name | Description |
|
||||||
|
| ----------- | ------------------------------------------------------------- |
|
||||||
|
| `docs` | The documents to predict. ~~Iterable[Doc]~~ |
|
||||||
|
| **RETURNS** | The predicted spans for the `Doc`s. ~~List[MentionClusters]~~ |
|
||||||
|
|
||||||
|
## SpanPredictor.set_annotations {#set_annotations tag="method"}
|
||||||
|
|
||||||
|
Modify a batch of documents, saving predictions using the output prefix in
|
||||||
|
`Doc.spans`.
|
||||||
|
|
||||||
|
> #### Example
|
||||||
|
>
|
||||||
|
> ```python
|
||||||
|
> span_predictor = nlp.add_pipe("span_predictor")
|
||||||
|
> spans = span_predictor.predict([doc1, doc2])
|
||||||
|
> span_predictor.set_annotations([doc1, doc2], spans)
|
||||||
|
> ```
|
||||||
|
|
||||||
|
| Name | Description |
|
||||||
|
| ------- | ------------------------------------------------------------- |
|
||||||
|
| `docs` | The documents to modify. ~~Iterable[Doc]~~ |
|
||||||
|
| `spans` | The predicted spans for the `docs`. ~~List[MentionClusters]~~ |
|
||||||
|
|
||||||
|
## SpanPredictor.update {#update tag="method"}
|
||||||
|
|
||||||
|
Learn from a batch of [`Example`](/api/example) objects. Delegates to
|
||||||
|
[`predict`](/api/span-predictor#predict).
|
||||||
|
|
||||||
|
> #### Example
|
||||||
|
>
|
||||||
|
> ```python
|
||||||
|
> span_predictor = nlp.add_pipe("span_predictor")
|
||||||
|
> optimizer = nlp.initialize()
|
||||||
|
> losses = span_predictor.update(examples, sgd=optimizer)
|
||||||
|
> ```
|
||||||
|
|
||||||
|
| Name | Description |
|
||||||
|
| -------------- | ------------------------------------------------------------------------------------------------------------------------ |
|
||||||
|
| `examples` | A batch of [`Example`](/api/example) objects to learn from. ~~Iterable[Example]~~ |
|
||||||
|
| _keyword-only_ | |
|
||||||
|
| `drop` | The dropout rate. ~~float~~ |
|
||||||
|
| `sgd` | An optimizer. Will be created via [`create_optimizer`](#create_optimizer) if not set. ~~Optional[Optimizer]~~ |
|
||||||
|
| `losses` | Optional record of the loss during training. Updated using the component name as the key. ~~Optional[Dict[str, float]]~~ |
|
||||||
|
| **RETURNS** | The updated `losses` dictionary. ~~Dict[str, float]~~ |
|
||||||
|
|
||||||
|
## SpanPredictor.create_optimizer {#create_optimizer tag="method"}
|
||||||
|
|
||||||
|
Create an optimizer for the pipeline component.
|
||||||
|
|
||||||
|
> #### Example
|
||||||
|
>
|
||||||
|
> ```python
|
||||||
|
> span_predictor = nlp.add_pipe("span_predictor")
|
||||||
|
> optimizer = span_predictor.create_optimizer()
|
||||||
|
> ```
|
||||||
|
|
||||||
|
| Name | Description |
|
||||||
|
| ----------- | ---------------------------- |
|
||||||
|
| **RETURNS** | The optimizer. ~~Optimizer~~ |
|
||||||
|
|
||||||
|
## SpanPredictor.use_params {#use_params tag="method, contextmanager"}
|
||||||
|
|
||||||
|
Modify the pipe's model, to use the given parameter values. At the end of the
|
||||||
|
context, the original parameters are restored.
|
||||||
|
|
||||||
|
> #### Example
|
||||||
|
>
|
||||||
|
> ```python
|
||||||
|
> span_predictor = nlp.add_pipe("span_predictor")
|
||||||
|
> with span_predictor.use_params(optimizer.averages):
|
||||||
|
> span_predictor.to_disk("/best_model")
|
||||||
|
> ```
|
||||||
|
|
||||||
|
| Name | Description |
|
||||||
|
| -------- | -------------------------------------------------- |
|
||||||
|
| `params` | The parameter values to use in the model. ~~dict~~ |
|
||||||
|
|
||||||
|
## SpanPredictor.to_disk {#to_disk tag="method"}
|
||||||
|
|
||||||
|
Serialize the pipe to disk.
|
||||||
|
|
||||||
|
> #### Example
|
||||||
|
>
|
||||||
|
> ```python
|
||||||
|
> span_predictor = nlp.add_pipe("span_predictor")
|
||||||
|
> span_predictor.to_disk("/path/to/span_predictor")
|
||||||
|
> ```
|
||||||
|
|
||||||
|
| Name | Description |
|
||||||
|
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||||
|
| `path` | A path to a directory, which will be created if it doesn't exist. Paths may be either strings or `Path`-like objects. ~~Union[str, Path]~~ |
|
||||||
|
| _keyword-only_ | |
|
||||||
|
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
|
||||||
|
|
||||||
|
## SpanPredictor.from_disk {#from_disk tag="method"}
|
||||||
|
|
||||||
|
Load the pipe from disk. Modifies the object in place and returns it.
|
||||||
|
|
||||||
|
> #### Example
|
||||||
|
>
|
||||||
|
> ```python
|
||||||
|
> span_predictor = nlp.add_pipe("span_predictor")
|
||||||
|
> span_predictor.from_disk("/path/to/span_predictor")
|
||||||
|
> ```
|
||||||
|
|
||||||
|
| Name | Description |
|
||||||
|
| -------------- | ----------------------------------------------------------------------------------------------- |
|
||||||
|
| `path` | A path to a directory. Paths may be either strings or `Path`-like objects. ~~Union[str, Path]~~ |
|
||||||
|
| _keyword-only_ | |
|
||||||
|
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
|
||||||
|
| **RETURNS** | The modified `SpanPredictor` object. ~~SpanPredictor~~ |
|
||||||
|
|
||||||
|
## SpanPredictor.to_bytes {#to_bytes tag="method"}
|
||||||
|
|
||||||
|
> #### Example
|
||||||
|
>
|
||||||
|
> ```python
|
||||||
|
> span_predictor = nlp.add_pipe("span_predictor")
|
||||||
|
> span_predictor_bytes = span_predictor.to_bytes()
|
||||||
|
> ```
|
||||||
|
|
||||||
|
Serialize the pipe to a bytestring.
|
||||||
|
|
||||||
|
| Name | Description |
|
||||||
|
| -------------- | ------------------------------------------------------------------------------------------- |
|
||||||
|
| _keyword-only_ | |
|
||||||
|
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
|
||||||
|
| **RETURNS** | The serialized form of the `SpanPredictor` object. ~~bytes~~ |
|
||||||
|
|
||||||
|
## SpanPredictor.from_bytes {#from_bytes tag="method"}
|
||||||
|
|
||||||
|
Load the pipe from a bytestring. Modifies the object in place and returns it.
|
||||||
|
|
||||||
|
> #### Example
|
||||||
|
>
|
||||||
|
> ```python
|
||||||
|
> span_predictor_bytes = span_predictor.to_bytes()
|
||||||
|
> span_predictor = nlp.add_pipe("span_predictor")
|
||||||
|
> span_predictor.from_bytes(span_predictor_bytes)
|
||||||
|
> ```
|
||||||
|
|
||||||
|
| Name | Description |
|
||||||
|
| -------------- | ------------------------------------------------------------------------------------------- |
|
||||||
|
| `bytes_data` | The data to load from. ~~bytes~~ |
|
||||||
|
| _keyword-only_ | |
|
||||||
|
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
|
||||||
|
| **RETURNS** | The `SpanPredictor` object. ~~SpanPredictor~~ |
|
||||||
|
|
||||||
|
## Serialization fields {#serialization-fields}
|
||||||
|
|
||||||
|
During serialization, spaCy will export several data fields used to restore
|
||||||
|
different aspects of the object. If needed, you can exclude them from
|
||||||
|
serialization by passing in the string names via the `exclude` argument.
|
||||||
|
|
||||||
|
> #### Example
|
||||||
|
>
|
||||||
|
> ```python
|
||||||
|
> data = span_predictor.to_disk("/path", exclude=["vocab"])
|
||||||
|
> ```
|
||||||
|
|
||||||
|
| Name | Description |
|
||||||
|
| ------- | -------------------------------------------------------------- |
|
||||||
|
| `vocab` | The shared [`Vocab`](/api/vocab). |
|
||||||
|
| `cfg` | The config file. You usually don't want to exclude this. |
|
||||||
|
| `model` | The binary model data. You usually don't want to exclude this. |
|
||||||
Loading…
Reference in New Issue
Block a user