0
# TensorFlow.js Node
1

2
TensorFlow.js Node provides a native TensorFlow backend for Node.js applications, enabling high-performance machine learning operations using the full power of the native TensorFlow C++ library. It extends the browser-based TensorFlow.js API with Node.js-specific functionality including native tensor operations, file system model loading, image processing, and TensorBoard integration.
3

4
## Package Information
5

6
- **Package Name**: @tensorflow/tfjs-node
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @tensorflow/tfjs-node`
10

11
## Core Imports
12

13
ESM (TypeScript/Modern JavaScript):
14

15
```typescript
16
import * as tf from '@tensorflow/tfjs-node';
17
```
18

19
CommonJS:
20

21
```javascript
22
const tf = require('@tensorflow/tfjs-node');
23
```
24

25
For specific functionality:
26

27
```typescript
28
// Main TensorFlow.js functionality
29
import { tensor, sequential, layers } from '@tensorflow/tfjs-node';
30

31
// Node-specific functionality
32
import { node, io, version } from '@tensorflow/tfjs-node';
33
```
34

35
## Basic Usage
36

37
```typescript
38
import * as tf from '@tensorflow/tfjs-node';
39

40
// Create tensors and perform operations
41
const a = tf.tensor([[1, 2], [3, 4]]);
42
const b = tf.tensor([[5, 6], [7, 8]]);
43
const result = tf.matMul(a, b);
44

45
console.log('Matrix multiplication result:');
46
result.print();
47

48
// Create and train a model
49
const model = tf.sequential({
50
  layers: [
51
    tf.layers.dense({ inputShape: [2], units: 3, activation: 'relu' }),
52
    tf.layers.dense({ units: 1, activation: 'linear' })
53
  ]
54
});
55

56
model.compile({ optimizer: 'adam', loss: 'meanSquaredError' });
57

58
// Train with sample data
59
const xs = tf.tensor2d([[1, 2], [2, 3], [3, 4], [4, 5]]);
60
const ys = tf.tensor2d([[3], [5], [7], [9]]);
61

62
model.fit(xs, ys, { epochs: 100 }).then(() => {
63
  console.log('Model trained');
64
});
65
```
66

67
## Architecture
68

69
TensorFlow.js Node is built around several key components:
70

71
- **Core TensorFlow.js API**: Complete tensor operations, models, layers, optimizers, losses, and metrics from the browser version
72
- **Native Backend**: High-performance tensor operations using the TensorFlow C++ library 
73
- **Node.js Extensions**: File system access, HTTP loading, image processing, and server-specific functionality
74
- **Model Persistence**: Enhanced save/load capabilities using the file system
75
- **Training Tools**: Progress callbacks and TensorBoard integration for training visualization
76

77
## Capabilities
78

79
### Core TensorFlow.js API
80

81
All standard TensorFlow.js functionality including tensor operations, neural networks, and machine learning algorithms. This provides the same API as the browser version but with native performance.
82

83
```typescript { .api }
84
// Core tensor operations (examples)
85
function tensor(values: TensorLike, shape?: Shape, dtype?: DataType): Tensor;
86
function matMul(a: Tensor, b: Tensor, transposeA?: boolean, transposeB?: boolean): Tensor;
87
function sequential(config?: SequentialArgs): Sequential;
88

89
// Model creation and layers
90
const layers: {
91
  dense: (args: DenseLayerArgs) => Dense;
92
  conv2d: (args: Conv2DLayerArgs) => Conv2D;
93
  // ... hundreds of other operations and layers
94
};
95
```
96

97
*Note: Complete TensorFlow.js API documentation is available at https://js.tensorflow.org/api/latest/*
98

99
### Node-specific Image Processing
100

101
Decode and encode images directly to/from tensors using native implementations for optimal performance.
102

103
```typescript { .api }
104
namespace node {
105
  function decodeImage(contents: Uint8Array, channels?: number, dtype?: string, expandAnimations?: boolean): Tensor3D | Tensor4D;
106
  function decodeJpeg(contents: Uint8Array, channels?: number, ratio?: number, fancyUpscaling?: boolean, tryRecoverTruncated?: boolean, acceptableFraction?: number, dctMethod?: string): Tensor3D;
107
  function decodePng(contents: Uint8Array, channels?: number, dtype?: string): Tensor3D;
108
  function decodeBmp(contents: Uint8Array, channels?: number): Tensor3D;
109
  function decodeGif(contents: Uint8Array): Tensor4D;
110
  function encodeJpeg(image: Tensor3D, format?: ImageFormat, quality?: number, progressive?: boolean, optimizeSize?: boolean, chromaDownsampling?: boolean, densityUnit?: DensityUnit, xDensity?: number, yDensity?: number, xmpMetadata?: string): Promise<Uint8Array>;
111
  function encodePng(image: Tensor3D, compression?: number): Promise<Uint8Array>;
112
}
113

