FastEmbed Ruby

embedding = Fastembed::TextEmbedding.new
vectors = embedding.embed(["The quick brown fox", "jumps over the lazy dog"]).to_a

gem "fastembed"

gem "mini_magick"

require "fastembed"

# Create an embedding model (downloads ~67MB on first use)
embedding = Fastembed::TextEmbedding.new

# Embed some text
documents = [
  "Ruby is a dynamic programming language",
  "Python is great for data science",
  "JavaScript runs in the browser"
]
vectors = embedding.embed(documents).to_a

# Each vector is 384 floats (for the default model)
vectors.first.length  # => 384

embedding = Fastembed::TextEmbedding.new

# Your document corpus
documents = [
  "The cat sat on the mat",
  "Machine learning powers modern AI",
  "Ruby on Rails is a web framework",
  "Deep learning uses neural networks"
]
doc_vectors = embedding.embed(documents).to_a

# Search for a concept
query = "artificial intelligence and neural nets"
query_vector = embedding.embed([query]).first

# Find the most similar document (cosine similarity)
scores = doc_vectors.map { |v| query_vector.zip(v).sum { |a, b| a * b } }
best_idx = scores.each_with_index.max.last

puts documents[best_idx]  # => "Deep learning uses neural networks"

# With Qdrant
require "qdrant"

embedding = Fastembed::TextEmbedding.new
client = Qdrant::Client.new(url: "http://localhost:6333")

# Index documents
documents.each_with_index do |doc, i|
  vector = embedding.embed([doc]).first
  client.points.upsert(
    collection_name: "docs",
    points: [{ id: i, vector: vector, payload: { text: doc } }]
  )
end

# Search
query_vector = embedding.embed(["your search query"]).first
results = client.points.search(collection_name: "docs", vector: query_vector, limit: 5)

# Default: fast and accurate (384 dimensions, 67MB)
embedding = Fastembed::TextEmbedding.new

# Higher accuracy (768 dimensions, 210MB)
embedding = Fastembed::TextEmbedding.new(model_name: "BAAI/bge-base-en-v1.5")

# Multilingual - 100+ languages (384 dimensions)
embedding = Fastembed::TextEmbedding.new(model_name: "intfloat/multilingual-e5-small")

# Long documents - 8192 token context (768 dimensions)
embedding = Fastembed::TextEmbedding.new(model_name: "nomic-ai/nomic-embed-text-v1.5")

# For search queries
query_vectors = embedding.query_embed(["What is Ruby?"]).to_a

# For documents/passages
doc_vectors = embedding.passage_embed(documents).to_a

# Process millions of documents without loading all vectors into memory
File.foreach("documents.txt").lazy.each_slice(1000) do |batch|
  embedding.embed(batch).each do |vector|
    store_in_database(vector)
  end
end

reranker = Fastembed::TextCrossEncoder.new

query = "What is machine learning?"
documents = [
  "Machine learning is a branch of AI",
  "The weather is nice today",
  "Deep learning uses neural networks"
]

# Get raw scores (higher = more relevant)
scores = reranker.rerank(query: query, documents: documents)
# => [8.5, -10.2, 5.3]

# Get sorted results with metadata
results = reranker.rerank_with_scores(query: query, documents: documents, top_k: 2)
# => [
#   { document: "Machine learning is...", score: 8.5, index: 0 },
#   { document: "Deep learning uses...", score: 5.3, index: 2 }
# ]

sparse = Fastembed::TextSparseEmbedding.new

result = sparse.embed(["Ruby programming language"]).first
# => #<SparseEmbedding indices=[1234, 5678, ...] values=[0.8, 1.2, ...]>

result.indices  # vocabulary token IDs with non-zero weights
result.values   # corresponding weights
result.nnz      # number of non-zero elements

dense = Fastembed::TextEmbedding.new
sparse = Fastembed::TextSparseEmbedding.new

documents = ["your documents here"]

# Generate both types of embeddings
dense_vectors = dense.embed(documents).to_a
sparse_vectors = sparse.embed(documents).to_a

# Store both in your vector database and combine scores at query time

colbert = Fastembed::LateInteractionTextEmbedding.new

query = colbert.query_embed(["What is Ruby?"]).first
doc = colbert.embed(["Ruby is a programming language"]).first

# MaxSim scoring - sum of max similarities per query token
score = query.max_sim(doc)

# Requires mini_magick gem
image_embed = Fastembed::ImageEmbedding.new

# From file paths
vectors = image_embed.embed(["photo1.jpg", "photo2.png"]).to_a

# From URLs
vectors = image_embed.embed(["https://example.com/image.jpg"]).to_a

embedding = Fastembed::TextEmbedding.new

# Start async embedding
future = embedding.embed_async(large_document_list)

# Do other work...

# Get results when ready (blocks until complete)
vectors = future.value

# Process multiple batches concurrently
futures = documents.each_slice(1000).map do |batch|
  embedding.embed_async(batch)
end

# Wait for all and combine results
all_vectors = futures.flat_map(&:value)

future.complete?  # check if done
future.pending?   # check if still running
future.success?   # completed without error?
future.failure?   # completed with error?
future.error      # get the error if failed
future.wait(timeout: 5)  # wait up to 5 seconds

# Chaining
future.then { |vectors| vectors.map(&:first) }
      .rescue { |e| puts "Error: #{e}" }

# Wait for all futures
results = Fastembed::Async.all(futures)

# Get first completed result
result = Fastembed::Async.race(futures, timeout: 10)

embedding = Fastembed::TextEmbedding.new

documents = Array.new(10_000) { "document text" }

embedding.embed(documents, batch_size: 256) do |progress|
  puts "Batch #{progress.current}/#{progress.total}"
  puts "#{(progress.percentage * 100).round}% complete"
  puts "~#{progress.documents_processed} documents processed"
end.to_a

Fastembed.register_model(
  model_name: "my-org/my-model",
  dim: 768,
  description: "My custom model",
  sources: { hf: "my-org/my-model" },
  model_file: "onnx/model.onnx"
)

# Now use it like any other model
embedding = Fastembed::TextEmbedding.new(model_name: "my-org/my-model")

embedding = Fastembed::TextEmbedding.new(
  local_model_dir: "/path/to/model",
  model_file: "model.onnx",
  tokenizer_file: "tokenizer.json"
)

Fastembed::TextEmbedding.new(
  model_name: "BAAI/bge-small-en-v1.5",  # model to use
  cache_dir: "~/.cache/fastembed",        # where to store models
  threads: 4,                              # ONNX Runtime threads
  providers: ["CUDAExecutionProvider"],    # GPU acceleration
  show_progress: true,                     # show download progress
  quantization: :q4                        # use quantized model
)

# Available: :fp32 (default), :fp16, :int8, :uint8, :q4
embedding = Fastembed::TextEmbedding.new(quantization: :int8)

# CUDA (Linux/Windows with NVIDIA GPU)
embedding = Fastembed::TextEmbedding.new(
  providers: ["CUDAExecutionProvider", "CPUExecutionProvider"]
)

# CoreML (macOS)
embedding = Fastembed::TextEmbedding.new(
  providers: ["CoreMLExecutionProvider", "CPUExecutionProvider"]
)