1# Copyright 2015 The TensorFlow Authors. All Rights Reserved. 2# 3# Licensed under the Apache License, Version 2.0 (the "License"); 4# you may not use this file except in compliance with the License. 5# You may obtain a copy of the License at 6# 7# http://www.apache.org/licenses/LICENSE-2.0 8# 9# Unless required by applicable law or agreed to in writing, software 10# distributed under the License is distributed on an "AS IS" BASIS, 11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12# See the License for the specific language governing permissions and 13# limitations under the License. 14# ============================================================================== 15 16"""Wrappers for candidate sampling operations.""" 17 18from __future__ import absolute_import 19from __future__ import division 20from __future__ import print_function 21 22from tensorflow.python.framework import random_seed 23from tensorflow.python.ops import array_ops # pylint: disable=unused-import 24from tensorflow.python.ops import gen_candidate_sampling_ops 25from tensorflow.python.ops import math_ops # pylint: disable=unused-import 26from tensorflow.python.util import deprecation 27from tensorflow.python.util.tf_export import tf_export 28 29 30@tf_export( 31 'random.uniform_candidate_sampler', 32 v1=['random.uniform_candidate_sampler', 'nn.uniform_candidate_sampler']) 33@deprecation.deprecated_endpoints('nn.uniform_candidate_sampler') 34def uniform_candidate_sampler(true_classes, num_true, num_sampled, unique, 35 range_max, seed=None, name=None): 36 """Samples a set of classes using a uniform base distribution. 37 38 This operation randomly samples a tensor of sampled classes 39 (`sampled_candidates`) from the range of integers `[0, range_max)`. 40 41 The elements of `sampled_candidates` are drawn without replacement 42 (if `unique=True`) or with replacement (if `unique=False`) from 43 the base distribution. 44 45 The base distribution for this operation is the uniform distribution 46 over the range of integers `[0, range_max)`. 47 48 In addition, this operation returns tensors `true_expected_count` 49 and `sampled_expected_count` representing the number of times each 50 of the target classes (`true_classes`) and the sampled 51 classes (`sampled_candidates`) is expected to occur in an average 52 tensor of sampled classes. These values correspond to `Q(y|x)` 53 defined in [this 54 document](http://www.tensorflow.org/extras/candidate_sampling.pdf). 55 If `unique=True`, then these are post-rejection probabilities and we 56 compute them approximately. 57 58 Args: 59 true_classes: A `Tensor` of type `int64` and shape `[batch_size, 60 num_true]`. The target classes. 61 num_true: An `int`. The number of target classes per training example. 62 num_sampled: An `int`. The number of classes to randomly sample. The 63 `sampled_candidates` return value will have shape `[num_sampled]`. If 64 `unique=True`, `num_sampled` must be less than or equal to `range_max`. 65 unique: A `bool`. Determines whether all sampled classes in a batch are 66 unique. 67 range_max: An `int`. The number of possible classes. 68 seed: An `int`. An operation-specific seed. Default is 0. 69 name: A name for the operation (optional). 70 71 Returns: 72 sampled_candidates: A tensor of type `int64` and shape `[num_sampled]`. The 73 sampled classes, either with possible duplicates (`unique=False`) or all 74 unique (`unique=True`). In either case, `sampled_candidates` is 75 independent of the true classes. 76 true_expected_count: A tensor of type `float`. Same shape as 77 `true_classes`. The expected counts under the sampling distribution 78 of each of `true_classes`. 79 sampled_expected_count: A tensor of type `float`. Same shape as 80 `sampled_candidates`. The expected counts under the sampling distribution 81 of each of `sampled_candidates`. 82 """ 83 seed1, seed2 = random_seed.get_seed(seed) 84 return gen_candidate_sampling_ops.uniform_candidate_sampler( 85 true_classes, num_true, num_sampled, unique, range_max, seed=seed1, 86 seed2=seed2, name=name) 87 88 89@tf_export( 90 'random.log_uniform_candidate_sampler', 91 v1=[ 92 'random.log_uniform_candidate_sampler', 93 'nn.log_uniform_candidate_sampler' 94 ]) 95@deprecation.deprecated_endpoints('nn.log_uniform_candidate_sampler') 96def log_uniform_candidate_sampler(true_classes, num_true, num_sampled, unique, 97 range_max, seed=None, name=None): 98 """Samples a set of classes using a log-uniform (Zipfian) base distribution. 99 100 This operation randomly samples a tensor of sampled classes 101 (`sampled_candidates`) from the range of integers `[0, range_max)`. 102 103 The elements of `sampled_candidates` are drawn without replacement 104 (if `unique=True`) or with replacement (if `unique=False`) from 105 the base distribution. 106 107 The base distribution for this operation is an approximately log-uniform 108 or Zipfian distribution: 109 110 `P(class) = (log(class + 2) - log(class + 1)) / log(range_max + 1)` 111 112 This sampler is useful when the target classes approximately follow such 113 a distribution - for example, if the classes represent words in a lexicon 114 sorted in decreasing order of frequency. If your classes are not ordered by 115 decreasing frequency, do not use this op. 116 117 In addition, this operation returns tensors `true_expected_count` 118 and `sampled_expected_count` representing the number of times each 119 of the target classes (`true_classes`) and the sampled 120 classes (`sampled_candidates`) is expected to occur in an average 121 tensor of sampled classes. These values correspond to `Q(y|x)` 122 defined in [this 123 document](http://www.tensorflow.org/extras/candidate_sampling.pdf). 124 If `unique=True`, then these are post-rejection probabilities and we 125 compute them approximately. 126 127 Args: 128 true_classes: A `Tensor` of type `int64` and shape `[batch_size, 129 num_true]`. The target classes. 130 num_true: An `int`. The number of target classes per training example. 131 num_sampled: An `int`. The number of classes to randomly sample. 132 unique: A `bool`. Determines whether all sampled classes in a batch are 133 unique. 134 range_max: An `int`. The number of possible classes. 135 seed: An `int`. An operation-specific seed. Default is 0. 136 name: A name for the operation (optional). 137 138 Returns: 139 sampled_candidates: A tensor of type `int64` and shape `[num_sampled]`. 140 The sampled classes. 141 true_expected_count: A tensor of type `float`. Same shape as 142 `true_classes`. The expected counts under the sampling distribution 143 of each of `true_classes`. 144 sampled_expected_count: A tensor of type `float`. Same shape as 145 `sampled_candidates`. The expected counts under the sampling distribution 146 of each of `sampled_candidates`. 147 """ 148 seed1, seed2 = random_seed.get_seed(seed) 149 return gen_candidate_sampling_ops.log_uniform_candidate_sampler( 150 true_classes, num_true, num_sampled, unique, range_max, seed=seed1, 151 seed2=seed2, name=name) 152 153 154@tf_export( 155 'random.learned_unigram_candidate_sampler', 156 'nn.learned_unigram_candidate_sampler') 157@deprecation.deprecated_endpoints(['nn.learned_unigram_candidate_sampler']) 158def learned_unigram_candidate_sampler(true_classes, num_true, num_sampled, 159 unique, range_max, seed=None, name=None): 160 """Samples a set of classes from a distribution learned during training. 161 162 This operation randomly samples a tensor of sampled classes 163 (`sampled_candidates`) from the range of integers `[0, range_max)`. 164 165 The elements of `sampled_candidates` are drawn without replacement 166 (if `unique=True`) or with replacement (if `unique=False`) from 167 the base distribution. 168 169 The base distribution for this operation is constructed on the fly 170 during training. It is a unigram distribution over the target 171 classes seen so far during training. Every integer in `[0, range_max)` 172 begins with a weight of 1, and is incremented by 1 each time it is 173 seen as a target class. The base distribution is not saved to checkpoints, 174 so it is reset when the model is reloaded. 175 176 In addition, this operation returns tensors `true_expected_count` 177 and `sampled_expected_count` representing the number of times each 178 of the target classes (`true_classes`) and the sampled 179 classes (`sampled_candidates`) is expected to occur in an average 180 tensor of sampled classes. These values correspond to `Q(y|x)` 181 defined in [this 182 document](http://www.tensorflow.org/extras/candidate_sampling.pdf). 183 If `unique=True`, then these are post-rejection probabilities and we 184 compute them approximately. 185 186 Args: 187 true_classes: A `Tensor` of type `int64` and shape `[batch_size, 188 num_true]`. The target classes. 189 num_true: An `int`. The number of target classes per training example. 190 num_sampled: An `int`. The number of classes to randomly sample. 191 unique: A `bool`. Determines whether all sampled classes in a batch are 192 unique. 193 range_max: An `int`. The number of possible classes. 194 seed: An `int`. An operation-specific seed. Default is 0. 195 name: A name for the operation (optional). 196 197 Returns: 198 sampled_candidates: A tensor of type `int64` and shape `[num_sampled]`. 199 The sampled classes. 200 true_expected_count: A tensor of type `float`. Same shape as 201 `true_classes`. The expected counts under the sampling distribution 202 of each of `true_classes`. 203 sampled_expected_count: A tensor of type `float`. Same shape as 204 `sampled_candidates`. The expected counts under the sampling distribution 205 of each of `sampled_candidates`. 206 207 """ 208 seed1, seed2 = random_seed.get_seed(seed) 209 return gen_candidate_sampling_ops.learned_unigram_candidate_sampler( 210 true_classes, num_true, num_sampled, unique, range_max, seed=seed1, 211 seed2=seed2, name=name) 212 213 214@tf_export('random.fixed_unigram_candidate_sampler', 215 'nn.fixed_unigram_candidate_sampler') 216def fixed_unigram_candidate_sampler(true_classes, 217 num_true, 218 num_sampled, 219 unique, 220 range_max, 221 vocab_file='', 222 distortion=1.0, 223 num_reserved_ids=0, 224 num_shards=1, 225 shard=0, 226 unigrams=(), 227 seed=None, 228 name=None): 229 """Samples a set of classes using the provided (fixed) base distribution. 230 231 This operation randomly samples a tensor of sampled classes 232 (`sampled_candidates`) from the range of integers `[0, range_max)`. 233 234 The elements of `sampled_candidates` are drawn without replacement 235 (if `unique=True`) or with replacement (if `unique=False`) from 236 the base distribution. 237 238 The base distribution is read from a file or passed in as an 239 in-memory array. There is also an option to skew the distribution by 240 applying a distortion power to the weights. 241 242 In addition, this operation returns tensors `true_expected_count` 243 and `sampled_expected_count` representing the number of times each 244 of the target classes (`true_classes`) and the sampled 245 classes (`sampled_candidates`) is expected to occur in an average 246 tensor of sampled classes. These values correspond to `Q(y|x)` 247 defined in [this 248 document](http://www.tensorflow.org/extras/candidate_sampling.pdf). 249 If `unique=True`, then these are post-rejection probabilities and we 250 compute them approximately. 251 252 Args: 253 true_classes: A `Tensor` of type `int64` and shape `[batch_size, 254 num_true]`. The target classes. 255 num_true: An `int`. The number of target classes per training example. 256 num_sampled: An `int`. The number of classes to randomly sample. 257 unique: A `bool`. Determines whether all sampled classes in a batch are 258 unique. 259 range_max: An `int`. The number of possible classes. 260 vocab_file: Each valid line in this file (which should have a CSV-like 261 format) corresponds to a valid word ID. IDs are in sequential order, 262 starting from num_reserved_ids. The last entry in each line is expected 263 to be a value corresponding to the count or relative probability. Exactly 264 one of `vocab_file` and `unigrams` needs to be passed to this operation. 265 distortion: The distortion is used to skew the unigram probability 266 distribution. Each weight is first raised to the distortion's power 267 before adding to the internal unigram distribution. As a result, 268 `distortion = 1.0` gives regular unigram sampling (as defined by the vocab 269 file), and `distortion = 0.0` gives a uniform distribution. 270 num_reserved_ids: Optionally some reserved IDs can be added in the range 271 `[0, num_reserved_ids)` by the users. One use case is that a special 272 unknown word token is used as ID 0. These IDs will have a sampling 273 probability of 0. 274 num_shards: A sampler can be used to sample from a subset of the original 275 range in order to speed up the whole computation through parallelism. This 276 parameter (together with `shard`) indicates the number of partitions that 277 are being used in the overall computation. 278 shard: A sampler can be used to sample from a subset of the original range 279 in order to speed up the whole computation through parallelism. This 280 parameter (together with `num_shards`) indicates the particular partition 281 number of the operation, when partitioning is being used. 282 unigrams: A list of unigram counts or probabilities, one per ID in 283 sequential order. Exactly one of `vocab_file` and `unigrams` should be 284 passed to this operation. 285 seed: An `int`. An operation-specific seed. Default is 0. 286 name: A name for the operation (optional). 287 288 Returns: 289 sampled_candidates: A tensor of type `int64` and shape `[num_sampled]`. 290 The sampled classes. 291 true_expected_count: A tensor of type `float`. Same shape as 292 `true_classes`. The expected counts under the sampling distribution 293 of each of `true_classes`. 294 sampled_expected_count: A tensor of type `float`. Same shape as 295 `sampled_candidates`. The expected counts under the sampling distribution 296 of each of `sampled_candidates`. 297 298 """ 299 seed1, seed2 = random_seed.get_seed(seed) 300 return gen_candidate_sampling_ops.fixed_unigram_candidate_sampler( 301 true_classes, num_true, num_sampled, unique, range_max, 302 vocab_file=vocab_file, distortion=distortion, 303 num_reserved_ids=num_reserved_ids, num_shards=num_shards, shard=shard, 304 unigrams=unigrams, seed=seed1, seed2=seed2, name=name) 305 306 307@tf_export('random.all_candidate_sampler', 'nn.all_candidate_sampler') 308def all_candidate_sampler(true_classes, num_true, num_sampled, unique, 309 seed=None, name=None): 310 """Generate the set of all classes. 311 312 Deterministically generates and returns the set of all possible classes. 313 For testing purposes. There is no need to use this, since you might as 314 well use full softmax or full logistic regression. 315 316 Args: 317 true_classes: A `Tensor` of type `int64` and shape `[batch_size, 318 num_true]`. The target classes. 319 num_true: An `int`. The number of target classes per training example. 320 num_sampled: An `int`. The number of possible classes. 321 unique: A `bool`. Ignored. 322 unique. 323 seed: An `int`. An operation-specific seed. Default is 0. 324 name: A name for the operation (optional). 325 326 Returns: 327 sampled_candidates: A tensor of type `int64` and shape `[num_sampled]`. 328 This operation deterministically returns the entire range 329 `[0, num_sampled]`. 330 true_expected_count: A tensor of type `float`. Same shape as 331 `true_classes`. The expected counts under the sampling distribution 332 of each of `true_classes`. All returned values are 1.0. 333 sampled_expected_count: A tensor of type `float`. Same shape as 334 `sampled_candidates`. The expected counts under the sampling distribution 335 of each of `sampled_candidates`. All returned values are 1.0. 336 """ 337 seed1, seed2 = random_seed.get_seed(seed) 338 return gen_candidate_sampling_ops.all_candidate_sampler( 339 true_classes, num_true, num_sampled, unique, seed=seed1, seed2=seed2, 340 name=name) 341 342 343@tf_export('nn.compute_accidental_hits') 344def compute_accidental_hits(true_classes, sampled_candidates, num_true, 345 seed=None, name=None): 346 """Compute the position ids in `sampled_candidates` matching `true_classes`. 347 348 In Candidate Sampling, this operation facilitates virtually removing 349 sampled classes which happen to match target classes. This is done 350 in Sampled Softmax and Sampled Logistic. 351 352 See our [Candidate Sampling Algorithms 353 Reference](http://www.tensorflow.org/extras/candidate_sampling.pdf). 354 355 We presuppose that the `sampled_candidates` are unique. 356 357 We call it an 'accidental hit' when one of the target classes 358 matches one of the sampled classes. This operation reports 359 accidental hits as triples `(index, id, weight)`, where `index` 360 represents the row number in `true_classes`, `id` represents the 361 position in `sampled_candidates`, and weight is `-FLOAT_MAX`. 362 363 The result of this op should be passed through a `sparse_to_dense` 364 operation, then added to the logits of the sampled classes. This 365 removes the contradictory effect of accidentally sampling the true 366 target classes as noise classes for the same example. 367 368 Args: 369 true_classes: A `Tensor` of type `int64` and shape `[batch_size, 370 num_true]`. The target classes. 371 sampled_candidates: A tensor of type `int64` and shape `[num_sampled]`. 372 The sampled_candidates output of CandidateSampler. 373 num_true: An `int`. The number of target classes per training example. 374 seed: An `int`. An operation-specific seed. Default is 0. 375 name: A name for the operation (optional). 376 377 Returns: 378 indices: A `Tensor` of type `int32` and shape `[num_accidental_hits]`. 379 Values indicate rows in `true_classes`. 380 ids: A `Tensor` of type `int64` and shape `[num_accidental_hits]`. 381 Values indicate positions in `sampled_candidates`. 382 weights: A `Tensor` of type `float` and shape `[num_accidental_hits]`. 383 Each value is `-FLOAT_MAX`. 384 385 """ 386 seed1, seed2 = random_seed.get_seed(seed) 387 return gen_candidate_sampling_ops.compute_accidental_hits( 388 true_classes, sampled_candidates, num_true, seed=seed1, seed2=seed2, 389 name=name) 390