voyageai

package module
v1.1.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 20, 2025 License: MIT Imports: 12 Imported by: 0

README

Voyage Go Library

voyageai is a Go client for Voyage AI

Installation

go get github.com/austinfhunter/voyageai

Usage

Generating Embeddings
	vo := voyageai.NewClient(nil)
	
	embeddings, err := vo.Embed(
		[]string{
			"Embed this text please",
			"And this as well",
		}, 
		"voyage-3-lite", 
		nil,
	)

	if err != nil {
		fmt.Printf("Could not get embedding: %s", err.Error())
	}
	// ... Use the generated embeddings ...

If the embedding request is successful, the embeddings variable will contain an EmbeddingResponse, which contains the embedding objects and usage details.

type EmbeddingObject struct {
	Object string `json:"object"` // The object type, which is always "embedding".
	Embedding []float32 `json:"embedding"` // An array of embedding objects.
	Index int `json:"index"` // An integer representing the index of the embedding within the list of embeddings.
}

type UsageObject struct {
	TotalTokens int `json:"total_tokens"` // The total number of tokens used for computing the embeddings.
	ImagePixels *int `json:"image_pixels,omitempty"` // The total number of image pixels in the list of inputs.
	TextTokens *int `json:"text_tokens,omitempty"` // The total number of text tokens in the list of inputs.
}

type EmbeddingResponse struct {
	Object string `json:"object"` // The object type, which is always "list".
	Data []EmbeddingObject `json:"data"` // An array of embedding objects.
	Model string `json:"model"` // Name of the model.
	Useage UsageObject `json:"useage"` // An object containing useage details
}
Generating Multimodal Embeddings
	// png, jpeg, and gif are all supported file types, webp is not yet supported.
	img, err := os.Open("path/to/image.png")
	if err != nil {
		fmt.Printf("Could not open image: %s", err.Error())
	}

	multimodalInput := []voyageai.MultimodalContent{
		{
			Content: []voyageai.MultimodalInput{
				{
					Type: "text",
					Text: "This is a picture of the Go mascot",
				},
				{
					Type: "image_base64",
					ImageBase64: voyageai.MustGetBase64(img),
				},
			},
		},
	}

	mEmbedding, err := vo.MultimodalEmbed(multimodalInput, "voyage-multimodal-3", nil)
	if err != nil {
		fmt.Printf("Could not get multimodal embedding: %s", err.Error())
	}
	// ... Use the generated embeddings ...

A successful multimodal embedding request also returns an EmbeddingResponse.

Reranking
	vo := voyageai.NewClient(nil)

	reranking, err := vo.Rerank(
		"This is an example query",
		[]string{"this is a document", "this is also a document"}, 
		"rerank-2-lite", 
		nil,
	)
	if err != nil {
		fmt.Printf("Could not get reranking results: %s", err.Error())
	}
	// ... Use the reranked documents  ...

If the reranking request is successful, the reranking variable will contain a RerankingResponse, which contains the reranking objects and usage details.

type RerankResponse struct {
	Object string `json:"object"` // The object type, which is always "list".
	Data []RerankObject `json:"data"` // An array of the reranking results, sorted by the descending order of relevance scores.
	Model string `json:"model"` // Name of the model.
	Useage UsageObject `json:"useage"` // An object containing useage details
}


type RerankObject struct {
	Index int `json:"index"` // The index of the document in the input list.
	RelevanceScore float32 `json:"relevance_score"` // The relevance score of the document with respect to the query.
	Document *string `json:"document,omitempty"` // The document string. Only returned when return_documents is set to true.
}

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func GetBase64 

func GetBase64(img io.Reader) (imageBase64, error)

Reads all image data from an io.Reader and converts it to a base64 encoded data URL for use with MultimodalInput.

func ImageURL 

func ImageURL(s string) imageURL

Convert the provided string to the 'imageURL' type for use with MultimodalInput.

func MustGetBase64 

func MustGetBase64(img io.Reader) imageBase64

Reads all image data and converts it to a base64 encoded data URL for use with MultimodalInput. Panics on failure.

func Opt 

func Opt[T any](opt T) *T

Returns a pointer to the given input. Useful when creating EmbeddingRequestOpts, MultimodalRequestOpts, and RerankRequestOpts literals.

func Text 

func Text(s string) text

Convert the provided string to the 'text' type for use with MultimodalInput.

Types

type APIError 

type APIError struct {
	Detail string `json:"detail"`
}

type EmbeddingObject 

type EmbeddingObject struct {
	Object    string    `json:"object"`    // The object type, which is always "embedding".
	Embedding []float32 `json:"embedding"` // An array of embedding objects.
	Index     int       `json:"index"`     // An integer representing the index of the embedding within the list of embeddings.
}

An embedding object. Part of the data returned by the /embed endpoint

type EmbeddingRequest 

