Module: RubyLLM::Voyage

Defined in:
lib/ruby_llm/voyage.rb,
lib/ruby_llm/voyage/results.rb,
lib/ruby_llm/voyage/version.rb,
lib/ruby_llm/voyage/vector_decoder.rb

Overview

Voyage retrieval integration for RubyLLM.

Use Voyage.embed_query and Voyage.embed_documents for the two sides of retrieval, Voyage.embed for request-level Voyage options, or the conventional RubyLLM.embed(..., provider: :voyage) interface.

Defined Under Namespace

Modules: VectorDecoder Classes: ContextualizedChunk, ContextualizedEmbedding, ContextualizedResult, FileDeletion, Page, RerankResult, Reranking, VoyageFile

Constant Summary collapse

VERSION =

Current gem version.

'0.1.0'
UNSET =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

Internal sentinel used to distinguish an omitted option from an explicit nil value.

Object.new.freeze

Class Method Summary collapse

Class Method Details

.contextualized_embed(inputs, model: 'voyage-context-4', input_type: UNSET, dimensions: nil, output_dtype: UNSET, encoding_format: UNSET, auto_chunk: nil, chunk_size: nil, chunk_overlap: nil, provider_options: {}, context: nil) ⇒ RubyLLM::Voyage::ContextualizedEmbedding

Generates context-aware embeddings for grouped document chunks.

Parameters:

  • inputs (Array<String>, Array<Array<String>>)
  • model (String) (defaults to: 'voyage-context-4')
  • input_type (String, Symbol, nil) (defaults to: UNSET)
  • dimensions (Integer, nil) (defaults to: nil) —

    defaults to config.voyage_default_output_dimension

  • output_dtype (String, Symbol, nil) (defaults to: UNSET)
  • encoding_format (String, Symbol, nil) (defaults to: UNSET)
  • auto_chunk (Boolean, nil) (defaults to: nil)
  • chunk_size (Integer, nil) (defaults to: nil)
  • chunk_overlap (Integer, nil) (defaults to: nil)
  • provider_options (Hash) (defaults to: {})
  • context (RubyLLM::Context, nil) (defaults to: nil)

Returns:



156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
 
# File 'lib/ruby_llm/voyage.rb', line 156

def self.contextualized_embed(inputs, model: 'voyage-context-4', input_type: UNSET, dimensions: nil,
                              output_dtype: UNSET, encoding_format: UNSET, auto_chunk: nil, chunk_size: nil,
                              chunk_overlap: nil, provider_options: {}, context: nil)
  validate_input!(:inputs, inputs)
  config = context&.config || RubyLLM.config
  provider = Providers::Voyage.new(config)
  payload = { model: model, input_count: inputs.length, input_type: input_type, auto_chunk: auto_chunk }
            .reject { |_key, value| value.equal?(UNSET) }
  RubyLLM.instrument('contextualized_embedding.voyage', payload, config:) do |event|
    result = provider.contextualized_embed(
      inputs, model:, input_type:, dimensions:, output_dtype:, encoding_format:, auto_chunk:, chunk_size:,
              chunk_overlap:, provider_options:
    )
    event[:result] = result
    event[:response_model] = result.model
    event[:input_tokens] = result.input_tokens
    result
  end
end

.delete_files(file_ids, context: nil) ⇒ RubyLLM::Voyage::FileDeletion

Deletes one or more Voyage files atomically.

Parameters:

  • file_ids (Array<String>)
  • context (RubyLLM::Context, nil) (defaults to: nil)

Returns:



216
217
218
 
# File 'lib/ruby_llm/voyage.rb', line 216

def self.delete_files(file_ids, context: nil)
  provider_for(context).delete_files(file_ids)
end

.embed(text, model: nil, dimensions: nil, input_type: UNSET, truncation: UNSET, output_dtype: UNSET, encoding_format: UNSET, provider_options: {}, context: nil) ⇒ RubyLLM::Embedding

Generates embeddings with a Voyage text embedding model.

