Package org.mockserver.llm.codec

Class EmbeddingVectors

java.lang.Object

org.mockserver.llm.codec.EmbeddingVectors

public final class EmbeddingVectors
extends Object

Shared, deterministic embedding-vector generation used by every provider embedding codec (OpenAI, Gemini, Ollama, Bedrock Titan/Cohere).

The vector is either reproducibly derived from the input text + seed + dimensions (when EmbeddingResponse.getDeterministicFromInput() is true and an input is present) or random, then L2-normalised so it behaves like a real embedding (unit length, cosine-comparable). Provider codecs only differ in the JSON envelope they wrap this vector in.

The deterministic vector is produced by n-gram feature hashing (a.k.a. the "hashing trick"): the input is tokenised into word unigrams, word bigrams, and character n-grams; each feature is hashed into one of dimensions buckets with a signed contribution (to reduce collision bias) weighted by a sublinear term frequency; the accumulated vector is then L2-normalised. Two texts that share vocabulary / n-grams land in overlapping buckets and therefore have a higher cosine similarity, while unrelated texts are near-orthogonal — so the vector is both deterministic (same input+seed+dimensions ⇒ same vector) and semantically plausible, which lets offline RAG / vector-search code rank related documents above unrelated ones without calling a real embedding model.

Method Summary

Modifier and Type	Method	Description
static int	approximateTokens(String input)	Approximate the prompt token count from the input length, matching the convention used by the chat codecs (~4 chars per token).
static double[]	build(EmbeddingResponse embedding, String input, int defaultDimensions)	Build the embedding vector for an EmbeddingResponse and input, applying the determinism flag, seed, and default dimensions, then L2-normalising the result.
static double[]	generateDeterministicVector(String input, int dimensions, long seed)	Produce a deterministic, semantically-plausible (un-normalised) vector from the input text via n-gram feature hashing.
static double[]	generateRandomVector(int dimensions)
static void	normalizeL2(double[] vector)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

build

public static double[] build(EmbeddingResponse embedding,
 String input,
 int defaultDimensions)

Build the embedding vector for an EmbeddingResponse and input, applying the determinism flag, seed, and default dimensions, then L2-normalising the result.

Parameters:

embedding - the configured embedding response

input - the request input text (may be null)

defaultDimensions - provider-specific default when no dimensions are configured

Returns:

an L2-normalised vector

generateDeterministicVector

public static double[] generateDeterministicVector(String input,
 int dimensions,
 long seed)

Produce a deterministic, semantically-plausible (un-normalised) vector from the input text via n-gram feature hashing. The same input, dimensions, and seed always yield the same vector; texts sharing vocabulary / n-grams accumulate into overlapping buckets and so have a higher cosine similarity.

generateRandomVector

public static double[] generateRandomVector(int dimensions)

normalizeL2

public static void normalizeL2(double[] vector)

approximateTokens

public static int approximateTokens(String input)

Approximate the prompt token count from the input length, matching the convention used by the chat codecs (~4 chars per token).