스프링 프로젝트에 Langfuse 도입하기 [1] — 프롬프트 관리와 트레이싱

<dependency>
    <groupId>com.langfuse</groupId>
    <artifactId>langfuse-java</artifactId>
    <version>0.1.2</version>
</dependency>

implementation 'com.langfuse:langfuse-java:0.1.2'

@Configuration
@ConditionalOnProperty(prefix = "langfuse", name = "enabled", havingValue = "true")
public class LangfuseConfig {
 
    @Value("${langfuse.public-key}")
    private String publicKey;
 
    @Value("${langfuse.secret-key}")
    private String secretKey;
 
    @Value("${langfuse.base-url}")
    private String baseUrl;
 
    @Value("${langfuse.okhttp.keepalive.duration:20}")
    private int keepAliveDuration;
 
    @Value("${langfuse.okhttp.connection.pool.max:20}")
    private int maxIdleConnections;
 
    @Bean
    public OkHttpClient langfuseOkHttpClient() {
        ConnectionPool pool = new ConnectionPool(
            maxIdleConnections,
            keepAliveDuration,
            TimeUnit.SECONDS
        );
        return new OkHttpClient.Builder()
                .connectionPool(pool)
                .build();
    }
 
    @Bean
    public LangfuseClient langfuseClient(OkHttpClient langfuseOkHttpClient) {
        return LangfuseClient.builder()
                .url(baseUrl)
                .credentials(publicKey, secretKey)
                .httpClient(langfuseOkHttpClient)
                .timeout(10)
                .build();
    }
}

langfuse:
  enabled: true
  base-url: https://us.cloud.langfuse.com
  public-key: ${LANGFUSE_PUBLIC_KEY}
  secret-key: ${LANGFUSE_SECRET_KEY}
  okhttp:
    keepalive:
      duration: 20
    connection:
      pool:
        max: 20
  cache:
    ttl-seconds: 1800
  trace:
    enabled: true

String maskedKey = publicKey != null && publicKey.length() > 4
    ? "****" + publicKey.substring(publicKey.length() - 4)
    : "NOT_SET";
log.info("[LangfuseConfig] publicKey: {}", maskedKey);

public interface LangfusePromptService {
    PromptWithConfig resolvePrompt(LLMPromptRequest request);
}

public record PromptWithConfig(
    String promptText,
    PromptConfigData config,
    String promptName,
    Integer promptVersion
) {
    public static PromptWithConfig fallback(String text, String name) {
        return new PromptWithConfig(text, PromptConfigData.defaults(), name, null);
    }
}

public class PromptConfigData {
    private String provider;        // "openai", "anthropic"
    private String model;           // "gpt-4o", "claude-sonnet-4-20250514"
    private Double temperature;
    private Integer maxTokens;
 
    public String getProviderOrDefault() {
        return provider != null ? provider : "openai";
    }
 
    public String getModelOrDefault() {
        return model != null ? model : "gpt-4o";
    }
}

public record LLMPromptRequest(
    String promptName,
    Map<String, Object> promptVariables,
    String fallbackPrompt
) {
    public static LLMPromptRequest of(String promptName) {
        return new LLMPromptRequest(promptName, Map.of(), null);
    }
 
    public static LLMPromptRequest of(String promptName,
                                       Map<String, Object> variables,
                                       String fallbackPrompt) {
        return new LLMPromptRequest(promptName, variables, fallbackPrompt);
    }
}

public class PromptVariableReplacer {
 
    private static final Pattern VARIABLE_PATTERN =
        Pattern.compile("\\{\\{(\\w+(?:\\.\\w+)*)}}");
 
    public static String replace(String template, Map<String, Object> variables) {
        if (template == null || variables == null || variables.isEmpty()) {
            return template;
        }
 
        Matcher matcher = VARIABLE_PATTERN.matcher(template);
        StringBuilder result = new StringBuilder();
        while (matcher.find()) {
            String varName = matcher.group(1);
            Object value = variables.get(varName);
            if (value != null) {
                matcher.appendReplacement(result,
                    Matcher.quoteReplacement(String.valueOf(value)));
            }
        }
        matcher.appendTail(result);
        return result.toString();
    }
}

public enum PromptLabel {
    DEV("development"),
    PR("production"),
    LATEST("latest");
 
    private final String value;
 
    public List<PromptLabel> fallbackChain() {
        return switch (this) {
            case DEV -> List.of(DEV, PR, LATEST);
            case PR -> List.of(PR, LATEST);
            case LATEST -> List.of(LATEST);
        };
    }
}

@Component
public class LangfuseEnvironmentConfig {
 
