// 錯(cuò)誤：直接使用LangChain4j，不知其所以然
@Service
public class BadAgentService {

    @Inject
    ChatLanguageModel model;

    public String chat(String message) {
        // 只會(huì)調(diào)用API，不理解背后的原理
        return model.generate(message);
        // 問(wèn)題：Prompt怎么優(yōu)化？失敗怎么辦？成本如何控制？
    }
}

import com.fasterxml.jackson.databind.ObjectMapper;
import okhttp3.*;
import java.io.IOException;
import java.util.*;

/**
 * LLM客戶(hù)端基礎(chǔ)實(shí)現(xiàn)
 * 理解LLM調(diào)用的核心原理后再使用框架
 */
public class LLMClient {

    private static final String API_URL = "https://api.openai.com/v1/chat/completions";
    private final String apiKey;
    private final OkHttpClient httpClient;
    private final ObjectMapper objectMapper;

    public LLMClient(String apiKey) {
        this.apiKey = apiKey;
        this.httpClient = new OkHttpClient();
        this.objectMapper = new ObjectMapper();
    }

    /**
     * 基礎(chǔ)聊天完成請(qǐng)求
     * 理解參數(shù)含義：temperature、max_tokens等
     */
    public String chat(String userMessage, String systemPrompt) throws IOException {
        // 構(gòu)建請(qǐng)求體 - 理解消息格式
        Map<String, Object> requestBody = new HashMap<>();
        requestBody.put("model", "gpt-3.5-turbo");

        // 理解角色系統(tǒng)：system/user/assistant
        List<Map<String, String>> messages = new ArrayList<>();
        messages.add(Map.of("role", "system", "content", systemPrompt));
        messages.add(Map.of("role", "user", "content", userMessage));
        requestBody.put("messages", messages);

        // 理解參數(shù)作用
        requestBody.put("temperature", 0.7);  // 控制隨機(jī)性
        requestBody.put("max_tokens", 2000);  // 控制輸出長(zhǎng)度
        requestBody.put("top_p", 1.0);        // 核采樣

        // 發(fā)送請(qǐng)求 - 理解HTTP通信
        Request request = new Request.Builder()
                .url(API_URL)
                .addHeader("Authorization", "Bearer " + apiKey)
                .addHeader("Content-Type", "application/json")
                .post(RequestBody.create(
                        objectMapper.writeValueAsString(requestBody),
                        MediaType.parse("application/json")
                ))
                .build();

        try (Response response = httpClient.newCall(request).execute()) {
            if (!response.isSuccessful()) {
                throw new IOException("API調(diào)用失敗: " + response.code());
            }

            String responseBody = response.body().string();
            return parseResponse(responseBody);
        }
    }

    /**
     * 流式響應(yīng) - 理解Server-Sent Events
     */
    public void chatStream(String userMessage, StreamCallback callback) {
        // 流式請(qǐng)求實(shí)現(xiàn)
        // 理解SSE協(xié)議和流式處理
    }

    private String parseResponse(String responseBody) throws IOException {
        // 解析響應(yīng) - 理解返回格式
        Map<String, Object> response = objectMapper.readValue(responseBody, Map.class);
        List<Map<String, Object>> choices = (List<Map<String, Object>>) response.get("choices");
        Map<String, Object> message = (Map<String, Object>) choices.get(0).get("message");
        return (String) message.get("content");
    }

    @FunctionalInterface
    public interface StreamCallback {
        void onChunk(String chunk);
    }
}

import java.util.*;

/**
 * 記憶管理基礎(chǔ)實(shí)現(xiàn)
 * 理解Agent的記憶機(jī)制
 */
public class MemoryManager {

    // 對(duì)話(huà)歷史
    private final List<Map<String, String>> conversationHistory = new ArrayList<>();

    // 長(zhǎng)期記憶存儲(chǔ)
    private final Map<String, Object> longTermMemory = new HashMap<>();

    // 記憶重要性評(píng)估
    private final int maxHistorySize = 50;

