# Agent_Project

**Repository Path**: yu-yi123/agent_-project

## Basic Information

- **Project Name**: Agent_Project
- **Description**: 基于 **FastAPI + LangChain + LangGraph + Vue 3 + 阿里百炼大模型** 的企业级 AI Agent 全栈解决方案，支持智能意图路由、RAG 知识库问答、Agent 原生 Function Calling 工具调用、多Agent编排、多轮对话记忆管理、SSE 流式输出、全链路防幻觉机制。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 4
- **Forks**: 1
- **Created**: 2026-05-15
- **Last Updated**: 2026-09-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🤖 企业级 AI Agent 全栈应用

基于 **FastAPI + LangChain + LangGraph + Vue 3 + 阿里百炼大模型** 的企业级 AI Agent 全栈解决方案，支持智能意图路由、RAG 知识库问答、Agent 原生 Function Calling 工具调用、多Agent编排、多轮对话记忆管理、SSE 流式输出、全链路防幻觉机制。

---

## 一、技术架构

### 1.1 后端技术栈

| 分类 | 技术 | 版本 | 用途 |
|------|------|------|------|
| Web 框架 | **FastAPI** | 0.110.0 | 高性能异步 Web 服务，自动生成 OpenAPI 文档 |
| ASGI 服务器 | **Uvicorn** | 0.27.1 | 生产级 ASGI 服务器，支持多 workers |
| AI 框架 | **LangChain Community** | 0.0.33 | ChatTongyi 大模型封装、工具绑定、文本分块 |
| 多Agent编排 | **LangGraph** | 0.2.50 | 意图路由 → RAG → Agent 流程调度 |
| 大模型服务 | **阿里百炼 DashScope** | 1.20.1 | 通义千问 qwen-max + text-embedding-v2 + gte-rerank |
| 关系数据库 | **MySQL 8.0** + **SQLAlchemy 2.0** | 8.0 / 2.0 | 持久化存储 + ORM + 连接池 |
| 缓存服务 | **Redis** | 5.0.3 | 短期对话记忆 / 会话缓存 / 限流计数器 |
| 向量数据库 | **ChromaDB** | 0.4.24 | Embedding 向量存储（子进程隔离防 segfault） |
| 认证鉴权 | **python-jose + passlib + bcrypt** | 最新 | JWT (HS256) + bcrypt 密码哈希 |
| 配置管理 | **pydantic-settings** | 2.2.1 | 环境变量类型校验，.env 自动加载 |
| 日志系统 | **loguru** | 0.7.2 | 结构化日志（按天轮转、自动压缩、彩色输出） |
| 接口限流 | **slowapi** | 0.1.9 | FastAPI 接口限流中间件，防暴力请求 |
| HTTP 客户端 | **httpx** | 0.27.0 | 异步 HTTP 客户端，用于调用外部 API |
| 模板引擎 | **Jinja2** | 3.1.3 | 邮件模板渲染（变量替换 + 条件判断） |
| 异步文件 | **aiofiles** | 23.2.1 | 异步文件读写，不阻塞事件循环 |
| 文档解析 | **pypdf + python-docx + openpyxl** | 最新 | PDF / Word / Excel 多格式文档解析 |
| 文件检测 | **python-magic** | 0.4.27 | 文件签名识别，防止伪造扩展名 |
| 数据库迁移 | **Alembic** | 1.13.1 | 数据库版本迁移工具 |

### 1.2 前端技术栈

| 分类 | 技术 | 版本 | 用途 |
|------|------|------|------|
| 框架 | **Vue 3** | ^3.4.21 | Composition API + `<script setup>` |
| 构建工具 | **Vite** | ^5.1.6 | 极速开发/构建（HMR 热模块替换） |
| UI 组件库 | **Element Plus** | ^2.13.7 | 企业级组件库（含图标库） |
| 图标库 | **@element-plus/icons-vue** | ^2.3.2 | Element Plus 配套图标 |
| 状态管理 | **Pinia** | ^2.1.7 | 组合式 Store，管理会话/消息/加载状态 |
| HTTP 请求 | **Axios** | ^1.6.7 | 拦截器（JWT 注入/错误处理/超时控制） |
| Markdown 渲染 | **marked** | ^12.0.1 | Markdown → HTML，支持 GFM |
| 代码高亮 | **highlight.js** | ^11.9.0 | 代码块语法高亮（多语言支持） |
| 路由管理 | **vue-router** | ^4.3.0 | 前端路由管理（登录/聊天/知识库） |
| 日期处理 | **dayjs** | ^1.11.10 | 轻量级日期格式化与计算 |
| CSS 预处理器 | **Less** | ^4.2.0 | 可编程 CSS 编写，变量/嵌套/Mixins |