    @Value("${spring.profiles.active:local}")
    private String activeProfile;
 
    public PromptLabel getPromptLabel() {
        if ("production".equals(activeProfile)) {
            return PromptLabel.PR;
        }
        return PromptLabel.DEV;
    }
}

@Service
@ConditionalOnProperty(prefix = "langfuse", name = "enabled", havingValue = "true")
@RequiredArgsConstructor
public class LangfusePromptServiceImpl implements LangfusePromptService {
 
    private final LangfuseClient langfuseClient;
    private final LangfuseEnvironmentConfig envConfig;
 
    @Override
    public PromptWithConfig resolvePrompt(LLMPromptRequest request) {
        PromptLabel label = envConfig.getPromptLabel();
 
        for (PromptLabel candidate : label.fallbackChain()) {
            try {
                return getPrompt(
                    request.promptName(),
                    candidate,
                    request.promptVariables()
                );
            } catch (PromptLoadException e) {
                log.warn("[Langfuse] {} 라벨로 프롬프트 조회 실패, 다음 시도",
                    candidate.getValue());
            }
        }
 
        // 모든 라벨 실패 → fallback 프롬프트 사용
        String compiled = PromptVariableReplacer.replace(
            request.fallbackPrompt(),
            request.promptVariables()
        );
        return PromptWithConfig.fallback(compiled, request.promptName());
    }
 
    private PromptWithConfig getPrompt(String promptName,
                                        PromptLabel label,
                                        Map<String, Object> variables) {
        GetPromptRequest getRequest = GetPromptRequest.builder()
                .label(label.getValue())
                .build();
 
        Prompt prompt = langfuseClient.prompts()
                .get(promptName, getRequest);
 
        String text = PromptExtractor.extractText(prompt);
        PromptConfigData config = PromptExtractor.extractConfig(prompt);
        Integer version = PromptExtractor.extractVersion(prompt);
 
        String compiled = PromptVariableReplacer.replace(text, variables);
 
        return PromptWithConfig.of(compiled, config, promptName, version);
    }
}

public final class PromptExtractor {
 
    private static final ObjectMapper OBJECT_MAPPER = new ObjectMapper()
        .configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);
 
    public static String extractText(Prompt prompt) {
        if (prompt.isText()) {
            return prompt.getText()
                .orElseThrow(() -> new PromptLoadException("Text prompt is empty"))
                .getPrompt();
        }
 
        if (prompt.isChat()) {
            ChatPrompt chatPrompt = prompt.getChat()
                .orElseThrow(() -> new PromptLoadException("Chat prompt is empty"));
 
            // Chat 프롬프트는 여러 메시지(system, user 등)를 줄바꿈으로 결합
            StringBuilder combined = new StringBuilder();
            for (ChatMessageWithPlaceholders msg : chatPrompt.getPrompt()) {
                if (msg.isChatmessage() && msg.getChatmessage().isPresent()) {
                    if (!combined.isEmpty()) combined.append("\n\n");
                    combined.append(msg.getChatmessage().get().getContent());
                }
            }
            return combined.toString();
        }
 
        throw new PromptLoadException("Unknown prompt type");
    }
 
    public static PromptConfigData extractConfig(Prompt prompt) {
        try {
            Object config = prompt.isText()
                ? prompt.getText().map(TextPrompt::getConfig).orElse(null)
                : prompt.getChat().map(ChatPrompt::getConfig).orElse(null);
 
            if (config != null) {
                return OBJECT_MAPPER.convertValue(config, PromptConfigData.class);
            }
        } catch (Exception e) {
            log.warn("[PromptExtractor] config 추출 실패", e);
        }
        return PromptConfigData.defaults();
    }
 
    public static Integer extractVersion(Prompt prompt) {
        if (prompt.isText()) return prompt.getText().map(TextPrompt::getVersion).orElse(null);
        if (prompt.isChat()) return prompt.getChat().map(ChatPrompt::getVersion).orElse(null);
        return null;
    }
}

public record TraceRequest(
    String name,
    Object input,
    Map<String, Object> metadata
) {}
 
public record GenerationRequest(
    String traceId,
    String name,
    String model,
    Object input,
    Object output,
    Map<String, Object> metadata,
    OffsetDateTime startTime
) {
    public String promptName() {
        return metadata != null ? (String) metadata.get("promptName") : null;
    }
 
    public Integer promptVersion() {
        Object value = metadata != null ? metadata.get("promptVersion") : null;
        if (value instanceof Integer i) return i;
        if (value instanceof Number n) return n.intValue();
        return null;
    }
}