    /**
     * 添加消息到歷史
     * 理解Token限制和上下文窗口管理
     */
    public void addMessage(String role, String content) {
        Map<String, String> message = Map.of("role", role, "content", content);
        conversationHistory.add(message);

        // 管理歷史長(zhǎng)度 - 滑動(dòng)窗口策略
        if (conversationHistory.size() > maxHistorySize) {
            // 保留最近的N條消息
            int removeCount = conversationHistory.size() - maxHistorySize;
            for (int i = 0; i < removeCount; i++) {
                conversationHistory.remove(0);
            }
        }
    }

    /**
     * 構(gòu)建上下文 - 理解提示詞工程
     */
    public List<Map<String, String>> buildContext(String systemPrompt) {
        List<Map<String, String>> context = new ArrayList<>();

        // 系統(tǒng)提示詞
        context.add(Map.of("role", "system", "content", systemPrompt));

        // 添加長(zhǎng)期記憶中的關(guān)鍵信息
        String memoryContext = buildMemoryContext();
        if (!memoryContext.isEmpty()) {
            context.add(Map.of("role", "system", "content",
                "重要背景信息：" + memoryContext));
        }

        // 對(duì)話(huà)歷史
        context.addAll(conversationHistory);

        return context;
    }

    /**
     * 記憶檢索 - 理解向量檢索原理
     */
    public List<String> retrieveRelevantMemory(String query, int topK) {
        // 簡(jiǎn)化版：基于關(guān)鍵詞匹配
        // 實(shí)際應(yīng)該使用向量相似度檢索

        List<String> relevant = new ArrayList<>();
        // TODO: 實(shí)現(xiàn)向量檢索
        return relevant;
    }

    private String buildMemoryContext() {
        // 構(gòu)建記憶摘要
        StringBuilder sb = new StringBuilder();
        longTermMemory.forEach((key, value) -> {
            sb.append(key).append(": ").append(value).append("; ");
        });
        return sb.toString();
    }

    public void saveToLongTermMemory(String key, Object value) {
        longTermMemory.put(key, value);
    }
}

// 錯(cuò)誤：像Python一樣直接拼接字符串
public class BadJsonHandler {

    public String buildPrompt(String name, int age) {
        // Python風(fēng)格的字符串格式化
        return "你好 " + name + "，你今年 " + age + " 歲了";
        // 問(wèn)題：沒(méi)有類(lèi)型安全，容易出錯(cuò)
    }

    public String parseResponse(String jsonStr) {
        // 手動(dòng)解析JSON
        int start = jsonStr.indexOf("\"content\": \"") + 11;
        int end = jsonStr.indexOf("\"", start);
        return jsonStr.substring(start, end);
        // 問(wèn)題：脆弱、易錯(cuò)、難以維護(hù)
    }
}

import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;
import lombok.Builder;
import lombok.Data;
import lombok.extern.slf4j.Slf4j;

/**
 * Java風(fēng)格的類(lèi)型安全實(shí)現(xiàn)
 */
@Slf4j
public class GoodJsonHandler {

    private final ObjectMapper objectMapper = new ObjectMapper();

    /**
     * 使用強(qiáng)類(lèi)型對(duì)象
     */
    @Data
    @Builder
    public static class ChatRequest {
        @JsonProperty("model")
        private String model;

        @JsonProperty("messages")
        private List<Message> messages;

        @JsonProperty("temperature")
        private Double temperature;

        @JsonProperty("max_tokens")
        private Integer maxTokens;
    }

    @Data
    @Builder
    public static class Message {
        @JsonProperty("role")
        private String role;

        @JsonProperty("content")
        private String content;
    }

    @Data
    public static class ChatResponse {
        @JsonProperty("id")
        private String id;

        @JsonProperty("choices")
        private List<Choice> choices;

        @JsonProperty("usage")
        private Usage usage;

        @Data
        public static class Choice {
            @JsonProperty("index")
            private Integer index;

            @JsonProperty("message")
            private Message message;

            @JsonProperty("finish_reason")
            private String finishReason;
        }

        @Data
        public static class Usage {
            @JsonProperty("prompt_tokens")
            private Integer promptTokens;

            @JsonProperty("completion_tokens")
            private Integer completionTokens;

            @JsonProperty("total_tokens")
            private Integer totalTokens;
        }
    }

    /**
     * 使用Record模式（Java 16+）
     */
    public record UserInfo(String name, int age) {}

