Embedding Basics

Overview

Embeddings are numerical representations of text that capture semantic meaning. LlmTornado provides comprehensive embedding capabilities across multiple AI providers including OpenAI, Google, Cohere, Mistral, and Voyage. Embeddings are essential for semantic search, similarity comparisons, clustering, and building advanced AI applications like RAG (Retrieval-Augmented Generation) systems.

Quick Start

Here's a simple embedding example:

csharp

using LlmTornado;
using LlmTornado.Embedding;
using LlmTornado.Embedding.Models;

TornadoApi api = new TornadoApi("your-api-key");

// Create an embedding
EmbeddingResult? result = await api.Embeddings.CreateEmbedding(
    EmbeddingModel.OpenAi.Gen2.Ada, 
    "lorem ipsum");

float[]? embedding = result?.Data.FirstOrDefault()?.Embedding;

if (embedding is not null)
{
    Console.WriteLine($"Embedding dimension: {embedding.Length}");
    Console.WriteLine($"First 10 values: {string.Join(", ", embedding.Take(10))}");
}

Prerequisites

Before using embeddings, ensure you have:

The LlmTornado package installed
A valid API key with embeddings access
Understanding of vector operations (for advanced usage)
Basic knowledge of semantic search concepts

Detailed Explanation

What Are Embeddings?

Embeddings convert text into high-dimensional vectors (arrays of numbers) that represent the semantic meaning of the text. Similar texts have similar embeddings, making them useful for:

Semantic Search - Find relevant documents based on meaning, not just keywords
Similarity Comparison - Measure how similar two pieces of text are
Classification - Group texts by semantic similarity
Recommendation Systems - Find related content
RAG Systems - Build retrieval-augmented generation applications

Embedding Models

LlmTornado supports multiple embedding providers:

OpenAI

text-embedding-ada-002 - General-purpose, cost-effective (1536 dimensions)
text-embedding-3-small - Smaller, faster (512-1536 dimensions)
text-embedding-3-large - Highest quality (256-3072 dimensions)

Google

text-embedding-004 - Latest Google embedding model
text-embedding-gecko-001 - Gemini-based embedding

Cohere

embed-multilingual-v3.0 - Multilingual support (1024 dimensions)
embed-english-v4.0 - Latest English model

Mistral

mistral-embed - Mistral's embedding model
codestral-embed - Code-specialized embeddings (512 dimensions configurable)

Voyage AI

voyage-3.5 - High-quality embeddings with customization

Embedding Dimensions

Different models produce different embedding sizes:

Larger dimensions → More information but slower
Smaller dimensions → Faster but less detailed
Some models allow custom dimension sizes

Basic Usage

Simple Text Embedding

csharp

EmbeddingResult? result = await api.Embeddings.CreateEmbedding(
    EmbeddingModel.OpenAi.Gen2.Ada, 
    "lorem ipsum");

float[]? data = result?.Data.FirstOrDefault()?.Embedding;

if (data is not null)
{
    for (int i = 0; i < Math.Min(data.Length, 10); i++)
    {
        Console.WriteLine(data[i]);
    }
    
    Console.WriteLine($"... (length: {data.Length})");
}

Multiple Text Embeddings

Embed multiple texts in one request:

csharp

EmbeddingResult? result = await api.Embeddings.CreateEmbedding(
    EmbeddingModel.OpenAi.Gen2.Ada, 
    [ "how are you", "how are you doing" ]);

if (result is not null)
{
    Console.WriteLine($"Generated {result.Data.Count} embeddings");
    
    foreach (EmbeddingEntry entry in result.Data)
    {
        Console.WriteLine($"Embedding dimension: {entry.Embedding.Length}");
    }
}

Using Different Providers

csharp

// OpenAI
EmbeddingResult? openAiResult = await api.Embeddings.CreateEmbedding(
    EmbeddingModel.OpenAi.Gen2.Ada, 
    "lorem ipsum");

// Google
EmbeddingResult? googleResult = await api.Embeddings.CreateEmbedding(
    EmbeddingModel.Google.Gemini.Embedding4, 
    "lorem ipsum");

// Cohere
EmbeddingResult? cohereResult = await api.Embeddings.CreateEmbedding(
    EmbeddingModel.Cohere.Gen3.Multilingual, 
    "lorem ipsum");

Advanced Usage

Custom Dimensions with Mistral

csharp

EmbeddingResult? result = await api.Embeddings.CreateEmbedding(new EmbeddingRequest
{
    Model = EmbeddingModel.Mistral.Premier.CodestralEmbed,
    InputScalar = "<div>hello world</div>",
    Dimensions = 512,
    OutputDType = EmbeddingOutputDtypes.Int8
});

