spring-ai-demo/docs/架构设计.md

Fintec AI Framework 架构设计文档

📋 目录

• 整体架构
• 模块职责
• 技术栈

---

整体架构

架构图

模块职责

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

定位: 纯 JAR - 契约、模型与常量定义

职责:

• 统一的 AI 配置管理 (AiCoreProperties)
• 统一响应模型 (AiResponse + TokenUsage + ErrorInfo)
• 统一异常体系 (AiException)
• Graph 核心接口 (Node, Condition)

设计原则:

• 无 Spring 依赖（纯 POJO/接口）
• 不包含自动配置
• 被所有 autoconfigure 模块依赖

关键类:

com.ccb.fintec.core.properties.AiCoreProperties
com.ccb.fintec.core.dto.AiResponse
com.ccb.fintec.core.exception.AiException
com.ccb.fintec.core.graph.Node
com.ccb.fintec.core.graph.Condition

---

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

定位: 对话式 AI 和多模态能力中心

职责:

• 基础对话: ChatClient 封装,同步/流式响应
• Tool Calling: @Tool 自动注册和调用
• 对话记忆: ChatMemory + JDBC/Redis 持久化
• Advisor 链: Memory/RAG/Log/Guardrails
• 结构化输出: .entity(Class) JSON解析
• 多模态输入: 图片理解、文档理解
• 语音合成: TTS (Text-to-Speech) - 暂不支持
• 语音识别: STT (Speech-to-Text) - 暂不支持

核心组件:

AgentTemplate          - 对话模板
MultimodalTemplate     - 多模态模板

典型场景:

• 智能客服机器人
• AI 编程助手
• 多模态交互应用

---

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

定位: 检索增强生成和图片生成中心

职责:

• RAG 检索增强: RetrievalAugmentationAdvisor
• ETL 文档管道: PDF/Word/网页读取分块
• Embedding: 向量化接口
• Vector Store: PGVector/Redis/Chroma 等
• 图片生成: ImageModel (DALL-E等)

核心组件:

RagTemplate            - RAG模板
ImageGenerationTemplate - 图片生成模板

典型场景:

• 企业知识库问答
• 智能文档检索
• AI 绘画应用

---

4. fintec-framework-agent-spring-boot-starter (Graph 模块)

定位: 工作流编排引擎

职责:

• Sequential: 顺序链式执行
• Parallel: 并行执行聚合
• Routing: 条件分支路由
• Loop + Recursive: 循环和递归
• Human in the Loop: 人工干预节点

核心组件:

Node                   - 工作流节点
Condition              - 条件边
SequentialWorkflow     - 顺序工作流
ParallelWorkflow       - 并行工作流
RoutingWorkflow        - 路由工作流
LoopWorkflow           - 循环工作流
GraphTemplate          - 工作流模板

典型场景:

• 复杂业务流程编排
• 多步骤 AI 任务
• 决策树系统

---

5. fintec-framework-mcp-server-spring-boot-starter (MCP 模块)

定位: Model Context Protocol 支持

职责:

• MCP Server: SSE + STDIO + Streamable-HTTP
• MCP Client: 连接远程 MCP Server
• 工具发现: 自动扫描 @Tool 注解
• 协议适配: 多种传输协议支持

核心组件:

ToolCallbackProvider   - 工具回调提供者
McpAutoConfiguration   - MCP自动配置

典型场景:

• AI 调用外部 API
• 跨系统集成
• 微服务编排

---

技术栈

基础框架

• JDK: 17+
• Spring Boot: 3.4.6+
• Spring AI: 1.1.0+
• Maven: 3.6+

AI 模型支持

• LLM: OpenAI GPT、Ollama、通义千问、Anthropic Claude
• Embedding: OpenAI Embedding、本地 Embedding
• Image: DALL-E 3、Stable Diffusion
• Audio: OpenAI Whisper/TTS

向量数据库

• PGVector: PostgreSQL 向量扩展
• Redis: Redis Stack
• Chroma: 原生向量数据库
• Milvus: 大规模向量检索

数据存储

• JDBC: MySQL/PostgreSQL/Oracle
• Redis: 会话缓存
• Caffeine: 本地缓存