public interface LangfuseTraceService {
    boolean isEnabled();
    String createTrace(TraceRequest request);
    void recordGeneration(GenerationRequest request);
    void endTrace(String traceId, Object output);
    void flush();
}

@Service
@ConditionalOnProperty(prefix = "langfuse.trace", name = "enabled", havingValue = "true")
@RequiredArgsConstructor
public class LangfuseTraceServiceImpl implements LangfuseTraceService {
 
    private final LangfuseClient langfuseClient;
    private final ConcurrentLinkedQueue<IngestionEvent> eventBuffer
        = new ConcurrentLinkedQueue<>();
    private static final int BATCH_SIZE = 10;
 
    @Override
    public boolean isEnabled() { return true; }
 
    @Override
    public String createTrace(TraceRequest request) {
        String traceId = UUID.randomUUID().toString();
        OffsetDateTime now = OffsetDateTime.now();
 
        TraceEvent traceEvent = TraceEvent.builder()
            .id(UUID.randomUUID().toString())
            .timestamp(now.format(DateTimeFormatter.ISO_OFFSET_DATE_TIME))
            .body(TraceBody.builder()
                .id(traceId)
                .name(request.name())
                .timestamp(now)
                .input(request.input())
                .metadata(request.metadata())
                .build())
            .build();
 
        addToBuffer(IngestionEvent.traceCreate(traceEvent));
        return traceId;
    }
 
    @Override
    public void recordGeneration(GenerationRequest request) {
        String generationId = UUID.randomUUID().toString();
        OffsetDateTime now = OffsetDateTime.now();
 
        CreateGenerationEvent event = CreateGenerationEvent.builder()
            .id(UUID.randomUUID().toString())
            .timestamp(now.format(DateTimeFormatter.ISO_OFFSET_DATE_TIME))
            .body(CreateGenerationBody.builder()
                .id(generationId)
                .traceId(request.traceId())
                .name(request.name())
                .model(request.model())
                .startTime(request.startTime())
                .endTime(now)
                .input(request.input())
                .output(request.output())
                .promptName(request.promptName())
                .promptVersion(request.promptVersion())
                .metadata(request.metadata())
                .build())
            .build();
 
        addToBuffer(IngestionEvent.generationCreate(event));
    }
 
    @Override
    public void endTrace(String traceId, Object output) {
        OffsetDateTime now = OffsetDateTime.now();
 
        TraceEvent traceEvent = TraceEvent.builder()
            .id(UUID.randomUUID().toString())
            .timestamp(now.format(DateTimeFormatter.ISO_OFFSET_DATE_TIME))
            .body(TraceBody.builder()
                .id(traceId)
                .output(output)
                .build())
            .build();
 
        addToBuffer(IngestionEvent.traceCreate(traceEvent));
        flush();
    }
 
    @Override
    public void flush() {
        List<IngestionEvent> events = new ArrayList<>();
        IngestionEvent event;
        while ((event = eventBuffer.poll()) != null) {
            events.add(event);
        }
        if (events.isEmpty()) return;
 
        try {
            IngestionRequest request = IngestionRequest.builder()
                .batch(events)
                .build();
            langfuseClient.ingestion().batch(request);
        } catch (Exception e) {
            log.error("[LangfuseTrace] flush 실패", e);
        }
    }
 
    private void addToBuffer(IngestionEvent event) {
        eventBuffer.add(event);
        if (eventBuffer.size() >= BATCH_SIZE) {
            flush();
        }
    }
}

@Service
@ConditionalOnProperty(
    prefix = "langfuse", name = "enabled",
    havingValue = "false", matchIfMissing = true
)
public class NoOpLangfusePromptService implements LangfusePromptService {
 
    @Override
    public PromptWithConfig resolvePrompt(LLMPromptRequest request) {
        String compiled = PromptVariableReplacer.replace(
            request.fallbackPrompt(),
            request.promptVariables()
        );
        return PromptWithConfig.fallback(compiled, request.promptName());
    }
}

@Service
@ConditionalOnProperty(
    prefix = "langfuse.trace", name = "enabled",
    havingValue = "false", matchIfMissing = true
)
public class NoOpLangfuseTraceService implements LangfuseTraceService {
 
    @Override
    public boolean isEnabled() { return false; }
 
    @Override
    public String createTrace(TraceRequest request) {
        return UUID.randomUUID().toString();
    }
 
    @Override
    public void recordGeneration(GenerationRequest request) { }
 
    @Override
    public void endTrace(String traceId, Object output) { }
 
    @Override
    public void flush() { }
}

