Table of Contents

Class SiameseNeuralNetwork<T>

Namespace
AiDotNet.NeuralNetworks
Assembly
AiDotNet.dll

Siamese Neural Network implementation for dual-encoder comparison and similarity learning.

public class SiameseNeuralNetwork<T> : NeuralNetworkBase<T>, INeuralNetworkModel<T>, INeuralNetwork<T>, IFullModel<T, Tensor<T>, Tensor<T>>, IModel<Tensor<T>, Tensor<T>, ModelMetadata<T>>, IModelSerializer, ICheckpointableModel, IParameterizable<T, Tensor<T>, Tensor<T>>, IFeatureAware, IFeatureImportance<T>, ICloneable<IFullModel<T, Tensor<T>, Tensor<T>>>, IGradientComputable<T, Tensor<T>, Tensor<T>>, IJitCompilable<T>, IInterpretableModel<T>, IInputGradientComputable<T>, IDisposable, IEmbeddingModel<T>

Type Parameters

T

The numeric type used for calculations (typically float or double).

Inheritance
SiameseNeuralNetwork<T>
Implements
IFullModel<T, Tensor<T>, Tensor<T>>
IModel<Tensor<T>, Tensor<T>, ModelMetadata<T>>
IParameterizable<T, Tensor<T>, Tensor<T>>
ICloneable<IFullModel<T, Tensor<T>, Tensor<T>>>
IGradientComputable<T, Tensor<T>, Tensor<T>>
Inherited Members
Extension Methods

Remarks

A Siamese Neural Network consists of two identical subnetworks (sharing the same parameters) that process two different inputs. The outputs are typically compared using a distance metric and optimized via contrastive or triplet loss.

For Beginners: A Siamese Network is like having two identical twins who think exactly the same way. You give a different photo to each twin, and they each describe what they see using a list of numbers. Because the twins think the same way, if the photos are similar, their descriptions will be almost identical. This is the most popular way to build face recognition or "find similar" search systems.

Constructors

SiameseNeuralNetwork(NeuralNetworkArchitecture<T>, ITokenizer?, IGradientBasedOptimizer<T, Tensor<T>, Tensor<T>>?, int, int, int, ILossFunction<T>?, double)

Initializes a new instance of the SiameseNeuralNetwork model.

public SiameseNeuralNetwork(NeuralNetworkArchitecture<T> architecture, ITokenizer? tokenizer = null, IGradientBasedOptimizer<T, Tensor<T>, Tensor<T>>? optimizer = null, int vocabSize = 30522, int embeddingDimension = 768, int maxSequenceLength = 512, ILossFunction<T>? lossFunction = null, double maxGradNorm = 1)

Parameters

architecture NeuralNetworkArchitecture<T>

The configuration defining the model's structural metadata.

tokenizer ITokenizer

Optional tokenizer for text processing.

optimizer IGradientBasedOptimizer<T, Tensor<T>, Tensor<T>>

Optional optimizer for training.

vocabSize int

The size of the shared vocabulary (default: 30522).

embeddingDimension int

The dimension of the shared embeddings (default: 768).

maxSequenceLength int

The maximum allowed input length (default: 512).

lossFunction ILossFunction<T>

Optional loss function. Defaults to Contrastive Loss.

maxGradNorm double

Maximum gradient norm for stability (default: 1.0).

Properties

EmbeddingDimension

Gets the dimensionality of the embedding vectors produced by this model.

public int EmbeddingDimension { get; }

Property Value

int

Remarks

The embedding dimension determines the size of the vector representation. Common dimensions range from 128 to 1536, with larger dimensions typically capturing more nuanced semantic relationships at the cost of memory and computation.

For Beginners: This is how many numbers represent each piece of text.

Think of it like describing a person:

  • Low dimension (128): Basic traits like height, weight, age
  • High dimension (768): Detailed description including personality, preferences, habits
  • Very high dimension (1536): Extremely detailed profile

More dimensions = more detailed understanding, but also more storage space needed.

MaxTokens

Gets the maximum length of text (in tokens) that this model can process.

public int MaxTokens { get; }

Property Value

int

Remarks

Most embedding models have a maximum context length beyond which text must be truncated. Common limits range from 512 to 8192 tokens. Implementations should handle text exceeding this limit gracefully, either by truncation or raising an exception.

For Beginners: This is the maximum amount of text the model can understand at once.

Think of it like a reader's attention span:

  • Short span (512 tokens): Can read about a paragraph
  • Medium span (2048 tokens): Can read a few pages
  • Long span (8192 tokens): Can read a short chapter

If your text is longer, it needs to be split into chunks. (A token is roughly a word, so 512 tokens ≈ 1-2 paragraphs)

