embedding-tutorial

Embedding Similarity Calculator

A Quarkus application that demonstrates how to compare the meaning of two texts using AI-powered embeddings. It uses LangChain4j and a local Ollama model to generate high-dimensional vectors for each input, then calculates cosine similarity and Euclidean distance to show how semantically close the texts are. The app features a web UI built with Qute for visualizing similarity scores, vector dimensions, and partial embeddings—making it a hands-on example of semantic search and vector math in Java.

• Supporting article: From Strings to Semantics — Comparing Text with Java, Quarkus, and Embeddings

Features

• Text similarity calculation using embeddings
• Cosine similarity visualization with a progress bar
• Euclidean distance calculation
• Vector dimension display
• First 10 dimensions of the embedding vectors shown
• Error handling for invalid inputs

Prerequisites

• Java 17 or later
• Maven 3.8.1 or later
• Ollama running locally (for the embedding model)

Running the Application

1. Start Ollama (if not already running)
2. Run the application in dev mode:

./mvnw quarkus:dev

3. Access the application at: http://localhost:8080/similarity?text1=your+first+text&text2=your+second+text

Example Usage

Calculate similarity between two texts:

http://localhost:8080/similarity?text1=Quarkus+is+fast&text2=I+like+high-performance+Java

Response Format

The application returns an HTML page with:

• Input texts
• Cosine similarity (range: [-1, 1])
• Similarity percentage visualization
• Euclidean distance (range: [0, 2])
• Vector dimensions
• First 10 dimensions of the embedding vectors

Technologies Used

• Quarkus
• Qute templating engine
• LangChain4j for embeddings
• Ollama for the embedding model

Error Handling

The application handles:

• Missing input parameters
• Invalid inputs
• Processing errors

Error messages are displayed in red on the HTML page.

embedding-tutorial

This project uses Quarkus, the Supersonic Subatomic Java Framework.

If you want to learn more about Quarkus, please visit its website: https://quarkus.io/.

Running the application in dev mode

You can run your application in dev mode that enables live coding using:

./mvnw quarkus:dev

NOTE: Quarkus now ships with a Dev UI, which is available in dev mode only at http://localhost:8080/q/dev/.

Packaging and running the application

The application can be packaged using:

./mvnw package

It produces the quarkus-run.jar file in the target/quarkus-app/ directory. Be aware that it's not an über-jar as the dependencies are copied into the target/quarkus-app/lib/ directory.

The application is now runnable using java -jar target/quarkus-app/quarkus-run.jar.

If you want to build an über-jar, execute the following command:

./mvnw package -Dquarkus.package.jar.type=uber-jar

The application, packaged as an über-jar, is now runnable using java -jar target/*-runner.jar.

Creating a native executable

You can create a native executable using:

./mvnw package -Dnative

Or, if you don't have GraalVM installed, you can run the native executable build in a container using:

./mvnw package -Dnative -Dquarkus.native.container-build=true

You can then execute your native executable with: ./target/embedding-tutorial-1.0.0-SNAPSHOT-runner

If you want to learn more about building native executables, please consult https://quarkus.io/guides/maven-tooling.

Related Guides

• Qute (guide): Offer templating support for web, email, etc in a build time, type-safe way
• REST Jackson (guide): Jackson serialization support for Quarkus REST. This extension is not compatible with the quarkus-resteasy extension, or any of the extensions that depend on it
• LangChain4j Ollama (guide): Provides the basic integration of Ollama with LangChain4j

Provided Code

REST

Easily start your REST Web Services

Related guide section...