tessl/maven-dev-langchain4j--langchain4j-hugging-face

LangChain4j integration library for Hugging Face inference capabilities including chat, language, and embedding models

Overview

Eval results

Files

LangChain4j Hugging Face Integration

Name: tessl/maven-dev-langchain4j--langchain4j-hugging-face
Author: tessl

Integration library for using Hugging Face models with LangChain4j framework. Provides Java implementations for chat, language, and embedding models with builder-pattern configuration.

Quick Reference

Package: dev.langchain4j:langchain4j-hugging-face:1.11.0

Core Classes:

HuggingFaceChatModel - Chat-style interactions (deprecated)
HuggingFaceLanguageModel - Text generation (deprecated)
HuggingFaceEmbeddingModel - Vector embeddings
HuggingFaceClient - Low-level API client
HuggingFaceModelName - Model constants (deprecated)

Critical Notice: HuggingFaceChatModel and HuggingFaceLanguageModel are deprecated since 1.7.0-beta13. Use OpenAiChatModel from langchain4j-open-ai module instead. HuggingFaceEmbeddingModel remains supported.

Installation

Maven:

<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-hugging-face</artifactId>
    <version>1.11.0</version>
</dependency>

Gradle:

implementation 'dev.langchain4j:langchain4j-hugging-face:1.11.0'

Quick Start

Embeddings (Recommended)

import dev.langchain4j.model.huggingface.HuggingFaceEmbeddingModel;
import dev.langchain4j.data.segment.TextSegment;
import dev.langchain4j.data.embedding.Embedding;
import dev.langchain4j.model.output.Response;
import java.util.List;

// Create model
HuggingFaceEmbeddingModel model = HuggingFaceEmbeddingModel.builder()
    .accessToken(System.getenv("HF_API_KEY"))
    .modelId("sentence-transformers/all-MiniLM-L6-v2")
    .build();

// Single embedding
Response<Embedding> response = model.embed("Hello world");
float[] vector = response.content().vector();

// Batch embeddings
List<TextSegment> segments = List.of(
    TextSegment.from("Text 1"),
    TextSegment.from("Text 2")
);
Response<List<Embedding>> batchResponse = model.embedAll(segments);

Chat (Deprecated - Use OpenAI Module Instead)

import dev.langchain4j.model.huggingface.HuggingFaceChatModel;
import dev.langchain4j.model.chat.response.ChatResponse;

HuggingFaceChatModel model = HuggingFaceChatModel.builder()
    .accessToken(System.getenv("HF_API_KEY"))
    .modelId("tiiuae/falcon-7b-instruct")
    .temperature(0.7)
    .build();

String response = model.chat("What is Java?");

Language Model (Deprecated - Use OpenAI Module Instead)

import dev.langchain4j.model.huggingface.HuggingFaceLanguageModel;
import dev.langchain4j.model.output.Response;

HuggingFaceLanguageModel model = HuggingFaceLanguageModel.builder()
    .accessToken(System.getenv("HF_API_KEY"))
    .modelId("microsoft/Phi-3-mini-4k-instruct")
    .temperature(0.8)
    .build();

Response<String> response = model.generate("Write a haiku");

Decision Guide

Choose HuggingFaceEmbeddingModel when:

Generating vector embeddings for semantic search
Creating text representations for similarity analysis
Building RAG (Retrieval-Augmented Generation) systems
Clustering or classifying text

Avoid HuggingFaceChatModel/LanguageModel (deprecated):

Use OpenAiChatModel from langchain4j-open-ai module instead
Better support, not scheduled for removal
Compatible with Hugging Face OpenAI-compatible endpoint

Configuration Essentials

All models support builder pattern with these common options:

Parameter	Type	Default	Required	Description
accessToken	String	-	Yes	Hugging Face API key
modelId	String	-	Recommended	Model identifier
baseUrl	String	`https://router.huggingface.co/hf-inference/`	No	Custom API endpoint
timeout	Duration	15 seconds	No	Request timeout
waitForModel	Boolean	true	No	Wait if model loading

Get API Token: https://huggingface.co/settings/tokens

See Configuration Guide for all options.

Common Model IDs

Embedding Models:

sentence-transformers/all-MiniLM-L6-v2 - Fast, 384-dim
sentence-transformers/all-mpnet-base-v2 - High quality, 768-dim
BAAI/bge-small-en-v1.5 - Optimized for retrieval

Language/Chat Models (for OpenAI module):

tiiuae/falcon-7b-instruct - General purpose
microsoft/Phi-3-mini-4k-instruct - Efficient, 4K context
mistralai/Mistral-7B-Instruct-v0.2 - High quality

Documentation Map

Getting Started