---

## 二、核心功能

### 2.1 智能意图路由（后端自动分流）

**功能描述**：前端不再需要手动切换模式，后端通过大模型自动识别用户意图并智能分流到对应的业务链路。

**意图分类体系**：

| 意图类型 | 触发场景 | 自动分流 | 示例 |
|---------|---------|---------|------|
| **chat** | 日常问候、寒暄、情感交流 | 普通对话模式 | "你好"、"今天天气怎么样" |
| **rag** | 查询企业知识、政策、流程 | RAG 检索增强模式 | "公司的请假流程是什么" |
| **agent** | 查询数据库、生成报表、发邮件 | Agent 工具调用模式 | "查询上个月销售额" |
| **rag_agent** | 既查知识库又需工具操作 | RAG + Agent 混合模式 | "根据公司政策，查询数据并生成报表" |

**技术实现**：
- 大模型意图分类（temperature=0.1，确保分类稳定）
- 系统提示词定义四类意图的判断规则
- 识别失败自动降级到 RAG 模式，保证高可用
- 前端单一聊天入口，全自动智能分流

### 2.2 RAG 知识库问答（Rerank 重排序增强）

**功能描述**：基于混合检索架构的企业级知识库问答系统，支持向量语义检索、Rerank 重排序、关键词降级检索。

**检索流程**：

```
用户查询 → 向量检索（Top10） → Rerank 重排序 → 过滤低分片段 → 保留 Top5 → 大模型生成回答
```

**1. 向量检索（ChromaDB，子进程隔离）**：
- 召回 Top10 供 Rerank 使用
- 相似度阈值 0.65，低于直接过滤
- 去重处理，保留最相关分块
- 子进程隔离：Chroma C 扩展 segfault 不影响主进程

**2. Rerank 重排序（阿里百炼 gte-rerank）**：
- 向量召回 Top10 → Rerank 精细打分
- 分数阈值 0.35，低于过滤
- 按分数重排，保留 Top5 入大模型
- API 调用失败自动降级到原始 TopK

**3. 关键词检索（MySQL LIKE，降级方案）**：
- 向量服务故障时自动降级
- 智能关键词提取（正则替换、停用词过滤、长词拆分）
- 有效片段＜3条触发拒答
- 意图粗匹配过滤无关分块

**防幻觉机制**：
- RAG 专属温度参数 `temperature=0.2`（压制随机性）
- 强约束系统提示词：仅允许使用传入的知识库作答
- 低置信度自动拒答（多维度判断）
- 后置事实校验：数字/日期/条款溯源校验
- 标准化兜底话术

### 2.3 Agent 工具调用（Function Calling）

**功能描述**：基于阿里通义大模型原生 Function Calling 协议的智能体工具调用系统，支持多工具串联执行、动态工具过滤、智能延续机制。

**架构流程**：
```
用户问题 → 意图识别 → 动态工具过滤 → LLM 决定调用工具 → 执行工具 → 回填结果 → 循环完成
```

**关键特性**：

- **动态工具过滤**：根据关键词意图决定暴露哪些工具
  - 查询类 → 只暴露 `sql_query_tool`
  - 导出类 → 暴露 `sql_query_tool` + `excel_report_tool`
  - 邮件类 → 暴露全部三个工具

- **智能延续机制**：工具执行成功后引导下一步，避免死循环
- **错误终止机制**：工具返回错误立即终止，不再喂给模型
- **历史上下文感知**：避免重复执行已完成的步骤
- **短路判断**：查询结果为空时不再继续后续工具