This facade exposes Voyage-specific options that are not first-class keywords on RubyLLM.embed in RubyLLM 1.x. It returns the same Embedding result type and emits the same instrumentation event.

Examples:

Embed a retrieval query

embedding = RubyLLM::Voyage.embed(
  "How do I configure SSO?",
  model: "voyage-4-lite",
  input_type: :query,
  dimensions: 512
)
embedding.vectors #=> Array<Float>

Parameters:

  • text (String, Array<String>) —

    one input or a batch of inputs

  • model (String, nil) (defaults to: nil) —

    Voyage model ID, such as voyage-4-lite; defaults to config.default_embedding_model

  • dimensions (Integer, nil) (defaults to: nil) —

    requested output dimensions; defaults to config.voyage_default_output_dimension

  • input_type (String, Symbol, nil) (defaults to: UNSET) —

    query, document, or nil

  • truncation (Boolean, nil) (defaults to: UNSET) —

    whether Voyage may truncate long inputs

  • output_dtype (String, Symbol, nil) (defaults to: UNSET) —

    float, int8, uint8, binary, ubinary, or nil

  • encoding_format (String, Symbol, nil) (defaults to: UNSET) —

    base64 or nil

  • provider_options (Hash) (defaults to: {}) —

    trusted fields merged into the Voyage request after named options

  • context (RubyLLM::Context, nil) (defaults to: nil) —

    isolated RubyLLM configuration

Returns:

  • (RubyLLM::Embedding) —

    vectors, model ID, and input-token usage

Raises:

  • (RubyLLM::ConfigurationError) —

    when the Voyage API key is missing

  • (RubyLLM::Error) —

    when Voyage returns an unsuccessful response



45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
 
# File 'lib/ruby_llm/voyage.rb', line 45

def self.embed(text, model: nil, dimensions: nil, input_type: UNSET, truncation: UNSET, output_dtype: UNSET,
               encoding_format: UNSET, provider_options: {}, context: nil)
  validate_input!(:text, text)
  config = context&.config || RubyLLM.config
  model ||= config.default_embedding_model
  provider = Providers::Voyage.new(config)
  payload = {
    provider: provider.slug,
    model: model,
    input: text,
    dimensions: dimensions,
    input_type: input_type,
    truncation: truncation,
    output_dtype: output_dtype,
    encoding_format: encoding_format
  }.reject { |_key, value| value.equal?(UNSET) }

  RubyLLM.instrument('embedding.ruby_llm', payload, config:) do |event|
    result = provider.embed(
      text,
      model:,
      dimensions:,
      input_type:,
      truncation:,
      output_dtype:,
      encoding_format:,
      provider_options:
    )
    event[:result] = result
    event[:response_model] = result.model
    event[:input_tokens] = result.input_tokens
    result
  end
end

.embed_documents(texts, **options) ⇒ RubyLLM::Embedding

Embeds content for the document side of retrieval.

Equivalent to embed with input_type: 'document'. Accepts one text or a batch of up to 1,000.

Examples:

RubyLLM::Voyage.embed_documents(articles.map(&:content)).vectors

Parameters:

  • texts (String, Array<String>) —

    content to index

  • options (Hash) —

    the same options as embed, except input_type

Returns:

  • (RubyLLM::Embedding)

Raises:

  • (ArgumentError) —

    when input_type is passed



110
111
112
 
# File 'lib/ruby_llm/voyage.rb', line 110

def self.embed_documents(texts, **options)
  embed_side(texts, 'document', __method__, options)
end

.embed_query(text, **options) ⇒ RubyLLM::Embedding

Embeds search text for the query side of retrieval.

Equivalent to embed with input_type: 'query'. Pair with embed_documents so Voyage optimizes both sides of retrieval, and configure default_embedding_model and voyage_default_output_dimension once to keep call sites small.

Examples:

RubyLLM::Voyage.embed_query('How do I configure SSO?').vectors

Parameters:

  • text (String, Array<String>) —

    one search input or a batch

  • options (Hash) —

    the same options as embed, except input_type