type EmbeddingRequest struct {
	// A list of strings to be embedded.
	Input []string `json:"input"`
	// Name of the model. Recommended options: voyage-3-large, voyage-3, voyage-3-lite, voyage-code-3, voyage-finance-2, voyage-law-2.
	Model string `json:"model"`
	// Type of the input text. Defaults to null. Other options: query, document.
	InputType *string `json:"input_type,omitempty"`
	// Whether to truncate the input texts to fit within the context length. Defaults to true.
	Truncation *bool `json:"truncation,omitempty"`
	// The number of dimensions for resulting output embeddings. Defaults to null.
	OutputDimension *int `json:"output_dimension,omitempty"`
	// The data type for the embeddings to be returned. Defaults to float.
	OutputDType    *string `json:"output_dtype,omitempty"`
	EncodingFormat *string `json:"encoding_format,omitempty"`
}

A data structure that matches the expected fields of the /embedding endpoint. Use EmbeddingRequestOpts when building a request for use with VoyageClient. For more details, see the Voyage AI docs "API reference."

type EmbeddingRequestOpts 

type EmbeddingRequestOpts struct {
	InputType       *string `json:"input_type,omitempty"`       // Type of the input text. Defaults to null. Other options: query, document.
	Truncation      *bool   `json:"truncation,omitempty"`       // Whether to truncate the input texts to fit within the context length. Defaults to true.
	OutputDimension *int    `json:"output_dimension,omitempty"` // The number of dimensions for resulting output embeddings. Defaults to null.
	OutputDType     *string `json:"output_dtype,omitempty"`     // The data type for the embeddings to be returned. Defaults to float.
	EncodingFormat  *string `json:"encoding_format,omitempty"`  // Format in which the embeddings are encoded. Defaults to null. Other options: base64.
}

Additional request options that can be passed to VoyageClient.Embed

type EmbeddingResponse 

type EmbeddingResponse struct {
	Object string            `json:"object"` // The object type, which is always "list".
	Data   []EmbeddingObject `json:"data"`   // An array of embedding objects.
	Model  string            `json:"model"`  // Name of the model.
	Usage  UsageObject       `json:"usage"`  // An object containing usage details
}

The response from the /embed and /multimodalembed endpoints

type Model added in v1.1.0 

type Model = string

A list of models supported by the Voyage AI API. 

const (
	ModelVoyage3Large      Model = "voyage-3-large"
	ModelVoyage3           Model = "voyage-3"
	ModelVoyage3Lite       Model = "voyage-3-lite"
	ModelVoyageMultimodal3 Model = "voyage-multimodal-3"
	ModelVoyageCode3       Model = "voyage-code-3"
	ModelVoyageFinance2    Model = "voyage-finance-2"
	ModelVoyageLaw2        Model = "voyage-law-2"
	ModelRerank2           Model = "rerank-2"
	ModelRerank2Lite       Model = "rerank-2-lite"
)

type MultimodalContent 

type MultimodalContent struct {
	Content []MultimodalInput `json:"content"`
}

type MultimodalInput 

type MultimodalInput struct {
	// Specifies the type of the piece of the content. Allowed values are text, image_url, or image_base64.
	Type string `json:"type"`
	// Only present when type is image_url. The value should be a URL linking to the image. We support PNG, JPEG, WEBP, and GIF images.
	Text text `json:"text,omitempty"`
	// Only present when type is image_base64.
	// The value should be a Base64-encoded image in the data URL format data:[<mediatype>];base64,<data>.
	// Currently supported mediatypes are: image/png, image/jpeg, image/webp, and image/gif.
	ImageBase64 imageBase64 `json:"image_base64,omitempty"`
	ImageURL    imageURL    `json:"image_url,omitempty"`
}

An input for a multimodal embedding request. See [MultimodalEmbed]

func Multimodal 

func Multimodal(v any) MultimodalInput

Multimodal returns a new MultimodalInput. v must be of type text, imageBase64, or imageURL. An empty MultimodalInput will be returned for all other types.

type MultimodalRequest 

type MultimodalRequest struct {
	Inputs        []MultimodalContent `json:"inputs"`                    // A list of multimodal inputs to be vectorized.
	Model         string              `json:"model"`                     // Name of the model. Currently, the only supported model is voyage-multimodal-3.
	InputType     *string             `json:"input_type,omitempty"`      // Type of the input. Options: None, query, document. Defaults to null.
	Truncation    *bool               `json:"truncation,omitempty"`      // Whether to truncate the inputs to fit within the context length. Defaults to True.
	OuputEncoding *string             `json:"output_encoding,omitempty"` // Format in which the embeddings are encoded. Defaults to null.
}

A data structure that matches the expected fields of the /multimodalembedding endpoint. Use MultimodalRequestOpts when building a request for use with VoyageClient. For more details, see the Voyage AI docs "API reference."

type MultimodalRequestOpts 

type MultimodalRequestOpts struct {
	InputType     *string `json:"input_type,omitempty"`
	Truncation    *bool   `json:"truncation,omitempty"`
	OuputEncoding *string `json:"output_encoding,omitempty"`
}

Additional request options that can be passed to VoyageClient.MultimodalEmbed.

type OutputDimension added in v1.1.0 

type OutputDimension = int