**可用工具**：

| 工具 | 功能 | 技术实现 |
|------|------|---------|
| **SQL Query Tool** | 自然语言转 SQL 查询 | NL2SQL + 三层安全防线（SELECT 白名单/词边界检测/参数化执行） |
| **Excel Report Tool** | 生成带样式 Excel 报表 | openpyxl 样式美化（表头蓝色背景/偶行变色/自适应列宽） |
| **Email Tool** | 发送 HTML 邮件 | SMTP + HTML 自动转换 + 附件支持 |

### 2.4 LangGraph 多Agent编排（可选启用）

**功能描述**：基于 LangGraph 的多节点流程编排系统，支持条件路由、结果汇总、混合任务处理。

**节点流程**：
```
意图路由节点 → RAG问答节点 → Agent工具节点 → 结果汇总节点 → END
```

**节点说明**：

| 节点 | 功能 | 说明 |
|------|------|------|
| **意图路由节点** | 识别用户意图 | 调用 classify_intent 自动分类 |
| **RAG问答节点** | 知识库检索回答 | 复用 rag_service 检索和生成 |
| **Agent工具节点** | 工具调用执行 | 复用 agent_service 执行工具链 |
| **普通聊天节点** | 纯对话回答 | 复用 llm_service 生成回答 |
| **结果汇总节点** | 多源结果融合 | RAG+Agent 混合模式的结果汇总 |

**特性**：
- 完全复用现有服务，原有代码一行不删
- 条件路由：根据意图自动分支
- 支持 RAG+Agent 混合任务的结果汇总
- 默认关闭，配置 `USE_LANGGRAPH = True` 启用

### 2.5 多轮对话记忆管理

**功能描述**：双层记忆系统，短期记忆基于 Redis，长期记忆基于 MySQL，支持多轮上下文理解和历史对话回溯。

**短期记忆（Redis）**：
- 存储当前会话最近 5 轮对话（10 条消息）
- 24 小时自动过期
- 支持多轮上下文理解

**长期记忆（MySQL）**：
- 对话结束后生成摘要存入数据库
- 支持用户回溯历史对话
- 支持对话详情查看

### 2.6 知识库文档管理

**功能描述**：支持多种文档格式的上传、解析、分块、向量化全流程管理。

**支持格式**：PDF / Word / Excel / TXT / Markdown

**处理流程**：
1. **文档上传**：文件格式白名单校验
2. **文档解析**：多格式统一转换为纯文本
   - PDF：pdfminer.six 逐页提取
   - Word：python-docx 提取段落
   - Excel：openpyxl 逐行读取
3. **语义分块**：RecursiveCharacterTextSplitter 递归分割
   - 优先按段落分割（\n\n）
   - 段落太长则按行分割（\n）
   - 行太长则按句号分割（。）
4. **向量入库**：text-embedding-v2 生成向量，写入 ChromaDB

### 2.7 SSE 流式输出

**功能描述**：基于 Server-Sent Events 的实时流式输出，支持多种事件类型推送，前端打字机效果。

**技术实现**：
- 后端使用 Python async generator 逐步 yield SSE 事件
- 前端使用 EventSource 接收流式数据
- 支持多种事件类型：text / agent_thought / tool_call / tool_result / references / done
- 前端打字机效果，用户体验优化

---

## 三、项目结构

