# lang_main.types API documentation

# Module `lang_main.types`

## Classes

`class SpacyDoc (...)`

  Doc(Vocab vocab, words=None, spaces=None, user_data=None, *, tags=None, pos=None, morphs=None, lemmas=None, heads=None, deps=None, sent_starts=None, ents=None) A sequence of Token objects. Access sentences and named entities, export annotations to numpy arrays, losslessly serialize to compressed binary strings. The `Doc` object holds an array of `TokenC` structs. The Python-level `Token` and `Span` objects are views of this array, i.e. they don't own the data themselves.

      EXAMPLE:
          Construction 1
          >>> doc = nlp(u'Some text')

          Construction 2
          >>> from spacy.tokens import Doc
          >>> doc = Doc(nlp.vocab, words=["hello", "world", "!"], spaces=[True, False, False])

      DOCS: <https://spacy.io/api/doc>

  Create a Doc object.

  vocab (Vocab): A vocabulary object, which must match any models you want to use (e.g. tokenizer, parser, entity recognizer). words (Optional[List[Union[str, int]]]): A list of unicode strings or hash values to add to the document as words. If `None`, defaults to empty list. spaces (Optional[List[bool]]): A list of boolean values, of the same length as `words`. `True` means that the word is followed by a space, `False` means it is not. If `None`, defaults to `[True]*len(words)` user_data (dict or None): Optional extra data to attach to the Doc. tags (Optional[List[str]]): A list of unicode strings, of the same length as words, to assign as token.tag. Defaults to None. pos (Optional[List[str]]): A list of unicode strings, of the same length as words, to assign as token.pos. Defaults to None. morphs (Optional[List[str]]): A list of unicode strings, of the same length as words, to assign as token.morph. Defaults to None. lemmas (Optional[List[str]]): A list of unicode strings, of the same length as words, to assign as token.lemma. Defaults to None. heads (Optional[List[int]]): A list of values, of the same length as words, to assign as heads. Head indices are the position of the head in the doc. Defaults to None. deps (Optional[List[str]]): A list of unicode strings, of the same length as words, to assign as token.dep. Defaults to None. sent_starts (Optional[List[Union[bool, int, None]]]): A list of values, of the same length as words, to assign as token.is_sent_start. Will be overridden by heads if heads is provided. Defaults to None. ents (Optional[List[str]]): A list of unicode strings, of the same length as words, as IOB tags to assign as token.ent_iob and token.ent_type. Defaults to None.

  DOCS: https://spacy.io/api/doc#init

  ### Static methods

  `def from_docs(...)`

    Doc.from_docs(docs, ensure_whitespace=True, attrs=None, *, exclude=tuple()) Concatenate multiple Doc objects to form a new one. Raises an error if the `Doc` objects do not all share the same `Vocab`.

            docs (list): A list of Doc objects.
            ensure_whitespace (bool): Insert a space between two adjacent docs
                whenever the first doc does not end in whitespace.
            attrs (list): Optional list of attribute ID ints or attribute name
                strings.
            exclude (Iterable[str]): Doc attributes to exclude. Supported
                attributes: <code>spans</code>, <code>tensor</code>, <code>user\_data</code>.
            RETURNS (Doc): A doc that contains the concatenated docs, or None if no
                docs were given.

            DOCS: <https://spacy.io/api/doc#from_docs>

  ### Instance variables

  `var cats`

    cats: object

  `var doc`
  `var ents`

    The named entities in the document. Returns a tuple of named entity `Span` objects, if the entity recognizer has been applied.

    RETURNS (tuple): Entities in the document, one `Span` per entity.

    DOCS: https://spacy.io/api/doc#ents

  `var has_unknown_spaces`

    has_unknown_spaces: 'bool'

  `var has_vector`

    A boolean value indicating whether a word vector is associated with the object.

    RETURNS (bool): Whether a word vector is associated with the object.

    DOCS: https://spacy.io/api/doc#has_vector

  `var is_nered`
  `var is_parsed`
  `var is_sentenced`
  `var is_tagged`
  `var lang`

    RETURNS (uint64): ID of the language of the doc's vocabulary.

  `var lang_`

    RETURNS (str): Language of the doc's vocabulary, e.g. 'en'.

  `var mem`
  `var noun_chunks`

    Iterate over the base noun phrases in the document. Yields base noun-phrase #[code Span] objects, if the language has a noun chunk iterator. Raises a NotImplementedError otherwise.

    A base noun phrase, or "NP chunk", is a noun phrase that does not permit other NPs to be nested within it – so no NP-level coordination, no prepositional phrases, and no relative clauses.

    YIELDS (Span): Noun chunks in the document.

    DOCS: https://spacy.io/api/doc#noun_chunks

  `var noun_chunks_iterator`

    noun_chunks_iterator: object

  `var sentiment`

    sentiment: 'float'

  `var sents`

    Iterate over the sentences in the document. Yields sentence `Span` objects. Sentence spans have no label.

    YIELDS (Span): Sentences in the document.

    DOCS: https://spacy.io/api/doc#sents

  `var spans`
  `var tensor`

    tensor: object

  `var text`

    A unicode representation of the document text.

    RETURNS (str): The original verbatim text of the document.

  `var text_with_ws`

    An alias of `Doc.text`, provided for duck-type compatibility with `Span` and `Token`.

    RETURNS (str): The original verbatim text of the document.

  `var user_data`

    user_data: object

  `var user_hooks`

    user_hooks: dict

  `var user_span_hooks`

    user_span_hooks: dict

  `var user_token_hooks`

    user_token_hooks: dict

  `var vector`

    A real-valued meaning representation. Defaults to an average of the token vectors.

    RETURNS (numpy.ndarray[ndim=1, dtype='float32']): A 1D numpy array representing the document's semantics.

    DOCS: https://spacy.io/api/doc#vector

  `var vector_norm`

    The L2 norm of the document's vector representation.

    RETURNS (float): The L2 norm of the vector representation.

    DOCS: https://spacy.io/api/doc#vector_norm

  `var vocab`

  ### Methods

  `def char_span(...)`

    Doc.char_span(self, int start_idx, int end_idx, label=0, kb_id=0, vector=None, alignment_mode='strict', span_id=0) Create a `Span` object from the slice `doc.text[start_idx : end_idx]`. Returns None if no valid `Span` can be created.

            doc (Doc): The parent document.
            start_idx (int): The index of the first character of the span.
            end_idx (int): The index of the first character after the span.
            label (Union[int, str]): A label to attach to the Span, e.g. for
                named entities.
            kb_id (Union[int, str]):  An ID from a KB to capture the meaning of a
                named entity.
            vector (ndarray[ndim=1, dtype='float32']): A meaning representation of
                the span.
            alignment_mode (str): How character indices are aligned to token
                boundaries. Options: "strict" (character indices must be aligned
                with token boundaries), "contract" (span of all tokens completely
                within the character span), "expand" (span of all tokens at least
                partially covered by the character span). Defaults to "strict".
            span_id (Union[int, str]): An identifier to associate with the span.
            RETURNS (Span): The newly constructed object.

            DOCS: <https://spacy.io/api/doc#char_span>

  `def copy(...)`

    Doc.copy(self)

  `def count_by(...)`

    Doc.count_by(self, attr_id_t attr_id, exclude=None, counts=None) Count the frequencies of a given attribute. Produces a dict of `{attribute (int): count (ints)}` frequencies, keyed by the values of the given attribute ID.

            attr_id (int): The attribute ID to key the counts.
            RETURNS (dict): A dictionary mapping attributes to integer counts.

            DOCS: <https://spacy.io/api/doc#count_by>

  `def extend_tensor(...)`

    Doc.extend_tensor(self, tensor) Concatenate a new tensor onto the doc.tensor object.

            The doc.tensor attribute holds dense feature vectors
            computed by the models in the pipeline. Let's say a
            document with 30 words has a tensor with 128 dimensions
            per word. doc.tensor.shape will be (30, 128). After
            calling doc.extend_tensor with an array of shape (30, 64),
            doc.tensor == (30, 192).

  `def from_array(...)`

    Doc.from_array(self, attrs, array) Load attributes from a numpy array. Write to a `Doc` object, from an `(M, N)` array of attributes.

            attrs (list) A list of attribute ID ints.
            array (numpy.ndarray[ndim=2, dtype='int32']): The attribute values.
            RETURNS (Doc): Itself.

            DOCS: <https://spacy.io/api/doc#from_array>

  `def from_bytes(...)`

    Doc.from_bytes(self, bytes_data, *, exclude=tuple()) Deserialize, i.e. import the document contents from a binary string.

            data (bytes): The string to load from.
            exclude (Iterable[str]): String names of serialization fields to exclude.
            RETURNS (Doc): Itself.

            DOCS: <https://spacy.io/api/doc#from_bytes>

  `def from_dict(...)`

    Doc.from_dict(self, msg, *, exclude=tuple()) Deserialize the document contents from a dictionary representation.

            msg (Dict[str, Any]): The dictionary to load from.
            exclude (Iterable[str]): String names of serialization fields to exclude.
            RETURNS (Doc): Itself.

  `def from_disk(...)`

    Doc.from_disk(self, path, *, exclude=tuple()) Loads state from a directory. Modifies the object in place and returns it.

            path (str / Path): A path to a directory. Paths may be either
                strings or <code>Path</code>-like objects.
            exclude (Iterable[str]): String names of serialization fields to exclude.
            RETURNS (Doc): The modified <code><a title="lang_main.types.Doc" href="#lang_main.types.Doc">Doc</a></code> object.

            DOCS: <https://spacy.io/api/doc#from_disk>

  `def from_json(...)`

    Doc.from_json(self, doc_json, *, validate=False) Convert a JSON document generated by Doc.to_json() to a Doc.

            doc_json (Dict): JSON representation of doc object to load.
            validate (bool): Whether to validate <code>doc\_json</code> against the expected schema.
                Defaults to False.
            RETURNS (Doc): A doc instance corresponding to the specified JSON representation.

  `def get_extension(...)`

    Doc.get_extension(type cls, name) Look up a previously registered extension by name.

            name (str): Name of the extension.
            RETURNS (tuple): A <code>(default, method, getter, setter)</code> tuple.

            DOCS: <https://spacy.io/api/doc#get_extension>

  `def get_lca_matrix(...)`

    Doc.get_lca_matrix(self) Calculates a matrix of Lowest Common Ancestors (LCA) for a given `Doc`, where LCA[i, j] is the index of the lowest common ancestor among token i and j.

            RETURNS (np.array[ndim=2, dtype=numpy.int32]): LCA matrix with shape
                (n, n), where n = len(self).

            DOCS: <https://spacy.io/api/doc#get_lca_matrix>

  `def has_annotation(...)`

    Doc.has_annotation(self, attr, *, require_complete=False) Check whether the doc contains annotation on a token attribute.

            attr (Union[int, str]): The attribute string name or int ID.
            require_complete (bool): Whether to check that the attribute is set on
                every token in the doc.
            RETURNS (bool): Whether annotation is present.

            DOCS: <https://spacy.io/api/doc#has_annotation>

  `def has_extension(...)`

    Doc.has_extension(type cls, name) Check whether an extension has been registered.

            name (str): Name of the extension.
            RETURNS (bool): Whether the extension has been registered.

            DOCS: <https://spacy.io/api/doc#has_extension>

  `def remove_extension(...)`

    Doc.remove_extension(type cls, name) Remove a previously registered extension.

            name (str): Name of the extension.
            RETURNS (tuple): A <code>(default, method, getter, setter)</code> tuple of the
                removed extension.

            DOCS: <https://spacy.io/api/doc#remove_extension>

  `def retokenize(...)`

    Doc.retokenize(self) Context manager to handle retokenization of the Doc. Modifications to the Doc's tokenization are stored, and then made all at once when the context manager exits. This is much more efficient, and less error-prone.

            All views of the Doc (Span and Token) created before the
            retokenization are invalidated, although they may accidentally
            continue to work.

            DOCS: <https://spacy.io/api/doc#retokenize>
            USAGE: <https://spacy.io/usage/linguistic-features#retokenization>

  `def set_ents(...)`

    Doc.set_ents(self, entities, *, blocked=None, missing=None, outside=None, default=SetEntsDefault.outside) Set entity annotation.

            entities (List[Span]): Spans with labels to set as entities.
            blocked (Optional[List[Span]]): Spans to set as 'blocked' (never an
                entity) for spacy's built-in NER component. Other components may
                ignore this setting.
            missing (Optional[List[Span]]): Spans with missing/unknown entity
                information.
            outside (Optional[List[Span]]): Spans outside of entities (O in IOB).
            default (str): How to set entity annotation for tokens outside of any
                provided spans. Options: "blocked", "missing", "outside" and
                "unmodified" (preserve current state). Defaults to "outside".

  `def set_extension(...)`

    Doc.set_extension(type cls, name, **kwargs) Define a custom attribute which becomes available as `Doc._`.

            name (str): Name of the attribute to set.
            default: Optional default value of the attribute.
            getter (callable): Optional getter function.
            setter (callable): Optional setter function.
            method (callable): Optional method for method extension.
            force (bool): Force overwriting existing attribute.

            DOCS: <https://spacy.io/api/doc#set_extension>
            USAGE: <https://spacy.io/usage/processing-pipelines#custom-components-attributes>

  `def similarity(...)`

    Doc.similarity(self, other) Make a semantic similarity estimate. The default estimate is cosine similarity using an average of word vectors.

            other (object): The object to compare with. By default, accepts <code><a title="lang_main.types.Doc" href="#lang_main.types.Doc">Doc</a></code>,
                <code>Span</code>, <code><a title="lang_main.types.Token" href="#lang_main.types.Token">Token</a></code> and <code>Lexeme</code> objects.
            RETURNS (float): A scalar similarity score. Higher is more similar.

            DOCS: <https://spacy.io/api/doc#similarity>

  `def to_array(...)`

    Doc.to_array(self, py_attr_ids) -> ndarray Export given token attributes to a numpy `ndarray`. If `attr_ids` is a sequence of M attributes, the output array will be of shape `(N, M)`, where N is the length of the `Doc` (in tokens). If `attr_ids` is a single attribute, the output shape will be (N,). You can specify attributes by integer ID (e.g. spacy.attrs.LEMMA) or string name (e.g. 'LEMMA' or 'lemma').

            py_attr_ids (list[]): A list of attributes (int IDs or string names).
            RETURNS (numpy.ndarray[long, ndim=2]): A feature matrix, with one row
                per word, and one column per attribute indicated in the input
                <code>attr\_ids</code>.

            EXAMPLE:
                >>> from spacy.attrs import LOWER, POS, ENT_TYPE, IS_ALPHA
                >>> doc = nlp(text)
                >>> # All strings mapped to integers, for easy export to numpy
                >>> np_array = doc.to_array([LOWER, POS, ENT_TYPE, IS_ALPHA])

  `def to_bytes(...)`

    Doc.to_bytes(self, *, exclude=tuple()) Serialize, i.e. export the document contents to a binary string.

            exclude (Iterable[str]): String names of serialization fields to exclude.
            RETURNS (bytes): A losslessly serialized copy of the <code><a title="lang_main.types.Doc" href="#lang_main.types.Doc">Doc</a></code>, including
                all annotations.

            DOCS: <https://spacy.io/api/doc#to_bytes>

  `def to_dict(...)`

    Doc.to_dict(self, *, exclude=tuple()) Export the document contents to a dictionary for serialization.

            exclude (Iterable[str]): String names of serialization fields to exclude.
            RETURNS (Dict[str, Any]): A dictionary representation of the <code><a title="lang_main.types.Doc" href="#lang_main.types.Doc">Doc</a></code>

  `def to_disk(...)`

    Doc.to_disk(self, path, *, exclude=tuple()) Save the current state to a directory.

            path (str / Path): A path to a directory, which will be created if
                it doesn't exist. Paths may be either strings or Path-like objects.
            exclude (Iterable[str]): String names of serialization fields to exclude.

            DOCS: <https://spacy.io/api/doc#to_disk>

  `def to_json(...)`

    Doc.to_json(self, underscore=None) Convert a Doc to JSON.

            underscore (list): Optional list of string names of custom doc._.
            attributes. Attribute values need to be JSON-serializable. Values will
            be added to an "_" key in the data, e.g. "_": {"foo": "bar"}.
            RETURNS (dict): The data in JSON format.

  `def to_utf8_array(...)`

    Doc.to_utf8_array(self, int nr_char=-1) Encode word strings to utf8, and export to a fixed-width array of characters. Characters are placed into the array in the order: 0, -1, 1, -2, etc For example, if the array is sliced array[:, :8], the array will contain the first 4 characters and last 4 characters of each word — with the middle characters clipped out. The value 255 is used as a pad value.

`class SpacyModel (vocab: spacy.vocab.Vocab | bool = True,
*,
max_length: int = 1000000,
meta: Dict[str, Any] = {},
create_tokenizer: Callable[[ForwardRef('Language')], Callable[[str], spacy.tokens.doc.Doc]] | None = None,
create_vectors: Callable[[ForwardRef('Vocab')], spacy.vectors.BaseVectors] | None = None,
batch_size: int = 1000,
**kwargs)`
  Expand source code

      class Language:
          """A text-processing pipeline. Usually you'll load this once per process,
          and pass the instance around your application.

          Defaults (class): Settings, data and factory methods for creating the `nlp`
              object and processing pipeline.
          lang (str): IETF language code, such as 'en'.

          DOCS: https://spacy.io/api/language
          """

          Defaults = BaseDefaults
          lang: Optional[str] = None
          default_config = DEFAULT_CONFIG

          factories = SimpleFrozenDict(error=Errors.E957)
          _factory_meta: Dict[str, "FactoryMeta"] = {}  # meta by factory

          def __init__(
              self,
              vocab: Union[Vocab, bool] = True,
              *,
              max_length: int = 10**6,
              meta: Dict[str, Any] = {},
              create_tokenizer: Optional[Callable[["Language"], Callable[[str], Doc]]] = None,
              create_vectors: Optional[Callable[["Vocab"], BaseVectors]] = None,
              batch_size: int = 1000,
              **kwargs,
          ) -> None:
              """Initialise a Language object.

              vocab (Vocab): A `Vocab` object. If `True`, a vocab is created.
              meta (dict): Custom meta data for the Language class. Is written to by
                  models to add model meta data.
              max_length (int): Maximum number of characters in a single text. The
                  current models may run out memory on extremely long texts, due to
                  large internal allocations. You should segment these texts into
                  meaningful units, e.g. paragraphs, subsections etc, before passing
                  them to spaCy. Default maximum length is 1,000,000 charas (1mb). As
                  a rule of thumb, if all pipeline components are enabled, spaCy's
                  default models currently requires roughly 1GB of temporary memory per
                  100,000 characters in one text.
              create_tokenizer (Callable): Function that takes the nlp object and
                  returns a tokenizer.
              batch_size (int): Default batch size for pipe and evaluate.

              DOCS: https://spacy.io/api/language#init
              """
              # We're only calling this to import all factories provided via entry
              # points. The factory decorator applied to these functions takes care
              # of the rest.
              util.registry._entry_point_factories.get_all()

              self._config = DEFAULT_CONFIG.merge(self.default_config)
              self._meta = dict(meta)
              self._path = None
              self._optimizer: Optional[Optimizer] = None
              # Component meta and configs are only needed on the instance
              self._pipe_meta: Dict[str, "FactoryMeta"] = {}  # meta by component
              self._pipe_configs: Dict[str, Config] = {}  # config by component

              if not isinstance(vocab, Vocab) and vocab is not True:
                  raise ValueError(Errors.E918.format(vocab=vocab, vocab_type=type(Vocab)))
              if vocab is True:
                  vectors_name = meta.get("vectors", {}).get("name")
                  vocab = create_vocab(self.lang, self.Defaults, vectors_name=vectors_name)
                  if not create_vectors:
                      vectors_cfg = {"vectors": self._config["nlp"]["vectors"]}
                      create_vectors = registry.resolve(vectors_cfg)["vectors"]
                  vocab.vectors = create_vectors(vocab)
              else:
                  if (self.lang and vocab.lang) and (self.lang != vocab.lang):
                      raise ValueError(Errors.E150.format(nlp=self.lang, vocab=vocab.lang))
              self.vocab: Vocab = vocab
              if self.lang is None:
                  self.lang = self.vocab.lang
              self._components: List[Tuple[str, PipeCallable]] = []
              self._disabled: Set[str] = set()
              self.max_length = max_length
              # Create the default tokenizer from the default config
              if not create_tokenizer:
                  tokenizer_cfg = {"tokenizer": self._config["nlp"]["tokenizer"]}
                  create_tokenizer = registry.resolve(tokenizer_cfg)["tokenizer"]
              self.tokenizer = create_tokenizer(self)
              self.batch_size = batch_size
              self.default_error_handler = raise_error

          def __init_subclass__(cls, **kwargs):
              super().__init_subclass__(**kwargs)
              cls.default_config = DEFAULT_CONFIG.merge(cls.Defaults.config)
              cls.default_config["nlp"]["lang"] = cls.lang

          @property
          def path(self):
              return self._path

          @property
          def meta(self) -> Dict[str, Any]:
              """Custom meta data of the language class. If a model is loaded, this
              includes details from the model's meta.json.

              RETURNS (Dict[str, Any]): The meta.

              DOCS: https://spacy.io/api/language#meta
              """
              spacy_version = util.get_minor_version_range(about.__version__)
              if self.vocab.lang:
                  self._meta.setdefault("lang", self.vocab.lang)
              else:
                  self._meta.setdefault("lang", self.lang)
              self._meta.setdefault("name", "pipeline")
              self._meta.setdefault("version", "0.0.0")
              self._meta.setdefault("spacy_version", spacy_version)
              self._meta.setdefault("description", "")
              self._meta.setdefault("author", "")
              self._meta.setdefault("email", "")
              self._meta.setdefault("url", "")
              self._meta.setdefault("license", "")
              self._meta.setdefault("spacy_git_version", GIT_VERSION)
              self._meta["vectors"] = {
                  "width": self.vocab.vectors_length,
                  "vectors": len(self.vocab.vectors),
                  "keys": self.vocab.vectors.n_keys,
                  "name": self.vocab.vectors.name,
                  "mode": self.vocab.vectors.mode,
              }
              self._meta["labels"] = dict(self.pipe_labels)
              # TODO: Adding this back to prevent breaking people's code etc., but
              # we should consider removing it
              self._meta["pipeline"] = list(self.pipe_names)
              self._meta["components"] = list(self.component_names)
              self._meta["disabled"] = list(self.disabled)
              return self._meta

          @meta.setter
          def meta(self, value: Dict[str, Any]) -> None:
              self._meta = value

          @property
          def config(self) -> Config:
              """Trainable config for the current language instance. Includes the
              current pipeline components, as well as default training config.

              RETURNS (thinc.api.Config): The config.

              DOCS: https://spacy.io/api/language#config
              """
              self._config.setdefault("nlp", {})
              self._config.setdefault("training", {})
              self._config["nlp"]["lang"] = self.lang
              # We're storing the filled config for each pipeline component and so
              # we can populate the config again later
              pipeline = {}
              score_weights = []
              for pipe_name in self.component_names:
                  pipe_meta = self.get_pipe_meta(pipe_name)
                  pipe_config = self.get_pipe_config(pipe_name)
                  pipeline[pipe_name] = {"factory": pipe_meta.factory, **pipe_config}
                  if pipe_meta.default_score_weights:
                      score_weights.append(pipe_meta.default_score_weights)
              self._config["nlp"]["pipeline"] = list(self.component_names)
              self._config["nlp"]["disabled"] = list(self.disabled)
              self._config["components"] = pipeline
              # We're merging the existing score weights back into the combined
              # weights to make sure we're preserving custom settings in the config
              # but also reflect updates (e.g. new components added)
              prev_weights = self._config["training"].get("score_weights", {})
              combined_score_weights = combine_score_weights(score_weights, prev_weights)
              self._config["training"]["score_weights"] = combined_score_weights
              if not srsly.is_json_serializable(self._config):
                  raise ValueError(Errors.E961.format(config=self._config))
              return self._config

          @config.setter
          def config(self, value: Config) -> None:
              self._config = value

          @property
          def disabled(self) -> List[str]:
              """Get the names of all disabled components.

              RETURNS (List[str]): The disabled components.
              """
              # Make sure the disabled components are returned in the order they
              # appear in the pipeline (which isn't guaranteed by the set)
              names = [name for name, _ in self._components if name in self._disabled]
              return SimpleFrozenList(names, error=Errors.E926.format(attr="disabled"))

          @property
          def factory_names(self) -> List[str]:
              """Get names of all available factories.

              RETURNS (List[str]): The factory names.
              """
              names = list(self.factories.keys())
              return SimpleFrozenList(names)

          @property
          def components(self) -> List[Tuple[str, PipeCallable]]:
              """Get all (name, component) tuples in the pipeline, including the
              currently disabled components.
              """
              return SimpleFrozenList(
                  self._components, error=Errors.E926.format(attr="components")
              )

          @property
          def component_names(self) -> List[str]:
              """Get the names of the available pipeline components. Includes all
              active and inactive pipeline components.

              RETURNS (List[str]): List of component name strings, in order.
              """
              names = [pipe_name for pipe_name, _ in self._components]
              return SimpleFrozenList(names, error=Errors.E926.format(attr="component_names"))

          @property
          def pipeline(self) -> List[Tuple[str, PipeCallable]]:
              """The processing pipeline consisting of (name, component) tuples. The
              components are called on the Doc in order as it passes through the
              pipeline.

              RETURNS (List[Tuple[str, Callable[[Doc], Doc]]]): The pipeline.
              """
              pipes = [(n, p) for n, p in self._components if n not in self._disabled]
              return SimpleFrozenList(pipes, error=Errors.E926.format(attr="pipeline"))

          @property
          def pipe_names(self) -> List[str]:
              """Get names of available active pipeline components.

              RETURNS (List[str]): List of component name strings, in order.
              """
              names = [pipe_name for pipe_name, _ in self.pipeline]
              return SimpleFrozenList(names, error=Errors.E926.format(attr="pipe_names"))

          @property
          def pipe_factories(self) -> Dict[str, str]:
              """Get the component factories for the available pipeline components.

              RETURNS (Dict[str, str]): Factory names, keyed by component names.
              """
              factories = {}
              for pipe_name, pipe in self._components:
                  factories[pipe_name] = self.get_pipe_meta(pipe_name).factory
              return SimpleFrozenDict(factories)

          @property
          def pipe_labels(self) -> Dict[str, List[str]]:
              """Get the labels set by the pipeline components, if available (if
              the component exposes a labels property and the labels are not
              hidden).

              RETURNS (Dict[str, List[str]]): Labels keyed by component name.
              """
              labels = {}
              for name, pipe in self._components:
                  if hasattr(pipe, "hide_labels") and pipe.hide_labels is True:
                      continue
                  if hasattr(pipe, "labels"):
                      labels[name] = list(pipe.labels)
              return SimpleFrozenDict(labels)

          @classmethod
          def has_factory(cls, name: str) -> bool:
              """RETURNS (bool): Whether a factory of that name is registered."""
              internal_name = cls.get_factory_name(name)
              return name in registry.factories or internal_name in registry.factories

          @classmethod
          def get_factory_name(cls, name: str) -> str:
              """Get the internal factory name based on the language subclass.

              name (str): The factory name.
              RETURNS (str): The internal factory name.
              """
              if cls.lang is None:
                  return name
              return f"{cls.lang}.{name}"

          @classmethod
          def get_factory_meta(cls, name: str) -> "FactoryMeta":
              """Get the meta information for a given factory name.

              name (str): The component factory name.
              RETURNS (FactoryMeta): The meta for the given factory name.
              """
              internal_name = cls.get_factory_name(name)
              if internal_name in cls._factory_meta:
                  return cls._factory_meta[internal_name]
              if name in cls._factory_meta:
                  return cls._factory_meta[name]
              raise ValueError(Errors.E967.format(meta="factory", name=name))

          @classmethod
          def set_factory_meta(cls, name: str, value: "FactoryMeta") -> None:
              """Set the meta information for a given factory name.

              name (str): The component factory name.
              value (FactoryMeta): The meta to set.
              """
              cls._factory_meta[cls.get_factory_name(name)] = value

          def get_pipe_meta(self, name: str) -> "FactoryMeta":
              """Get the meta information for a given component name.

              name (str): The component name.
              RETURNS (FactoryMeta): The meta for the given component name.
              """
              if name not in self._pipe_meta:
                  raise ValueError(Errors.E967.format(meta="component", name=name))
              return self._pipe_meta[name]

          def get_pipe_config(self, name: str) -> Config:
              """Get the config used to create a pipeline component.

              name (str): The component name.
              RETURNS (Config): The config used to create the pipeline component.
              """
              if name not in self._pipe_configs:
                  raise ValueError(Errors.E960.format(name=name))
              pipe_config = self._pipe_configs[name]
              return pipe_config

          @classmethod
          def factory(
              cls,
              name: str,
              *,
              default_config: Dict[str, Any] = SimpleFrozenDict(),
              assigns: Iterable[str] = SimpleFrozenList(),
              requires: Iterable[str] = SimpleFrozenList(),
              retokenizes: bool = False,
              default_score_weights: Dict[str, Optional[float]] = SimpleFrozenDict(),
              func: Optional[Callable] = None,
          ) -> Callable:
              """Register a new pipeline component factory. Can be used as a decorator
              on a function or classmethod, or called as a function with the factory
              provided as the func keyword argument. To create a component and add
              it to the pipeline, you can use nlp.add_pipe(name).

              name (str): The name of the component factory.
              default_config (Dict[str, Any]): Default configuration, describing the
                  default values of the factory arguments.
              assigns (Iterable[str]): Doc/Token attributes assigned by this component,
                  e.g. "token.ent_id". Used for pipeline analysis.
              requires (Iterable[str]): Doc/Token attributes required by this component,
                  e.g. "token.ent_id". Used for pipeline analysis.
              retokenizes (bool): Whether the component changes the tokenization.
                  Used for pipeline analysis.
              default_score_weights (Dict[str, Optional[float]]): The scores to report during
                  training, and their default weight towards the final score used to
                  select the best model. Weights should sum to 1.0 per component and
                  will be combined and normalized for the whole pipeline. If None,
                  the score won't be shown in the logs or be weighted.
              func (Optional[Callable]): Factory function if not used as a decorator.

              DOCS: https://spacy.io/api/language#factory
              """
              if not isinstance(name, str):
                  raise ValueError(Errors.E963.format(decorator="factory"))
              if "." in name:
                  raise ValueError(Errors.E853.format(name=name))
              if not isinstance(default_config, dict):
                  err = Errors.E962.format(
                      style="default config", name=name, cfg_type=type(default_config)
                  )
                  raise ValueError(err)

              def add_factory(factory_func: Callable) -> Callable:
                  internal_name = cls.get_factory_name(name)
                  if internal_name in registry.factories:
                      # We only check for the internal name here – it's okay if it's a
                      # subclass and the base class has a factory of the same name. We
                      # also only raise if the function is different to prevent raising
                      # if module is reloaded.
                      existing_func = registry.factories.get(internal_name)
                      if not util.is_same_func(factory_func, existing_func):
                          err = Errors.E004.format(
                              name=name, func=existing_func, new_func=factory_func
                          )
                          raise ValueError(err)

                  arg_names = util.get_arg_names(factory_func)
                  if "nlp" not in arg_names or "name" not in arg_names:
                      raise ValueError(Errors.E964.format(name=name))
                  # Officially register the factory so we can later call
                  # registry.resolve and refer to it in the config as
                  # @factories = "spacy.Language.xyz". We use the class name here so
                  # different classes can have different factories.
                  registry.factories.register(internal_name, func=factory_func)
                  factory_meta = FactoryMeta(
                      factory=name,
                      default_config=default_config,
                      assigns=validate_attrs(assigns),
                      requires=validate_attrs(requires),
                      scores=list(default_score_weights.keys()),
                      default_score_weights=default_score_weights,
                      retokenizes=retokenizes,
                  )
                  cls.set_factory_meta(name, factory_meta)
                  # We're overwriting the class attr with a frozen dict to handle
                  # backwards-compat (writing to Language.factories directly). This
                  # wouldn't work with an instance property and just produce a
                  # confusing error – here we can show a custom error
                  cls.factories = SimpleFrozenDict(
                      registry.factories.get_all(), error=Errors.E957
                  )
                  return factory_func

              if func is not None:  # Support non-decorator use cases
                  return add_factory(func)
              return add_factory

          @classmethod
          def component(
              cls,
              name: str,
              *,
              assigns: Iterable[str] = SimpleFrozenList(),
              requires: Iterable[str] = SimpleFrozenList(),
              retokenizes: bool = False,
              func: Optional[PipeCallable] = None,
          ) -> Callable[..., Any]:
              """Register a new pipeline component. Can be used for stateless function
              components that don't require a separate factory. Can be used as a
              decorator on a function or classmethod, or called as a function with the
              factory provided as the func keyword argument. To create a component and
              add it to the pipeline, you can use nlp.add_pipe(name).

              name (str): The name of the component factory.
              assigns (Iterable[str]): Doc/Token attributes assigned by this component,
                  e.g. "token.ent_id". Used for pipeline analysis.
              requires (Iterable[str]): Doc/Token attributes required by this component,
                  e.g. "token.ent_id". Used for pipeline analysis.
              retokenizes (bool): Whether the component changes the tokenization.
                  Used for pipeline analysis.
              func (Optional[Callable[[Doc], Doc]): Factory function if not used as a decorator.

              DOCS: https://spacy.io/api/language#component
              """
              if name is not None:
                  if not isinstance(name, str):
                      raise ValueError(Errors.E963.format(decorator="component"))
                  if "." in name:
                      raise ValueError(Errors.E853.format(name=name))
              component_name = name if name is not None else util.get_object_name(func)

              def add_component(component_func: PipeCallable) -> Callable:
                  if isinstance(func, type):  # function is a class
                      raise ValueError(Errors.E965.format(name=component_name))

                  def factory_func(nlp, name: str) -> PipeCallable:
                      return component_func

                  internal_name = cls.get_factory_name(name)
                  if internal_name in registry.factories:
                      # We only check for the internal name here – it's okay if it's a
                      # subclass and the base class has a factory of the same name. We
                      # also only raise if the function is different to prevent raising
                      # if module is reloaded. It's hacky, but we need to check the
                      # existing functure for a closure and whether that's identical
                      # to the component function (because factory_func created above
                      # will always be different, even for the same function)
                      existing_func = registry.factories.get(internal_name)
                      closure = existing_func.__closure__
                      wrapped = [c.cell_contents for c in closure][0] if closure else None
                      if util.is_same_func(wrapped, component_func):
                          factory_func = existing_func  # noqa: F811

                  cls.factory(
                      component_name,
                      assigns=assigns,
                      requires=requires,
                      retokenizes=retokenizes,
                      func=factory_func,
                  )
                  return component_func

              if func is not None:  # Support non-decorator use cases
                  return add_component(func)
              return add_component

          def analyze_pipes(
              self,
              *,
              keys: List[str] = ["assigns", "requires", "scores", "retokenizes"],
              pretty: bool = False,
          ) -> Optional[Dict[str, Any]]:
              """Analyze the current pipeline components, print a summary of what
              they assign or require and check that all requirements are met.

              keys (List[str]): The meta values to display in the table. Corresponds
                  to values in FactoryMeta, defined by @Language.factory decorator.
              pretty (bool): Pretty-print the results.
              RETURNS (dict): The data.
              """
              analysis = analyze_pipes(self, keys=keys)
              if pretty:
                  print_pipe_analysis(analysis, keys=keys)
              return analysis

          def get_pipe(self, name: str) -> PipeCallable:
              """Get a pipeline component for a given component name.

              name (str): Name of pipeline component to get.
              RETURNS (callable): The pipeline component.

              DOCS: https://spacy.io/api/language#get_pipe
              """
              for pipe_name, component in self._components:
                  if pipe_name == name:
                      return component
              raise KeyError(Errors.E001.format(name=name, opts=self.component_names))

          def create_pipe(
              self,
              factory_name: str,
              name: Optional[str] = None,
              *,
              config: Dict[str, Any] = SimpleFrozenDict(),
              raw_config: Optional[Config] = None,
              validate: bool = True,
          ) -> PipeCallable:
              """Create a pipeline component. Mostly used internally. To create and
              add a component to the pipeline, you can use nlp.add_pipe.

              factory_name (str): Name of component factory.
              name (Optional[str]): Optional name to assign to component instance.
                  Defaults to factory name if not set.
              config (Dict[str, Any]): Config parameters to use for this component.
                  Will be merged with default config, if available.
              raw_config (Optional[Config]): Internals: the non-interpolated config.
              validate (bool): Whether to validate the component config against the
                  arguments and types expected by the factory.
              RETURNS (Callable[[Doc], Doc]): The pipeline component.

              DOCS: https://spacy.io/api/language#create_pipe
              """
              name = name if name is not None else factory_name
              if not isinstance(config, dict):
                  err = Errors.E962.format(style="config", name=name, cfg_type=type(config))
                  raise ValueError(err)
              if not srsly.is_json_serializable(config):
                  raise ValueError(Errors.E961.format(config=config))
              if not self.has_factory(factory_name):
                  err = Errors.E002.format(
                      name=factory_name,
                      opts=", ".join(self.factory_names),
                      method="create_pipe",
                      lang=util.get_object_name(self),
                      lang_code=self.lang,
                  )
                  raise ValueError(err)
              pipe_meta = self.get_factory_meta(factory_name)
              # This is unideal, but the alternative would mean you always need to
              # specify the full config settings, which is not really viable.
              if pipe_meta.default_config:
                  config = Config(pipe_meta.default_config).merge(config)
              internal_name = self.get_factory_name(factory_name)
              # If the language-specific factory doesn't exist, try again with the
              # not-specific name
              if internal_name not in registry.factories:
                  internal_name = factory_name
              # The name allows components to know their pipe name and use it in the
              # losses etc. (even if multiple instances of the same factory are used)
              config = {"nlp": self, "name": name, **config, "@factories": internal_name}
              # We need to create a top-level key because Thinc doesn't allow resolving
              # top-level references to registered functions. Also gives nicer errors.
              cfg = {factory_name: config}
              # We're calling the internal _fill here to avoid constructing the
              # registered functions twice
              resolved = registry.resolve(cfg, validate=validate)
              filled = registry.fill({"cfg": cfg[factory_name]}, validate=validate)["cfg"]
              filled = Config(filled)
              filled["factory"] = factory_name
              filled.pop("@factories", None)
              # Remove the extra values we added because we don't want to keep passing
              # them around, copying them etc.
              filled.pop("nlp", None)
              filled.pop("name", None)
              # Merge the final filled config with the raw config (including non-
              # interpolated variables)
              if raw_config:
                  filled = filled.merge(raw_config)
              self._pipe_configs[name] = filled
              return resolved[factory_name]

          def create_pipe_from_source(
              self, source_name: str, source: "Language", *, name: str
          ) -> Tuple[PipeCallable, str]:
              """Create a pipeline component by copying it from an existing model.

              source_name (str): Name of the component in the source pipeline.
              source (Language): The source nlp object to copy from.
              name (str): Optional alternative name to use in current pipeline.
              RETURNS (Tuple[Callable[[Doc], Doc], str]): The component and its factory name.
              """
              # Check source type
              if not isinstance(source, Language):
                  raise ValueError(Errors.E945.format(name=source_name, source=type(source)))
              if self.vocab.vectors != source.vocab.vectors:
                  warnings.warn(Warnings.W113.format(name=source_name))
              if source_name not in source.component_names:
                  raise KeyError(
                      Errors.E944.format(
                          name=source_name,
                          model=f"{source.meta['lang']}_{source.meta['name']}",
                          opts=", ".join(source.component_names),
                      )
                  )
              pipe = source.get_pipe(source_name)
              # There is no actual solution here. Either the component has the right
              # name for the source pipeline or the component has the right name for
              # the current pipeline. This prioritizes the current pipeline.
              if hasattr(pipe, "name"):
                  pipe.name = name
              # Make sure the source config is interpolated so we don't end up with
              # orphaned variables in our final config
              source_config = source.config.interpolate()
              pipe_config = util.copy_config(source_config["components"][source_name])
              self._pipe_configs[name] = pipe_config
              if self.vocab.strings != source.vocab.strings:
                  for s in source.vocab.strings:
                      self.vocab.strings.add(s)
              return pipe, pipe_config["factory"]

          def add_pipe(
              self,
              factory_name: str,
              name: Optional[str] = None,
              *,
              before: Optional[Union[str, int]] = None,
              after: Optional[Union[str, int]] = None,
              first: Optional[bool] = None,
              last: Optional[bool] = None,
              source: Optional["Language"] = None,
              config: Dict[str, Any] = SimpleFrozenDict(),
              raw_config: Optional[Config] = None,
              validate: bool = True,
          ) -> PipeCallable:
              """Add a component to the processing pipeline. Valid components are
              callables that take a `Doc` object, modify it and return it. Only one
              of before/after/first/last can be set. Default behaviour is "last".

              factory_name (str): Name of the component factory.
              name (str): Name of pipeline component. Overwrites existing
                  component.name attribute if available. If no name is set and
                  the component exposes no name attribute, component.__name__ is
                  used. An error is raised if a name already exists in the pipeline.
              before (Union[str, int]): Name or index of the component to insert new
                  component directly before.
              after (Union[str, int]): Name or index of the component to insert new
                  component directly after.
              first (bool): If True, insert component first in the pipeline.
              last (bool): If True, insert component last in the pipeline.
              source (Language): Optional loaded nlp object to copy the pipeline
                  component from.
              config (Dict[str, Any]): Config parameters to use for this component.
                  Will be merged with default config, if available.
              raw_config (Optional[Config]): Internals: the non-interpolated config.
              validate (bool): Whether to validate the component config against the
                  arguments and types expected by the factory.
              RETURNS (Callable[[Doc], Doc]): The pipeline component.

              DOCS: https://spacy.io/api/language#add_pipe
              """
              if not isinstance(factory_name, str):
                  bad_val = repr(factory_name)
                  err = Errors.E966.format(component=bad_val, name=name)
                  raise ValueError(err)
              name = name if name is not None else factory_name
              if name in self.component_names:
                  raise ValueError(Errors.E007.format(name=name, opts=self.component_names))
              # Overriding pipe name in the config is not supported and will be ignored.
              if "name" in config:
                  warnings.warn(Warnings.W119.format(name_in_config=config.pop("name")))
              if source is not None:
                  # We're loading the component from a model. After loading the
                  # component, we know its real factory name
                  pipe_component, factory_name = self.create_pipe_from_source(
                      factory_name, source, name=name
                  )
              else:
                  pipe_component = self.create_pipe(
                      factory_name,
                      name=name,
                      config=config,
                      raw_config=raw_config,
                      validate=validate,
                  )
              pipe_index = self._get_pipe_index(before, after, first, last)
              self._pipe_meta[name] = self.get_factory_meta(factory_name)
              self._components.insert(pipe_index, (name, pipe_component))
              self._link_components()
              return pipe_component

          def _get_pipe_index(
              self,
              before: Optional[Union[str, int]] = None,
              after: Optional[Union[str, int]] = None,
              first: Optional[bool] = None,
              last: Optional[bool] = None,
          ) -> int:
              """Determine where to insert a pipeline component based on the before/
              after/first/last values.

              before (str): Name or index of the component to insert directly before.
              after (str): Name or index of component to insert directly after.
              first (bool): If True, insert component first in the pipeline.
              last (bool): If True, insert component last in the pipeline.
              RETURNS (int): The index of the new pipeline component.
              """
              all_args = {"before": before, "after": after, "first": first, "last": last}
              if sum(arg is not None for arg in [before, after, first, last]) >= 2:
                  raise ValueError(
                      Errors.E006.format(args=all_args, opts=self.component_names)
                  )
              if last or not any(value is not None for value in [first, before, after]):
                  return len(self._components)
              elif first:
                  return 0
              elif isinstance(before, str):
                  if before not in self.component_names:
                      raise ValueError(
                          Errors.E001.format(name=before, opts=self.component_names)
                      )
                  return self.component_names.index(before)
              elif isinstance(after, str):
                  if after not in self.component_names:
                      raise ValueError(
                          Errors.E001.format(name=after, opts=self.component_names)
                      )
                  return self.component_names.index(after) + 1
              # We're only accepting indices referring to components that exist
              # (can't just do isinstance here because bools are instance of int, too)
              elif type(before) == int:
                  if before >= len(self._components) or before < 0:
                      err = Errors.E959.format(
                          dir="before", idx=before, opts=self.component_names
                      )
                      raise ValueError(err)
                  return before
              elif type(after) == int:
                  if after >= len(self._components) or after < 0:
                      err = Errors.E959.format(
                          dir="after", idx=after, opts=self.component_names
                      )
                      raise ValueError(err)
                  return after + 1
              raise ValueError(Errors.E006.format(args=all_args, opts=self.component_names))

          def has_pipe(self, name: str) -> bool:
              """Check if a component name is present in the pipeline. Equivalent to
              `name in nlp.pipe_names`.

              name (str): Name of the component.
              RETURNS (bool): Whether a component of the name exists in the pipeline.

              DOCS: https://spacy.io/api/language#has_pipe
              """
              return name in self.pipe_names

          def replace_pipe(
              self,
              name: str,
              factory_name: str,
              *,
              config: Dict[str, Any] = SimpleFrozenDict(),
              validate: bool = True,
          ) -> PipeCallable:
              """Replace a component in the pipeline.

              name (str): Name of the component to replace.
              factory_name (str): Factory name of replacement component.
              config (Optional[Dict[str, Any]]): Config parameters to use for this
                  component. Will be merged with default config, if available.
              validate (bool): Whether to validate the component config against the
                  arguments and types expected by the factory.
              RETURNS (Callable[[Doc], Doc]): The new pipeline component.

              DOCS: https://spacy.io/api/language#replace_pipe
              """
              if name not in self.component_names:
                  raise ValueError(Errors.E001.format(name=name, opts=self.pipe_names))
              if hasattr(factory_name, "__call__"):
                  err = Errors.E968.format(component=repr(factory_name), name=name)
                  raise ValueError(err)
              # We need to delegate to Language.add_pipe here instead of just writing
              # to Language.pipeline to make sure the configs are handled correctly
              pipe_index = self.component_names.index(name)
              self.remove_pipe(name)
              if not len(self._components) or pipe_index == len(self._components):
                  # we have no components to insert before/after, or we're replacing the last component
                  return self.add_pipe(
                      factory_name, name=name, config=config, validate=validate
                  )
              else:
                  return self.add_pipe(
                      factory_name,
                      name=name,
                      before=pipe_index,
                      config=config,
                      validate=validate,
                  )

          def rename_pipe(self, old_name: str, new_name: str) -> None:
              """Rename a pipeline component.

              old_name (str): Name of the component to rename.
              new_name (str): New name of the component.

              DOCS: https://spacy.io/api/language#rename_pipe
              """
              if old_name not in self.component_names:
                  raise ValueError(
                      Errors.E001.format(name=old_name, opts=self.component_names)
                  )
              if new_name in self.component_names:
                  raise ValueError(
                      Errors.E007.format(name=new_name, opts=self.component_names)
                  )
              i = self.component_names.index(old_name)
              self._components[i] = (new_name, self._components[i][1])
              self._pipe_meta[new_name] = self._pipe_meta.pop(old_name)
              self._pipe_configs[new_name] = self._pipe_configs.pop(old_name)
              # Make sure [initialize] config is adjusted
              if old_name in self._config["initialize"]["components"]:
                  init_cfg = self._config["initialize"]["components"].pop(old_name)
                  self._config["initialize"]["components"][new_name] = init_cfg
              self._link_components()

          def remove_pipe(self, name: str) -> Tuple[str, PipeCallable]:
              """Remove a component from the pipeline.

              name (str): Name of the component to remove.
              RETURNS (Tuple[str, Callable[[Doc], Doc]]): A `(name, component)` tuple of the removed component.

              DOCS: https://spacy.io/api/language#remove_pipe
              """
              if name not in self.component_names:
                  raise ValueError(Errors.E001.format(name=name, opts=self.component_names))
              removed = self._components.pop(self.component_names.index(name))
              # We're only removing the component itself from the metas/configs here
              # because factory may be used for something else
              self._pipe_meta.pop(name)
              self._pipe_configs.pop(name)
              self.meta.get("_sourced_vectors_hashes", {}).pop(name, None)
              # Make sure name is removed from the [initialize] config
              if name in self._config["initialize"]["components"]:
                  self._config["initialize"]["components"].pop(name)
              # Make sure the name is also removed from the set of disabled components
              if name in self.disabled:
                  self._disabled.remove(name)
              self._link_components()
              return removed

          def disable_pipe(self, name: str) -> None:
              """Disable a pipeline component. The component will still exist on
              the nlp object, but it won't be run as part of the pipeline. Does
              nothing if the component is already disabled.

              name (str): The name of the component to disable.
              """
              if name not in self.component_names:
                  raise ValueError(Errors.E001.format(name=name, opts=self.component_names))
              self._disabled.add(name)

          def enable_pipe(self, name: str) -> None:
              """Enable a previously disabled pipeline component so it's run as part
              of the pipeline. Does nothing if the component is already enabled.

              name (str): The name of the component to enable.
              """
              if name not in self.component_names:
                  raise ValueError(Errors.E001.format(name=name, opts=self.component_names))
              if name in self.disabled:
                  self._disabled.remove(name)

          def __call__(
              self,
              text: Union[str, Doc],
              *,
              disable: Iterable[str] = SimpleFrozenList(),
              component_cfg: Optional[Dict[str, Dict[str, Any]]] = None,
          ) -> Doc:
              """Apply the pipeline to some text. The text can span multiple sentences,
              and can contain arbitrary whitespace. Alignment into the original string
              is preserved.

              text (Union[str, Doc]): If `str`, the text to be processed. If `Doc`,
                  the doc will be passed directly to the pipeline, skipping
                  `Language.make_doc`.
              disable (List[str]): Names of the pipeline components to disable.
              component_cfg (Dict[str, dict]): An optional dictionary with extra
                  keyword arguments for specific components.
              RETURNS (Doc): A container for accessing the annotations.

              DOCS: https://spacy.io/api/language#call
              """
              doc = self._ensure_doc(text)
              if component_cfg is None:
                  component_cfg = {}
              for name, proc in self.pipeline:
                  if name in disable:
                      continue
                  if not hasattr(proc, "__call__"):
                      raise ValueError(Errors.E003.format(component=type(proc), name=name))
                  error_handler = self.default_error_handler
                  if hasattr(proc, "get_error_handler"):
                      error_handler = proc.get_error_handler()
                  try:
                      doc = proc(doc, **component_cfg.get(name, {}))  # type: ignore[call-arg]
                  except KeyError as e:
                      # This typically happens if a component is not initialized
                      raise ValueError(Errors.E109.format(name=name)) from e
                  except Exception as e:
                      error_handler(name, proc, [doc], e)
                  if not isinstance(doc, Doc):
                      raise ValueError(Errors.E005.format(name=name, returned_type=type(doc)))
              return doc

          def disable_pipes(self, *names) -> "DisabledPipes":
              """Disable one or more pipeline components. If used as a context
              manager, the pipeline will be restored to the initial state at the end
              of the block. Otherwise, a DisabledPipes object is returned, that has
              a `.restore()` method you can use to undo your changes.

              This method has been deprecated since 3.0
              """
              warnings.warn(Warnings.W096, DeprecationWarning)
              if len(names) == 1 and isinstance(names[0], (list, tuple)):
                  names = names[0]  # type: ignore[assignment]    # support list of names instead of spread
              return self.select_pipes(disable=names)

          def select_pipes(
              self,
              *,
              disable: Optional[Union[str, Iterable[str]]] = None,
              enable: Optional[Union[str, Iterable[str]]] = None,
          ) -> "DisabledPipes":
              """Disable one or more pipeline components. If used as a context
              manager, the pipeline will be restored to the initial state at the end
              of the block. Otherwise, a DisabledPipes object is returned, that has
              a `.restore()` method you can use to undo your changes.

              disable (str or iterable): The name(s) of the pipes to disable
              enable (str or iterable): The name(s) of the pipes to enable - all others will be disabled

              DOCS: https://spacy.io/api/language#select_pipes
              """
              if enable is None and disable is None:
                  raise ValueError(Errors.E991)
              if isinstance(disable, str):
                  disable = [disable]
              if enable is not None:
                  if isinstance(enable, str):
                      enable = [enable]
                  to_disable = [pipe for pipe in self.pipe_names if pipe not in enable]
                  # raise an error if the enable and disable keywords are not consistent
                  if disable is not None and disable != to_disable:
                      raise ValueError(
                          Errors.E992.format(
                              enable=enable, disable=disable, names=self.pipe_names
                          )
                      )
                  disable = to_disable
              assert disable is not None
              # DisabledPipes will restore the pipes in 'disable' when it's done, so we need to exclude
              # those pipes that were already disabled.
              disable = [d for d in disable if d not in self._disabled]
              return DisabledPipes(self, disable)

          def make_doc(self, text: str) -> Doc:
              """Turn a text into a Doc object.

              text (str): The text to process.
              RETURNS (Doc): The processed doc.
              """
              if len(text) > self.max_length:
                  raise ValueError(
                      Errors.E088.format(length=len(text), max_length=self.max_length)
                  )
              return self.tokenizer(text)

          def _ensure_doc(self, doc_like: Union[str, Doc, bytes]) -> Doc:
              """Create a Doc if need be, or raise an error if the input is not
              a Doc, string, or a byte array (generated by Doc.to_bytes())."""
              if isinstance(doc_like, Doc):
                  return doc_like
              if isinstance(doc_like, str):
                  return self.make_doc(doc_like)
              if isinstance(doc_like, bytes):
                  return Doc(self.vocab).from_bytes(doc_like)
              raise ValueError(Errors.E1041.format(type=type(doc_like)))

          def _ensure_doc_with_context(
              self, doc_like: Union[str, Doc, bytes], context: _AnyContext
          ) -> Doc:
              """Call _ensure_doc to generate a Doc and set its context object."""
              doc = self._ensure_doc(doc_like)
              doc._context = context
              return doc

          def update(
              self,
              examples: Iterable[Example],
              _: Optional[Any] = None,
              *,
              drop: float = 0.0,
              sgd: Optional[Optimizer] = None,
              losses: Optional[Dict[str, float]] = None,
              component_cfg: Optional[Dict[str, Dict[str, Any]]] = None,
              exclude: Iterable[str] = SimpleFrozenList(),
              annotates: Iterable[str] = SimpleFrozenList(),
          ):
              """Update the models in the pipeline.

              examples (Iterable[Example]): A batch of examples
              _: Should not be set - serves to catch backwards-incompatible scripts.
              drop (float): The dropout rate.
              sgd (Optimizer): An optimizer.
              losses (Dict[str, float]): Dictionary to update with the loss, keyed by
                  component.
              component_cfg (Dict[str, Dict]): Config parameters for specific pipeline
                  components, keyed by component name.
              exclude (Iterable[str]): Names of components that shouldn't be updated.
              annotates (Iterable[str]): Names of components that should set
                  annotations on the predicted examples after updating.
              RETURNS (Dict[str, float]): The updated losses dictionary

              DOCS: https://spacy.io/api/language#update
              """
              if _ is not None:
                  raise ValueError(Errors.E989)
              if losses is None:
                  losses = {}
              if isinstance(examples, list) and len(examples) == 0:
                  return losses
              validate_examples(examples, "Language.update")
              examples = _copy_examples(examples)
              if sgd is None:
                  if self._optimizer is None:
                      self._optimizer = self.create_optimizer()
                  sgd = self._optimizer
              if component_cfg is None:
                  component_cfg = {}
              pipe_kwargs = {}
              for i, (name, proc) in enumerate(self.pipeline):
                  component_cfg.setdefault(name, {})
                  pipe_kwargs[name] = deepcopy(component_cfg[name])
                  component_cfg[name].setdefault("drop", drop)
                  pipe_kwargs[name].setdefault("batch_size", self.batch_size)
              for name, proc in self.pipeline:
                  # ignore statements are used here because mypy ignores hasattr
                  if name not in exclude and hasattr(proc, "update"):
                      proc.update(examples, sgd=None, losses=losses, **component_cfg[name])  # type: ignore
                  if sgd not in (None, False):
                      if (
                          name not in exclude
                          and isinstance(proc, ty.TrainableComponent)
                          and proc.is_trainable
                          and proc.model not in (True, False, None)
                      ):
                          proc.finish_update(sgd)
                  if name in annotates:
                      for doc, eg in zip(
                          _pipe(
                              (eg.predicted for eg in examples),
                              proc=proc,
                              name=name,
                              default_error_handler=self.default_error_handler,
                              kwargs=pipe_kwargs[name],
                          ),
                          examples,
                      ):
                          eg.predicted = doc
              return _replace_numpy_floats(losses)

          def rehearse(
              self,
              examples: Iterable[Example],
              *,
              sgd: Optional[Optimizer] = None,
              losses: Optional[Dict[str, float]] = None,
              component_cfg: Optional[Dict[str, Dict[str, Any]]] = None,
              exclude: Iterable[str] = SimpleFrozenList(),
          ) -> Dict[str, float]:
              """Make a "rehearsal" update to the models in the pipeline, to prevent
              forgetting. Rehearsal updates run an initial copy of the model over some
              data, and update the model so its current predictions are more like the
              initial ones. This is useful for keeping a pretrained model on-track,
              even if you're updating it with a smaller set of examples.

              examples (Iterable[Example]): A batch of `Example` objects.
              sgd (Optional[Optimizer]): An optimizer.
              component_cfg (Dict[str, Dict]): Config parameters for specific pipeline
                  components, keyed by component name.
              exclude (Iterable[str]): Names of components that shouldn't be updated.
              RETURNS (dict): Results from the update.

              EXAMPLE:
                  >>> raw_text_batches = minibatch(raw_texts)
                  >>> for labelled_batch in minibatch(examples):
                  >>>     nlp.update(labelled_batch)
                  >>>     raw_batch = [Example.from_dict(nlp.make_doc(text), {}) for text in next(raw_text_batches)]
                  >>>     nlp.rehearse(raw_batch)

              DOCS: https://spacy.io/api/language#rehearse
              """
              if losses is None:
                  losses = {}
              if isinstance(examples, list) and len(examples) == 0:
                  return losses
              validate_examples(examples, "Language.rehearse")
              if sgd is None:
                  if self._optimizer is None:
                      self._optimizer = self.create_optimizer()
                  sgd = self._optimizer
              pipes = list(self.pipeline)
              random.shuffle(pipes)
              if component_cfg is None:
                  component_cfg = {}
              grads = {}

              def get_grads(key, W, dW):
                  grads[key] = (W, dW)
                  return W, dW

              get_grads.learn_rate = sgd.learn_rate  # type: ignore[attr-defined, union-attr]
              get_grads.b1 = sgd.b1  # type: ignore[attr-defined, union-attr]
              get_grads.b2 = sgd.b2  # type: ignore[attr-defined, union-attr]
              for name, proc in pipes:
                  if name in exclude or not hasattr(proc, "rehearse"):
                      continue
                  grads = {}
                  proc.rehearse(  # type: ignore[attr-defined]
                      examples, sgd=get_grads, losses=losses, **component_cfg.get(name, {})
                  )
              for key, (W, dW) in grads.items():
                  sgd(key, W, dW)  # type: ignore[call-arg, misc]
              return losses

          def begin_training(
              self,
              get_examples: Optional[Callable[[], Iterable[Example]]] = None,
              *,
              sgd: Optional[Optimizer] = None,
          ) -> Optimizer:
              warnings.warn(Warnings.W089, DeprecationWarning)
              return self.initialize(get_examples, sgd=sgd)

          def initialize(
              self,
              get_examples: Optional[Callable[[], Iterable[Example]]] = None,
              *,
              sgd: Optional[Optimizer] = None,
          ) -> Optimizer:
              """Initialize the pipe for training, using data examples if available.

              get_examples (Callable[[], Iterable[Example]]): Optional function that
                  returns gold-standard Example objects.
              sgd (Optional[Optimizer]): An optimizer to use for updates. If not
                  provided, will be created using the .create_optimizer() method.
              RETURNS (thinc.api.Optimizer): The optimizer.

              DOCS: https://spacy.io/api/language#initialize
              """
              if get_examples is None:
                  util.logger.debug(
                      "No 'get_examples' callback provided to 'Language.initialize', creating dummy examples"
                  )
                  doc = Doc(self.vocab, words=["x", "y", "z"])

                  def get_examples():
                      return [Example.from_dict(doc, {})]

              if not hasattr(get_examples, "__call__"):
                  err = Errors.E930.format(
                      method="Language.initialize", obj=type(get_examples)
                  )
                  raise TypeError(err)
              # Make sure the config is interpolated so we can resolve subsections
              config = self.config.interpolate()
              # These are the settings provided in the [initialize] block in the config
              I = registry.resolve(config["initialize"], schema=ConfigSchemaInit)
              before_init = I["before_init"]
              if before_init is not None:
                  before_init(self)
              try:
                  init_vocab(
                      self, data=I["vocab_data"], lookups=I["lookups"], vectors=I["vectors"]
                  )
              except IOError:
                  raise IOError(Errors.E884.format(vectors=I["vectors"]))
              if self.vocab.vectors.shape[1] >= 1:
                  ops = get_current_ops()
                  self.vocab.vectors.to_ops(ops)
              if hasattr(self.tokenizer, "initialize"):
                  tok_settings = validate_init_settings(
                      self.tokenizer.initialize,  # type: ignore[union-attr]
                      I["tokenizer"],
                      section="tokenizer",
                      name="tokenizer",
                  )
                  self.tokenizer.initialize(get_examples, nlp=self, **tok_settings)  # type: ignore[union-attr]
              for name, proc in self.pipeline:
                  if isinstance(proc, ty.InitializableComponent):
                      p_settings = I["components"].get(name, {})
                      p_settings = validate_init_settings(
                          proc.initialize, p_settings, section="components", name=name
                      )
                      proc.initialize(get_examples, nlp=self, **p_settings)
              pretrain_cfg = config.get("pretraining")
              if pretrain_cfg:
                  P = registry.resolve(pretrain_cfg, schema=ConfigSchemaPretrain)
                  init_tok2vec(self, P, I)
              self._link_components()
              self._optimizer = sgd
              if sgd is not None:
                  self._optimizer = sgd
              elif self._optimizer is None:
                  self._optimizer = self.create_optimizer()
              after_init = I["after_init"]
              if after_init is not None:
                  after_init(self)
              return self._optimizer

          def resume_training(self, *, sgd: Optional[Optimizer] = None) -> Optimizer:
              """Continue training a pretrained model.

              Create and return an optimizer, and initialize "rehearsal" for any pipeline
              component that has a .rehearse() method. Rehearsal is used to prevent
              models from "forgetting" their initialized "knowledge". To perform
              rehearsal, collect samples of text you want the models to retain performance
              on, and call nlp.rehearse() with a batch of Example objects.

              RETURNS (Optimizer): The optimizer.

              DOCS: https://spacy.io/api/language#resume_training
              """
              ops = get_current_ops()
              if self.vocab.vectors.shape[1] >= 1:
                  self.vocab.vectors.to_ops(ops)
              for name, proc in self.pipeline:
                  if hasattr(proc, "_rehearsal_model"):
                      proc._rehearsal_model = deepcopy(proc.model)  # type: ignore[attr-defined]
              if sgd is not None:
                  self._optimizer = sgd
              elif self._optimizer is None:
                  self._optimizer = self.create_optimizer()
              return self._optimizer

          def set_error_handler(
              self,
              error_handler: Callable[[str, PipeCallable, List[Doc], Exception], NoReturn],
          ):
              """Set an error handler object for all the components in the pipeline
              that implement a set_error_handler function.

              error_handler (Callable[[str, Callable[[Doc], Doc], List[Doc], Exception], NoReturn]):
                  Function that deals with a failing batch of documents. This callable
                  function should take in the component's name, the component itself,
                  the offending batch of documents, and the exception that was thrown.
              DOCS: https://spacy.io/api/language#set_error_handler
              """
              self.default_error_handler = error_handler
              for name, pipe in self.pipeline:
                  if hasattr(pipe, "set_error_handler"):
                      pipe.set_error_handler(error_handler)

          def evaluate(
              self,
              examples: Iterable[Example],
              *,
              batch_size: Optional[int] = None,
              scorer: Optional[Scorer] = None,
              component_cfg: Optional[Dict[str, Dict[str, Any]]] = None,
              scorer_cfg: Optional[Dict[str, Any]] = None,
              per_component: bool = False,
          ) -> Dict[str, Any]:
              """Evaluate a model's pipeline components.

              examples (Iterable[Example]): `Example` objects.
              batch_size (Optional[int]): Batch size to use.
              scorer (Optional[Scorer]): Scorer to use. If not passed in, a new one
                  will be created.
              component_cfg (dict): An optional dictionary with extra keyword
                  arguments for specific components.
              scorer_cfg (dict): An optional dictionary with extra keyword arguments
                  for the scorer.
              per_component (bool): Whether to return the scores keyed by component
                  name. Defaults to False.

              RETURNS (Scorer): The scorer containing the evaluation results.

              DOCS: https://spacy.io/api/language#evaluate
              """
              examples = list(examples)
              validate_examples(examples, "Language.evaluate")
              examples = _copy_examples(examples)
              if batch_size is None:
                  batch_size = self.batch_size
              if component_cfg is None:
                  component_cfg = {}
              if scorer_cfg is None:
                  scorer_cfg = {}
              if scorer is None:
                  kwargs = dict(scorer_cfg)
                  kwargs.setdefault("nlp", self)
                  scorer = Scorer(**kwargs)
              # reset annotation in predicted docs and time tokenization
              start_time = timer()
              # this is purely for timing
              for eg in examples:
                  self.make_doc(eg.reference.text)
              # apply all pipeline components
              docs = self.pipe(
                  (eg.predicted for eg in examples),
                  batch_size=batch_size,
                  component_cfg=component_cfg,
              )
              for eg, doc in zip(examples, docs):
                  eg.predicted = doc
              end_time = timer()
              results = scorer.score(examples, per_component=per_component)
              n_words = sum(len(eg.predicted) for eg in examples)
              results["speed"] = n_words / (end_time - start_time)
              return _replace_numpy_floats(results)

          def create_optimizer(self):
              """Create an optimizer, usually using the [training.optimizer] config."""
              subconfig = {"optimizer": self.config["training"]["optimizer"]}
              return registry.resolve(subconfig)["optimizer"]

          @contextmanager
          def use_params(self, params: Optional[dict]):
              """Replace weights of models in the pipeline with those provided in the
              params dictionary. Can be used as a contextmanager, in which case,
              models go back to their original weights after the block.

              params (dict): A dictionary of parameters keyed by model ID.

              EXAMPLE:
                  >>> with nlp.use_params(optimizer.averages):
                  >>>     nlp.to_disk("/tmp/checkpoint")

              DOCS: https://spacy.io/api/language#use_params
              """
              if not params:
                  yield
              else:
                  contexts = [
                      pipe.use_params(params)  # type: ignore[attr-defined]
                      for name, pipe in self.pipeline
                      if hasattr(pipe, "use_params") and hasattr(pipe, "model")
                  ]
                  # TODO: Having trouble with contextlib
                  # Workaround: these aren't actually context managers atm.
                  for context in contexts:
                      try:
                          next(context)
                      except StopIteration:
                          pass
                  yield
                  for context in contexts:
                      try:
                          next(context)
                      except StopIteration:
                          pass

          @overload
          def pipe(
              self,
              texts: Iterable[Union[str, Doc]],
              *,
              as_tuples: Literal[False] = ...,
              batch_size: Optional[int] = ...,
              disable: Iterable[str] = ...,
              component_cfg: Optional[Dict[str, Dict[str, Any]]] = ...,
              n_process: int = ...,
          ) -> Iterator[Doc]:
              ...

          @overload
          def pipe(  # noqa: F811
              self,
              texts: Iterable[Tuple[Union[str, Doc], _AnyContext]],
              *,
              as_tuples: Literal[True] = ...,
              batch_size: Optional[int] = ...,
              disable: Iterable[str] = ...,
              component_cfg: Optional[Dict[str, Dict[str, Any]]] = ...,
              n_process: int = ...,
          ) -> Iterator[Tuple[Doc, _AnyContext]]:
              ...

          def pipe(  # noqa: F811
              self,
              texts: Union[
                  Iterable[Union[str, Doc]], Iterable[Tuple[Union[str, Doc], _AnyContext]]
              ],
              *,
              as_tuples: bool = False,
              batch_size: Optional[int] = None,
              disable: Iterable[str] = SimpleFrozenList(),
              component_cfg: Optional[Dict[str, Dict[str, Any]]] = None,
              n_process: int = 1,
          ) -> Union[Iterator[Doc], Iterator[Tuple[Doc, _AnyContext]]]:
              """Process texts as a stream, and yield `Doc` objects in order.

              texts (Iterable[Union[str, Doc]]): A sequence of texts or docs to
                  process.
              as_tuples (bool): If set to True, inputs should be a sequence of
                  (text, context) tuples. Output will then be a sequence of
                  (doc, context) tuples. Defaults to False.
              batch_size (Optional[int]): The number of texts to buffer.
              disable (List[str]): Names of the pipeline components to disable.
              component_cfg (Dict[str, Dict]): An optional dictionary with extra keyword
                  arguments for specific components.
              n_process (int): Number of processors to process texts. If -1, set `multiprocessing.cpu_count()`.
              YIELDS (Doc): Documents in the order of the original text.

              DOCS: https://spacy.io/api/language#pipe
              """
              if as_tuples:
                  texts = cast(Iterable[Tuple[Union[str, Doc], _AnyContext]], texts)
                  docs_with_contexts = (
                      self._ensure_doc_with_context(text, context) for text, context in texts
                  )
                  docs = self.pipe(
                      docs_with_contexts,
                      batch_size=batch_size,
                      disable=disable,
                      n_process=n_process,
                      component_cfg=component_cfg,
                  )
                  for doc in docs:
                      context = doc._context
                      doc._context = None
                      yield (doc, context)
                  return

              texts = cast(Iterable[Union[str, Doc]], texts)

              # Set argument defaults
              if n_process == -1:
                  n_process = mp.cpu_count()
              if component_cfg is None:
                  component_cfg = {}
              if batch_size is None:
                  batch_size = self.batch_size

              pipes = (
                  []
              )  # contains functools.partial objects to easily create multiprocess worker.
              for name, proc in self.pipeline:
                  if name in disable:
                      continue
                  kwargs = component_cfg.get(name, {})
                  # Allow component_cfg to overwrite the top-level kwargs.
                  kwargs.setdefault("batch_size", batch_size)
                  f = functools.partial(
                      _pipe,
                      proc=proc,
                      name=name,
                      kwargs=kwargs,
                      default_error_handler=self.default_error_handler,
                  )
                  pipes.append(f)

              if n_process != 1:
                  if self._has_gpu_model(disable):
                      warnings.warn(Warnings.W114)

                  docs = self._multiprocessing_pipe(texts, pipes, n_process, batch_size)
              else:
                  # if n_process == 1, no processes are forked.
                  docs = (self._ensure_doc(text) for text in texts)
                  for pipe in pipes:
                      docs = pipe(docs)
              for doc in docs:
                  yield doc

          def _has_gpu_model(self, disable: Iterable[str]):
              for name, proc in self.pipeline:
                  is_trainable = hasattr(proc, "is_trainable") and proc.is_trainable  # type: ignore
                  if name in disable or not is_trainable:
                      continue

                  if hasattr(proc, "model") and hasattr(proc.model, "ops") and isinstance(proc.model.ops, CupyOps):  # type: ignore
                      return True

              return False

          def _multiprocessing_pipe(
              self,
              texts: Iterable[Union[str, Doc]],
              pipes: Iterable[Callable[..., Iterator[Doc]]],
              n_process: int,
              batch_size: int,
          ) -> Iterator[Doc]:
              def prepare_input(
                  texts: Iterable[Union[str, Doc]]
              ) -> Iterable[Tuple[Union[str, bytes], _AnyContext]]:
                  # Serialize Doc inputs to bytes to avoid incurring pickling
                  # overhead when they are passed to child processes. Also yield
                  # any context objects they might have separately (as they are not serialized).
                  for doc_like in texts:
                      if isinstance(doc_like, Doc):
                          yield (doc_like.to_bytes(), cast(_AnyContext, doc_like._context))
                      else:
                          yield (doc_like, cast(_AnyContext, None))

              serialized_texts_with_ctx = prepare_input(texts)  # type: ignore
              # raw_texts is used later to stop iteration.
              texts, raw_texts = itertools.tee(serialized_texts_with_ctx)  # type: ignore
              # for sending texts to worker
              texts_q: List[mp.Queue] = [mp.Queue() for _ in range(n_process)]
              # for receiving byte-encoded docs from worker
              bytedocs_recv_ch, bytedocs_send_ch = zip(
                  *[mp.Pipe(False) for _ in range(n_process)]
              )

              batch_texts = util.minibatch(texts, batch_size)
              # Sender sends texts to the workers.
              # This is necessary to properly handle infinite length of texts.
              # (In this case, all data cannot be sent to the workers at once)
              sender = _Sender(batch_texts, texts_q, chunk_size=n_process)
              # send twice to make process busy
              sender.send()
              sender.send()

              procs = [
                  mp.Process(
                      target=_apply_pipes,
                      args=(
                          self._ensure_doc_with_context,
                          pipes,
                          rch,
                          sch,
                          Underscore.get_state(),
                      ),
                  )
                  for rch, sch in zip(texts_q, bytedocs_send_ch)
              ]
              for proc in procs:
                  proc.start()

              # Close writing-end of channels. This is needed to avoid that reading
              # from the channel blocks indefinitely when the worker closes the
              # channel.
              for tx in bytedocs_send_ch:
                  tx.close()

              # Cycle channels not to break the order of docs.
              # The received object is a batch of byte-encoded docs, so flatten them with chain.from_iterable.
              byte_tuples = chain.from_iterable(
                  recv.recv() for recv in cycle(bytedocs_recv_ch)
              )
              try:
                  for i, (_, (byte_doc, context, byte_error)) in enumerate(
                      zip(raw_texts, byte_tuples), 1
                  ):
                      if byte_doc is not None:
                          doc = Doc(self.vocab).from_bytes(byte_doc)
                          doc._context = context
                          yield doc
                      elif byte_error is not None:
                          error = srsly.msgpack_loads(byte_error)
                          self.default_error_handler(
                              None, None, None, ValueError(Errors.E871.format(error=error))
                          )
                      if i % batch_size == 0:
                          # tell `sender` that one batch was consumed.
                          sender.step()
              finally:
                  # If we are stopping in an orderly fashion, the workers' queues
                  # are empty. Put the sentinel in their queues to signal that work
                  # is done, so that they can exit gracefully.
                  for q in texts_q:
                      q.put(_WORK_DONE_SENTINEL)
                      q.close()

                  # Otherwise, we are stopping because the error handler raised an
                  # exception. The sentinel will be last to go out of the queue.
                  # To avoid doing unnecessary work or hanging on platforms that
                  # block on sending (Windows), we'll close our end of the channel.
                  # This signals to the worker that it can exit the next time it
                  # attempts to send data down the channel.
                  for r in bytedocs_recv_ch:
                      r.close()

                  for proc in procs:
                      proc.join()

                  if not all(proc.exitcode == 0 for proc in procs):
                      warnings.warn(Warnings.W127)

          def _link_components(self) -> None:
              """Register 'listeners' within pipeline components, to allow them to
              effectively share weights.
              """
              # I had thought, "Why do we do this inside the Language object? Shouldn't
              # it be the tok2vec/transformer/etc's job?
              # The problem is we need to do it during deserialization...And the
              # components don't receive the pipeline then. So this does have to be
              # here :(
              # First, fix up all the internal component names in case they have
              # gotten out of sync due to sourcing components from different
              # pipelines, since find_listeners uses proc2.name for the listener
              # map.
              for name, proc in self.pipeline:
                  if hasattr(proc, "name"):
                      proc.name = name
              for i, (name1, proc1) in enumerate(self.pipeline):
                  if isinstance(proc1, ty.ListenedToComponent):
                      proc1.listener_map = {}
                      for name2, proc2 in self.pipeline[i + 1 :]:
                          proc1.find_listeners(proc2)

          @classmethod
          def from_config(
              cls,
              config: Union[Dict[str, Any], Config] = {},
              *,
              vocab: Union[Vocab, bool] = True,
              disable: Union[str, Iterable[str]] = _DEFAULT_EMPTY_PIPES,
              enable: Union[str, Iterable[str]] = _DEFAULT_EMPTY_PIPES,
              exclude: Union[str, Iterable[str]] = _DEFAULT_EMPTY_PIPES,
              meta: Dict[str, Any] = SimpleFrozenDict(),
              auto_fill: bool = True,
              validate: bool = True,
          ) -> "Language":
              """Create the nlp object from a loaded config. Will set up the tokenizer
              and language data, add pipeline components etc. If no config is provided,
              the default config of the given language is used.

              config (Dict[str, Any] / Config): The loaded config.
              vocab (Vocab): A Vocab object. If True, a vocab is created.
              disable (Union[str, Iterable[str]]): Name(s) of pipeline component(s) to disable.
                  Disabled pipes will be loaded but they won't be run unless you
                  explicitly enable them by calling nlp.enable_pipe.
              enable (Union[str, Iterable[str]]): Name(s) of pipeline component(s) to enable. All other
                  pipes will be disabled (and can be enabled using `nlp.enable_pipe`).
              exclude (Union[str, Iterable[str]]): Name(s) of pipeline component(s) to exclude.
                  Excluded components won't be loaded.
              meta (Dict[str, Any]): Meta overrides for nlp.meta.
              auto_fill (bool): Automatically fill in missing values in config based
                  on defaults and function argument annotations.
              validate (bool): Validate the component config and arguments against
                  the types expected by the factory.
              RETURNS (Language): The initialized Language class.

              DOCS: https://spacy.io/api/language#from_config
              """
              if auto_fill:
                  config = Config(
                      cls.default_config, section_order=CONFIG_SECTION_ORDER
                  ).merge(config)
              if "nlp" not in config:
                  raise ValueError(Errors.E985.format(config=config))
              # fill in [nlp.vectors] if not present (as a narrower alternative to
              # auto-filling [nlp] from the default config)
              if "vectors" not in config["nlp"]:
                  config["nlp"]["vectors"] = {"@vectors": "spacy.Vectors.v1"}
              config_lang = config["nlp"].get("lang")
              if config_lang is not None and config_lang != cls.lang:
                  raise ValueError(
                      Errors.E958.format(
                          bad_lang_code=config["nlp"]["lang"],
                          lang_code=cls.lang,
                          lang=util.get_object_name(cls),
                      )
                  )
              config["nlp"]["lang"] = cls.lang
              # This isn't very elegant, but we remove the [components] block here to prevent
              # it from getting resolved (causes problems because we expect to pass in
              # the nlp and name args for each component). If we're auto-filling, we're
              # using the nlp.config with all defaults.
              config = util.copy_config(config)
              orig_pipeline = config.pop("components", {})
              orig_pretraining = config.pop("pretraining", None)
              config["components"] = {}
              if auto_fill:
                  filled = registry.fill(config, validate=validate, schema=ConfigSchema)
              else:
                  filled = config
              filled["components"] = orig_pipeline
              config["components"] = orig_pipeline
              if orig_pretraining is not None:
                  filled["pretraining"] = orig_pretraining
                  config["pretraining"] = orig_pretraining
              resolved_nlp = registry.resolve(
                  filled["nlp"], validate=validate, schema=ConfigSchemaNlp
              )
              create_tokenizer = resolved_nlp["tokenizer"]
              create_vectors = resolved_nlp["vectors"]
              before_creation = resolved_nlp["before_creation"]
              after_creation = resolved_nlp["after_creation"]
              after_pipeline_creation = resolved_nlp["after_pipeline_creation"]
              lang_cls = cls
              if before_creation is not None:
                  lang_cls = before_creation(cls)
                  if (
                      not isinstance(lang_cls, type)
                      or not issubclass(lang_cls, cls)
                      or lang_cls is not cls
                  ):
                      raise ValueError(Errors.E943.format(value=type(lang_cls)))

              # Warn about require_gpu usage in jupyter notebook
              warn_if_jupyter_cupy()

              # Note that we don't load vectors here, instead they get loaded explicitly
              # inside stuff like the spacy train function. If we loaded them here,
              # then we would load them twice at runtime: once when we make from config,
              # and then again when we load from disk.
              nlp = lang_cls(
                  vocab=vocab,
                  create_tokenizer=create_tokenizer,
                  create_vectors=create_vectors,
                  meta=meta,
              )
              if after_creation is not None:
                  nlp = after_creation(nlp)
                  if not isinstance(nlp, cls):
                      raise ValueError(Errors.E942.format(name="creation", value=type(nlp)))
              # To create the components we need to use the final interpolated config
              # so all values are available (if component configs use variables).
              # Later we replace the component config with the raw config again.
              interpolated = filled.interpolate() if not filled.is_interpolated else filled
              pipeline = interpolated.get("components", {})
              # If components are loaded from a source (existing models), we cache
              # them here so they're only loaded once
              source_nlps = {}
              source_nlp_vectors_hashes = {}
              vocab_b = None
              for pipe_name in config["nlp"]["pipeline"]:
                  if pipe_name not in pipeline:
                      opts = ", ".join(pipeline.keys())
                      raise ValueError(Errors.E956.format(name=pipe_name, opts=opts))
                  pipe_cfg = util.copy_config(pipeline[pipe_name])
                  raw_config = Config(filled["components"][pipe_name])
                  if pipe_name not in exclude:
                      if "factory" not in pipe_cfg and "source" not in pipe_cfg:
                          err = Errors.E984.format(name=pipe_name, config=pipe_cfg)
                          raise ValueError(err)
                      if "factory" in pipe_cfg:
                          factory = pipe_cfg.pop("factory")
                          # The pipe name (key in the config) here is the unique name
                          # of the component, not necessarily the factory
                          nlp.add_pipe(
                              factory,
                              name=pipe_name,
                              config=pipe_cfg,
                              validate=validate,
                              raw_config=raw_config,
                          )
                      else:
                          assert "source" in pipe_cfg
                          # We need the sourced components to reference the same
                          # vocab without modifying the current vocab state **AND**
                          # we still want to load the source model vectors to perform
                          # the vectors check. Since the source vectors clobber the
                          # current ones, we save the original vocab state and
                          # restore after this loop. Existing strings are preserved
                          # during deserialization, so they do not need any
                          # additional handling.
                          if vocab_b is None:
                              vocab_b = nlp.vocab.to_bytes(exclude=["lookups", "strings"])
                          model = pipe_cfg["source"]
                          if model not in source_nlps:
                              # Load with the same vocab, adding any strings
                              source_nlps[model] = util.load_model(
                                  model, vocab=nlp.vocab, exclude=["lookups"]
                              )
                          source_name = pipe_cfg.get("component", pipe_name)
                          listeners_replaced = False
                          if "replace_listeners" in pipe_cfg:
                              # Make sure that the listened-to component has the
                              # state of the source pipeline listener map so that the
                              # replace_listeners method below works as intended.
                              source_nlps[model]._link_components()
                              for name, proc in source_nlps[model].pipeline:
                                  if source_name in getattr(proc, "listening_components", []):
                                      source_nlps[model].replace_listeners(
                                          name, source_name, pipe_cfg["replace_listeners"]
                                      )
                                      listeners_replaced = True
                          with warnings.catch_warnings():
                              warnings.filterwarnings("ignore", message="\\[W113\\]")
                              nlp.add_pipe(
                                  source_name, source=source_nlps[model], name=pipe_name
                              )
                              # At this point after nlp.add_pipe, the listener map
                              # corresponds to the new pipeline.
                          if model not in source_nlp_vectors_hashes:
                              source_nlp_vectors_hashes[model] = hash(
                                  source_nlps[model].vocab.vectors.to_bytes(
                                      exclude=["strings"]
                                  )
                              )
                          if "_sourced_vectors_hashes" not in nlp.meta:
                              nlp.meta["_sourced_vectors_hashes"] = {}
                          nlp.meta["_sourced_vectors_hashes"][
                              pipe_name
                          ] = source_nlp_vectors_hashes[model]
                          # Delete from cache if listeners were replaced
                          if listeners_replaced:
                              del source_nlps[model]
              # Restore the original vocab after sourcing if necessary
              if vocab_b is not None:
                  nlp.vocab.from_bytes(vocab_b)

              # Resolve disabled/enabled settings.
              if isinstance(disable, str):
                  disable = [disable]
              if isinstance(enable, str):
                  enable = [enable]
              if isinstance(exclude, str):
                  exclude = [exclude]

              # `enable` should not be merged with `enabled` (the opposite is true for `disable`/`disabled`). If the config
              # specifies values for `enabled` not included in `enable`, emit warning.
              if id(enable) != id(_DEFAULT_EMPTY_PIPES):
                  enabled = config["nlp"].get("enabled", [])
                  if len(enabled) and not set(enabled).issubset(enable):
                      warnings.warn(
                          Warnings.W123.format(
                              enable=enable,
                              enabled=enabled,
                          )
                      )

              # Ensure sets of disabled/enabled pipe names are not contradictory.
              disabled_pipes = cls._resolve_component_status(
                  list({*disable, *config["nlp"].get("disabled", [])}),
                  enable,
                  config["nlp"]["pipeline"],
              )
              nlp._disabled = set(p for p in disabled_pipes if p not in exclude)

              nlp.batch_size = config["nlp"]["batch_size"]
              nlp.config = filled if auto_fill else config
              if after_pipeline_creation is not None:
                  nlp = after_pipeline_creation(nlp)
                  if not isinstance(nlp, cls):
                      raise ValueError(
                          Errors.E942.format(name="pipeline_creation", value=type(nlp))
                      )
              return nlp

          def replace_listeners(
              self,
              tok2vec_name: str,
              pipe_name: str,
              listeners: Iterable[str],
          ) -> None:
              """Find listener layers (connecting to a token-to-vector embedding
              component) of a given pipeline component model and replace
              them with a standalone copy of the token-to-vector layer. This can be
              useful when training a pipeline with components sourced from an existing
              pipeline: if multiple components (e.g. tagger, parser, NER) listen to
              the same tok2vec component, but some of them are frozen and not updated,
              their performance may degrade significantly as the tok2vec component is
              updated with new data. To prevent this, listeners can be replaced with
              a standalone tok2vec layer that is owned by the component and doesn't
              change if the component isn't updated.

              tok2vec_name (str): Name of the token-to-vector component, typically
                  "tok2vec" or "transformer".
              pipe_name (str): Name of pipeline component to replace listeners for.
              listeners (Iterable[str]): The paths to the listeners, relative to the
                  component config, e.g. ["model.tok2vec"]. Typically, implementations
                  will only connect to one tok2vec component, [model.tok2vec], but in
                  theory, custom models can use multiple listeners. The value here can
                  either be an empty list to not replace any listeners, or a complete
                  (!) list of the paths to all listener layers used by the model.

              DOCS: https://spacy.io/api/language#replace_listeners
              """
              if tok2vec_name not in self.pipe_names:
                  err = Errors.E889.format(
                      tok2vec=tok2vec_name,
                      name=pipe_name,
                      unknown=tok2vec_name,
                      opts=", ".join(self.pipe_names),
                  )
                  raise ValueError(err)
              if pipe_name not in self.pipe_names:
                  err = Errors.E889.format(
                      tok2vec=tok2vec_name,
                      name=pipe_name,
                      unknown=pipe_name,
                      opts=", ".join(self.pipe_names),
                  )
                  raise ValueError(err)
              tok2vec = self.get_pipe(tok2vec_name)
              tok2vec_cfg = self.get_pipe_config(tok2vec_name)
              if not isinstance(tok2vec, ty.ListenedToComponent):
                  raise ValueError(Errors.E888.format(name=tok2vec_name, pipe=type(tok2vec)))
              tok2vec_model = tok2vec.model
              pipe_listeners = tok2vec.listener_map.get(pipe_name, [])
              pipe = self.get_pipe(pipe_name)
              pipe_cfg = self._pipe_configs[pipe_name]
              if listeners:
                  util.logger.debug("Replacing listeners of component '%s'", pipe_name)
                  if len(list(listeners)) != len(pipe_listeners):
                      # The number of listeners defined in the component model doesn't
                      # match the listeners to replace, so we won't be able to update
                      # the nodes and generate a matching config
                      err = Errors.E887.format(
                          name=pipe_name,
                          tok2vec=tok2vec_name,
                          paths=listeners,
                          n_listeners=len(pipe_listeners),
                      )
                      raise ValueError(err)
                  # Update the config accordingly by copying the tok2vec model to all
                  # sections defined in the listener paths
                  for listener_path in listeners:
                      # Check if the path actually exists in the config
                      try:
                          util.dot_to_object(pipe_cfg, listener_path)
                      except KeyError:
                          err = Errors.E886.format(
                              name=pipe_name, tok2vec=tok2vec_name, path=listener_path
                          )
                          raise ValueError(err)
                      new_config = tok2vec_cfg["model"]
                      if "replace_listener_cfg" in tok2vec_model.attrs:
                          replace_func = tok2vec_model.attrs["replace_listener_cfg"]
                          new_config = replace_func(
                              tok2vec_cfg["model"], pipe_cfg["model"]["tok2vec"]
                          )
                      util.set_dot_to_object(pipe_cfg, listener_path, new_config)
                  # Go over the listener layers and replace them
                  for listener in pipe_listeners:
                      new_model = tok2vec_model.copy()
                      replace_listener_func = tok2vec_model.attrs.get("replace_listener")
                      if replace_listener_func is not None:
                          # Pass the extra args to the callback without breaking compatibility with
                          # old library versions that only expect a single parameter.
                          num_params = len(
                              inspect.signature(replace_listener_func).parameters
                          )
                          if num_params == 1:
                              new_model = replace_listener_func(new_model)
                          elif num_params == 3:
                              new_model = replace_listener_func(new_model, listener, tok2vec)
                          else:
                              raise ValueError(Errors.E1055.format(num_params=num_params))

                      util.replace_model_node(pipe.model, listener, new_model)  # type: ignore[attr-defined]
                      tok2vec.remove_listener(listener, pipe_name)

          @contextmanager
          def memory_zone(self, mem: Optional[Pool] = None) -> Iterator[Pool]:
              """Begin a block where all resources allocated during the block will
              be freed at the end of it. If a resources was created within the
              memory zone block, accessing it outside the block is invalid.
              Behaviour of this invalid access is undefined. Memory zones should
              not be nested.

              The memory zone is helpful for services that need to process large
              volumes of text with a defined memory budget.

              Example
              -------
              >>> with nlp.memory_zone():
              ...     for doc in nlp.pipe(texts):
              ...        process_my_doc(doc)
              >>> # use_doc(doc) <-- Invalid: doc was allocated in the memory zone
              """
              if mem is None:
                  mem = Pool()
              # The ExitStack allows programmatic nested context managers.
              # We don't know how many we need, so it would be awkward to have
              # them as nested blocks.
              with ExitStack() as stack:
                  contexts = [stack.enter_context(self.vocab.memory_zone(mem))]
                  if hasattr(self.tokenizer, "memory_zone"):
                      contexts.append(stack.enter_context(self.tokenizer.memory_zone(mem)))
                  for _, pipe in self.pipeline:
                      if hasattr(pipe, "memory_zone"):
                          contexts.append(stack.enter_context(pipe.memory_zone(mem)))
                  yield mem

          def to_disk(
              self, path: Union[str, Path], *, exclude: Iterable[str] = SimpleFrozenList()
          ) -> None:
              """Save the current state to a directory.  If a model is loaded, this
              will include the model.

              path (str / Path): Path to a directory, which will be created if
                  it doesn't exist.
              exclude (Iterable[str]): Names of components or serialization fields to exclude.

              DOCS: https://spacy.io/api/language#to_disk
              """
              path = util.ensure_path(path)
              serializers = {}
              serializers["tokenizer"] = lambda p: self.tokenizer.to_disk(  # type: ignore[union-attr]
                  p, exclude=["vocab"]
              )
              serializers["meta.json"] = lambda p: srsly.write_json(
                  p, _replace_numpy_floats(self.meta)
              )
              serializers["config.cfg"] = lambda p: self.config.to_disk(p)
              for name, proc in self._components:
                  if name in exclude:
                      continue
                  if not hasattr(proc, "to_disk"):
                      continue
                  serializers[name] = lambda p, proc=proc: proc.to_disk(p, exclude=["vocab"])  # type: ignore[misc]
              serializers["vocab"] = lambda p: self.vocab.to_disk(p, exclude=exclude)
              util.to_disk(path, serializers, exclude)

          @staticmethod
          def _resolve_component_status(
              disable: Union[str, Iterable[str]],
              enable: Union[str, Iterable[str]],
              pipe_names: Iterable[str],
          ) -> Tuple[str, ...]:
              """Derives whether (1) `disable` and `enable` values are consistent and (2)
              resolves those to a single set of disabled components. Raises an error in
              case of inconsistency.

              disable (Union[str, Iterable[str]]): Name(s) of component(s) or serialization fields to disable.
              enable (Union[str, Iterable[str]]): Name(s) of pipeline component(s) to enable.
              pipe_names (Iterable[str]): Names of all pipeline components.

              RETURNS (Tuple[str, ...]): Names of components to exclude from pipeline w.r.t.
                                         specified includes and excludes.
              """

              if isinstance(disable, str):
                  disable = [disable]
              to_disable = disable

              if enable:
                  if isinstance(enable, str):
                      enable = [enable]
                  to_disable = {
                      *[pipe_name for pipe_name in pipe_names if pipe_name not in enable],
                      *disable,
                  }
                  # If any pipe to be enabled is in to_disable, the specification is inconsistent.
                  if len(set(enable) & to_disable):
                      raise ValueError(Errors.E1042.format(enable=enable, disable=disable))

              return tuple(to_disable)

          def from_disk(
              self,
              path: Union[str, Path],
              *,
              exclude: Iterable[str] = SimpleFrozenList(),
              overrides: Dict[str, Any] = SimpleFrozenDict(),
          ) -> "Language":
              """Loads state from a directory. Modifies the object in place and
              returns it. If the saved `Language` object contains a model, the
              model will be loaded.

              path (str / Path): A path to a directory.
              exclude (Iterable[str]): Names of components or serialization fields to exclude.
              RETURNS (Language): The modified `Language` object.

              DOCS: https://spacy.io/api/language#from_disk
              """

              def deserialize_meta(path: Path) -> None:
                  if path.exists():
                      data = srsly.read_json(path)
                      self.meta.update(data)
                      # self.meta always overrides meta["vectors"] with the metadata
                      # from self.vocab.vectors, so set the name directly
                      self.vocab.vectors.name = data.get("vectors", {}).get("name")

              def deserialize_vocab(path: Path) -> None:
                  if path.exists():
                      self.vocab.from_disk(path, exclude=exclude)

              path = util.ensure_path(path)
              deserializers = {}
              if Path(path / "config.cfg").exists():  # type: ignore[operator]
                  deserializers["config.cfg"] = lambda p: self.config.from_disk(
                      p, interpolate=False, overrides=overrides
                  )
              deserializers["meta.json"] = deserialize_meta  # type: ignore[assignment]
              deserializers["vocab"] = deserialize_vocab  # type: ignore[assignment]
              deserializers["tokenizer"] = lambda p: self.tokenizer.from_disk(  # type: ignore[union-attr]
                  p, exclude=["vocab"]
              )
              for name, proc in self._components:
                  if name in exclude:
                      continue
                  if not hasattr(proc, "from_disk"):
                      continue
                  deserializers[name] = lambda p, proc=proc: proc.from_disk(  # type: ignore[misc]
                      p, exclude=["vocab"]
                  )
              if not (path / "vocab").exists() and "vocab" not in exclude:  # type: ignore[operator]
                  # Convert to list here in case exclude is (default) tuple
                  exclude = list(exclude) + ["vocab"]
              util.from_disk(path, deserializers, exclude)  # type: ignore[arg-type]
              self._path = path  # type: ignore[assignment]
              self._link_components()
              return self

          def to_bytes(self, *, exclude: Iterable[str] = SimpleFrozenList()) -> bytes:
              """Serialize the current state to a binary string.

              exclude (Iterable[str]): Names of components or serialization fields to exclude.
              RETURNS (bytes): The serialized form of the `Language` object.

              DOCS: https://spacy.io/api/language#to_bytes
              """
              serializers: Dict[str, Callable[[], bytes]] = {}
              serializers["vocab"] = lambda: self.vocab.to_bytes(exclude=exclude)
              serializers["tokenizer"] = lambda: self.tokenizer.to_bytes(exclude=["vocab"])  # type: ignore[union-attr]
              serializers["meta.json"] = lambda: srsly.json_dumps(
                  _replace_numpy_floats(self.meta)
              )
              serializers["config.cfg"] = lambda: self.config.to_bytes()
              for name, proc in self._components:
                  if name in exclude:
                      continue
                  if not hasattr(proc, "to_bytes"):
                      continue
                  serializers[name] = lambda proc=proc: proc.to_bytes(exclude=["vocab"])  # type: ignore[misc]
              return util.to_bytes(serializers, exclude)

          def from_bytes(
              self, bytes_data: bytes, *, exclude: Iterable[str] = SimpleFrozenList()
          ) -> "Language":
              """Load state from a binary string.

              bytes_data (bytes): The data to load from.
              exclude (Iterable[str]): Names of components or serialization fields to exclude.
              RETURNS (Language): The `Language` object.

              DOCS: https://spacy.io/api/language#from_bytes
              """

              def deserialize_meta(b):
                  data = srsly.json_loads(b)
                  self.meta.update(data)
                  # self.meta always overrides meta["vectors"] with the metadata
                  # from self.vocab.vectors, so set the name directly
                  self.vocab.vectors.name = data.get("vectors", {}).get("name")

              deserializers: Dict[str, Callable[[bytes], Any]] = {}
              deserializers["config.cfg"] = lambda b: self.config.from_bytes(
                  b, interpolate=False
              )
              deserializers["meta.json"] = deserialize_meta
              deserializers["vocab"] = lambda b: self.vocab.from_bytes(b, exclude=exclude)
              deserializers["tokenizer"] = lambda b: self.tokenizer.from_bytes(  # type: ignore[union-attr]
                  b, exclude=["vocab"]
              )
              for name, proc in self._components:
                  if name in exclude:
                      continue
                  if not hasattr(proc, "from_bytes"):
                      continue
                  deserializers[name] = lambda b, proc=proc: proc.from_bytes(  # type: ignore[misc]
                      b, exclude=["vocab"]
                  )
              util.from_bytes(bytes_data, deserializers, exclude)
              self._link_components()
              return self

  A text-processing pipeline. Usually you'll load this once per process, and pass the instance around your application.

  Defaults (class): Settings, data and factory methods for creating the `nlp` object and processing pipeline. lang (str): IETF language code, such as 'en'.

  DOCS: https://spacy.io/api/language

  Initialise a Language object.

  vocab (Vocab): A `Vocab` object. If `True`, a vocab is created. meta (dict): Custom meta data for the Language class. Is written to by models to add model meta data. max_length (int): Maximum number of characters in a single text. The current models may run out memory on extremely long texts, due to large internal allocations. You should segment these texts into meaningful units, e.g. paragraphs, subsections etc, before passing them to spaCy. Default maximum length is 1,000,000 charas (1mb). As a rule of thumb, if all pipeline components are enabled, spaCy's default models currently requires roughly 1GB of temporary memory per 100,000 characters in one text. create_tokenizer (Callable): Function that takes the nlp object and returns a tokenizer. batch_size (int): Default batch size for pipe and evaluate.

  DOCS: https://spacy.io/api/language#init

  ### Subclasses

  - spacy.lang.de.German
  - spacy.lang.ja.Japanese
  - spacy.lang.xx.MultiLanguage

  ### Class variables

  `var Defaults`

    Language data defaults, available via Language.Defaults. Can be overwritten by language subclasses by defining their own subclasses of Language.Defaults.

  `var default_config`
  `var factories`
  `var lang : str | None`

  ### Static methods

  `def component(name: str,
  *,
  assigns: Iterable[str] = [],
  requires: Iterable[str] = [],
  retokenizes: bool = False,
  func: Callable[[spacy.tokens.doc.Doc], spacy.tokens.doc.Doc] | None = None) ‑> Callable[..., Any]`

    Register a new pipeline component. Can be used for stateless function components that don't require a separate factory. Can be used as a decorator on a function or classmethod, or called as a function with the factory provided as the func keyword argument. To create a component and add it to the pipeline, you can use nlp.add_pipe(name).

    name (str): The name of the component factory. assigns (Iterable[str]): Doc/Token attributes assigned by this component, e.g. "token.ent_id". Used for pipeline analysis. requires (Iterable[str]): Doc/Token attributes required by this component, e.g. "token.ent_id". Used for pipeline analysis. retokenizes (bool): Whether the component changes the tokenization. Used for pipeline analysis. func (Optional[Callable[[Doc], Doc]): Factory function if not used as a decorator.

    DOCS: https://spacy.io/api/language#component

  `def factory(name: str,
  *,
  default_config: Dict[str, Any] = {},
  assigns: Iterable[str] = [],
  requires: Iterable[str] = [],
  retokenizes: bool = False,
  default_score_weights: Dict[str, float | None] = {},
  func: Callable | None = None) ‑> Callable`

    Register a new pipeline component factory. Can be used as a decorator on a function or classmethod, or called as a function with the factory provided as the func keyword argument. To create a component and add it to the pipeline, you can use nlp.add_pipe(name).

    name (str): The name of the component factory. default_config (Dict[str, Any]): Default configuration, describing the default values of the factory arguments. assigns (Iterable[str]): Doc/Token attributes assigned by this component, e.g. "token.ent_id". Used for pipeline analysis. requires (Iterable[str]): Doc/Token attributes required by this component, e.g. "token.ent_id". Used for pipeline analysis. retokenizes (bool): Whether the component changes the tokenization. Used for pipeline analysis. default_score_weights (Dict[str, Optional[float]]): The scores to report during training, and their default weight towards the final score used to select the best model. Weights should sum to 1.0 per component and will be combined and normalized for the whole pipeline. If None, the score won't be shown in the logs or be weighted. func (Optional[Callable]): Factory function if not used as a decorator.

    DOCS: https://spacy.io/api/language#factory

  `def from_config(config: Dict[str, Any] | confection.Config = {},
  *,
  vocab: spacy.vocab.Vocab | bool = True,
  disable: str | Iterable[str] = [],
  enable: str | Iterable[str] = [],
  exclude: str | Iterable[str] = [],
  meta: Dict[str, Any] = {},
  auto_fill: bool = True,
  validate: bool = True) ‑> spacy.language.Language`

    Create the nlp object from a loaded config. Will set up the tokenizer and language data, add pipeline components etc. If no config is provided, the default config of the given language is used.

    config (Dict[str, Any] / Config): The loaded config. vocab (Vocab): A Vocab object. If True, a vocab is created. disable (Union[str, Iterable[str]]): Name(s) of pipeline component(s) to disable. Disabled pipes will be loaded but they won't be run unless you explicitly enable them by calling nlp.enable_pipe. enable (Union[str, Iterable[str]]): Name(s) of pipeline component(s) to enable. All other pipes will be disabled (and can be enabled using `nlp.enable_pipe`). exclude (Union[str, Iterable[str]]): Name(s) of pipeline component(s) to exclude. Excluded components won't be loaded. meta (Dict[str, Any]): Meta overrides for nlp.meta. auto_fill (bool): Automatically fill in missing values in config based on defaults and function argument annotations. validate (bool): Validate the component config and arguments against the types expected by the factory. RETURNS (Language): The initialized Language class.

    DOCS: https://spacy.io/api/language#from_config

  `def get_factory_meta(name: str) ‑> spacy.language.FactoryMeta`

    Get the meta information for a given factory name.

    name (str): The component factory name. RETURNS (FactoryMeta): The meta for the given factory name.

  `def get_factory_name(name: str) ‑> str`

    Get the internal factory name based on the language subclass.

    name (str): The factory name. RETURNS (str): The internal factory name.

  `def has_factory(name: str) ‑> bool`

    RETURNS (bool): Whether a factory of that name is registered.

  `def set_factory_meta(name: str, value: FactoryMeta) ‑> None`

    Set the meta information for a given factory name.

    name (str): The component factory name. value (FactoryMeta): The meta to set.

  ### Instance variables

  `prop component_names : List[str]`
    Expand source code

        @property
        def component_names(self) -> List[str]:
            """Get the names of the available pipeline components. Includes all
            active and inactive pipeline components.

            RETURNS (List[str]): List of component name strings, in order.
            """
            names = [pipe_name for pipe_name, _ in self._components]
            return SimpleFrozenList(names, error=Errors.E926.format(attr="component_names"))

    Get the names of the available pipeline components. Includes all active and inactive pipeline components.

    RETURNS (List[str]): List of component name strings, in order.

  `prop components : List[Tuple[str, Callable[[spacy.tokens.doc.Doc], spacy.tokens.doc.Doc]]]`
    Expand source code

        @property
        def components(self) -> List[Tuple[str, PipeCallable]]:
            """Get all (name, component) tuples in the pipeline, including the
            currently disabled components.
            """
            return SimpleFrozenList(
                self._components, error=Errors.E926.format(attr="components")
            )

    Get all (name, component) tuples in the pipeline, including the currently disabled components.

  `prop config : confection.Config`
    Expand source code

        @property
        def config(self) -> Config:
            """Trainable config for the current language instance. Includes the
            current pipeline components, as well as default training config.

            RETURNS (thinc.api.Config): The config.

            DOCS: https://spacy.io/api/language#config
            """
            self._config.setdefault("nlp", {})
            self._config.setdefault("training", {})
            self._config["nlp"]["lang"] = self.lang
            # We're storing the filled config for each pipeline component and so
            # we can populate the config again later
            pipeline = {}
            score_weights = []
            for pipe_name in self.component_names:
                pipe_meta = self.get_pipe_meta(pipe_name)
                pipe_config = self.get_pipe_config(pipe_name)
                pipeline[pipe_name] = {"factory": pipe_meta.factory, **pipe_config}
                if pipe_meta.default_score_weights:
                    score_weights.append(pipe_meta.default_score_weights)
            self._config["nlp"]["pipeline"] = list(self.component_names)
            self._config["nlp"]["disabled"] = list(self.disabled)
            self._config["components"] = pipeline
            # We're merging the existing score weights back into the combined
            # weights to make sure we're preserving custom settings in the config
            # but also reflect updates (e.g. new components added)
            prev_weights = self._config["training"].get("score_weights", {})
            combined_score_weights = combine_score_weights(score_weights, prev_weights)
            self._config["training"]["score_weights"] = combined_score_weights
            if not srsly.is_json_serializable(self._config):
                raise ValueError(Errors.E961.format(config=self._config))
            return self._config

    Trainable config for the current language instance. Includes the current pipeline components, as well as default training config.

    RETURNS (thinc.api.Config): The config.

    DOCS: https://spacy.io/api/language#config

  `prop disabled : List[str]`
    Expand source code

        @property
        def disabled(self) -> List[str]:
            """Get the names of all disabled components.

            RETURNS (List[str]): The disabled components.
            """
            # Make sure the disabled components are returned in the order they
            # appear in the pipeline (which isn't guaranteed by the set)
            names = [name for name, _ in self._components if name in self._disabled]
            return SimpleFrozenList(names, error=Errors.E926.format(attr="disabled"))

    Get the names of all disabled components.

    RETURNS (List[str]): The disabled components.

  `prop factory_names : List[str]`
    Expand source code

        @property
        def factory_names(self) -> List[str]:
            """Get names of all available factories.

            RETURNS (List[str]): The factory names.
            """
            names = list(self.factories.keys())
            return SimpleFrozenList(names)

    Get names of all available factories.

    RETURNS (List[str]): The factory names.

  `prop meta : Dict[str, Any]`
    Expand source code

        @property
        def meta(self) -> Dict[str, Any]:
            """Custom meta data of the language class. If a model is loaded, this
            includes details from the model's meta.json.

            RETURNS (Dict[str, Any]): The meta.

            DOCS: https://spacy.io/api/language#meta
            """
            spacy_version = util.get_minor_version_range(about.__version__)
            if self.vocab.lang:
                self._meta.setdefault("lang", self.vocab.lang)
            else:
                self._meta.setdefault("lang", self.lang)
            self._meta.setdefault("name", "pipeline")
            self._meta.setdefault("version", "0.0.0")
            self._meta.setdefault("spacy_version", spacy_version)
            self._meta.setdefault("description", "")
            self._meta.setdefault("author", "")
            self._meta.setdefault("email", "")
            self._meta.setdefault("url", "")
            self._meta.setdefault("license", "")
            self._meta.setdefault("spacy_git_version", GIT_VERSION)
            self._meta["vectors"] = {
                "width": self.vocab.vectors_length,
                "vectors": len(self.vocab.vectors),
                "keys": self.vocab.vectors.n_keys,
                "name": self.vocab.vectors.name,
                "mode": self.vocab.vectors.mode,
            }
            self._meta["labels"] = dict(self.pipe_labels)
            # TODO: Adding this back to prevent breaking people's code etc., but
            # we should consider removing it
            self._meta["pipeline"] = list(self.pipe_names)
            self._meta["components"] = list(self.component_names)
            self._meta["disabled"] = list(self.disabled)
            return self._meta

    Custom meta data of the language class. If a model is loaded, this includes details from the model's meta.json.

    RETURNS (Dict[str, Any]): The meta.

    DOCS: https://spacy.io/api/language#meta

  `prop path`
    Expand source code

        @property
        def path(self):
            return self._path

  `prop pipe_factories : Dict[str, str]`
    Expand source code

        @property
        def pipe_factories(self) -> Dict[str, str]:
            """Get the component factories for the available pipeline components.

            RETURNS (Dict[str, str]): Factory names, keyed by component names.
            """
            factories = {}
            for pipe_name, pipe in self._components:
                factories[pipe_name] = self.get_pipe_meta(pipe_name).factory
            return SimpleFrozenDict(factories)

    Get the component factories for the available pipeline components.

    RETURNS (Dict[str, str]): Factory names, keyed by component names.

  `prop pipe_labels : Dict[str, List[str]]`
    Expand source code

        @property
        def pipe_labels(self) -> Dict[str, List[str]]:
            """Get the labels set by the pipeline components, if available (if
            the component exposes a labels property and the labels are not
            hidden).

            RETURNS (Dict[str, List[str]]): Labels keyed by component name.
            """
            labels = {}
            for name, pipe in self._components:
                if hasattr(pipe, "hide_labels") and pipe.hide_labels is True:
                    continue
                if hasattr(pipe, "labels"):
                    labels[name] = list(pipe.labels)
            return SimpleFrozenDict(labels)

    Get the labels set by the pipeline components, if available (if the component exposes a labels property and the labels are not hidden).

    RETURNS (Dict[str, List[str]]): Labels keyed by component name.

  `prop pipe_names : List[str]`
    Expand source code

        @property
        def pipe_names(self) -> List[str]:
            """Get names of available active pipeline components.

            RETURNS (List[str]): List of component name strings, in order.
            """
            names = [pipe_name for pipe_name, _ in self.pipeline]
            return SimpleFrozenList(names, error=Errors.E926.format(attr="pipe_names"))

    Get names of available active pipeline components.

    RETURNS (List[str]): List of component name strings, in order.

  `prop pipeline : List[Tuple[str, Callable[[spacy.tokens.doc.Doc], spacy.tokens.doc.Doc]]]`
    Expand source code

        @property
        def pipeline(self) -> List[Tuple[str, PipeCallable]]:
            """The processing pipeline consisting of (name, component) tuples. The
            components are called on the Doc in order as it passes through the
            pipeline.

            RETURNS (List[Tuple[str, Callable[[Doc], Doc]]]): The pipeline.
            """
            pipes = [(n, p) for n, p in self._components if n not in self._disabled]
            return SimpleFrozenList(pipes, error=Errors.E926.format(attr="pipeline"))

    The processing pipeline consisting of (name, component) tuples. The components are called on the Doc in order as it passes through the pipeline.

    RETURNS (List[Tuple[str, Callable[[Doc], Doc]]]): The pipeline.

  ### Methods

  `def add_pipe(self,
  factory_name: str,
  name: str | None = None,
  *,
  before: str | int | None = None,
  after: str | int | None = None,
  first: bool | None = None,
  last: bool | None = None,
  source: ForwardRef('Language') | None = None,
  config: Dict[str, Any] = {},
  raw_config: confection.Config | None = None,
  validate: bool = True) ‑> Callable[[spacy.tokens.doc.Doc], spacy.tokens.doc.Doc]`
    Expand source code

        def add_pipe(
            self,
            factory_name: str,
            name: Optional[str] = None,
            *,
            before: Optional[Union[str, int]] = None,
            after: Optional[Union[str, int]] = None,
            first: Optional[bool] = None,
            last: Optional[bool] = None,
            source: Optional["Language"] = None,
            config: Dict[str, Any] = SimpleFrozenDict(),
            raw_config: Optional[Config] = None,
            validate: bool = True,
        ) -> PipeCallable:
            """Add a component to the processing pipeline. Valid components are
            callables that take a `Doc` object, modify it and return it. Only one
            of before/after/first/last can be set. Default behaviour is "last".

            factory_name (str): Name of the component factory.
            name (str): Name of pipeline component. Overwrites existing
                component.name attribute if available. If no name is set and
                the component exposes no name attribute, component.__name__ is
                used. An error is raised if a name already exists in the pipeline.
            before (Union[str, int]): Name or index of the component to insert new
                component directly before.
            after (Union[str, int]): Name or index of the component to insert new
                component directly after.
            first (bool): If True, insert component first in the pipeline.
            last (bool): If True, insert component last in the pipeline.
            source (Language): Optional loaded nlp object to copy the pipeline
                component from.
            config (Dict[str, Any]): Config parameters to use for this component.
                Will be merged with default config, if available.
            raw_config (Optional[Config]): Internals: the non-interpolated config.
            validate (bool): Whether to validate the component config against the
                arguments and types expected by the factory.
            RETURNS (Callable[[Doc], Doc]): The pipeline component.

            DOCS: https://spacy.io/api/language#add_pipe
            """
            if not isinstance(factory_name, str):
                bad_val = repr(factory_name)
                err = Errors.E966.format(component=bad_val, name=name)
                raise ValueError(err)
            name = name if name is not None else factory_name
            if name in self.component_names:
                raise ValueError(Errors.E007.format(name=name, opts=self.component_names))
            # Overriding pipe name in the config is not supported and will be ignored.
            if "name" in config:
                warnings.warn(Warnings.W119.format(name_in_config=config.pop("name")))
            if source is not None:
                # We're loading the component from a model. After loading the
                # component, we know its real factory name
                pipe_component, factory_name = self.create_pipe_from_source(
                    factory_name, source, name=name
                )
            else:
                pipe_component = self.create_pipe(
                    factory_name,
                    name=name,
                    config=config,
                    raw_config=raw_config,
                    validate=validate,
                )
            pipe_index = self._get_pipe_index(before, after, first, last)
            self._pipe_meta[name] = self.get_factory_meta(factory_name)
            self._components.insert(pipe_index, (name, pipe_component))
            self._link_components()
            return pipe_component

    Add a component to the processing pipeline. Valid components are callables that take a `Doc` object, modify it and return it. Only one of before/after/first/last can be set. Default behaviour is "last".

    factory_name (str): Name of the component factory. name (str): Name of pipeline component. Overwrites existing component.name attribute if available. If no name is set and the component exposes no name attribute, component.name is used. An error is raised if a name already exists in the pipeline. before (Union[str, int]): Name or index of the component to insert new component directly before. after (Union[str, int]): Name or index of the component to insert new component directly after. first (bool): If True, insert component first in the pipeline. last (bool): If True, insert component last in the pipeline. source (Language): Optional loaded nlp object to copy the pipeline component from. config (Dict[str, Any]): Config parameters to use for this component. Will be merged with default config, if available. raw_config (Optional[Config]): Internals: the non-interpolated config. validate (bool): Whether to validate the component config against the arguments and types expected by the factory. RETURNS (Callable[[Doc], Doc]): The pipeline component.

    DOCS: https://spacy.io/api/language#add_pipe

  `def analyze_pipes(self,
  *,
  keys: List[str] = ['assigns', 'requires', 'scores', 'retokenizes'],
  pretty: bool = False) ‑> Dict[str, Any] | None`
    Expand source code

        def analyze_pipes(
            self,
            *,
            keys: List[str] = ["assigns", "requires", "scores", "retokenizes"],
            pretty: bool = False,
        ) -> Optional[Dict[str, Any]]:
            """Analyze the current pipeline components, print a summary of what
            they assign or require and check that all requirements are met.

            keys (List[str]): The meta values to display in the table. Corresponds
                to values in FactoryMeta, defined by @Language.factory decorator.
            pretty (bool): Pretty-print the results.
            RETURNS (dict): The data.
            """
            analysis = analyze_pipes(self, keys=keys)
            if pretty:
                print_pipe_analysis(analysis, keys=keys)
            return analysis

    Analyze the current pipeline components, print a summary of what they assign or require and check that all requirements are met.

    keys (List[str]): The meta values to display in the table. Corresponds to values in FactoryMeta, defined by @Language.factory decorator. pretty (bool): Pretty-print the results. RETURNS (dict): The data.

  `def begin_training(self,
  get_examples: Callable[[], Iterable[spacy.training.example.Example]] | None = None,
  *,
  sgd: thinc.optimizers.Optimizer | None = None) ‑> thinc.optimizers.Optimizer`
    Expand source code

        def begin_training(
            self,
            get_examples: Optional[Callable[[], Iterable[Example]]] = None,
            *,
            sgd: Optional[Optimizer] = None,
        ) -> Optimizer:
            warnings.warn(Warnings.W089, DeprecationWarning)
            return self.initialize(get_examples, sgd=sgd)

  `def create_optimizer(self)`
    Expand source code

        def create_optimizer(self):
            """Create an optimizer, usually using the [training.optimizer] config."""
            subconfig = {"optimizer": self.config["training"]["optimizer"]}
            return registry.resolve(subconfig)["optimizer"]

    Create an optimizer, usually using the [training.optimizer] config.

  `def create_pipe(self,
  factory_name: str,
  name: str | None = None,
  *,
  config: Dict[str, Any] = {},
  raw_config: confection.Config | None = None,
  validate: bool = True) ‑> Callable[[spacy.tokens.doc.Doc], spacy.tokens.doc.Doc]`
    Expand source code

        def create_pipe(
            self,
            factory_name: str,
            name: Optional[str] = None,
            *,
            config: Dict[str, Any] = SimpleFrozenDict(),
            raw_config: Optional[Config] = None,
            validate: bool = True,
        ) -> PipeCallable:
            """Create a pipeline component. Mostly used internally. To create and
            add a component to the pipeline, you can use nlp.add_pipe.

            factory_name (str): Name of component factory.
            name (Optional[str]): Optional name to assign to component instance.
                Defaults to factory name if not set.
            config (Dict[str, Any]): Config parameters to use for this component.
                Will be merged with default config, if available.
            raw_config (Optional[Config]): Internals: the non-interpolated config.
            validate (bool): Whether to validate the component config against the
                arguments and types expected by the factory.
            RETURNS (Callable[[Doc], Doc]): The pipeline component.

            DOCS: https://spacy.io/api/language#create_pipe
            """
            name = name if name is not None else factory_name
            if not isinstance(config, dict):
                err = Errors.E962.format(style="config", name=name, cfg_type=type(config))
                raise ValueError(err)
            if not srsly.is_json_serializable(config):
                raise ValueError(Errors.E961.format(config=config))
            if not self.has_factory(factory_name):
                err = Errors.E002.format(
                    name=factory_name,
                    opts=", ".join(self.factory_names),
                    method="create_pipe",
                    lang=util.get_object_name(self),
                    lang_code=self.lang,
                )
                raise ValueError(err)
            pipe_meta = self.get_factory_meta(factory_name)
            # This is unideal, but the alternative would mean you always need to
            # specify the full config settings, which is not really viable.
            if pipe_meta.default_config:
                config = Config(pipe_meta.default_config).merge(config)
            internal_name = self.get_factory_name(factory_name)
            # If the language-specific factory doesn't exist, try again with the
            # not-specific name
            if internal_name not in registry.factories:
                internal_name = factory_name
            # The name allows components to know their pipe name and use it in the
            # losses etc. (even if multiple instances of the same factory are used)
            config = {"nlp": self, "name": name, **config, "@factories": internal_name}
            # We need to create a top-level key because Thinc doesn't allow resolving
            # top-level references to registered functions. Also gives nicer errors.
            cfg = {factory_name: config}
            # We're calling the internal _fill here to avoid constructing the
            # registered functions twice
            resolved = registry.resolve(cfg, validate=validate)
            filled = registry.fill({"cfg": cfg[factory_name]}, validate=validate)["cfg"]
            filled = Config(filled)
            filled["factory"] = factory_name
            filled.pop("@factories", None)
            # Remove the extra values we added because we don't want to keep passing
            # them around, copying them etc.
            filled.pop("nlp", None)
            filled.pop("name", None)
            # Merge the final filled config with the raw config (including non-
            # interpolated variables)
            if raw_config:
                filled = filled.merge(raw_config)
            self._pipe_configs[name] = filled
            return resolved[factory_name]

    Create a pipeline component. Mostly used internally. To create and add a component to the pipeline, you can use nlp.add_pipe.

    factory_name (str): Name of component factory. name (Optional[str]): Optional name to assign to component instance. Defaults to factory name if not set. config (Dict[str, Any]): Config parameters to use for this component. Will be merged with default config, if available. raw_config (Optional[Config]): Internals: the non-interpolated config. validate (bool): Whether to validate the component config against the arguments and types expected by the factory. RETURNS (Callable[[Doc], Doc]): The pipeline component.

    DOCS: https://spacy.io/api/language#create_pipe

  `def create_pipe_from_source(self,
  source_name: str,
  source: Language,
  *,
  name: str) ‑> Tuple[Callable[[spacy.tokens.doc.Doc], spacy.tokens.doc.Doc], str]`
    Expand source code

        def create_pipe_from_source(
            self, source_name: str, source: "Language", *, name: str
        ) -> Tuple[PipeCallable, str]:
            """Create a pipeline component by copying it from an existing model.

            source_name (str): Name of the component in the source pipeline.
            source (Language): The source nlp object to copy from.
            name (str): Optional alternative name to use in current pipeline.
            RETURNS (Tuple[Callable[[Doc], Doc], str]): The component and its factory name.
            """
            # Check source type
            if not isinstance(source, Language):
                raise ValueError(Errors.E945.format(name=source_name, source=type(source)))
            if self.vocab.vectors != source.vocab.vectors:
                warnings.warn(Warnings.W113.format(name=source_name))
            if source_name not in source.component_names:
                raise KeyError(
                    Errors.E944.format(
                        name=source_name,
                        model=f"{source.meta['lang']}_{source.meta['name']}",
                        opts=", ".join(source.component_names),
                    )
                )
            pipe = source.get_pipe(source_name)
            # There is no actual solution here. Either the component has the right
            # name for the source pipeline or the component has the right name for
            # the current pipeline. This prioritizes the current pipeline.
            if hasattr(pipe, "name"):
                pipe.name = name
            # Make sure the source config is interpolated so we don't end up with
            # orphaned variables in our final config
            source_config = source.config.interpolate()
            pipe_config = util.copy_config(source_config["components"][source_name])
            self._pipe_configs[name] = pipe_config
            if self.vocab.strings != source.vocab.strings:
                for s in source.vocab.strings:
                    self.vocab.strings.add(s)
            return pipe, pipe_config["factory"]

    Create a pipeline component by copying it from an existing model.

    source_name (str): Name of the component in the source pipeline. source (Language): The source nlp object to copy from. name (str): Optional alternative name to use in current pipeline. RETURNS (Tuple[Callable[[Doc], Doc], str]): The component and its factory name.

  `def disable_pipe(self, name: str) ‑> None`
    Expand source code

        def disable_pipe(self, name: str) -> None:
            """Disable a pipeline component. The component will still exist on
            the nlp object, but it won't be run as part of the pipeline. Does
            nothing if the component is already disabled.

            name (str): The name of the component to disable.
            """
            if name not in self.component_names:
                raise ValueError(Errors.E001.format(name=name, opts=self.component_names))
            self._disabled.add(name)

    Disable a pipeline component. The component will still exist on the nlp object, but it won't be run as part of the pipeline. Does nothing if the component is already disabled.

    name (str): The name of the component to disable.

  `def disable_pipes(self, *names) ‑> spacy.language.DisabledPipes`
    Expand source code

        def disable_pipes(self, *names) -> "DisabledPipes":
            """Disable one or more pipeline components. If used as a context
            manager, the pipeline will be restored to the initial state at the end
            of the block. Otherwise, a DisabledPipes object is returned, that has
            a `.restore()` method you can use to undo your changes.

            This method has been deprecated since 3.0
            """
            warnings.warn(Warnings.W096, DeprecationWarning)
            if len(names) == 1 and isinstance(names[0], (list, tuple)):
                names = names[0]  # type: ignore[assignment]    # support list of names instead of spread
            return self.select_pipes(disable=names)

    Disable one or more pipeline components. If used as a context manager, the pipeline will be restored to the initial state at the end of the block. Otherwise, a DisabledPipes object is returned, that has a `.restore()` method you can use to undo your changes.

    This method has been deprecated since 3.0

  `def enable_pipe(self, name: str) ‑> None`
    Expand source code

        def enable_pipe(self, name: str) -> None:
            """Enable a previously disabled pipeline component so it's run as part
            of the pipeline. Does nothing if the component is already enabled.

            name (str): The name of the component to enable.
            """
            if name not in self.component_names:
                raise ValueError(Errors.E001.format(name=name, opts=self.component_names))
            if name in self.disabled:
                self._disabled.remove(name)

    Enable a previously disabled pipeline component so it's run as part of the pipeline. Does nothing if the component is already enabled.

    name (str): The name of the component to enable.

  `def evaluate(self,
  examples: Iterable[spacy.training.example.Example],
  *,
  batch_size: int | None = None,
  scorer: spacy.scorer.Scorer | None = None,
  component_cfg: Dict[str, Dict[str, Any]] | None = None,
  scorer_cfg: Dict[str, Any] | None = None,
  per_component: bool = False) ‑> Dict[str, Any]`
    Expand source code

        def evaluate(
            self,
            examples: Iterable[Example],
            *,
            batch_size: Optional[int] = None,
            scorer: Optional[Scorer] = None,
            component_cfg: Optional[Dict[str, Dict[str, Any]]] = None,
            scorer_cfg: Optional[Dict[str, Any]] = None,
            per_component: bool = False,
        ) -> Dict[str, Any]:
            """Evaluate a model's pipeline components.

            examples (Iterable[Example]): `Example` objects.
            batch_size (Optional[int]): Batch size to use.
            scorer (Optional[Scorer]): Scorer to use. If not passed in, a new one
                will be created.
            component_cfg (dict): An optional dictionary with extra keyword
                arguments for specific components.
            scorer_cfg (dict): An optional dictionary with extra keyword arguments
                for the scorer.
            per_component (bool): Whether to return the scores keyed by component
                name. Defaults to False.

            RETURNS (Scorer): The scorer containing the evaluation results.

            DOCS: https://spacy.io/api/language#evaluate
            """
            examples = list(examples)
            validate_examples(examples, "Language.evaluate")
            examples = _copy_examples(examples)
            if batch_size is None:
                batch_size = self.batch_size
            if component_cfg is None:
                component_cfg = {}
            if scorer_cfg is None:
                scorer_cfg = {}
            if scorer is None:
                kwargs = dict(scorer_cfg)
                kwargs.setdefault("nlp", self)
                scorer = Scorer(**kwargs)
            # reset annotation in predicted docs and time tokenization
            start_time = timer()
            # this is purely for timing
            for eg in examples:
                self.make_doc(eg.reference.text)
            # apply all pipeline components
            docs = self.pipe(
                (eg.predicted for eg in examples),
                batch_size=batch_size,
                component_cfg=component_cfg,
            )
            for eg, doc in zip(examples, docs):
                eg.predicted = doc
            end_time = timer()
            results = scorer.score(examples, per_component=per_component)
            n_words = sum(len(eg.predicted) for eg in examples)
            results["speed"] = n_words / (end_time - start_time)
            return _replace_numpy_floats(results)

    Evaluate a model's pipeline components.

    examples (Iterable[Example]): `Example` objects. batch_size (Optional[int]): Batch size to use. scorer (Optional[Scorer]): Scorer to use. If not passed in, a new one will be created. component_cfg (dict): An optional dictionary with extra keyword arguments for specific components. scorer_cfg (dict): An optional dictionary with extra keyword arguments for the scorer. per_component (bool): Whether to return the scores keyed by component name. Defaults to False.

    RETURNS (Scorer): The scorer containing the evaluation results.

    DOCS: https://spacy.io/api/language#evaluate

  `def from_bytes(self, bytes_data: bytes, *, exclude: Iterable[str] = []) ‑> spacy.language.Language`
    Expand source code

        def from_bytes(
            self, bytes_data: bytes, *, exclude: Iterable[str] = SimpleFrozenList()
        ) -> "Language":
            """Load state from a binary string.

            bytes_data (bytes): The data to load from.
            exclude (Iterable[str]): Names of components or serialization fields to exclude.
            RETURNS (Language): The `Language` object.

            DOCS: https://spacy.io/api/language#from_bytes
            """

            def deserialize_meta(b):
                data = srsly.json_loads(b)
                self.meta.update(data)
                # self.meta always overrides meta["vectors"] with the metadata
                # from self.vocab.vectors, so set the name directly
                self.vocab.vectors.name = data.get("vectors", {}).get("name")

            deserializers: Dict[str, Callable[[bytes], Any]] = {}
            deserializers["config.cfg"] = lambda b: self.config.from_bytes(
                b, interpolate=False
            )
            deserializers["meta.json"] = deserialize_meta
            deserializers["vocab"] = lambda b: self.vocab.from_bytes(b, exclude=exclude)
            deserializers["tokenizer"] = lambda b: self.tokenizer.from_bytes(  # type: ignore[union-attr]
                b, exclude=["vocab"]
            )
            for name, proc in self._components:
                if name in exclude:
                    continue
                if not hasattr(proc, "from_bytes"):
                    continue
                deserializers[name] = lambda b, proc=proc: proc.from_bytes(  # type: ignore[misc]
                    b, exclude=["vocab"]
                )
            util.from_bytes(bytes_data, deserializers, exclude)
            self._link_components()
            return self

    Load state from a binary string.

    bytes_data (bytes): The data to load from. exclude (Iterable[str]): Names of components or serialization fields to exclude. RETURNS (Language): The `Language` object.

    DOCS: https://spacy.io/api/language#from_bytes

  `def from_disk(self,
  path: str | pathlib.Path,
  *,
  exclude: Iterable[str] = [],
  overrides: Dict[str, Any] = {}) ‑> spacy.language.Language`
    Expand source code

        def from_disk(
            self,
            path: Union[str, Path],
            *,
            exclude: Iterable[str] = SimpleFrozenList(),
            overrides: Dict[str, Any] = SimpleFrozenDict(),
        ) -> "Language":
            """Loads state from a directory. Modifies the object in place and
            returns it. If the saved `Language` object contains a model, the
            model will be loaded.

            path (str / Path): A path to a directory.
            exclude (Iterable[str]): Names of components or serialization fields to exclude.
            RETURNS (Language): The modified `Language` object.

            DOCS: https://spacy.io/api/language#from_disk
            """

            def deserialize_meta(path: Path) -> None:
                if path.exists():
                    data = srsly.read_json(path)
                    self.meta.update(data)
                    # self.meta always overrides meta["vectors"] with the metadata
                    # from self.vocab.vectors, so set the name directly
                    self.vocab.vectors.name = data.get("vectors", {}).get("name")

            def deserialize_vocab(path: Path) -> None:
                if path.exists():
                    self.vocab.from_disk(path, exclude=exclude)

            path = util.ensure_path(path)
            deserializers = {}
            if Path(path / "config.cfg").exists():  # type: ignore[operator]
                deserializers["config.cfg"] = lambda p: self.config.from_disk(
                    p, interpolate=False, overrides=overrides
                )
            deserializers["meta.json"] = deserialize_meta  # type: ignore[assignment]
            deserializers["vocab"] = deserialize_vocab  # type: ignore[assignment]
            deserializers["tokenizer"] = lambda p: self.tokenizer.from_disk(  # type: ignore[union-attr]
                p, exclude=["vocab"]
            )
            for name, proc in self._components:
                if name in exclude:
                    continue
                if not hasattr(proc, "from_disk"):
                    continue
                deserializers[name] = lambda p, proc=proc: proc.from_disk(  # type: ignore[misc]
                    p, exclude=["vocab"]
                )
            if not (path / "vocab").exists() and "vocab" not in exclude:  # type: ignore[operator]
                # Convert to list here in case exclude is (default) tuple
                exclude = list(exclude) + ["vocab"]
            util.from_disk(path, deserializers, exclude)  # type: ignore[arg-type]
            self._path = path  # type: ignore[assignment]
            self._link_components()
            return self

    Loads state from a directory. Modifies the object in place and returns it. If the saved `Language` object contains a model, the model will be loaded.

    path (str / Path): A path to a directory. exclude (Iterable[str]): Names of components or serialization fields to exclude. RETURNS (Language): The modified `Language` object.

    DOCS: https://spacy.io/api/language#from_disk

  `def get_pipe(self, name: str) ‑> Callable[[spacy.tokens.doc.Doc], spacy.tokens.doc.Doc]`
    Expand source code

        def get_pipe(self, name: str) -> PipeCallable:
            """Get a pipeline component for a given component name.

            name (str): Name of pipeline component to get.
            RETURNS (callable): The pipeline component.

            DOCS: https://spacy.io/api/language#get_pipe
            """
            for pipe_name, component in self._components:
                if pipe_name == name:
                    return component
            raise KeyError(Errors.E001.format(name=name, opts=self.component_names))

    Get a pipeline component for a given component name.

    name (str): Name of pipeline component to get. RETURNS (callable): The pipeline component.

    DOCS: https://spacy.io/api/language#get_pipe

  `def get_pipe_config(self, name: str) ‑> confection.Config`
    Expand source code

        def get_pipe_config(self, name: str) -> Config:
            """Get the config used to create a pipeline component.

            name (str): The component name.
            RETURNS (Config): The config used to create the pipeline component.
            """
            if name not in self._pipe_configs:
                raise ValueError(Errors.E960.format(name=name))
            pipe_config = self._pipe_configs[name]
            return pipe_config

    Get the config used to create a pipeline component.

    name (str): The component name. RETURNS (Config): The config used to create the pipeline component.

  `def get_pipe_meta(self, name: str) ‑> spacy.language.FactoryMeta`
    Expand source code

        def get_pipe_meta(self, name: str) -> "FactoryMeta":
            """Get the meta information for a given component name.

            name (str): The component name.
            RETURNS (FactoryMeta): The meta for the given component name.
            """
            if name not in self._pipe_meta:
                raise ValueError(Errors.E967.format(meta="component", name=name))
            return self._pipe_meta[name]

    Get the meta information for a given component name.

    name (str): The component name. RETURNS (FactoryMeta): The meta for the given component name.

  `def has_pipe(self, name: str) ‑> bool`
    Expand source code

        def has_pipe(self, name: str) -> bool:
            """Check if a component name is present in the pipeline. Equivalent to
            `name in nlp.pipe_names`.

            name (str): Name of the component.
            RETURNS (bool): Whether a component of the name exists in the pipeline.

            DOCS: https://spacy.io/api/language#has_pipe
            """
            return name in self.pipe_names

    Check if a component name is present in the pipeline. Equivalent to `name in nlp.pipe_names`.

    name (str): Name of the component. RETURNS (bool): Whether a component of the name exists in the pipeline.

    DOCS: https://spacy.io/api/language#has_pipe

  `def initialize(self,
  get_examples: Callable[[], Iterable[spacy.training.example.Example]] | None = None,
  *,
  sgd: thinc.optimizers.Optimizer | None = None) ‑> thinc.optimizers.Optimizer`
    Expand source code

        def initialize(
            self,
            get_examples: Optional[Callable[[], Iterable[Example]]] = None,
            *,
            sgd: Optional[Optimizer] = None,
        ) -> Optimizer:
            """Initialize the pipe for training, using data examples if available.

            get_examples (Callable[[], Iterable[Example]]): Optional function that
                returns gold-standard Example objects.
            sgd (Optional[Optimizer]): An optimizer to use for updates. If not
                provided, will be created using the .create_optimizer() method.
            RETURNS (thinc.api.Optimizer): The optimizer.

            DOCS: https://spacy.io/api/language#initialize
            """
            if get_examples is None:
                util.logger.debug(
                    "No 'get_examples' callback provided to 'Language.initialize', creating dummy examples"
                )
                doc = Doc(self.vocab, words=["x", "y", "z"])

                def get_examples():
                    return [Example.from_dict(doc, {})]

            if not hasattr(get_examples, "__call__"):
                err = Errors.E930.format(
                    method="Language.initialize", obj=type(get_examples)
                )
                raise TypeError(err)
            # Make sure the config is interpolated so we can resolve subsections
            config = self.config.interpolate()
            # These are the settings provided in the [initialize] block in the config
            I = registry.resolve(config["initialize"], schema=ConfigSchemaInit)
            before_init = I["before_init"]
            if before_init is not None:
                before_init(self)
            try:
                init_vocab(
                    self, data=I["vocab_data"], lookups=I["lookups"], vectors=I["vectors"]
                )
            except IOError:
                raise IOError(Errors.E884.format(vectors=I["vectors"]))
            if self.vocab.vectors.shape[1] >= 1:
                ops = get_current_ops()
                self.vocab.vectors.to_ops(ops)
            if hasattr(self.tokenizer, "initialize"):
                tok_settings = validate_init_settings(
                    self.tokenizer.initialize,  # type: ignore[union-attr]
                    I["tokenizer"],
                    section="tokenizer",
                    name="tokenizer",
                )
                self.tokenizer.initialize(get_examples, nlp=self, **tok_settings)  # type: ignore[union-attr]
            for name, proc in self.pipeline:
                if isinstance(proc, ty.InitializableComponent):
                    p_settings = I["components"].get(name, {})
                    p_settings = validate_init_settings(
                        proc.initialize, p_settings, section="components", name=name
                    )
                    proc.initialize(get_examples, nlp=self, **p_settings)
            pretrain_cfg = config.get("pretraining")
            if pretrain_cfg:
                P = registry.resolve(pretrain_cfg, schema=ConfigSchemaPretrain)
                init_tok2vec(self, P, I)
            self._link_components()
            self._optimizer = sgd
            if sgd is not None:
                self._optimizer = sgd
            elif self._optimizer is None:
                self._optimizer = self.create_optimizer()
            after_init = I["after_init"]
            if after_init is not None:
                after_init(self)
            return self._optimizer

    Initialize the pipe for training, using data examples if available.

    get_examples (Callable[[], Iterable[Example]]): Optional function that returns gold-standard Example objects. sgd (Optional[Optimizer]): An optimizer to use for updates. If not provided, will be created using the .create_optimizer() method. RETURNS (thinc.api.Optimizer): The optimizer.

    DOCS: https://spacy.io/api/language#initialize

  `def make_doc(self, text: str) ‑> spacy.tokens.doc.Doc`
    Expand source code

        def make_doc(self, text: str) -> Doc:
            """Turn a text into a Doc object.

            text (str): The text to process.
            RETURNS (Doc): The processed doc.
            """
            if len(text) > self.max_length:
                raise ValueError(
                    Errors.E088.format(length=len(text), max_length=self.max_length)
                )
            return self.tokenizer(text)

    Turn a text into a Doc object.

    text (str): The text to process. RETURNS (Doc): The processed doc.

  `def memory_zone(self, mem: cymem.cymem.Pool | None = None) ‑> Iterator[cymem.cymem.Pool]`
    Expand source code

        @contextmanager
        def memory_zone(self, mem: Optional[Pool] = None) -> Iterator[Pool]:
            """Begin a block where all resources allocated during the block will
            be freed at the end of it. If a resources was created within the
            memory zone block, accessing it outside the block is invalid.
            Behaviour of this invalid access is undefined. Memory zones should
            not be nested.

            The memory zone is helpful for services that need to process large
            volumes of text with a defined memory budget.

            Example
            -------
            >>> with nlp.memory_zone():
            ...     for doc in nlp.pipe(texts):
            ...        process_my_doc(doc)
            >>> # use_doc(doc) <-- Invalid: doc was allocated in the memory zone
            """
            if mem is None:
                mem = Pool()
            # The ExitStack allows programmatic nested context managers.
            # We don't know how many we need, so it would be awkward to have
            # them as nested blocks.
            with ExitStack() as stack:
                contexts = [stack.enter_context(self.vocab.memory_zone(mem))]
                if hasattr(self.tokenizer, "memory_zone"):
                    contexts.append(stack.enter_context(self.tokenizer.memory_zone(mem)))
                for _, pipe in self.pipeline:
                    if hasattr(pipe, "memory_zone"):
                        contexts.append(stack.enter_context(pipe.memory_zone(mem)))
                yield mem

    Begin a block where all resources allocated during the block will be freed at the end of it. If a resources was created within the memory zone block, accessing it outside the block is invalid. Behaviour of this invalid access is undefined. Memory zones should not be nested.

    The memory zone is helpful for services that need to process large volumes of text with a defined memory budget.

    ## Example

        >>> with nlp.memory_zone():
        ...     for doc in nlp.pipe(texts):
        ...        process_my_doc(doc)
        >>> # use_doc(doc) <-- Invalid: doc was allocated in the memory zone

  `def pipe(self,
  texts: Iterable[str | spacy.tokens.doc.Doc] | Iterable[Tuple[str | spacy.tokens.doc.Doc, ~_AnyContext]],
  *,
  as_tuples: bool = False,
  batch_size: int | None = None,
  disable: Iterable[str] = [],
  component_cfg: Dict[str, Dict[str, Any]] | None = None,
  n_process: int = 1) ‑> Iterator[spacy.tokens.doc.Doc] | Iterator[Tuple[spacy.tokens.doc.Doc, ~_AnyContext]]`
    Expand source code

        def pipe(  # noqa: F811
            self,
            texts: Union[
                Iterable[Union[str, Doc]], Iterable[Tuple[Union[str, Doc], _AnyContext]]
            ],
            *,
            as_tuples: bool = False,
            batch_size: Optional[int] = None,
            disable: Iterable[str] = SimpleFrozenList(),
            component_cfg: Optional[Dict[str, Dict[str, Any]]] = None,
            n_process: int = 1,
        ) -> Union[Iterator[Doc], Iterator[Tuple[Doc, _AnyContext]]]:
            """Process texts as a stream, and yield `Doc` objects in order.

            texts (Iterable[Union[str, Doc]]): A sequence of texts or docs to
                process.
            as_tuples (bool): If set to True, inputs should be a sequence of
                (text, context) tuples. Output will then be a sequence of
                (doc, context) tuples. Defaults to False.
            batch_size (Optional[int]): The number of texts to buffer.
            disable (List[str]): Names of the pipeline components to disable.
            component_cfg (Dict[str, Dict]): An optional dictionary with extra keyword
                arguments for specific components.
            n_process (int): Number of processors to process texts. If -1, set `multiprocessing.cpu_count()`.
            YIELDS (Doc): Documents in the order of the original text.

            DOCS: https://spacy.io/api/language#pipe
            """
            if as_tuples:
                texts = cast(Iterable[Tuple[Union[str, Doc], _AnyContext]], texts)
                docs_with_contexts = (
                    self._ensure_doc_with_context(text, context) for text, context in texts
                )
                docs = self.pipe(
                    docs_with_contexts,
                    batch_size=batch_size,
                    disable=disable,
                    n_process=n_process,
                    component_cfg=component_cfg,
                )
                for doc in docs:
                    context = doc._context
                    doc._context = None
                    yield (doc, context)
                return

            texts = cast(Iterable[Union[str, Doc]], texts)

            # Set argument defaults
            if n_process == -1:
                n_process = mp.cpu_count()
            if component_cfg is None:
                component_cfg = {}
            if batch_size is None:
                batch_size = self.batch_size

            pipes = (
                []
            )  # contains functools.partial objects to easily create multiprocess worker.
            for name, proc in self.pipeline:
                if name in disable:
                    continue
                kwargs = component_cfg.get(name, {})
                # Allow component_cfg to overwrite the top-level kwargs.
                kwargs.setdefault("batch_size", batch_size)
                f = functools.partial(
                    _pipe,
                    proc=proc,
                    name=name,
                    kwargs=kwargs,
                    default_error_handler=self.default_error_handler,
                )
                pipes.append(f)

            if n_process != 1:
                if self._has_gpu_model(disable):
                    warnings.warn(Warnings.W114)

                docs = self._multiprocessing_pipe(texts, pipes, n_process, batch_size)
            else:
                # if n_process == 1, no processes are forked.
                docs = (self._ensure_doc(text) for text in texts)
                for pipe in pipes:
                    docs = pipe(docs)
            for doc in docs:
                yield doc

    Process texts as a stream, and yield `Doc` objects in order.

    texts (Iterable[Union[str, Doc]]): A sequence of texts or docs to process. as_tuples (bool): If set to True, inputs should be a sequence of (text, context) tuples. Output will then be a sequence of (doc, context) tuples. Defaults to False. batch_size (Optional[int]): The number of texts to buffer. disable (List[str]): Names of the pipeline components to disable. component_cfg (Dict[str, Dict]): An optional dictionary with extra keyword arguments for specific components. n_process (int): Number of processors to process texts. If -1, set `multiprocessing.cpu_count()`. YIELDS (Doc): Documents in the order of the original text.

    DOCS: https://spacy.io/api/language#pipe

  `def rehearse(self,
  examples: Iterable[spacy.training.example.Example],
  *,
  sgd: thinc.optimizers.Optimizer | None = None,
  losses: Dict[str, float] | None = None,
  component_cfg: Dict[str, Dict[str, Any]] | None = None,
  exclude: Iterable[str] = []) ‑> Dict[str, float]`
    Expand source code

        def rehearse(
            self,
            examples: Iterable[Example],
            *,
            sgd: Optional[Optimizer] = None,
            losses: Optional[Dict[str, float]] = None,
            component_cfg: Optional[Dict[str, Dict[str, Any]]] = None,
            exclude: Iterable[str] = SimpleFrozenList(),
        ) -> Dict[str, float]:
            """Make a "rehearsal" update to the models in the pipeline, to prevent
            forgetting. Rehearsal updates run an initial copy of the model over some
            data, and update the model so its current predictions are more like the
            initial ones. This is useful for keeping a pretrained model on-track,
            even if you're updating it with a smaller set of examples.

            examples (Iterable[Example]): A batch of `Example` objects.
            sgd (Optional[Optimizer]): An optimizer.
            component_cfg (Dict[str, Dict]): Config parameters for specific pipeline
                components, keyed by component name.
            exclude (Iterable[str]): Names of components that shouldn't be updated.
            RETURNS (dict): Results from the update.

            EXAMPLE:
                >>> raw_text_batches = minibatch(raw_texts)
                >>> for labelled_batch in minibatch(examples):
                >>>     nlp.update(labelled_batch)
                >>>     raw_batch = [Example.from_dict(nlp.make_doc(text), {}) for text in next(raw_text_batches)]
                >>>     nlp.rehearse(raw_batch)

            DOCS: https://spacy.io/api/language#rehearse
            """
            if losses is None:
                losses = {}
            if isinstance(examples, list) and len(examples) == 0:
                return losses
            validate_examples(examples, "Language.rehearse")
            if sgd is None:
                if self._optimizer is None:
                    self._optimizer = self.create_optimizer()
                sgd = self._optimizer
            pipes = list(self.pipeline)
            random.shuffle(pipes)
            if component_cfg is None:
                component_cfg = {}
            grads = {}

            def get_grads(key, W, dW):
                grads[key] = (W, dW)
                return W, dW

            get_grads.learn_rate = sgd.learn_rate  # type: ignore[attr-defined, union-attr]
            get_grads.b1 = sgd.b1  # type: ignore[attr-defined, union-attr]
            get_grads.b2 = sgd.b2  # type: ignore[attr-defined, union-attr]
            for name, proc in pipes:
                if name in exclude or not hasattr(proc, "rehearse"):
                    continue
                grads = {}
                proc.rehearse(  # type: ignore[attr-defined]
                    examples, sgd=get_grads, losses=losses, **component_cfg.get(name, {})
                )
            for key, (W, dW) in grads.items():
                sgd(key, W, dW)  # type: ignore[call-arg, misc]
            return losses

    Make a "rehearsal" update to the models in the pipeline, to prevent forgetting. Rehearsal updates run an initial copy of the model over some data, and update the model so its current predictions are more like the initial ones. This is useful for keeping a pretrained model on-track, even if you're updating it with a smaller set of examples.

    examples (Iterable[Example]): A batch of `Example` objects. sgd (Optional[Optimizer]): An optimizer. component_cfg (Dict[str, Dict]): Config parameters for specific pipeline components, keyed by component name. exclude (Iterable[str]): Names of components that shouldn't be updated. RETURNS (dict): Results from the update.

    ## Example

        >>> raw_text_batches = minibatch(raw_texts)
        >>> for labelled_batch in minibatch(examples):
        >>>     nlp.update(labelled_batch)
        >>>     raw_batch = [Example.from_dict(nlp.make_doc(text), {}) for text in next(raw_text_batches)]
        >>>     nlp.rehearse(raw_batch)

    DOCS: https://spacy.io/api/language#rehearse

  `def remove_pipe(self, name: str) ‑> Tuple[str, Callable[[spacy.tokens.doc.Doc], spacy.tokens.doc.Doc]]`
    Expand source code

        def remove_pipe(self, name: str) -> Tuple[str, PipeCallable]:
            """Remove a component from the pipeline.

            name (str): Name of the component to remove.
            RETURNS (Tuple[str, Callable[[Doc], Doc]]): A `(name, component)` tuple of the removed component.

            DOCS: https://spacy.io/api/language#remove_pipe
            """
            if name not in self.component_names:
                raise ValueError(Errors.E001.format(name=name, opts=self.component_names))
            removed = self._components.pop(self.component_names.index(name))
            # We're only removing the component itself from the metas/configs here
            # because factory may be used for something else
            self._pipe_meta.pop(name)
            self._pipe_configs.pop(name)
            self.meta.get("_sourced_vectors_hashes", {}).pop(name, None)
            # Make sure name is removed from the [initialize] config
            if name in self._config["initialize"]["components"]:
                self._config["initialize"]["components"].pop(name)
            # Make sure the name is also removed from the set of disabled components
            if name in self.disabled:
                self._disabled.remove(name)
            self._link_components()
            return removed

    Remove a component from the pipeline.

    name (str): Name of the component to remove. RETURNS (Tuple[str, Callable[[Doc], Doc]]): A `(name, component)` tuple of the removed component.

    DOCS: https://spacy.io/api/language#remove_pipe

  `def rename_pipe(self, old_name: str, new_name: str) ‑> None`
    Expand source code

        def rename_pipe(self, old_name: str, new_name: str) -> None:
            """Rename a pipeline component.

            old_name (str): Name of the component to rename.
            new_name (str): New name of the component.

            DOCS: https://spacy.io/api/language#rename_pipe
            """
            if old_name not in self.component_names:
                raise ValueError(
                    Errors.E001.format(name=old_name, opts=self.component_names)
                )
            if new_name in self.component_names:
                raise ValueError(
                    Errors.E007.format(name=new_name, opts=self.component_names)
                )
            i = self.component_names.index(old_name)
            self._components[i] = (new_name, self._components[i][1])
            self._pipe_meta[new_name] = self._pipe_meta.pop(old_name)
            self._pipe_configs[new_name] = self._pipe_configs.pop(old_name)
            # Make sure [initialize] config is adjusted
            if old_name in self._config["initialize"]["components"]:
                init_cfg = self._config["initialize"]["components"].pop(old_name)
                self._config["initialize"]["components"][new_name] = init_cfg
            self._link_components()

    Rename a pipeline component.

    old_name (str): Name of the component to rename. new_name (str): New name of the component.

    DOCS: https://spacy.io/api/language#rename_pipe

  `def replace_listeners(self, tok2vec_name: str, pipe_name: str, listeners: Iterable[str]) ‑> None`
    Expand source code

        def replace_listeners(
            self,
            tok2vec_name: str,
            pipe_name: str,
            listeners: Iterable[str],
        ) -> None:
            """Find listener layers (connecting to a token-to-vector embedding
            component) of a given pipeline component model and replace
            them with a standalone copy of the token-to-vector layer. This can be
            useful when training a pipeline with components sourced from an existing
            pipeline: if multiple components (e.g. tagger, parser, NER) listen to
            the same tok2vec component, but some of them are frozen and not updated,
            their performance may degrade significantly as the tok2vec component is
            updated with new data. To prevent this, listeners can be replaced with
            a standalone tok2vec layer that is owned by the component and doesn't
            change if the component isn't updated.

            tok2vec_name (str): Name of the token-to-vector component, typically
                "tok2vec" or "transformer".
            pipe_name (str): Name of pipeline component to replace listeners for.
            listeners (Iterable[str]): The paths to the listeners, relative to the
                component config, e.g. ["model.tok2vec"]. Typically, implementations
                will only connect to one tok2vec component, [model.tok2vec], but in
                theory, custom models can use multiple listeners. The value here can
                either be an empty list to not replace any listeners, or a complete
                (!) list of the paths to all listener layers used by the model.

            DOCS: https://spacy.io/api/language#replace_listeners
            """
            if tok2vec_name not in self.pipe_names:
                err = Errors.E889.format(
                    tok2vec=tok2vec_name,
                    name=pipe_name,
                    unknown=tok2vec_name,
                    opts=", ".join(self.pipe_names),
                )
                raise ValueError(err)
            if pipe_name not in self.pipe_names:
                err = Errors.E889.format(
                    tok2vec=tok2vec_name,
                    name=pipe_name,
                    unknown=pipe_name,
                    opts=", ".join(self.pipe_names),
                )
                raise ValueError(err)
            tok2vec = self.get_pipe(tok2vec_name)
            tok2vec_cfg = self.get_pipe_config(tok2vec_name)
            if not isinstance(tok2vec, ty.ListenedToComponent):
                raise ValueError(Errors.E888.format(name=tok2vec_name, pipe=type(tok2vec)))
            tok2vec_model = tok2vec.model
            pipe_listeners = tok2vec.listener_map.get(pipe_name, [])
            pipe = self.get_pipe(pipe_name)
            pipe_cfg = self._pipe_configs[pipe_name]
            if listeners:
                util.logger.debug("Replacing listeners of component '%s'", pipe_name)
                if len(list(listeners)) != len(pipe_listeners):
                    # The number of listeners defined in the component model doesn't
                    # match the listeners to replace, so we won't be able to update
                    # the nodes and generate a matching config
                    err = Errors.E887.format(
                        name=pipe_name,
                        tok2vec=tok2vec_name,
                        paths=listeners,
                        n_listeners=len(pipe_listeners),
                    )
                    raise ValueError(err)
                # Update the config accordingly by copying the tok2vec model to all
                # sections defined in the listener paths
                for listener_path in listeners:
                    # Check if the path actually exists in the config
                    try:
                        util.dot_to_object(pipe_cfg, listener_path)
                    except KeyError:
                        err = Errors.E886.format(
                            name=pipe_name, tok2vec=tok2vec_name, path=listener_path
                        )
                        raise ValueError(err)
                    new_config = tok2vec_cfg["model"]
                    if "replace_listener_cfg" in tok2vec_model.attrs:
                        replace_func = tok2vec_model.attrs["replace_listener_cfg"]
                        new_config = replace_func(
                            tok2vec_cfg["model"], pipe_cfg["model"]["tok2vec"]
                        )
                    util.set_dot_to_object(pipe_cfg, listener_path, new_config)
                # Go over the listener layers and replace them
                for listener in pipe_listeners:
                    new_model = tok2vec_model.copy()
                    replace_listener_func = tok2vec_model.attrs.get("replace_listener")
                    if replace_listener_func is not None:
                        # Pass the extra args to the callback without breaking compatibility with
                        # old library versions that only expect a single parameter.
                        num_params = len(
                            inspect.signature(replace_listener_func).parameters
                        )
                        if num_params == 1:
                            new_model = replace_listener_func(new_model)
                        elif num_params == 3:
                            new_model = replace_listener_func(new_model, listener, tok2vec)
                        else:
                            raise ValueError(Errors.E1055.format(num_params=num_params))

                    util.replace_model_node(pipe.model, listener, new_model)  # type: ignore[attr-defined]
                    tok2vec.remove_listener(listener, pipe_name)

    Find listener layers (connecting to a token-to-vector embedding component) of a given pipeline component model and replace them with a standalone copy of the token-to-vector layer. This can be useful when training a pipeline with components sourced from an existing pipeline: if multiple components (e.g. tagger, parser, NER) listen to the same tok2vec component, but some of them are frozen and not updated, their performance may degrade significantly as the tok2vec component is updated with new data. To prevent this, listeners can be replaced with a standalone tok2vec layer that is owned by the component and doesn't change if the component isn't updated.

    tok2vec_name (str): Name of the token-to-vector component, typically "tok2vec" or "transformer". pipe_name (str): Name of pipeline component to replace listeners for. listeners (Iterable[str]): The paths to the listeners, relative to the component config, e.g. ["model.tok2vec"]. Typically, implementations will only connect to one tok2vec component, [model.tok2vec], but in theory, custom models can use multiple listeners. The value here can either be an empty list to not replace any listeners, or a complete (!) list of the paths to all listener layers used by the model.

    DOCS: https://spacy.io/api/language#replace_listeners

  `def replace_pipe(self,
  name: str,
  factory_name: str,
  *,
  config: Dict[str, Any] = {},
  validate: bool = True) ‑> Callable[[spacy.tokens.doc.Doc], spacy.tokens.doc.Doc]`
    Expand source code

        def replace_pipe(
            self,
            name: str,
            factory_name: str,
            *,
            config: Dict[str, Any] = SimpleFrozenDict(),
            validate: bool = True,
        ) -> PipeCallable:
            """Replace a component in the pipeline.

            name (str): Name of the component to replace.
            factory_name (str): Factory name of replacement component.
            config (Optional[Dict[str, Any]]): Config parameters to use for this
                component. Will be merged with default config, if available.
            validate (bool): Whether to validate the component config against the
                arguments and types expected by the factory.
            RETURNS (Callable[[Doc], Doc]): The new pipeline component.

            DOCS: https://spacy.io/api/language#replace_pipe
            """
            if name not in self.component_names:
                raise ValueError(Errors.E001.format(name=name, opts=self.pipe_names))
            if hasattr(factory_name, "__call__"):
                err = Errors.E968.format(component=repr(factory_name), name=name)
                raise ValueError(err)
            # We need to delegate to Language.add_pipe here instead of just writing
            # to Language.pipeline to make sure the configs are handled correctly
            pipe_index = self.component_names.index(name)
            self.remove_pipe(name)
            if not len(self._components) or pipe_index == len(self._components):
                # we have no components to insert before/after, or we're replacing the last component
                return self.add_pipe(
                    factory_name, name=name, config=config, validate=validate
                )
            else:
                return self.add_pipe(
                    factory_name,
                    name=name,
                    before=pipe_index,
                    config=config,
                    validate=validate,
                )

    Replace a component in the pipeline.

    name (str): Name of the component to replace. factory_name (str): Factory name of replacement component. config (Optional[Dict[str, Any]]): Config parameters to use for this component. Will be merged with default config, if available. validate (bool): Whether to validate the component config against the arguments and types expected by the factory. RETURNS (Callable[[Doc], Doc]): The new pipeline component.

    DOCS: https://spacy.io/api/language#replace_pipe

  `def resume_training(self, *, sgd: thinc.optimizers.Optimizer | None = None) ‑> thinc.optimizers.Optimizer`
    Expand source code

        def resume_training(self, *, sgd: Optional[Optimizer] = None) -> Optimizer:
            """Continue training a pretrained model.

            Create and return an optimizer, and initialize "rehearsal" for any pipeline
            component that has a .rehearse() method. Rehearsal is used to prevent
            models from "forgetting" their initialized "knowledge". To perform
            rehearsal, collect samples of text you want the models to retain performance
            on, and call nlp.rehearse() with a batch of Example objects.

            RETURNS (Optimizer): The optimizer.

            DOCS: https://spacy.io/api/language#resume_training
            """
            ops = get_current_ops()
            if self.vocab.vectors.shape[1] >= 1:
                self.vocab.vectors.to_ops(ops)
            for name, proc in self.pipeline:
                if hasattr(proc, "_rehearsal_model"):
                    proc._rehearsal_model = deepcopy(proc.model)  # type: ignore[attr-defined]
            if sgd is not None:
                self._optimizer = sgd
            elif self._optimizer is None:
                self._optimizer = self.create_optimizer()
            return self._optimizer

    Continue training a pretrained model.

    Create and return an optimizer, and initialize "rehearsal" for any pipeline component that has a .rehearse() method. Rehearsal is used to prevent models from "forgetting" their initialized "knowledge". To perform rehearsal, collect samples of text you want the models to retain performance on, and call nlp.rehearse() with a batch of Example objects.

    RETURNS (Optimizer): The optimizer.

    DOCS: https://spacy.io/api/language#resume_training

  `def select_pipes(self,
  *,
  disable: str | Iterable[str] | None = None,
  enable: str | Iterable[str] | None = None) ‑> spacy.language.DisabledPipes`
    Expand source code

        def select_pipes(
            self,
            *,
            disable: Optional[Union[str, Iterable[str]]] = None,
            enable: Optional[Union[str, Iterable[str]]] = None,
        ) -> "DisabledPipes":
            """Disable one or more pipeline components. If used as a context
            manager, the pipeline will be restored to the initial state at the end
            of the block. Otherwise, a DisabledPipes object is returned, that has
            a `.restore()` method you can use to undo your changes.

            disable (str or iterable): The name(s) of the pipes to disable
            enable (str or iterable): The name(s) of the pipes to enable - all others will be disabled

            DOCS: https://spacy.io/api/language#select_pipes
            """
            if enable is None and disable is None:
                raise ValueError(Errors.E991)
            if isinstance(disable, str):
                disable = [disable]
            if enable is not None:
                if isinstance(enable, str):
                    enable = [enable]
                to_disable = [pipe for pipe in self.pipe_names if pipe not in enable]
                # raise an error if the enable and disable keywords are not consistent
                if disable is not None and disable != to_disable:
                    raise ValueError(
                        Errors.E992.format(
                            enable=enable, disable=disable, names=self.pipe_names
                        )
                    )
                disable = to_disable
            assert disable is not None
            # DisabledPipes will restore the pipes in 'disable' when it's done, so we need to exclude
            # those pipes that were already disabled.
            disable = [d for d in disable if d not in self._disabled]
            return DisabledPipes(self, disable)

    Disable one or more pipeline components. If used as a context manager, the pipeline will be restored to the initial state at the end of the block. Otherwise, a DisabledPipes object is returned, that has a `.restore()` method you can use to undo your changes.

    disable (str or iterable): The name(s) of the pipes to disable enable (str or iterable): The name(s) of the pipes to enable - all others will be disabled

    DOCS: https://spacy.io/api/language#select_pipes

  `def set_error_handler(self,
  error_handler: Callable[[str, Callable[[spacy.tokens.doc.Doc], spacy.tokens.doc.Doc], List[spacy.tokens.doc.Doc], Exception], NoReturn])`
    Expand source code

        def set_error_handler(
            self,
            error_handler: Callable[[str, PipeCallable, List[Doc], Exception], NoReturn],
        ):
            """Set an error handler object for all the components in the pipeline
            that implement a set_error_handler function.

            error_handler (Callable[[str, Callable[[Doc], Doc], List[Doc], Exception], NoReturn]):
                Function that deals with a failing batch of documents. This callable
                function should take in the component's name, the component itself,
                the offending batch of documents, and the exception that was thrown.
            DOCS: https://spacy.io/api/language#set_error_handler
            """
            self.default_error_handler = error_handler
            for name, pipe in self.pipeline:
                if hasattr(pipe, "set_error_handler"):
                    pipe.set_error_handler(error_handler)

    Set an error handler object for all the components in the pipeline that implement a set_error_handler function.

    error_handler (Callable[[str, Callable[[Doc], Doc], List[Doc], Exception], NoReturn]): Function that deals with a failing batch of documents. This callable function should take in the component's name, the component itself, the offending batch of documents, and the exception that was thrown. DOCS: https://spacy.io/api/language#set_error_handler

  `def to_bytes(self, *, exclude: Iterable[str] = []) ‑> bytes`
    Expand source code

        def to_bytes(self, *, exclude: Iterable[str] = SimpleFrozenList()) -> bytes:
            """Serialize the current state to a binary string.

            exclude (Iterable[str]): Names of components or serialization fields to exclude.
            RETURNS (bytes): The serialized form of the `Language` object.

            DOCS: https://spacy.io/api/language#to_bytes
            """
            serializers: Dict[str, Callable[[], bytes]] = {}
            serializers["vocab"] = lambda: self.vocab.to_bytes(exclude=exclude)
            serializers["tokenizer"] = lambda: self.tokenizer.to_bytes(exclude=["vocab"])  # type: ignore[union-attr]
            serializers["meta.json"] = lambda: srsly.json_dumps(
                _replace_numpy_floats(self.meta)
            )
            serializers["config.cfg"] = lambda: self.config.to_bytes()
            for name, proc in self._components:
                if name in exclude:
                    continue
                if not hasattr(proc, "to_bytes"):
                    continue
                serializers[name] = lambda proc=proc: proc.to_bytes(exclude=["vocab"])  # type: ignore[misc]
            return util.to_bytes(serializers, exclude)

    Serialize the current state to a binary string.

    exclude (Iterable[str]): Names of components or serialization fields to exclude. RETURNS (bytes): The serialized form of the `Language` object.

    DOCS: https://spacy.io/api/language#to_bytes

  `def to_disk(self, path: str | pathlib.Path, *, exclude: Iterable[str] = []) ‑> None`
    Expand source code

        def to_disk(
            self, path: Union[str, Path], *, exclude: Iterable[str] = SimpleFrozenList()
        ) -> None:
            """Save the current state to a directory.  If a model is loaded, this
            will include the model.

            path (str / Path): Path to a directory, which will be created if
                it doesn't exist.
            exclude (Iterable[str]): Names of components or serialization fields to exclude.

            DOCS: https://spacy.io/api/language#to_disk
            """
            path = util.ensure_path(path)
            serializers = {}
            serializers["tokenizer"] = lambda p: self.tokenizer.to_disk(  # type: ignore[union-attr]
                p, exclude=["vocab"]
            )
            serializers["meta.json"] = lambda p: srsly.write_json(
                p, _replace_numpy_floats(self.meta)
            )
            serializers["config.cfg"] = lambda p: self.config.to_disk(p)
            for name, proc in self._components:
                if name in exclude:
                    continue
                if not hasattr(proc, "to_disk"):
                    continue
                serializers[name] = lambda p, proc=proc: proc.to_disk(p, exclude=["vocab"])  # type: ignore[misc]
            serializers["vocab"] = lambda p: self.vocab.to_disk(p, exclude=exclude)
            util.to_disk(path, serializers, exclude)

    Save the current state to a directory. If a model is loaded, this will include the model.

    path (str / Path): Path to a directory, which will be created if it doesn't exist. exclude (Iterable[str]): Names of components or serialization fields to exclude.

    DOCS: https://spacy.io/api/language#to_disk

  `def update(self,
  examples: Iterable[spacy.training.example.Example],
  *,
  drop: float = 0.0,
  sgd: thinc.optimizers.Optimizer | None = None,
  losses: Dict[str, float] | None = None,
  component_cfg: Dict[str, Dict[str, Any]] | None = None,
  exclude: Iterable[str] = [],
  annotates: Iterable[str] = [])`
    Expand source code

        def update(
            self,
            examples: Iterable[Example],
            _: Optional[Any] = None,
            *,
            drop: float = 0.0,
            sgd: Optional[Optimizer] = None,
            losses: Optional[Dict[str, float]] = None,
            component_cfg: Optional[Dict[str, Dict[str, Any]]] = None,
            exclude: Iterable[str] = SimpleFrozenList(),
            annotates: Iterable[str] = SimpleFrozenList(),
        ):
            """Update the models in the pipeline.

            examples (Iterable[Example]): A batch of examples
            _: Should not be set - serves to catch backwards-incompatible scripts.
            drop (float): The dropout rate.
            sgd (Optimizer): An optimizer.
            losses (Dict[str, float]): Dictionary to update with the loss, keyed by
                component.
            component_cfg (Dict[str, Dict]): Config parameters for specific pipeline
                components, keyed by component name.
            exclude (Iterable[str]): Names of components that shouldn't be updated.
            annotates (Iterable[str]): Names of components that should set
                annotations on the predicted examples after updating.
            RETURNS (Dict[str, float]): The updated losses dictionary

            DOCS: https://spacy.io/api/language#update
            """
            if _ is not None:
                raise ValueError(Errors.E989)
            if losses is None:
                losses = {}
            if isinstance(examples, list) and len(examples) == 0:
                return losses
            validate_examples(examples, "Language.update")
            examples = _copy_examples(examples)
            if sgd is None:
                if self._optimizer is None:
                    self._optimizer = self.create_optimizer()
                sgd = self._optimizer
            if component_cfg is None:
                component_cfg = {}
            pipe_kwargs = {}
            for i, (name, proc) in enumerate(self.pipeline):
                component_cfg.setdefault(name, {})
                pipe_kwargs[name] = deepcopy(component_cfg[name])
                component_cfg[name].setdefault("drop", drop)
                pipe_kwargs[name].setdefault("batch_size", self.batch_size)
            for name, proc in self.pipeline:
                # ignore statements are used here because mypy ignores hasattr
                if name not in exclude and hasattr(proc, "update"):
                    proc.update(examples, sgd=None, losses=losses, **component_cfg[name])  # type: ignore
                if sgd not in (None, False):
                    if (
                        name not in exclude
                        and isinstance(proc, ty.TrainableComponent)
                        and proc.is_trainable
                        and proc.model not in (True, False, None)
                    ):
                        proc.finish_update(sgd)
                if name in annotates:
                    for doc, eg in zip(
                        _pipe(
                            (eg.predicted for eg in examples),
                            proc=proc,
                            name=name,
                            default_error_handler=self.default_error_handler,
                            kwargs=pipe_kwargs[name],
                        ),
                        examples,
                    ):
                        eg.predicted = doc
            return _replace_numpy_floats(losses)

    Update the models in the pipeline.

    examples (Iterable[Example]): A batch of examples _: Should not be set - serves to catch backwards-incompatible scripts. drop (float): The dropout rate. sgd (Optimizer): An optimizer. losses (Dict[str, float]): Dictionary to update with the loss, keyed by component. component_cfg (Dict[str, Dict]): Config parameters for specific pipeline components, keyed by component name. exclude (Iterable[str]): Names of components that shouldn't be updated. annotates (Iterable[str]): Names of components that should set annotations on the predicted examples after updating. RETURNS (Dict[str, float]): The updated losses dictionary

    DOCS: https://spacy.io/api/language#update

  `def use_params(self, params: dict | None)`
    Expand source code

        @contextmanager
        def use_params(self, params: Optional[dict]):
            """Replace weights of models in the pipeline with those provided in the
            params dictionary. Can be used as a contextmanager, in which case,
            models go back to their original weights after the block.

            params (dict): A dictionary of parameters keyed by model ID.

            EXAMPLE:
                >>> with nlp.use_params(optimizer.averages):
                >>>     nlp.to_disk("/tmp/checkpoint")

            DOCS: https://spacy.io/api/language#use_params
            """
            if not params:
                yield
            else:
                contexts = [
                    pipe.use_params(params)  # type: ignore[attr-defined]
                    for name, pipe in self.pipeline
                    if hasattr(pipe, "use_params") and hasattr(pipe, "model")
                ]
                # TODO: Having trouble with contextlib
                # Workaround: these aren't actually context managers atm.
                for context in contexts:
                    try:
                        next(context)
                    except StopIteration:
                        pass
                yield
                for context in contexts:
                    try:
                        next(context)
                    except StopIteration:
                        pass

    Replace weights of models in the pipeline with those provided in the params dictionary. Can be used as a contextmanager, in which case, models go back to their original weights after the block.

    params (dict): A dictionary of parameters keyed by model ID.

    ## Example

        >>> with nlp.use_params(optimizer.averages):
        >>>     nlp.to_disk("/tmp/checkpoint")

    DOCS: https://spacy.io/api/language#use_params

`class SentenceTransformer (model_name_or_path: str | None = None,
modules: Iterable[nn.Module] | None = None,
device: str | None = None,
prompts: dict[str, str] | None = None,
default_prompt_name: str | None = None,
similarity_fn_name: str | SimilarityFunction | None = None,
cache_folder: str | None = None,
trust_remote_code: bool = False,
revision: str | None = None,
local_files_only: bool = False,
token: bool | str | None = None,
use_auth_token: bool | str | None = None,
truncate_dim: int | None = None,
model_kwargs: dict[str, Any] | None = None,
tokenizer_kwargs: dict[str, Any] | None = None,
config_kwargs: dict[str, Any] | None = None,
model_card_data: SentenceTransformerModelCardData | None = None,
backend: "Literal['torch', 'onnx', 'openvino']" = 'torch')`
  Expand source code

      class SentenceTransformer(nn.Sequential, FitMixin, PeftAdapterMixin):
          """
          Loads or creates a SentenceTransformer model that can be used to map sentences / text to embeddings.

          Args:
              model_name_or_path (str, optional): If it is a filepath on disc, it loads the model from that path. If it is not a path,
                  it first tries to download a pre-trained SentenceTransformer model. If that fails, tries to construct a model
                  from the Hugging Face Hub with that name.
              modules (Iterable[nn.Module], optional): A list of torch Modules that should be called sequentially, can be used to create custom
                  SentenceTransformer models from scratch.
              device (str, optional): Device (like "cuda", "cpu", "mps", "npu") that should be used for computation. If None, checks if a GPU
                  can be used.
              prompts (Dict[str, str], optional): A dictionary with prompts for the model. The key is the prompt name, the value is the prompt text.
                  The prompt text will be prepended before any text to encode. For example:
                  `{"query": "query: ", "passage": "passage: "}` or `{"clustering": "Identify the main category based on the
                  titles in "}`.
              default_prompt_name (str, optional): The name of the prompt that should be used by default. If not set,
                  no prompt will be applied.
              similarity_fn_name (str or SimilarityFunction, optional): The name of the similarity function to use. Valid options are "cosine", "dot",
                  "euclidean", and "manhattan". If not set, it is automatically set to "cosine" if `similarity` or
                  `similarity_pairwise` are called while `model.similarity_fn_name` is still `None`.
              cache_folder (str, optional): Path to store models. Can also be set by the SENTENCE_TRANSFORMERS_HOME environment variable.
              trust_remote_code (bool, optional): Whether or not to allow for custom models defined on the Hub in their own modeling files.
                  This option should only be set to True for repositories you trust and in which you have read the code, as it
                  will execute code present on the Hub on your local machine.
              revision (str, optional): The specific model version to use. It can be a branch name, a tag name, or a commit id,
                  for a stored model on Hugging Face.
              local_files_only (bool, optional): Whether or not to only look at local files (i.e., do not try to download the model).
              token (bool or str, optional): Hugging Face authentication token to download private models.
              use_auth_token (bool or str, optional): Deprecated argument. Please use `token` instead.
              truncate_dim (int, optional): The dimension to truncate sentence embeddings to. `None` does no truncation. Truncation is
                  only applicable during inference when :meth:`SentenceTransformer.encode` is called.
              model_kwargs (Dict[str, Any], optional): Additional model configuration parameters to be passed to the Hugging Face Transformers model.
                  Particularly useful options are:

                  - ``torch_dtype``: Override the default `torch.dtype` and load the model under a specific `dtype`.
                    The different options are:

                          1. ``torch.float16``, ``torch.bfloat16`` or ``torch.float``: load in a specified
                          ``dtype``, ignoring the model's ``config.torch_dtype`` if one exists. If not specified - the model will
                          get loaded in ``torch.float`` (fp32).

                          2. ``"auto"`` - A ``torch_dtype`` entry in the ``config.json`` file of the model will be
                          attempted to be used. If this entry isn't found then next check the ``dtype`` of the first weight in
                          the checkpoint that's of a floating point type and use that as ``dtype``. This will load the model
                          using the ``dtype`` it was saved in at the end of the training. It can't be used as an indicator of how
                          the model was trained. Since it could be trained in one of half precision dtypes, but saved in fp32.
                  - ``attn_implementation``: The attention implementation to use in the model (if relevant). Can be any of
                    `"eager"` (manual implementation of the attention), `"sdpa"` (using `F.scaled_dot_product_attention
                    <https://pytorch.org/docs/master/generated/torch.nn.functional.scaled_dot_product_attention.html>`_),
                    or `"flash_attention_2"` (using `Dao-AILab/flash-attention <https://github.com/Dao-AILab/flash-attention>`_).
                    By default, if available, SDPA will be used for torch>=2.1.1. The default is otherwise the manual `"eager"`
                    implementation.
                  - ``provider``: If backend is "onnx", this is the provider to use for inference, for example "CPUExecutionProvider",
                    "CUDAExecutionProvider", etc. See https://onnxruntime.ai/docs/execution-providers/ for all ONNX execution providers.
                  - ``file_name``: If backend is "onnx" or "openvino", this is the file name to load, useful for loading optimized
                    or quantized ONNX or OpenVINO models.
                  - ``export``: If backend is "onnx" or "openvino", then this is a boolean flag specifying whether this model should
                    be exported to the backend. If not specified, the model will be exported only if the model repository or directory
                    does not already contain an exported model.

                  See the `PreTrainedModel.from_pretrained
                  <https://huggingface.co/docs/transformers/en/main_classes/model#transformers.PreTrainedModel.from_pretrained>`_
                  documentation for more details.
              tokenizer_kwargs (Dict[str, Any], optional): Additional tokenizer configuration parameters to be passed to the Hugging Face Transformers tokenizer.
                  See the `AutoTokenizer.from_pretrained
                  <https://huggingface.co/docs/transformers/en/model_doc/auto#transformers.AutoTokenizer.from_pretrained>`_
                  documentation for more details.
              config_kwargs (Dict[str, Any], optional): Additional model configuration parameters to be passed to the Hugging Face Transformers config.
                  See the `AutoConfig.from_pretrained
                  <https://huggingface.co/docs/transformers/en/model_doc/auto#transformers.AutoConfig.from_pretrained>`_
                  documentation for more details.
              model_card_data (:class:`~sentence_transformers.model_card.SentenceTransformerModelCardData`, optional): A model
                  card data object that contains information about the model. This is used to generate a model card when saving
                  the model. If not set, a default model card data object is created.
              backend (str): The backend to use for inference. Can be one of "torch" (default), "onnx", or "openvino".
                  See https://sbert.net/docs/sentence_transformer/usage/efficiency.html for benchmarking information
                  on the different backends.

          Example:
              ::

                  from sentence_transformers import SentenceTransformer

                  # Load a pre-trained SentenceTransformer model
                  model = SentenceTransformer('all-mpnet-base-v2')

                  # Encode some texts
                  sentences = [
                      "The weather is lovely today.",
                      "It's so sunny outside!",
                      "He drove to the stadium.",
                  ]
                  embeddings = model.encode(sentences)
                  print(embeddings.shape)
                  # (3, 768)

                  # Get the similarity scores between all sentences
                  similarities = model.similarity(embeddings, embeddings)
                  print(similarities)
                  # tensor([[1.0000, 0.6817, 0.0492],
                  #         [0.6817, 1.0000, 0.0421],
                  #         [0.0492, 0.0421, 1.0000]])
          """

          def __init__(
              self,
              model_name_or_path: str | None = None,
              modules: Iterable[nn.Module] | None = None,
              device: str | None = None,
              prompts: dict[str, str] | None = None,
              default_prompt_name: str | None = None,
              similarity_fn_name: str | SimilarityFunction | None = None,
              cache_folder: str | None = None,
              trust_remote_code: bool = False,
              revision: str | None = None,
              local_files_only: bool = False,
              token: bool | str | None = None,
              use_auth_token: bool | str | None = None,
              truncate_dim: int | None = None,
              model_kwargs: dict[str, Any] | None = None,
              tokenizer_kwargs: dict[str, Any] | None = None,
              config_kwargs: dict[str, Any] | None = None,
              model_card_data: SentenceTransformerModelCardData | None = None,
              backend: Literal["torch", "onnx", "openvino"] = "torch",
          ) -> None:
              # Note: self._load_sbert_model can also update `self.prompts` and `self.default_prompt_name`
              self.prompts = prompts or {}
              self.default_prompt_name = default_prompt_name
              self.similarity_fn_name = similarity_fn_name
              self.trust_remote_code = trust_remote_code
              self.truncate_dim = truncate_dim
              self.model_card_data = model_card_data or SentenceTransformerModelCardData()
              self.module_kwargs = None
              self._model_card_vars = {}
              self._model_card_text = None
              self._model_config = {}
              self.backend = backend
              if use_auth_token is not None:
                  warnings.warn(
                      "The `use_auth_token` argument is deprecated and will be removed in v4 of SentenceTransformers.",
                      FutureWarning,
                  )
                  if token is not None:
                      raise ValueError(
                          "`token` and `use_auth_token` are both specified. Please set only the argument `token`."
                      )
                  token = use_auth_token

              if cache_folder is None:
                  cache_folder = os.getenv("SENTENCE_TRANSFORMERS_HOME")

              if device is None:
                  device = get_device_name()
                  logger.info(f"Use pytorch device_name: {device}")

              if device == "hpu" and importlib.util.find_spec("optimum") is not None:
                  from optimum.habana.transformers.modeling_utils import adapt_transformers_to_gaudi

                  adapt_transformers_to_gaudi()

              if model_name_or_path is not None and model_name_or_path != "":
                  logger.info(f"Load pretrained SentenceTransformer: {model_name_or_path}")

                  # Old models that don't belong to any organization
                  basic_transformer_models = [
                      "albert-base-v1",
                      "albert-base-v2",
                      "albert-large-v1",
                      "albert-large-v2",
                      "albert-xlarge-v1",
                      "albert-xlarge-v2",
                      "albert-xxlarge-v1",
                      "albert-xxlarge-v2",
                      "bert-base-cased-finetuned-mrpc",
                      "bert-base-cased",
                      "bert-base-chinese",
                      "bert-base-german-cased",
                      "bert-base-german-dbmdz-cased",
                      "bert-base-german-dbmdz-uncased",
                      "bert-base-multilingual-cased",
                      "bert-base-multilingual-uncased",
                      "bert-base-uncased",
                      "bert-large-cased-whole-word-masking-finetuned-squad",
                      "bert-large-cased-whole-word-masking",
                      "bert-large-cased",
                      "bert-large-uncased-whole-word-masking-finetuned-squad",
                      "bert-large-uncased-whole-word-masking",
                      "bert-large-uncased",
                      "camembert-base",
                      "ctrl",
                      "distilbert-base-cased-distilled-squad",
                      "distilbert-base-cased",
                      "distilbert-base-german-cased",
                      "distilbert-base-multilingual-cased",
                      "distilbert-base-uncased-distilled-squad",
                      "distilbert-base-uncased-finetuned-sst-2-english",
                      "distilbert-base-uncased",
                      "distilgpt2",
                      "distilroberta-base",
                      "gpt2-large",
                      "gpt2-medium",
                      "gpt2-xl",
                      "gpt2",
                      "openai-gpt",
                      "roberta-base-openai-detector",
                      "roberta-base",
                      "roberta-large-mnli",
                      "roberta-large-openai-detector",
                      "roberta-large",
                      "t5-11b",
                      "t5-3b",
                      "t5-base",
                      "t5-large",
                      "t5-small",
                      "transfo-xl-wt103",
                      "xlm-clm-ende-1024",
                      "xlm-clm-enfr-1024",
                      "xlm-mlm-100-1280",
                      "xlm-mlm-17-1280",
                      "xlm-mlm-en-2048",
                      "xlm-mlm-ende-1024",
                      "xlm-mlm-enfr-1024",
                      "xlm-mlm-enro-1024",
                      "xlm-mlm-tlm-xnli15-1024",
                      "xlm-mlm-xnli15-1024",
                      "xlm-roberta-base",
                      "xlm-roberta-large-finetuned-conll02-dutch",
                      "xlm-roberta-large-finetuned-conll02-spanish",
                      "xlm-roberta-large-finetuned-conll03-english",
                      "xlm-roberta-large-finetuned-conll03-german",
                      "xlm-roberta-large",
                      "xlnet-base-cased",
                      "xlnet-large-cased",
                  ]

                  if not os.path.exists(model_name_or_path):
                      # Not a path, load from hub
                      if "\\" in model_name_or_path or model_name_or_path.count("/") > 1:
                          raise ValueError(f"Path {model_name_or_path} not found")

                      if "/" not in model_name_or_path and model_name_or_path.lower() not in basic_transformer_models:
                          # A model from sentence-transformers
                          model_name_or_path = __MODEL_HUB_ORGANIZATION__ + "/" + model_name_or_path

                  if is_sentence_transformer_model(
                      model_name_or_path,
                      token,
                      cache_folder=cache_folder,
                      revision=revision,
                      local_files_only=local_files_only,
                  ):
                      modules, self.module_kwargs = self._load_sbert_model(
                          model_name_or_path,
                          token=token,
                          cache_folder=cache_folder,
                          revision=revision,
                          trust_remote_code=trust_remote_code,
                          local_files_only=local_files_only,
                          model_kwargs=model_kwargs,
                          tokenizer_kwargs=tokenizer_kwargs,
                          config_kwargs=config_kwargs,
                      )
                  else:
                      modules = self._load_auto_model(
                          model_name_or_path,
                          token=token,
                          cache_folder=cache_folder,
                          revision=revision,
                          trust_remote_code=trust_remote_code,
                          local_files_only=local_files_only,
                          model_kwargs=model_kwargs,
                          tokenizer_kwargs=tokenizer_kwargs,
                          config_kwargs=config_kwargs,
                      )

              if modules is not None and not isinstance(modules, OrderedDict):
                  modules = OrderedDict([(str(idx), module) for idx, module in enumerate(modules)])

              super().__init__(modules)

              # Ensure all tensors in the model are of the same dtype as the first tensor
              # This is necessary if the first module has been given a lower precision via
              # model_kwargs["torch_dtype"]. The rest of the model should be loaded in the same dtype
              # See #2887 for more details
              try:
                  dtype = next(self.parameters()).dtype
                  self.to(dtype)
              except StopIteration:
                  pass

              self.to(device)
              self.is_hpu_graph_enabled = False

              if self.default_prompt_name is not None and self.default_prompt_name not in self.prompts:
                  raise ValueError(
                      f"Default prompt name '{self.default_prompt_name}' not found in the configured prompts "
                      f"dictionary with keys {list(self.prompts.keys())!r}."
                  )

              if self.prompts:
                  logger.info(f"{len(self.prompts)} prompts are loaded, with the keys: {list(self.prompts.keys())}")
              if self.default_prompt_name:
                  logger.warning(
                      f"Default prompt name is set to '{self.default_prompt_name}'. "
                      "This prompt will be applied to all `encode()` calls, except if `encode()` "
                      "is called with `prompt` or `prompt_name` parameters."
                  )

              # Ideally, INSTRUCTOR models should set `include_prompt=False` in their pooling configuration, but
              # that would be a breaking change for users currently using the InstructorEmbedding project.
              # So, instead we hardcode setting it for the main INSTRUCTOR models, and otherwise give a warning if we
              # suspect the user is using an INSTRUCTOR model.
              if model_name_or_path in ("hkunlp/instructor-base", "hkunlp/instructor-large", "hkunlp/instructor-xl"):
                  self.set_pooling_include_prompt(include_prompt=False)
              elif (
                  model_name_or_path
                  and "/" in model_name_or_path
                  and "instructor" in model_name_or_path.split("/")[1].lower()
              ):
                  if any([module.include_prompt for module in self if isinstance(module, Pooling)]):
                      logger.warning(
                          "Instructor models require `include_prompt=False` in the pooling configuration. "
                          "Either update the model configuration or call `model.set_pooling_include_prompt(False)` after loading the model."
                      )

              # Pass the model to the model card data for later use in generating a model card upon saving this model
              self.model_card_data.register_model(self)

          def get_backend(self) -> Literal["torch", "onnx", "openvino"]:
              """Return the backend used for inference, which can be one of "torch", "onnx", or "openvino".

              Returns:
                  str: The backend used for inference.
              """
              return self.backend

          @overload
          def encode(
              self,
              sentences: str,
              prompt_name: str | None = ...,
              prompt: str | None = ...,
              batch_size: int = ...,
              show_progress_bar: bool | None = ...,
              output_value: Literal["sentence_embedding", "token_embeddings"] | None = ...,
              precision: Literal["float32", "int8", "uint8", "binary", "ubinary"] = ...,
              convert_to_numpy: Literal[False] = ...,
              convert_to_tensor: Literal[False] = ...,
              device: str = ...,
              normalize_embeddings: bool = ...,
              **kwargs,
          ) -> Tensor: ...

          @overload
          def encode(
              self,
              sentences: str | list[str],
              prompt_name: str | None = ...,
              prompt: str | None = ...,
              batch_size: int = ...,
              show_progress_bar: bool | None = ...,
              output_value: Literal["sentence_embedding", "token_embeddings"] | None = ...,
              precision: Literal["float32", "int8", "uint8", "binary", "ubinary"] = ...,
              convert_to_numpy: Literal[True] = ...,
              convert_to_tensor: Literal[False] = ...,
              device: str = ...,
              normalize_embeddings: bool = ...,
              **kwargs,
          ) -> np.ndarray: ...

          @overload
          def encode(
              self,
              sentences: str | list[str],
              prompt_name: str | None = ...,
              prompt: str | None = ...,
              batch_size: int = ...,
              show_progress_bar: bool | None = ...,
              output_value: Literal["sentence_embedding", "token_embeddings"] | None = ...,
              precision: Literal["float32", "int8", "uint8", "binary", "ubinary"] = ...,
              convert_to_numpy: bool = ...,
              convert_to_tensor: Literal[True] = ...,
              device: str = ...,
              normalize_embeddings: bool = ...,
              **kwargs,
          ) -> Tensor: ...

          @overload
          def encode(
              self,
              sentences: list[str] | np.ndarray,
              prompt_name: str | None = ...,
              prompt: str | None = ...,
              batch_size: int = ...,
              show_progress_bar: bool | None = ...,
              output_value: Literal["sentence_embedding", "token_embeddings"] | None = ...,
              precision: Literal["float32", "int8", "uint8", "binary", "ubinary"] = ...,
              convert_to_numpy: Literal[False] = ...,
              convert_to_tensor: Literal[False] = ...,
              device: str = ...,
              normalize_embeddings: bool = ...,
              **kwargs,
          ) -> list[Tensor]: ...

          def encode(
              self,
              sentences: str | list[str],
              prompt_name: str | None = None,
              prompt: str | None = None,
              batch_size: int = 32,
              show_progress_bar: bool | None = None,
              output_value: Literal["sentence_embedding", "token_embeddings"] | None = "sentence_embedding",
              precision: Literal["float32", "int8", "uint8", "binary", "ubinary"] = "float32",
              convert_to_numpy: bool = True,
              convert_to_tensor: bool = False,
              device: str = None,
              normalize_embeddings: bool = False,
              **kwargs,
          ) -> list[Tensor] | np.ndarray | Tensor:
              """
              Computes sentence embeddings.

              Args:
                  sentences (Union[str, List[str]]): The sentences to embed.
                  prompt_name (Optional[str], optional): The name of the prompt to use for encoding. Must be a key in the `prompts` dictionary,
                      which is either set in the constructor or loaded from the model configuration. For example if
                      ``prompt_name`` is "query" and the ``prompts`` is {"query": "query: ", ...}, then the sentence "What
                      is the capital of France?" will be encoded as "query: What is the capital of France?" because the sentence
                      is appended to the prompt. If ``prompt`` is also set, this argument is ignored. Defaults to None.
                  prompt (Optional[str], optional): The prompt to use for encoding. For example, if the prompt is "query: ", then the
                      sentence "What is the capital of France?" will be encoded as "query: What is the capital of France?"
                      because the sentence is appended to the prompt. If ``prompt`` is set, ``prompt_name`` is ignored. Defaults to None.
                  batch_size (int, optional): The batch size used for the computation. Defaults to 32.
                  show_progress_bar (bool, optional): Whether to output a progress bar when encode sentences. Defaults to None.
                  output_value (Optional[Literal["sentence_embedding", "token_embeddings"]], optional): The type of embeddings to return:
                      "sentence_embedding" to get sentence embeddings, "token_embeddings" to get wordpiece token embeddings, and `None`,
                      to get all output values. Defaults to "sentence_embedding".
                  precision (Literal["float32", "int8", "uint8", "binary", "ubinary"], optional): The precision to use for the embeddings.
                      Can be "float32", "int8", "uint8", "binary", or "ubinary". All non-float32 precisions are quantized embeddings.
                      Quantized embeddings are smaller in size and faster to compute, but may have a lower accuracy. They are useful for
                      reducing the size of the embeddings of a corpus for semantic search, among other tasks. Defaults to "float32".
                  convert_to_numpy (bool, optional): Whether the output should be a list of numpy vectors. If False, it is a list of PyTorch tensors.
                      Defaults to True.
                  convert_to_tensor (bool, optional): Whether the output should be one large tensor. Overwrites `convert_to_numpy`.
                      Defaults to False.
                  device (str, optional): Which :class:`torch.device` to use for the computation. Defaults to None.
                  normalize_embeddings (bool, optional): Whether to normalize returned vectors to have length 1. In that case,
                      the faster dot-product (util.dot_score) instead of cosine similarity can be used. Defaults to False.

              Returns:
                  Union[List[Tensor], ndarray, Tensor]: By default, a 2d numpy array with shape [num_inputs, output_dimension] is returned.
                  If only one string input is provided, then the output is a 1d array with shape [output_dimension]. If ``convert_to_tensor``,
                  a torch Tensor is returned instead. If ``self.truncate_dim <= output_dimension`` then output_dimension is ``self.truncate_dim``.

              Example:
                  ::

                      from sentence_transformers import SentenceTransformer

                      # Load a pre-trained SentenceTransformer model
                      model = SentenceTransformer('all-mpnet-base-v2')

                      # Encode some texts
                      sentences = [
                          "The weather is lovely today.",
                          "It's so sunny outside!",
                          "He drove to the stadium.",
                      ]
                      embeddings = model.encode(sentences)
                      print(embeddings.shape)
                      # (3, 768)
              """
              if self.device.type == "hpu" and not self.is_hpu_graph_enabled:
                  import habana_frameworks.torch as ht

                  ht.hpu.wrap_in_hpu_graph(self, disable_tensor_cache=True)
                  self.is_hpu_graph_enabled = True

              self.eval()
              if show_progress_bar is None:
                  show_progress_bar = logger.getEffectiveLevel() in (logging.INFO, logging.DEBUG)

              if convert_to_tensor:
                  convert_to_numpy = False

              if output_value != "sentence_embedding":
                  convert_to_tensor = False
                  convert_to_numpy = False

              input_was_string = False
              if isinstance(sentences, str) or not hasattr(
                  sentences, "__len__"
              ):  # Cast an individual sentence to a list with length 1
                  sentences = [sentences]
                  input_was_string = True

              if prompt is None:
                  if prompt_name is not None:
                      try:
                          prompt = self.prompts[prompt_name]
                      except KeyError:
                          raise ValueError(
                              f"Prompt name '{prompt_name}' not found in the configured prompts dictionary with keys {list(self.prompts.keys())!r}."
                          )
                  elif self.default_prompt_name is not None:
                      prompt = self.prompts.get(self.default_prompt_name, None)
              else:
                  if prompt_name is not None:
                      logger.warning(
                          "Encode with either a `prompt`, a `prompt_name`, or neither, but not both. "
                          "Ignoring the `prompt_name` in favor of `prompt`."
                      )

              extra_features = {}
              if prompt is not None:
                  sentences = [prompt + sentence for sentence in sentences]

                  # Some models (e.g. INSTRUCTOR, GRIT) require removing the prompt before pooling
                  # Tracking the prompt length allow us to remove the prompt during pooling
                  tokenized_prompt = self.tokenize([prompt])
                  if "input_ids" in tokenized_prompt:
                      extra_features["prompt_length"] = tokenized_prompt["input_ids"].shape[-1] - 1

              if device is None:
                  device = self.device

              self.to(device)

              all_embeddings = []
              length_sorted_idx = np.argsort([-self._text_length(sen) for sen in sentences])
              sentences_sorted = [sentences[idx] for idx in length_sorted_idx]

              for start_index in trange(0, len(sentences), batch_size, desc="Batches", disable=not show_progress_bar):
                  sentences_batch = sentences_sorted[start_index : start_index + batch_size]
                  features = self.tokenize(sentences_batch)
                  if self.device.type == "hpu":
                      if "input_ids" in features:
                          curr_tokenize_len = features["input_ids"].shape
                          additional_pad_len = 2 ** math.ceil(math.log2(curr_tokenize_len[1])) - curr_tokenize_len[1]
                          features["input_ids"] = torch.cat(
                              (
                                  features["input_ids"],
                                  torch.ones((curr_tokenize_len[0], additional_pad_len), dtype=torch.int8),
                              ),
                              -1,
                          )
                          features["attention_mask"] = torch.cat(
                              (
                                  features["attention_mask"],
                                  torch.zeros((curr_tokenize_len[0], additional_pad_len), dtype=torch.int8),
                              ),
                              -1,
                          )
                          if "token_type_ids" in features:
                              features["token_type_ids"] = torch.cat(
                                  (
                                      features["token_type_ids"],
                                      torch.zeros((curr_tokenize_len[0], additional_pad_len), dtype=torch.int8),
                                  ),
                                  -1,
                              )

                  features = batch_to_device(features, device)
                  features.update(extra_features)

                  with torch.no_grad():
                      out_features = self.forward(features, **kwargs)
                      if self.device.type == "hpu":
                          out_features = copy.deepcopy(out_features)

                      out_features["sentence_embedding"] = truncate_embeddings(
                          out_features["sentence_embedding"], self.truncate_dim
                      )

                      if output_value == "token_embeddings":
                          embeddings = []
                          for token_emb, attention in zip(out_features[output_value], out_features["attention_mask"]):
                              last_mask_id = len(attention) - 1
                              while last_mask_id > 0 and attention[last_mask_id].item() == 0:
                                  last_mask_id -= 1

                              embeddings.append(token_emb[0 : last_mask_id + 1])
                      elif output_value is None:  # Return all outputs
                          embeddings = []
                          for sent_idx in range(len(out_features["sentence_embedding"])):
                              row = {name: out_features[name][sent_idx] for name in out_features}
                              embeddings.append(row)
                      else:  # Sentence embeddings
                          embeddings = out_features[output_value]
                          embeddings = embeddings.detach()
                          if normalize_embeddings:
                              embeddings = torch.nn.functional.normalize(embeddings, p=2, dim=1)

                          # fixes for #522 and #487 to avoid oom problems on gpu with large datasets
                          if convert_to_numpy:
                              embeddings = embeddings.cpu()

                      all_embeddings.extend(embeddings)

              all_embeddings = [all_embeddings[idx] for idx in np.argsort(length_sorted_idx)]

              if precision and precision != "float32":
                  all_embeddings = quantize_embeddings(all_embeddings, precision=precision)

              if convert_to_tensor:
                  if len(all_embeddings):
                      if isinstance(all_embeddings, np.ndarray):
                          all_embeddings = torch.from_numpy(all_embeddings)
                      else:
                          all_embeddings = torch.stack(all_embeddings)
                  else:
                      all_embeddings = torch.Tensor()
              elif convert_to_numpy:
                  if not isinstance(all_embeddings, np.ndarray):
                      if all_embeddings and all_embeddings[0].dtype == torch.bfloat16:
                          all_embeddings = np.asarray([emb.float().numpy() for emb in all_embeddings])
                      else:
                          all_embeddings = np.asarray([emb.numpy() for emb in all_embeddings])
              elif isinstance(all_embeddings, np.ndarray):
                  all_embeddings = [torch.from_numpy(embedding) for embedding in all_embeddings]

              if input_was_string:
                  all_embeddings = all_embeddings[0]

              return all_embeddings

          def forward(self, input: dict[str, Tensor], **kwargs) -> dict[str, Tensor]:
              if self.module_kwargs is None:
                  return super().forward(input)

              for module_name, module in self.named_children():
                  module_kwarg_keys = self.module_kwargs.get(module_name, [])
                  module_kwargs = {key: value for key, value in kwargs.items() if key in module_kwarg_keys}
                  input = module(input, **module_kwargs)
              return input

          @property
          def similarity_fn_name(self) -> Literal["cosine", "dot", "euclidean", "manhattan"]:
              """Return the name of the similarity function used by :meth:`SentenceTransformer.similarity` and :meth:`SentenceTransformer.similarity_pairwise`.

              Returns:
                  Optional[str]: The name of the similarity function. Can be None if not set, in which case it will
                      default to "cosine" when first called.

              Example:
                  >>> model = SentenceTransformer("multi-qa-mpnet-base-dot-v1")
                  >>> model.similarity_fn_name
                  'dot'
              """
              if self._similarity_fn_name is None:
                  self.similarity_fn_name = SimilarityFunction.COSINE
              return self._similarity_fn_name

          @similarity_fn_name.setter
          def similarity_fn_name(
              self, value: Literal["cosine", "dot", "euclidean", "manhattan"] | SimilarityFunction
          ) -> None:
              if isinstance(value, SimilarityFunction):
                  value = value.value
              self._similarity_fn_name = value

              if value is not None:
                  self._similarity = SimilarityFunction.to_similarity_fn(value)
                  self._similarity_pairwise = SimilarityFunction.to_similarity_pairwise_fn(value)

          @overload
          def similarity(self, embeddings1: Tensor, embeddings2: Tensor) -> Tensor: ...

          @overload
          def similarity(self, embeddings1: ndarray, embeddings2: ndarray) -> Tensor: ...

          @property
          def similarity(self) -> Callable[[Tensor | ndarray, Tensor | ndarray], Tensor]:
              """
              Compute the similarity between two collections of embeddings. The output will be a matrix with the similarity
              scores between all embeddings from the first parameter and all embeddings from the second parameter. This
              differs from `similarity_pairwise` which computes the similarity between each pair of embeddings.

              Args:
                  embeddings1 (Union[Tensor, ndarray]): [num_embeddings_1, embedding_dim] or [embedding_dim]-shaped numpy array or torch tensor.
                  embeddings2 (Union[Tensor, ndarray]): [num_embeddings_2, embedding_dim] or [embedding_dim]-shaped numpy array or torch tensor.

              Returns:
                  Tensor: A [num_embeddings_1, num_embeddings_2]-shaped torch tensor with similarity scores.

              Example:
                  ::

                      >>> model = SentenceTransformer("all-mpnet-base-v2")
                      >>> sentences = [
                      ...     "The weather is so nice!",
                      ...     "It's so sunny outside.",
                      ...     "He's driving to the movie theater.",
                      ...     "She's going to the cinema.",
                      ... ]
                      >>> embeddings = model.encode(sentences, normalize_embeddings=True)
                      >>> model.similarity(embeddings, embeddings)
                      tensor([[1.0000, 0.7235, 0.0290, 0.1309],
                              [0.7235, 1.0000, 0.0613, 0.1129],
                              [0.0290, 0.0613, 1.0000, 0.5027],
                              [0.1309, 0.1129, 0.5027, 1.0000]])
                      >>> model.similarity_fn_name
                      "cosine"
                      >>> model.similarity_fn_name = "euclidean"
                      >>> model.similarity(embeddings, embeddings)
                      tensor([[-0.0000, -0.7437, -1.3935, -1.3184],
                              [-0.7437, -0.0000, -1.3702, -1.3320],
                              [-1.3935, -1.3702, -0.0000, -0.9973],
                              [-1.3184, -1.3320, -0.9973, -0.0000]])
              """
              if self.similarity_fn_name is None:
                  self.similarity_fn_name = SimilarityFunction.COSINE
              return self._similarity

          @overload
          def similarity_pairwise(self, embeddings1: Tensor, embeddings2: Tensor) -> Tensor: ...

          @overload
          def similarity_pairwise(self, embeddings1: ndarray, embeddings2: ndarray) -> Tensor: ...

          @property
          def similarity_pairwise(self) -> Callable[[Tensor | ndarray, Tensor | ndarray], Tensor]:
              """
              Compute the similarity between two collections of embeddings. The output will be a vector with the similarity
              scores between each pair of embeddings.

              Args:
                  embeddings1 (Union[Tensor, ndarray]): [num_embeddings, embedding_dim] or [embedding_dim]-shaped numpy array or torch tensor.
                  embeddings2 (Union[Tensor, ndarray]): [num_embeddings, embedding_dim] or [embedding_dim]-shaped numpy array or torch tensor.

              Returns:
                  Tensor: A [num_embeddings]-shaped torch tensor with pairwise similarity scores.

              Example:
                  ::

                      >>> model = SentenceTransformer("all-mpnet-base-v2")
                      >>> sentences = [
                      ...     "The weather is so nice!",
                      ...     "It's so sunny outside.",
                      ...     "He's driving to the movie theater.",
                      ...     "She's going to the cinema.",
                      ... ]
                      >>> embeddings = model.encode(sentences, normalize_embeddings=True)
                      >>> model.similarity_pairwise(embeddings[::2], embeddings[1::2])
                      tensor([0.7235, 0.5027])
                      >>> model.similarity_fn_name
                      "cosine"
                      >>> model.similarity_fn_name = "euclidean"
                      >>> model.similarity_pairwise(embeddings[::2], embeddings[1::2])
                      tensor([-0.7437, -0.9973])
              """
              if self.similarity_fn_name is None:
                  self.similarity_fn_name = SimilarityFunction.COSINE
              return self._similarity_pairwise

          def start_multi_process_pool(
              self, target_devices: list[str] = None
          ) -> dict[Literal["input", "output", "processes"], Any]:
              """
              Starts a multi-process pool to process the encoding with several independent processes
              via :meth:`SentenceTransformer.encode_multi_process <sentence_transformers.SentenceTransformer.encode_multi_process>`.

              This method is recommended if you want to encode on multiple GPUs or CPUs. It is advised
              to start only one process per GPU. This method works together with encode_multi_process
              and stop_multi_process_pool.

              Args:
                  target_devices (List[str], optional): PyTorch target devices, e.g. ["cuda:0", "cuda:1", ...],
                      ["npu:0", "npu:1", ...], or ["cpu", "cpu", "cpu", "cpu"]. If target_devices is None and CUDA/NPU
                      is available, then all available CUDA/NPU devices will be used. If target_devices is None and
                      CUDA/NPU is not available, then 4 CPU devices will be used.

              Returns:
                  Dict[str, Any]: A dictionary with the target processes, an input queue, and an output queue.
              """
              if target_devices is None:
                  if torch.cuda.is_available():
                      target_devices = [f"cuda:{i}" for i in range(torch.cuda.device_count())]
                  elif is_torch_npu_available():
                      target_devices = [f"npu:{i}" for i in range(torch.npu.device_count())]
                  else:
                      logger.info("CUDA/NPU is not available. Starting 4 CPU workers")
                      target_devices = ["cpu"] * 4

              logger.info("Start multi-process pool on devices: {}".format(", ".join(map(str, target_devices))))

              self.to("cpu")
              self.share_memory()
              ctx = mp.get_context("spawn")
              input_queue = ctx.Queue()
              output_queue = ctx.Queue()
              processes = []

              for device_id in target_devices:
                  p = ctx.Process(
                      target=SentenceTransformer._encode_multi_process_worker,
                      args=(device_id, self, input_queue, output_queue),
                      daemon=True,
                  )
                  p.start()
                  processes.append(p)

              return {"input": input_queue, "output": output_queue, "processes": processes}

          @staticmethod
          def stop_multi_process_pool(pool: dict[Literal["input", "output", "processes"], Any]) -> None:
              """
              Stops all processes started with start_multi_process_pool.

              Args:
                  pool (Dict[str, object]): A dictionary containing the input queue, output queue, and process list.

              Returns:
                  None
              """
              for p in pool["processes"]:
                  p.terminate()

              for p in pool["processes"]:
                  p.join()
                  p.close()

              pool["input"].close()
              pool["output"].close()

          def encode_multi_process(
              self,
              sentences: list[str],
              pool: dict[Literal["input", "output", "processes"], Any],
              prompt_name: str | None = None,
              prompt: str | None = None,
              batch_size: int = 32,
              chunk_size: int = None,
              show_progress_bar: bool | None = None,
              precision: Literal["float32", "int8", "uint8", "binary", "ubinary"] = "float32",
              normalize_embeddings: bool = False,
          ) -> np.ndarray:
              """
              Encodes a list of sentences using multiple processes and GPUs via
              :meth:`SentenceTransformer.encode <sentence_transformers.SentenceTransformer.encode>`.
              The sentences are chunked into smaller packages and sent to individual processes, which encode them on different
              GPUs or CPUs. This method is only suitable for encoding large sets of sentences.

              Args:
                  sentences (List[str]): List of sentences to encode.
                  pool (Dict[Literal["input", "output", "processes"], Any]): A pool of workers started with
                      :meth:`SentenceTransformer.start_multi_process_pool <sentence_transformers.SentenceTransformer.start_multi_process_pool>`.
                  prompt_name (Optional[str], optional): The name of the prompt to use for encoding. Must be a key in the `prompts` dictionary,
                      which is either set in the constructor or loaded from the model configuration. For example if
                      ``prompt_name`` is "query" and the ``prompts`` is {"query": "query: ", ...}, then the sentence "What
                      is the capital of France?" will be encoded as "query: What is the capital of France?" because the sentence
                      is appended to the prompt. If ``prompt`` is also set, this argument is ignored. Defaults to None.
                  prompt (Optional[str], optional): The prompt to use for encoding. For example, if the prompt is "query: ", then the
                      sentence "What is the capital of France?" will be encoded as "query: What is the capital of France?"
                      because the sentence is appended to the prompt. If ``prompt`` is set, ``prompt_name`` is ignored. Defaults to None.
                  batch_size (int): Encode sentences with batch size. (default: 32)
                  chunk_size (int): Sentences are chunked and sent to the individual processes. If None, it determines a
                      sensible size. Defaults to None.
                  show_progress_bar (bool, optional): Whether to output a progress bar when encode sentences. Defaults to None.
                  precision (Literal["float32", "int8", "uint8", "binary", "ubinary"]): The precision to use for the
                      embeddings. Can be "float32", "int8", "uint8", "binary", or "ubinary". All non-float32 precisions
                      are quantized embeddings. Quantized embeddings are smaller in size and faster to compute, but may
                      have lower accuracy. They are useful for reducing the size of the embeddings of a corpus for
                      semantic search, among other tasks. Defaults to "float32".
                  normalize_embeddings (bool): Whether to normalize returned vectors to have length 1. In that case,
                      the faster dot-product (util.dot_score) instead of cosine similarity can be used. Defaults to False.

              Returns:
                  np.ndarray: A 2D numpy array with shape [num_inputs, output_dimension].

              Example:
                  ::

                      from sentence_transformers import SentenceTransformer

                      def main():
                          model = SentenceTransformer("all-mpnet-base-v2")
                          sentences = ["The weather is so nice!", "It's so sunny outside.", "He's driving to the movie theater.", "She's going to the cinema."] * 1000

                          pool = model.start_multi_process_pool()
                          embeddings = model.encode_multi_process(sentences, pool)
                          model.stop_multi_process_pool(pool)

                          print(embeddings.shape)
                          # => (4000, 768)

                      if __name__ == "__main__":
                          main()
              """

              if chunk_size is None:
                  chunk_size = min(math.ceil(len(sentences) / len(pool["processes"]) / 10), 5000)

              if show_progress_bar is None:
                  show_progress_bar = logger.getEffectiveLevel() in (logging.INFO, logging.DEBUG)

              logger.debug(f"Chunk data into {math.ceil(len(sentences) / chunk_size)} packages of size {chunk_size}")

              input_queue = pool["input"]
              last_chunk_id = 0
              chunk = []

              for sentence in sentences:
                  chunk.append(sentence)
                  if len(chunk) >= chunk_size:
                      input_queue.put(
                          [last_chunk_id, batch_size, chunk, prompt_name, prompt, precision, normalize_embeddings]
                      )
                      last_chunk_id += 1
                      chunk = []

              if len(chunk) > 0:
                  input_queue.put([last_chunk_id, batch_size, chunk, prompt_name, prompt, precision, normalize_embeddings])
                  last_chunk_id += 1

              output_queue = pool["output"]
              results_list = sorted(
                  [output_queue.get() for _ in trange(last_chunk_id, desc="Chunks", disable=not show_progress_bar)],
                  key=lambda x: x[0],
              )
              embeddings = np.concatenate([result[1] for result in results_list])
              return embeddings

          @staticmethod
          def _encode_multi_process_worker(
              target_device: str, model: SentenceTransformer, input_queue: Queue, results_queue: Queue
          ) -> None:
              """
              Internal working process to encode sentences in multi-process setup
              """
              while True:
                  try:
                      chunk_id, batch_size, sentences, prompt_name, prompt, precision, normalize_embeddings = (
                          input_queue.get()
                      )
                      embeddings = model.encode(
                          sentences,
                          prompt_name=prompt_name,
                          prompt=prompt,
                          device=target_device,
                          show_progress_bar=False,
                          precision=precision,
                          convert_to_numpy=True,
                          batch_size=batch_size,
                          normalize_embeddings=normalize_embeddings,
                      )

                      results_queue.put([chunk_id, embeddings])
                  except queue.Empty:
                      break

          def set_pooling_include_prompt(self, include_prompt: bool) -> None:
              """
              Sets the `include_prompt` attribute in the pooling layer in the model, if there is one.

              This is useful for INSTRUCTOR models, as the prompt should be excluded from the pooling strategy
              for these models.

              Args:
                  include_prompt (bool): Whether to include the prompt in the pooling layer.

              Returns:
                  None
              """
              for module in self:
                  if isinstance(module, Pooling):
                      module.include_prompt = include_prompt
                      break

          def get_max_seq_length(self) -> int | None:
              """
              Returns the maximal sequence length that the model accepts. Longer inputs will be truncated.

              Returns:
                  Optional[int]: The maximal sequence length that the model accepts, or None if it is not defined.
              """
              if hasattr(self._first_module(), "max_seq_length"):
                  return self._first_module().max_seq_length

              return None

          def tokenize(self, texts: list[str] | list[dict] | list[tuple[str, str]]) -> dict[str, Tensor]:
              """
              Tokenizes the texts.

              Args:
                  texts (Union[List[str], List[Dict], List[Tuple[str, str]]]): A list of texts to be tokenized.

              Returns:
                  Dict[str, Tensor]: A dictionary of tensors with the tokenized texts. Common keys are "input_ids",
                      "attention_mask", and "token_type_ids".
              """
              return self._first_module().tokenize(texts)

          def get_sentence_features(self, *features) -> dict[Literal["sentence_embedding"], Tensor]:
              return self._first_module().get_sentence_features(*features)

          def get_sentence_embedding_dimension(self) -> int | None:
              """
              Returns the number of dimensions in the output of :meth:`SentenceTransformer.encode <sentence_transformers.SentenceTransformer.encode>`.

              Returns:
                  Optional[int]: The number of dimensions in the output of `encode`. If it's not known, it's `None`.
              """
              output_dim = None
              for mod in reversed(self._modules.values()):
                  sent_embedding_dim_method = getattr(mod, "get_sentence_embedding_dimension", None)
                  if callable(sent_embedding_dim_method):
                      output_dim = sent_embedding_dim_method()
                      break
              if self.truncate_dim is not None:
                  # The user requested truncation. If they set it to a dim greater than output_dim,
                  # no truncation will actually happen. So return output_dim instead of self.truncate_dim
                  return min(output_dim or np.inf, self.truncate_dim)
              return output_dim

          @contextmanager
          def truncate_sentence_embeddings(self, truncate_dim: int | None) -> Iterator[None]:
              """
              In this context, :meth:`SentenceTransformer.encode <sentence_transformers.SentenceTransformer.encode>` outputs
              sentence embeddings truncated at dimension ``truncate_dim``.

              This may be useful when you are using the same model for different applications where different dimensions
              are needed.

              Args:
                  truncate_dim (int, optional): The dimension to truncate sentence embeddings to. ``None`` does no truncation.

              Example:
                  ::

                      from sentence_transformers import SentenceTransformer

                      model = SentenceTransformer("all-mpnet-base-v2")

                      with model.truncate_sentence_embeddings(truncate_dim=16):
                          embeddings_truncated = model.encode(["hello there", "hiya"])
                      assert embeddings_truncated.shape[-1] == 16
              """
              original_output_dim = self.truncate_dim
              try:
                  self.truncate_dim = truncate_dim
                  yield
              finally:
                  self.truncate_dim = original_output_dim

          def _first_module(self) -> torch.nn.Module:
              """Returns the first module of this sequential embedder"""
              return self._modules[next(iter(self._modules))]

          def _last_module(self) -> torch.nn.Module:
              """Returns the last module of this sequential embedder"""
              return self._modules[next(reversed(self._modules))]

          def save(
              self,
              path: str,
              model_name: str | None = None,
              create_model_card: bool = True,
              train_datasets: list[str] | None = None,
              safe_serialization: bool = True,
          ) -> None:
              """
              Saves a model and its configuration files to a directory, so that it can be loaded
              with ``SentenceTransformer(path)`` again.

              Args:
                  path (str): Path on disc where the model will be saved.
                  model_name (str, optional): Optional model name.
                  create_model_card (bool, optional): If True, create a README.md with basic information about this model.
                  train_datasets (List[str], optional): Optional list with the names of the datasets used to train the model.
                  safe_serialization (bool, optional): If True, save the model using safetensors. If False, save the model
                      the traditional (but unsafe) PyTorch way.
              """
              if path is None:
                  return

              os.makedirs(path, exist_ok=True)

              logger.info(f"Save model to {path}")
              modules_config = []

              # Save some model info
              self._model_config["__version__"] = {
                  "sentence_transformers": __version__,
                  "transformers": transformers.__version__,
                  "pytorch": torch.__version__,
              }

              with open(os.path.join(path, "config_sentence_transformers.json"), "w") as fOut:
                  config = self._model_config.copy()
                  config["prompts"] = self.prompts
                  config["default_prompt_name"] = self.default_prompt_name
                  config["similarity_fn_name"] = self.similarity_fn_name
                  json.dump(config, fOut, indent=2)

              # Save modules
              for idx, name in enumerate(self._modules):
                  module = self._modules[name]
                  if idx == 0 and hasattr(module, "save_in_root"):  # Save first module in the main folder
                      model_path = path + "/"
                  else:
                      model_path = os.path.join(path, str(idx) + "_" + type(module).__name__)

                  os.makedirs(model_path, exist_ok=True)
                  # Try to save with safetensors, but fall back to the traditional PyTorch way if the module doesn't support it
                  try:
                      module.save(model_path, safe_serialization=safe_serialization)
                  except TypeError:
                      module.save(model_path)

                  # "module" only works for Sentence Transformers as the modules have the same names as the classes
                  class_ref = type(module).__module__
                  # For remote modules, we want to remove "transformers_modules.{repo_name}":
                  if class_ref.startswith("transformers_modules."):
                      class_file = sys.modules[class_ref].__file__

                      # Save the custom module file
                      dest_file = Path(model_path) / (Path(class_file).name)
                      shutil.copy(class_file, dest_file)

                      # Save all files importeed in the custom module file
                      for needed_file in get_relative_import_files(class_file):
                          dest_file = Path(model_path) / (Path(needed_file).name)
                          shutil.copy(needed_file, dest_file)

                      # For remote modules, we want to ignore the "transformers_modules.{repo_id}" part,
                      # i.e. we only want the filename
                      class_ref = f"{class_ref.split('.')[-1]}.{type(module).__name__}"
                  # For other cases, we want to add the class name:
                  elif not class_ref.startswith("sentence_transformers."):
                      class_ref = f"{class_ref}.{type(module).__name__}"
                  modules_config.append({"idx": idx, "name": name, "path": os.path.basename(model_path), "type": class_ref})

              with open(os.path.join(path, "modules.json"), "w") as fOut:
                  json.dump(modules_config, fOut, indent=2)

              # Create model card
              if create_model_card:
                  self._create_model_card(path, model_name, train_datasets)

          def save_pretrained(
              self,
              path: str,
              model_name: str | None = None,
              create_model_card: bool = True,
              train_datasets: list[str] | None = None,
              safe_serialization: bool = True,
          ) -> None:
              """
              Saves a model and its configuration files to a directory, so that it can be loaded
              with ``SentenceTransformer(path)`` again.

              Args:
                  path (str): Path on disc where the model will be saved.
                  model_name (str, optional): Optional model name.
                  create_model_card (bool, optional): If True, create a README.md with basic information about this model.
                  train_datasets (List[str], optional): Optional list with the names of the datasets used to train the model.
                  safe_serialization (bool, optional): If True, save the model using safetensors. If False, save the model
                      the traditional (but unsafe) PyTorch way.
              """
              self.save(
                  path,
                  model_name=model_name,
                  create_model_card=create_model_card,
                  train_datasets=train_datasets,
                  safe_serialization=safe_serialization,
              )

          def _create_model_card(
              self, path: str, model_name: str | None = None, train_datasets: list[str] | None = "deprecated"
          ) -> None:
              """
              Create an automatic model and stores it in the specified path. If no training was done and the loaded model
              was a Sentence Transformer model already, then its model card is reused.

              Args:
                  path (str): The path where the model card will be stored.
                  model_name (Optional[str], optional): The name of the model. Defaults to None.
                  train_datasets (Optional[List[str]], optional): Deprecated argument. Defaults to "deprecated".

              Returns:
                  None
              """
              if model_name:
                  model_path = Path(model_name)
                  if not model_path.exists() and not self.model_card_data.model_id:
                      self.model_card_data.model_id = model_name

              # If we loaded a Sentence Transformer model from the Hub, and no training was done, then
              # we don't generate a new model card, but reuse the old one instead.
              if self._model_card_text and self.model_card_data.trainer is None:
                  model_card = self._model_card_text
                  if self.model_card_data.model_id:
                      # If the original model card was saved without a model_id, we replace the model_id with the new model_id
                      model_card = model_card.replace(
                          'model = SentenceTransformer("sentence_transformers_model_id"',
                          f'model = SentenceTransformer("{self.model_card_data.model_id}"',
                      )
              else:
                  try:
                      model_card = generate_model_card(self)
                  except Exception:
                      logger.error(
                          f"Error while generating model card:\n{traceback.format_exc()}"
                          "Consider opening an issue on https://github.com/UKPLab/sentence-transformers/issues with this traceback.\n"
                          "Skipping model card creation."
                      )
                      return

              with open(os.path.join(path, "README.md"), "w", encoding="utf8") as fOut:
                  fOut.write(model_card)

          @save_to_hub_args_decorator
          def save_to_hub(
              self,
              repo_id: str,
              organization: str | None = None,
              token: str | None = None,
              private: bool | None = None,
              safe_serialization: bool = True,
              commit_message: str = "Add new SentenceTransformer model.",
              local_model_path: str | None = None,
              exist_ok: bool = False,
              replace_model_card: bool = False,
              train_datasets: list[str] | None = None,
          ) -> str:
              """
              DEPRECATED, use `push_to_hub` instead.

              Uploads all elements of this Sentence Transformer to a new HuggingFace Hub repository.

              Args:
                  repo_id (str): Repository name for your model in the Hub, including the user or organization.
                  token (str, optional): An authentication token (See https://huggingface.co/settings/token)
                  private (bool, optional): Set to true, for hosting a private model
                  safe_serialization (bool, optional): If true, save the model using safetensors. If false, save the model the traditional PyTorch way
                  commit_message (str, optional): Message to commit while pushing.
                  local_model_path (str, optional): Path of the model locally. If set, this file path will be uploaded. Otherwise, the current model will be uploaded
                  exist_ok (bool, optional): If true, saving to an existing repository is OK. If false, saving only to a new repository is possible
                  replace_model_card (bool, optional): If true, replace an existing model card in the hub with the automatically created model card
                  train_datasets (List[str], optional): Datasets used to train the model. If set, the datasets will be added to the model card in the Hub.

              Returns:
                  str: The url of the commit of your model in the repository on the Hugging Face Hub.
              """
              logger.warning(
                  "The `save_to_hub` method is deprecated and will be removed in a future version of SentenceTransformers."
                  " Please use `push_to_hub` instead for future model uploads."
              )

              if organization:
                  if "/" not in repo_id:
                      logger.warning(
                          f'Providing an `organization` to `save_to_hub` is deprecated, please use `repo_id="{organization}/{repo_id}"` instead.'
                      )
                      repo_id = f"{organization}/{repo_id}"
                  elif repo_id.split("/")[0] != organization:
                      raise ValueError(
                          "Providing an `organization` to `save_to_hub` is deprecated, please only use `repo_id`."
                      )
                  else:
                      logger.warning(
                          f'Providing an `organization` to `save_to_hub` is deprecated, please only use `repo_id="{repo_id}"` instead.'
                      )

              return self.push_to_hub(
                  repo_id=repo_id,
                  token=token,
                  private=private,
                  safe_serialization=safe_serialization,
                  commit_message=commit_message,
                  local_model_path=local_model_path,
                  exist_ok=exist_ok,
                  replace_model_card=replace_model_card,
                  train_datasets=train_datasets,
              )

          def push_to_hub(
              self,
              repo_id: str,
              token: str | None = None,
              private: bool | None = None,
              safe_serialization: bool = True,
              commit_message: str | None = None,
              local_model_path: str | None = None,
              exist_ok: bool = False,
              replace_model_card: bool = False,
              train_datasets: list[str] | None = None,
              revision: str | None = None,
              create_pr: bool = False,
          ) -> str:
              """
              Uploads all elements of this Sentence Transformer to a new HuggingFace Hub repository.

              Args:
                  repo_id (str): Repository name for your model in the Hub, including the user or organization.
                  token (str, optional): An authentication token (See https://huggingface.co/settings/token)
                  private (bool, optional): Set to true, for hosting a private model
                  safe_serialization (bool, optional): If true, save the model using safetensors. If false, save the model the traditional PyTorch way
                  commit_message (str, optional): Message to commit while pushing.
                  local_model_path (str, optional): Path of the model locally. If set, this file path will be uploaded. Otherwise, the current model will be uploaded
                  exist_ok (bool, optional): If true, saving to an existing repository is OK. If false, saving only to a new repository is possible
                  replace_model_card (bool, optional): If true, replace an existing model card in the hub with the automatically created model card
                  train_datasets (List[str], optional): Datasets used to train the model. If set, the datasets will be added to the model card in the Hub.
                  revision (str, optional): Branch to push the uploaded files to
                  create_pr (bool, optional): If True, create a pull request instead of pushing directly to the main branch

              Returns:
                  str: The url of the commit of your model in the repository on the Hugging Face Hub.
              """
              api = HfApi(token=token)
              repo_url = api.create_repo(
                  repo_id=repo_id,
                  private=private,
                  repo_type=None,
                  exist_ok=exist_ok or create_pr,
              )
              repo_id = repo_url.repo_id  # Update the repo_id in case the old repo_id didn't contain a user or organization
              self.model_card_data.set_model_id(repo_id)
              if revision is not None:
                  api.create_branch(repo_id=repo_id, branch=revision, exist_ok=True)

              if commit_message is None:
                  backend = self.get_backend()
                  if backend == "torch":
                      commit_message = "Add new SentenceTransformer model"
                  else:
                      commit_message = f"Add new SentenceTransformer model with an {backend} backend"

              commit_description = ""
              if create_pr:
                  commit_description = f"""\
      Hello!

      *This pull request has been automatically generated from the [`push_to_hub`](https://sbert.net/docs/package_reference/sentence_transformer/SentenceTransformer.html#sentence_transformers.SentenceTransformer.push_to_hub) method from the Sentence Transformers library.*

      ## Full Model Architecture:
      ```
      {self}
      ```

      ## Tip:
      Consider testing this pull request before merging by loading the model from this PR with the `revision` argument:
      ```python
      from sentence_transformers import SentenceTransformer

      # TODO: Fill in the PR number
      pr_number = 2
      model = SentenceTransformer(
          "{repo_id}",
          revision=f"refs/pr/{{pr_number}}",
          backend="{self.get_backend()}",
      )

      # Verify that everything works as expected
      embeddings = model.encode(["The weather is lovely today.", "It's so sunny outside!", "He drove to the stadium."])
      print(embeddings.shape)

      similarities = model.similarity(embeddings, embeddings)
      print(similarities)
      ```
      """

              if local_model_path:
                  folder_url = api.upload_folder(
                      repo_id=repo_id,
                      folder_path=local_model_path,
                      commit_message=commit_message,
                      commit_description=commit_description,
                      revision=revision,
                      create_pr=create_pr,
                  )
              else:
                  with tempfile.TemporaryDirectory() as tmp_dir:
                      create_model_card = replace_model_card or not os.path.exists(os.path.join(tmp_dir, "README.md"))
                      self.save_pretrained(
                          tmp_dir,
                          model_name=repo_url.repo_id,
                          create_model_card=create_model_card,
                          train_datasets=train_datasets,
                          safe_serialization=safe_serialization,
                      )
                      folder_url = api.upload_folder(
                          repo_id=repo_id,
                          folder_path=tmp_dir,
                          commit_message=commit_message,
                          commit_description=commit_description,
                          revision=revision,
                          create_pr=create_pr,
                      )

              if create_pr:
                  return folder_url.pr_url
              return folder_url.commit_url

          def _text_length(self, text: list[int] | list[list[int]]) -> int:
              """
              Help function to get the length for the input text. Text can be either
              a list of ints (which means a single text as input), or a tuple of list of ints
              (representing several text inputs to the model).
              """

              if isinstance(text, dict):  # {key: value} case
                  return len(next(iter(text.values())))
              elif not hasattr(text, "__len__"):  # Object has no len() method
                  return 1
              elif len(text) == 0 or isinstance(text[0], int):  # Empty string or list of ints
                  return len(text)
              else:
                  return sum([len(t) for t in text])  # Sum of length of individual strings

          def evaluate(self, evaluator: SentenceEvaluator, output_path: str = None) -> dict[str, float] | float:
              """
              Evaluate the model based on an evaluator

              Args:
                  evaluator (SentenceEvaluator): The evaluator used to evaluate the model.
                  output_path (str, optional): The path where the evaluator can write the results. Defaults to None.

              Returns:
                  The evaluation results.
              """
              if output_path is not None:
                  os.makedirs(output_path, exist_ok=True)
              return evaluator(self, output_path)

          def _load_auto_model(
              self,
              model_name_or_path: str,
              token: bool | str | None,
              cache_folder: str | None,
              revision: str | None = None,
              trust_remote_code: bool = False,
              local_files_only: bool = False,
              model_kwargs: dict[str, Any] | None = None,
              tokenizer_kwargs: dict[str, Any] | None = None,
              config_kwargs: dict[str, Any] | None = None,
          ) -> list[nn.Module]:
              """
              Creates a simple Transformer + Mean Pooling model and returns the modules

              Args:
                  model_name_or_path (str): The name or path of the pre-trained model.
                  token (Optional[Union[bool, str]]): The token to use for the model.
                  cache_folder (Optional[str]): The folder to cache the model.
                  revision (Optional[str], optional): The revision of the model. Defaults to None.
                  trust_remote_code (bool, optional): Whether to trust remote code. Defaults to False.
                  local_files_only (bool, optional): Whether to use only local files. Defaults to False.
                  model_kwargs (Optional[Dict[str, Any]], optional): Additional keyword arguments for the model. Defaults to None.
                  tokenizer_kwargs (Optional[Dict[str, Any]], optional): Additional keyword arguments for the tokenizer. Defaults to None.
                  config_kwargs (Optional[Dict[str, Any]], optional): Additional keyword arguments for the config. Defaults to None.

              Returns:
                  List[nn.Module]: A list containing the transformer model and the pooling model.
              """
              logger.warning(
                  f"No sentence-transformers model found with name {model_name_or_path}. Creating a new one with mean pooling."
              )

              shared_kwargs = {
                  "token": token,
                  "trust_remote_code": trust_remote_code,
                  "revision": revision,
                  "local_files_only": local_files_only,
              }
              model_kwargs = shared_kwargs if model_kwargs is None else {**shared_kwargs, **model_kwargs}
              tokenizer_kwargs = shared_kwargs if tokenizer_kwargs is None else {**shared_kwargs, **tokenizer_kwargs}
              config_kwargs = shared_kwargs if config_kwargs is None else {**shared_kwargs, **config_kwargs}

              transformer_model = Transformer(
                  model_name_or_path,
                  cache_dir=cache_folder,
                  model_args=model_kwargs,
                  tokenizer_args=tokenizer_kwargs,
                  config_args=config_kwargs,
                  backend=self.backend,
              )
              pooling_model = Pooling(transformer_model.get_word_embedding_dimension(), "mean")
              self.model_card_data.set_base_model(model_name_or_path, revision=revision)
              return [transformer_model, pooling_model]

          def _load_module_class_from_ref(
              self,
              class_ref: str,
              model_name_or_path: str,
              trust_remote_code: bool,
              revision: str | None,
              model_kwargs: dict[str, Any] | None,
          ) -> nn.Module:
              # If the class is from sentence_transformers, we can directly import it,
              # otherwise, we try to import it dynamically, and if that fails, we fall back to the default import
              if class_ref.startswith("sentence_transformers."):
                  return import_from_string(class_ref)

              if trust_remote_code:
                  code_revision = model_kwargs.pop("code_revision", None) if model_kwargs else None
                  try:
                      return get_class_from_dynamic_module(
                          class_ref,
                          model_name_or_path,
                          revision=revision,
                          code_revision=code_revision,
                      )
                  except OSError:
                      # Ignore the error if the file does not exist, and fall back to the default import
                      pass

              return import_from_string(class_ref)

          def _load_sbert_model(
              self,
              model_name_or_path: str,
              token: bool | str | None,
              cache_folder: str | None,
              revision: str | None = None,
              trust_remote_code: bool = False,
              local_files_only: bool = False,
              model_kwargs: dict[str, Any] | None = None,
              tokenizer_kwargs: dict[str, Any] | None = None,
              config_kwargs: dict[str, Any] | None = None,
          ) -> dict[str, nn.Module]:
              """
              Loads a full SentenceTransformer model using the modules.json file.

              Args:
                  model_name_or_path (str): The name or path of the pre-trained model.
                  token (Optional[Union[bool, str]]): The token to use for the model.
                  cache_folder (Optional[str]): The folder to cache the model.
                  revision (Optional[str], optional): The revision of the model. Defaults to None.
                  trust_remote_code (bool, optional): Whether to trust remote code. Defaults to False.
                  local_files_only (bool, optional): Whether to use only local files. Defaults to False.
                  model_kwargs (Optional[Dict[str, Any]], optional): Additional keyword arguments for the model. Defaults to None.
                  tokenizer_kwargs (Optional[Dict[str, Any]], optional): Additional keyword arguments for the tokenizer. Defaults to None.
                  config_kwargs (Optional[Dict[str, Any]], optional): Additional keyword arguments for the config. Defaults to None.

              Returns:
                  OrderedDict[str, nn.Module]: An ordered dictionary containing the modules of the model.
              """
              # Check if the config_sentence_transformers.json file exists (exists since v2 of the framework)
              config_sentence_transformers_json_path = load_file_path(
                  model_name_or_path,
                  "config_sentence_transformers.json",
                  token=token,
                  cache_folder=cache_folder,
                  revision=revision,
                  local_files_only=local_files_only,
              )
              if config_sentence_transformers_json_path is not None:
                  with open(config_sentence_transformers_json_path) as fIn:
                      self._model_config = json.load(fIn)

                  if (
                      "__version__" in self._model_config
                      and "sentence_transformers" in self._model_config["__version__"]
                      and self._model_config["__version__"]["sentence_transformers"] > __version__
                  ):
                      logger.warning(
                          "You try to use a model that was created with version {}, however, your version is {}. This might cause unexpected behavior or errors. In that case, try to update to the latest version.\n\n\n".format(
                              self._model_config["__version__"]["sentence_transformers"], __version__
                          )
                      )

                  # Set score functions & prompts if not already overridden by the __init__ calls
                  if self._similarity_fn_name is None:
                      self.similarity_fn_name = self._model_config.get("similarity_fn_name", None)
                  if not self.prompts:
                      self.prompts = self._model_config.get("prompts", {})
                  if not self.default_prompt_name:
                      self.default_prompt_name = self._model_config.get("default_prompt_name", None)

              # Check if a readme exists
              model_card_path = load_file_path(
                  model_name_or_path,
                  "README.md",
                  token=token,
                  cache_folder=cache_folder,
                  revision=revision,
                  local_files_only=local_files_only,
              )
              if model_card_path is not None:
                  try:
                      with open(model_card_path, encoding="utf8") as fIn:
                          self._model_card_text = fIn.read()
                  except Exception:
                      pass

              # Load the modules of sentence transformer
              modules_json_path = load_file_path(
                  model_name_or_path,
                  "modules.json",
                  token=token,
                  cache_folder=cache_folder,
                  revision=revision,
                  local_files_only=local_files_only,
              )
              with open(modules_json_path) as fIn:
                  modules_config = json.load(fIn)

              modules = OrderedDict()
              module_kwargs = OrderedDict()
              for module_config in modules_config:
                  class_ref = module_config["type"]
                  module_class = self._load_module_class_from_ref(
                      class_ref, model_name_or_path, trust_remote_code, revision, model_kwargs
                  )

                  # For Transformer, don't load the full directory, rely on `transformers` instead
                  # But, do load the config file first.
                  if module_config["path"] == "":
                      kwargs = {}
                      for config_name in [
                          "sentence_bert_config.json",
                          "sentence_roberta_config.json",
                          "sentence_distilbert_config.json",
                          "sentence_camembert_config.json",
                          "sentence_albert_config.json",
                          "sentence_xlm-roberta_config.json",
                          "sentence_xlnet_config.json",
                      ]:
                          config_path = load_file_path(
                              model_name_or_path,
                              config_name,
                              token=token,
                              cache_folder=cache_folder,
                              revision=revision,
                              local_files_only=local_files_only,
                          )
                          if config_path is not None:
                              with open(config_path) as fIn:
                                  kwargs = json.load(fIn)
                                  # Don't allow configs to set trust_remote_code
                                  if "model_args" in kwargs and "trust_remote_code" in kwargs["model_args"]:
                                      kwargs["model_args"].pop("trust_remote_code")
                                  if "tokenizer_args" in kwargs and "trust_remote_code" in kwargs["tokenizer_args"]:
                                      kwargs["tokenizer_args"].pop("trust_remote_code")
                                  if "config_args" in kwargs and "trust_remote_code" in kwargs["config_args"]:
                                      kwargs["config_args"].pop("trust_remote_code")
                              break

                      hub_kwargs = {
                          "token": token,
                          "trust_remote_code": trust_remote_code,
                          "revision": revision,
                          "local_files_only": local_files_only,
                      }
                      # 3rd priority: config file
                      if "model_args" not in kwargs:
                          kwargs["model_args"] = {}
                      if "tokenizer_args" not in kwargs:
                          kwargs["tokenizer_args"] = {}
                      if "config_args" not in kwargs:
                          kwargs["config_args"] = {}

                      # 2nd priority: hub_kwargs
                      kwargs["model_args"].update(hub_kwargs)
                      kwargs["tokenizer_args"].update(hub_kwargs)
                      kwargs["config_args"].update(hub_kwargs)

                      # 1st priority: kwargs passed to SentenceTransformer
                      if model_kwargs:
                          kwargs["model_args"].update(model_kwargs)
                      if tokenizer_kwargs:
                          kwargs["tokenizer_args"].update(tokenizer_kwargs)
                      if config_kwargs:
                          kwargs["config_args"].update(config_kwargs)

                      # Try to initialize the module with a lot of kwargs, but only if the module supports them
                      # Otherwise we fall back to the load method
                      try:
                          module = module_class(model_name_or_path, cache_dir=cache_folder, backend=self.backend, **kwargs)
                      except TypeError:
                          module = module_class.load(model_name_or_path)
                  else:
                      # Normalize does not require any files to be loaded
                      if module_class == Normalize:
                          module_path = None
                      else:
                          module_path = load_dir_path(
                              model_name_or_path,
                              module_config["path"],
                              token=token,
                              cache_folder=cache_folder,
                              revision=revision,
                              local_files_only=local_files_only,
                          )
                      module = module_class.load(module_path)

                  modules[module_config["name"]] = module
                  module_kwargs[module_config["name"]] = module_config.get("kwargs", [])

              if revision is None:
                  path_parts = Path(modules_json_path)
                  if len(path_parts.parts) >= 2:
                      revision_path_part = Path(modules_json_path).parts[-2]
                      if len(revision_path_part) == 40:
                          revision = revision_path_part
              self.model_card_data.set_base_model(model_name_or_path, revision=revision)
              return modules, module_kwargs

          @staticmethod
          def load(input_path) -> SentenceTransformer:
              return SentenceTransformer(input_path)

          @property
          def device(self) -> device:
              """
              Get torch.device from module, assuming that the whole module has one device.
              In case there are no PyTorch parameters, fall back to CPU.
              """
              if isinstance(self[0], Transformer):
                  return self[0].auto_model.device

              try:
                  return next(self.parameters()).device
              except StopIteration:
                  # For nn.DataParallel compatibility in PyTorch 1.5

                  def find_tensor_attributes(module: nn.Module) -> list[tuple[str, Tensor]]:
                      tuples = [(k, v) for k, v in module.__dict__.items() if torch.is_tensor(v)]
                      return tuples

                  gen = self._named_members(get_members_fn=find_tensor_attributes)
                  try:
                      first_tuple = next(gen)
                      return first_tuple[1].device
                  except StopIteration:
                      return torch.device("cpu")

          @property
          def tokenizer(self) -> Any:
              """
              Property to get the tokenizer that is used by this model
              """
              return self._first_module().tokenizer

          @tokenizer.setter
          def tokenizer(self, value) -> None:
              """
              Property to set the tokenizer that should be used by this model
              """
              self._first_module().tokenizer = value

          @property
          def max_seq_length(self) -> int:
              """
              Returns the maximal input sequence length for the model. Longer inputs will be truncated.

              Returns:
                  int: The maximal input sequence length.

              Example:
                  ::

                      from sentence_transformers import SentenceTransformer

                      model = SentenceTransformer("all-mpnet-base-v2")
                      print(model.max_seq_length)
                      # => 384
              """
              return self._first_module().max_seq_length

          @max_seq_length.setter
          def max_seq_length(self, value) -> None:
              """
              Property to set the maximal input sequence length for the model. Longer inputs will be truncated.
              """
              self._first_module().max_seq_length = value

          @property
          def _target_device(self) -> torch.device:
              logger.warning(
                  "`SentenceTransformer._target_device` has been deprecated, please use `SentenceTransformer.device` instead.",
              )
              return self.device

          @_target_device.setter
          def _target_device(self, device: int | str | torch.device | None = None) -> None:
              self.to(device)

          @property
          def _no_split_modules(self) -> list[str]:
              try:
                  return self._first_module()._no_split_modules
              except AttributeError:
                  return []

          @property
          def _keys_to_ignore_on_save(self) -> list[str]:
              try:
                  return self._first_module()._keys_to_ignore_on_save
              except AttributeError:
                  return []

          def gradient_checkpointing_enable(self, gradient_checkpointing_kwargs=None) -> None:
              # Propagate the gradient checkpointing to the transformer model
              for module in self:
                  if isinstance(module, Transformer):
                      return module.auto_model.gradient_checkpointing_enable(gradient_checkpointing_kwargs)

  Loads or creates a SentenceTransformer model that can be used to map sentences / text to embeddings.

  ## Args

  `model_name_or_path` :`str`, optional
    If it is a filepath on disc, it loads the model from that path. If it is not a path, it first tries to download a pre-trained SentenceTransformer model. If that fails, tries to construct a model from the Hugging Face Hub with that name.
  `modules` :`Iterable[nn.Module]`, optional
    A list of torch Modules that should be called sequentially, can be used to create custom SentenceTransformer models from scratch.
  `device` :`str`, optional
    Device (like "cuda", "cpu", "mps", "npu") that should be used for computation. If None, checks if a GPU can be used.
  `prompts` :`Dict[str, str]`, optional
    A dictionary with prompts for the model. The key is the prompt name, the value is the prompt text. The prompt text will be prepended before any text to encode. For example: `{"query": "query: ", "passage": "passage: "}` or `{"clustering": "Identify the main category based on the titles in "}`.
  `default_prompt_name` :`str`, optional
    The name of the prompt that should be used by default. If not set, no prompt will be applied.
  `similarity_fn_name` :`str` or `SimilarityFunction`, optional
    The name of the similarity function to use. Valid options are "cosine", "dot", "euclidean", and "manhattan". If not set, it is automatically set to "cosine" if `similarity` or `similarity_pairwise` are called while `model.similarity_fn_name` is still `None`.
  `cache_folder` :`str`, optional
    Path to store models. Can also be set by the SENTENCE_TRANSFORMERS_HOME environment variable.
  `trust_remote_code` :`bool`, optional
    Whether or not to allow for custom models defined on the Hub in their own modeling files. This option should only be set to True for repositories you trust and in which you have read the code, as it will execute code present on the Hub on your local machine.
  `revision` :`str`, optional
    The specific model version to use. It can be a branch name, a tag name, or a commit id, for a stored model on Hugging Face.
  `local_files_only` :`bool`, optional
    Whether or not to only look at local files (i.e., do not try to download the model).
  `token` :`bool` or `str`, optional
    Hugging Face authentication token to download private models.
  `use_auth_token` :`bool` or `str`, optional
    Deprecated argument. Please use `token` instead.
  `truncate_dim` :`int`, optional
    The dimension to truncate sentence embeddings to. `None` does no truncation. Truncation is only applicable during inference when :meth:`SentenceTransformer.encode()` is called.
  `model_kwargs` :`Dict[str, Any]`, optional

    Additional model configuration parameters to be passed to the Hugging Face Transformers model. Particularly useful options are:

    - `torch_dtype`: Override the default `torch.dtype` and load the model under a specific `dtype`. The different options are:

          1. <code>torch.float16</code>, <code>torch.bfloat16</code> or <code>torch.float</code>: load in a specified
          <code>dtype</code>, ignoring the model's <code>config.torch\_dtype</code> if one exists. If not specified - the model will
          get loaded in <code>torch.float</code> (fp32).

          2. ``"auto"`` - A <code>torch\_dtype</code> entry in the <code>config.json</code> file of the model will be
          attempted to be used. If this entry isn't found then next check the <code>dtype</code> of the first weight in
          the checkpoint that's of a floating point type and use that as <code>dtype</code>. This will load the model
          using the <code>dtype</code> it was saved in at the end of the training. It can't be used as an indicator of how
          the model was trained. Since it could be trained in one of half precision dtypes, but saved in fp32.
          - <code>attn\_implementation</code>: The attention implementation to use in the model (if relevant). Can be any of
            `"eager"` (manual implementation of the attention), `"sdpa"` (using `F.scaled_dot_product_attention
            <https://pytorch.org/docs/master/generated/torch.nn.functional.scaled_dot_product_attention.html>`_),
            or `"flash_attention_2"` (using `Dao-AILab/flash-attention <https://github.com/Dao-AILab/flash-attention>`_).
            By default, if available, SDPA will be used for torch>=2.1.1. The default is otherwise the manual `"eager"`
            implementation.
          - <code>provider</code>: If backend is "onnx", this is the provider to use for inference, for example "CPUExecutionProvider",
            "CUDAExecutionProvider", etc. See <https://onnxruntime.ai/docs/execution-providers/> for all ONNX execution providers.
          - <code>file\_name</code>: If backend is "onnx" or "openvino", this is the file name to load, useful for loading optimized
            or quantized ONNX or OpenVINO models.
          - <code>export</code>: If backend is "onnx" or "openvino", then this is a boolean flag specifying whether this model should
            be exported to the backend. If not specified, the model will be exported only if the model repository or directory
            does not already contain an exported model.

    See the `PreTrainedModel.from_pretrained <https://huggingface.co/docs/transformers/en/main_classes/model#transformers.PreTrainedModel.from_pretrained>`_ documentation for more details.

  `tokenizer_kwargs` :`Dict[str, Any]`, optional
    Additional tokenizer configuration parameters to be passed to the Hugging Face Transformers tokenizer. See the `AutoTokenizer.from_pretrained <https://huggingface.co/docs/transformers/en/model_doc/auto#transformers.AutoTokenizer.from_pretrained>`_ documentation for more details.
  `config_kwargs` :`Dict[str, Any]`, optional
    Additional model configuration parameters to be passed to the Hugging Face Transformers config. See the `AutoConfig.from_pretrained <https://huggingface.co/docs/transformers/en/model_doc/auto#transformers.AutoConfig.from_pretrained>`_ documentation for more details.
  model_card_data (:class:`~sentence_transformers.model_card.SentenceTransformerModelCardData`, optional): A model
  card data object that contains information about the model. This is used to generate a model card when saving
  the model. If not set, a default model card data object is created.
  `backend` :`str`
    The backend to use for inference. Can be one of "torch" (default), "onnx", or "openvino". See https://sbert.net/docs/sentence_transformer/usage/efficiency.html for benchmarking information on the different backends.

  ## Example

  ::

      from sentence_transformers import SentenceTransformer

      # Load a pre-trained SentenceTransformer model
      model = SentenceTransformer('all-mpnet-base-v2')

      # Encode some texts
      sentences = [
          "The weather is lovely today.",
          "It's so sunny outside!",
          "He drove to the stadium.",
      ]
      embeddings = model.encode(sentences)
      print(embeddings.shape)
      # (3, 768)

      # Get the similarity scores between all sentences
      similarities = model.similarity(embeddings, embeddings)
      print(similarities)
      # tensor([[1.0000, 0.6817, 0.0492],
      #         [0.6817, 1.0000, 0.0421],
      #         [0.0492, 0.0421, 1.0000]])

  Initialize internal Module state, shared by both nn.Module and ScriptModule.

  ### Ancestors

  - torch.nn.modules.container.Sequential
  - torch.nn.modules.module.Module
  - sentence_transformers.fit_mixin.FitMixin
  - sentence_transformers.peft_mixin.PeftAdapterMixin

  ### Static methods

  `def load(input_path) ‑> sentence_transformers.SentenceTransformer.SentenceTransformer`
    Expand source code

        @staticmethod
        def load(input_path) -> SentenceTransformer:
            return SentenceTransformer(input_path)

  `def stop_multi_process_pool(pool: "dict[Literal['input', 'output', 'processes'], Any]") ‑> None`
    Expand source code

        @staticmethod
        def stop_multi_process_pool(pool: dict[Literal["input", "output", "processes"], Any]) -> None:
            """
            Stops all processes started with start_multi_process_pool.

            Args:
                pool (Dict[str, object]): A dictionary containing the input queue, output queue, and process list.

            Returns:
                None
            """
            for p in pool["processes"]:
                p.terminate()

            for p in pool["processes"]:
                p.join()
                p.close()

            pool["input"].close()
            pool["output"].close()

    Stops all processes started with start_multi_process_pool.

    ## Args

    `pool` :`Dict[str, object]`
      A dictionary containing the input queue, output queue, and process list.

    ## Returns

    None

  ### Instance variables

  `prop device : device`
    Expand source code

        @property
        def device(self) -> device:
            """
            Get torch.device from module, assuming that the whole module has one device.
            In case there are no PyTorch parameters, fall back to CPU.
            """
            if isinstance(self[0], Transformer):
                return self[0].auto_model.device

            try:
                return next(self.parameters()).device
            except StopIteration:
                # For nn.DataParallel compatibility in PyTorch 1.5

                def find_tensor_attributes(module: nn.Module) -> list[tuple[str, Tensor]]:
                    tuples = [(k, v) for k, v in module.__dict__.items() if torch.is_tensor(v)]
                    return tuples

                gen = self._named_members(get_members_fn=find_tensor_attributes)
                try:
                    first_tuple = next(gen)
                    return first_tuple[1].device
                except StopIteration:
                    return torch.device("cpu")

    Get torch.device from module, assuming that the whole module has one device. In case there are no PyTorch parameters, fall back to CPU.

  `prop max_seq_length : int`
    Expand source code

        @property
        def max_seq_length(self) -> int:
            """
            Returns the maximal input sequence length for the model. Longer inputs will be truncated.

            Returns:
                int: The maximal input sequence length.

            Example:
                ::

                    from sentence_transformers import SentenceTransformer

                    model = SentenceTransformer("all-mpnet-base-v2")
                    print(model.max_seq_length)
                    # => 384
            """
            return self._first_module().max_seq_length

    Returns the maximal input sequence length for the model. Longer inputs will be truncated.

    ## Returns

    `int`
      The maximal input sequence length.

    ## Example

    ::

        from sentence_transformers import SentenceTransformer

        model = SentenceTransformer("all-mpnet-base-v2")
        print(model.max_seq_length)
        # => 384

  `prop similarity : Callable[[Tensor | ndarray, Tensor | ndarray], Tensor]`
    Expand source code

        @property
        def similarity(self) -> Callable[[Tensor | ndarray, Tensor | ndarray], Tensor]:
            """
            Compute the similarity between two collections of embeddings. The output will be a matrix with the similarity
            scores between all embeddings from the first parameter and all embeddings from the second parameter. This
            differs from `similarity_pairwise` which computes the similarity between each pair of embeddings.

            Args:
                embeddings1 (Union[Tensor, ndarray]): [num_embeddings_1, embedding_dim] or [embedding_dim]-shaped numpy array or torch tensor.
                embeddings2 (Union[Tensor, ndarray]): [num_embeddings_2, embedding_dim] or [embedding_dim]-shaped numpy array or torch tensor.

            Returns:
                Tensor: A [num_embeddings_1, num_embeddings_2]-shaped torch tensor with similarity scores.

            Example:
                ::

                    >>> model = SentenceTransformer("all-mpnet-base-v2")
                    >>> sentences = [
                    ...     "The weather is so nice!",
                    ...     "It's so sunny outside.",
                    ...     "He's driving to the movie theater.",
                    ...     "She's going to the cinema.",
                    ... ]
                    >>> embeddings = model.encode(sentences, normalize_embeddings=True)
                    >>> model.similarity(embeddings, embeddings)
                    tensor([[1.0000, 0.7235, 0.0290, 0.1309],
                            [0.7235, 1.0000, 0.0613, 0.1129],
                            [0.0290, 0.0613, 1.0000, 0.5027],
                            [0.1309, 0.1129, 0.5027, 1.0000]])
                    >>> model.similarity_fn_name
                    "cosine"
                    >>> model.similarity_fn_name = "euclidean"
                    >>> model.similarity(embeddings, embeddings)
                    tensor([[-0.0000, -0.7437, -1.3935, -1.3184],
                            [-0.7437, -0.0000, -1.3702, -1.3320],
                            [-1.3935, -1.3702, -0.0000, -0.9973],
                            [-1.3184, -1.3320, -0.9973, -0.0000]])
            """
            if self.similarity_fn_name is None:
                self.similarity_fn_name = SimilarityFunction.COSINE
            return self._similarity

    Compute the similarity between two collections of embeddings. The output will be a matrix with the similarity scores between all embeddings from the first parameter and all embeddings from the second parameter. This differs from `similarity_pairwise` which computes the similarity between each pair of embeddings.

    ## Args

    `embeddings1` :`Union[Tensor, ndarray]`
      [num_embeddings_1, embedding_dim] or [embedding_dim]-shaped numpy array or torch tensor.
    `embeddings2` :`Union[Tensor, ndarray]`
      [num_embeddings_2, embedding_dim] or [embedding_dim]-shaped numpy array or torch tensor.

    ## Returns

    `Tensor`
      A [num_embeddings_1, num_embeddings_2]-shaped torch tensor with similarity scores.

    ## Example

    ::

        >>> model = SentenceTransformer("all-mpnet-base-v2")
        >>> sentences = [
        ...     "The weather is so nice!",
        ...     "It's so sunny outside.",
        ...     "He's driving to the movie theater.",
        ...     "She's going to the cinema.",
        ... ]
        >>> embeddings = model.encode(sentences, normalize_embeddings=True)
        >>> model.similarity(embeddings, embeddings)
        tensor([[1.0000, 0.7235, 0.0290, 0.1309],
                [0.7235, 1.0000, 0.0613, 0.1129],
                [0.0290, 0.0613, 1.0000, 0.5027],
                [0.1309, 0.1129, 0.5027, 1.0000]])
        >>> model.similarity_fn_name
        "cosine"
        >>> model.similarity_fn_name = "euclidean"
        >>> model.similarity(embeddings, embeddings)
        tensor([[-0.0000, -0.7437, -1.3935, -1.3184],
                [-0.7437, -0.0000, -1.3702, -1.3320],
                [-1.3935, -1.3702, -0.0000, -0.9973],
                [-1.3184, -1.3320, -0.9973, -0.0000]])

  `prop similarity_fn_name : Literal['cosine', 'dot', 'euclidean', 'manhattan']`
    Expand source code

        @property
        def similarity_fn_name(self) -> Literal["cosine", "dot", "euclidean", "manhattan"]:
            """Return the name of the similarity function used by :meth:`SentenceTransformer.similarity` and :meth:`SentenceTransformer.similarity_pairwise`.

            Returns:
                Optional[str]: The name of the similarity function. Can be None if not set, in which case it will
                    default to "cosine" when first called.

            Example:
                >>> model = SentenceTransformer("multi-qa-mpnet-base-dot-v1")
                >>> model.similarity_fn_name
                'dot'
            """
            if self._similarity_fn_name is None:
                self.similarity_fn_name = SimilarityFunction.COSINE
            return self._similarity_fn_name

    Return the name of the similarity function used by :meth:`SentenceTransformer.similarity` and :meth:`SentenceTransformer.similarity_pairwise`.

    ## Returns

    `Optional[str]`
      The name of the similarity function. Can be None if not set, in which case it will default to "cosine" when first called.

    ## Example

        >>> model = SentenceTransformer("multi-qa-mpnet-base-dot-v1")
        >>> model.similarity_fn_name
        'dot'

  `prop similarity_pairwise : Callable[[Tensor | ndarray, Tensor | ndarray], Tensor]`
    Expand source code

        @property
        def similarity_pairwise(self) -> Callable[[Tensor | ndarray, Tensor | ndarray], Tensor]:
            """
            Compute the similarity between two collections of embeddings. The output will be a vector with the similarity
            scores between each pair of embeddings.

            Args:
                embeddings1 (Union[Tensor, ndarray]): [num_embeddings, embedding_dim] or [embedding_dim]-shaped numpy array or torch tensor.
                embeddings2 (Union[Tensor, ndarray]): [num_embeddings, embedding_dim] or [embedding_dim]-shaped numpy array or torch tensor.

            Returns:
                Tensor: A [num_embeddings]-shaped torch tensor with pairwise similarity scores.

            Example:
                ::

                    >>> model = SentenceTransformer("all-mpnet-base-v2")
                    >>> sentences = [
                    ...     "The weather is so nice!",
                    ...     "It's so sunny outside.",
                    ...     "He's driving to the movie theater.",
                    ...     "She's going to the cinema.",
                    ... ]
                    >>> embeddings = model.encode(sentences, normalize_embeddings=True)
                    >>> model.similarity_pairwise(embeddings[::2], embeddings[1::2])
                    tensor([0.7235, 0.5027])
                    >>> model.similarity_fn_name
                    "cosine"
                    >>> model.similarity_fn_name = "euclidean"
                    >>> model.similarity_pairwise(embeddings[::2], embeddings[1::2])
                    tensor([-0.7437, -0.9973])
            """
            if self.similarity_fn_name is None:
                self.similarity_fn_name = SimilarityFunction.COSINE
            return self._similarity_pairwise

    Compute the similarity between two collections of embeddings. The output will be a vector with the similarity scores between each pair of embeddings.

    ## Args

    `embeddings1` :`Union[Tensor, ndarray]`
      [num_embeddings, embedding_dim] or [embedding_dim]-shaped numpy array or torch tensor.
    `embeddings2` :`Union[Tensor, ndarray]`
      [num_embeddings, embedding_dim] or [embedding_dim]-shaped numpy array or torch tensor.

    ## Returns

    `Tensor`
      A [num_embeddings]-shaped torch tensor with pairwise similarity scores.

    ## Example

    ::

        >>> model = SentenceTransformer("all-mpnet-base-v2")
        >>> sentences = [
        ...     "The weather is so nice!",
        ...     "It's so sunny outside.",
        ...     "He's driving to the movie theater.",
        ...     "She's going to the cinema.",
        ... ]
        >>> embeddings = model.encode(sentences, normalize_embeddings=True)
        >>> model.similarity_pairwise(embeddings[::2], embeddings[1::2])
        tensor([0.7235, 0.5027])
        >>> model.similarity_fn_name
        "cosine"
        >>> model.similarity_fn_name = "euclidean"
        >>> model.similarity_pairwise(embeddings[::2], embeddings[1::2])
        tensor([-0.7437, -0.9973])

  `prop tokenizer : Any`
    Expand source code

        @property
        def tokenizer(self) -> Any:
            """
            Property to get the tokenizer that is used by this model
            """
            return self._first_module().tokenizer

    Property to get the tokenizer that is used by this model

  ### Methods

  `def encode(self,
  sentences: str | list[str],
  prompt_name: str | None = None,
  prompt: str | None = None,
  batch_size: int = 32,
  show_progress_bar: bool | None = None,
  output_value: "Literal['sentence_embedding', 'token_embeddings'] | None" = 'sentence_embedding',
  precision: "Literal['float32', 'int8', 'uint8', 'binary', 'ubinary']" = 'float32',
  convert_to_numpy: bool = True,
  convert_to_tensor: bool = False,
  device: str = None,
  normalize_embeddings: bool = False,
  **kwargs) ‑> list[torch.Tensor] | numpy.ndarray | torch.Tensor`
    Expand source code

        def encode(
            self,
            sentences: str | list[str],
            prompt_name: str | None = None,
            prompt: str | None = None,
            batch_size: int = 32,
            show_progress_bar: bool | None = None,
            output_value: Literal["sentence_embedding", "token_embeddings"] | None = "sentence_embedding",
            precision: Literal["float32", "int8", "uint8", "binary", "ubinary"] = "float32",
            convert_to_numpy: bool = True,
            convert_to_tensor: bool = False,
            device: str = None,
            normalize_embeddings: bool = False,
            **kwargs,
        ) -> list[Tensor] | np.ndarray | Tensor:
            """
            Computes sentence embeddings.

            Args:
                sentences (Union[str, List[str]]): The sentences to embed.
                prompt_name (Optional[str], optional): The name of the prompt to use for encoding. Must be a key in the `prompts` dictionary,
                    which is either set in the constructor or loaded from the model configuration. For example if
                    ``prompt_name`` is "query" and the ``prompts`` is {"query": "query: ", ...}, then the sentence "What
                    is the capital of France?" will be encoded as "query: What is the capital of France?" because the sentence
                    is appended to the prompt. If ``prompt`` is also set, this argument is ignored. Defaults to None.
                prompt (Optional[str], optional): The prompt to use for encoding. For example, if the prompt is "query: ", then the
                    sentence "What is the capital of France?" will be encoded as "query: What is the capital of France?"
                    because the sentence is appended to the prompt. If ``prompt`` is set, ``prompt_name`` is ignored. Defaults to None.
                batch_size (int, optional): The batch size used for the computation. Defaults to 32.
                show_progress_bar (bool, optional): Whether to output a progress bar when encode sentences. Defaults to None.
                output_value (Optional[Literal["sentence_embedding", "token_embeddings"]], optional): The type of embeddings to return:
                    "sentence_embedding" to get sentence embeddings, "token_embeddings" to get wordpiece token embeddings, and `None`,
                    to get all output values. Defaults to "sentence_embedding".
                precision (Literal["float32", "int8", "uint8", "binary", "ubinary"], optional): The precision to use for the embeddings.
                    Can be "float32", "int8", "uint8", "binary", or "ubinary". All non-float32 precisions are quantized embeddings.
                    Quantized embeddings are smaller in size and faster to compute, but may have a lower accuracy. They are useful for
                    reducing the size of the embeddings of a corpus for semantic search, among other tasks. Defaults to "float32".
                convert_to_numpy (bool, optional): Whether the output should be a list of numpy vectors. If False, it is a list of PyTorch tensors.
                    Defaults to True.
                convert_to_tensor (bool, optional): Whether the output should be one large tensor. Overwrites `convert_to_numpy`.
                    Defaults to False.
                device (str, optional): Which :class:`torch.device` to use for the computation. Defaults to None.
                normalize_embeddings (bool, optional): Whether to normalize returned vectors to have length 1. In that case,
                    the faster dot-product (util.dot_score) instead of cosine similarity can be used. Defaults to False.

            Returns:
                Union[List[Tensor], ndarray, Tensor]: By default, a 2d numpy array with shape [num_inputs, output_dimension] is returned.
                If only one string input is provided, then the output is a 1d array with shape [output_dimension]. If ``convert_to_tensor``,
                a torch Tensor is returned instead. If ``self.truncate_dim <= output_dimension`` then output_dimension is ``self.truncate_dim``.

            Example:
                ::

                    from sentence_transformers import SentenceTransformer

                    # Load a pre-trained SentenceTransformer model
                    model = SentenceTransformer('all-mpnet-base-v2')

                    # Encode some texts
                    sentences = [
                        "The weather is lovely today.",
                        "It's so sunny outside!",
                        "He drove to the stadium.",
                    ]
                    embeddings = model.encode(sentences)
                    print(embeddings.shape)
                    # (3, 768)
            """
            if self.device.type == "hpu" and not self.is_hpu_graph_enabled:
                import habana_frameworks.torch as ht

                ht.hpu.wrap_in_hpu_graph(self, disable_tensor_cache=True)
                self.is_hpu_graph_enabled = True

            self.eval()
            if show_progress_bar is None:
                show_progress_bar = logger.getEffectiveLevel() in (logging.INFO, logging.DEBUG)

            if convert_to_tensor:
                convert_to_numpy = False

            if output_value != "sentence_embedding":
                convert_to_tensor = False
                convert_to_numpy = False

            input_was_string = False
            if isinstance(sentences, str) or not hasattr(
                sentences, "__len__"
            ):  # Cast an individual sentence to a list with length 1
                sentences = [sentences]
                input_was_string = True

            if prompt is None:
                if prompt_name is not None:
                    try:
                        prompt = self.prompts[prompt_name]
                    except KeyError:
                        raise ValueError(
                            f"Prompt name '{prompt_name}' not found in the configured prompts dictionary with keys {list(self.prompts.keys())!r}."
                        )
                elif self.default_prompt_name is not None:
                    prompt = self.prompts.get(self.default_prompt_name, None)
            else:
                if prompt_name is not None:
                    logger.warning(
                        "Encode with either a `prompt`, a `prompt_name`, or neither, but not both. "
                        "Ignoring the `prompt_name` in favor of `prompt`."
                    )

            extra_features = {}
            if prompt is not None:
                sentences = [prompt + sentence for sentence in sentences]

                # Some models (e.g. INSTRUCTOR, GRIT) require removing the prompt before pooling
                # Tracking the prompt length allow us to remove the prompt during pooling
                tokenized_prompt = self.tokenize([prompt])
                if "input_ids" in tokenized_prompt:
                    extra_features["prompt_length"] = tokenized_prompt["input_ids"].shape[-1] - 1

            if device is None:
                device = self.device

            self.to(device)

            all_embeddings = []
            length_sorted_idx = np.argsort([-self._text_length(sen) for sen in sentences])
            sentences_sorted = [sentences[idx] for idx in length_sorted_idx]

            for start_index in trange(0, len(sentences), batch_size, desc="Batches", disable=not show_progress_bar):
                sentences_batch = sentences_sorted[start_index : start_index + batch_size]
                features = self.tokenize(sentences_batch)
                if self.device.type == "hpu":
                    if "input_ids" in features:
                        curr_tokenize_len = features["input_ids"].shape
                        additional_pad_len = 2 ** math.ceil(math.log2(curr_tokenize_len[1])) - curr_tokenize_len[1]
                        features["input_ids"] = torch.cat(
                            (
                                features["input_ids"],
                                torch.ones((curr_tokenize_len[0], additional_pad_len), dtype=torch.int8),
                            ),
                            -1,
                        )
                        features["attention_mask"] = torch.cat(
                            (
                                features["attention_mask"],
                                torch.zeros((curr_tokenize_len[0], additional_pad_len), dtype=torch.int8),
                            ),
                            -1,
                        )
                        if "token_type_ids" in features:
                            features["token_type_ids"] = torch.cat(
                                (
                                    features["token_type_ids"],
                                    torch.zeros((curr_tokenize_len[0], additional_pad_len), dtype=torch.int8),
                                ),
                                -1,
                            )

                features = batch_to_device(features, device)
                features.update(extra_features)

                with torch.no_grad():
                    out_features = self.forward(features, **kwargs)
                    if self.device.type == "hpu":
                        out_features = copy.deepcopy(out_features)

                    out_features["sentence_embedding"] = truncate_embeddings(
                        out_features["sentence_embedding"], self.truncate_dim
                    )

                    if output_value == "token_embeddings":
                        embeddings = []
                        for token_emb, attention in zip(out_features[output_value], out_features["attention_mask"]):
                            last_mask_id = len(attention) - 1
                            while last_mask_id > 0 and attention[last_mask_id].item() == 0:
                                last_mask_id -= 1

                            embeddings.append(token_emb[0 : last_mask_id + 1])
                    elif output_value is None:  # Return all outputs
                        embeddings = []
                        for sent_idx in range(len(out_features["sentence_embedding"])):
                            row = {name: out_features[name][sent_idx] for name in out_features}
                            embeddings.append(row)
                    else:  # Sentence embeddings
                        embeddings = out_features[output_value]
                        embeddings = embeddings.detach()
                        if normalize_embeddings:
                            embeddings = torch.nn.functional.normalize(embeddings, p=2, dim=1)

                        # fixes for #522 and #487 to avoid oom problems on gpu with large datasets
                        if convert_to_numpy:
                            embeddings = embeddings.cpu()

                    all_embeddings.extend(embeddings)

            all_embeddings = [all_embeddings[idx] for idx in np.argsort(length_sorted_idx)]

            if precision and precision != "float32":
                all_embeddings = quantize_embeddings(all_embeddings, precision=precision)

            if convert_to_tensor:
                if len(all_embeddings):
                    if isinstance(all_embeddings, np.ndarray):
                        all_embeddings = torch.from_numpy(all_embeddings)
                    else:
                        all_embeddings = torch.stack(all_embeddings)
                else:
                    all_embeddings = torch.Tensor()
            elif convert_to_numpy:
                if not isinstance(all_embeddings, np.ndarray):
                    if all_embeddings and all_embeddings[0].dtype == torch.bfloat16:
                        all_embeddings = np.asarray([emb.float().numpy() for emb in all_embeddings])
                    else:
                        all_embeddings = np.asarray([emb.numpy() for emb in all_embeddings])
            elif isinstance(all_embeddings, np.ndarray):
                all_embeddings = [torch.from_numpy(embedding) for embedding in all_embeddings]

            if input_was_string:
                all_embeddings = all_embeddings[0]

            return all_embeddings

    Computes sentence embeddings.

    ## Args

    `sentences` :`Union[str, List[str]]`
      The sentences to embed.
    `prompt_name` :`Optional[str]`, optional
      The name of the prompt to use for encoding. Must be a key in the `prompts` dictionary, which is either set in the constructor or loaded from the model configuration. For example if `prompt_name` is "query" and the `prompts` is {"query": "query: ", …}, then the sentence "What is the capital of France?" will be encoded as "query: What is the capital of France?" because the sentence is appended to the prompt. If `prompt` is also set, this argument is ignored. Defaults to None.
    `prompt` :`Optional[str]`, optional
      The prompt to use for encoding. For example, if the prompt is "query: ", then the sentence "What is the capital of France?" will be encoded as "query: What is the capital of France?" because the sentence is appended to the prompt. If `prompt` is set, `prompt_name` is ignored. Defaults to None.
    `batch_size` :`int`, optional
      The batch size used for the computation. Defaults to 32.
    `show_progress_bar` :`bool`, optional
      Whether to output a progress bar when encode sentences. Defaults to None.
    output_value (Optional[Literal["sentence_embedding", "token_embeddings"]], optional): The type of embeddings to return:
    "sentence_embedding" to get sentence embeddings, "token_embeddings" to get wordpiece token embeddings, and `None`,
    to get all output values. Defaults to "sentence_embedding".
    precision (Literal["float32", "int8", "uint8", "binary", "ubinary"], optional): The precision to use for the embeddings.
    Can be "float32", "int8", "uint8", "binary", or "ubinary". All non-float32 precisions are quantized embeddings.
    Quantized embeddings are smaller in size and faster to compute, but may have a lower accuracy. They are useful for
    reducing the size of the embeddings of a corpus for semantic search, among other tasks. Defaults to "float32".
    `convert_to_numpy` :`bool`, optional
      Whether the output should be a list of numpy vectors. If False, it is a list of PyTorch tensors. Defaults to True.
    `convert_to_tensor` :`bool`, optional
      Whether the output should be one large tensor. Overwrites `convert_to_numpy`. Defaults to False.
    `device` :`str`, optional
      Which :class:`torch.device` to use for the computation. Defaults to None.
    `normalize_embeddings` :`bool`, optional
      Whether to normalize returned vectors to have length 1. In that case, the faster dot-product (util.dot_score) instead of cosine similarity can be used. Defaults to False.

    ## Returns

    `Union[List[Tensor], ndarray, Tensor]`
      By default, a 2d numpy array with shape [num_inputs, output_dimension] is returned.

    If only one string input is provided, then the output is a 1d array with shape [output_dimension]. If `convert_to_tensor`, a torch Tensor is returned instead. If `self.truncate_dim <= output_dimension` then output_dimension is `self.truncate_dim`.

    ## Example

    ::

        from sentence_transformers import SentenceTransformer

        # Load a pre-trained SentenceTransformer model
        model = SentenceTransformer('all-mpnet-base-v2')

        # Encode some texts
        sentences = [
            "The weather is lovely today.",
            "It's so sunny outside!",
            "He drove to the stadium.",
        ]
        embeddings = model.encode(sentences)
        print(embeddings.shape)
        # (3, 768)

  `def encode_multi_process(self,
  sentences: list[str],
  pool: "dict[Literal['input', 'output', 'processes'], Any]",
  prompt_name: str | None = None,
  prompt: str | None = None,
  batch_size: int = 32,
  chunk_size: int = None,
  show_progress_bar: bool | None = None,
  precision: "Literal['float32', 'int8', 'uint8', 'binary', 'ubinary']" = 'float32',
  normalize_embeddings: bool = False) ‑> numpy.ndarray`
    Expand source code

        def encode_multi_process(
            self,
            sentences: list[str],
            pool: dict[Literal["input", "output", "processes"], Any],
            prompt_name: str | None = None,
            prompt: str | None = None,
            batch_size: int = 32,
            chunk_size: int = None,
            show_progress_bar: bool | None = None,
            precision: Literal["float32", "int8", "uint8", "binary", "ubinary"] = "float32",
            normalize_embeddings: bool = False,
        ) -> np.ndarray:
            """
            Encodes a list of sentences using multiple processes and GPUs via
            :meth:`SentenceTransformer.encode <sentence_transformers.SentenceTransformer.encode>`.
            The sentences are chunked into smaller packages and sent to individual processes, which encode them on different
            GPUs or CPUs. This method is only suitable for encoding large sets of sentences.

            Args:
                sentences (List[str]): List of sentences to encode.
                pool (Dict[Literal["input", "output", "processes"], Any]): A pool of workers started with
                    :meth:`SentenceTransformer.start_multi_process_pool <sentence_transformers.SentenceTransformer.start_multi_process_pool>`.
                prompt_name (Optional[str], optional): The name of the prompt to use for encoding. Must be a key in the `prompts` dictionary,
                    which is either set in the constructor or loaded from the model configuration. For example if
                    ``prompt_name`` is "query" and the ``prompts`` is {"query": "query: ", ...}, then the sentence "What
                    is the capital of France?" will be encoded as "query: What is the capital of France?" because the sentence
                    is appended to the prompt. If ``prompt`` is also set, this argument is ignored. Defaults to None.
                prompt (Optional[str], optional): The prompt to use for encoding. For example, if the prompt is "query: ", then the
                    sentence "What is the capital of France?" will be encoded as "query: What is the capital of France?"
                    because the sentence is appended to the prompt. If ``prompt`` is set, ``prompt_name`` is ignored. Defaults to None.
                batch_size (int): Encode sentences with batch size. (default: 32)
                chunk_size (int): Sentences are chunked and sent to the individual processes. If None, it determines a
                    sensible size. Defaults to None.
                show_progress_bar (bool, optional): Whether to output a progress bar when encode sentences. Defaults to None.
                precision (Literal["float32", "int8", "uint8", "binary", "ubinary"]): The precision to use for the
                    embeddings. Can be "float32", "int8", "uint8", "binary", or "ubinary". All non-float32 precisions
                    are quantized embeddings. Quantized embeddings are smaller in size and faster to compute, but may
                    have lower accuracy. They are useful for reducing the size of the embeddings of a corpus for
                    semantic search, among other tasks. Defaults to "float32".
                normalize_embeddings (bool): Whether to normalize returned vectors to have length 1. In that case,
                    the faster dot-product (util.dot_score) instead of cosine similarity can be used. Defaults to False.

            Returns:
                np.ndarray: A 2D numpy array with shape [num_inputs, output_dimension].

            Example:
                ::

                    from sentence_transformers import SentenceTransformer

                    def main():
                        model = SentenceTransformer("all-mpnet-base-v2")
                        sentences = ["The weather is so nice!", "It's so sunny outside.", "He's driving to the movie theater.", "She's going to the cinema."] * 1000

                        pool = model.start_multi_process_pool()
                        embeddings = model.encode_multi_process(sentences, pool)
                        model.stop_multi_process_pool(pool)

                        print(embeddings.shape)
                        # => (4000, 768)

                    if __name__ == "__main__":
                        main()
            """

            if chunk_size is None:
                chunk_size = min(math.ceil(len(sentences) / len(pool["processes"]) / 10), 5000)

            if show_progress_bar is None:
                show_progress_bar = logger.getEffectiveLevel() in (logging.INFO, logging.DEBUG)

            logger.debug(f"Chunk data into {math.ceil(len(sentences) / chunk_size)} packages of size {chunk_size}")

            input_queue = pool["input"]
            last_chunk_id = 0
            chunk = []

            for sentence in sentences:
                chunk.append(sentence)
                if len(chunk) >= chunk_size:
                    input_queue.put(
                        [last_chunk_id, batch_size, chunk, prompt_name, prompt, precision, normalize_embeddings]
                    )
                    last_chunk_id += 1
                    chunk = []

            if len(chunk) > 0:
                input_queue.put([last_chunk_id, batch_size, chunk, prompt_name, prompt, precision, normalize_embeddings])
                last_chunk_id += 1

            output_queue = pool["output"]
            results_list = sorted(
                [output_queue.get() for _ in trange(last_chunk_id, desc="Chunks", disable=not show_progress_bar)],
                key=lambda x: x[0],
            )
            embeddings = np.concatenate([result[1] for result in results_list])
            return embeddings

    Encodes a list of sentences using multiple processes and GPUs via :meth:`SentenceTransformer.encode <sentence_transformers.SentenceTransformer.encode>`. The sentences are chunked into smaller packages and sent to individual processes, which encode them on different GPUs or CPUs. This method is only suitable for encoding large sets of sentences.

    ## Args

    `sentences` :`List[str]`
      List of sentences to encode.
    pool (Dict[Literal["input", "output", "processes"], Any]): A pool of workers started with
    :meth:`SentenceTransformer.start_multi_process_pool <sentence_transformers.SentenceTransformer.start_multi_process_pool>`.
    `prompt_name` :`Optional[str]`, optional
      The name of the prompt to use for encoding. Must be a key in the `prompts` dictionary, which is either set in the constructor or loaded from the model configuration. For example if `prompt_name` is "query" and the `prompts` is {"query": "query: ", …}, then the sentence "What is the capital of France?" will be encoded as "query: What is the capital of France?" because the sentence is appended to the prompt. If `prompt` is also set, this argument is ignored. Defaults to None.
    `prompt` :`Optional[str]`, optional
      The prompt to use for encoding. For example, if the prompt is "query: ", then the sentence "What is the capital of France?" will be encoded as "query: What is the capital of France?" because the sentence is appended to the prompt. If `prompt` is set, `prompt_name` is ignored. Defaults to None.
    `batch_size` :`int`
      Encode sentences with batch size. (default: 32)
    `chunk_size` :`int`
      Sentences are chunked and sent to the individual processes. If None, it determines a sensible size. Defaults to None.
    `show_progress_bar` :`bool`, optional
      Whether to output a progress bar when encode sentences. Defaults to None.
    precision (Literal["float32", "int8", "uint8", "binary", "ubinary"]): The precision to use for the
    embeddings. Can be "float32", "int8", "uint8", "binary", or "ubinary". All non-float32 precisions
    are quantized embeddings. Quantized embeddings are smaller in size and faster to compute, but may
    have lower accuracy. They are useful for reducing the size of the embeddings of a corpus for
    semantic search, among other tasks. Defaults to "float32".
    `normalize_embeddings` :`bool`
      Whether to normalize returned vectors to have length 1. In that case, the faster dot-product (util.dot_score) instead of cosine similarity can be used. Defaults to False.

    ## Returns

    `np.ndarray`
      A 2D numpy array with shape [num_inputs, output_dimension].

    ## Example

    ::

        from sentence_transformers import SentenceTransformer

        def main():
            model = SentenceTransformer("all-mpnet-base-v2")
            sentences = ["The weather is so nice!", "It's so sunny outside.", "He's driving to the movie theater.", "She's going to the cinema."] * 1000

            pool = model.start_multi_process_pool()
            embeddings = model.encode_multi_process(sentences, pool)
            model.stop_multi_process_pool(pool)

            print(embeddings.shape)
            # => (4000, 768)

        if __name__ == "__main__":
            main()

  `def evaluate(self, evaluator: SentenceEvaluator, output_path: str = None) ‑> dict[str, float] | float`
    Expand source code

        def evaluate(self, evaluator: SentenceEvaluator, output_path: str = None) -> dict[str, float] | float:
            """
            Evaluate the model based on an evaluator

            Args:
                evaluator (SentenceEvaluator): The evaluator used to evaluate the model.
                output_path (str, optional): The path where the evaluator can write the results. Defaults to None.

            Returns:
                The evaluation results.
            """
            if output_path is not None:
                os.makedirs(output_path, exist_ok=True)
            return evaluator(self, output_path)

    Evaluate the model based on an evaluator

    ## Args

    `evaluator` :`SentenceEvaluator`
      The evaluator used to evaluate the model.
    `output_path` :`str`, optional
      The path where the evaluator can write the results. Defaults to None.

    ## Returns

    The evaluation results.

  `def forward(self,
  input: dict[str, Tensor],
  **kwargs) ‑> dict[str, torch.Tensor]`
    Expand source code

        def forward(self, input: dict[str, Tensor], **kwargs) -> dict[str, Tensor]:
            if self.module_kwargs is None:
                return super().forward(input)

            for module_name, module in self.named_children():
                module_kwarg_keys = self.module_kwargs.get(module_name, [])
                module_kwargs = {key: value for key, value in kwargs.items() if key in module_kwarg_keys}
                input = module(input, **module_kwargs)
            return input

    Define the computation performed at every call.

    Should be overridden by all subclasses.

    Note

    Although the recipe for forward pass needs to be defined within this function, one should call the :class:`Module` instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

  `def get_backend(self) ‑> Literal['torch', 'onnx', 'openvino']`
    Expand source code

        def get_backend(self) -> Literal["torch", "onnx", "openvino"]:
            """Return the backend used for inference, which can be one of "torch", "onnx", or "openvino".

            Returns:
                str: The backend used for inference.
            """
            return self.backend

    Return the backend used for inference, which can be one of "torch", "onnx", or "openvino".

    ## Returns

    `str`
      The backend used for inference.
  `def get_max_seq_length(self) ‑> int | None`
    Expand source code

        def get_max_seq_length(self) -> int | None:
            """
            Returns the maximal sequence length that the model accepts. Longer inputs will be truncated.

            Returns:
                Optional[int]: The maximal sequence length that the model accepts, or None if it is not defined.
            """
            if hasattr(self._first_module(), "max_seq_length"):
                return self._first_module().max_seq_length

            return None

    Returns the maximal sequence length that the model accepts. Longer inputs will be truncated.

    ## Returns

    `Optional[int]`
      The maximal sequence length that the model accepts, or None if it is not defined.
  `def get_sentence_embedding_dimension(self) ‑> int | None`
    Expand source code

        def get_sentence_embedding_dimension(self) -> int | None:
            """
            Returns the number of dimensions in the output of :meth:`SentenceTransformer.encode <sentence_transformers.SentenceTransformer.encode>`.

            Returns:
                Optional[int]: The number of dimensions in the output of `encode`. If it's not known, it's `None`.
            """
            output_dim = None
            for mod in reversed(self._modules.values()):
                sent_embedding_dim_method = getattr(mod, "get_sentence_embedding_dimension", None)
                if callable(sent_embedding_dim_method):
                    output_dim = sent_embedding_dim_method()
                    break
            if self.truncate_dim is not None:
                # The user requested truncation. If they set it to a dim greater than output_dim,
                # no truncation will actually happen. So return output_dim instead of self.truncate_dim
                return min(output_dim or np.inf, self.truncate_dim)
            return output_dim

    Returns the number of dimensions in the output of :meth:`SentenceTransformer.encode <sentence_transformers.SentenceTransformer.encode>`.

    ## Returns

    `Optional[int]`
      The number of dimensions in the output of `encode`. If it's not known, it's `None`.
  `def get_sentence_features(self, *features) ‑> dict[typing.Literal['sentence_embedding'], torch.Tensor]`
    Expand source code

        def get_sentence_features(self, *features) -> dict[Literal["sentence_embedding"], Tensor]:
            return self._first_module().get_sentence_features(*features)

  `def gradient_checkpointing_enable(self, gradient_checkpointing_kwargs=None) ‑> None`
    Expand source code

        def gradient_checkpointing_enable(self, gradient_checkpointing_kwargs=None) -> None:
            # Propagate the gradient checkpointing to the transformer model
            for module in self:
                if isinstance(module, Transformer):
                    return module.auto_model.gradient_checkpointing_enable(gradient_checkpointing_kwargs)

  `def push_to_hub(self,
  repo_id: str,
  token: str | None = None,
  private: bool | None = None,
  safe_serialization: bool = True,
  commit_message: str | None = None,
  local_model_path: str | None = None,
  exist_ok: bool = False,
  replace_model_card: bool = False,
  train_datasets: list[str] | None = None,
  revision: str | None = None,
  create_pr: bool = False) ‑> str`
    Expand source code

            def push_to_hub(
                self,
                repo_id: str,
                token: str | None = None,
                private: bool | None = None,
                safe_serialization: bool = True,
                commit_message: str | None = None,
                local_model_path: str | None = None,
                exist_ok: bool = False,
                replace_model_card: bool = False,
                train_datasets: list[str] | None = None,
                revision: str | None = None,
                create_pr: bool = False,
            ) -> str:
                """
                Uploads all elements of this Sentence Transformer to a new HuggingFace Hub repository.

                Args:
                    repo_id (str): Repository name for your model in the Hub, including the user or organization.
                    token (str, optional): An authentication token (See https://huggingface.co/settings/token)
                    private (bool, optional): Set to true, for hosting a private model
                    safe_serialization (bool, optional): If true, save the model using safetensors. If false, save the model the traditional PyTorch way
                    commit_message (str, optional): Message to commit while pushing.
                    local_model_path (str, optional): Path of the model locally. If set, this file path will be uploaded. Otherwise, the current model will be uploaded
                    exist_ok (bool, optional): If true, saving to an existing repository is OK. If false, saving only to a new repository is possible
                    replace_model_card (bool, optional): If true, replace an existing model card in the hub with the automatically created model card
                    train_datasets (List[str], optional): Datasets used to train the model. If set, the datasets will be added to the model card in the Hub.
                    revision (str, optional): Branch to push the uploaded files to
                    create_pr (bool, optional): If True, create a pull request instead of pushing directly to the main branch

                Returns:
                    str: The url of the commit of your model in the repository on the Hugging Face Hub.
                """
                api = HfApi(token=token)
                repo_url = api.create_repo(
                    repo_id=repo_id,
                    private=private,
                    repo_type=None,
                    exist_ok=exist_ok or create_pr,
                )
                repo_id = repo_url.repo_id  # Update the repo_id in case the old repo_id didn't contain a user or organization
                self.model_card_data.set_model_id(repo_id)
                if revision is not None:
                    api.create_branch(repo_id=repo_id, branch=revision, exist_ok=True)

                if commit_message is None:
                    backend = self.get_backend()
                    if backend == "torch":
                        commit_message = "Add new SentenceTransformer model"
                    else:
                        commit_message = f"Add new SentenceTransformer model with an {backend} backend"

                commit_description = ""
                if create_pr:
                    commit_description = f"""\
        Hello!

        *This pull request has been automatically generated from the [`push_to_hub`](https://sbert.net/docs/package_reference/sentence_transformer/SentenceTransformer.html#sentence_transformers.SentenceTransformer.push_to_hub) method from the Sentence Transformers library.*

        ## Full Model Architecture:
        ```
        {self}
        ```

        ## Tip:
        Consider testing this pull request before merging by loading the model from this PR with the `revision` argument:
        ```python
        from sentence_transformers import SentenceTransformer

        # TODO: Fill in the PR number
        pr_number = 2
        model = SentenceTransformer(
            "{repo_id}",
            revision=f"refs/pr/{{pr_number}}",
            backend="{self.get_backend()}",
        )

        # Verify that everything works as expected
        embeddings = model.encode(["The weather is lovely today.", "It's so sunny outside!", "He drove to the stadium."])
        print(embeddings.shape)

        similarities = model.similarity(embeddings, embeddings)
        print(similarities)
        ```
        """

                if local_model_path:
                    folder_url = api.upload_folder(
                        repo_id=repo_id,
                        folder_path=local_model_path,
                        commit_message=commit_message,
                        commit_description=commit_description,
                        revision=revision,
                        create_pr=create_pr,
                    )
                else:
                    with tempfile.TemporaryDirectory() as tmp_dir:
                        create_model_card = replace_model_card or not os.path.exists(os.path.join(tmp_dir, "README.md"))
                        self.save_pretrained(
                            tmp_dir,
                            model_name=repo_url.repo_id,
                            create_model_card=create_model_card,
                            train_datasets=train_datasets,
                            safe_serialization=safe_serialization,
                        )
                        folder_url = api.upload_folder(
                            repo_id=repo_id,
                            folder_path=tmp_dir,
                            commit_message=commit_message,
                            commit_description=commit_description,
                            revision=revision,
                            create_pr=create_pr,
                        )

                if create_pr:
                    return folder_url.pr_url
                return folder_url.commit_url

    Uploads all elements of this Sentence Transformer to a new HuggingFace Hub repository.

    ## Args

    `repo_id` :`str`
      Repository name for your model in the Hub, including the user or organization.
    `token` :`str`, optional
      An authentication token (See https://huggingface.co/settings/token)
    `private` :`bool`, optional
      Set to true, for hosting a private model
    `safe_serialization` :`bool`, optional
      If true, save the model using safetensors. If false, save the model the traditional PyTorch way
    `commit_message` :`str`, optional
      Message to commit while pushing.
    `local_model_path` :`str`, optional
      Path of the model locally. If set, this file path will be uploaded. Otherwise, the current model will be uploaded
    `exist_ok` :`bool`, optional
      If true, saving to an existing repository is OK. If false, saving only to a new repository is possible
    `replace_model_card` :`bool`, optional
      If true, replace an existing model card in the hub with the automatically created model card
    `train_datasets` :`List[str]`, optional
      Datasets used to train the model. If set, the datasets will be added to the model card in the Hub.
    `revision` :`str`, optional
      Branch to push the uploaded files to
    `create_pr` :`bool`, optional
      If True, create a pull request instead of pushing directly to the main branch

    ## Returns

    `str`
      The url of the commit of your model in the repository on the Hugging Face Hub.
  `def save(self,
  path: str,
  model_name: str | None = None,
  create_model_card: bool = True,
  train_datasets: list[str] | None = None,
  safe_serialization: bool = True) ‑> None`
    Expand source code

        def save(
            self,
            path: str,
            model_name: str | None = None,
            create_model_card: bool = True,
            train_datasets: list[str] | None = None,
            safe_serialization: bool = True,
        ) -> None:
            """
            Saves a model and its configuration files to a directory, so that it can be loaded
            with ``SentenceTransformer(path)`` again.

            Args:
                path (str): Path on disc where the model will be saved.
                model_name (str, optional): Optional model name.
                create_model_card (bool, optional): If True, create a README.md with basic information about this model.
                train_datasets (List[str], optional): Optional list with the names of the datasets used to train the model.
                safe_serialization (bool, optional): If True, save the model using safetensors. If False, save the model
                    the traditional (but unsafe) PyTorch way.
            """
            if path is None:
                return

            os.makedirs(path, exist_ok=True)

            logger.info(f"Save model to {path}")
            modules_config = []

            # Save some model info
            self._model_config["__version__"] = {
                "sentence_transformers": __version__,
                "transformers": transformers.__version__,
                "pytorch": torch.__version__,
            }

            with open(os.path.join(path, "config_sentence_transformers.json"), "w") as fOut:
                config = self._model_config.copy()
                config["prompts"] = self.prompts
                config["default_prompt_name"] = self.default_prompt_name
                config["similarity_fn_name"] = self.similarity_fn_name
                json.dump(config, fOut, indent=2)

            # Save modules
            for idx, name in enumerate(self._modules):
                module = self._modules[name]
                if idx == 0 and hasattr(module, "save_in_root"):  # Save first module in the main folder
                    model_path = path + "/"
                else:
                    model_path = os.path.join(path, str(idx) + "_" + type(module).__name__)

                os.makedirs(model_path, exist_ok=True)
                # Try to save with safetensors, but fall back to the traditional PyTorch way if the module doesn't support it
                try:
                    module.save(model_path, safe_serialization=safe_serialization)
                except TypeError:
                    module.save(model_path)

                # "module" only works for Sentence Transformers as the modules have the same names as the classes
                class_ref = type(module).__module__
                # For remote modules, we want to remove "transformers_modules.{repo_name}":
                if class_ref.startswith("transformers_modules."):
                    class_file = sys.modules[class_ref].__file__

                    # Save the custom module file
                    dest_file = Path(model_path) / (Path(class_file).name)
                    shutil.copy(class_file, dest_file)

                    # Save all files importeed in the custom module file
                    for needed_file in get_relative_import_files(class_file):
                        dest_file = Path(model_path) / (Path(needed_file).name)
                        shutil.copy(needed_file, dest_file)

                    # For remote modules, we want to ignore the "transformers_modules.{repo_id}" part,
                    # i.e. we only want the filename
                    class_ref = f"{class_ref.split('.')[-1]}.{type(module).__name__}"
                # For other cases, we want to add the class name:
                elif not class_ref.startswith("sentence_transformers."):
                    class_ref = f"{class_ref}.{type(module).__name__}"
                modules_config.append({"idx": idx, "name": name, "path": os.path.basename(model_path), "type": class_ref})

            with open(os.path.join(path, "modules.json"), "w") as fOut:
                json.dump(modules_config, fOut, indent=2)

            # Create model card
            if create_model_card:
                self._create_model_card(path, model_name, train_datasets)

    Saves a model and its configuration files to a directory, so that it can be loaded with `SentenceTransformer(path)` again.

    ## Args

    `path` :`str`
      Path on disc where the model will be saved.
    `model_name` :`str`, optional
      Optional model name.
    `create_model_card` :`bool`, optional
      If True, create a README.md with basic information about this model.
    `train_datasets` :`List[str]`, optional
      Optional list with the names of the datasets used to train the model.
    `safe_serialization` :`bool`, optional
      If True, save the model using safetensors. If False, save the model the traditional (but unsafe) PyTorch way.
  `def save_pretrained(self,
  path: str,
  model_name: str | None = None,
  create_model_card: bool = True,
  train_datasets: list[str] | None = None,
  safe_serialization: bool = True) ‑> None`
    Expand source code

        def save_pretrained(
            self,
            path: str,
            model_name: str | None = None,
            create_model_card: bool = True,
            train_datasets: list[str] | None = None,
            safe_serialization: bool = True,
        ) -> None:
            """
            Saves a model and its configuration files to a directory, so that it can be loaded
            with ``SentenceTransformer(path)`` again.

            Args:
                path (str): Path on disc where the model will be saved.
                model_name (str, optional): Optional model name.
                create_model_card (bool, optional): If True, create a README.md with basic information about this model.
                train_datasets (List[str], optional): Optional list with the names of the datasets used to train the model.
                safe_serialization (bool, optional): If True, save the model using safetensors. If False, save the model
                    the traditional (but unsafe) PyTorch way.
            """
            self.save(
                path,
                model_name=model_name,
                create_model_card=create_model_card,
                train_datasets=train_datasets,
                safe_serialization=safe_serialization,
            )

    Saves a model and its configuration files to a directory, so that it can be loaded with `SentenceTransformer(path)` again.

    ## Args

    `path` :`str`
      Path on disc where the model will be saved.
    `model_name` :`str`, optional
      Optional model name.
    `create_model_card` :`bool`, optional
      If True, create a README.md with basic information about this model.
    `train_datasets` :`List[str]`, optional
      Optional list with the names of the datasets used to train the model.
    `safe_serialization` :`bool`, optional
      If True, save the model using safetensors. If False, save the model the traditional (but unsafe) PyTorch way.
  `def save_to_hub(self,
  repo_id: str,
  organization: str | None = None,
  token: str | None = None,
  private: bool | None = None,
  safe_serialization: bool = True,
  commit_message: str = 'Add new SentenceTransformer model.',
  local_model_path: str | None = None,
  exist_ok: bool = False,
  replace_model_card: bool = False,
  train_datasets: list[str] | None = None) ‑> str`
    Expand source code

        @save_to_hub_args_decorator
        def save_to_hub(
            self,
            repo_id: str,
            organization: str | None = None,
            token: str | None = None,
            private: bool | None = None,
            safe_serialization: bool = True,
            commit_message: str = "Add new SentenceTransformer model.",
            local_model_path: str | None = None,
            exist_ok: bool = False,
            replace_model_card: bool = False,
            train_datasets: list[str] | None = None,
        ) -> str:
            """
            DEPRECATED, use `push_to_hub` instead.

            Uploads all elements of this Sentence Transformer to a new HuggingFace Hub repository.

            Args:
                repo_id (str): Repository name for your model in the Hub, including the user or organization.
                token (str, optional): An authentication token (See https://huggingface.co/settings/token)
                private (bool, optional): Set to true, for hosting a private model
                safe_serialization (bool, optional): If true, save the model using safetensors. If false, save the model the traditional PyTorch way
                commit_message (str, optional): Message to commit while pushing.
                local_model_path (str, optional): Path of the model locally. If set, this file path will be uploaded. Otherwise, the current model will be uploaded
                exist_ok (bool, optional): If true, saving to an existing repository is OK. If false, saving only to a new repository is possible
                replace_model_card (bool, optional): If true, replace an existing model card in the hub with the automatically created model card
                train_datasets (List[str], optional): Datasets used to train the model. If set, the datasets will be added to the model card in the Hub.

            Returns:
                str: The url of the commit of your model in the repository on the Hugging Face Hub.
            """
            logger.warning(
                "The `save_to_hub` method is deprecated and will be removed in a future version of SentenceTransformers."
                " Please use `push_to_hub` instead for future model uploads."
            )

            if organization:
                if "/" not in repo_id:
                    logger.warning(
                        f'Providing an `organization` to `save_to_hub` is deprecated, please use `repo_id="{organization}/{repo_id}"` instead.'
                    )
                    repo_id = f"{organization}/{repo_id}"
                elif repo_id.split("/")[0] != organization:
                    raise ValueError(
                        "Providing an `organization` to `save_to_hub` is deprecated, please only use `repo_id`."
                    )
                else:
                    logger.warning(
                        f'Providing an `organization` to `save_to_hub` is deprecated, please only use `repo_id="{repo_id}"` instead.'
                    )

            return self.push_to_hub(
                repo_id=repo_id,
                token=token,
                private=private,
                safe_serialization=safe_serialization,
                commit_message=commit_message,
                local_model_path=local_model_path,
                exist_ok=exist_ok,
                replace_model_card=replace_model_card,
                train_datasets=train_datasets,
            )

    DEPRECATED, use `push_to_hub` instead.

    Uploads all elements of this Sentence Transformer to a new HuggingFace Hub repository.

    ## Args

    `repo_id` :`str`
      Repository name for your model in the Hub, including the user or organization.
    `token` :`str`, optional
      An authentication token (See https://huggingface.co/settings/token)
    `private` :`bool`, optional
      Set to true, for hosting a private model
    `safe_serialization` :`bool`, optional
      If true, save the model using safetensors. If false, save the model the traditional PyTorch way
    `commit_message` :`str`, optional
      Message to commit while pushing.
    `local_model_path` :`str`, optional
      Path of the model locally. If set, this file path will be uploaded. Otherwise, the current model will be uploaded
    `exist_ok` :`bool`, optional
      If true, saving to an existing repository is OK. If false, saving only to a new repository is possible
    `replace_model_card` :`bool`, optional
      If true, replace an existing model card in the hub with the automatically created model card
    `train_datasets` :`List[str]`, optional
      Datasets used to train the model. If set, the datasets will be added to the model card in the Hub.

    ## Returns

    `str`
      The url of the commit of your model in the repository on the Hugging Face Hub.
  `def set_pooling_include_prompt(self, include_prompt: bool) ‑> None`
    Expand source code

        def set_pooling_include_prompt(self, include_prompt: bool) -> None:
            """
            Sets the `include_prompt` attribute in the pooling layer in the model, if there is one.

            This is useful for INSTRUCTOR models, as the prompt should be excluded from the pooling strategy
            for these models.

            Args:
                include_prompt (bool): Whether to include the prompt in the pooling layer.

            Returns:
                None
            """
            for module in self:
                if isinstance(module, Pooling):
                    module.include_prompt = include_prompt
                    break

    Sets the `include_prompt` attribute in the pooling layer in the model, if there is one.

    This is useful for INSTRUCTOR models, as the prompt should be excluded from the pooling strategy for these models.

    ## Args

    `include_prompt` :`bool`
      Whether to include the prompt in the pooling layer.

    ## Returns

    None

  `def start_multi_process_pool(self, target_devices: list[str] = None) ‑> dict[typing.Literal['input', 'output', 'processes'], typing.Any]`
    Expand source code

        def start_multi_process_pool(
            self, target_devices: list[str] = None
        ) -> dict[Literal["input", "output", "processes"], Any]:
            """
            Starts a multi-process pool to process the encoding with several independent processes
            via :meth:`SentenceTransformer.encode_multi_process <sentence_transformers.SentenceTransformer.encode_multi_process>`.

            This method is recommended if you want to encode on multiple GPUs or CPUs. It is advised
            to start only one process per GPU. This method works together with encode_multi_process
            and stop_multi_process_pool.

            Args:
                target_devices (List[str], optional): PyTorch target devices, e.g. ["cuda:0", "cuda:1", ...],
                    ["npu:0", "npu:1", ...], or ["cpu", "cpu", "cpu", "cpu"]. If target_devices is None and CUDA/NPU
                    is available, then all available CUDA/NPU devices will be used. If target_devices is None and
                    CUDA/NPU is not available, then 4 CPU devices will be used.

            Returns:
                Dict[str, Any]: A dictionary with the target processes, an input queue, and an output queue.
            """
            if target_devices is None:
                if torch.cuda.is_available():
                    target_devices = [f"cuda:{i}" for i in range(torch.cuda.device_count())]
                elif is_torch_npu_available():
                    target_devices = [f"npu:{i}" for i in range(torch.npu.device_count())]
                else:
                    logger.info("CUDA/NPU is not available. Starting 4 CPU workers")
                    target_devices = ["cpu"] * 4

            logger.info("Start multi-process pool on devices: {}".format(", ".join(map(str, target_devices))))

            self.to("cpu")
            self.share_memory()
            ctx = mp.get_context("spawn")
            input_queue = ctx.Queue()
            output_queue = ctx.Queue()
            processes = []

            for device_id in target_devices:
                p = ctx.Process(
                    target=SentenceTransformer._encode_multi_process_worker,
                    args=(device_id, self, input_queue, output_queue),
                    daemon=True,
                )
                p.start()
                processes.append(p)

            return {"input": input_queue, "output": output_queue, "processes": processes}

    Starts a multi-process pool to process the encoding with several independent processes via :meth:`SentenceTransformer.encode_multi_process <sentence_transformers.SentenceTransformer.encode_multi_process>`.

    This method is recommended if you want to encode on multiple GPUs or CPUs. It is advised to start only one process per GPU. This method works together with encode_multi_process and stop_multi_process_pool.

    ## Args

    `target_devices` :`List[str]`, optional
      PyTorch target devices, e.g. ["cuda:0", "cuda:1", …], ["npu:0", "npu:1", …], or ["cpu", "cpu", "cpu", "cpu"]. If target_devices is None and CUDA/NPU is available, then all available CUDA/NPU devices will be used. If target_devices is None and CUDA/NPU is not available, then 4 CPU devices will be used.

    ## Returns

    `Dict[str, Any]`
      A dictionary with the target processes, an input queue, and an output queue.
  `def tokenize(self, texts: list[str] | list[dict] | list[tuple[str, str]]) ‑> dict[str, torch.Tensor]`
    Expand source code

        def tokenize(self, texts: list[str] | list[dict] | list[tuple[str, str]]) -> dict[str, Tensor]:
            """
            Tokenizes the texts.

            Args:
                texts (Union[List[str], List[Dict], List[Tuple[str, str]]]): A list of texts to be tokenized.

            Returns:
                Dict[str, Tensor]: A dictionary of tensors with the tokenized texts. Common keys are "input_ids",
                    "attention_mask", and "token_type_ids".
            """
            return self._first_module().tokenize(texts)

    Tokenizes the texts.

    ## Args

    `texts` :`Union[List[str], List[Dict], List[Tuple[str, str]]]`
      A list of texts to be tokenized.

    ## Returns

    `Dict[str, Tensor]`
      A dictionary of tensors with the tokenized texts. Common keys are "input_ids", "attention_mask", and "token_type_ids".
  `def truncate_sentence_embeddings(self, truncate_dim: int | None) ‑> Iterator[None]`
    Expand source code

        @contextmanager
        def truncate_sentence_embeddings(self, truncate_dim: int | None) -> Iterator[None]:
            """
            In this context, :meth:`SentenceTransformer.encode <sentence_transformers.SentenceTransformer.encode>` outputs
            sentence embeddings truncated at dimension ``truncate_dim``.

            This may be useful when you are using the same model for different applications where different dimensions
            are needed.

            Args:
                truncate_dim (int, optional): The dimension to truncate sentence embeddings to. ``None`` does no truncation.

            Example:
                ::

                    from sentence_transformers import SentenceTransformer

                    model = SentenceTransformer("all-mpnet-base-v2")

                    with model.truncate_sentence_embeddings(truncate_dim=16):
                        embeddings_truncated = model.encode(["hello there", "hiya"])
                    assert embeddings_truncated.shape[-1] == 16
            """
            original_output_dim = self.truncate_dim
            try:
                self.truncate_dim = truncate_dim
                yield
            finally:
                self.truncate_dim = original_output_dim

    In this context, :meth:`SentenceTransformer.encode <sentence_transformers.SentenceTransformer.encode>` outputs sentence embeddings truncated at dimension `truncate_dim`.

    This may be useful when you are using the same model for different applications where different dimensions are needed.

    ## Args

    `truncate_dim` :`int`, optional
      The dimension to truncate sentence embeddings to. `None` does no truncation.

    ## Example

    ::

        from sentence_transformers import SentenceTransformer

        model = SentenceTransformer("all-mpnet-base-v2")

        with model.truncate_sentence_embeddings(truncate_dim=16):
            embeddings_truncated = model.encode(["hello there", "hiya"])
        assert embeddings_truncated.shape[-1] == 16

`class Tensor (...)`

  ### Ancestors

  - torch._C.TensorBase

  ### Subclasses

  - torch._subclasses.fake_tensor.FakeTensor
  - torch._subclasses.functional_tensor.FunctionalTensor
  - torch.masked.maskedtensor.core.MaskedTensor
  - torch.nn.parameter.Buffer
  - torch.nn.parameter.Parameter
  - torch.nn.parameter.UninitializedBuffer
  - torch.sparse.semi_structured.SparseSemiStructuredTensor
  - torch.testing._internal.logging_tensor.LoggingTensor

  ### Methods

  `def align_to(self, *names)`
    Expand source code

        def align_to(self, *names):
            r"""Permutes the dimensions of the :attr:`self` tensor to match the order
            specified in :attr:`names`, adding size-one dims for any new names.

            All of the dims of :attr:`self` must be named in order to use this method.
            The resulting tensor is a view on the original tensor.

            All dimension names of :attr:`self` must be present in :attr:`names`.
            :attr:`names` may contain additional names that are not in ``self.names``;
            the output tensor has a size-one dimension for each of those new names.

            :attr:`names` may contain up to one Ellipsis (``...``).
            The Ellipsis is expanded to be equal to all dimension names of :attr:`self`
            that are not mentioned in :attr:`names`, in the order that they appear
            in :attr:`self`.

            Python 2 does not support Ellipsis but one may use a string literal
            instead (``'...'``).

            Args:
                names (iterable of str): The desired dimension ordering of the
                    output tensor. May contain up to one Ellipsis that is expanded
                    to all unmentioned dim names of :attr:`self`.

            Examples::

                >>> tensor = torch.randn(2, 2, 2, 2, 2, 2)
                >>> named_tensor = tensor.refine_names('A', 'B', 'C', 'D', 'E', 'F')

                # Move the F and E dims to the front while keeping the rest in order
                >>> named_tensor.align_to('F', 'E', ...)

            .. warning::
                The named tensor API is experimental and subject to change.

            """
            if has_torch_function_unary(self):
                return handle_torch_function(Tensor.align_to, (self,), self, *names)
            ellipsis_idx = single_ellipsis_index(names, "align_to")
            if ellipsis_idx is None:
                return super().align_to(names)
            return super().align_to(
                [name for name in names if not is_ellipsis(name)], ellipsis_idx
            )

    Permutes the dimensions of the :attr:`self` tensor to match the order specified in :attr:`names`, adding size-one dims for any new names.

    All of the dims of :attr:`self` must be named in order to use this method. The resulting tensor is a view on the original tensor.

    All dimension names of :attr:`self` must be present in :attr:`names`. :attr:`names` may contain additional names that are not in `self.names`; the output tensor has a size-one dimension for each of those new names.

    :attr:`names` may contain up to one Ellipsis (`…`). The Ellipsis is expanded to be equal to all dimension names of :attr:`self` that are not mentioned in :attr:`names`, in the order that they appear in :attr:`self`.

    Python 2 does not support Ellipsis but one may use a string literal instead (`'...'`).

    ## Args

    `names` :`iterable` of `str`
      The desired dimension ordering of the output tensor. May contain up to one Ellipsis that is expanded to all unmentioned dim names of :attr:`self`.

    Examples::

        >>> tensor = torch.randn(2, 2, 2, 2, 2, 2)
        >>> named_tensor = tensor.refine_names('A', 'B', 'C', 'D', 'E', 'F')

        # Move the F and E dims to the front while keeping the rest in order
        >>> named_tensor.align_to('F', 'E', ...)

    Warning

    The named tensor API is experimental and subject to change.

  `def backward(self, gradient=None, retain_graph=None, create_graph=False, inputs=None)`
    Expand source code

        def backward(
            self, gradient=None, retain_graph=None, create_graph=False, inputs=None
        ):
            r"""Computes the gradient of current tensor wrt graph leaves.

            The graph is differentiated using the chain rule. If the tensor is
            non-scalar (i.e. its data has more than one element) and requires
            gradient, the function additionally requires specifying a ``gradient``.
            It should be a tensor of matching type and shape, that represents
            the gradient of the differentiated function w.r.t. ``self``.

            This function accumulates gradients in the leaves - you might need to zero
            ``.grad`` attributes or set them to ``None`` before calling it.
            See :ref:`Default gradient layouts<default-grad-layouts>`
            for details on the memory layout of accumulated gradients.

            .. note::

                If you run any forward ops, create ``gradient``, and/or call ``backward``
                in a user-specified CUDA stream context, see
                :ref:`Stream semantics of backward passes<bwd-cuda-stream-semantics>`.

            .. note::

                When ``inputs`` are provided and a given input is not a leaf,
                the current implementation will call its grad_fn (though it is not strictly needed to get this gradients).
                It is an implementation detail on which the user should not rely.
                See https://github.com/pytorch/pytorch/pull/60521#issuecomment-867061780 for more details.

            Args:
                gradient (Tensor, optional): The gradient of the function
                    being differentiated w.r.t. ``self``.
                    This argument can be omitted if ``self`` is a scalar.
                retain_graph (bool, optional): If ``False``, the graph used to compute
                    the grads will be freed. Note that in nearly all cases setting
                    this option to True is not needed and often can be worked around
                    in a much more efficient way. Defaults to the value of
                    ``create_graph``.
                create_graph (bool, optional): If ``True``, graph of the derivative will
                    be constructed, allowing to compute higher order derivative
                    products. Defaults to ``False``.
                inputs (sequence of Tensor, optional): Inputs w.r.t. which the gradient will be
                    accumulated into ``.grad``. All other tensors will be ignored. If not
                    provided, the gradient is accumulated into all the leaf Tensors that were
                    used to compute the :attr:`tensors`.
            """
            if has_torch_function_unary(self):
                return handle_torch_function(
                    Tensor.backward,
                    (self,),
                    self,
                    gradient=gradient,
                    retain_graph=retain_graph,
                    create_graph=create_graph,
                    inputs=inputs,
                )
            torch.autograd.backward(
                self, gradient, retain_graph, create_graph, inputs=inputs
            )

    Computes the gradient of current tensor wrt graph leaves.

    The graph is differentiated using the chain rule. If the tensor is non-scalar (i.e. its data has more than one element) and requires gradient, the function additionally requires specifying a `gradient`. It should be a tensor of matching type and shape, that represents the gradient of the differentiated function w.r.t. `self`.

    This function accumulates gradients in the leaves - you might need to zero `.grad` attributes or set them to `None` before calling it. See :ref:`Default gradient layouts<default-grad-layouts>` for details on the memory layout of accumulated gradients.

    Note

    If you run any forward ops, create `gradient`, and/or call `backward` in a user-specified CUDA stream context, see :ref:`Stream semantics of backward passes<bwd-cuda-stream-semantics>`.

    Note

    When `inputs` are provided and a given input is not a leaf, the current implementation will call its grad_fn (though it is not strictly needed to get this gradients). It is an implementation detail on which the user should not rely. See https://github.com/pytorch/pytorch/pull/60521#issuecomment-867061780 for more details.

    ## Args

    `gradient` :`Tensor`, optional
      The gradient of the function being differentiated w.r.t. `self`. This argument can be omitted if `self` is a scalar.
    `retain_graph` :`bool`, optional
      If `False`, the graph used to compute the grads will be freed. Note that in nearly all cases setting this option to True is not needed and often can be worked around in a much more efficient way. Defaults to the value of `create_graph`.
    `create_graph` :`bool`, optional
      If `True`, graph of the derivative will be constructed, allowing to compute higher order derivative products. Defaults to `False`.
    `inputs` :`sequence` of `Tensor`, optional
      Inputs w.r.t. which the gradient will be accumulated into `.grad`. All other tensors will be ignored. If not provided, the gradient is accumulated into all the leaf Tensors that were used to compute the :attr:`tensors`.
  `def detach(...)`

    Returns a new Tensor, detached from the current graph.

    The result will never require gradient.

    This method also affects forward mode AD gradients and the result will never have forward mode AD gradients.

    Note

    Returned Tensor shares the same storage with the original one. In-place modifications on either of them will be seen, and may trigger errors in correctness checks.

  `def detach_(...)`

    Detaches the Tensor from the graph that created it, making it a leaf. Views cannot be detached in-place.

    This method also affects forward mode AD gradients and the result will never have forward mode AD gradients.

  `def dim_order(self)`
    Expand source code

        def dim_order(self):
            """

            dim_order() -> tuple

            Returns a tuple of int describing the dim order or physical layout of :attr:`self`.

            Args:
                None

            Dim order represents how dimensions are laid out in memory,
            starting from the outermost to the innermost dimension.

            Example::
                >>> torch.empty((2, 3, 5, 7)).dim_order()
                (0, 1, 2, 3)
                >>> torch.empty((2, 3, 5, 7), memory_format=torch.channels_last).dim_order()
                (0, 2, 3, 1)

            .. warning::
                The dim_order tensor API is experimental and subject to change.

            """
            if has_torch_function_unary(self):
                return handle_torch_function(Tensor.dim_order, (self,), self)

            import torch._prims_common as utils

            return tuple(utils.compute_elementwise_output_logical_to_physical_perm(self))

    dim_order() -> tuple

    Returns a tuple of int describing the dim order or physical layout of :attr:`self`.

    ## Args

    None Dim order represents how dimensions are laid out in memory, starting from the outermost to the innermost dimension.

    Example:: >>> torch.empty((2, 3, 5, 7)).dim_order() (0, 1, 2, 3) >>> torch.empty((2, 3, 5, 7), memory_format=torch.channels_last).dim_order() (0, 2, 3, 1)

    Warning

    The dim_order tensor API is experimental and subject to change.

  `def eig(self, eigenvectors=False)`
    Expand source code

        def eig(self, eigenvectors=False):
            from torch._linalg_utils import eig

            return eig(self, eigenvectors=eigenvectors)

  `def is_shared(self)`
    Expand source code

        def is_shared(self):
            r"""Checks if tensor is in shared memory.

            This is always ``True`` for CUDA tensors.
            """
            if has_torch_function_unary(self):
                return handle_torch_function(Tensor.is_shared, (self,), self)
            return self._typed_storage()._is_shared()

    Checks if tensor is in shared memory.

    This is always `True` for CUDA tensors.

  `def istft(self,
  n_fft: int,
  hop_length: int | None = None,
  win_length: int | None = None,
  window: Optional[Tensor] = None,
  center: bool = True,
  normalized: bool = False,
  onesided: bool | None = None,
  length: int | None = None,
  return_complex: bool = False)`
    Expand source code

        def istft(
            self,
            n_fft: int,
            hop_length: Optional[int] = None,
            win_length: Optional[int] = None,
            window: "Optional[Tensor]" = None,
            center: bool = True,
            normalized: bool = False,
            onesided: Optional[bool] = None,
            length: Optional[int] = None,
            return_complex: bool = False,
        ):
            r"""See :func:`torch.istft`"""
            if has_torch_function_unary(self):
                return handle_torch_function(
                    Tensor.istft,
                    (self,),
                    self,
                    n_fft,
                    hop_length=hop_length,
                    win_length=win_length,
                    window=window,
                    center=center,
                    normalized=normalized,
                    onesided=onesided,
                    length=length,
                    return_complex=return_complex,
                )
            return torch.istft(
                self,
                n_fft,
                hop_length,
                win_length,
                window,
                center,
                normalized,
                onesided,
                length,
                return_complex=return_complex,
            )

    See :func:`torch.istft`

  `def lstsq(self, other)`
    Expand source code

        def lstsq(self, other):
            from torch._linalg_utils import lstsq

            return lstsq(self, other)

  `def lu(self, pivot=True, get_infos=False)`
    Expand source code

        def lu(self, pivot=True, get_infos=False):
            r"""See :func:`torch.lu`"""
            # If get_infos is True, then we don't need to check for errors and vice versa
            if has_torch_function_unary(self):
                return handle_torch_function(
                    Tensor.lu, (self,), self, pivot=pivot, get_infos=get_infos
                )

            LU, pivots, infos = torch._lu_with_info(
                self, pivot=pivot, check_errors=(not get_infos)
            )
            if get_infos:
                return LU, pivots, infos
            else:
                return LU, pivots

    See :func:`torch.lu`

  `def module_load(self, other, assign=False)`
    Expand source code

        def module_load(self, other, assign=False):
            r"""Defines how to transform ``other`` when loading it into ``self`` in :meth:`~nn.Module.load_state_dict`.

            Used when :func:`~torch.__future__.get_swap_module_params_on_conversion` is ``True``.

            It is expected that ``self`` is a parameter or buffer in an ``nn.Module`` and ``other`` is the
            value in the state dictionary with the corresponding key, this method defines
            how ``other`` is remapped before being swapped with ``self`` via
            :func:`~torch.utils.swap_tensors` in :meth:`~nn.Module.load_state_dict`.

            .. note::
                This method should always return a new object that is not ``self`` or ``other``.
                For example, the default implementation returns ``self.copy_(other).detach()``
                if ``assign`` is ``False`` or ``other.detach()`` if ``assign`` is ``True``.

            Args:
                other (Tensor): value in state dict with key corresponding to ``self``
                assign (bool): the assign argument passed to :meth:`nn.Module.load_state_dict`

            """
            if has_torch_function_variadic(self, other):
                return handle_torch_function(
                    Tensor.module_load, (self, other), self, other, assign=assign
                )

            if assign:
                return other.detach()
            else:
                return self.copy_(other).detach()

    Defines how to transform `other` when loading it into `self` in :meth:`~nn.Module.load_state_dict`.

    Used when :func:`~torch.__future__.get_swap_module_params_on_conversion` is `True`.

    It is expected that `self` is a parameter or buffer in an `nn.Module` and `other` is the value in the state dictionary with the corresponding key, this method defines how `other` is remapped before being swapped with `self` via :func:`~torch.utils.swap_tensors` in :meth:`~nn.Module.load_state_dict`.

    Note

    This method should always return a new object that is not `self` or `other`. For example, the default implementation returns `self.copy_(other).detach()` if `assign` is `False` or `other.detach()` if `assign` is `True`.

    ## Args

    `other` :`Tensor`
      value in state dict with key corresponding to `self`
    `assign` :`bool`
      the assign argument passed to :meth:`nn.Module.load_state_dict`
  `def norm(self, p: float | str | None = 'fro', dim=None, keepdim=False, dtype=None)`
    Expand source code

        def norm(
            self,
            p: Optional[Union[float, str]] = "fro",
            dim=None,
            keepdim=False,
            dtype=None,
        ):
            r"""See :func:`torch.norm`"""
            if has_torch_function_unary(self):
                return handle_torch_function(
                    Tensor.norm, (self,), self, p=p, dim=dim, keepdim=keepdim, dtype=dtype
                )
            return torch.norm(self, p, dim, keepdim, dtype=dtype)

    See :func:`torch.norm`

  `def refine_names(self, *names)`
    Expand source code

        def refine_names(self, *names):
            r"""Refines the dimension names of :attr:`self` according to :attr:`names`.

            Refining is a special case of renaming that "lifts" unnamed dimensions.
            A ``None`` dim can be refined to have any name; a named dim can only be
            refined to have the same name.

            Because named tensors can coexist with unnamed tensors, refining names
            gives a nice way to write named-tensor-aware code that works with both
            named and unnamed tensors.

            :attr:`names` may contain up to one Ellipsis (``...``).
            The Ellipsis is expanded greedily; it is expanded in-place to fill
            :attr:`names` to the same length as ``self.dim()`` using names from the
            corresponding indices of ``self.names``.

            Python 2 does not support Ellipsis but one may use a string literal
            instead (``'...'``).

            Args:
                names (iterable of str): The desired names of the output tensor. May
                    contain up to one Ellipsis.

            Examples::

                >>> imgs = torch.randn(32, 3, 128, 128)
                >>> named_imgs = imgs.refine_names('N', 'C', 'H', 'W')
                >>> named_imgs.names
                ('N', 'C', 'H', 'W')

                >>> tensor = torch.randn(2, 3, 5, 7, 11)
                >>> tensor = tensor.refine_names('A', ..., 'B', 'C')
                >>> tensor.names
                ('A', None, None, 'B', 'C')

            .. warning::
                The named tensor API is experimental and subject to change.

            """
            if has_torch_function_unary(self):
                return handle_torch_function(Tensor.refine_names, (self,), self, *names)
            names = resolve_ellipsis(names, self.names, "refine_names")
            return super().refine_names(names)

    Refines the dimension names of :attr:`self` according to :attr:`names`.

    Refining is a special case of renaming that "lifts" unnamed dimensions. A `None` dim can be refined to have any name; a named dim can only be refined to have the same name.

    Because named tensors can coexist with unnamed tensors, refining names gives a nice way to write named-tensor-aware code that works with both named and unnamed tensors.

    :attr:`names` may contain up to one Ellipsis (`…`). The Ellipsis is expanded greedily; it is expanded in-place to fill :attr:`names` to the same length as `self.dim()` using names from the corresponding indices of `self.names`.

    Python 2 does not support Ellipsis but one may use a string literal instead (`'...'`).

    ## Args

    `names` :`iterable` of `str`
      The desired names of the output tensor. May contain up to one Ellipsis.

    Examples::

        >>> imgs = torch.randn(32, 3, 128, 128)
        >>> named_imgs = imgs.refine_names('N', 'C', 'H', 'W')
        >>> named_imgs.names
        ('N', 'C', 'H', 'W')

        >>> tensor = torch.randn(2, 3, 5, 7, 11)
        >>> tensor = tensor.refine_names('A', ..., 'B', 'C')
        >>> tensor.names
        ('A', None, None, 'B', 'C')

    Warning

    The named tensor API is experimental and subject to change.

  `def register_hook(self, hook)`
    Expand source code

        def register_hook(self, hook):
            r"""Registers a backward hook.

            The hook will be called every time a gradient with respect to the
            Tensor is computed. The hook should have the following signature::

                hook(grad) -> Tensor or None

            The hook should not modify its argument, but it can optionally return
            a new gradient which will be used in place of :attr:`grad`.

            This function returns a handle with a method ``handle.remove()``
            that removes the hook from the module.

            .. note::
                See :ref:`backward-hooks-execution` for more information on how when this hook
                is executed, and how its execution is ordered relative to other hooks.

            Example::

                >>> v = torch.tensor([0., 0., 0.], requires_grad=True)
                >>> h = v.register_hook(lambda grad: grad * 2)  # double the gradient
                >>> v.backward(torch.tensor([1., 2., 3.]))
                >>> v.grad

                 2
                 4
                 6
                [torch.FloatTensor of size (3,)]

                >>> h.remove()  # removes the hook
            """
            if has_torch_function_unary(self):
                return handle_torch_function(Tensor.register_hook, (self,), self, hook)
            if not self.requires_grad:
                raise RuntimeError(
                    "cannot register a hook on a tensor that doesn't require gradient"
                )
            if self._backward_hooks is None:
                self._backward_hooks = OrderedDict()
                if self.grad_fn is not None:
                    self.grad_fn._register_hook_dict(self)

            from torch.utils.hooks import RemovableHandle

            handle = RemovableHandle(self._backward_hooks)
            self._backward_hooks[handle.id] = hook
            return handle

    Registers a backward hook.

    The hook will be called every time a gradient with respect to the Tensor is computed. The hook should have the following signature::

        hook(grad) -> Tensor or None

    The hook should not modify its argument, but it can optionally return a new gradient which will be used in place of :attr:`grad`.

    This function returns a handle with a method `handle.remove()` that removes the hook from the module.

    Note

    See :ref:`backward-hooks-execution` for more information on how when this hook is executed, and how its execution is ordered relative to other hooks.

    Example::

        >>> v = torch.tensor([0., 0., 0.], requires_grad=True)
        >>> h = v.register_hook(lambda grad: grad * 2)  # double the gradient
        >>> v.backward(torch.tensor([1., 2., 3.]))
        >>> v.grad

         2
         4
         6
        [torch.FloatTensor of size (3,)]

        >>> h.remove()  # removes the hook

  `def register_post_accumulate_grad_hook(self, hook)`
    Expand source code

        def register_post_accumulate_grad_hook(self, hook):
            r"""Registers a backward hook that runs after grad accumulation.

            The hook will be called after all gradients for a tensor have been accumulated,
            meaning that the .grad field has been updated on that tensor. The post
            accumulate grad hook is ONLY applicable for leaf tensors (tensors without a
            .grad_fn field). Registering this hook on a non-leaf tensor will error!

            The hook should have the following signature::

                hook(param: Tensor) -> None

            Note that, unlike other autograd hooks, this hook operates on the tensor
            that requires grad and not the grad itself. The hook can in-place modify
            and access its Tensor argument, including its .grad field.

            This function returns a handle with a method ``handle.remove()``
            that removes the hook from the module.

            .. note::
                See :ref:`backward-hooks-execution` for more information on how when this hook
                is executed, and how its execution is ordered relative to other hooks. Since
                this hook runs during the backward pass, it will run in no_grad mode (unless
                create_graph is True). You can use torch.enable_grad() to re-enable autograd
                within the hook if you need it.

            Example::

                >>> v = torch.tensor([0., 0., 0.], requires_grad=True)
                >>> lr = 0.01
                >>> # simulate a simple SGD update
                >>> h = v.register_post_accumulate_grad_hook(lambda p: p.add_(p.grad, alpha=-lr))
                >>> v.backward(torch.tensor([1., 2., 3.]))
                >>> v
                tensor([-0.0100, -0.0200, -0.0300], requires_grad=True)

                >>> h.remove()  # removes the hook
            """
            if has_torch_function_unary(self):
                return handle_torch_function(
                    Tensor.register_post_accumulate_grad_hook, (self,), self, hook
                )
            if not self.requires_grad:
                raise RuntimeError(
                    "cannot register a hook on a tensor that doesn't require gradient"
                )
            if self.grad_fn is not None:
                raise RuntimeError(
                    "post accumulate grad hooks cannot be registered on non-leaf tensors"
                )
            if self._post_accumulate_grad_hooks is None:
                self._post_accumulate_grad_hooks: Dict[Any, Any] = OrderedDict()

            from torch.utils.hooks import RemovableHandle

            handle = RemovableHandle(self._post_accumulate_grad_hooks)
            self._post_accumulate_grad_hooks[handle.id] = hook
            return handle

    Registers a backward hook that runs after grad accumulation.

    The hook will be called after all gradients for a tensor have been accumulated, meaning that the .grad field has been updated on that tensor. The post accumulate grad hook is ONLY applicable for leaf tensors (tensors without a .grad_fn field). Registering this hook on a non-leaf tensor will error!

    The hook should have the following signature::

        hook(param: Tensor) -> None

    Note that, unlike other autograd hooks, this hook operates on the tensor that requires grad and not the grad itself. The hook can in-place modify and access its Tensor argument, including its .grad field.

    This function returns a handle with a method `handle.remove()` that removes the hook from the module.

    Note

    See :ref:`backward-hooks-execution` for more information on how when this hook is executed, and how its execution is ordered relative to other hooks. Since this hook runs during the backward pass, it will run in no_grad mode (unless create_graph is True). You can use torch.enable_grad() to re-enable autograd within the hook if you need it.

    Example::

        >>> v = torch.tensor([0., 0., 0.], requires_grad=True)
        >>> lr = 0.01
        >>> # simulate a simple SGD update
        >>> h = v.register_post_accumulate_grad_hook(lambda p: p.add_(p.grad, alpha=-lr))
        >>> v.backward(torch.tensor([1., 2., 3.]))
        >>> v
        tensor([-0.0100, -0.0200, -0.0300], requires_grad=True)

        >>> h.remove()  # removes the hook

  `def reinforce(self, reward)`
    Expand source code

        def reinforce(self, reward):
            def trim(str):
                return "\n".join([line.strip() for line in str.split("\n")])

            raise RuntimeError(
                trim(
                    r"""reinforce() was removed.
                Use torch.distributions instead.
                See https://pytorch.org/docs/main/distributions.html

                Instead of:

                probs = policy_network(state)
                action = probs.multinomial()
                next_state, reward = env.step(action)
                action.reinforce(reward)
                action.backward()

                Use:

                probs = policy_network(state)
                # NOTE: categorical is equivalent to what used to be called multinomial
                m = torch.distributions.Categorical(probs)
                action = m.sample()
                next_state, reward = env.step(action)
                loss = -m.log_prob(action) * reward
                loss.backward()
            """
                )
            )

  `def rename(self, *names, **rename_map)`
    Expand source code

        def rename(self, *names, **rename_map):
            """Renames dimension names of :attr:`self`.

            There are two main usages:

            ``self.rename(**rename_map)`` returns a view on tensor that has dims
            renamed as specified in the mapping :attr:`rename_map`.

            ``self.rename(*names)`` returns a view on tensor, renaming all
            dimensions positionally using :attr:`names`.
            Use ``self.rename(None)`` to drop names on a tensor.

            One cannot specify both positional args :attr:`names` and keyword args
            :attr:`rename_map`.

            Examples::

                >>> imgs = torch.rand(2, 3, 5, 7, names=('N', 'C', 'H', 'W'))
                >>> renamed_imgs = imgs.rename(N='batch', C='channels')
                >>> renamed_imgs.names
                ('batch', 'channels', 'H', 'W')

                >>> renamed_imgs = imgs.rename(None)
                >>> renamed_imgs.names
                (None, None, None, None)

                >>> renamed_imgs = imgs.rename('batch', 'channel', 'height', 'width')
                >>> renamed_imgs.names
                ('batch', 'channel', 'height', 'width')

            .. warning::
                The named tensor API is experimental and subject to change.

            """
            if has_torch_function_unary(self):
                return handle_torch_function(
                    Tensor.rename, (self,), self, *names, **rename_map
                )

            # See Note [rename_ / rename API]
            return update_names(self, names, rename_map, inplace=False)

    Renames dimension names of :attr:`self`.

    There are two main usages:

    `self.rename(**rename_map)` returns a view on tensor that has dims renamed as specified in the mapping :attr:`rename_map`.

    `self.rename(*names)` returns a view on tensor, renaming all dimensions positionally using :attr:`names`. Use `self.rename(None)` to drop names on a tensor.

    One cannot specify both positional args :attr:`names` and keyword args :attr:`rename_map`.

    Examples::

        >>> imgs = torch.rand(2, 3, 5, 7, names=('N', 'C', 'H', 'W'))
        >>> renamed_imgs = imgs.rename(N='batch', C='channels')
        >>> renamed_imgs.names
        ('batch', 'channels', 'H', 'W')

        >>> renamed_imgs = imgs.rename(None)
        >>> renamed_imgs.names
        (None, None, None, None)

        >>> renamed_imgs = imgs.rename('batch', 'channel', 'height', 'width')
        >>> renamed_imgs.names
        ('batch', 'channel', 'height', 'width')

    Warning

    The named tensor API is experimental and subject to change.

  `def rename_(self, *names, **rename_map)`
    Expand source code

        def rename_(self, *names, **rename_map):
            """In-place version of :meth:`~Tensor.rename`."""

            if has_torch_function_unary(self):
                return handle_torch_function(
                    Tensor.rename_, (self,), self, *names, **rename_map
                )

            # Note [rename_ / rename API]
            # The Python API for these is different from the C++ API. In Python:
            # 1) tensor.rename(*names) takes a vararglist of names
            # 2) tensor.rename(**rename_map) takes a map of names to rename.
            # C++ is static, making it difficult to implement similar behavior.
            return update_names(self, names, rename_map, inplace=True)

    In-place version of :meth:`~Tensor.rename`.

  `def resize(self, *sizes)`
    Expand source code

        def resize(self, *sizes):
            if has_torch_function_unary(self):
                return handle_torch_function(Tensor.resize, (self,), self, *sizes)
            warnings.warn("non-inplace resize is deprecated")
            from torch.autograd._functions import Resize

            return Resize.apply(self, sizes)

  `def resize_as(self, tensor)`
    Expand source code

        def resize_as(self, tensor):
            if has_torch_function_variadic(self, tensor):
                return handle_torch_function(Tensor.resize_as, (self, tensor), self, tensor)
            warnings.warn("non-inplace resize_as is deprecated")
            from torch.autograd._functions import Resize

            return Resize.apply(self, tensor.size())

  `def share_memory_(self)`
    Expand source code

        def share_memory_(self):
            r"""Moves the underlying storage to shared memory.

            This is a no-op if the underlying storage is already in shared memory
            and for CUDA tensors. Tensors in shared memory cannot be resized.

            See :meth:`torch.UntypedStorage.share_memory_` for more details.
            """
            if has_torch_function_unary(self):
                return handle_torch_function(Tensor.share_memory_, (self,), self)
            self._typed_storage()._share_memory_()
            return self

    Moves the underlying storage to shared memory.

    This is a no-op if the underlying storage is already in shared memory and for CUDA tensors. Tensors in shared memory cannot be resized.

    See :meth:`torch.UntypedStorage.share_memory_` for more details.

  `def solve(self, other)`
    Expand source code

        def solve(self, other):
            from torch._linalg_utils import solve

            return solve(self, other)

  `def split(self, split_size, dim=0)`
    Expand source code

        def split(self, split_size, dim=0):
            r"""See :func:`torch.split`"""
            if has_torch_function_unary(self):
                return handle_torch_function(
                    Tensor.split, (self,), self, split_size, dim=dim
                )
            if isinstance(split_size, Tensor):
                try:
                    split_size = int(split_size)
                except ValueError:
                    pass

            if isinstance(split_size, (int, torch.SymInt)):
                return torch._VF.split(self, split_size, dim)  # type: ignore[attr-defined]
            else:
                return torch._VF.split_with_sizes(self, split_size, dim)

    See :func:`torch.split`

  `def stft(self,
  n_fft: int,
  hop_length: int | None = None,
  win_length: int | None = None,
  window: Optional[Tensor] = None,
  center: bool = True,
  pad_mode: str = 'reflect',
  normalized: bool = False,
  onesided: bool | None = None,
  return_complex: bool | None = None)`
    Expand source code

        def stft(
            self,
            n_fft: int,
            hop_length: Optional[int] = None,
            win_length: Optional[int] = None,
            window: "Optional[Tensor]" = None,
            center: bool = True,
            pad_mode: str = "reflect",
            normalized: bool = False,
            onesided: Optional[bool] = None,
            return_complex: Optional[bool] = None,
        ):
            r"""See :func:`torch.stft`

            .. warning::
              This function changed signature at version 0.4.1. Calling with
              the previous signature may cause error or return incorrect result.
            """
            if has_torch_function_unary(self):
                return handle_torch_function(
                    Tensor.stft,
                    (self,),
                    self,
                    n_fft,
                    hop_length=hop_length,
                    win_length=win_length,
                    window=window,
                    center=center,
                    pad_mode=pad_mode,
                    normalized=normalized,
                    onesided=onesided,
                    return_complex=return_complex,
                )
            return torch.stft(
                self,
                n_fft,
                hop_length,
                win_length,
                window,
                center,
                pad_mode,
                normalized,
                onesided,
                return_complex=return_complex,
            )

    See :func:`torch.stft`

    Warning

    This function changed signature at version 0.4.1. Calling with the previous signature may cause error or return incorrect result.

  `def storage(self)`
    Expand source code

        def storage(self):
            r"""
            storage() -> torch.TypedStorage

            Returns the underlying :class:`TypedStorage`.

            .. warning::

                :class:`TypedStorage` is deprecated. It will be removed in the future, and
                :class:`UntypedStorage` will be the only storage class. To access the
                :class:`UntypedStorage` directly, use :attr:`Tensor.untyped_storage()`.
            """
            if has_torch_function_unary(self):
                return handle_torch_function(Tensor.storage, (self,), self)

            torch.storage._warn_typed_storage_removal(stacklevel=2)
            return self._typed_storage()

    storage() -> torch.TypedStorage

    Returns the underlying :class:`TypedStorage`.

    Warning

    :class:`TypedStorage` is deprecated. It will be removed in the future, and :class:`UntypedStorage` will be the only storage class. To access the :class:`UntypedStorage` directly, use :attr:`Tensor.untyped_storage()`.

  `def storage_type(self)`
    Expand source code

        def storage_type(self):
            r"""storage_type() -> type

            Returns the type of the underlying storage.

            """
            if has_torch_function_unary(self):
                return handle_torch_function(Tensor.storage_type, (self,), self)

            torch.storage._warn_typed_storage_removal()

            return self._typed_storage()._get_legacy_storage_class()

    storage_type() -> type

    Returns the type of the underlying storage.

  `def symeig(self, eigenvectors=False)`
    Expand source code

        def symeig(self, eigenvectors=False):
            from torch._linalg_utils import _symeig

            return _symeig(self, eigenvectors=eigenvectors)

  `def to_sparse_coo(self)`
    Expand source code

        def to_sparse_coo(self):
            """Convert a tensor to :ref:`coordinate format <sparse-coo-docs>`.

            Examples::

                 >>> dense = torch.randn(5, 5)
                 >>> sparse = dense.to_sparse_coo()
                 >>> sparse._nnz()
                 25

            """
            return self.to_sparse()

    Convert a tensor to :ref:`coordinate format <sparse-coo-docs>`.

    Examples::

         >>> dense = torch.randn(5, 5)
         >>> sparse = dense.to_sparse_coo()
         >>> sparse._nnz()
         25

  `def unflatten(self, dim, sizes)`
    Expand source code

        def unflatten(self, dim, sizes):
            r"""
            unflatten(dim, sizes) -> Tensor

            See :func:`torch.unflatten`.

            """
            if has_torch_function_unary(self):
                return handle_torch_function(Tensor.unflatten, (self,), self, dim, sizes)

            if not sizes:
                raise RuntimeError("unflatten: sizes must be non-empty")

            names = None
            if isinstance(sizes, OrderedDict) or (
                isinstance(sizes, (tuple, list)) and isinstance(sizes[0], (tuple, list))
            ):
                names, sizes = unzip_namedshape(sizes)
                return super().unflatten(dim, sizes, names)
            else:
                return super().unflatten(dim, sizes)

    unflatten(dim, sizes) -> Tensor

    See :func:`torch.unflatten`.

  `def unique(self, sorted=True, return_inverse=False, return_counts=False, dim=None)`
    Expand source code

        def unique(self, sorted=True, return_inverse=False, return_counts=False, dim=None):
            r"""Returns the unique elements of the input tensor.

            See :func:`torch.unique`
            """
            if has_torch_function_unary(self):
                return handle_torch_function(
                    Tensor.unique,
                    (self,),
                    self,
                    sorted=sorted,
                    return_inverse=return_inverse,
                    return_counts=return_counts,
                    dim=dim,
                )
            return torch.unique(
                self,
                sorted=sorted,
                return_inverse=return_inverse,
                return_counts=return_counts,
                dim=dim,
            )

    Returns the unique elements of the input tensor.

    See :func:`torch.unique`

  `def unique_consecutive(self, return_inverse=False, return_counts=False, dim=None)`
    Expand source code

        def unique_consecutive(self, return_inverse=False, return_counts=False, dim=None):
            r"""Eliminates all but the first element from every consecutive group of equivalent elements.

            See :func:`torch.unique_consecutive`
            """
            if has_torch_function_unary(self):
                return handle_torch_function(
                    Tensor.unique_consecutive,
                    (self,),
                    self,
                    return_inverse=return_inverse,
                    return_counts=return_counts,
                    dim=dim,
                )
            return torch.unique_consecutive(
                self, return_inverse=return_inverse, return_counts=return_counts, dim=dim
            )

    Eliminates all but the first element from every consecutive group of equivalent elements.

    See :func:`torch.unique_consecutive`

`class SpacyToken (...)`

  An individual token – i.e. a word, punctuation symbol, whitespace, etc.

  DOCS: https://spacy.io/api/token

  ### Instance variables

  `var ancestors`

    A sequence of this token's syntactic ancestors.

    YIELDS (Token): A sequence of ancestor tokens such that `ancestor.is_ancestor(self)`.

    DOCS: https://spacy.io/api/token#ancestors

  `var children`

    A sequence of the token's immediate syntactic children.

    YIELDS (Token): A child token such that `child.head==self`.

    DOCS: https://spacy.io/api/token#children

  `var cluster`

    RETURNS (int): Brown cluster ID.

  `var conjuncts`

    A sequence of coordinated tokens, including the token itself.

    RETURNS (tuple): The coordinated tokens.

    DOCS: https://spacy.io/api/token#conjuncts

  `var dep`

    RETURNS (uint64): ID of syntactic dependency label.

  `var dep_`

    RETURNS (str): The syntactic dependency label.

  `var doc`
  `var ent_id`

    RETURNS (uint64): ID of the entity the token is an instance of, if any.

  `var ent_id_`

    RETURNS (str): ID of the entity the token is an instance of, if any.

  `var ent_iob`

    IOB code of named entity tag. `1="I", 2="O", 3="B"`. 0 means no tag is assigned.

    RETURNS (uint64): IOB code of named entity tag.

  `var ent_iob_`

    IOB code of named entity tag. "B" means the token begins an entity, "I" means it is inside an entity, "O" means it is outside an entity, and "" means no entity tag is set. "B" with an empty ent_type means that the token is blocked from further processing by NER.

    RETURNS (str): IOB code of named entity tag.

  `var ent_kb_id`

    RETURNS (uint64): Named entity KB ID.

  `var ent_kb_id_`

    RETURNS (str): Named entity KB ID.

  `var ent_type`

    RETURNS (uint64): Named entity type.

  `var ent_type_`

    RETURNS (str): Named entity type.

  `var has_vector`

    A boolean value indicating whether a word vector is associated with the object.

    RETURNS (bool): Whether a word vector is associated with the object.

    DOCS: https://spacy.io/api/token#has_vector

  `var head`

    The syntactic parent, or "governor", of this token. If token.has_head() is `False`, this method will return itself.

    RETURNS (Token): The token predicted by the parser to be the head of the current token.

  `var i`
  `var idx`

    RETURNS (int): The character offset of the token within the parent document.

  `var is_alpha`

    RETURNS (bool): Whether the token consists of alpha characters. Equivalent to `token.text.isalpha()`.

  `var is_ascii`

    RETURNS (bool): Whether the token consists of ASCII characters. Equivalent to `[any(ord(c) >= 128 for c in token.text)]`.

  `var is_bracket`

    RETURNS (bool): Whether the token is a bracket.

  `var is_currency`

    RETURNS (bool): Whether the token is a currency symbol.

  `var is_digit`

    RETURNS (bool): Whether the token consists of digits. Equivalent to `token.text.isdigit()`.

  `var is_left_punct`

    RETURNS (bool): Whether the token is a left punctuation mark.

  `var is_lower`

    RETURNS (bool): Whether the token is in lowercase. Equivalent to `token.text.islower()`.

  `var is_oov`

    RETURNS (bool): Whether the token is out-of-vocabulary.

  `var is_punct`

    RETURNS (bool): Whether the token is punctuation.

  `var is_quote`

    RETURNS (bool): Whether the token is a quotation mark.

  `var is_right_punct`

    RETURNS (bool): Whether the token is a right punctuation mark.

  `var is_sent_end`

    A boolean value indicating whether the token ends a sentence. `None` if unknown. Defaults to `True` for the last token in the `Doc`.

    RETURNS (bool / None): Whether the token ends a sentence. None if unknown.

    DOCS: https://spacy.io/api/token#is_sent_end

  `var is_sent_start`

    A boolean value indicating whether the token starts a sentence. `None` if unknown. Defaults to `True` for the first token in the `Doc`.

    RETURNS (bool / None): Whether the token starts a sentence. None if unknown.

  `var is_space`

    RETURNS (bool): Whether the token consists of whitespace characters. Equivalent to `token.text.isspace()`.

  `var is_stop`

    RETURNS (bool): Whether the token is a stop word, i.e. part of a "stop list" defined by the language data.

  `var is_title`

    RETURNS (bool): Whether the token is in titlecase. Equivalent to `token.text.istitle()`.

  `var is_upper`

    RETURNS (bool): Whether the token is in uppercase. Equivalent to `token.text.isupper()`

  `var lang`

    RETURNS (uint64): ID of the language of the parent document's vocabulary.

  `var lang_`

    RETURNS (str): Language of the parent document's vocabulary, e.g. 'en'.

  `var left_edge`

    The leftmost token of this token's syntactic descendents.

    RETURNS (Token): The first token such that `self.is_ancestor(token)`.

  `var lefts`

    The leftward immediate children of the word, in the syntactic dependency parse.

    YIELDS (Token): A left-child of the token.

    DOCS: https://spacy.io/api/token#lefts

  `var lemma`

    RETURNS (uint64): ID of the base form of the word, with no inflectional suffixes.

  `var lemma_`

    RETURNS (str): The token lemma, i.e. the base form of the word, with no inflectional suffixes.

  `var lex`

    RETURNS (Lexeme): The underlying lexeme.

  `var lex_id`

    RETURNS (int): Sequential ID of the token's lexical type.

  `var like_email`

    RETURNS (bool): Whether the token resembles an email address.

  `var like_num`

    RETURNS (bool): Whether the token resembles a number, e.g. "10.9", "10", "ten", etc.

  `var like_url`

    RETURNS (bool): Whether the token resembles a URL.

  `var lower`

    RETURNS (uint64): ID of the lowercase token text.

  `var lower_`

    RETURNS (str): The lowercase token text. Equivalent to `Token.text.lower()`.

  `var morph`
  `var n_lefts`

    The number of leftward immediate children of the word, in the syntactic dependency parse.

    RETURNS (int): The number of leftward immediate children of the word, in the syntactic dependency parse.

    DOCS: https://spacy.io/api/token#n_lefts

  `var n_rights`

    The number of rightward immediate children of the word, in the syntactic dependency parse.

    RETURNS (int): The number of rightward immediate children of the word, in the syntactic dependency parse.

    DOCS: https://spacy.io/api/token#n_rights

  `var norm`

    RETURNS (uint64): ID of the token's norm, i.e. a normalised form of the token text. Usually set in the language's tokenizer exceptions or norm exceptions.

  `var norm_`

    RETURNS (str): The token's norm, i.e. a normalised form of the token text. Usually set in the language's tokenizer exceptions or norm exceptions.

  `var orth`

    RETURNS (uint64): ID of the verbatim text content.

  `var orth_`

    RETURNS (str): Verbatim text content (identical to `Token.text`). Exists mostly for consistency with the other attributes.

  `var pos`

    RETURNS (uint64): ID of coarse-grained part-of-speech tag.

  `var pos_`

    RETURNS (str): Coarse-grained part-of-speech tag.

  `var prefix`

    RETURNS (uint64): ID of a length-N substring from the start of the token. Defaults to `N=1`.

  `var prefix_`

    RETURNS (str): A length-N substring from the start of the token. Defaults to `N=1`.

  `var prob`

    RETURNS (float): Smoothed log probability estimate of token type.

  `var rank`

    RETURNS (int): Sequential ID of the token's lexical type, used to index into tables, e.g. for word vectors.

  `var right_edge`

    The rightmost token of this token's syntactic descendents.

    RETURNS (Token): The last token such that `self.is_ancestor(token)`.

  `var rights`

    The rightward immediate children of the word, in the syntactic dependency parse.

    YIELDS (Token): A right-child of the token.

    DOCS: https://spacy.io/api/token#rights

  `var sent`

    RETURNS (Span): The sentence span that the token is a part of.

  `var sent_start`

    Deprecated: use Token.is_sent_start instead.

  `var sentiment`

    RETURNS (float): A scalar value indicating the positivity or negativity of the token.

  `var shape`

    RETURNS (uint64): ID of the token's shape, a transform of the token's string, to show orthographic features (e.g. "Xxxx", "dd").

  `var shape_`

    RETURNS (str): Transform of the token's string, to show orthographic features. For example, "Xxxx" or "dd".

  `var subtree`

    A sequence containing the token and all the token's syntactic descendants.

    YIELDS (Token): A descendent token such that `self.is_ancestor(descendent) or token == self`.

    DOCS: https://spacy.io/api/token#subtree

  `var suffix`

    RETURNS (uint64): ID of a length-N substring from the end of the token. Defaults to `N=3`.

  `var suffix_`

    RETURNS (str): A length-N substring from the end of the token. Defaults to `N=3`.

  `var tag`

    RETURNS (uint64): ID of fine-grained part-of-speech tag.

  `var tag_`

    RETURNS (str): Fine-grained part-of-speech tag.

  `var tensor`
  `var text`

    RETURNS (str): The original verbatim text of the token.

  `var text_with_ws`

    RETURNS (str): The text content of the span (with trailing whitespace).

  `var vector`

    A real-valued meaning representation.

    RETURNS (numpy.ndarray[ndim=1, dtype='float32']): A 1D numpy array representing the token's semantics.

    DOCS: https://spacy.io/api/token#vector

  `var vector_norm`

    The L2 norm of the token's vector representation.

    RETURNS (float): The L2 norm of the vector representation.

    DOCS: https://spacy.io/api/token#vector_norm

  `var vocab`
  `var whitespace_`

    RETURNS (str): The trailing whitespace character, if present.

  ### Methods

  `def check_flag(...)`

    Token.check_flag(self, attr_id_t flag_id) -> bool Check the value of a boolean flag.

            flag_id (int): The ID of the flag attribute.
            RETURNS (bool): Whether the flag is set.

            DOCS: <https://spacy.io/api/token#check_flag>

  `def get_extension(...)`

    Token.get_extension(type cls, name) Look up a previously registered extension by name.

            name (str): Name of the extension.
            RETURNS (tuple): A <code>(default, method, getter, setter)</code> tuple.

            DOCS: <https://spacy.io/api/token#get_extension>

  `def has_dep(...)`

    Token.has_dep(self) Check whether the token has annotated dep information. Returns False when the dep label is unset/missing.

            RETURNS (bool): Whether the dep label is valid or not.

  `def has_extension(...)`

    Token.has_extension(type cls, name) Check whether an extension has been registered.

            name (str): Name of the extension.
            RETURNS (bool): Whether the extension has been registered.

            DOCS: <https://spacy.io/api/token#has_extension>

  `def has_head(...)`

    Token.has_head(self) Check whether the token has annotated head information. Return False when the head annotation is unset/missing.

            RETURNS (bool): Whether the head annotation is valid or not.

  `def has_morph(...)`

    Token.has_morph(self) Check whether the token has annotated morph information. Return False when the morph annotation is unset/missing.

            RETURNS (bool): Whether the morph annotation is set.

  `def iob_strings(...)`

    Token.iob_strings(type cls)

  `def is_ancestor(...)`

    Token.is_ancestor(self, descendant) Check whether this token is a parent, grandparent, etc. of another in the dependency tree.

            descendant (Token): Another token.
            RETURNS (bool): Whether this token is the ancestor of the descendant.

            DOCS: <https://spacy.io/api/token#is_ancestor>

  `def nbor(...)`

    Token.nbor(self, int i=1) Get a neighboring token.

            i (int): The relative position of the token to get. Defaults to 1.
            RETURNS (Token): The token at position `self.doc[self.i+i]`.

            DOCS: <https://spacy.io/api/token#nbor>

  `def remove_extension(...)`

    Token.remove_extension(type cls, name) Remove a previously registered extension.

            name (str): Name of the extension.
            RETURNS (tuple): A <code>(default, method, getter, setter)</code> tuple of the
                removed extension.

            DOCS: <https://spacy.io/api/token#remove_extension>

  `def set_extension(...)`

    Token.set_extension(type cls, name, **kwargs) Define a custom attribute which becomes available as `Token._`.

            name (str): Name of the attribute to set.
            default: Optional default value of the attribute.
            getter (callable): Optional getter function.
            setter (callable): Optional setter function.
            method (callable): Optional method for method extension.
            force (bool): Force overwriting existing attribute.

            DOCS: <https://spacy.io/api/token#set_extension>
            USAGE: <https://spacy.io/usage/processing-pipelines#custom-components-attributes>

  `def set_morph(...)`

    Token.set_morph(self, features)

  `def similarity(...)`

    Token.similarity(self, other) Make a semantic similarity estimate. The default estimate is cosine similarity using an average of word vectors.

            other (object): The object to compare with. By default, accepts <code><a title="lang_main.types.Doc" href="#lang_main.types.Doc">Doc</a></code>,
                <code>Span</code>, <code><a title="lang_main.types.Token" href="#lang_main.types.Token">Token</a></code> and <code>Lexeme</code> objects.
            RETURNS (float): A scalar similarity score. Higher is more similar.

            DOCS: <https://spacy.io/api/token#similarity>