Java 后端的 LLM 实战路线：微调、RAG、Agent 全链路拆解

// 对话格式（ChatML）
{
  "messages": [
    {"role": "system", "content": "你是一个专业的客服助手"},
    {"role": "user", "content": "你们的退货政策是什么？"},
    {"role": "assistant", "content": "我们支持 7 天无理由退货..."}
  ]
}

// 指令格式（Alpaca）
{
  "instruction": "将以下英文翻译成中文",
  "input": "Hello, how are you?",
  "output": "你好，你怎么样？"
}

# 安装
git clone https://github.com/hiyouga/LLaMA-Factory.git
cd LLaMA-Factory
pip install -e .

# 准备数据（放到 data/ 目录）
# 编辑 data/dataset_info.json 注册数据集

# Web UI 训练（最简单）
llamafactory-cli webui

# 命令行训练
llamafactory-cli train \
    --model_name_or_path Qwen2.5-7B-Instruct \
    --dataset my_dataset \
    --template qwen \
    --finetuning_type lora \
    --lora_rank 16 \
    --lora_alpha 32 \
    --output_dir output/my_lora \
    --num_train_epochs 3 \
    --learning_rate 2e-4 \
    --per_device_train_batch_size 4 \
    --gradient_accumulation_steps 4

from peft import LoraConfig, get_peft_model, TaskType
from transformers import AutoModelForCausalLM, AutoTokenizer, TrainingArguments, Trainer

# 加载基座模型
model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen2.5-7B-Instruct")
tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen2.5-7B-Instruct")

# 配置 LoRA
lora_config = LoraConfig(
    task_type=TaskType.CAUSAL_LM,
    r=16,
    lora_alpha=32,
    lora_dropout=0.05,
    target_modules=["q_proj", "v_proj", "k_proj", "o_proj"],
)

# 应用 LoRA
model = get_peft_model(model, lora_config)
model.print_trainable_parameters()
# 输出: trainable params: 4,194,304 || all params: 7,615,616,000 || trainable%: 0.055%

# 训练
training_args = TrainingArguments(
    output_dir="./output",
    num_train_epochs=3,
    per_device_train_batch_size=4,
    gradient_accumulation_steps=4,
    learning_rate=2e-4,
    warmup_steps=100,
    logging_steps=10,
    save_steps=500,
    fp16=True,  # 混合精度训练
)

trainer = Trainer(
    model=model,
    args=training_args,
    train_dataset=train_dataset,
    tokenizer=tokenizer,
)
trainer.train()

# 保存 LoRA 权重（只有几十 MB）
model.save_pretrained("./output/my_lora")

# LoRA 权重合并回基座模型
python scripts/merge_peft_adapter.py \
    --base_model Qwen/Qwen2.5-7B-Instruct \
    --peft_model output/my_lora \
    --output_path output/merged_model

# 合并后就是一个完整的模型，可以正常部署

// 文档解析器接口
public interface DocumentParser {
    List<DocumentChunk> parse(InputStream input, String filename);
}

// PDF 解析
public class PdfParser implements DocumentParser {
    // 方案一: Apache PDFBox（纯 Java，推荐）
    // 方案二: Tika（支持格式多，但重）
    // 方案三: 调 API（百度文档解析等）
}

// Word 解析
public class WordParser implements DocumentParser {
    // Apache POI
}

// Markdown 解析
public class MarkdownParser implements DocumentParser {
    // 按标题层级切分
}

public class TextChunker {

    // 方案一: 固定长度切片（最简单但最粗暴）
    public List<String> fixedSizeSplit(String text, int chunkSize, int overlap) {
        // chunkSize: 每片 500 字符
        // overlap: 前后重叠 50 字符（防止在句子中间切断）
    }

    // 方案二: 按段落/标题切分（推荐）
    public List<String> semanticSplit(String text) {
        // 按 \n\n 分段
        // 按 Markdown 标题 # ## ### 分节
        // 每段如果太长，再按句子细分
    }

    // 方案三: 递归切分（LangChain 的 RecursiveCharacterTextSplitter）
    public List<String> recursiveSplit(String text, int chunkSize) {
        // 先尝试按 \n\n 分
        // 如果某段太长，按 \n 分
        // 还是太长，按 。分
        // 还是太长，按字符硬切
    }
}

// 调用 Embedding API
public interface EmbeddingService {
    float[] embed(String text);
    List<float[]> embedBatch(List<String> texts);
}