```
d:/Agent_Project/
├── backend/
│   ├── app/
│   │   ├── api/                    # API 路由层
│   │   │   ├── auth.py             # 用户认证（注册/登录/JWT）
│   │   │   ├── chat.py             # 智能对话（会话管理/消息发送/流式输出/意图路由）
│   │   │   ├── knowledge.py        # 知识库管理（文档上传/列表/删除/分块预览）
│   │   │   └── agent.py            # Agent 工具配置（工具列表/测试调用）
│   │   ├── core/                   # 基础设施层
│   │   │   ├── security.py         # JWT 认证/密码哈希
│   │   │   ├── logger.py           # loguru 日志配置
│   │   │   ├── rate_limit.py       # slowapi 接口限流
│   │   │   └── exceptions.py       # 全局异常处理
│   │   ├── models/                 # SQLAlchemy ORM 模型层
│   │   │   ├── user.py             # 用户模型
│   │   │   ├── conversation.py     # 会话/消息模型
│   │   │   └── document.py         # 文档/分块模型
│   │   ├── schemas/                # Pydantic 数据校验层
│   │   │   ├── user.py             # 用户请求/响应 Schema
│   │   │   ├── chat.py             # 对话请求/响应 Schema
│   │   │   └── document.py         # 文档 Schema
│   │   ├── services/               # 业务服务层
│   │   │   ├── llm_service.py      # LLM 统一调用（LangChain ChatTongyi）
│   │   │   ├── rag_service.py      # RAG 混合检索（向量 + Rerank + 关键词降级）
│   │   │   ├── agent_service.py    # Agent Function Calling 循环
│   │   │   ├── agent_graph.py      # LangGraph 多Agent编排
│   │   │   ├── intent_router.py    # 意图自动路由
│   │   │   ├── memory_service.py   # 对话记忆管理（Redis + MySQL）
│   │   │   ├── document_service.py # 文档解析/分块/向量化
│   │   │   └── vector_search_service.py  # Chroma 向量检索
│   │   ├── tools/                  # Agent 工具层（BaseTool 继承）
│   │   │   ├── sql_query_tool.py   # SQL 查询（三层安全防线）
│   │   │   ├── excel_report_tool.py # Excel 报表生成
│   │   │   └── email_tool.py       # 邮件发送
│   │   ├── config.py               # 配置管理（含防幻觉 + Rerank 参数）
│   │   ├── database.py             # 数据库连接/会话管理
│   │   └── main.py                 # FastAPI 入口（路由注册/中间件/生命周期）
│   ├── Dockerfile                  # Docker 构建文件（python:3.10-slim）
│   ├── requirements.txt            # Python 依赖清单
│   └── .env                        # 环境变量配置
├── frontend/
│   ├── src/
│   │   ├── api/                    # Axios 接口封装
│   │   │   ├── auth.js             # 认证接口
│   │   │   ├── chat.js             # 对话接口（含 SSE 流式）
│   │   │   └── knowledge.js        # 知识库接口
│   │   ├── stores/                 # Pinia 状态管理
│   │   │   └── chat.js             # 聊天状态（会话/消息/模式/加载）
│   │   ├── views/                  # 页面组件
│   │   │   ├── ChatView.vue        # 聊天主页面
│   │   │   ├── KnowledgeView.vue   # 知识库管理页面
│   │   │   ├── Login.vue           # 登录页面
│   │   │   └── Register.vue        # 注册页面
│   │   ├── utils/                  # 工具函数
│   │   │   └── request.js          # Axios 封装（JWT 注入/错误处理/超时）
│   │   ├── router/                 # 路由配置
│   │   └── main.js                 # Vue 入口
│   ├── Dockerfile                  # 多阶段构建（Node 编译 → Nginx 运行）
│   ├── nginx.conf                  # Nginx 配置（SPA 路由 + API 反向代理 + SSE 支持）
│   └── package.json                # Node.js 依赖
├── docker-compose.yml              # Docker Compose 一键部署（MySQL/Redis/后端/前端）
├── pyrightconfig.json               # Python 类型检查配置
├── logs/                           # 应用日志目录（后端运行时生成）
└── README.md                       # 项目文档
```

---

## 四、快速开始

### 4.1 环境要求

- Python 3.11+
- Node.js 20+
- MySQL 8.0+
- Redis 5.0+

### 4.2 后端启动

```bash
cd backend
pip install -r requirements.txt
cp .env.example .env
# 编辑 .env 文件，配置 API Key 和数据库连接
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

### 4.3 前端启动

```bash
cd frontend
npm install
npm run dev
```

访问 http://localhost:5173 使用应用。

### 4.4 Docker 一键部署

项目提供完整的 Docker Compose 编排，一键启动所有服务。

```bash
# 1. 克隆项目
git clone <your-repo-url>
cd Agent_Project

