Skip to main content

​
Prerequisites

Install the Tracia SDK and the provider package(s) you need: 
npm install tracia ai @ai-sdk/openai
Set your API keys as environment variables:
.env
TRACIA_API_KEY=tr_your_tracia_key
OPENAI_API_KEY=sk-your-openai-key
GOOGLE_API_KEY=your_google_key
AWS_ACCESS_KEY_ID=your_aws_access_key
AWS_SECRET_ACCESS_KEY=your_aws_secret_key
AWS_REGION=us-east-1

​
Single Text Embedding

Pass a string to input to embed a single piece of text: 
import { Tracia } from 'tracia';

const tracia = new Tracia({ apiKey: process.env.TRACIA_API_KEY });

const result = await tracia.runEmbedding({
  model: 'text-embedding-3-small',
  input: 'What is the meaning of life?',
});

console.log(result.embeddings[0].values.length); // 1536
console.log(result.embeddings[0].index);          // 0
console.log(result.usage.totalTokens);            // 8

​
Batch Embedding

Pass an array of strings to embed multiple texts in a single request: 
const result = await tracia.runEmbedding({
  model: 'text-embedding-3-small',
  input: [
    'First document about TypeScript',
    'Second document about Python',
    'Third document about Rust',
  ],
});

console.log(result.embeddings.length); // 3

for (const embedding of result.embeddings) {
  console.log(`Index ${embedding.index}: ${embedding.values.length} dimensions`);
}
Batch embedding is more efficient than making separate requests for each text. The provider processes all inputs in a single API call.

​
Specifying Dimensions

Some models support reducing the embedding dimensions. This is useful for saving storage space or improving retrieval speed: 
// text-embedding-3-large defaults to 3072 dimensions
const fullResult = await tracia.runEmbedding({
  model: 'text-embedding-3-large',
  input: 'Hello world',
});
console.log(fullResult.embeddings[0].values.length); // 3072

// Reduce to 256 dimensions
const reducedResult = await tracia.runEmbedding({
  model: 'text-embedding-3-large',
  input: 'Hello world',
  dimensions: 256,
});
console.log(reducedResult.embeddings[0].values.length); // 256
Not all models support the dimensions parameter. Currently, OpenAI’s text-embedding-3-small and text-embedding-3-large, and Google’s text-embedding-004 support it.

​
Using with Sessions

Sessions automatically chain embedding spans with other spans under the same trace: 
const session = tracia.createSession();

// First: generate an embedding
const embeddingResult = await session.runEmbedding({
  model: 'text-embedding-3-small',
  input: 'What is quantum computing?',
});

// Second: use the embedding context in a completion
const completionResult = await session.runLocal({
  model: 'gpt-4o',
  messages: [
    { role: 'user', content: 'Explain the concept I just embedded.' },
  ],
});

// Both spans are linked under the same trace in the dashboard
console.log(session.getTraceId());
The session manages traceId and parentSpanId automatically, so all spans appear in sequence in the Tracia dashboard.

​
With Tracing Metadata

Add tags and user identifiers for filtering in the Tracia dashboard: 
const result = await tracia.runEmbedding({
  model: 'text-embedding-3-small',
  input: 'Document to embed for search',
  tags: ['production', 'search-index'],
  userId: 'user_abc123',
});

console.log(`Span ID: ${result.spanId}`);

​
Without Tracing

Disable tracing when you don’t need observability: 
const result = await tracia.runEmbedding({
  model: 'text-embedding-3-small',
  input: 'Just need the embedding, no trace',
  sendTrace: false,
});

​
Google Embeddings

const result = await tracia.runEmbedding({
  model: 'text-embedding-004',
  input: 'Embed with Google',
});

console.log(result.provider); // 'google'
console.log(result.embeddings[0].values.length); // 768

​
Amazon Bedrock Embeddings

const result = await tracia.runEmbedding({
  model: 'amazon.titan-embed-text-v2:0',
  input: 'Embed with Bedrock',
});

console.log(result.provider); // 'amazon_bedrock'

​
RunEmbeddingInput Reference

ParameterTypeRequiredDescription
inputstring | string[]YesText or array of texts to embed
modelstringYesEmbedding model name
providerLLMProviderNoProvider override (auto-detected from model)
providerApiKeystringNoProvider API key override
dimensionsnumberNoDimension override (model-dependent)
timeoutMsnumberNoRequest timeout in milliseconds
sendTracebooleanNoSend trace to Tracia (default: true)
spanIdstringNoCustom span ID (sp_ + 16 hex chars)
tagsstring[]NoTags for the span
userIdstringNoUser ID for the span
sessionIdstringNoSession ID for the span
traceIdstringNoGroup related spans together
parentSpanIdstringNoLink to a parent span

​
RunEmbeddingResult Reference

FieldTypeDescription
embeddingsEmbeddingVector[]Array of embedding vectors
spanIdstringUnique span ID for this request
traceIdstringTrace ID for grouping related spans
latencyMsnumberRequest latency in milliseconds
usageEmbeddingUsageToken usage (totalTokens)
costnumber | nullAlways null (cost is calculated server-side)
providerLLMProviderThe provider used
modelstringThe model used

​
EmbeddingVector

FieldTypeDescription
valuesnumber[]The embedding float values
indexnumberIndex of this embedding in the input array

​
EmbeddingUsage

FieldTypeDescription
totalTokensnumberTotal tokens consumed by the request