float[]? data = result?.Data.FirstOrDefault()?.Embedding;

if (data is not null)
{
    Console.WriteLine($"Custom dimension embedding: {data.Length}");
}

Google Extensions

Use Google-specific features for better results:

csharp

EmbeddingResult? result = await api.Embeddings.CreateEmbedding(
    new EmbeddingRequest(
        EmbeddingModel.Google.Gemini.Embedding4, 
        "This is content of a document")
    {
        VendorExtensions = new EmbeddingRequestVendorExtensions(
            new EmbeddingRequestVendorGoogleExtensions
            {
                TaskType = EmbeddingRequestVendorGoogleExtensionsTaskTypes.RetrievalDocument,
                Title = "My document 1"
            })
    });

float[]? data = result?.Data.FirstOrDefault()?.Embedding;
Console.WriteLine($"Document embedding: {data?.Length}");

Voyage AI Extensions

Customize Voyage embeddings with input types:

csharp

EmbeddingResult? result = await api.Embeddings.CreateEmbedding(
    EmbeddingModel.Voyage.Gen35.Default, 
    "lorem ipsum", 
    256, 
    new EmbeddingRequestVendorExtensions
    {
        Voyage = new EmbeddingRequestVendorVoyageExtensions
        {
            OutputDtype = EmbeddingOutputDtypes.Uint8,
            InputType = EmbeddingVendorVoyageInputTypes.Document
        }
    });

float[]? data = result?.Data.FirstOrDefault()?.Embedding;
Console.WriteLine($"Voyage embedding with custom settings: {data?.Length}");

Cohere Extensions

Optimize Cohere embeddings for specific use cases:

csharp

// For search documents
EmbeddingResult? docResult = await api.Embeddings.CreateEmbedding(
    EmbeddingModel.Cohere.Gen3.Multilingual, 
    "lorem ipsum", 
    new EmbeddingRequestVendorExtensions
    {
        Cohere = new EmbeddingRequestVendorCohereExtensions
        {
            InputType = EmbeddingVendorCohereExtensionInputTypes.SearchDocument,
            Truncate = EmbeddingVendorCohereExtensionTruncation.End
        }
    });

// For search queries
EmbeddingResult? queryResult = await api.Embeddings.CreateEmbedding(
    EmbeddingModel.Cohere.Gen3.Multilingual, 
    "search query", 
    new EmbeddingRequestVendorExtensions
    {
        Cohere = new EmbeddingRequestVendorCohereExtensions
        {
            InputType = EmbeddingVendorCohereExtensionInputTypes.SearchQuery,
            Truncate = EmbeddingVendorCohereExtensionTruncation.End
        }
    });

Batch Processing

Process multiple texts efficiently:

csharp

string[] texts = [
    "First document about artificial intelligence",
    "Second document about machine learning",
    "Third document about neural networks"
];

EmbeddingResult? result = await api.Embeddings.CreateEmbedding(
    EmbeddingModel.Google.Gemini.Embedding4, 
    texts);

if (result is not null)
{
    for (int i = 0; i < result.Data.Count; i++)
    {
        Console.WriteLine($"Text {i + 1} embedding dimension: {result.Data[i].Embedding.Length}");
    }
}

Cosine Similarity

Calculate similarity between embeddings:

csharp

float CosineSimilarity(float[] embedding1, float[] embedding2)
{
    if (embedding1.Length != embedding2.Length)
        throw new ArgumentException("Embeddings must have same dimensions");
    
    float dotProduct = 0;
    float norm1 = 0;
    float norm2 = 0;
    
    for (int i = 0; i < embedding1.Length; i++)
    {
        dotProduct += embedding1[i] * embedding2[i];
        norm1 += embedding1[i] * embedding1[i];
        norm2 += embedding2[i] * embedding2[i];
    }
    
    return dotProduct / (float)(Math.Sqrt(norm1) * Math.Sqrt(norm2));
}

// Usage
EmbeddingResult? result1 = await api.Embeddings.CreateEmbedding(
    EmbeddingModel.OpenAi.Gen2.Ada, 
    "artificial intelligence");

EmbeddingResult? result2 = await api.Embeddings.CreateEmbedding(
    EmbeddingModel.OpenAi.Gen2.Ada, 
    "machine learning");

float similarity = CosineSimilarity(
    result1.Data[0].Embedding, 
    result2.Data[0].Embedding);

Console.WriteLine($"Similarity: {similarity:F4}");

Best Practices

1. Choose the Right Model