    /**
     * 類(lèi)型安全的Prompt構(gòu)建
     */
    public String buildPrompt(UserInfo user) {
        return String.format("你好 %s，你今年 %d 歲了", user.name(), user.age());
    }

    /**
     * 類(lèi)型安全的JSON序列化
     */
    public String serializeRequest(ChatRequest request) {
        try {
            return objectMapper.writeValueAsString(request);
        } catch (JsonProcessingException e) {
            log.error("JSON序列化失敗", e);
            throw new RuntimeException("請(qǐng)求構(gòu)建失敗", e);
        }
    }

    /**
     * 類(lèi)型安全的JSON反序列化
     */
    public ChatResponse parseResponse(String jsonStr) {
        try {
            return objectMapper.readValue(jsonStr, ChatResponse.class);
        } catch (JsonProcessingException e) {
            log.error("JSON反序列化失敗: {}", jsonStr, e);
            throw new RuntimeException("響應(yīng)解析失敗", e);
        }
    }

    /**
     * 使用Java的Optional處理可能為空的值
     */
    public String safeExtractContent(ChatResponse response) {
        return Optional.ofNullable(response)
                .map(ChatResponse::getChoices)
                .filter(choices -> !choices.isEmpty())
                .map(choices -> choices.get(0))
                .map(Choice::getMessage)
                .map(Message::getContent)
                .orElse("無(wú)法獲取響應(yīng)內(nèi)容");
    }
}

// 錯(cuò)誤：像Python一樣同步調(diào)用
public class BadAsyncHandler {

    public void handleMultipleRequests(List<String> prompts) {
        for (String prompt : prompts) {
            // 同步調(diào)用，阻塞等待
            String response = callLLM(prompt);
            System.out.println(response);
        }
        // 問(wèn)題：性能差，無(wú)法利用Java并發(fā)優(yōu)勢(shì)
    }

    private String callLLM(String prompt) {
        // 同步HTTP調(diào)用
        return "response";
    }
}

import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;
import reactor.core.scheduler.Schedulers;
import lombok.extern.slf4j.Slf4j;
import java.util.List;

/**
 * Java風(fēng)格的響應(yīng)式異步處理
 */
@Slf4j
public class GoodAsyncHandler {

    private final LLMClient llmClient;

    public GoodAsyncHandler(LLMClient llmClient) {
        this.llmClient = llmClient;
    }

    /**
     * 使用Project Reactor處理并發(fā)請(qǐng)求
     */
    public Flux<String> handleMultipleRequestsReactive(List<String> prompts) {
        return Flux.fromIterable(prompts)
                .flatMap(prompt ->
                    Mono.fromCallable(() -> llmClient.chat(prompt, "你是一個(gè)助手"))
                        .subscribeOn(Schedulers.boundedElastic())
                        .doOnError(e -> log.error("處理失敗: {}", prompt, e))
                        .onErrorReturn("處理失敗")
                )
                .doOnNext(response -> log.info("收到響應(yīng)"));
    }

    /**
     * 使用Virtual Thread（Java 21+）
     */
    public void handleMultipleRequestsVirtualThreads(List<String> prompts) {
        try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
            List<Future<String>> futures = prompts.stream()
                    .map(prompt -> executor.submit(() -> llmClient.chat(prompt, "你是一個(gè)助手")))
                    .toList();

            for (Future<String> future : futures) {
                try {
                    String response = future.get();
                    log.info("響應(yīng): {}", response);
                } catch (Exception e) {
                    log.error("獲取響應(yīng)失敗", e);
                }
            }
        }
    }

    /**
     * 使用CompletableFuture（Java 8+）
     */
    public CompletableFuture<List<String>> handleMultipleRequestsAsync(List<String> prompts) {
        List<CompletableFuture<String>> futures = prompts.stream()
                .map(prompt -> CompletableFuture.supplyAsync(
                        () -> llmClient.chat(prompt, "你是一個(gè)助手"),
                        Executors.newVirtualThreadPerTaskExecutor()
                ).exceptionally(e -> {
                    log.error("請(qǐng)求失敗: {}", prompt, e);
                    return "默認(rèn)響應(yīng)";
                }))
                .toList();

        return CompletableFuture.allOf(futures.toArray(new CompletableFuture[0]))
                .thenApply(v -> futures.stream()
                        .map(CompletableFuture::join)
                        .toList());
    }

    /**
     * 帶限流的并發(fā)控制
     */
    public Flux<String> handleWithRateLimit(List<String> prompts, int ratePerSecond) {
        return Flux.fromIterable(prompts)
                .delayElements(Duration.ofMillis(1000 / ratePerSecond))
                .flatMap(prompt ->
                    Mono.fromCallable(() -> llmClient.chat(prompt, "助手"))
                        .timeout(Duration.ofSeconds(30))
                        .retry(2)
                        .onErrorReturn("超時(shí)")
                );
    }
}

