Documentation
¶
Overview ¶
Package voyage implements Core embedding and reranking with Voyage AI.
Voyage publishes retrieval-tuned text and multimodal embedding models that consistently lead public retrieval benchmarks; the current voyage-4-large / voyage-4 / voyage-4-lite models support matryoshka-style output truncation via the output_dimension parameter.
Voyage's /embeddings shape is bespoke (input_type, truncation, quantization knobs) and doesn't speak the OpenAI dialect — this package implements embedding.Model directly against the native API. Reranking keeps truncation provider-specific while returning Core document indices.
Embedding limits. "The maximum length of the list is 1,000", which MaxTextsPerEmbedRequest names and the model refuses above rather than sending a request certain to be rejected. Voyage caps total tokens per request as well, by model rather than uniformly, which a text count cannot predict; that one surfaces as a provider error.
Rerank limits. "The number of documents cannot exceed 1,000", which MaxDocumentsPerRerankRequest names and the model refuses above. Rerank truncation defaults to true as well, so "the query and documents will be truncated to fit within the context length limit, before processed by the reranker model"; setting it false raises an error instead.
Over-long input is truncated by default: truncation defaults to true, so "an over-length input texts will be truncated to fit within the context length, before vectorized by the embedding model" and nothing reports it. Set truncation to false through the request extension and "an error will be raised if any given text exceeds the context length".
Rerank scores. Voyage documents relevance_score only as "the relevance score of the document with respect to the query" and states no range, so this package does not claim one either: the value is passed to rerank.Score, whose contract is [0, 1], and a score outside that range fails the call by name rather than being rescaled onto the bound. There is no published scale to map from, and inventing one would put a plausible number where a reported mismatch belongs.
See https://docs.voyageai.com/ for the full reference.
Index ¶
Constants ¶
const ( EmbeddingRequestExtensionKey = "voyage/embedding_request" RerankRequestExtensionKey = "voyage/rerank_request" // DefaultBaseURL is Voyage AI's production REST endpoint. Override // via [APIConfig.BaseURL] when proxying through an internal gateway. DefaultBaseURL = "https://api.voyageai.com/v1" Model4Large = "voyage-4-large" Model4 = "voyage-4" Model4Lite = "voyage-4-lite" ModelRerank25 = "rerank-2.5" ModelRerank25Lite = "rerank-2.5-lite" )
Exported identifiers keep provider-owned names and defaults out of caller literals.
const MaxDocumentsPerRerankRequest = 1000
MaxDocumentsPerRerankRequest is the documented ceiling for one rerank call: "the number of documents cannot exceed 1,000". Unlike Cohere's, which is phrased as a recommendation, this one is stated as a limit, so a larger request is refused rather than sent to be rejected.
const MaxTextsPerEmbedRequest = 1000
MaxTextsPerEmbedRequest is the documented ceiling for one embed call: "the maximum length of the list is 1,000". A larger request is refused here rather than sent to be rejected. Voyage also caps the total token count per request, by model rather than uniformly, which a text count cannot predict; that limit surfaces as a provider error.
const (
Provider = "Voyage"
)
Provider is the stable backend name for host-side attribution.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type EmbeddingModel ¶
type EmbeddingModel struct {
// contains filtered or unexported fields
}
EmbeddingModel wraps Voyage AI's /embeddings endpoint. Voyage is Anthropic's officially recommended embedding provider, so this gives Anthropic-centric stacks a first-class RAG embedder without routing through OpenAI/Google.
Current general-purpose models are voyage-4-large, voyage-4, and voyage-4-lite. Specialized models such as voyage-code-3 remain supported.
Voyage-specific knobs that don't fit the generic surface — InputType ("query" / "document" for asymmetric retrieval), Truncation, OutputDtype (int8/uint8/binary quantization) — are reached via the extension-threaded SDK params, see [getOptionsParams] and the [EmbeddingRequest] struct.
func NewEmbeddingModel ¶
func NewEmbeddingModel(_ context.Context, config EmbeddingModelConfig) (*EmbeddingModel, error)
NewEmbeddingModel rejects an invalid provider binding before the first embedding call.
type EmbeddingModelConfig ¶
type EmbeddingModelConfig struct {
APIKey string
DefaultOptions embedding.Options
// BaseURL / HTTPClient mirror [APIConfig] for callers that need to
// proxy through a custom endpoint or share an http.Client.
BaseURL string
HTTPClient *http.Client
}
EmbeddingModelConfig binds provider access and defaults shared by every embedding call.
func (EmbeddingModelConfig) Validate ¶
func (e EmbeddingModelConfig) Validate() error
type RerankModel ¶ added in v0.12.0
type RerankModel struct {
// contains filtered or unexported fields
}
RerankModel implements the Core reranking contract with Voyage.
func NewRerankModel ¶ added in v0.12.0
func NewRerankModel(_ context.Context, config RerankModelConfig) (*RerankModel, error)
NewRerankModel rejects an invalid provider binding before the first reranking call.
type RerankModelConfig ¶ added in v0.12.0
type RerankModelConfig struct {
APIKey string
DefaultOptions rerank.Options
BaseURL string
HTTPClient *http.Client
}
RerankModelConfig binds provider access and defaults shared by every reranking call.
func (RerankModelConfig) Validate ¶ added in v0.12.0
func (r RerankModelConfig) Validate() error
type RerankRequestOptions ¶ added in v0.12.0
type RerankRequestOptions struct {
Truncation *bool `json:"truncation,omitempty"`
}
RerankRequestOptions contains Voyage controls that do not alter Core's reranking result semantics.
Source Files