// OpenAI 实现
@Service
public class OpenAiEmbeddingService implements EmbeddingService {
    @Override
    public float[] embed(String text) {
        // 调 OpenAI /v1/embeddings API
    }
}

// 本地 BGE 模型实现（通过 Python 服务或 ONNX）
@Service
public class BgeEmbeddingService implements EmbeddingService {
    @Override
    public float[] embed(String text) {
        // 调本地 Python FastAPI 服务
        // 或用 ONNX Runtime 在 Java 中直接推理
    }
}

// pgvector 示例（JdbcTemplate）
@Service
public class VectorStoreService {

    @Autowired
    private JdbcTemplate jdbc;

    // 存储向量
    public void store(String docId, String content, float[] embedding) {
        jdbc.update(
            "INSERT INTO documents (doc_id, content, embedding) VALUES (?, ?, ?::vector)",
            docId, content, toPgVectorString(embedding)
        );
    }

    // 向量相似度搜索（余弦距离）
    public List<DocumentResult> search(float[] queryEmbedding, int topK) {
        return jdbc.query(
            "SELECT doc_id, content, 1 - (embedding <=> ?::vector) AS score " +
            "FROM documents ORDER BY embedding <=> ?::vector LIMIT ?",
            new Object[]{toPgVectorString(queryEmbedding), toPgVectorString(queryEmbedding), topK},
            (rs, i) -> new DocumentResult(
                rs.getString("doc_id"),
                rs.getString("content"),
                rs.getFloat("score")
            )
        );
    }
}

@Service
public class RagService {

    @Autowired private DocumentParser documentParser;
    @Autowired private TextChunker textChunker;
    @Autowired private EmbeddingService embeddingService;
    @Autowired private VectorStoreService vectorStore;
    @Autowired private LlmService llmService;

    // 离线：文档入库
    public void ingestDocument(InputStream input, String filename) {
        List<DocumentChunk> chunks = documentParser.parse(input, filename);
        for (DocumentChunk chunk : chunks) {
            float[] embedding = embeddingService.embed(chunk.getContent());
            vectorStore.store(chunk.getId(), chunk.getContent(), embedding);
        }
    }

    // 在线：RAG 问答
    public String ask(String question) {
        // 1. 问题向量化
        float[] qEmbedding = embeddingService.embed(question);

        // 2. 检索相关片段
        List<DocumentResult> results = vectorStore.search(qEmbedding, 5);

        // 3. 构造 Prompt
        String context = results.stream()
            .map(DocumentResult::getContent)
            .collect(Collectors.joining("\n---\n"));

        String prompt = String.format("""
            基于以下参考资料回答用户问题。
            如果参考资料中没有相关信息，请说"我没有找到相关信息"。

            参考资料：
            %s

            用户问题：%s
            """, context, question);

        // 4. 调用 LLM 生成回答
        return llmService.chat(prompt);
    }
}

// Skill 接口定义
public interface Skill {
    String getName();
    String getDescription();
    List<ParameterSchema> getParameters();
    Object execute(Map<String, Object> params);
}

// 天气查询 Skill
@Component
public class WeatherSkill implements Skill {

    @Override
    public String getName() { return "get_weather"; }

    @Override
    public String getDescription() { return "查询指定城市的天气信息"; }

    @Override
    public List<ParameterSchema> getParameters() {
        return List.of(
            new ParameterSchema("city", "string", "城市名称", true)
        );
    }

    @Override
    public Object execute(Map<String, Object> params) {
        String city = (String) params.get("city");
        // 调天气 API
        return weatherApi.query(city);
    }
}

// 数据库查询 Skill
@Component
public class SqlQuerySkill implements Skill {

    @Override
    public String getName() { return "query_database"; }

    @Override
    public String getDescription() { return "查询数据库获取数据"; }

    @Override
    public List<ParameterSchema> getParameters() {
        return List.of(
            new ParameterSchema("sql", "string", "SQL 查询语句", true)
        );
    }

    @Override
    public Object execute(Map<String, Object> params) {
        String sql = (String) params.get("sql");
        // 只允许 SELECT，禁止修改数据
        if (!sql.trim().toUpperCase().startsWith("SELECT")) {
            throw new SecurityException("只允许查询操作");
        }
        return jdbcTemplate.queryForList(sql);
    }
}

@Service
public class AgentService {