Use OpenAI Ada for general-purpose tasks
Use Cohere for multilingual content
Use Mistral Codestral for code embeddings
Use Google for integration with Gemini ecosystem

2. Optimize for Performance

Batch multiple texts when possible
Cache embeddings to avoid redundant API calls
Use appropriate dimensions (smaller = faster)
Store embeddings in vector databases

3. Handle Input Text

Preprocess text (remove extra whitespace, normalize)
Split long texts into chunks if needed
Use appropriate input types (document vs query)
Consider text length limits for each model

4. Manage Costs

Batch requests to reduce API calls
Cache frequently used embeddings
Use smaller dimension models when appropriate
Monitor usage and set limits

5. Vector Storage

Store embeddings in vector databases (Chroma, Pinecone, etc.)
Index embeddings for fast retrieval
Implement efficient similarity search
Consider compression for storage

Common Issues

Dimension Mismatch

Issue: Embeddings have different dimensions
Solution: Ensure all embeddings use the same model
Prevention: Standardize on one model per use case

Out of Memory

Issue: Large batch of embeddings crashes
Solution: Process in smaller batches
Prevention: Implement chunking for large datasets

Slow Performance

Issue: Embedding generation is too slow
Solution: Use smaller models or batch processing
Prevention: Profile and optimize batch sizes

Poor Similarity Results

Issue: Similar texts have low similarity scores
Solution: Try different models or preprocessing
Prevention: Test models with your specific content

API Reference

EmbeddingRequest

EmbeddingModel Model - Model to use for embeddings
string InputScalar - Single text to embed
List<string> Input - Multiple texts to embed
int? Dimensions - Custom dimension size (if supported)
EmbeddingOutputDtypes? OutputDType - Output data type
EmbeddingRequestVendorExtensions VendorExtensions - Provider-specific options

EmbeddingResult

List<EmbeddingEntry> Data - Embedding data entries
string Model - Model used
Usage Usage - Token usage information

EmbeddingEntry

float[] Embedding - The embedding vector
int Index - Index in the batch
string Object - Object type

EmbeddingModel

OpenAi.Gen2.Ada - OpenAI Ada model
OpenAi.Gen3.Small - OpenAI 3 Small
OpenAi.Gen3.Large - OpenAI 3 Large
Google.Gemini.Embedding4 - Google Embedding 4
Cohere.Gen3.Multilingual - Cohere Multilingual v3
Cohere.Gen4.V4 - Cohere v4
Mistral.Premier.CodestralEmbed - Mistral Codestral
Voyage.Gen35.Default - Voyage 3.5

Vector Databases - Store and search embeddings
Chat Basics - Using embeddings with chat
Rerank - Improve search results
Agents - Building RAG systems

Embedding Basics ​

Overview ​

Quick Start ​

Prerequisites ​

Detailed Explanation ​

What Are Embeddings? ​

Embedding Models ​

OpenAI ​

Google ​

Cohere ​

Mistral ​

Voyage AI ​

Embedding Dimensions ​

Basic Usage ​

Simple Text Embedding ​

Multiple Text Embeddings ​

Using Different Providers ​

Advanced Usage ​

Custom Dimensions with Mistral ​

Google Extensions ​

Voyage AI Extensions ​

Cohere Extensions ​

Batch Processing ​

Cosine Similarity ​

Best Practices ​

1. Choose the Right Model ​

2. Optimize for Performance ​

3. Handle Input Text ​

4. Manage Costs ​

5. Vector Storage ​

Common Issues ​

Dimension Mismatch ​

Out of Memory ​

Slow Performance ​

Poor Similarity Results ​

API Reference ​

EmbeddingRequest ​

EmbeddingResult ​

EmbeddingEntry ​

EmbeddingModel ​

Related Topics ​

Embedding Basics

Overview

Quick Start

Prerequisites

Detailed Explanation

What Are Embeddings?

Embedding Models

OpenAI

Google

Cohere

Mistral

Voyage AI

Embedding Dimensions

Basic Usage

Simple Text Embedding

Multiple Text Embeddings

Using Different Providers

Advanced Usage

Custom Dimensions with Mistral

Google Extensions

Voyage AI Extensions

Cohere Extensions

Batch Processing

Cosine Similarity

Best Practices

1. Choose the Right Model

2. Optimize for Performance

3. Handle Input Text

4. Manage Costs

5. Vector Storage

Common Issues

Dimension Mismatch

Out of Memory

Slow Performance

Poor Similarity Results

API Reference

EmbeddingRequest

EmbeddingResult

EmbeddingEntry

EmbeddingModel

Related Topics