Class: Parse::Embeddings::Voyage

Inherits:
Provider
  • Object
show all
Defined in:
lib/parse/embeddings/voyage.rb

Overview

Voyage AI embeddings provider. Wraps POST /v1/embeddings for text-only models and POST /v1/multimodalembeddings for the multimodal text+image models (text via #embed_text, images via #embed_image).

Supported models:

  • v4 family — voyage-4-large (MoE flagship, Matryoshka-capable), voyage-4, voyage-4-lite, voyage-4-nano (Apache 2.0, open-weight on Hugging Face — also runnable through LocalHTTP when self-hosted on vLLM / Ollama / llama.cpp).
  • v3 family — voyage-3-large, voyage-3, voyage-3-lite, voyage-code-3.
  • domain models — voyage-finance-2, voyage-law-2.
  • multimodal — voyage-multimodal-3 (1024-dim). Unified text+image vector space at the network boundary. Text inputs route to /v1/multimodalembeddings with a { inputs: [{ content: [{ type: "text", text: … }] }] } envelope; image inputs go through #embed_image as image_url rows (provider-side fetch, v5.1) or image_base64 rows (SDK-fetched bytes, v5.5). Text and image vectors share the same space, so stored text vectors are comparable against image vectors without re-embedding.

Asymmetric input types

Voyage's input_type field accepts "query" or "document" (mapped from the SDK-canonical :search_query / :search_document Symbols). The values are functionally analogous to Cohere's search_query / search_document — they're encoded by separately tuned heads, so re-using one type for both sides of a retrieval pair measurably degrades recall.

Voyage also accepts null (omit the field), which Voyage's docs recommend for "general purpose" embeddings unrelated to retrieval. We translate the absent / non-retrieval cases to null rather than picking a default — Voyage's training depends on the asymmetry, so guessing on the caller's behalf would be worse than passing-through.

Security

  • The Faraday connection refuses proxy: unless the caller opts in via allow_faraday_proxy: true. Env-proxy autodiscovery (HTTPS_PROXY etc.) is suppressed by default.
  • #inspect (inherited from Provider) never surfaces @api_key.
  • Authorization and Voyage-Api-Key are in Middleware::BodyBuilder::REDACTED_HEADERS.

Examples:

registration

Parse::Embeddings.register(:voyage,
  Parse::Embeddings::Voyage.new(
    api_key: ENV.fetch("VOYAGE_API_KEY"),
    model:   "voyage-3",
  ))

Defined Under Namespace

Classes: AuthenticationError, BadRequestError, RateLimitError, TransientError

Constant Summary collapse

DEFAULT_BASE_URL = 
"https://api.voyageai.com/v1"
DEFAULT_MODEL = 
"voyage-3"
DEFAULT_TIMEOUT = 
30
DEFAULT_OPEN_TIMEOUT = 
5
DEFAULT_MAX_RETRIES = 
3
DEFAULT_BATCH_SIZE =

Voyage's documented per-request cap is 128 inputs.

128
MAX_RESPONSE_BYTES = 
16 * 1024 * 1024
MODEL_DEFAULT_DIMENSIONS =

Native vector widths per model. The v4 family is Voyage's current flagship line (MoE for voyage-4-large, open-weight nano under Apache 2.0). voyage-4-large supports Matryoshka truncation via the constructor's dimensions: override.

{
  "voyage-4-large"      => 2048,
  "voyage-4"            => 1024,
  "voyage-4-lite"       => 512,
  "voyage-4-nano"       => 256,
  "voyage-3-large"      => 1024,
  "voyage-3"            => 1024,
  "voyage-3-lite"       => 512,
  "voyage-code-3"       => 1024,
  "voyage-finance-2"    => 1024,
  "voyage-law-2"        => 1024,
  "voyage-multimodal-3" => 1024,
}.freeze
MODEL_MAX_INPUT_TOKENS = 
{
  "voyage-4-large"      => 32_000,
  "voyage-4"            => 32_000,
  "voyage-4-lite"       => 32_000,
  "voyage-4-nano"       => 32_000,
  "voyage-3-large"      => 32_000,
  "voyage-3"            => 32_000,
  "voyage-3-lite"       => 32_000,
  "voyage-code-3"       => 32_000,
  "voyage-finance-2"    => 16_000,
  "voyage-law-2"        => 16_000,
  "voyage-multimodal-3" => 32_000,
}.freeze
MATRYOSHKA_MODELS =

Models that accept Voyage's output_dimension Matryoshka truncation parameter. Sending the field for other models is rejected with a 400 by Voyage, so we gate it explicitly.

%w[voyage-4-large].freeze
MULTIMODAL_MODELS =

Models that route to /v1/multimodalembeddings with the { inputs: [{ content: [...] }] } envelope rather than the standard /v1/embeddings { input: [String] } envelope. Text-only inputs from this provider are wrapped as { type: "text", text: s } content rows.

%w[voyage-multimodal-3].freeze
INPUT_TYPE_WIRE_VALUES =

Map SDK-canonical input_type symbols to Voyage wire strings. :classification / :clustering map to nil (omitted) since Voyage only distinguishes retrieval halves — other intents should receive the unconditioned vector.

{
  search_query:    "query",
  search_document: "document",
  classification:  nil,
  clustering:      nil,
}.freeze

Constants inherited from Provider

Provider::AS_NOTIFICATION_NAME

Instance Method Summary collapse

Methods inherited from Provider

#embed_text_batched, #inspect, #instrument_embed, #validate_response!

Constructor Details

#initialize(api_key:, model: DEFAULT_MODEL, base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT, open_timeout: DEFAULT_OPEN_TIMEOUT, max_retries: DEFAULT_MAX_RETRIES, embed_batch_size: DEFAULT_BATCH_SIZE, dimensions: nil, truncation: true, allow_faraday_proxy: false, allow_insecure_base_url: false, connection: nil) ⇒ Voyage

Returns a new instance of Voyage.

Parameters:

  • api_key (String) —

    required. Sent as Authorization: Bearer ….

  • model (String) (defaults to: DEFAULT_MODEL) —

    one of MODEL_DEFAULT_DIMENSIONS's keys.

  • base_url (String) (defaults to: DEFAULT_BASE_URL) —

    override. Must be HTTPS unless allow_insecure_base_url: true.

  • timeout (Integer) (defaults to: DEFAULT_TIMEOUT) —

    read timeout, seconds.

  • open_timeout (Integer) (defaults to: DEFAULT_OPEN_TIMEOUT) —

    connect timeout, seconds.

  • max_retries (Integer) (defaults to: DEFAULT_MAX_RETRIES) —

    retry attempts on 429/5xx/timeouts.

  • embed_batch_size (Integer) (defaults to: DEFAULT_BATCH_SIZE) —

    inputs per request (max 128).

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

    override output width via Voyage's output_dimension Matryoshka parameter. Only voyage-4-large accepts the field; for every other model the override must equal the native width or be omitted.

  • truncation (Boolean) (defaults to: true) —

    forward Voyage's truncation: field. Defaults true to match Voyage's API default. Set false to force the API to reject over-length inputs rather than silently truncating (useful when you want explicit chunking errors).

  • allow_faraday_proxy (Boolean) (defaults to: false) —

    opt in to proxy / env-proxy autodiscovery. Defaults false.

  • allow_insecure_base_url (Boolean) (defaults to: false) —

    permit http:// base.

  • connection (Faraday::Connection, nil) (defaults to: nil) —

    injection seam.



155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
 
# File 'lib/parse/embeddings/voyage.rb', line 155

def initialize(
  api_key:,
  model: DEFAULT_MODEL,
  base_url: DEFAULT_BASE_URL,
  timeout: DEFAULT_TIMEOUT,
  open_timeout: DEFAULT_OPEN_TIMEOUT,
  max_retries: DEFAULT_MAX_RETRIES,
  embed_batch_size: DEFAULT_BATCH_SIZE,
  dimensions: nil,
  truncation: true,
  allow_faraday_proxy: false,
  allow_insecure_base_url: false,
  connection: nil
)
  validate_api_key!(api_key)
  validate_model!(model)
  sanitized_base_url = validate_base_url!(base_url, allow_insecure_base_url)
  validate_positive_integer!(:timeout, timeout)
  validate_positive_integer!(:open_timeout, open_timeout)
  validate_non_negative_integer!(:max_retries, max_retries)
  validate_positive_integer!(:embed_batch_size, embed_batch_size)
  if embed_batch_size > 128
    raise ArgumentError,
          "Parse::Embeddings::Voyage: embed_batch_size #{embed_batch_size} exceeds Voyage's per-request cap (128)."
  end
  unless [true, false].include?(truncation)
    raise ArgumentError,
          "Parse::Embeddings::Voyage: truncation must be true or false (got #{truncation.inspect})."
  end
  validate_dimensions!(model, dimensions)

  @api_key = api_key
  @model = model
  @dimensions = dimensions || MODEL_DEFAULT_DIMENSIONS.fetch(model)
  @base_url = sanitized_base_url
  @timeout = timeout
  @open_timeout = open_timeout
  @max_retries = max_retries
  @embed_batch_size = embed_batch_size
  @truncation = truncation
  @allow_faraday_proxy = allow_faraday_proxy
  @connection = connection || build_connection
end

Instance Method Details

#dimensions ⇒ Object 



199
200
201
 
# File 'lib/parse/embeddings/voyage.rb', line 199

def dimensions
  @dimensions
end

#embed_batch_size ⇒ Object 



207
208
209
 
# File 'lib/parse/embeddings/voyage.rb', line 207

def embed_batch_size
  @embed_batch_size
end

#embed_image(sources, input_type: :search_document, allow_insecure: false) ⇒ Array<Array<Float>>

Embed a batch of images through Voyage's /v1/multimodalembeddings endpoint. Two source forms:

  • String URL (v5.1 path) — the provider receives a public URL and issues its own fetch. The SDK does NOT download the image; it validates the URL through Parse::Embeddings.validate_image_url! (CIDR / port / host allowlist, sentinel-gated egress opt-in) and forwards the canonicalized URL string in a { type: "image_url", image_url: ... } content row.
  • ImageFetch::FetchedImage (v5.5 bytes path) — bytes the SDK already downloaded through File.safe_open_url, magic-byte-verified, and EXIF-stripped. Forwarded as a { type: "image_base64", image_base64: "data:<mime>;base64,..." } content row. No URL validation runs (there is no provider-side fetch) and the trust_provider_url_fetch sentinel is NOT required.

Multimodal model required. Voyage's text-only models (voyage-3, voyage-4, etc.) do not accept image inputs; calling embed_image on a provider configured with one of those raises BadRequestError before any network call.

Parameters:

Returns:

  • (Array<Array<Float>>) —

    vectors aligned 1:1 with sources.



317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
 
# File 'lib/parse/embeddings/voyage.rb', line 317

def embed_image(sources, input_type: :search_document, allow_insecure: false)
  unless MULTIMODAL_MODELS.include?(@model)
    raise BadRequestError,
          "Parse::Embeddings::Voyage#embed_image: model #{@model.inspect} does not " \
          "accept image inputs. Configure the provider with a multimodal model " \
          "(supported: #{MULTIMODAL_MODELS.inspect})."
  end
  unless sources.is_a?(Array)
    raise ArgumentError,
          "Parse::Embeddings::Voyage#embed_image expects Array of image URLs " \
          "(got #{sources.class})."
  end
  return [] if sources.empty?

  unless INPUT_TYPE_WIRE_VALUES.key?(input_type)
    raise ArgumentError,
          "Parse::Embeddings::Voyage#embed_image input_type #{input_type.inspect} not in " \
          "#{INPUT_TYPE_WIRE_VALUES.keys.inspect}."
  end
  # Voyage caps multimodal requests at the same per-request size
  # as the text endpoint. The text path goes through
  # `embed_text_batched` which chunks automatically; the image
  # path has no chunker yet (every directive is a single image
  # source), so guard the direct-API caller against a silent 400.
  if sources.length > @embed_batch_size
    raise ArgumentError,
          "Parse::Embeddings::Voyage#embed_image: batch size #{sources.length} exceeds " \
          "the configured cap #{@embed_batch_size} (Voyage per-request max: 128). " \
          "Split the input and call embed_image once per chunk."
  end

  # Validate every URL up-front so a malformed entry in slot N
  # does not get past validation while slots 0..N-1 are already
  # in the wire body. URL entries forward the validator's
  # canonicalized URL (never the caller's raw input); fetched-
  # bytes entries skip URL validation (the bytes were already
  # downloaded + verified by ImageFetch) and forward as base64.
  content_rows = sources.each_with_index.map do |src, i|
    if src.is_a?(Parse::Embeddings::ImageFetch::FetchedImage)
      { content: [{ type: "image_base64", image_base64: src.to_data_uri }] }
    elsif src.is_a?(String)
      canonical = Parse::Embeddings.validate_image_url!(src, allow_insecure: allow_insecure)
      { content: [{ type: "image_url", image_url: canonical }] }
    else
      raise ArgumentError,
            "Parse::Embeddings::Voyage#embed_image sources[#{i}] must be a URL String " \
            "or Parse::Embeddings::ImageFetch::FetchedImage (got #{src.class})."
    end
  end

  wire_input_type = INPUT_TYPE_WIRE_VALUES[input_type]
  body = {
    inputs: content_rows,
    model: @model,
    truncation: @truncation,
  }
  body[:input_type] = wire_input_type if wire_input_type

  instrument_embed(sources.length, input_type, modality: :image) do |emit_payload|
    payload = post_embeddings(body, path: "multimodalembeddings")
    if payload.is_a?(Hash) && payload["usage"].is_a?(Hash)
      tt = payload["usage"]["total_tokens"]
      emit_payload[:total_tokens] = tt if tt.is_a?(Integer) && tt >= 0
    end
    vectors = extract_vectors!(payload, sources.length)
    validate_response!(sources.length, vectors)
  end
end

#embed_text(strings, input_type: :search_document) ⇒ Array<Array<Float>>

Returns vectors aligned 1:1 with strings.

Parameters:

Returns:

  • (Array<Array<Float>>) —

    vectors aligned 1:1 with strings.



227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
 
# File 'lib/parse/embeddings/voyage.rb', line 227

def embed_text(strings, input_type: :search_document)
  unless strings.is_a?(Array)
    raise ArgumentError,
          "Parse::Embeddings::Voyage#embed_text expects Array<String> (got #{strings.class})."
  end
  return [] if strings.empty?
  strings.each_with_index do |s, i|
    unless s.is_a?(String)
      raise ArgumentError,
            "Parse::Embeddings::Voyage#embed_text strings[#{i}] is not a String (#{s.class})."
    end
    if s.empty?
      raise ArgumentError,
            "Parse::Embeddings::Voyage#embed_text strings[#{i}] is empty; Voyage rejects empty inputs."
    end
  end
  unless INPUT_TYPE_WIRE_VALUES.key?(input_type)
    raise ArgumentError,
          "Parse::Embeddings::Voyage#embed_text input_type #{input_type.inspect} not in " \
          "#{INPUT_TYPE_WIRE_VALUES.keys.inspect}."
  end
  wire_input_type = INPUT_TYPE_WIRE_VALUES[input_type]

  # Multimodal models route to a different endpoint with a
  # different request envelope. The response envelope shape is
  # the same (`{ data: [{ embedding, index }], usage: {...} }`)
  # so `extract_vectors!` is reused as-is.
  body =
    if MULTIMODAL_MODELS.include?(@model)
      build_multimodal_body(strings, wire_input_type)
    else
      build_text_body(strings, wire_input_type)
    end

  path = MULTIMODAL_MODELS.include?(@model) ? "multimodalembeddings" : "embeddings"

  instrument_embed(strings.length, input_type) do |emit_payload|
    payload = post_embeddings(body, path: path)
    # Voyage's response carries `usage: { total_tokens }`.
    if payload.is_a?(Hash) && payload["usage"].is_a?(Hash)
      tt = payload["usage"]["total_tokens"]
      emit_payload[:total_tokens] = tt if tt.is_a?(Integer) && tt >= 0
    end
    vectors = extract_vectors!(payload, strings.length)
    validate_response!(strings.length, vectors)
  end
end

#inspect_attrs ⇒ Object 



386
387
388
 
# File 'lib/parse/embeddings/voyage.rb', line 386

def inspect_attrs
  super.merge(base: safe_base_host, retries: @max_retries)
end

#max_input_tokens ⇒ Object 



211
212
213
 
# File 'lib/parse/embeddings/voyage.rb', line 211

def max_input_tokens
  MODEL_MAX_INPUT_TOKENS[@model]
end

#modalities ⇒ Array<Symbol>

Returns Voyage's multimodal models support [:text, :image]; text-only models report [:text].

Returns:

  • (Array<Symbol>) —

    Voyage's multimodal models support [:text, :image]; text-only models report [:text].



277
278
279
 
# File 'lib/parse/embeddings/voyage.rb', line 277

def modalities
  MULTIMODAL_MODELS.include?(@model) ? %i[text image] : [:text]
end

#model_name ⇒ Object 



203
204
205
 
# File 'lib/parse/embeddings/voyage.rb', line 203

def model_name
  @model
end

#normalize? ⇒ Boolean

Returns:

  • (Boolean) 


215
216
217
218
 
# File 'lib/parse/embeddings/voyage.rb', line 215

def normalize?
  # Voyage's v3 embeddings are documented unit-normalized.
  true
end

#supports_input_type? ⇒ Boolean

Returns:

  • (Boolean) 


220
221
222
 
# File 'lib/parse/embeddings/voyage.rb', line 220

def supports_input_type?
  true
end