# 2. 配置环境变量
cp backend/.env.example backend/.env
# 编辑 .env，填写 DASHSCOPE_API_KEY 和数据库密码

# 3. 一键启动（四个容器）
docker-compose up -d

# 4. 查看启动日志
docker-compose logs -f

# 5. 访问应用
# 前端：http://localhost:80
# 后端 API：http://localhost:8000
# API 文档：http://localhost:8000/docs
```

**Docker 服务架构：**

```
┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│  MySQL   │    │  Redis   │    │  FastAPI │    │  Nginx   │
│  8.0     │    │  7       │    │  后端    │    │  前端    │
│ :3307    │    │ :6379    │    │ :8000    │    │ :80      │
└────┬─────┘    └────┬─────┘    └────┬─────┘    └────┬─────┘
     │               │               │               │
     └───────────────┴───────────────┴───────────────┘
                    Docker 内部网络
```

**Docker 卷持久化说明：**

| 卷名 | 用途 | 存储路径 |
|------|------|---------|
| `mysql_data` | MySQL 数据文件 | `/var/lib/mysql` |
| `redis_data` | Redis RDB/AOF 持久化 | `/data` |
| `backend_logs` | 应用日志 | `/app/logs` |
| `backend_uploads` | 用户上传文档 | `/app/uploaded_files` |
| `backend_reports` | 生成的 Excel 报表 | `/app/generated_reports` |
| `backend_chroma` | 向量数据库持久化 | `/app/chroma_data` |

**Dockerfile 构建特点：**

- **后端**：`python:3.10-slim` 基础镜像，利用 Docker 缓存层加速构建（requirements.txt 不变则跳过 pip install）
- **前端**：多阶段构建（Node 18 编译 → Nginx Alpine 运行），最终镜像仅约 25MB
- **Nginx 配置**：SPA 路由重定向 + `/api/` 反向代理到后端 + SSE 流式传输支持（关闭缓冲、24h 长超时）

---

## 五、企业级防幻觉机制

### 5.1 检索层拦截

- 向量检索相似度阈值 0.65，低于直接过滤
- Rerank 重排序（Top10 → 精细打分 → Top5）
- Rerank 分数阈值 0.35，低于过滤
- MySQL 关键词检索有效片段＜3条触发拒答
- 意图粗匹配过滤无关分块

### 5.2 模型层控制

- RAG 专属温度参数 `temperature=0.2`（压制随机性）
- 强约束系统提示词：仅允许使用知识库作答
- 禁止编造数字/日期/条款/专有名词

### 5.3 拒答机制

- 平均相似度＜0.65 → 自动拒答
- 有效分块＜3条 → 自动拒答
- 最高相似度＜0.7 → 自动拒答
- 标准化兜底话术

### 5.4 事实校验

- 后置轻量校验：数字/日期/条款溯源
- 无法溯源的内容记录警告日志

---

## 六、API 接口文档（后端路由总览）

### 6.1 认证服务 `/api/auth`

| 方法 | 路径 | 功能 | 认证 |
|------|------|------|------|
| POST | `/api/auth/register` | 用户注册（用户名 + 密码） | ❌ |
| POST | `/api/auth/login` | 用户登录，返回 JWT Token | ❌ |
| GET | `/api/auth/me` | 获取当前用户信息 | ✅ |

### 6.2 对话服务 `/api/chat`

| 方法 | 路径 | 功能 | 认证 |
|------|------|------|------|
| POST | `/api/chat/conversations` | 创建新会话 | ✅ |
| GET | `/api/chat/conversations` | 获取会话列表（分页） | ✅ |
| DELETE | `/api/chat/conversations/{id}` | 逻辑删除会话 | ✅ |
| GET | `/api/chat/conversations/{id}/messages` | 获取会话消息历史 | ✅ |
| POST | `/api/chat/send` | **发送消息（核心接口，SSE 流式返回）** | ✅ |

### 6.3 知识库服务 `/api/knowledge`

| 方法 | 路径 | 功能 | 认证 |
|------|------|------|------|
| GET | `/api/knowledge/documents` | 获取文档列表 | ✅ |
| POST | `/api/knowledge/upload` | 上传文档（PDF/Word/Excel/TXT/MD） | ✅ |
| DELETE | `/api/knowledge/documents/{id}` | 删除文档及向量索引 | ✅ |
| GET | `/api/knowledge/documents/{id}/chunks` | 查看文档分块详情 | ✅ |
| POST | `/api/knowledge/reindex` | 重新索引所有文档 | ✅ |

### 6.4 Agent 工具服务 `/api/agent`

| 方法 | 路径 | 功能 | 认证 |
|------|------|------|------|
| GET | `/api/agent/tools` | 获取可用工具列表 | ✅ |
| POST | `/api/agent/test/{tool_name}` | 测试调用指定工具 | ✅ |

### 6.5 SSE 事件类型

| 事件类型 | 含义 | 数据格式 |
|----------|------|---------|
| `text` | AI 回复文本片段 | `{"type":"text","content":"..."}` |
| `tool_call` | Agent 正在调用工具 | `{"type":"tool_call","tool_name":"...","tool_input":"..."}` |
| `tool_result` | 工具执行结果 | `{"type":"tool_result","tool_name":"...","content":"..."}` |
| `references` | RAG 引用的知识来源 | `{"type":"references","sources":[...]}` |
| `done` | 流式输出结束 | `{"type":"done"}` |

---

## 七、安全特性

### 7.1 SQL 工具三层安全防线

```python:41:55:backend\app\tools\sql_query_tool.py
防线①：语句校验 — 正则 ^\\s*select\\b 确保以 SELECT 开头，拦截 DELETE/DROP/ALTER/INSERT
防线②：词边界检测 — \\bkeyword\\b 精确匹配，避免字段名误杀（如 updated_at 中的 update）
防线③：参数化执行 — SQLAlchemy text() 参数化，防 SQL 注入
```

### 7.2 JWT 认证

- **算法**：HS256（HMAC with SHA-256）
- **Token 有效期**：24 小时（可配置）
- **密码存储**：bcrypt 哈希，不存明文
- **中间件注入**：FastAPI Depends 自动校验，无需手动处理

### 7.3 接口限流

- **中间件**：slowapi
- **策略**：每分钟最多 10 次请求（可配置）
- **范围**：全局 API 限流，防暴力请求

### 7.4 文件上传安全

- **格式白名单**：仅允许 PDF / Word / Excel / TXT / Markdown
- **签名校验**：python-magic 通过文件内容识别真实类型，防伪造扩展名
- **大小限制**：Nginx `client_max_body_size 20m`

---

## 八、日志管理

### 8.1 日志架构

```python
# backend/app/core/logger.py
logger.add(
    "./logs/app_{time:YYYY-MM-DD}.log",       # 按天生成日志文件
    rotation="50 MB",                           # 单文件超过 50MB 自动轮转
    compression="zip",                          # 轮转后自动压缩为 .zip
    level="DEBUG",                              # 开发环境 DEBUG，生产环境 INFO
    format="{time} | {level} | {name}:{line} | {message}",
    enqueue=True,                                # 多线程安全写入
    backtrace=True,                              # 异常时输出完整堆栈
)
```

### 8.2 日志分类

| 日志级别 | 记录内容 |
|----------|---------|
| `INFO` | 正常流程：意图识别结果、模式选择、工具调用开始/结束 |
| `WARNING` | 降级事件：向量检索超时 → 降级到关键词、Rerank API 失败、事实校验失败 |
| `ERROR` | 系统异常：API 调用失败、数据库连接失败、文件解析异常 |

### 8.3 日志文件位置

```
backend/logs/
├── app_2026-05-14.log     # 当天日志
├── app_2026-05-13.zip     # 历史日志（自动压缩）
├── app_2026-05-12.zip
└── ...
```

---

## 九、配置说明

### 9.1 核心配置（config.py）

```python
# ── 模型配置 ──
LLM_MODEL: str = "qwen-max"                # 阿里百炼大模型
EMBEDDING_MODEL: str = "text-embedding-v2" # Embedding 模型
LLM_TEMPERATURE: float = 0.7               # 普通对话温度
LLM_MAX_TOKENS: int = 2000                 # 最大输出 token
LLM_TOP_P: float = 0.8                     # Top-p 采样
RAG_TEMPERATURE: float = 0.2               # RAG 模式专属温度