Returns:

  • (RubyLLM::Embedding)

Raises:

  • (ArgumentError) —

    when input_type is passed



94
95
96
 
# File 'lib/ruby_llm/voyage.rb', line 94

def self.embed_query(text, **options)
  embed_side(text, 'query', __method__, options)
end

.file_content(file_id, context: nil) ⇒ String Also known as: download_file

Downloads a Voyage file's raw contents.

Parameters:

  • file_id (String)
  • context (RubyLLM::Context, nil) (defaults to: nil)

Returns:

  • (String) 


208
209
210
 
# File 'lib/ruby_llm/voyage.rb', line 208

def self.file_content(file_id, context: nil)
  provider_for(context).file_content(file_id)
end

.list_files(purpose: nil, limit: nil, order: nil, after: nil, context: nil) ⇒ RubyLLM::Voyage::Page

Lists Voyage files with cursor pagination.

Parameters:

  • purpose (String, nil) (defaults to: nil)
  • limit (Integer, nil) (defaults to: nil)
  • order (String, Symbol, nil) (defaults to: nil)
  • after (String, nil) (defaults to: nil)
  • context (RubyLLM::Context, nil) (defaults to: nil)

Returns:



200
201
202
 
# File 'lib/ruby_llm/voyage.rb', line 200

def self.list_files(purpose: nil, limit: nil, order: nil, after: nil, context: nil)
  provider_for(context).list_files(purpose:, limit:, order: order&.to_s, after:)
end

.rerank(query:, documents:, model: 'rerank-2.5-lite', top_k: nil, return_documents: UNSET, truncation: UNSET, provider_options: {}, context: nil) ⇒ RubyLLM::Voyage::Reranking

Reranks documents for a query with a Voyage reranker.

Parameters:

  • query (String)
  • documents (Array<String>)
  • model (String) (defaults to: 'rerank-2.5-lite')
  • top_k (Integer, nil) (defaults to: nil)
  • return_documents (Boolean) (defaults to: UNSET)
  • truncation (Boolean) (defaults to: UNSET)
  • provider_options (Hash) (defaults to: {})
  • context (RubyLLM::Context, nil) (defaults to: nil)

Returns:



124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
 
# File 'lib/ruby_llm/voyage.rb', line 124

def self.rerank(query:, documents:, model: 'rerank-2.5-lite', top_k: nil, return_documents: UNSET,
                truncation: UNSET, provider_options: {}, context: nil)
  validate_input!(:query, query)
  validate_input!(:documents, documents)
  config = context&.config || RubyLLM.config
  provider = Providers::Voyage.new(config)
  payload = { model: model, query: query, document_count: documents.length }
  RubyLLM.instrument('rerank.voyage', payload, config:) do |event|
    result = provider.rerank(
      query:, documents:, model:, top_k:, return_documents:, truncation:, provider_options:
    )
    event[:result] = result
    event[:response_model] = result.model
    event[:input_tokens] = result.input_tokens
    result
  end
end

.retrieve_file(file_id, context: nil) ⇒ RubyLLM::Voyage::VoyageFile Also known as: find_file

Retrieves metadata for one Voyage file.

Parameters:

  • file_id (String)
  • context (RubyLLM::Context, nil) (defaults to: nil)

Returns:



189
190
191
 
# File 'lib/ruby_llm/voyage.rb', line 189

def self.retrieve_file(file_id, context: nil)
  provider_for(context).retrieve_file(file_id)
end

.upload_file(path, purpose: 'batch', context: nil) ⇒ RubyLLM::Voyage::VoyageFile

Uploads a JSONL file to Voyage.

Parameters:

  • path (String, Pathname)
  • purpose (String) (defaults to: 'batch')
  • context (RubyLLM::Context, nil) (defaults to: nil)

Returns:



181
182
183
 
# File 'lib/ruby_llm/voyage.rb', line 181

def self.upload_file(path, purpose: 'batch', context: nil)
  provider_for(context).upload_file(path, purpose:)
end