    @Autowired
    private List<Skill> skills;

    @Autowired
    private LlmService llmService;

    public String run(String userMessage) {
        // 1. 把所有 Skill 定义转为 OpenAI function 格式
        List<FunctionDef> functions = skills.stream()
            .map(this::toFunctionDef)
            .toList();

        // 2. 第一次调用 LLM（判断是否需要调用工具）
        LlmResponse response = llmService.chat(userMessage, functions);

        // 3. 如果 LLM 决定调用工具
        if (response.hasToolCall()) {
            ToolCall toolCall = response.getToolCall();

            // 4. 执行工具
            Skill skill = findSkill(toolCall.getName());
            Object result = skill.execute(toolCall.getArguments());

            // 5. 把工具结果返回给 LLM，让它生成最终回答
            return llmService.chatWithToolResult(
                userMessage, toolCall, result
            );
        }

        // 6. 不需要工具，直接返回
        return response.getContent();
    }
}

// 统一接口，屏蔽不同模型的差异
public interface LlmService {
    // 同步调用
    String chat(String systemPrompt, String userMessage);

    // 带工具调用
    LlmResponse chat(String userMessage, List<FunctionDef> functions);

    // 流式调用（SSE）
    Flux<String> chatStream(String systemPrompt, String userMessage);

    // 多轮对话
    String chat(List<ChatMessage> messages);
}

// 配置化：不同模型用不同实现
@Service
@ConditionalOnProperty(name = "ai.llm.provider", havingValue = "openai")
public class OpenAiLlmService implements LlmService { ... }

@Service
@ConditionalOnProperty(name = "ai.llm.provider", havingValue = "qwen")
public class QwenLlmService implements LlmService { ... }

@RestController
@RequestMapping("/api/chat")
public class ChatController {

    @Autowired
    private LlmService llmService;

    @GetMapping(value = "/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
    public SseEmitter stream(@RequestParam String message) {
        SseEmitter emitter = new SseEmitter(60000L);

        Flux<String> stream = llmService.chatStream("你是助手", message);

        stream.subscribe(
            chunk -> emitter.send(SseEmitter.event().data(chunk)),
            emitter::completeWithError,
            emitter::complete
        );

        return emitter;
    }
}

// 会话实体
@Data
@TableName("ai_chat_session")
public class ChatSession {
    @TableId(type = IdType.ASSIGN_ID)
    private Long sessionId;
    private Long userId;
    private String title;
    private String systemPrompt;
    private Integer messageCount;
    private LocalDateTime createTime;
    private LocalDateTime updateTime;
}

// 消息实体
@Data
@TableName("ai_chat_message")
public class ChatMessage {
    @TableId(type = IdType.ASSIGN_ID)
    private Long messageId;
    private Long sessionId;
    private String role;       // system/user/assistant/tool
    private String content;
    private String toolCalls;  // JSON
    private String toolResult; // JSON
    private Integer tokens;    // token 消耗
    private Long costMs;       // 耗时
    private LocalDateTime createTime;
}

@Component
public class CostController {

    // Token 限流：每用户每天最多 N tokens
    private final Map<Long, AtomicLong> dailyTokenUsage = new ConcurrentHashMap<>();

    public void checkBudget(Long userId, int estimatedTokens) {
        long used = dailyTokenUsage.getOrDefault(userId, new AtomicLong(0)).get();
        long limit = getUserDailyLimit(userId);

        if (used + estimatedTokens > limit) {
            throw new BusinessException("今日 Token 额度已用完");
        }

        dailyTokenUsage.computeIfAbsent(userId, k -> new AtomicLong(0))
            .addAndGet(estimatedTokens);
    }
}

<script setup lang="ts">
// SSE 流式接收
const sendMessage = async (content: string) => {
  const response = await fetch('/api/chat/stream?' + new URLSearchParams({ message: content }))
  const reader = response.body!.getReader()
  const decoder = new TextDecoder()

  while (true) {
    const { done, value } = await reader.read()
    if (done) break

    const chunk = decoder.decode(value)
    // SSE 格式解析
    const lines = chunk.split('\n')
    for (const line of lines) {
      if (line.startsWith('data:')) {
        const data = line.slice(5).trim()
        if (data === '[DONE]') break
        currentMessage.value += data  // 逐字追加
      }
    }

    // 自动滚动到底部
    scrollToBottom()
  }
}
</script>