114
type ImageFormat = '' | 'grayscale' | 'rgb';
115
type DensityUnit = 'in' | 'cm';
116
```
117

118
[Image Processing](./image-processing.md)
119

120
### SavedModel Support
121

122
Load and run inference with TensorFlow SavedModels, enabling integration with models trained in Python TensorFlow.
123

124
```typescript { .api }
125
namespace node {
126
  function loadSavedModel(path: string, tags?: string[], signature?: string): Promise<TFSavedModel>;
127
  function getMetaGraphsFromSavedModel(path: string): Promise<MetaGraph[]>;
128
  function getNumOfSavedModels(): number;
129
}
130

131
interface TFSavedModel extends InferenceModel {
132
  inputs: ModelTensorInfo;
133
  outputs: ModelTensorInfo;
134
  predict(inputs: Tensor | Tensor[] | NamedTensorMap, config?: PredictConfig): Tensor | Tensor[] | NamedTensorMap;
135
  dispose(): void;
136
}
137
```
138

139
[SavedModel Support](./savedmodel.md)
140

141
### File System and HTTP Loading
142

143
Enhanced model loading and saving capabilities using the Node.js file system and HTTP requests.
144

145
```typescript { .api }
146
// Extended io namespace with Node.js capabilities
147
const io: {
148
  // All browser tf.io functionality plus:
149
  fileSystem: (path: string | string[]) => IOHandler;
150
  nodeHTTPRequest: (path: string, requestInit?: RequestInit, weightPathPrefix?: string) => IOHandler;
151
};
152
```
153

154
[File System and HTTP IO](./io.md)
155

156
### TensorBoard Integration
157

158
Log training metrics and visualize model performance using TensorBoard integration.
159

160
```typescript { .api }
161
namespace node {
162
  function tensorBoard(logdir?: string, args?: TensorBoardCallbackArgs): TensorBoardCallback;
163
  function summaryFileWriter(logdir: string, maxQueue?: number, flushMillis?: number, filenameSuffix?: string): SummaryFileWriter;
164
}
165

166
interface TensorBoardCallbackArgs {
167
  updateFreq?: 'batch' | 'epoch';
168
  histogramFreq?: number;
169
}
170

171
interface SummaryFileWriter {
172
  scalar(name: string, value: number, step: number, description?: string): void;
173
  histogram(name: string, data: Tensor, step: number, buckets?: number, description?: string): void;
174
  flush(): void;
175
}
176
```
177

178
[TensorBoard Integration](./tensorboard.md)
179

180
### Training Callbacks
181

182
Enhanced training experience with progress bars and logging callbacks.
183

184
```typescript { .api }
185
class ProgbarLogger extends CustomCallback {
186
  constructor();
187
}
188

189
class TensorBoardCallback extends CustomCallback {
190
  constructor(logdir?: string, updateFreq?: 'batch' | 'epoch', histogramFreq?: number);
191
}
192
```
193

194
[Training Callbacks](./callbacks.md)
195

196
## Version Information
197

198
```typescript { .api }
199
const version: {
200
  [key: string]: string;
201
  'tfjs-node': string;
202
  'tfjs-core': string;
203
  'tfjs-data': string;
204
  'tfjs-layers': string;
205
  'tfjs-converter': string;
206
};
207
```
208

209
## Common Types
210

211
```typescript { .api }
212
// Tensor types
213
type TensorLike = TypedArray | number | boolean | string | RecursiveArray<number | boolean | string>;
214
type Shape = number[];
215
type DataType = 'float32' | 'int32' | 'bool' | 'complex64' | 'string';
216

217
// Model types
218
interface InferenceModel {
219
  inputs: ModelTensorInfo;
220
  outputs: ModelTensorInfo;
221
  predict(inputs: Tensor | Tensor[] | NamedTensorMap, config?: PredictConfig): Tensor | Tensor[] | NamedTensorMap;
222
  dispose(): void;
223
}
224

225
interface IOHandler {
226
  load?(): Promise<ModelArtifacts>;
227
  save?(modelArtifacts: ModelArtifacts): Promise<SaveResult>;
228
}
229

230
// SavedModel types
231
interface MetaGraph {
232
  tags: string[];
233
  signatureDef: {[key: string]: SignatureDefEntry};
234
}
235

236
interface ModelTensorInfo {
237
  [inputName: string]: {
238
    name: string;
239
    shape: number[];
240
    dtype: string;
241
  };
242
}
243
```