# Fintec AI Framework 开发指南

## 📚 文档目录

- [快速开始](#快速开始)
- [架构概览](#架构概览)
- [模块说明](#模块说明)
- [使用示例](#使用示例)
- [最佳实践](#最佳实践)
- [常见问题](#常见问题)

---

## 快速开始

### 环境要求

- JDK 17+
- Spring Boot 3.4.6+
- Spring AI 1.1.1+
- Maven 3.6+

### 引入依赖

在项目的 `pom.xml` 中添加依赖:

```xml
<!-- Agent Starter(对话能力) -->
<dependency>
    <groupId>com.ccb.fintec</groupId>
    <artifactId>fintec-framework-agent-spring-boot-starter</artifactId>
</dependency>

<!-- RAG Starter(知识库问答) -->
<dependency>
    <groupId>com.ccb.fintec</groupId>
    <artifactId>fintec-framework-rag-spring-boot-starter</artifactId>
</dependency>

<!-- MCP Server Starter(工具暴露) -->
<dependency>
    <groupId>com.ccb.fintec</groupId>
    <artifactId>fintec-framework-mcp-server-spring-boot-starter</artifactId>
</dependency>
```

### 基础配置

在 `application.yml` 中配置 AI 模型:

```yaml
spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}
      base-url: https://api.openai.com/v1
      chat:
        options:
          model: gpt-4
          temperature: 0.7

app:
  ai:
    # 安全防护
    safety:
      enabled: true
      block-keywords:
        - 暴力
        - 色情
        - 赌博
    # 限流配置
    rate-limit:
      max-requests-per-minute: 60
    # 重试策略（自动处理网络波动）
    retry:
      enabled: true
      max-attempts: 3
      backoff-ms: 1000
```

---

## 架构概览

### 整体架构

```
┌─────────────────────────────────────────────┐
│         业务应用层 (Business App)            │
├─────────────────────────────────────────────┤
│  Agent+Graph+MCP Client  │   RAG            │
│  Starter                 │ Starter          │
├─────────────────────────────────────────────┤
│         Core 核心层 (统一抽象)                │
├─────────────────────────────────────────────┤
│      Spring AI (模型适配层)                   │
├─────────────────────────────────────────────┤
│  OpenAI │ Ollama │ Anthropic │ 其他模型      │
└─────────────────────────────────────────────┘
           ↑
┌─────────────────────────────────────────────┐
│     MCP Server (独立部署)                     │
│  SSE + STDIO + Streamable-HTTP              │
└─────────────────────────────────────────────┘
```

### 设计原则

1. **分层解耦**: 技术实现与业务编排分离
2. **多模型支持**: 通过 Spring AI 抽象,支持切换不同模型厂商
3. **开箱即用**: 自动配置,零样板代码
4. **可扩展性**: 基于 Spring Boot Starter 机制,易于扩展

---

## 模块说明

### 1. fintec-framework-ai-core (核心模块)

**职责**: 提供统一的 AI 配置和能力抽象

**功能**:
- 全局 AI 配置管理 (`AiCoreProperties`)
- 公共的接口和DTO，公共回复等解耦...

---

### 2. fintec-framework-agent-spring-boot-starter (Agent 模块)

**职责**: 提供对话式 AI、Graph 工作流编排和 MCP Client 能力

**核心组件**:
- `AgentTemplate`: 封装常用对话模式（内置重试）
- `MultimodalTemplate`: 多模态能力(图片/文档理解)
- `ChatClient`: 统一的聊天客户端
- `ChatMemory`: 对话记忆管理
- Graph 工作流: `Node`, `Condition`, `SequentialWorkflow`, `ParallelWorkflow`, `RoutingWorkflow`, `LoopWorkflow`
- `McpClientAutoConfiguration`: MCP Client 自动配置
- `RetryAutoConfiguration`: 自动重试机制
- `SafetyAspect`: 敏感词过滤切面

**主要功能**:
- 简单问答
- 带系统提示的对话
- Function Calling(工具调用)
- 结构化输出
- 流式响应
- 对话记忆
- **图片理解**: 分析图片内容、OCR识别
- **Graph 工作流**: Sequential/Parallel/Routing/Loop
- **MCP Client**: 连接外部 MCP Server
- **安全防护**: 敏感词过滤（请求+响应双向检查）
- **自动重试**: 处理网络波动、临时故障

**典型场景**: 智能客服、AI助手、代码生成、多模态应用、复杂工作流编排

---

### 3. fintec-framework-rag-spring-boot-starter (RAG 模块)

**职责**: 提供检索增强生成、ETL 和图片生成能力

**核心组件**:
- `RagTemplate`: 封装 RAG 调用模式
- `ImageGenerationTemplate`: 图片生成能力
- `QuestionAnswerAdvisor`: 向量检索顾问

**主要功能**:
- **ETL**: 文档读取和解析（PDF、Word、TXT等）
- **Embedding**: 文本向量化
- **VectorStore**: 向量存储和检索
- 基于知识库的问答
- 自定义相似度阈值和 TopK
- 流式输出
- 结合对话记忆
- **图片生成**: 根据文本描述生成图片

**典型场景**: 企业知识库问答、文档检索、智能搜索、AI绘画

---

### 4. fintec-framework-mcp-server-spring-boot-starter (MCP Server 模块)

**职责**: 提供 Model Context Protocol Server 支持，将工具暴露给外部 Agent

**核心组件**:
- `McpAutoConfiguration`: MCP Server 自动配置
- `ToolCallbackProvider`: 自动扫描 `@Tool` 注解

**主要功能**:
- 自动注册工具函数
- **SSE**: Server-Sent Events 传输
- **STDIO**: 标准输入输出传输
- **Streamable-HTTP**: 流式 HTTP 传输
- 工具发现与调用

**典型场景**: AI 调用外部 API、数据库查询、业务系统集成（独立部署）

---

## 使用示例

### Agent 模块示例（包含 Graph 工作流）

```java
@Service
public class CustomerService {
    
    @Autowired
    private AgentTemplate agentTemplate;
    
    // 简单问答
    public String answer(String question) {
        return agentTemplate.ask(question);
    }
    
    // 带系统提示
    public String answerWithRole(String question) {
        return agentTemplate.ask(
            "你是一位专业的客服代表,请用礼貌的语气回答",
            question
        );
    }
    
    // 流式输出
    public Flux<String> streamAnswer(String question) {
        return agentTemplate.stream(question);
    }
    
    // 带对话记忆
    public String chat(String conversationId, String message) {
        return agentTemplate.askWithMemory(conversationId, message);
    }
    
    // 结构化输出
    public OrderInfo extractOrder(String text) {
        return agentTemplate.askForObject(
            "从以下文本中提取订单信息: " + text,
            OrderInfo.class
        );
    }
}
```

### Graph 工作流示例

```java
@Service
public class WorkflowService {
    
    @Autowired
    private GraphTemplate graphTemplate;
    
    // 顺序工作流: 数据清洗 -> 翻译 -> 总结
    public String processText(String text) {
        var workflow = GraphTemplate.sequential(
            GraphTemplate.node("清洗", t -> t.trim()),
            GraphTemplate.node("翻译", t -> translate(t)),
            GraphTemplate.node("总结", t -> summarize(t))
        );
        return workflow.execute(text);
    }
    
    // 并行工作流: 多维度分析
    public List<String> analyzeText(String text) {
        var workflow = GraphTemplate.parallel(
            GraphTemplate.node("情感分析", t -> sentiment(t)),
            GraphTemplate.node("关键词提取", t -> keywords(t)),
            GraphTemplate.node("分类", t -> classify(t))
        );
        return workflow.execute(text);
    }
    
    // 路由工作流: 根据问题类型选择处理逻辑
    public String routeQuestion(String question) {
        var workflow = GraphTemplate.routing()
            .addBranch("技术", 
                q -> ((String)q).contains("技术"),
                GraphTemplate.node("技术回答", q -> techAnswer(q)))
            .addBranch("业务",
                q -> ((String)q).contains("业务"),
                GraphTemplate.node("业务回答", q -> businessAnswer(q)))
            .setDefault(GraphTemplate.node("通用回答", q -> generalAnswer(q)));
        
        return workflow.execute(question);
    }
}
```

```java
@Service
public class KnowledgeService {
    
    @Autowired
    private RagTemplate ragTemplate;
    
    // 基于知识库问答
    public String askKnowledge(String question) {
        return ragTemplate.ask(question);
    }
    
    // 自定义检索参数
    public String askWithConfig(String question) {
        return ragTemplate.askWithConfig(
            question,
            0.8,  // 相似度阈值
            5     // TopK
        );
    }
    
    // 流式输出
    public Flux<String> streamAsk(String question) {
        return ragTemplate.stream(question);
    }
}
```

### Graph 模块示例

```java
@Service
public class WorkflowService {
    
    @Autowired
    private GraphTemplate graphTemplate;
    
    // 顺序工作流: 数据清洗 -> 翻译 -> 总结
    public String processText(String text) {
        var workflow = GraphTemplate.sequential(
            GraphTemplate.node("清洗", t -> t.trim()),
            GraphTemplate.node("翻译", t -> translate(t)),
            GraphTemplate.node("总结", t -> summarize(t))
        );
        return workflow.execute(text);
    }
    
    // 并行工作流: 多维度分析
    public List<String> analyzeText(String text) {
        var workflow = GraphTemplate.parallel(
            GraphTemplate.node("情感分析", t -> sentiment(t)),
            GraphTemplate.node("关键词提取", t -> keywords(t)),
            GraphTemplate.node("分类", t -> classify(t))
        );
        return workflow.execute(text);
    }
    
    // 路由工作流: 根据问题类型选择处理逻辑
    public String routeQuestion(String question) {
        var workflow = GraphTemplate.routing()
            .addBranch("技术", 
                q -> ((String)q).contains("技术"),
                GraphTemplate.node("技术回答", q -> techAnswer(q)))
            .addBranch("业务",
                q -> ((String)q).contains("业务"),
                GraphTemplate.node("业务回答", q -> businessAnswer(q)))
            .setDefault(GraphTemplate.node("通用回答", q -> generalAnswer(q)));
        
        return workflow.execute(question);
    }
}
```

---

## 最佳实践

### 1. 对话记忆管理

✅ **推荐做法**:
```java
// 使用业务ID作为会话ID
String conversationId = "user_" + userId + "_session_" + sessionId;
agentTemplate.askWithMemory(conversationId, message);

// 定期清理过期会话
@Component
public class MemoryCleanupTask {
    @Scheduled(cron = "0 0 2 * * ?") // 每天凌晨2点
    public void cleanup() {
        // 清理7天前的会话
    }
}
```

❌ **避免做法**:
- 使用 UUID 作为会话ID(每次都是新会话)
- 不清理会话数据(内存泄漏)
- 不同用户共用同一会话ID

---

### 3. RAG 优化

✅ **推荐做法**:
```java
// 调整相似度阈值(根据业务场景)
ragTemplate.askWithConfig(question, 0.75, 3);

// 文档切片策略
// - 技术文档: 500-800 tokens/chunk
// - FAQ: 按问题拆分
// - 合同: 按条款拆分

// 添加元数据过滤
SearchRequest.builder()
    .similarityThreshold(0.8)
    .topK(5)
    .filterExpression("category == 'technical'")
    .build();
```

❌ **避免做法**:
- TopK 设置过大(增加成本)
- 相似度阈值过低(返回不相关内容)
- 不处理文档切片重叠

---

### 4. 工作流设计

✅ **推荐做法**:
```java
// 为节点命名(便于调试)
GraphTemplate.node("数据验证", data -> validate(data));

// 设置合理的循环上限
GraphTemplate.loop(node, condition, 5); // 最多5次迭代

// 异常处理
try {
    return workflow.execute(input);
} catch (Exception e) {
    log.error("工作流执行失败", e);
    return fallbackResult;
}
```

❌ **避免做法**:
- 循环不设上限(死循环风险)
- 节点逻辑过于复杂(应拆分为多个节点)
- 不记录工作流执行日志

---

### 5. 性能优化

✅ **推荐做法**:
```java
// 使用流式输出提升用户体验
@GetMapping(value = "/chat/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public Flux<String> streamChat(String message) {
    return agentTemplate.stream(message);
}

// 并行执行独立任务
var results = GraphTemplate.parallel(
    node1, node2, node3
).execute(input);

// 缓存常见问题的答案
@Cacheable(value = "faq", key = "#question")
public String getFaqAnswer(String question) {
    return ragTemplate.ask(question);
}
```

❌ **避免做法**:
- 同步等待大模型响应(超时风险)
- 串行执行可并行的任务
- 重复调用相同的 Prompt

---

## 常见问题

### Q1: 如何切换不同的 AI 模型?

**A**: 修改 `application.yml` 配置即可:

```yaml
# 切换到 Ollama
spring:
  ai:
    ollama:
      base-url: http://localhost:11434
      chat:
        options:
          model: llama3

# 切换到通义千问
spring:
  ai:
    dashscope:
      api-key: ${DASHSCOPE_API_KEY}
      chat:
        options:
          model: qwen-max
```

---

### Q2: 如何实现多轮对话?

**A**: 使用 `askWithMemory` 方法:

```java
// 第一次对话
String answer1 = agentTemplate.askWithMemory("session_001", "你好");

// 第二次对话(能记住上下文)
String answer2 = agentTemplate.askWithMemory("session_001", "我刚才说了什么?");
```

---

### Q3: RAG 检索不到相关内容怎么办?

**A**: 检查以下几点:
1. 降低相似度阈值(如从 0.8 降到 0.6)
2. 增加 TopK 数量
3. 优化文档切片策略
4. 检查 Embedding 模型质量
5. 添加更多相关文档

---

### Q4: 如何调试工作流?

**A**: 启用 DEBUG 日志:

```yaml
logging:
  level:
    com.ccb.fintec.graph: DEBUG
```

查看每个节点的输入输出和执行时间。

---

### Q5: 如何保证 AI 输出的安全性?

**A**: 多层防护:
1. 配置敏感词过滤 (`app.ai.safety.block-keywords`)
2. 设置输出长度限制 (`max-tokens-per-request`)
3. 人工审核关键业务输出