# ── Rerank 重排序 ──
RERANK_MODEL: str = "gte-rerank"           # 阿里百炼 Rerank 模型
RERANK_TOP_K: int = 10                     # 向量召回数量（供 Rerank 筛选）
RERANK_OUTPUT_TOP_K: int = 5               # Rerank 后保留 Top5
RERANK_SCORE_THRESHOLD: float = 0.35       # Rerank 分数阈值

# ── 防幻觉参数 ──
RAG_SIMILARITY_THRESHOLD: float = 0.65     # 向量相似度阈值
RAG_MIN_VALID_CHUNKS: int = 3              # 最小有效分块数
RAG_CHUNK_SIZE: int = 500                  # 文档分块大小
RAG_CHUNK_OVERLAP: int = 50                # 分块重叠大小
RAG_TOP_K: int = 5                         # 默认召回数量

# ── Agent 参数 ──
AGENT_MAX_ITERATIONS: int = 5              # 最大工具调用轮次
AGENT_MAX_RETRIES: int = 2                 # 工具失败重试次数

# ── LangGraph 编排 ──
USE_LANGGRAPH: bool = False                # 默认关闭，设为 True 启用

# ── SMTP 邮件配置 ──
SMTP_HOST: str = "smtp.qq.com"            # SMTP 服务器地址
SMTP_PORT: int = 465                       # SMTP 端口（SSL）
SMTP_USE_SSL: bool = True                  # 是否启用 SSL

