# ai-study 

**Repository Path**: lfws/ai-study

## Basic Information

- **Project Name**: ai-study 
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-10
- **Last Updated**: 2026-09-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ai-lab —— Spring AI 企业级学习项目

以「回款业务助手」为载体的 Spring AI 全链路练习场：从命令行对话起步，逐步加上工具调用、记忆、流式输出、结构化输出、RAG、MCP，最终演进为带持久化存储的 Web 服务。

## 技术栈

| 组件 | 版本 | 用途 |
|---|---|---|
| Spring Boot | 4.1.0 | 应用框架 |
| Spring AI | 2.0.1 | AI 能力抽象 |
| 通义千问 | qwen3.8-max（DashScope OpenAI 兼容接口） | 对话/结构化输出 |
| text-embedding-v3 | 1024 维（手写 EmbeddingModel 直连） | 向量化 |
| Milvus | v3.0.0（Docker standalone） | 向量数据库 |
| Redis Stack | latest（Docker，含 RediSearch） | 会话记忆持久化 |

## 架构

```
POST /api/chat (SSE 流式)  /  POST /api/chat/block (整段)
        │
        ├─ 查询改写（无记忆 AI 调用：指代消解，物理隔离历史污染）
        ├─ 回答模型（无记忆，按需自主调用工具）
        │     ├─ PaymentQueryTools   回款数据查询（mock）
        │     └─ KnowledgeQueryTools 知识库检索 → Milvus
        └─ 会话记忆手动读写 → Redis（按 conversationId 隔离，7 天 TTL）
```

关键设计：**回答时模型看不到历史原文**（历史只参与改写环节），从架构上杜绝跨话题夹带。

## 快速开始

```powershell
# 1. 配置环境变量（阿里云百炼 key）
setx DASHSCOPE_API_KEY "sk-你的key"   # 设完重开终端

# 2. 启动依赖中间件（Milvus + Redis Stack）
docker compose up -d

# 3. 启动 Web 服务（默认 8080）
mvn spring-boot:run
```

知识库：把 `.md` / `.pdf` 文件丢进 `src/main/resources/docs/`，重启自动增量入库（文档级幂等，已入库的跳过）。

## 三种运行模式

| 模式 | 命令 | 说明 |
|---|---|---|
| Web 服务（默认） | `mvn spring-boot:run` | 对外 HTTP/SSE 接口 |
| 命令行 | `mvn spring-boot:run "-Dspring-boot.run.profiles=cli"` | 控制台交互 |
| MCP server | `mvn clean package -DskipTests` 后由 Cursor 拉起 | 把工具暴露给 MCP 客户端 |

## API 一览

| 接口 | 说明 |
|---|---|
| `POST /api/chat` | 对话（SSE 流式），body: `{"conversationId","message"}` |
| `POST /api/chat/block` | 对话（一次性返回整段） |
| `GET /api/chat/{conversationId}/history` | 查看会话历史（验证 Redis 持久化） |
| `GET /api/knowledge/search?question=&topK=` | 检索调试：绕过模型直接看向量库命中 |

`api-test.http` 里有现成的请求样例（IDEA 直接点着跑）。

## 已覆盖知识点

- Tool Calling（模型自主决策调工具，Agentic RAG）
- 会话记忆：Redis 持久化 + conversationId 多会话隔离
- SSE 流式 / 非流式双形态接口
- 结构化输出（`.entity()` 提取贷款意向）
- RAG 全链路：PDF/MD 解析 → 切块 → 向量化 → Milvus → 检索 → 生成
- RAG 排障方法论：入库层 / 检索层 / 生成层 三层定罪法
- 查询改写（Conversational RAG 防上下文污染）
- MCP server（stdio，供 Cursor 调用）
- Spring Boot 条件装配排障（`debug: true` 条件评估报告）

## 进行中

- 评估集：标准问答对 + 自动判分 runner（RAG 准确率量化）