# fish **Repository Path**: xuyihang96/fish ## Basic Information - **Project Name**: fish - **Description**: AI学习验证验证项目验证JAVA_AI项目技术研究 - **Primary Language**: Java - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 4 - **Forks**: 0 - **Created**: 2026-06-15 - **Last Updated**: 2026-07-10 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 🐟 鱼病诊断 AI 应用（我的第一个 AI 项目） > 通过"鱼病诊断"这个具体场景，从零完整理解 AI 应用开发的全流程。 > 这不仅是一个 Demo，更是一套**可复用的 AI 应用骨架认知**—— > 换个领域（宠物、植物、汽车故障），结构不变，只换知识库和 Prompt。 --- ## 📚 这是什么 一个用 **Java + Spring Boot + LangChain4j** 搭建的 AI 应用学习项目。 输入鱼的文字症状或图片，系统经过多 Agent 协作诊断，给出诊断和用药建议。 **目标**：通过亲手实现，搞懂 AI 应用开发的核心技术全链路。 **核心理念**（项目作者的认知）： - **框架只是基础设施**：反射 + 动态代理 + 注解解析，学一次终身受用 - **业务编排才是核心**：提示词设计、知识库整合、多 Agent 协作是真正的复杂度所在 - **先手写后用框架**：先理解手写编排，再用声明式 Workflow 重构，对比学习 --- ## 🚀 快速开始 ### 环境准备 - **Java 17+** - **Maven 3.8+** - **DeepSeek API Key**（必填）：https://platform.deepseek.com - **DashScope API Key**（可选，多模态用）：https://bailian.console.aliyun.com ### 配置（环境变量方式，不要明文写 key） ```cmd set DEEPSEEK_API_KEY=sk-xxx set DASHSCOPE_API_KEY=sk-xxx （可选，多模态） set MCP_SERVER_JAR=target/xxx.jar （可选，第十站 MCP） ``` ### 运行 ```cmd mvn spring-boot:run ``` 或用打包好的 jar： ```cmd java -jar target/fish-disease-diagnosis-0.0.1-SNAPSHOT.jar ``` --- ## 🗺️ 学习路线（15 站 + 接口对照表） 每站对应一个 HTTP 接口，启动后用浏览器访问即可测试。 | 站 | 接口 | 学的概念 | 测试示例 | |----|------|---------|---------| | 1️⃣ | `GET /api/diagnose` | Prompt / ChatModel | `?symptom=鱼有白点蹭缸` | | 2️⃣ | `GET /api/extract-symptom` | 结构化输出（record）| `?description=鱼有白点蹭缸` | | 3️⃣ | `GET /api/diagnose-with-tool` | Function Call（@Tool）| `?symptom=能用孔雀石绿吗` | | 4️⃣ | `GET /api/diagnose-with-rag` | **RAG 知识库（核心目标）** | `?symptom=鱼有白点蹭缸` | | 4️⃣调试 | `GET /api/debug-retrieve` | 看检索结果（验证不全量塞）| `?query=白点病` | | 5️⃣ | `GET /api/diagnose-agentic` | 多 Agent + Agentic RAG + LLM-as-Judge | `?symptom=鱼有白点蹭缸` | | 6️⃣ | `GET /api/chat` | ChatMemory（@MemoryId 多轮）| `?userId=user1&message=鱼有白点` | | 7️⃣ | `GET /api/diagnose-safe` | 护栏 + 意图路由（三层防御）| `?input=鱼有白点蹭缸` | | 8️⃣ | `GET /api/diagnose-image` | 多模态 VLM（图片+文字）| `?imageUrl=图片直链` | | 9️⃣ | `GET /api/diagnose-route` | 多模型路由（chat/reasoner）| `?symptom=鱼有白点蹭缸` | | 🔟 | `GET /api/diagnose-mcp` | MCP（工具即服务）| `?symptom=鱼有白点蹭缸` | | 1️⃣1️⃣ | `GET /api/diagnose-workflow` | 声明式 Workflow 编排 | `?symptom=鱼有白点蹭缸` | | 进阶 | `HybridRetriever`（内部组件）| 混合检索 BM25 + Rerank | 代码内调用 | | 进阶 | `GET /api/traces` | LLMOps 可观测性 | `?limit=5` | ### 完整接口示例（浏览器直接访问） ``` http://localhost:8080/api/diagnose?symptom=我的金鱼身上有白色小点，经常蹭缸 http://localhost:8080/api/diagnose-with-rag?symptom=我的金鱼身上有白色小点，密密麻麻，鱼一直蹭缸 http://localhost:8080/api/diagnose-agentic?symptom=我的金鱼身上有白色小点，密密麻麻，鱼一直蹭缸 http://localhost:8080/api/chat?userId=user1&message=我的金鱼身上有白点蹭缸 http://localhost:8080/api/diagnose-safe?input=我的金鱼身上有白点蹭缸 http://localhost:8080/api/diagnose-route?symptom=鱼一直治不好白点病，反反复复，很严重 http://localhost:8080/api/traces?limit=5 ``` --- ## 🏗️ 项目结构 ``` src/main/java/com/fish/diagnosis/ ├── config/ # 配置层：装配 LLM、向量库、Agent Bean │ ├── AiConfig.java # 三模型装配（DeepSeek chat/reasoner + Qwen-VL） │ ├── RagConfig.java # EmbeddingModel Bean │ └── McpConfig.java # MCP 客户端装配 ├── controller/ # 入口层：13 个 REST 接口（每站一个） ├── service/ # 编排层：业务主流程，串联各 Agent ├── agent/ # AI 智能体层：@AiService interface │ ├── SymptomExtractAgent # 症状提取（结构化输出） │ ├── DiagnosisAgent # 工具版诊断 │ ├── RagDiagnosisAgent # RAG 版诊断 │ ├── AgenticDiagnosisAgent # Agentic RAG 诊断 │ ├── DiagnosisJudgeAgent # LLM-as-Judge 质检 │ ├── ChatAgent # 带记忆的聊天 │ ├── IntentRouterAgent # 意图识别路由 │ ├── DrugRewriteAgent # 违禁药改写（LLM 护栏） │ ├── ComplexDiagnosisAgent # 疑难诊断（R1 推理） │ ├── VisionAnalysisAgent # VLM 视觉分析 │ └── McpDiagnosisAgent # MCP 工具诊断 ├── rag/ # 知识库层：RAG 全流程 │ ├── IndexEmbeddingStore # 索引向量库（粗筛） │ ├── DetailEmbeddingStore # 详细向量库（精查） │ ├── DocumentIngestor # 双库分别灌入 │ ├── KnowledgeRetriever # 检索器 │ └── HybridRetriever # 混合检索 BM25+Rerank（进阶） ├── tool/ # 工具层：@Tool 方法 │ ├── DiseaseLookupTool # 3 个工具（查药/列禁用/查治疗） │ └── KnowledgeLookupTool # Agentic RAG 精查 ├── guardrail/ # 护栏层：Harness 兜底 │ └── OutputGuardrail # 规则定位 + LLM 改写 ├── workflow/ # 工作流层（第十一站） │ └── DiseaseDiagnosisWorkflow ├── observability/ # 可观测性（进阶） │ └── AiTraceRecorder # LLMOps trace 追踪 ├── mcp/ # MCP Server（第十站） │ └── KnowledgeMcpServerMain # 可独立运行的 MCP Server 入口 └── model/ # 数据模型层：DTO、record、enum src/main/resources/ ├── application.yml # 配置（三模型统一，key 全用环境变量） ├── prompts/ # 提示词模板（外置） └── knowledge/ # 知识库文档（双库） ├── 疾病索引.md # 索引库（疾病名+简介） └── 常见鱼病图谱.md # 详细库（完整资料） ``` **这套结构以后做任何 AI 项目都能复用**——这是本项目最大的长期价值。 --- ## 🧰 技术栈 | 组件 | 版本 | 用途 | |------|------|------| | Java | 17 | 运行时 | | Spring Boot | 3.4.5 | Web 框架 | | LangChain4j | 1.13.0 + starter 1.13.0-beta23 | AI 框架 | | LangChain4j Agentic | 1.13.0-beta23 | 声明式 Workflow | | DeepSeek chat | deepseek-chat | 文本诊断（日常）| | DeepSeek reasoner | deepseek-reasoner | 推理诊断（疑难）| | Qwen-VL | qwen-vl-plus | 图片识别（多模态）| | BGE-small-zh | 离线 | 中文 Embedding | | InMemoryEmbeddingStore | 内置 | 内存向量库（双库）| --- ## 🤖 三模型架构 本项目采用**混合多模型架构**，不同任务用不同模型： | 模型 | Bean | 用途 | 配置 | |------|------|------|------| | deepseek-chat | `chatModel`(@Primary) | 日常诊断/RAG/工具/聊天 | `DEEPSEEK_API_KEY` | | deepseek-reasoner | `reasonerModel` | 疑难推理（R1）| 同上 | | qwen-vl-plus | `qwenVisionModel` | 图片识别（多模态）| `DASHSCOPE_API_KEY` | 详见 [multi-model-setup.md](docs/multi-model-setup.md) --- ## 📖 文档体系（8 份完整文档） ``` docs/ ├── interview-cheatsheet.md # 🎯 面试必备：AI 概念汇总（定义+本质+项目实例+追问） ├── learning-roadmap.md # 📚 怎么学：15 站学习路线详解 ├── design-ideas.md # 💡 为什么这么设计：14 个设计想法→业界模式→落地决策 ├── annotations-cheatsheet.md # 🔧 框架怎么用：所有注解一图看懂（反射+动态代理机制） ├── multi-model-setup.md # 🤖 多模型架构：DeepSeek + Qwen-VL 混合架构说明 ├── troubleshooting.md # 🐛 出问题怎么办：真实踩坑问题排查 ├── dify-comparison.md # 🔍 对比参考：Dify 可视化 vs LangChain4j 代码 └── setup-guide.md # 🚀 怎么跑起来：Windows 环境安装指南 ``` ### 推荐阅读顺序 1. **新手先看**：[learning-roadmap.md](docs/learning-roadmap.md) —— 建立心智模型 2. **理解代码**：[annotations-cheatsheet.md](docs/annotations-cheatsheet.md) —— 看懂每个注解 3. **深入设计**：[design-ideas.md](docs/design-ideas.md) —— 为什么这么设计 4. **遇到问题**：[troubleshooting.md](docs/troubleshooting.md) —— 按症状查根因 --- ## 🎯 核心认知（项目沉淀） ### 1. 框架 vs 业务编排 ``` 基础设施层（框架）：反射 + 动态代理 + 注解解析，学一次终身受用 业务编排层（核心）：提示词设计、知识库整合、多 Agent 协作，是真正的复杂度 ``` ### 2. 纵深防御（五层护栏） ``` 第1层 @Tool description：说服模型主动查 第2层 @SystemMessage 安全规则：说服模型遵守 第3层 LLM-as-Judge：模型自我审查 第4层 意图路由：拦截不相关输入 第5层 代码护栏：硬规则兜底（规则定位 + LLM 改写） ``` ### 3. 多 Agent 架构 ``` 该用 Agent 的地方：意图识别（不确定性高，用模型判断） 该用 Workflow 的地方：业务流程（确定后步骤固定，硬编码更稳） 该用代码的地方：输出护栏（安全相关，不信任模型） ``` --- ## 💡 项目作者的设计想法（14 个，多数与业界前沿模式吻合） 作者在开发过程中独立思考出 14 个架构想法，很多与业界 2023-2024 年最前沿模式不谋而合： | 想法 | 业界模式 | 落地状态 | |------|---------|---------| | 索引库+详细库分离 | Hierarchical RAG | ✅ 已落地 | | 模型自主查详细库 | Agentic RAG | ✅ 已落地 | | 返回前评估 | Self-RAG / Reflection | ✅ 已落地 | | 不达标重试 | Retry Loop | ✅ 已落地 | | 入口意图路由 | Router 模式 | ✅ 已落地 | | 护栏三层演进 | Hybrid Guardrail | ✅ 已落地 | | 摘要记忆 | Summary Memory | ⏳ 记录 | | 配置化黑名单 | 数据与逻辑分离 | ⏳ 记录 | | ... | ... | ... | 完整记录见 [design-ideas.md](docs/design-ideas.md) **"你不是在瞎想，你在重新发明业界最前沿的 AI 架构模式。"** --- ## 📊 项目状态 - ✅ **15 站全部完成**，39 个源文件，编译通过，打包成功 - ✅ **核心目标达成**：文本+图片都能诊断，基于知识库回答 - ✅ **进阶架构落地**：Agentic RAG + LLM-as-Judge + 三模型路由 + MCP + Workflow - ✅ **7 份文档 + 14 个设计想法** 完整沉淀 **最有价值的产物不是代码，而是文档 + 独立思考。** --- ## 🧪 测试方法 每站都有对应的测试类（在 `src/test/java/`）： ```cmd mvn test -Dtest=DiagnosisServiceTest # 第一站 mvn test -Dtest=Stage2StructuredOutputTest # 第二站 mvn test -Dtest=Stage3FunctionCallTest # 第三站 mvn test -Dtest=Stage4RagTest # 第四站 mvn test -Dtest=Stage6ChatMemoryTest # 第六站 mvn test -Dtest=Stage7GuardrailsTest # 第七站 ``` --- ## ⚠️ 安全提醒 - **所有 API Key 必须用环境变量**，不要明文写进 application.yml - 泄露的 key 要立刻在厂商后台作废重置 - 如果要传 Git，把 `application.yml` 加进 `.gitignore` --- > 这是我（项目作者）的第一个 AI 应用项目。 > 从对 AI 概念一知半解，到独立设计出与业界前沿吻合的架构。 > 代码可以重写，但这份认知和思考过程，是最宝贵的收获。