0
# Standard Text Embeddings
1

2
Core Universal Sentence Encoder functionality for generating 512-dimensional embeddings from text using the Transformer architecture. Perfect for semantic similarity, text classification, clustering, and general natural language processing tasks.
3

4
## Capabilities
5

6
### Load Model
7

8
Creates and loads the main Universal Sentence Encoder model with optional custom configuration.
9

10
```typescript { .api }
11
/**
12
 * Load the Universal Sentence Encoder model
13
 * @param config - Optional configuration for custom model and vocabulary URLs
14
 * @returns Promise that resolves to UniversalSentenceEncoder instance
15
 */
16
function load(config?: LoadConfig): Promise<UniversalSentenceEncoder>;
17

18
interface LoadConfig {
19
  /** Custom URL for the model files (defaults to TFHub model) */
20
  modelUrl?: string;
21
  /** Custom URL for the vocabulary file (defaults to built-in vocab) */
22
  vocabUrl?: string;
23
}
24
```
25

26
**Usage Examples:**
27

28
```typescript
29
import * as use from '@tensorflow-models/universal-sentence-encoder';
30

31
// Load with default configuration
32
const model = await use.load();
33

34
// Load with custom model URL
35
const customModel = await use.load({
36
  modelUrl: 'https://example.com/my-custom-model',
37
  vocabUrl: 'https://example.com/my-vocab.json'
38
});
39
```
40

41
### Universal Sentence Encoder Class
42

43
Main class for generating text embeddings with 512-dimensional output vectors.
44

45
```typescript { .api }
46
class UniversalSentenceEncoder {
47
  /**
48
   * Load the TensorFlow.js GraphModel
49
   * @param modelUrl - Optional custom model URL
50
   * @returns Promise that resolves to the loaded GraphModel
51
   */
52
  loadModel(modelUrl?: string): Promise<tf.GraphModel>;
53
  
54
  /**
55
   * Initialize the model and tokenizer
56
   * @param config - Configuration object with optional URLs
57
   */
58
  load(config?: LoadConfig): Promise<void>;
59
  
60
  /**
61
   * Generate embeddings for input text(s)
62
   * Returns a 2D Tensor of shape [input.length, 512] containing embeddings
63
   * @param inputs - String or array of strings to embed
64
   * @returns Promise that resolves to 2D tensor with 512-dimensional embeddings
65
   */
66
  embed(inputs: string[] | string): Promise<tf.Tensor2D>;
67
}
68
```
69

70
**Usage Examples:**
71

72
```typescript
73
import * as use from '@tensorflow-models/universal-sentence-encoder';
74

75
// Basic embedding
76
const model = await use.load();
77
const embeddings = await model.embed('Hello world');
78
// Shape: [1, 512]
79

80
// Batch embedding
81
const sentences = [
82
  'I like my phone.',
83
  'Your cellphone looks great.',
84
  'How old are you?',
85
  'What is your age?'
86
];
87
const batchEmbeddings = await model.embed(sentences);
88
// Shape: [4, 512]
89

90
// Calculate similarity
91
const similarity = tf.matMul(
92
  batchEmbeddings.slice([0, 0], [1, 512]), // First sentence
93
  batchEmbeddings.slice([1, 0], [1, 512]), // Second sentence
94
  false, 
95
  true
96
);
97
console.log(await similarity.data()); // Similarity score
98
```
99

100
### Model Configuration
101

102
The standard USE model loads from TensorFlow Hub by default but supports custom configurations.
103

104
**Default URLs:**
105
- **Model**: `https://tfhub.dev/tensorflow/tfjs-model/universal-sentence-encoder-lite/1/default/1`
106
- **Vocabulary**: `https://storage.googleapis.com/tfjs-models/savedmodel/universal_sentence_encoder/vocab.json`
107

108
**Custom Configuration Example:**
109

110
```typescript
111
// Using custom model and vocabulary
112
const model = await use.load({
113
  modelUrl: 'https://my-server.com/custom-use-model',
114
  vocabUrl: 'https://my-server.com/custom-vocab.json'
115
});
116
```
117

118
## Types
119

120
```typescript { .api }
121
import * as tf from '@tensorflow/tfjs-core';
122
import * as tfconv from '@tensorflow/tfjs-converter';
123

124
interface LoadConfig {
125
  modelUrl?: string;
126
  vocabUrl?: string;
127
}
128

129
// Internal interface for model inputs
130
interface ModelInputs extends tf.NamedTensorMap {
131
  indices: tf.Tensor;
132
  values: tf.Tensor;
133
}
134
```