import io.micrometer.core.instrument.*;
import io.micrometer.core.instrument.binder.jvm.JvmMemoryMetrics;
import io.micrometer.prometheus.PrometheusConfig;
import io.micrometer.prometheus.PrometheusMeterRegistry;
import lombok.extern.slf4j.Slf4j;
import org.springframework.retry.annotation.Backoff;
import org.springframework.retry.annotation.Retryable;
import org.springframework.stereotype.Component;
import reactor.core.publisher.Mono;
import java.time.Duration;
import java.util.concurrent.*;

/**
 * 生產(chǎn)級(jí)Agent實(shí)現(xiàn)
 * 包含監(jiān)控、重試、限流、緩存等生產(chǎn)特性
 */
@Slf4j
@Component
public class ProductionAgent {

    // 監(jiān)控指標(biāo)
    private final MeterRegistry meterRegistry;
    private final Counter requestCounter;
    private final Counter errorCounter;
    private final Timer responseTimer;
    private final Gauge cacheHitRate;

    // 限流器
    private final RateLimiter rateLimiter;

    // 緩存
    private final Cache<String, String> responseCache;

    // 斷路器
    private final CircuitBreaker circuitBreaker;

    private final LLMClient llmClient;

    public ProductionAgent(LLMClient llmClient) {
        this.llmClient = llmClient;

        // 初始化監(jiān)控
        this.meterRegistry = new PrometheusMeterRegistry(PrometheusConfig.DEFAULT);
        this.requestCounter = Counter.builder("agent.requests.total")
                .description("總請(qǐng)求數(shù)")
                .register(meterRegistry);
        this.errorCounter = Counter.builder("agent.errors.total")
                .description("錯(cuò)誤數(shù)")
                .register(meterRegistry);
        this.responseTimer = Timer.builder("agent.response.time")
                .description("響應(yīng)時(shí)間")
                .publishPercentiles(0.5, 0.95, 0.99)
                .register(meterRegistry);

        // 初始化限流
        this.rateLimiter = RateLimiter.create(10.0); // 每秒10個(gè)請(qǐng)求

        // 初始化緩存
        this.responseCache = Caffeine.newBuilder()
                .maximumSize(1000)
                .expireAfterWrite(Duration.ofMinutes(10))
                .recordStats()
                .build();

        this.cacheHitRate = Gauge.builder("agent.cache.hit.rate",
                responseCache, cache -> {
                    var stats = cache.stats();
                    return stats.hitCount() / (double) (stats.hitCount() + stats.missCount());
                })
                .register(meterRegistry);

        // 初始化斷路器
        this.circuitBreaker = CircuitBreaker.ofDefaults("llm-service");
        circuitBreaker.getEventPublisher()
                .onStateTransition(event ->
                    log.info("斷路器狀態(tài)變更: {}", event));
    }