# ── JWT 认证 ──
JWT_ALGORITHM: str = "HS256"              # Token 加密算法
JWT_EXPIRE_MINUTES: int = 1440            # Token 有效期（24小时）

# ── 限流 ──
RATE_LIMIT_PER_MINUTE: int = 10           # 每分钟最大请求数

# ── 兜底话术 ──
FALLBACK_NO_KNOWLEDGE: str = "当前知识库未查询到相关信息，无法为您解答。"
FALLBACK_LOW_CONFIDENCE: str = "当前知识库未查询到相关信息，无法为您解答。"
FALLBACK_RETRIEVAL_ERROR: str = "检索服务暂时不可用，请稍后重试。"
FALLBACK_VECTOR_TIMEOUT: str = "向量检索超时，已切换至关键词检索模式。"
```

### 9.2 环境变量（.env）

```bash
# ── 阿里百炼（必填）──
DASHSCOPE_API_KEY=your_api_key

# ── MySQL 数据库 ──
MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=your_password
MYSQL_DATABASE=agent_project

# ── Redis 缓存 ──
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_DB=0

# ── SMTP 邮件（Agent 发邮件功能需要）──
SMTP_HOST=smtp.qq.com
SMTP_PORT=465
SMTP_USER=your_email@qq.com
SMTP_PASSWORD=your_auth_code

# ── Chroma 向量库 ──
CHROMA_PERSIST_DIR=./chroma_data

