AIcode/test/README.md

# CardioAI - 心血管疾病智能辅助系统

## 项目概述

CardioAI是一个多模块应用系统，集成了数据可视化、机器学习预测和AI语音问答功能，用于心血管疾病的智能辅助分析和诊断。

### 系统模块

1. **Module 1: 数据可视化仪表板** (Streamlit) - 本模块
   - 数据清洗与特征工程
   - 交互式数据筛选
   - 可视化分析图表

2. **Module 2: 机器学习预测器** (Flask + XGBoost)
   - 心血管疾病风险预测模型
   - RESTful API接口
   - 实时预测服务

3. **Module 3: AI语音助手** (DeepSeek + CosyVoice)
   - 自然语言问答
   - 语音交互界面
   - 疾病知识查询

## Module 1: 数据可视化仪表板

### 功能特性

- ✅ **数据加载与清洗**: 自动处理异常值和缺失数据
- ✅ **特征工程**: 年龄转换、BMI计算、类别编码
- ✅ **交互式筛选**: 侧边栏多维度数据筛选
- ✅ **可视化分析**: Plotly交互式图表
- ✅ **性能优化**: 使用缓存加速数据加载

### 数据处理流程

1. **数据加载**: 从Excel文件加载原始数据
2. **年龄转换**: 将天数转换为年数（四舍五入）
3. **BMI计算**: `BMI = 体重(kg) / (身高(m)^2)`
4. **异常值处理**:
   - 删除舒张压 ≥ 收缩压的记录
   - 删除收缩压不在[90, 250] mmHg范围的记录
   - 删除舒张压不在[60, 150] mmHg范围的记录
5. **类别转换**:
   - 胆固醇水平: 1=正常, 2=高于正常, 3=极高
   - 血糖水平: 1=正常, 2=高于正常, 3=极高
   - 性别: 1=女性, 2=男性
   - BMI分类: <18.5=偏瘦, 18.5-24.9=正常, 25-29.9=超重, ≥30=肥胖

### 快速开始

#### 1. 环境配置

```bash
# 创建并激活conda虚拟环境
conda create -n cardioenv python=3.10
conda activate cardioenv

# 安装依赖包
pip install -r requirements.txt
```

#### 2. 数据准备

确保数据文件位于正确路径：
```
项目根目录/
├── data/
│   └── 心血管疾病.xlsx
└── module1_dashboard/
    └── cardio_dashboard.py
```

#### 3. 启动仪表板

```bash
# 进入项目根目录
cd D:\Project\PythonProject\AIcode\test

# 激活conda环境
conda activate cardioenv

# 启动Streamlit应用程序
streamlit run module1_dashboard/cardio_dashboard.py
```

或者使用conda直接运行：

```bash
"D:\software\anaconda\Scripts\conda.exe" run -n cardioenv streamlit run module1_dashboard/cardio_dashboard.py
```

#### 4. 访问应用