    /**
     * 生產(chǎn)級(jí)聊天方法
     * 包含完整的監(jiān)控、限流、重試、緩存
     */
    @Retryable(
        value = {LLMException.class},
        maxAttempts = 3,
        backoff = @Backoff(delay = 1000, multiplier = 2)
    )
    public Mono<AgentResponse> chat(AgentRequest request) {
        requestCounter.increment();

        return Mono.fromCallable(() -> {
            // 檢查斷路器
            if (!circuitBreaker.tryAcquirePermission()) {
                throw new LLMException("服務(wù)暫時(shí)不可用，請(qǐng)稍后重試");
            }

            // 限流檢查
            if (!rateLimiter.tryAcquire(Duration.ofSeconds(5))) {
                throw new LLMException("請(qǐng)求過(guò)多，請(qǐng)稍后重試");
            }

            // 檢查緩存
            String cacheKey = buildCacheKey(request);
            String cachedResponse = responseCache.getIfPresent(cacheKey);
            if (cachedResponse != null) {
                log.debug("緩存命中: {}", cacheKey);
                return AgentResponse.builder()
                        .content(cachedResponse)
                        .cached(true)
                        .build();
            }

            // 記錄開(kāi)始時(shí)間
            long startTime = System.nanoTime();
            Timer.Sample sample = Timer.start(meterRegistry);

            try {
                // 調(diào)用LLM
                String response = llmClient.chat(
                        request.getMessage(),
                        request.getSystemPrompt()
                );

                // 成功時(shí)更新斷路器
                circuitBreaker.onSuccess(0, TimeUnit.NANOSECONDS);

                // 緩存響應(yīng)
                if (request.isCacheable()) {
                    responseCache.put(cacheKey, response);
                }

                // 記錄指標(biāo)
                sample.stop(responseTimer);
                log.info("請(qǐng)求成功，耗時(shí): {}ms",
                        TimeUnit.NANOSECONDS.toMillis(System.nanoTime() - startTime));

                return AgentResponse.builder()
                        .content(response)
                        .cached(false)
                        .tokens(estimateTokens(request.getMessage(), response))
                        .build();

            } catch (Exception e) {
                // 失敗時(shí)記錄斷路器
                circuitBreaker.onError(0, TimeUnit.NANOSECONDS, e);
                errorCounter.increment();
                log.error("LLM調(diào)用失敗", e);
                throw new LLMException("LLM調(diào)用失敗", e);
            }

        }).subscribeOn(Schedulers.boundedElastic());
    }

    /**
     * 批量處理優(yōu)化
     */
    public Flux<AgentResponse> chatBatch(List<AgentRequest> requests) {
        return Flux.fromIterable(requests)
                .flatMap(request -> chat(request)
                        .timeout(Duration.ofSeconds(30))
                        .onErrorResume(e -> Mono.just(AgentResponse.builder()
                                .content("處理超時(shí)或失敗")
                                .error(e.getMessage())
                                .build()))
                );
    }

    /**
     * 流式響應(yīng)
     */
    public Flux<String> chatStream(AgentRequest request) {
        requestCounter.increment();

        return Flux.create(sink -> {
            llmClient.chatStream(request.getMessage(), chunk -> {
                sink.next(chunk);
            }, sink::error, sink::complete);
        });
    }

    /**
     * 安全檢查 - 過(guò)濾敏感信息
     */
    private void sanitizeInput(AgentRequest request) {
        String message = request.getMessage();

        // 檢測(cè)敏感信息
        if (containsSensitiveInfo(message)) {
            log.warn("檢測(cè)到敏感信息，已過(guò)濾");
            request.setMessage(filterSensitiveInfo(message));
        }

        // 檢測(cè)注入攻擊
        if (detectPromptInjection(message)) {
            log.warn("檢測(cè)到提示詞注入嘗試");
            throw new SecurityException("檢測(cè)到異常輸入");
        }
    }

    private String buildCacheKey(AgentRequest request) {
        return request.getSystemPrompt() + ":" + request.getMessage();
    }

    private boolean containsSensitiveInfo(String text) {
        // 簡(jiǎn)化的敏感信息檢測(cè)
        return text.matches(".*\\d{15,19}.*") || // 可能是身份證
               text.matches(".*\\d{11}.*");      // 可能是手機(jī)號(hào)
    }

    private String filterSensitiveInfo(String text) {
        return text.replaceAll("\\d{15,19}", "***")
                   .replaceAll("(\\d{3})\\d{4}(\\d{4})", "$1****$2");
    }

    private boolean detectPromptInjection(String text) {
        // 檢測(cè)常見(jiàn)的提示詞注入模式
        String[] injectionPatterns = {
            "忽略以上指令",
            "ignore previous instructions",
            "forget everything",
            "新的指令"
        };

        String lowerText = text.toLowerCase();
        for (String pattern : injectionPatterns) {
            if (lowerText.contains(pattern.toLowerCase())) {
                return true;
            }
        }
        return false;
    }