Methods

Backward(Tensor<T>)

Propagates error signal backward through the shared encoder layers.

public Tensor<T> Backward(Tensor<T> outputGradient)

Parameters

outputGradient Tensor<T>

Returns

Tensor<T>

CreateNewInstance()

Creates a new instance of the same type as this neural network.

protected override IFullModel<T, Tensor<T>, Tensor<T>> CreateNewInstance()

Returns

IFullModel<T, Tensor<T>, Tensor<T>>

A new instance of the same neural network type.

Remarks

For Beginners: This creates a blank version of the same type of neural network.

It's used internally by methods like DeepCopy and Clone to create the right type of network before copying the data into it.

DeserializeNetworkSpecificData(BinaryReader)

Deserializes network-specific data that was not covered by the general deserialization process.

protected override void DeserializeNetworkSpecificData(BinaryReader reader)

Parameters

reader BinaryReader

The BinaryReader to read the data from.

Remarks

This method is called at the end of the general deserialization process to allow derived classes to read any additional data specific to their implementation.

For Beginners: Continuing the suitcase analogy, this is like unpacking that special compartment. After the main deserialization method has unpacked the common items (layers, parameters), this method allows each specific type of neural network to unpack its own unique items that were stored during serialization.

Embed(string)

Encodes a single string into a normalized embedding vector using the shared encoder brain.

public Vector<T> Embed(string text)

Parameters

text string

Returns

Vector<T>

EmbedAsync(string)

Asynchronously encodes a single string into a normalized embedding vector.

public Task<Vector<T>> EmbedAsync(string text)

Parameters

text string

Returns

Task<Vector<T>>

EmbedBatch(IEnumerable<string>)

Encodes a batch of strings into a matrix of embedding vectors.

public Matrix<T> EmbedBatch(IEnumerable<string> texts)

Parameters

texts IEnumerable<string>

Returns

Matrix<T>

EmbedBatchAsync(IEnumerable<string>)

Asynchronously encodes a batch of strings into a matrix of embedding vectors.

public Task<Matrix<T>> EmbedBatchAsync(IEnumerable<string> texts)

Parameters

texts IEnumerable<string>

Returns

Task<Matrix<T>>

Forward(Tensor<T>)

Performs a forward pass through the shared encoder.

public Tensor<T> Forward(Tensor<T> input)

Parameters

input Tensor<T>

Returns

Tensor<T>

GetModelMetadata()

Retrieves metadata about the Siamese dual-encoder model.

public override ModelMetadata<T> GetModelMetadata()

Returns

ModelMetadata<T>

InitializeLayers()

Sets up the shared encoder layers for the Siamese twins using defaults from LayerHelper.

protected override void InitializeLayers()

Remarks

For Beginners: This method builds the "twin's brain." It sets up a transformer encoder that is shared by both sides of the network to ensure that identical inputs always produce identical results.

Predict(Tensor<T>)

Makes a prediction using the neural network.

public override Tensor<T> Predict(Tensor<T> input)

Parameters

input Tensor<T>

The input data to process.

Returns

Tensor<T>

The network's prediction.

Remarks

For Beginners: This is the main method you'll use to get results from your trained neural network. You provide some input data (like an image or text), and the network processes it through all its layers to produce an output (like a classification or prediction).

SerializeNetworkSpecificData(BinaryWriter)

Serializes network-specific data that is not covered by the general serialization process.

protected override void SerializeNetworkSpecificData(BinaryWriter writer)

Parameters

writer BinaryWriter

The BinaryWriter to write the data to.

Remarks

This method is called at the end of the general serialization process to allow derived classes to write any additional data specific to their implementation.

For Beginners: Think of this as packing a special compartment in your suitcase. While the main serialization method packs the common items (layers, parameters), this method allows each specific type of neural network to pack its own unique items that other networks might not have.

Train(Tensor<T>, Tensor<T>)

Trains the model on pairs of inputs using a similarity learning objective.

public override void Train(Tensor<T> input, Tensor<T> expectedOutput)

Parameters

input Tensor<T>

The input tensor containing a pair of sequences [2, seq_len].

expectedOutput Tensor<T>

The target similarity label (1 for same, 0 for different) as a tensor of [1].

Remarks

For Beginners: This is where the twins learn. You show one twin the first input and the other twin the second input. You then tell them if the inputs are the same or different (the label). They adjust their shared brain to make similar inputs have nearly identical coordinate summaries.

UpdateParameters(Vector<T>)

Updates the shared parameters of the dual encoders.

public override void UpdateParameters(Vector<T> parameters)

Parameters

parameters Vector<T>
Edit this page