Quarkus LangChain4j Hugging Face Extension

Quarkus extension that provides seamless integration between Quarkus applications and Hugging Face language models through the LangChain4j framework. This extension enables developers to incorporate Hugging Face's extensive collection of pre-trained NLP models into their applications for both chat-style text generation and text embeddings.

Package Information

• Package Name: quarkus-langchain4j-hugging-face
• Package Type: Maven
• Group ID: io.quarkiverse.langchain4j
• Artifact ID: quarkus-langchain4j-hugging-face
• Version: 1.7.4
• Language: Java
• Installation: Add Maven dependency to your Quarkus project

<dependency>
    <groupId>io.quarkiverse.langchain4j</groupId>
    <artifactId>quarkus-langchain4j-hugging-face</artifactId>
    <version>1.7.4</version>
</dependency>

Core Imports

import io.quarkiverse.langchain4j.huggingface.QuarkusHuggingFaceChatModel;
import io.quarkiverse.langchain4j.huggingface.QuarkusHuggingFaceEmbeddingModel;

Basic Usage

Configuration-Based Usage (Recommended)

Configure the extension in application.properties:

quarkus.langchain4j.huggingface.api-key=hf_your_token_here
quarkus.langchain4j.huggingface.chat-model.inference-endpoint-url=https://api-inference.huggingface.co/models/tiiuae/falcon-7b-instruct
quarkus.langchain4j.huggingface.chat-model.temperature=0.7
quarkus.langchain4j.huggingface.chat-model.max-new-tokens=100

When using LangChain4j AI Services, the configured models are automatically injected and available.

Programmatic Usage

import io.quarkiverse.langchain4j.huggingface.QuarkusHuggingFaceChatModel;
import java.net.URL;
import java.time.Duration;

// Build chat model programmatically
QuarkusHuggingFaceChatModel chatModel = QuarkusHuggingFaceChatModel.builder()
    .accessToken("hf_your_token_here")
    .url(new URL("https://api-inference.huggingface.co/models/tiiuae/falcon-7b-instruct"))
    .temperature(0.7)
    .maxNewTokens(100)
    .timeout(Duration.ofSeconds(30))
    .build();

// Use the model (implements dev.langchain4j.model.chat.ChatModel)
dev.langchain4j.data.message.UserMessage message = dev.langchain4j.data.message.UserMessage.from("Hello!");
dev.langchain4j.model.chat.request.ChatRequest request = dev.langchain4j.model.chat.request.ChatRequest.builder()
    .messages(java.util.Collections.singletonList(message))
    .build();
dev.langchain4j.model.chat.response.ChatResponse response = chatModel.doChat(request);

Architecture

This extension provides Quarkus-specific implementations of LangChain4j interfaces:

• Chat Models: Text generation using Hugging Face inference endpoints
• Embedding Models: Text-to-vector conversion for semantic search and RAG workflows
• Configuration System: Declarative and programmatic configuration with named configurations support
• REST Client Integration: Uses Quarkus REST client with Jackson for API communication
• Native Compilation: GraalVM native image support through Jackson mixins
• Observability: Integration with Quarkus metrics and tracing stack

Capabilities

Chat Model

Provides text generation capabilities using Hugging Face chat models with comprehensive configuration options including temperature, sampling strategies, and token limits.

public class QuarkusHuggingFaceChatModel implements dev.langchain4j.model.chat.ChatModel {
    public static QuarkusHuggingFaceChatModel.Builder builder();
    public dev.langchain4j.model.chat.response.ChatResponse doChat(
        dev.langchain4j.model.chat.request.ChatRequest chatRequest
    );
}

Chat Model

Embedding Model

Provides text embedding capabilities for converting text into vector representations, enabling semantic search and retrieval-augmented generation (RAG) workflows.

public class QuarkusHuggingFaceEmbeddingModel implements dev.langchain4j.model.embedding.EmbeddingModel {
    public static QuarkusHuggingFaceEmbeddingModel.Builder builder();
    public dev.langchain4j.model.output.Response<java.util.List<dev.langchain4j.data.embedding.Embedding>> embedAll(
        java.util.List<dev.langchain4j.data.segment.TextSegment> textSegments
    );
}

Embedding Model

Configuration

Declarative configuration system using Quarkus configuration properties with support for default and named configurations, comprehensive chat and embedding model settings, integration toggles, and build-time model enablement.

Runtime Configuration Root:

quarkus.langchain4j.huggingface.*

Build-Time Configuration:

quarkus.langchain4j.huggingface.chat-model.enabled=true
quarkus.langchain4j.huggingface.embedding-model.enabled=true

Configuration Reference

Client Factory

Factory for creating Hugging Face REST clients with Quarkus-specific configuration, including custom Jackson ObjectMapper setup and authentication handling.

public class QuarkusHuggingFaceClientFactory
    implements dev.langchain4j.model.huggingface.spi.HuggingFaceClientFactory {
    public dev.langchain4j.model.huggingface.client.HuggingFaceClient create(
        QuarkusHuggingFaceChatModel.Builder config,
        dev.langchain4j.model.huggingface.spi.HuggingFaceClientFactory.Input input,
        java.net.URI url
    );
}

Client Factory

Key Features

• Dual Model Support: Both chat (text generation) and embedding models
• Flexible Configuration: Declarative configuration via properties or programmatic via builders
• Named Configurations: Support for multiple model configurations with different settings
• Comprehensive Parameters: Temperature, top-K, top-P, repetition penalty, token limits, and more
• Multiple Endpoints: Hugging Face Hub API, private endpoints, locally deployed models, AWS-hosted endpoints
• Logging: Request/response logging with automatic API key masking
• Native Compilation: Full GraalVM native image support
• Quarkus Observability: Integration with Quarkus metrics and tracing
• LangChain4j Compatible: Implements standard LangChain4j interfaces for portability

Supported Model Types

Chat Models

• Default: tiiuae/falcon-7b-instruct
• Supported: Any Hugging Face text-to-text model
• Endpoints: Hosted API, private endpoints, local deployments

Embedding Models

• Default: sentence-transformers/all-MiniLM-L6-v2
• Supported: Any Hugging Face feature extraction model
• Endpoints: Hosted API, private endpoints, local deployments

Limitations

• No Tool Support: Hugging Face models do not support LangChain4j tools or function calling
• Text-to-Text Only: Only text-to-text models are supported for chat generation
• No Streaming: Streaming responses are not supported

Environment Variables

Configuration can be provided via environment variables using Quarkus naming conventions:

QUARKUS_LANGCHAIN4J_HUGGINGFACE_API_KEY=hf_your_token_here
QUARKUS_LANGCHAIN4J_HUGGINGFACE_CHAT_MODEL_TEMPERATURE=0.7
QUARKUS_LANGCHAIN4J_HUGGINGFACE_CHAT_MODEL_MAX_NEW_TOKENS=100