# ── JWT 密钥 ──
JWT_SECRET_KEY=your-jwt-secret-key-change-in-production
```

---

## 十、技术亮点

### 10.1 LangChain 原生 Function Calling

- 放弃手写 ReAct 格式，改用阿里通义原生协议
- 结构化 JSON 参数自动解析（无需正则提取）
- 支持多工具串联（SQL→Excel→Email）
- Pydantic Schema 自动校验工具参数

### 10.2 企业级混合检索

- 向量检索（ChromaDB）+ Rerank 重排序 + 关键词检索（MySQL LIKE）
- 子进程隔离：Chroma C 扩展 segfault 不影响主进程
- 自动降级：向量服务故障时切换到关键词检索

### 10.3 全链路防幻觉

- 检索层：相似度阈值 + Rerank 重排序 + 去重 + 意图匹配
- 模型层：低温度参数 + 强约束提示词
- 拒答层：多条件判断 + 标准化话术
- 校验层：事实溯源校验

### 10.4 意图自动路由

- 大模型自动识别用户意图（chat / rag / agent / rag_agent）
- 前端单一聊天入口，后端全自动智能分流
- 识别失败自动降级，保证高可用

### 10.5 LangGraph 多Agent编排

- 基于现有 LangChain 生态接入，不替换框架
- 多节点流程调度：意图路由 → RAG → Agent → 结果汇总
- 完全复用现有服务，原有代码一行不删

### 10.6 SQL 安全三层防线

- 防线1：SELECT 语句白名单校验（正则匹配）
- 防线2：词边界关键词检测（字符串剥离后检查）
- 防线3：SQLAlchemy text() 参数化执行

### 10.7 SSE 流式输出

- 所有模式支持 Server-Sent Events
- 前端打字机效果，用户体验优化
- 工具调用事件实时推送

---

## 十一、常见问题

### Q: API Key 配置错误？
A: 检查 `.env` 文件中的 `DASHSCOPE_API_KEY` 是否正确填写。

### Q: 向量检索超时？
A: ChromaDB 首次加载索引较慢，属正常现象。持久化目录为 `./chroma_data`。

### Q: 工具调用失败？
A: 检查工具配置（如 SMTP 邮件配置、数据库表结构）是否完整。

### Q: RAG 回答不准确？
A: 检查知识库文档质量，确保上传的文档内容清晰、结构化。也可以调整 Rerank 分数阈值（`RERANK_SCORE_THRESHOLD`）和相似度阈值（`RAG_SIMILARITY_THRESHOLD`）。

### Q: 如何启用 LangGraph？
A: 在 `config.py` 中设置 `USE_LANGGRAPH = True`，重启后端即可。

### Q: Docker 部署后前端访问报 502？
A: 检查后端是否成功启动：`docker-compose logs backend`。后端依赖 MySQL 和 Redis 健康状态才启动，首次启动可能需要等待 30-60 秒。

### Q: Agent 工具调用陷入死循环？
A: 系统有 6 层防死循环机制（max_iterations=5、工具报错终止、空结果终止等）。如果仍然遇到，检查 `AGENT_MAX_ITERATIONS` 配置是否合理。

### Q: ChromaDB 启动报错 segfault？
A: 这是 ChromaDB C 扩展的已知问题。项目已通过子进程隔离处理：向量检索在独立子进程中执行，崩溃不会影响主进程，同时自动降级到 MySQL LIKE 关键词检索。

### Q: 如何切换到大模型（如 DeepSeek / GLM）？
A: 修改 `config.py` 中的 `LLM_MODEL` 为对应模型 ID。如果使用非阿里百炼模型，需要替换 `ChatTongyi` 为对应 LangChain 封装类，并适配 API Key。

---

## 十二、更新日志

### v1.3.0（2026-05-15）
- ✅ 完善项目文档：新增 Docker 部署说明、API 接口文档、安全特性、日志管理章节
- ✅ 补充前端 Less/Element Plus Icons/dayjs 等技术栈
- ✅ 新增常见问题（Docker 排错、死循环、Chroma segfault、模型切换）
- ✅ 配置说明完善：SMTP 邮件、兜底话术、Agent 参数、JWT 配置

### v1.2.0（2026-05-14）
- ✅ RAG 模块接入 Rerank 重排序（阿里百炼 gte-rerank）
- ✅ 后端自动意图路由（大模型分类，前端单一入口）
- ✅ LangGraph 多Agent编排（可选启用）
- ✅ 前端精简：删除模式切换按钮

### v1.1.0（2026-05-14）
- ✅ 企业级防幻觉全链路升级
- ✅ RAG 专属温度参数控制
- ✅ 低置信度自动拒答机制
- ✅ 后置轻量事实校验
- ✅ 标准化兜底话术

### v1.0.0（初始版本）
- ✅ 四种聊天模式
- ✅ Agent 原生 Function Calling
- ✅ RAG 混合检索
- ✅ SSE 流式输出
- ✅ 多轮对话记忆管理

---

## 十三、技术支持

如有问题，请查看日志文件 `backend/logs/` 或提交 Issue。