tessl/maven-dev-langchain4j--langchain4j-hugging-face
LangChain4j integration library for Hugging Face inference capabilities including chat, language, and embedding models
client-api.mddocs/
Client API Reference
Low-level client interface and request/response types for direct Hugging Face API communication.
Overview
The client package provides low-level HTTP client functionality. These are used internally by model classes but can be accessed directly for advanced use cases.
Package: dev.langchain4j.model.huggingface.client
Use Case: Advanced customization, testing, debugging
Recommendation: Use model classes (EmbeddingModel, ChatModel) instead of direct client access for most use cases.
HuggingFaceClient Interface
package dev.langchain4j.model.huggingface.client;
public interface HuggingFaceClient {
@Deprecated(forRemoval = true, since = "1.7.0-beta13")
TextGenerationResponse chat(TextGenerationRequest request);
@Deprecated(forRemoval = true, since = "1.7.0-beta13")
TextGenerationResponse generate(TextGenerationRequest request);
java.util.List<float[]> embed(EmbeddingRequest request);
}chat()
TextGenerationResponse chat(TextGenerationRequest request)Chat-style text generation (deprecated).
generate()
TextGenerationResponse generate(TextGenerationRequest request)Standard text generation (deprecated).
embed()
java.util.List<float[]> embed(EmbeddingRequest request)Generates embeddings for text inputs.
Text Generation Types (Deprecated)
TextGenerationRequest
public class TextGenerationRequest {
public String getInputs();
public Parameters getParameters();
public Options getOptions();
public static Builder builder();
}Builder:
public static final class Builder {
public Builder inputs(String inputs);
public Builder parameters(Parameters parameters);
public Builder options(Options options);
public TextGenerationRequest build();
}TextGenerationResponse
public class TextGenerationResponse {
public TextGenerationResponse();
public TextGenerationResponse(String generatedText);
public String getGeneratedText();
public void setGeneratedText(String generatedText);
}Parameters
public class Parameters {
public Integer getTopK();
public Double getTopP();
public Double getTemperature();
public Double getRepetitionPenalty();
public Integer getMaxNewTokens();
public Double getMaxTime();
public Boolean getReturnFullText();
public Integer getNumReturnSequences();
public Boolean getDoSample();
public static Builder builder();
}Builder:
public static final class Builder {
public Builder topK(Integer topK);
public Builder topP(Double topP);
public Builder temperature(Double temperature);
public Builder repetitionPenalty(Double repetitionPenalty);
public Builder maxNewTokens(Integer maxNewTokens);
public Builder maxTime(Double maxTime);
public Builder returnFullText(Boolean returnFullText);
public Builder numReturnSequences(Integer numReturnSequences);
public Builder doSample(Boolean doSample);
public Parameters build();
}Parameter Guidelines:
- temperature: 0.0-2.0 (lower = deterministic, higher = creative)
- topK: Positive integer (typical: 40-100)
- topP: 0.0-1.0 (typical: 0.9-0.95)
- repetitionPenalty: >1.0 penalizes repetition (typical: 1.1-1.5)
Options
public class Options {
public Boolean getWaitForModel();
public Boolean getUseCache();
public static Builder builder();
}Builder:
public static final class Builder {
public Builder waitForModel(Boolean waitForModel);
public Builder useCache(Boolean useCache);
public Options build();
}Embedding Types
EmbeddingRequest
public class EmbeddingRequest {
public EmbeddingRequest(java.util.List<String> inputs, boolean waitForModel);
public java.util.List<String> getInputs();
public Options getOptions();
}Example:
List<String> texts = List.of("Hello", "World");
EmbeddingRequest request = new EmbeddingRequest(texts, true);Usage Examples
Direct Text Generation (Deprecated)
TextGenerationRequest request = TextGenerationRequest.builder()
.inputs("Write a poem:")
.parameters(Parameters.builder()
.temperature(0.7)
.maxNewTokens(100)
.build())
.options(Options.builder()
.waitForModel(true)
.build())
.build();
// HuggingFaceClient client = ...;
// TextGenerationResponse response = client.generate(request);
// String text = response.getGeneratedText();Direct Embedding Generation
List<String> texts = List.of("Text 1", "Text 2");
EmbeddingRequest request = new EmbeddingRequest(texts, true);
// HuggingFaceClient client = ...;
// List<float[]> embeddings = client.embed(request);JSON Serialization
All types use Jackson annotations:
@JsonIgnoreProperties(ignoreUnknown = true)- Ignore unknown fields@JsonInclude(NON_NULL)- Only include non-null fields@JsonNaming(SnakeCaseStrategy.class)- Use snake_case
Internal Usage
Client types are primarily used internally by:
- HuggingFaceChatModel (deprecated)
- HuggingFaceLanguageModel (deprecated)
- HuggingFaceEmbeddingModel
Direct usage needed for:
- Custom client implementations via SPI
- Advanced customization beyond model capabilities
- Testing and debugging
Default Implementation
The library provides DefaultHuggingFaceClient using:
- Retrofit2 for HTTP client
- OkHttp3 for transport
- Jackson for JSON
Related Documentation
- Embedding Model API - Recommended for embeddings
- Chat Model API - Deprecated, use OpenAI module
- SPI Extensions - Custom client implementations
- Error Handling - Error scenarios
Install with Tessl CLI
npx tessl i tessl/maven-dev-langchain4j--langchain4j-hugging-face@1.11.0