OutputDimension represents the dimension size for embedding outputs. 

const (
	OutputDimension256  OutputDimension = 256
	OutputDimension512  OutputDimension = 512
	OutputDimension1024 OutputDimension = 1024
	OutputDimension1536 OutputDimension = 1536
	OutputDimension2048 OutputDimension = 2048
)

type RerankObject 

type RerankObject struct {
	Index          int     `json:"index"`              // The index of the document in the input list.
	RelevanceScore float32 `json:"relevance_score"`    // The relevance score of the document with respect to the query.
	Document       *string `json:"document,omitempty"` // The document string. Only returned when return_documents is set to true.
}

An object containing reranking results.

type RerankRequest 

type RerankRequest struct {
	Query           string   `json:"query"`
	Documents       []string `json:"documents"`
	Model           string   `json:"model"`
	TopK            *int     `json:"top_k,omitempty"`
	ReturnDocuments *bool    `json:"return_documents,omitempty"`
	Truncation      *bool    `json:"truncation,omitempty"`
}

A data structure that matches the expected fields of the /rerank endpoint. Use RerankRequestOpts when building a request for use with VoyageClient. For more details, see the Voyage AI docs "API reference."

type RerankRequestOpts 

type RerankRequestOpts struct {
	// The number of most relevant documents to return. If not specified, the reranking results of all documents will be returned.
	TopK *int `json:"top_k,omitempty"`
	// Whether to return the documents in the response. Defaults to false.
	ReturnDocuments *bool `json:"return_documents,omitempty"`
	// Whether to truncate the input to satisfy the "context length limit" on the query and the documents. Defaults to true.
	Truncation *bool `json:"truncation,omitempty"`
}

Additional request options that can be passed to VoyageClient.Rerank.

type RerankResponse 

type RerankResponse struct {
	Object string         `json:"object"` // The object type, which is always "list".
	Data   []RerankObject `json:"data"`   // An array of the reranking results, sorted by the descending order of relevance scores.
	Model  string         `json:"model"`  // Name of the model.
	Usage  UsageObject    `json:"usage"`  // An object containing usage details
}

The response from the /rerank endpoint

type UsageObject 

type UsageObject struct {
	TotalTokens int  `json:"total_tokens"`           // The total number of tokens used for computing the embeddings.
	ImagePixels *int `json:"image_pixels,omitempty"` // The total number of image pixels in the list of inputs.
	TextTokens  *int `json:"text_tokens,omitempty"`  // The total number of text tokens in the list of inputs.
}

Contains details about system usage.

type VoyageClient 

type VoyageClient struct {
	// contains filtered or unexported fields
}

A client for the Voyage AI API.

func NewClient 

func NewClient(opts *VoyageClientOpts) *VoyageClient

Returns a new instance of VoyageClient

func (*VoyageClient) Embed 

func (c *VoyageClient) Embed(texts []string, model string, opts *EmbeddingRequestOpts) (*EmbeddingResponse, error)

Returns a pointer to an EmbeddingResponse or an error if the request failed.

Parameters:

  • texts - A list of texts as a list of strings, such as ["I like cats", "I also like dogs"]
  • model - Name of the model. Recommended options: voyage-3-large, voyage-3, voyage-3-lite, voyage-code-3, voyage-finance-2, voyage-law-2.
  • opts - optional parameters, see EmbeddingRequestOpts

func (*VoyageClient) MultimodalEmbed 

func (c *VoyageClient) MultimodalEmbed(inputs []MultimodalContent, model string, opts *MultimodalRequestOpts) (*EmbeddingResponse, error)

Returns a pointer to an EmbeddingResponse or an error if the request failed.

Parameters:

  • inputs - A list of multimodal inputs to be vectorized. See the "Voyage AI docs" for info on constraints.
  • model - Name of the model. Recommended options: voyage-3-large, voyage-3, voyage-3-lite, voyage-code-3, voyage-finance-2, voyage-law-2.
  • opts - Optional parameters, see MultimodalRequestOpts

func (*VoyageClient) Rerank 

func (c *VoyageClient) Rerank(query string, documents []string, model string, opts *RerankRequestOpts) (*RerankResponse, error)

Returns a pointer to a RerankResponse or an error if the request failed.

Parameters:

  • query - The query as a string. The query can contain a maximum of 4000 tokens for rerank-2, 2000 tokens for rerank-2-lite and rerank-1, and 1000 tokens for rerank-lite-1.
  • documents - The documents to be reranked as a list of strings.
  • model - Name of the model. Recommended options: rerank-2, rerank-2-lite.
  • opts - Optional parameters, see RerankRequestOpts

type VoyageClientOpts 

type VoyageClientOpts struct {
	Key        string // A Voyage AI API key
	TimeOut    int    // The timeout for all client requests, in milliseconds. No timeout is set by default.
	MaxRetries int    // The maximum number of retries. Requests will not be retried by default.
	BaseURL    string // The BaseURL for the API. Defaults to the Voyage AI API but can be changed for testing and/or mocking.
}

Optional arguments for the client configuration.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.