    private int estimateTokens(String input, String output) {
        // 簡(jiǎn)單估算：約4字符=1token
        return (input.length() + output.length()) / 4;
    }

    /**
     * 獲取監(jiān)控指標(biāo)
     */
    public String getMetrics() {
        return ((PrometheusMeterRegistry) meterRegistry).scrape();
    }
}

import lombok.Builder;
import lombok.Data;

/**
 * Agent請(qǐng)求數(shù)據(jù)結(jié)構(gòu)
 */
@Data
@Builder
public class AgentRequest {
    private String message;
    private String systemPrompt;
    @Builder.Default
    private boolean cacheable = true;
    private String userId;
    private String sessionId;
    private Map<String, Object> metadata;
}

import lombok.Builder;
import lombok.Data;

/**
 * Agent響應(yīng)數(shù)據(jù)結(jié)構(gòu)
 */
@Data
@Builder
public class AgentResponse {
    private String content;
    private boolean cached;
    private Integer tokens;
    private String error;
    private Map<String, Object> metadata;
}

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Configuration;
import lombok.Data;

/**
 * Agent配置管理
 */
@Data
@Configuration
@ConfigurationProperties(prefix = "agent")
public class AgentConfig {

    /**
     * LLM配置
     */
    private LLMConfig llm = new LLMConfig();

    /**
     * 緩存配置
     */
    private CacheConfig cache = new CacheConfig();

    /**
     * 限流配置
     */
    private RateLimitConfig rateLimit = new RateLimitConfig();

    /**
     * 重試配置
     */
    private RetryConfig retry = new RetryConfig();

    @Data
    public static class LLMConfig {
        private String apiKey;
        private String baseUrl = "https://api.openai.com/v1";
        private String model = "gpt-3.5-turbo";
        private Double temperature = 0.7;
        private Integer maxTokens = 2000;
        private Duration timeout = Duration.ofSeconds(30);
    }

    @Data
    public static class CacheConfig {
        private Integer maxSize = 1000;
        private Duration expireAfterWrite = Duration.ofMinutes(10);
        private Boolean enabled = true;
    }

    @Data
    public static class RateLimitConfig {
        private Double permitsPerSecond = 10.0;
        private Boolean enabled = true;
    }

    @Data
    public static class RetryConfig {
        private Integer maxAttempts = 3;
        private Long delay = 1000L;
        private Double multiplier = 2.0;
    }
}

# application.yml 配置示例
agent:
  llm:
    api-key: ${LLM_API_KEY}
    base-url: https://api.openai.com/v1
    model: gpt-3.5-turbo
    temperature: 0.7
    max-tokens: 2000
    timeout: 30s
  cache:
    max-size: 1000
    expire-after-write: 10m
    enabled: true
  rate-limit:
    permits-per-second: 10
    enabled: true
  retry:
    max-attempts: 3
    delay: 1000
    multiplier: 2.0
# 監(jiān)控配置
management:
  endpoints:
    web:
      exposure:
        include: health,metrics,prometheus
  metrics:
    export:
      prometheus:
        enabled: true

/**
 * 學(xué)習(xí)資源清單
 */
public class LearningResources {

    public static class Frameworks {
        // Java Agent框架
        String langChain4j = "https://docs.langchain4j.dev/";
        String springAI = "https://spring.io/projects/spring-ai";
        String dashscope = "https://github.com/aliyun/dashscope-java-sdk";
    }

    public static class Tools {
        // 開(kāi)發(fā)工具
        String idea = "IntelliJ IDEA + GitHub Copilot";
        String postman = "Postman - API調(diào)試";
        String wireshark = "Wireshark - 網(wǎng)絡(luò)抓包";
    }

    public static class Practice {
        // 實(shí)踐平臺(tái)
        String openai = "OpenAI API文檔";
        String huggingface = "Hugging Face模型庫(kù)";
        String kaggle = "Kaggle競(jìng)賽平臺(tái)";
    }

    public static class Reading {
        // 推薦閱讀
        String[] books = {
            "《Building Agents with LLMs》",
            "《Prompt Engineering Guide》",
            "《Reactive Programming in Java》"
        };
    }
}