打开浏览器，访问: [http://localhost:8501](http://localhost:8501)

### 界面说明

#### 侧边栏筛选器
- **年龄范围**: 滑动选择器，筛选指定年龄范围的记录
- **性别**: 多选框，选择要分析的性别（女性/男性）
- **心血管疾病状态**: 多选框，选择疾病状态（有/无）
- **BMI分类**: 多选框，选择BMI分类（偏瘦/正常/超重/肥胖）
- **胆固醇水平**: 多选框，选择胆固醇水平
- **血糖水平**: 多选框，选择血糖水平

#### 主界面区域

1. **关键指标面板**
   - 筛选后记录数
   - 心血管疾病风险率
   - 平均年龄
   - 平均BMI

2. **数据可视化图表**
   - 年龄分布与心血管疾病关系直方图
   - BMI分类对心血管疾病影响的堆叠柱状图
   - 血压关系散点图
   - 胆固醇水平分布饼图
   - 血糖水平分布饼图

3. **数据预览**
   - 数据摘要（形状、类型、缺失值）
   - 原始数据表格（可自定义显示的列）

### 配置文件说明

`.env` 文件包含以下配置项：

```ini
# 数据文件路径
DATA_PATH=./data/心血管疾病.xlsx

# Flask服务器配置
FLASK_APP=module2_predictor/app.py
FLASK_ENV=development

# Streamlit配置
STREAMLIT_PORT=8501

# AI模型API密钥（需要替换为实际值）
DASHSCOPE_API_KEY=your_dashscope_api_key_here
OPENAI_API_KEY=your_openai_api_key_here

# 模型文件路径
MODEL_PATH=./module2_predictor/models/xgb_model.pkl
```

### 依赖包说明

详细依赖见 `requirements.txt`：

- **数据处理**: pandas, numpy, openpyxl
- **机器学习**: scikit-learn, xgboost, joblib
- **可视化**: streamlit, plotly
- **Web服务**: Flask
- **环境管理**: python-dotenv
- **AI集成**: langchain-openai, dashscope, requests

## Module 2: 机器学习预测器

### 功能特性

- ✅ **模型训练**: XGBoost分类器，准确率约73%
- ✅ **特征工程**: 年龄转换、BMI计算、异常值处理
- ✅ **RESTful API**: Flask提供预测接口
- ✅ **前端界面**: 交互式Web表单，实时预测
- ✅ **模型持久化**: Joblib保存完整Pipeline

### 模型训练

#### 1. 训练模型（一次性）
```bash
# 进入项目根目录
cd D:\Project\PythonProject\AIcode\test

# 激活conda环境
conda activate cardioenv

# 运行训练脚本
python module2_predictor/train_and_save.py
```

训练脚本将：
1. 加载和清洗数据（与Module 1相同）
2. 特征工程：年龄转换、BMI计算
3. 构建机器学习Pipeline（StandardScaler + OneHotEncoder + XGBoost）
4. 训练模型并评估性能
5. 保存模型到 `module2_predictor/models/cardio_predictor_model.pkl`

#### 2. 模型特征
- **连续特征**: age_years, bmi, ap_hi, ap_lo
- **分类特征**: gender, cholesterol, gluc
- **二元特征**: smoke, alco, active

**Top 5 重要特征**:
1. 收缩压 (ap_hi)
2. 极高胆固醇 (cholesterol_3)
3. 年龄 (age_years)
4. 舒张压 (ap_lo)
5. 极高血糖 (gluc_3)

### Flask API服务

#### 1. 启动API服务
```bash
# 进入项目根目录
cd D:\Project\PythonProject\AIcode\test

# 激活conda环境
conda activate cardioenv

# 方法1: 直接运行Python脚本
python module2_predictor/app.py

# 方法2: 使用Flask CLI
set FLASK_APP=module2_predictor/app.py
flask run --host=0.0.0.0 --port=5000

# 方法3: 使用conda直接运行
"D:\software\anaconda\Scripts\conda.exe" run -n cardioenv python module2_predictor/app.py
```

#### 2. API端点

| 端点 | 方法 | 描述 |
|------|------|------|
| `/` | GET | 前端预测界面 |
| `/predict_cardio` | POST | 预测接口（接收JSON） |
| `/health` | GET | 健康检查 |
| `/model_info` | GET | 模型信息 |

#### 3. 预测接口示例

**请求**:
```bash
curl -X POST http://localhost:5000/predict_cardio \
  -H "Content-Type: application/json" \
  -d '{
    "age": 20228,
    "gender": 1,
    "height": 156,
    "weight": 85,
    "ap_hi": 140,
    "ap_lo": 90,
    "cholesterol": 1,
    "gluc": 1,
    "smoke": 0,
    "alco": 0,
    "active": 1
  }'
```

**响应**:
```json
{
  "success": true,
  "prediction": 1,
  "probability": 0.85,
  "risk_level": "高危",
  "message": "预测成功",
  "features": {
    "age_years": 55,
    "bmi": 34.9,
    "ap_hi": 140,
    "ap_lo": 90,
    "gender": 1,
    "cholesterol": 1,
    "gluc": 1,
    "smoke": 0,
    "alco": 0,
    "active": 1
  }
}
```

### 前端界面

访问 `http://localhost:5000` 使用预测界面：

1. **输入表单**: 11个特征字段，包含验证和示例数据
2. **实时预测**: 点击"开始预测"获取风险评估
3. **结果展示**: 风险等级、概率、健康建议
4. **示例数据**: 提供低、中、高风险示例数据

### 项目结构

```
module2_predictor/
├── app.py                    # Flask应用主程序
├── train_and_save.py         # 模型训练脚本（一次性）
├── test_api.py               # API测试脚本
├── templates/
│   └── index.html           # 前端界面模板
└── models/                  # 模型文件目录（训练后生成）
    ├── cardio_predictor_model.pkl
    └── feature_info.txt
```

### 测试验证

#### 1. 测试模型加载
```bash
python module2_predictor/test_api.py
```

#### 2. 测试API服务
1. 启动Flask应用：`python module2_predictor/app.py`
2. 打开浏览器访问：`http://localhost:5000`
3. 使用示例数据测试预测功能
4. 检查健康状态：`http://localhost:5000/health`

#### 3. 验证预测准确性
- 测试集准确率：约73%
- 特征重要性符合医学常识
- 风险等级划分合理

### 配置说明

#### 模型参数
- **算法**: XGBoost Classifier
- **树数量**: 100
- **最大深度**: 5
- **学习率**: 0.1
- **子采样率**: 0.8
- **随机种子**: 42

#### 特征预处理
- **连续特征**: StandardScaler标准化
- **分类特征**: OneHotEncoder独热编码
- **二元特征**: 直接使用（0/1）

### 性能指标

| 指标 | 训练集 | 测试集 |
|------|--------|--------|
| 准确率 | 74.21% | 73.14% |
| 特征数量 | 10个 | 10个 |
| 模型大小 | ~1.2 MB | ~1.2 MB |

### 注意事项

1. **模型更新**: 当数据变化时，重新运行训练脚本
2. **输入验证**: API对输入数据有严格的范围验证
3. **血压合理性**: 自动拒绝舒张压≥收缩压的输入
4. **错误处理**: 详细的错误信息和日志记录
5. **性能**: 单次预测时间 < 100ms

### 常见问题

#### Q1: 模型训练失败
**症状**: 训练脚本报错或无法保存模型
**解决**:
1. 检查数据文件路径是否正确
2. 确保有足够的磁盘空间
3. 检查Python依赖包是否完整安装

#### Q2: Flask应用无法启动
**症状**: 启动时出现导入错误或模型加载失败
**解决**:
1. 检查conda环境是否激活
2. 确保模型文件存在：`module2_predictor/models/cardio_predictor_model.pkl`
3. 检查端口5000是否被占用

#### Q3: 预测结果不合理
**症状**: 预测概率总是0或1，或与预期不符
**解决**:
1. 检查输入数据是否在合理范围内
2. 验证特征预处理是否正确
3. 确保模型训练时使用了正确的特征

#### Q4: 前端界面无法访问
**症状**: 浏览器显示连接错误
**解决**:
1. 确认Flask应用正在运行
2. 检查防火墙设置，允许端口5000
3. 尝试访问 `http://localhost:5000/health` 检查服务状态

### 下一步开发

1. **模型优化**: 尝试其他算法（LightGBM, CatBoost）和超参数调优
2. **特征扩展**: 添加更多临床特征（家族史、药物治疗等）
3. **API增强**: 添加批量预测、模型版本管理
4. **监控告警**: 添加性能监控和异常告警
5. **部署优化**: Docker容器化，云平台部署

---

### 常见问题

#### Q1: 数据加载失败
**症状**: 应用程序无法启动，提示文件找不到或格式错误
**解决**:
1. 检查 `data/心血管疾病.xlsx` 文件是否存在
2. 确认文件格式为Excel 2007+ (.xlsx)
3. 检查文件编码，确保不是二进制损坏

#### Q2: 图表显示异常
**症状**: 图表不显示或显示错误
**解决**:
1. 检查Plotly是否正确安装：`pip install plotly`
2. 确保数据经过正确清洗，没有无限值或NaN
3. 检查筛选条件是否过于严格导致无数据

#### Q3: 应用程序运行缓慢
**症状**: 页面响应慢，筛选操作延迟
**解决**:
1. 利用 `@st.cache_data` 装饰器的缓存功能
2. 减少一次性加载的数据量
3. 优化图表复杂度，减少数据点数量

#### Q4: 中文显示乱码
**症状**: 中文文字显示为乱码
**解决**:
1. 确保系统支持中文字体
2. Streamlit默认支持UTF-8编码，检查源代码文件保存为UTF-8
3. 在Windows系统上，设置控制台编码为UTF-8

### 开发说明

#### 项目结构
```
D:\Project\PythonProject\AIcode\test\
├── data\                   # 数据文件目录
│   └── 心血管疾病.xlsx
├── module1_dashboard\     # 数据可视化模块
│   ├── cardio_dashboard.py
│   └── test_data.py
├── module2_predictor\     # 机器学习预测模块
│   └── templates\
├── module3_voice_assistant\ # AI语音助手模块
│   └── templates\
├── requirements.txt       # Python依赖包
├── .env                  # 环境配置
└── README.md            # 项目文档
```

#### 代码结构
- `load_and_process_data()`: 数据加载和清洗主函数，使用 `@st.cache_data` 缓存
- `create_filters()`: 创建侧边栏筛选器组件
- `apply_filters()`: 应用筛选条件到数据框
- `display_metrics()`: 显示关键指标卡片
- `create_visualizations()`: 创建所有可视化图表
- `display_data_preview()`: 显示数据预览和摘要

#### 扩展开发

1. **添加新图表**
   ```python
   def create_new_chart(df):
       fig = px.scatter(df, x='column1', y='column2', color='cardio_str')
       st.plotly_chart(fig, use_container_width=True)
   ```

2. **添加新筛选器**
   ```python
   # 在create_filters函数中添加
   new_filter = st.sidebar.selectbox("新筛选器", options=['选项1', '选项2'])
   ```

3. **自定义样式**
   ```python
   st.markdown("""
   <style>
       .custom-class { color: blue; }
   </style>
   """, unsafe_allow_html=True)
   ```

### 性能优化建议

1. **数据缓存**: 所有数据处理函数使用 `@st.cache_data` 装饰器
2. **增量加载**: 对于大型数据集，考虑分页或懒加载
3. **图表优化**: 使用采样或聚合减少数据点数量
4. **异步处理**: 长时间操作使用异步函数避免阻塞UI

### 下一步计划

1. **Module 2开发**: 实现XGBoost预测模型和Flask API
2. **Module 3开发**: 集成DeepSeek和CosyVoice语音助手
3. **功能增强**: 添加数据导出、报告生成功能
4. **部署优化**: Docker容器化，云平台部署

### 技术支持

- **问题反馈**: 检查GitHub Issues或联系开发团队
- **文档更新**: 随着功能迭代保持文档同步
- **版本管理**: 使用Git进行版本控制，定期发布稳定版本

---

**版权所有 © 2024 CardioAI项目组**  
**版本**: 1.0.0  
**最后更新**: 2024-04-02