tools-only LangChain4j Spring Boot Integration - Configuration Guide
Detailed configuration options and advanced setup patterns for LangChain4j with Spring Boot.
Property-Based Configuration
Core Configuration Properties
application.yml
langchain4j:
# OpenAI Configuration
open-ai:
chat-model:
api-key: ${OPENAI_API_KEY}
model-name: gpt-4o-mini
temperature: 0.7
max-tokens: 1000
log-requests: true
log-responses: true
timeout: PT60S
max-retries: 3
organization: ${OPENAI_ORGANIZATION:}
embedding-model:
api-key: ${OPENAI_API_KEY}
model-name: text-embedding-3-small
dimensions: 1536
timeout: PT60S
streaming-chat-model:
api-key: ${OPENAI_API_KEY}
model-name: gpt-4o-mini
temperature: 0.7
max-tokens: 2000
# Azure OpenAI Configuration
azure-open-ai:
chat-model:
endpoint: ${AZURE_OPENAI_ENDPOINT}
api-key: ${AZURE_OPENAI_KEY}
deployment-name: gpt-4o
service-version: 2024-02-15-preview
temperature: 0.7
max-tokens: 1000
log-requests-and-responses: true
embedding-model:
endpoint: ${AZURE_OPENAI_ENDPOINT}
api-key: ${AZURE_OPENAI_KEY}
deployment-name: text-embedding-3-small
dimensions: 1536
# Anthropic Configuration
anthropic:
chat-model:
api-key: ${ANTHROPIC_API_KEY}
model-name: claude-3-5-sonnet-20241022
max-tokens: 4000
temperature: 0.7
streaming-chat-model:
api-key: ${ANTHROPIC_API_KEY}
model-name: claude-3-5-sonnet-20241022
# Ollama Configuration
ollama:
chat-model:
base-url: http://localhost:11434
model-name: llama3.1
temperature: 0.8
timeout: PT60S
# Memory Configuration
memory:
store-type: in-memory # in-memory, postgresql, mysql, mongodb
max-messages: 20
window-size: 10
# Vector Store Configuration
vector-store:
type: in-memory # in-memory, pinecone, weaviate, qdrant, postgresql
pinecone:
api-key: ${PINECONE_API_KEY}
index-name: my-index
namespace: production
qdrant:
host: localhost
port: 6333
collection-name: documents
weaviate:
host: localhost
port: 8080
collection-name: Documents
postgresql:
table: document_embeddings
dimension: 1536
Spring Profiles Configuration
application-dev.yml
langchain4j:
open-ai:
chat-model:
api-key: ${OPENAI_API_KEY_DEV}
model-name: gpt-4o-mini
temperature: 0.8 # Higher temperature for experimentation
log-requests: true
log-responses: true
vector-store:
type: in-memory
application-prod.yml
langchain4j:
open-ai:
chat-model:
api-key: ${OPENAI_API_KEY_PROD}
model-name: gpt-4o
temperature: 0.3 # Lower temperature for consistency
log-requests: false
log-responses: false
vector-store:
type: pinecone
pinecone:
api-key: ${PINECONE_API_KEY_PROD}
index-name: production-knowledge-base
Manual Bean Configuration
Advanced Chat Model Configuration
@Configuration
@Profile("custom-openai")
public class CustomOpenAiConfiguration {
@Bean
@Primary
public ChatModel customOpenAiChatModel(
@Value("${custom.openai.api.key}") String apiKey,
@Value("${custom.openai.model}") String model,
@Value("${custom.openai.temperature}") Double temperature) {
OpenAiChatModelBuilder builder = OpenAiChatModel.builder()
.apiKey(apiKey)
.modelName(model)
.temperature(temperature);
if (Boolean.TRUE.equals(env.getProperty("custom.openai.log-requests", Boolean.class))) {
builder.logRequests(true);
}
if (Boolean.TRUE.equals(env.getProperty("custom.openai.log-responses", Boolean.class))) {
builder.logResponses(true);
}
return builder.build();
}
@Bean
@ConditionalOnProperty(name = "custom.openai.proxy.enabled", havingValue = "true")
public ChatModel proxiedChatModel(ChatModel delegate) {
return new ProxiedChatModel(delegate,
env.getProperty("custom.openai.proxy.url"),
env.getProperty("custom.openai.proxy.username"),
env.getProperty("custom.openai.proxy.password"));
}
}
class ProxiedChatModel implements ChatModel {
private final ChatModel delegate;
private final String proxyUrl;
private final String username;
private final String password;
public ProxiedChatModel(ChatModel delegate, String proxyUrl, String username, String password) {
this.delegate = delegate;
this.proxyUrl = proxyUrl;
this.username = username;
this.password = password;
}
@Override
public Response<AiMessage> generate(ChatRequest request) {
// Apply proxy configuration
// Make request through proxy
return delegate.generate(request);
}
}
Multiple Provider Configuration
@Configuration
public class MultiProviderConfiguration {
@Bean("openAiChatModel")
public ChatModel openAiChatModel(
@Value("${openai.api.key}") String apiKey,
@Value("${openai.model.name}") String modelName) {
return OpenAiChatModel.builder()
.apiKey(apiKey)
.modelName(modelName)
.temperature(0.7)
.logRequests(env.acceptsProfiles("dev"))
.build();
}
@Bean("anthropicChatModel")
public ChatModel anthropicChatModel(
@Value("${anthropic.api.key}") String apiKey,
@Value("${anthropic.model.name}") String modelName) {
return AnthropicChatModel.builder()
.apiKey(apiKey)
.modelName(modelName)
.maxTokens(4000)
.build();
}
@Bean("ollamaChatModel")
@ConditionalOnProperty(name = "ollama.enabled", havingValue = "true")
public ChatModel ollamaChatModel(
@Value("${ollama.base-url}") String baseUrl,
@Value("${ollama.model.name}") String modelName) {
return OllamaChatModel.builder()
.baseUrl(baseUrl)
.modelName(modelName)
.temperature(0.8)
.build();
}
}
Explicit Wiring Configuration
@AiService(wiringMode = EXPLICIT, chatModel = "productionChatModel")
interface ProductionAssistant {
@SystemMessage("You are a production-grade AI assistant providing high-quality, reliable responses.")
String chat(String message);
}
@AiService(wiringMode = EXPLICIT, chatModel = "developmentChatModel")
interface DevelopmentAssistant {
@SystemMessage("You are a development assistant helping with code and debugging. " +
"Be experimental and creative in your responses.")
String chat(String message);
}
@AiService(wiringMode = EXPLICIT,
chatModel = "specializedChatModel",
tools = "businessTools")
interface SpecializedAssistant {
@SystemMessage("You are a specialized assistant with access to business tools. " +
"Use the available tools to provide accurate information.")
String chat(String message);
}
@Component("businessTools")
public class BusinessLogicTools {
@Tool("Calculate discount based on customer status")
public BigDecimal calculateDiscount(
@P("Purchase amount") BigDecimal amount,
@P("Customer status") String customerStatus) {
return switch (customerStatus.toLowerCase()) {
case "vip" -> amount.multiply(new BigDecimal("0.15"));
case "premium" -> amount.multiply(new BigDecimal("0.10"));
case "standard" -> amount.multiply(new BigDecimal("0.05"));
default -> BigDecimal.ZERO;
};
}
}
Embedding Store Configuration
PostgreSQL with pgvector
@Configuration
@RequiredArgsConstructor
public class PostgresEmbeddingStoreConfiguration {
@Bean
public EmbeddingStore<TextSegment> postgresEmbeddingStore(
DataSource dataSource,
@Value("${spring.datasource.schema}") String schema) {
return PgVectorEmbeddingStore.builder()
.dataSource(dataSource)
.table("document_embeddings")
.dimension(1536)
.initializeSchema(true)
.schema(schema)
.indexName("document_embeddings_idx")
.build();
}
@Bean
public ContentRetriever postgresContentRetriever(
EmbeddingStore<TextSegment> embeddingStore,
EmbeddingModel embeddingModel) {
return EmbeddingStoreContentRetriever.builder()
.embeddingStore(embeddingStore)
.embeddingModel(embeddingModel)
.maxResults(5)
.minScore(0.7)
.build();
}
}
Pinecone Configuration
@Configuration
@Profile("pinecone")
public class PineconeConfiguration {
@Bean
public EmbeddingStore<TextSegment> pineconeEmbeddingStore(
@Value("${pinecone.api.key}") String apiKey,
@Value("${pinecone.index.name}") String indexName,
@Value("${pinecone.namespace}") String namespace) {
PineconeEmbeddingStore store = PineconeEmbeddingStore.builder()
.apiKey(apiKey)
.indexName(indexName)
.namespace(namespace)
.build();
// Initialize if needed
if (!store.indexExists()) {
store.createIndex(1536);
}
return store;
}
}
Custom Embedding Store
@Component
public class CustomEmbeddingStore implements EmbeddingStore<TextSegment> {
private final Map<UUID, TextSegment> embeddings = new ConcurrentHashMap<>();
private final Map<UUID, float[]> vectors = new ConcurrentHashMap<>();
@Override
public void add(Embedding embedding, TextSegment textSegment) {
UUID id = UUID.randomUUID();
embeddings.put(id, textSegment);
vectors.put(id, embedding.vector());
}
@Override
public void addAll(List<Embedding> embeddings, List<TextSegment> textSegments) {
for (int i = 0; i < embeddings.size(); i++) {
add(embeddings.get(i), textSegments.get(i));
}
}
@Override
public List<Embedding> findRelevant(Embedding embedding, int maxResults) {
return vectors.entrySet().stream()
.sorted(Comparator.comparingDouble(e -> cosineSimilarity(e.getValue(), embedding.vector())))
.limit(maxResults)
.map(e -> new EmbeddingImpl(e.getValue(), embeddings.get(e.getKey()).id()))
.collect(Collectors.toList());
}
private double cosineSimilarity(float[] vec1, float[] vec2) {
// Implementation of cosine similarity
return 0.0;
}
}
Memory Configuration
Chat Memory Store Configuration
@Configuration
public class MemoryConfiguration {
@Bean
@Profile("in-memory")
public ChatMemoryStore inMemoryChatMemoryStore() {
return new InMemoryChatMemoryStore();
}
@Bean
@Profile("database")
public ChatMemoryStore databaseChatMemoryStore(ChatMessageRepository messageRepository) {
return new DatabaseChatMemoryStore(messageRepository);
}
@Bean
public ChatMemoryProvider chatMemoryProvider(ChatMemoryStore memoryStore) {
return memoryId -> MessageWindowChatMemory.builder()
.id(memoryId)
.maxMessages(getMaxMessages())
.chatMemoryStore(memoryStore)
.build();
}
private int getMaxMessages() {
return env.getProperty("langchain4j.memory.max-messages", int.class, 20);
}
}
Database Chat Memory Store
@Component
@RequiredArgsConstructor
public class DatabaseChatMemoryStore implements ChatMemoryStore {
private final ChatMessageRepository repository;
@Override
public List<ChatMessage> getMessages(Object memoryId) {
return repository.findByMemoryIdOrderByCreatedAtAsc(memoryId.toString())
.stream()
.map(this::toMessage)
.collect(Collectors.toList());
}
@Override
public void updateMessages(Object memoryId, List<ChatMessage> messages) {
String id = memoryId.toString();
repository.deleteByMemoryId(id);
List<ChatMessageEntity> entities = messages.stream()
.map(msg -> toEntity(id, msg))
.collect(Collectors.toList());
repository.saveAll(entities);
}
private ChatMessage toMessage(ChatMessageEntity entity) {
return switch (entity.getMessageType()) {
case USER -> UserMessage.from(entity.getContent());
case AI -> AiMessage.from(entity.getContent());
case SYSTEM -> SystemMessage.from(entity.getContent());
};
}
private ChatMessageEntity toEntity(String memoryId, ChatMessage message) {
ChatMessageEntity entity = new ChatMessageEntity();
entity.setMemoryId(memoryId);
entity.setContent(message.text());
entity.setCreatedAt(LocalDateTime.now());
entity.setMessageType(determineMessageType(message));
return entity;
}
private MessageType determineMessageType(ChatMessage message) {
if (message instanceof UserMessage) return MessageType.USER;
if (message instanceof AiMessage) return MessageType.AI;
if (message instanceof SystemMessage) return MessageType.SYSTEM;
throw new IllegalArgumentException("Unknown message type: " + message.getClass());
}
}
Observability Configuration
Monitoring and Metrics
@Configuration
public class ObservabilityConfiguration {
@Bean
public ChatModelListener chatModelListener(MeterRegistry meterRegistry) {
return new MonitoringChatModelListener(meterRegistry);
}
@Bean
public HealthIndicator aiHealthIndicator(ChatModel chatModel) {
return new AiHealthIndicator(chatModel);
}
}
class MonitoringChatModelListener implements ChatModelListener {
private final MeterRegistry meterRegistry;
private final Counter requestCounter;
private final Timer responseTimer;
public MonitoringChatModelListener(MeterRegistry meterRegistry) {
this.meterRegistry = meterRegistry;
this.requestCounter = Counter.builder("ai.requests.total")
.description("Total AI requests")
.register(meterRegistry);
this.responseTimer = Timer.builder("ai.response.duration")
.description("AI response time")
.register(meterRegistry);
}
@Override
public void onRequest(ChatModelRequestContext requestContext) {
requestCounter.increment();
logRequest(requestContext);
}
@Override
public void onResponse(ChatModelResponseContext responseContext) {
responseTimer.record(responseContext.duration());
logResponse(responseContext);
}
private void logRequest(ChatModelRequestContext requestContext) {
meterRegistry.gauge("ai.request.tokens",
requestContext.request().messages().size());
}
private void logResponse(ChatModelResponseContext responseContext) {
Response<AiMessage> response = responseContext.response();
meterRegistry.gauge("ai.response.tokens",
response.tokenUsage().totalTokenCount());
}
}
Custom Health Check
@Component
@RequiredArgsConstructor
public class AiHealthIndicator implements HealthIndicator {
private final ChatModel chatModel;
private final EmbeddingModel embeddingModel;
@Override
public Health health() {
try {
// Test chat model
Health.Builder builder = Health.up();
String chatResponse = chatModel.chat("ping");
builder.withDetail("chat_model", "healthy");
if (chatResponse == null || chatResponse.trim().isEmpty()) {
return Health.down().withDetail("reason", "Empty response");
}
// Test embedding model
List<String> testTexts = List.of("test", "ping", "hello");
List<Embedding> embeddings = embeddingModel.embedAll(testTexts).content();
if (embeddings.isEmpty()) {
return Health.down().withDetail("reason", "No embeddings generated");
}
builder.withDetail("embedding_model", "healthy")
.withDetail("embedding_dimension", embeddings.get(0).vector().length);
return builder.build();
} catch (Exception e) {
return Health.down()
.withDetail("error", e.getMessage())
.withDetail("exception_class", e.getClass().getSimpleName());
}
}
}
Security Configuration
API Key Security
@Configuration
@EnableWebSecurity
public class SecurityConfig {
@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
http
.csrf().disable()
.authorizeRequests()
.requestMatchers("/api/ai/**").hasRole("AI_USER")
.requestMatchers("/actuator/ai/**").hasRole("AI_ADMIN")
.anyRequest().permitAll()
.and()
.httpBasic();
return http.build();
}
@Bean
public ApiKeyAuthenticationFilter apiKeyAuthenticationFilter() {
return new ApiKeyAuthenticationFilter("/api/ai/**");
}
}
class ApiKeyAuthenticationFilter extends OncePerRequestFilter {
private final String pathPrefix;
public ApiKeyAuthenticationFilter(String pathPrefix) {
this.pathPrefix = pathPrefix;
}
@Override
protected void doFilterInternal(HttpServletRequest request,
HttpServletResponse response,
FilterChain filterChain) throws ServletException, IOException {
if (request.getRequestURI().startsWith(pathPrefix)) {
String apiKey = request.getHeader("X-API-Key");
if (apiKey == null || !isValidApiKey(apiKey)) {
response.sendError(HttpServletResponse.SC_UNAUTHORIZED, "Invalid API key");
return;
}
}
filterChain.doFilter(request, response);
}
private boolean isValidApiKey(String apiKey) {
// Validate API key against database or security service
return true;
}
}
Configuration Validation
@Component
@RequiredArgsConstructor
@Slf4j
public class AiConfigurationValidator implements InitializingBean {
private final AiProperties properties;
@Override
public void afterPropertiesSet() {
validateConfiguration();
}
private void validateConfiguration() {
if (properties.getOpenai() != null) {
validateOpenAiConfiguration();
}
if (properties.getAzureOpenAi() != null) {
validateAzureConfiguration();
}
if (properties.getAnthropic() != null) {
validateAnthropicConfiguration();
}
log.info("AI configuration validation completed successfully");
}
private void validateOpenAiConfiguration() {
OpenAiProperties openAi = properties.getOpenai();
if (openAi.getChatModel() != null &&
(openAi.getChatModel().getApiKey() == null ||
openAi.getChatModel().getApiKey().isEmpty())) {
log.warn("OpenAI chat model API key is not configured");
}
if (openAi.getChatModel() != null &&
openAi.getChatModel().getMaxTokens() != null &&
openAi.getChatModel().getMaxTokens() > 8192) {
log.warn("OpenAI max tokens {} exceeds recommended limit of 8192",
openAi.getChatModel().getMaxTokens());
}
}
private void validateAzureConfiguration() {
AzureOpenAiProperties azure = properties.getAzureOpenAi();
if (azure.getChatModel() != null &&
(azure.getChatModel().getEndpoint() == null ||
azure.getChatModel().getApiKey() == null)) {
log.error("Azure OpenAI endpoint or API key is not configured");
}
}
private void validateAnthropicConfiguration() {
AnthropicProperties anthropic = properties.getAnthropic();
if (anthropic.getChatModel() != null &&
(anthropic.getChatModel().getApiKey() == null ||
anthropic.getChatModel().getApiKey().isEmpty())) {
log.warn("Anthropic chat model API key is not configured");
}
}
}
@Configuration
@ConfigurationProperties(prefix = "langchain4j")
@Validated
@Data
public class AiProperties {
private OpenAiProperties openai;
private AzureOpenAiProperties azureOpenAi;
private AnthropicProperties anthropic;
private MemoryProperties memory;
private VectorStoreProperties vectorStore;
// Validation annotations for properties
}
@Data
@Validated
public class OpenAiProperties {
private ChatModelProperties chatModel;
private EmbeddingModelProperties embeddingModel;
private StreamingChatModelProperties streamingChatModel;
@Valid
@NotNull
public ChatModelProperties getChatModel() {
return chatModel;
}
}
Environment-Specific Configurations
Development Configuration
# application-dev.yml
langchain4j:
open-ai:
chat-model:
api-key: ${OPENAI_API_KEY_DEV}
model-name: gpt-4o-mini
temperature: 0.8
log-requests: true
log-responses: true
memory:
store-type: in-memory
max-messages: 10
vector-store:
type: in-memory
logging:
level:
dev.langchain4j: DEBUG
org.springframework.ai: DEBUG
Production Configuration
# application-prod.yml
langchain4j:
open-ai:
chat-model:
api-key: ${OPENAI_API_KEY_PROD}
model-name: gpt-4o
temperature: 0.3
log-requests: false
log-responses: false
max-tokens: 4000
memory:
store-type: postgresql
max-messages: 5
vector-store:
type: pinecone
pinecone:
index-name: production-knowledge-base
namespace: prod
logging:
level:
dev.langchain4j: WARN
org.springframework.ai: WARN
management:
endpoints:
web:
exposure:
include: health, metrics, info
endpoint:
health:
show-details: when-authorized
This configuration guide provides comprehensive options for setting up LangChain4j with Spring Boot, covering various providers, storage backends, monitoring, and security considerations.