spaCy/spacy/vectors.pyx

482 lines
17 KiB
Cython
Raw Normal View History

2017-10-27 20:45:19 +03:00
# coding: utf8
2017-08-19 22:27:35 +03:00
from __future__ import unicode_literals
2017-10-27 20:45:19 +03:00
cimport numpy as np
from cython.operator cimport dereference as deref
from libcpp.set cimport set as cppset
import functools
2017-06-05 13:32:08 +03:00
import numpy
from collections import OrderedDict
import srsly
import warnings
from thinc.neural.util import get_array_module
from thinc.neural._classes.model import Model
2017-06-05 13:32:08 +03:00
from .strings cimport StringStore
from .strings import get_string_id
2017-10-16 21:55:00 +03:00
from .compat import basestring_, path2str
from .errors import Errors
2017-10-27 20:45:19 +03:00
from . import util
2017-06-05 13:32:08 +03:00
2018-03-11 00:53:42 +03:00
def unpickle_vectors(bytes_data):
return Vectors().from_bytes(bytes_data)
2017-10-31 20:25:08 +03:00
class GlobalRegistry(object):
"""Global store of vectors, to avoid repeatedly loading the data."""
data = {}
@classmethod
def register(cls, name, data):
cls.data[name] = data
return functools.partial(cls.get, name)
@classmethod
def get(cls, name):
return cls.data[name]
2017-06-05 13:32:08 +03:00
cdef class Vectors:
2017-10-27 20:45:19 +03:00
"""Store, save and load word vectors.
2017-10-02 01:05:54 +03:00
2017-10-01 23:10:33 +03:00
Vectors data is kept in the vectors.data attribute, which should be an
2017-10-27 20:45:19 +03:00
instance of numpy.ndarray (for CPU vectors) or cupy.ndarray
(for GPU vectors). `vectors.key2row` is a dictionary mapping word hashes to
rows in the vectors.data table.
2017-11-01 01:23:34 +03:00
2017-10-31 20:25:08 +03:00
Multiple keys can be mapped to the same vector, and not all of the rows in
the table need to be assigned - so len(list(vectors.keys())) may be
2017-10-31 20:25:08 +03:00
greater or smaller than vectors.shape[0].
DOCS: https://spacy.io/api/vectors
2017-10-27 20:45:19 +03:00
"""
cdef public object name
2017-06-05 13:32:08 +03:00
cdef public object data
2017-08-19 05:33:03 +03:00
cdef public object key2row
cdef cppset[int] _unset
2017-06-05 13:32:08 +03:00
def __init__(self, *, shape=None, data=None, keys=None, name=None):
2017-10-31 20:25:08 +03:00
"""Create a new vector store.
2017-11-01 01:23:34 +03:00
2017-10-31 20:25:08 +03:00
shape (tuple): Size of the table, as (# entries, # columns)
2017-10-27 20:45:19 +03:00
data (numpy.ndarray): The vector data.
2017-11-01 01:23:34 +03:00
keys (iterable): A sequence of keys, aligned with the data.
2019-09-26 17:21:32 +03:00
name (unicode): A name to identify the vectors table.
2017-10-27 20:45:19 +03:00
RETURNS (Vectors): The newly created object.
DOCS: https://spacy.io/api/vectors#init
2017-10-27 20:45:19 +03:00
"""
self.name = name
2017-10-31 20:25:08 +03:00
if data is None:
if shape is None:
shape = (0,0)
data = numpy.zeros(shape, dtype="f")
2017-10-31 20:25:08 +03:00
self.data = data
self.key2row = OrderedDict()
if self.data is not None:
self._unset = cppset[int]({i for i in range(self.data.shape[0])})
2017-06-05 13:32:08 +03:00
else:
self._unset = cppset[int]()
2017-10-31 20:25:08 +03:00
if keys is not None:
for i, key in enumerate(keys):
self.add(key, row=i)
2017-11-01 01:23:34 +03:00
2017-10-31 20:25:08 +03:00
@property
def shape(self):
"""Get `(rows, dims)` tuples of number of rows and number of dimensions
in the vector table.
RETURNS (tuple): A `(rows, dims)` pair.
DOCS: https://spacy.io/api/vectors#shape
2017-10-31 20:25:08 +03:00
"""
return self.data.shape
@property
def size(self):
"""The vector size i,e. rows * dims.
RETURNS (int): The vector size.
DOCS: https://spacy.io/api/vectors#size
"""
2017-10-31 20:25:08 +03:00
return self.data.shape[0] * self.data.shape[1]
@property
def is_full(self):
"""Whether the vectors table is full.
RETURNS (bool): `True` if no slots are available for new keys.
DOCS: https://spacy.io/api/vectors#is_full
"""
return self._unset.size() == 0
2017-06-05 13:32:08 +03:00
2017-10-31 21:30:52 +03:00
@property
def n_keys(self):
"""Get the number of keys in the table. Note that this is the number
of all keys, not just unique vectors.
RETURNS (int): The number of keys in the table.
DOCS: https://spacy.io/api/vectors#n_keys
"""
2017-10-31 21:30:52 +03:00
return len(self.key2row)
2017-06-05 13:32:08 +03:00
def __reduce__(self):
2018-03-11 00:53:42 +03:00
return (unpickle_vectors, (self.to_bytes(),))
2017-06-05 13:32:08 +03:00
def __getitem__(self, key):
2017-10-31 20:25:08 +03:00
"""Get a vector by key. If the key is not found, a KeyError is raised.
2017-10-01 23:10:33 +03:00
2017-10-31 20:25:08 +03:00
key (int): The key to get the vector for.
RETURNS (ndarray): The vector for the key.
DOCS: https://spacy.io/api/vectors#getitem
2017-10-27 20:45:19 +03:00
"""
2017-08-19 05:33:03 +03:00
i = self.key2row[key]
2017-06-05 13:32:08 +03:00
if i is None:
raise KeyError(Errors.E058.format(key=key))
2017-06-05 13:32:08 +03:00
else:
return self.data[i]
def __setitem__(self, key, vector):
2017-10-31 20:25:08 +03:00
"""Set a vector for the given key.
2017-10-27 20:45:19 +03:00
2017-10-31 20:25:08 +03:00
key (int): The key to set the vector for.
2017-11-01 01:23:34 +03:00
vector (ndarray): The vector to set.
DOCS: https://spacy.io/api/vectors#setitem
2017-10-27 20:45:19 +03:00
"""
2017-08-19 05:33:03 +03:00
i = self.key2row[key]
2017-06-05 13:32:08 +03:00
self.data[i] = vector
if self._unset.count(i):
self._unset.erase(self._unset.find(i))
2017-06-05 13:32:08 +03:00
def __iter__(self):
2017-11-01 01:23:34 +03:00
"""Iterate over the keys in the table.
2017-10-27 20:45:19 +03:00
2017-11-01 01:23:34 +03:00
YIELDS (int): A key in the table.
DOCS: https://spacy.io/api/vectors#iter
2017-10-27 20:45:19 +03:00
"""
2017-10-31 20:25:08 +03:00
yield from self.key2row
2017-06-05 13:32:08 +03:00
def __len__(self):
2017-10-31 20:25:08 +03:00
"""Return the number of vectors in the table.
2017-10-27 20:45:19 +03:00
RETURNS (int): The number of vectors in the data.
DOCS: https://spacy.io/api/vectors#len
2017-10-27 20:45:19 +03:00
"""
2017-10-31 20:25:08 +03:00
return self.data.shape[0]
2017-08-19 20:52:25 +03:00
def __contains__(self, key):
2017-10-31 20:25:08 +03:00
"""Check whether a key has been mapped to a vector entry in the table.
2017-10-27 20:45:19 +03:00
2017-10-31 20:25:08 +03:00
key (int): The key to check.
2017-10-27 20:45:19 +03:00
RETURNS (bool): Whether the key has a vector entry.
DOCS: https://spacy.io/api/vectors#contains
2017-10-27 20:45:19 +03:00
"""
2017-08-19 20:52:25 +03:00
return key in self.key2row
2017-10-31 20:25:08 +03:00
def resize(self, shape, inplace=False):
2017-11-01 01:23:34 +03:00
"""Resize the underlying vectors array. If inplace=True, the memory
2017-10-31 20:25:08 +03:00
is reallocated. This may cause other references to the data to become
invalid, so only use inplace=True if you're sure that's what you want.
If the number of vectors is reduced, keys mapped to rows that have been
deleted are removed. These removed items are returned as a list of
2017-11-01 01:23:34 +03:00
`(key, row)` tuples.
shape (tuple): A `(rows, dims)` tuple.
inplace (bool): Reallocate the memory.
RETURNS (list): The removed items as a list of `(key, row)` tuples.
DOCS: https://spacy.io/api/vectors#resize
2017-11-01 01:23:34 +03:00
"""
xp = get_array_module(self.data)
2017-10-31 20:25:08 +03:00
if inplace:
if shape[1] != self.data.shape[1]:
raise ValueError(Errors.E193.format(new_dim=shape[1], curr_dim=self.data.shape[1]))
if xp == numpy:
self.data.resize(shape, refcheck=False)
else:
raise ValueError(Errors.E192)
2017-10-31 20:25:08 +03:00
else:
resized_array = xp.zeros(shape, dtype=self.data.dtype)
copy_shape = (min(shape[0], self.data.shape[0]), min(shape[1], self.data.shape[1]))
resized_array[:copy_shape[0], :copy_shape[1]] = self.data[:copy_shape[0], :copy_shape[1]]
self.data = resized_array
self._sync_unset()
2017-10-31 20:25:08 +03:00
removed_items = []
for key, row in list(self.key2row.items()):
2017-10-31 20:25:08 +03:00
if row >= shape[0]:
self.key2row.pop(key)
removed_items.append((key, row))
return removed_items
2017-11-01 01:23:34 +03:00
2017-10-31 20:25:08 +03:00
def keys(self):
"""RETURNS (iterable): A sequence of keys in the table."""
2017-11-01 01:23:34 +03:00
return self.key2row.keys()
2017-10-31 20:25:08 +03:00
def values(self):
2017-11-01 01:23:34 +03:00
"""Iterate over vectors that have been assigned to at least one key.
2017-10-31 20:25:08 +03:00
Note that some vectors may be unassigned, so the number of vectors
2017-11-01 01:23:34 +03:00
returned may be less than the length of the vectors table.
YIELDS (ndarray): A vector in the table.
DOCS: https://spacy.io/api/vectors#values
2017-11-01 01:23:34 +03:00
"""
2017-10-31 20:25:08 +03:00
for row, vector in enumerate(range(self.data.shape[0])):
if not self._unset.count(row):
2017-10-31 20:25:08 +03:00
yield vector
def items(self):
"""Iterate over `(key, vector)` pairs.
YIELDS (tuple): A key/vector pair.
DOCS: https://spacy.io/api/vectors#items
2017-10-31 20:25:08 +03:00
"""
for key, row in self.key2row.items():
yield key, self.data[row]
2017-11-01 02:34:55 +03:00
def find(self, *, key=None, keys=None, row=None, rows=None):
2017-11-01 02:42:39 +03:00
"""Look up one or more keys by row, or vice versa.
2017-11-01 02:34:55 +03:00
key (unicode / int): Find the row that the given key points to.
Returns int, -1 if missing.
2017-11-01 02:42:39 +03:00
keys (iterable): Find rows that the keys point to.
2017-11-01 02:34:55 +03:00
Returns ndarray.
2019-03-16 19:10:57 +03:00
row (int): Find the first key that points to the row.
2017-11-01 02:34:55 +03:00
Returns int.
2017-11-01 02:42:39 +03:00
rows (iterable): Find the keys that point to the rows.
2017-11-01 02:34:55 +03:00
Returns ndarray.
2017-11-01 02:42:39 +03:00
RETURNS: The requested key, keys, row or rows.
"""
2017-11-01 02:34:55 +03:00
if sum(arg is None for arg in (key, keys, row, rows)) != 3:
bad_kwargs = {"key": key, "keys": keys, "row": row, "rows": rows}
raise ValueError(Errors.E059.format(kwargs=bad_kwargs))
2017-10-31 20:25:08 +03:00
xp = get_array_module(self.data)
2017-11-01 02:34:55 +03:00
if key is not None:
key = get_string_id(key)
2017-11-01 02:34:55 +03:00
return self.key2row.get(key, -1)
elif keys is not None:
keys = [get_string_id(key) for key in keys]
2017-11-01 02:34:55 +03:00
rows = [self.key2row.get(key, -1.) for key in keys]
return xp.asarray(rows, dtype="i")
2017-11-01 02:34:55 +03:00
else:
row2key = {row: key for key, row in self.key2row.items()}
2017-11-01 02:34:55 +03:00
if row is not None:
return row2key[row]
2017-11-01 02:34:55 +03:00
else:
results = [row2key[row] for row in rows]
return xp.asarray(results, dtype="uint64")
2017-10-31 20:25:08 +03:00
def add(self, key, *, vector=None, row=None):
"""Add a key to the table. Keys can be mapped to an existing vector
by setting `row`, or a new vector can be added.
2017-10-27 20:45:19 +03:00
key (int): The key to add.
vector (ndarray / None): A vector to add for the key.
row (int / None): The row number of a vector to map the key to.
RETURNS (int): The row the vector was added to.
DOCS: https://spacy.io/api/vectors#add
2017-10-27 20:45:19 +03:00
"""
# use int for all keys and rows in key2row for more efficient access
# and serialization
key = int(get_string_id(key))
if row is not None:
row = int(row)
2017-10-31 04:00:26 +03:00
if row is None and key in self.key2row:
row = self.key2row[key]
elif row is None:
2017-10-31 20:25:08 +03:00
if self.is_full:
raise ValueError(Errors.E060.format(rows=self.data.shape[0],
cols=self.data.shape[1]))
row = deref(self._unset.begin())
if row < self.data.shape[0]:
self.key2row[key] = row
else:
raise ValueError(Errors.E197.format(row=row, key=key))
2017-08-19 20:52:25 +03:00
if vector is not None:
self.data[row] = vector
if self._unset.count(row):
self._unset.erase(self._unset.find(row))
return row
2017-11-01 01:23:34 +03:00
def most_similar(self, queries, *, batch_size=1024, n=1, sort=True):
"""For each of the given vectors, find the n most similar entries
2017-10-31 20:25:08 +03:00
to it, by cosine.
2017-11-01 01:23:34 +03:00
Queries are by vector. Results are returned as a `(keys, best_rows,
scores)` tuple. If `queries` is large, the calculations are performed in
chunks, to avoid consuming too much memory. You can set the `batch_size`
to control the size/space trade-off during the calculations.
queries (ndarray): An array with one or more vectors.
batch_size (int): The batch size to use.
n (int): The number of entries to return for each query.
sort (bool): Whether to sort the n entries returned by score.
RETURNS (tuple): The most similar entries as a `(keys, best_rows, scores)`
tuple.
"""
filled = sorted(list({row for row in self.key2row.values()}))
if len(filled) < n:
raise ValueError(Errors.E198.format(n=n, n_rows=len(filled)))
2017-10-31 20:25:08 +03:00
xp = get_array_module(self.data)
2017-11-01 01:23:34 +03:00
norms = xp.linalg.norm(self.data[filled], axis=1, keepdims=True)
norms[norms == 0] = 1
vectors = self.data[filled] / norms
2017-11-01 01:23:34 +03:00
best_rows = xp.zeros((queries.shape[0], n), dtype='i')
scores = xp.zeros((queries.shape[0], n), dtype='f')
2017-10-31 20:25:08 +03:00
# Work in batches, to avoid memory problems.
for i in range(0, queries.shape[0], batch_size):
batch = queries[i : i+batch_size]
batch_norms = xp.linalg.norm(batch, axis=1, keepdims=True)
batch_norms[batch_norms == 0] = 1
batch /= batch_norms
2017-10-31 20:25:08 +03:00
# batch e.g. (1024, 300)
# vectors e.g. (10000, 300)
# sims e.g. (1024, 10000)
sims = xp.dot(batch, vectors.T)
best_rows[i:i+batch_size] = xp.argpartition(sims, -n, axis=1)[:,-n:]
scores[i:i+batch_size] = xp.partition(sims, -n, axis=1)[:,-n:]
if sort and n >= 2:
sorted_index = xp.arange(scores.shape[0])[:,None][i:i+batch_size],xp.argsort(scores[i:i+batch_size], axis=1)[:,::-1]
scores[i:i+batch_size] = scores[sorted_index]
best_rows[i:i+batch_size] = best_rows[sorted_index]
for i, j in numpy.ndindex(best_rows.shape):
best_rows[i, j] = filled[best_rows[i, j]]
# Round values really close to 1 or -1
scores = xp.around(scores, decimals=4, out=scores)
# Account for numerical error we want to return in range -1, 1
scores = xp.clip(scores, a_min=-1, a_max=1, out=scores)
2017-11-01 04:06:58 +03:00
row2key = {row: key for key, row in self.key2row.items()}
keys = xp.asarray(
[[row2key[row] for row in best_rows[i] if row in row2key]
for i in range(len(queries)) ], dtype="uint64")
return (keys, best_rows, scores)
2017-06-05 13:32:08 +03:00
def to_disk(self, path, **kwargs):
2017-10-27 20:45:19 +03:00
"""Save the current state to a directory.
path (unicode / Path): A path to a directory, which will be created if
it doesn't exists.
DOCS: https://spacy.io/api/vectors#to_disk
2017-10-27 20:45:19 +03:00
"""
xp = get_array_module(self.data)
if xp is numpy:
save_array = lambda arr, file_: xp.save(file_, arr, allow_pickle=False)
else:
save_array = lambda arr, file_: xp.save(file_, arr)
def save_vectors(path):
# the source of numpy.save indicates that the file object is closed after use.
# but it seems that somehow this does not happen, as ResourceWarnings are raised here.
# in order to not rely on this, wrap in context manager.
with path.open("wb") as _file:
save_array(self.data, _file)
2017-08-18 21:45:48 +03:00
serializers = OrderedDict((
("vectors", lambda p: save_vectors(p)),
("key2row", lambda p: srsly.write_msgpack(p, self.key2row))
2017-08-18 21:45:48 +03:00
))
return util.to_disk(path, serializers, [])
2017-08-18 21:45:48 +03:00
def from_disk(self, path, **kwargs):
2017-10-27 20:45:19 +03:00
"""Loads state from a directory. Modifies the object in place and
returns it.
path (unicode / Path): Directory path, string or Path-like object.
RETURNS (Vectors): The modified object.
DOCS: https://spacy.io/api/vectors#from_disk
2017-10-27 20:45:19 +03:00
"""
2017-10-31 21:58:35 +03:00
def load_key2row(path):
2017-08-19 23:07:00 +03:00
if path.exists():
self.key2row = srsly.read_msgpack(path)
2017-10-31 21:58:35 +03:00
for key, row in self.key2row.items():
if self._unset.count(row):
self._unset.erase(self._unset.find(row))
2017-10-31 21:58:35 +03:00
def load_keys(path):
if path.exists():
keys = numpy.load(str(path))
for i, key in enumerate(keys):
self.add(key, row=i)
2017-08-19 19:42:11 +03:00
def load_vectors(path):
xp = Model.ops.xp
2017-08-19 23:07:00 +03:00
if path.exists():
self.data = xp.load(str(path))
2017-08-18 21:45:48 +03:00
serializers = OrderedDict((
("vectors", load_vectors),
2020-05-30 13:53:32 +03:00
("keys", load_keys),
("key2row", load_key2row),
2017-08-18 21:45:48 +03:00
))
util.from_disk(path, serializers, [])
self._sync_unset()
2017-08-19 19:42:11 +03:00
return self
2017-06-05 13:32:08 +03:00
def to_bytes(self, **kwargs):
2017-10-27 20:45:19 +03:00
"""Serialize the current state to a binary string.
exclude (list): String names of serialization fields to exclude.
2017-10-27 20:45:19 +03:00
RETURNS (bytes): The serialized form of the `Vectors` object.
DOCS: https://spacy.io/api/vectors#to_bytes
2017-10-27 20:45:19 +03:00
"""
2017-06-05 13:32:08 +03:00
def serialize_weights():
if hasattr(self.data, "to_bytes"):
2017-08-18 21:45:48 +03:00
return self.data.to_bytes()
2017-06-05 13:32:08 +03:00
else:
return srsly.msgpack_dumps(self.data)
2017-06-05 13:32:08 +03:00
serializers = OrderedDict((
("key2row", lambda: srsly.msgpack_dumps(self.key2row)),
("vectors", serialize_weights)
2017-06-05 13:32:08 +03:00
))
return util.to_bytes(serializers, [])
2017-06-05 13:32:08 +03:00
def from_bytes(self, data, **kwargs):
2017-10-27 20:45:19 +03:00
"""Load state from a binary string.
data (bytes): The data to load from.
exclude (list): String names of serialization fields to exclude.
2017-10-27 20:45:19 +03:00
RETURNS (Vectors): The `Vectors` object.
DOCS: https://spacy.io/api/vectors#from_bytes
2017-10-27 20:45:19 +03:00
"""
2017-06-05 13:32:08 +03:00
def deserialize_weights(b):
if hasattr(self.data, "from_bytes"):
2017-08-18 21:45:48 +03:00
self.data.from_bytes()
2017-06-05 13:32:08 +03:00
else:
self.data = srsly.msgpack_loads(b)
2017-06-05 13:32:08 +03:00
deserializers = OrderedDict((
("key2row", lambda b: self.key2row.update(srsly.msgpack_loads(b))),
("vectors", deserialize_weights)
2017-06-05 13:32:08 +03:00
))
util.from_bytes(data, deserializers, [])
self._sync_unset()
2017-08-19 19:42:11 +03:00
return self
def _sync_unset(self):
filled = {row for row in self.key2row.values()}
self._unset = cppset[int]({row for row in range(self.data.shape[0]) if row not in filled})