CtrlK
BlogDocsLog inGet started
Tessl Logo

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

chat-model.mddocs/

Chat Model API

Complete API reference for HuggingFaceChatModel (deprecated).

Deprecation Notice

This class is deprecated since version 1.7.0-beta13 and scheduled for removal.

Migration: Use OpenAiChatModel from langchain4j-open-ai module with Hugging Face's OpenAI-compatible endpoint.

Example Migration:

// Old (deprecated)
HuggingFaceChatModel model = HuggingFaceChatModel.builder()
    .accessToken(apiKey)
    .modelId("tiiuae/falcon-7b-instruct")
    .build();

// New (recommended)
import dev.langchain4j.model.openai.OpenAiChatModel;

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

See Migration Guide for complete details.

Overview

Provides chat-style interactions with Hugging Face language models through the LangChain4j ChatModel interface.

Package: dev.langchain4j.model.huggingface Status: ⚠️ Deprecated (scheduled for removal) Interfaces: ChatModel

Class Signature

package dev.langchain4j.model.huggingface;

@Deprecated(forRemoval = true, since = "1.7.0-beta13")
public class HuggingFaceChatModel implements dev.langchain4j.model.chat.ChatModel {

    // Construction
    public static Builder builder();
    public static HuggingFaceChatModel withAccessToken(String accessToken);

    // Chat operations
    public ChatResponse chat(ChatRequest chatRequest);
    public String chat(String userMessage);
    public ChatResponse chat(ChatMessage... messages);
    public ChatResponse chat(java.util.List<ChatMessage> messages);
}

Builder API

public static final class Builder {

    public Builder baseUrl(String baseUrl);
    public Builder accessToken(String accessToken);
    public Builder modelId(String modelId);
    public Builder timeout(java.time.Duration timeout);
    public Builder temperature(Double temperature);
    public Builder maxNewTokens(Integer maxNewTokens);
    public Builder returnFullText(Boolean returnFullText);
    public Builder waitForModel(Boolean waitForModel);

    public HuggingFaceChatModel build();
}

Construction

builder()

public static Builder builder()

Example:

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

withAccessToken()

public static HuggingFaceChatModel withAccessToken(String accessToken)

Quick construction with defaults.

Chat Operations

chat(ChatRequest)

public ChatResponse chat(ChatRequest chatRequest)

Parameters:

  • chatRequest - Request containing messages and parameters

Returns: ChatResponse with AI message and metadata

Throws: RuntimeException on API errors

chat(String)

public String chat(String userMessage)

Convenience method for single-turn chat.

Parameters:

  • userMessage - User's message text

Returns: AI response text

chat(ChatMessage...)

public ChatResponse chat(ChatMessage... messages)

Chat with varargs messages.

chat(List<ChatMessage>)

public ChatResponse chat(java.util.List<ChatMessage> messages)

Chat with message list.

Configuration

See Configuration Guide for all options.

Key Parameters:

  • accessToken (required) - API key
  • modelId (recommended) - Model identifier
  • temperature (optional) - Sampling temperature (0.0-2.0)
  • maxNewTokens (optional) - Max tokens to generate
  • returnFullText (optional) - Include prompt (default: false)
  • waitForModel (optional) - Wait if loading (default: true)
  • timeout (optional) - Request timeout (default: 15s)
  • baseUrl (optional) - Custom endpoint

Message Types

SystemMessage

public class SystemMessage extends ChatMessage {
    public String text();
    public static SystemMessage from(String text);
}

UserMessage

public class UserMessage extends ChatMessage {
    public String singleText();
    public static UserMessage from(String text);
}

AiMessage

public class AiMessage extends ChatMessage {
    public String text();
    public static AiMessage from(String text);
}

Usage Examples

Simple Chat

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

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

Chat with Messages

import dev.langchain4j.data.message.*;

ChatResponse response = model.chat(
    SystemMessage.from("You are a helpful assistant"),
    UserMessage.from("What is Java?")
);
String aiMessage = response.aiMessage().text();

Multi-turn Conversation

List<ChatMessage> history = new ArrayList<>();
history.add(SystemMessage.from("You are helpful"));
history.add(UserMessage.from("What is ML?"));

ChatResponse response1 = model.chat(history);
history.add(AiMessage.from(response1.aiMessage().text()));

history.add(UserMessage.from("Give an example"));
ChatResponse response2 = model.chat(history);

Error Handling

try {
    ChatResponse response = model.chat(request);
} catch (RuntimeException e) {
    // Error format: "status code: <code>; body: <body>"
    System.err.println("Chat failed: " + e.getMessage());
}

Common Errors:

  • 401: Invalid token
  • 404: Model not found
  • 429: Rate limiting
  • 503: Model loading

Related Documentation

Install with Tessl CLI

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

docs

chat-model.md

client-api.md

common-tasks.md

configuration.md

embedding-model.md

error-handling.md

index.md

language-model.md

migration-guide.md

model-names.md

quick-start.md

spi-extensions.md

tile.json