Quick Start Guide - Fastest paths to working code
Common Tasks - Task-oriented cookbook
Configuration Guide - All configuration options

API Reference

EmbeddingModel API - Vector embedding generation
ChatModel API - Chat interactions (deprecated)
LanguageModel API - Text generation (deprecated)
Client API - Low-level HTTP client
Model Names - Pre-defined constants

Guides

Error Handling - Troubleshooting and errors
Migration Guide - Migrating from deprecated classes
SPI Extensions - Custom implementations

Architecture Overview

┌─────────────────────────────────────────┐
│         Model Classes                    │
│  (ChatModel, LanguageModel, Embedding)  │
└──────────────┬──────────────────────────┘
               │
               ├─ Builder Pattern Configuration
               │
┌──────────────▼──────────────────────────┐
│      HuggingFaceClient Interface         │
└──────────────┬──────────────────────────┘
               │
┌──────────────▼──────────────────────────┐
│    DefaultHuggingFaceClient (Impl)      │
│      (Retrofit2 + OkHttp3)              │
└──────────────┬──────────────────────────┘
               │
┌──────────────▼──────────────────────────┐
│       Hugging Face API                   │
│  https://router.huggingface.co/         │
└─────────────────────────────────────────┘

Extension Points:

SPI for custom builders (HuggingFaceEmbeddingModelBuilderFactory)
SPI for custom clients (HuggingFaceClientFactory)
ServiceLoader-based discovery

Key Imports

// Embedding (recommended)
import dev.langchain4j.model.huggingface.HuggingFaceEmbeddingModel;
import dev.langchain4j.data.embedding.Embedding;
import dev.langchain4j.data.segment.TextSegment;

// Chat (deprecated)
import dev.langchain4j.model.huggingface.HuggingFaceChatModel;
import dev.langchain4j.model.chat.response.ChatResponse;
import dev.langchain4j.data.message.UserMessage;

// Language (deprecated)
import dev.langchain4j.model.huggingface.HuggingFaceLanguageModel;
import dev.langchain4j.model.output.Response;

// Low-level client
import dev.langchain4j.model.huggingface.client.HuggingFaceClient;
import dev.langchain4j.model.huggingface.client.EmbeddingRequest;
import dev.langchain4j.model.huggingface.client.TextGenerationRequest;

Error Handling Quick Reference

All model methods throw RuntimeException for API errors:

try {
    Response<Embedding> response = model.embed("text");
} catch (RuntimeException e) {
    // Error format: "status code: <code>; body: <body>"
    System.err.println("API error: " + e.getMessage());
}

Common Error Codes:

401: Invalid/missing access token
404: Model not found
429: Rate limiting
503: Model loading or unavailable

See Error Handling Guide for details.

Migration from Deprecated Classes

If using HuggingFaceChatModel or HuggingFaceLanguageModel, migrate to OpenAiChatModel:

Old (Deprecated):

HuggingFaceChatModel model = HuggingFaceChatModel.builder()
    .accessToken(System.getenv("HF_API_KEY"))
    .modelId("tiiuae/falcon-7b-instruct")
    .build();

New (Recommended):

import dev.langchain4j.model.openai.OpenAiChatModel;

OpenAiChatModel model = OpenAiChatModel.builder()
    .apiKey(System.getenv("HF_API_KEY"))
    .baseUrl("https://router.huggingface.co/v1")
    .modelName("tiiuae/falcon-7b-instruct:hf-inference")
    .build();

See Migration Guide for complete details.

Dependencies

This library requires:

langchain4j-core:1.11.0 - Core interfaces
Retrofit2 - HTTP client
OkHttp3 - HTTP transport
Jackson - JSON serialization

Performance Considerations

Batch Embeddings: Use embedAll() for multiple texts (more efficient)
Timeouts: Default 15s, increase for large models or slow networks
Model Loading: Set waitForModel(true) to avoid 503 errors
Rate Limits: Hugging Face API has rate limits per token tier
Caching: Models cache dimension after first call

Related Resources

Hugging Face Hub: https://huggingface.co/models
Get API Token: https://huggingface.co/settings/tokens
LangChain4j Docs: https://docs.langchain4j.dev
Source Code: https://github.com/langchain4j/langchain4j

Support and Issues

For issues or questions:

Check Error Handling Guide
Review Common Tasks
See LangChain4j GitHub Issues
Check Hugging Face API status

Next Steps

New Users: Start with Quick Start Guide
Specific Tasks: See Common Tasks
API Details: Browse API Reference section
Advanced: Explore SPI Extensions
Migrating: Read Migration Guide

Install with Tessl CLI

npx tessl i tessl/maven-dev-langchain4j--langchain4j-hugging-face@1.11.0

docs