@Component
@RequiredArgsConstructor
public class LLMServiceImpl implements LLMService {
 
    private final ChatModelSelector chatModelSelector;
    private final LangfusePromptService langfusePromptService;
    private final LangfuseTraceService langfuseTraceService;
 
    @Override
    public <T> T chat(LLMPromptRequest promptRequest,
                      Collection<LLMMessage> messages,
                      Class<T> responseType) {
 
        // 1. 프롬프트 조회 (Langfuse or fallback)
        PromptWithConfig prompt = langfusePromptService.resolvePrompt(promptRequest);
 
        // 2. Config에서 provider/model 결정
        ChatModel chatModel = chatModelSelector.select(prompt.config());
 
        // 3. 메타데이터 구성
        Map<String, Object> metadata = Map.of(
            "provider", prompt.config().getProviderOrDefault(),
            "model", prompt.config().getModelOrDefault(),
            "promptName", prompt.promptName(),
            "promptVersion", prompt.promptVersion() != null ? prompt.promptVersion() : 0
        );
 
        OffsetDateTime startTime = OffsetDateTime.now();
 
        try {
            // 4. LLM 호출
            String rawResponse = chatModel.call(prompt.promptText(), messages);
            T response = parseResponse(rawResponse, responseType);
 
            // 5. 성공 트레이싱
            String traceId = langfuseTraceService.createTrace(
                new TraceRequest(prompt.promptName(), messages, metadata));
            langfuseTraceService.recordGeneration(
                new GenerationRequest(
                    traceId, prompt.promptName(),
                    prompt.config().getModelOrDefault(),
                    messages, response, metadata, startTime));
            langfuseTraceService.endTrace(traceId, response);
 
            return response;
 
        } catch (Exception e) {
            // 6. 실패 트레이싱
            String traceId = langfuseTraceService.createTrace(
                new TraceRequest(prompt.promptName(), messages, metadata));
            langfuseTraceService.endTrace(traceId, Map.of("error", e.getMessage()));
            throw e;
        }
    }
}

public interface PromptId {
    String promptName();       // Langfuse에 등록된 프롬프트 이름
    String description();      // 문서화용 설명
    default String fallbackPrompt() { return null; }
}

public enum SummaryPrompt implements PromptId {
 
    DOCUMENT_SUMMARY(
        "document_summary",
        "문서를 요약하는 프롬프트",
        """
        다음 문서를 읽고 핵심 내용을 3~5줄로 요약하세요.
 
        문서:
        {{document}}
 
        응답은 반드시 다음 JSON 형식으로만 반환하세요:
        {"summary": "요약 텍스트", "keywords": ["키워드1", "키워드2"]}
        """
    ),
 
    FEEDBACK_ANALYSIS(
        "feedback_analysis",
        "사용자 피드백을 분석하여 감성과 핵심 이슈를 추출하는 프롬프트",
        """
        다음 사용자 피드백을 분석하세요.
 
        피드백:
        {{feedback}}
 
        응답은 반드시 다음 JSON 형식으로만 반환하세요:
        {"sentiment": "positive/negative/neutral", "issues": ["이슈1", "이슈2"]}
        """
    );
 
    private final String promptName;
    private final String description;
    private final String fallbackPrompt;
 
    // 생성자, getter 생략
 
    @Override
    public String promptName() { return promptName; }
 
    @Override
    public String description() { return description; }
 
    @Override
    public String fallbackPrompt() { return fallbackPrompt; }
}

public enum BriefingPrompt implements PromptId {
 
    WEEKLY_BRIEFING(
        "weekly_briefing",
        "주간 데이터 기반 AI 브리핑 생성"
    );
 
    // fallbackPrompt()는 기본값 null → Langfuse 실패 시 빈 결과 반환
}

@Service
@RequiredArgsConstructor
public class DocumentSummaryService {
 
    private final LLMService llmService;
 
    public SummaryResultDto summarize(String documentText) {
 
        return llmService.chat(
            LLMPromptRequest.of(
                SummaryPrompt.DOCUMENT_SUMMARY.promptName(),
                Map.of("document", documentText),
                SummaryPrompt.DOCUMENT_SUMMARY.fallbackPrompt()
            ),
            List.of(new LLMMessage.User(documentText)),
            SummaryResultDto.class
        );
    }
}

LLMPromptRequest request = PromptRequestBuilder
    .from(SummaryPrompt.FEEDBACK_ANALYSIS)
    .variable("feedback", userFeedbackText)
    .variable("targetDate", "2026-03-01")
    .build();
 
llmService.chat(request, messages, FeedbackResultDto.class);