Using Voyage AI

信息

Take-home activity! Do it if you are following along at home. It won't be covered during the hands-on lab.

Voyage AI provides high‑quality embedding models you can use for semantic search. You’ll need an API key to call their Embeddings API.

Create a Voyage account and get an API key

To get started with Voyage AI, go to https://voyageai.com and create an account.

Once you’re logged in, navigate to your account dashboard and generate a new API key.

This key will be required to call the Voyage Embeddings API. Make sure you copy and store it in a safe place, as you’ll need it later when configuring the application.

Create embeddings with cURL

Once you have your API key, you can test the API directly using curl:

VOYAGE_API_KEY=<YOUR_API_KEY>

curl --location 'https://api.voyageai.com/v1/embeddings' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $VOYAGE_API_KEY' \
--data '{ 
    "input": "Some text ..",
    "model": "voyage-3-large",    
    "output_dimension": 2048
}'

Using Voyage AI in the application

☕️ Java Spring Boot

To run semantic queries in Java, the application also needs to generate embeddings for your query.
This is handled by the EmbeddingProvider interface.

For Voyage AI, the implementation is VoyageAIEmbeddingProvider, which delegates the HTTP call to the Feign client:

src/main/java/com/mongodb/devrel/library/infrastructure/embeddings/voyageai/VoyageEmbeddingsClient.java

@FeignClient(
        name = "voyage",
        url = "${voyage.base-url}",
        configuration = VoyageFeignInterceptor.class
)
public interface VoyageEmbeddingsClient {
  @PostMapping("/embeddings")
  VoyageEmbeddingsResponse getEmbeddings(@RequestBody VoyageEmbeddingsRequest body);
}

Configuring the application

To use Voyage AI, you only need to adjust a few parameters in application.yml:

src/main/resources/application.yml

embeddings:
  source: ${EMBEDDING_SOURCE}
voyage:
  api-key: ${VOYAGE_KEY:yourKey}

The embeddings.source property is what selects the provider at runtime. If you set it to voyage, the Voyage AI implementation will be used. You can either edit these values in application.yml, or export them as environment variables:

export EMBEDDING_SOURCE=voyage
export VOYAGE_KEY=pa-6r..

Running the application

Once the variables are set, start the application as usual:

mvn spring-boot:run

At the end, when the application starts, just make a call to searchBooks as described in the step Add Semantic Search to Your Application and you will see the application calling the Voyage AI implementation: