From 5db2c7549292e2caa13f66d2d7ead14231b16490 Mon Sep 17 00:00:00 2001 From: 2311020116lhh <3201770152@qq.com> Date: Thu, 15 Jan 2026 22:01:53 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E6=B7=BB=E5=8A=A0=E4=B8=80=E9=94=AE?= =?UTF-8?q?=E5=AE=89=E8=A3=85=E8=84=9A=E6=9C=AC=E5=AE=9E=E7=8E=B0=E5=BC=80?= =?UTF-8?q?=E7=AE=B1=E5=8D=B3=E7=94=A8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 添加 install.bat Windows一键安装脚本 - 添加 install.sh Linux/Mac一键安装脚本 - 添加 auto_install.py 跨平台自动化安装脚本 - 更新 README.md 添加详细的一键安装说明 - 测试环境检查脚本功能正常 --- README.md | 169 ++++++++++++++++++++++++++++++--- auto_install.py | 241 ++++++++++++++++++++++++++++++++++++++++++++++++ install.bat | 112 ++++++++++++++++++++++ install.sh | 96 +++++++++++++++++++ 4 files changed, 604 insertions(+), 14 deletions(-) create mode 100644 auto_install.py create mode 100644 install.bat create mode 100644 install.sh diff --git a/README.md b/README.md index a5ec269..70517b0 100644 --- a/README.md +++ b/README.md @@ -8,26 +8,33 @@ ml_course_design/ ├── pyproject.toml # 项目配置与依赖 ├── uv.lock # 锁定的依赖版本 -├── README.md # 项目说明与报告 -├── .env.example # 环境变量模板 -├── .gitignore # Git 忽略规则 +├── requirements.txt # Python依赖列表 +├── setup.py # 包安装脚本 +├── README.md # 项目说明与报告 +├── QUICKSTART.md # 快速开始指南 +├── .env.example # 环境变量模板 +├── .gitignore # Git 忽略规则 +├── install.bat # Windows一键安装脚本 +├── install.sh # Linux/Mac一键安装脚本 +├── auto_install.py # 跨平台自动化安装脚本 +├── check_environment.py # 环境检查脚本 │ -├── data/ # 数据目录 -│ └── README.md # 数据来源说明 +├── data/ # 数据目录 +│ └── README.md # 数据来源说明 │ -├── models/ # 训练产物 +├── models/ # 训练产物 │ └── .gitkeep │ -├── src/ # 核心代码 +├── src/ # 核心代码 │ ├── __init__.py -│ ├── data.py # 数据读取/清洗 -│ ├── features.py # Pydantic 特征模型 -│ ├── train.py # 训练与评估 -│ ├── infer.py # 推理接口 -│ ├── agent_app.py # Agent 入口 -│ └── streamlit_app.py # Demo 入口 +│ ├── data.py # 数据读取/清洗 +│ ├── features.py # Pydantic 特征模型 +│ ├── train.py # 训练与评估 +│ ├── infer.py # 推理接口 +│ ├── agent_app.py # Agent 入口 +│ └── streamlit_app.py # Demo 入口 │ -└── tests/ # 测试 +└── tests/ # 测试 └── test_*.py ``` @@ -131,6 +138,47 @@ ml_course_design/ ## 快速开始 +### 🚀 一键安装（推荐） + +**最简单的方式 - 只需运行一个脚本！** + +#### Windows 用户 + +双击运行 `install.bat` 文件，或在命令行中执行： + +```bash +install.bat +``` + +#### Linux/Mac 用户 + +```bash +chmod +x install.sh +./install.sh +``` + +#### 跨平台方式（使用Python） + +```bash +python auto_install.py +``` + +**一键安装脚本会自动完成以下步骤：** +1. ✓ 检查Python版本 +2. ✓ 安装所有依赖包 +3. ✓ 提示下载数据文件 +4. ✓ 自动训练模型（如果需要） +5. ✓ 运行环境检查 +6. ✓ 启动Web界面 + +**注意：** 首次运行时，脚本会提示您下载数据文件，请按照提示操作。 + +--- + +### 手动安装 + +如果您希望手动控制每个步骤，请按照以下说明操作： + ### 前置要求 - Python 3.10 或更高版本 @@ -213,6 +261,99 @@ streamlit run src/streamlit_app.py 查看 [QUICKSTART.md](QUICKSTART.md) 获取详细的使用说明和常见问题解答。 +--- + +## 一键安装脚本说明 + +### 脚本功能 + +我们提供了三个自动化安装脚本，让您无需手动执行多个步骤： + +| 脚本文件 | 适用平台 | 使用方法 | +|-----------|---------|---------| +| `install.bat` | Windows | 双击运行或在命令行执行 `install.bat` | +| `install.sh` | Linux/Mac | `chmod +x install.sh && ./install.sh` | +| `auto_install.py` | 跨平台 | `python auto_install.py` | + +### 自动化流程 + +脚本会自动完成以下步骤： + +1. **环境检查** + - 验证Python版本（需要3.10+） + - 检查必要的依赖包 + +2. **依赖安装** + - 自动安装所有Python依赖 + - 支持国内镜像源加速 + +3. **数据准备** + - 检查数据文件是否存在 + - 提供数据下载链接和说明 + +4. **模型训练** + - 自动训练模型（如果不存在） + - 保存模型到 `models/` 目录 + +5. **环境验证** + - 运行环境检查脚本 + - 验证所有组件正常 + +6. **启动应用** + - 自动启动Web界面 + - 在浏览器中打开应用 + +### 首次使用 + +首次运行脚本时，您需要： + +1. **下载数据文件** + - 访问: https://www.kaggle.com/datasets/mlg-ulb/creditcardfraud + - 下载 `creditcard.csv` + - 放入项目的 `data/` 目录 + +2. **运行安装脚本** + - Windows: 双击 `install.bat` + - Linux/Mac: 执行 `./install.sh` + +3. **等待安装完成** + - 依赖安装：2-5分钟 + - 模型训练：5-10分钟（取决于硬件） + +4. **开始使用** + - Web界面会自动在浏览器中打开 + - 访问地址: http://localhost:8501 + +### 常见问题 + +**Q: 脚本运行失败怎么办？** + +A: 可以尝试以下步骤： +1. 确保Python版本 >= 3.10 +2. 检查网络连接 +3. 手动运行: `pip install -r requirements.txt` +4. 查看 [QUICKSTART.md](QUICKSTART.md) 的常见问题部分 + +**Q: 如何使用国内镜像源加速安装？** + +A: 修改安装命令： +```bash +pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple +``` + +**Q: 模型训练时间太长怎么办？** + +A: 模型训练需要一定时间，这是正常的。您可以： +- 等待训练完成（推荐） +- 使用预训练模型（如果提供） +- 减少训练数据量（修改代码） + +**Q: 如何停止Web服务？** + +A: 在运行脚本的终端窗口中按 `Ctrl+C` + +--- + ## 运行测试 ```bash diff --git a/auto_install.py b/auto_install.py new file mode 100644 index 0000000..7502795 --- /dev/null +++ b/auto_install.py @@ -0,0 +1,241 @@ +""" +信用卡欺诈检测系统 - 自动化安装脚本 +跨平台支持：Windows、Linux、macOS +""" + +import sys +import subprocess +import os +from pathlib import Path +import time + + +def print_header(text): + """打印标题""" + print("=" * 60) + print(text) + print("=" * 60) + print() + + +def print_step(step_num, total_steps, description): + """打印步骤信息""" + print(f"[步骤 {step_num}/{total_steps}] {description}") + + +def run_command(command, description=""): + """运行命令并处理错误""" + try: + if description: + print(f" 正在执行: {description}") + + result = subprocess.run( + command, + shell=True, + check=True, + capture_output=True, + text=True + ) + + if result.stdout: + print(result.stdout) + + return True + except subprocess.CalledProcessError as e: + print(f" [错误] 命令执行失败") + if e.stderr: + print(f" 错误信息: {e.stderr}") + return False + + +def check_python_version(): + """检查Python版本""" + print_step(1, 5, "检查Python版本...") + + version = sys.version_info + print(f" Python版本: {version.major}.{version.minor}.{version.micro}") + + if version.major == 3 and version.minor >= 10: + print(" ✓ Python版本符合要求 (>= 3.10)") + return True + else: + print(" ✗ Python版本不符合要求，需要3.10或更高版本") + print(" 请从 https://www.python.org/downloads/ 下载最新版本") + return False + + +def install_dependencies(): + """安装Python依赖""" + print_step(2, 5, "安装Python依赖...") + print(" 正在安装依赖包，这可能需要几分钟...") + + # 尝试使用pip安装 + success = run_command( + f"{sys.executable} -m pip install -r requirements.txt", + "安装依赖包" + ) + + if success: + print(" ✓ 依赖安装完成") + return True + else: + print(" ✗ 依赖安装失败") + print(" 请检查网络连接或尝试使用国内镜像源:") + print(f" {sys.executable} -m pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple") + return False + + +def check_data_file(): + """检查数据文件""" + print_step(3, 5, "检查数据文件...") + + data_file = Path("data/creditcard.csv") + + if data_file.exists(): + file_size = data_file.stat().st_size / (1024 * 1024) # MB + print(f" ✓ 数据文件已存在 (大小: {file_size:.2f} MB)") + return True + else: + print(" ✗ 未找到数据文件 data/creditcard.csv") + print() + print(" 请从以下地址下载数据集:") + print(" https://www.kaggle.com/datasets/mlg-ulb/creditcardfraud") + print() + print(" 下载后将 creditcard.csv 文件放入 data/ 目录") + print() + + response = input(" 数据文件已准备好吗？(Y/N): ").strip().upper() + if response == 'Y': + print(" ✓ 继续安装...") + return True + else: + print(" ✗ 安装已取消") + return False + + +def check_model_files(): + """检查并训练模型""" + print_step(4, 5, "检查模型文件...") + + models_dir = Path("models") + model_file = models_dir / "random_forest_model.joblib" + + if model_file.exists(): + file_size = model_file.stat().st_size / 1024 # KB + print(f" ✓ 模型文件已存在 (大小: {file_size:.2f} KB)") + return True + else: + print(" 模型文件不存在，开始训练模型...") + print(" 这可能需要几分钟，请耐心等待...") + + success = run_command( + f"{sys.executable} src/train.py", + "训练模型" + ) + + if success: + print(" ✓ 模型训练完成") + return True + else: + print(" ✗ 模型训练失败") + return False + + +def run_environment_check(): + """运行环境检查""" + print_step(5, 5, "运行环境检查...") + + success = run_command( + f"{sys.executable} check_environment.py", + "检查环境" + ) + + if success: + print(" ✓ 环境检查通过") + else: + print(" ⚠ 环境检查发现问题，但将继续启动应用") + + return True + + +def launch_application(): + """启动应用""" + print() + print_header("安装完成！正在启动Web界面...") + print() + print("提示:") + print("- Web界面将在浏览器中自动打开") + print("- 如果没有自动打开，请访问: http://localhost:8501") + print("- 按 Ctrl+C 可以停止服务") + print() + + # 等待几秒让用户看到提示 + time.sleep(2) + + # 启动应用 + try: + subprocess.run( + f"{sys.executable} src/agent_app.py", + shell=True, + check=True + ) + except KeyboardInterrupt: + print() + print("应用已停止") + except Exception as e: + print(f"启动应用时出错: {e}") + + +def main(): + """主函数""" + print_header("信用卡欺诈检测系统 - 自动化安装脚本") + + # 检查Python版本 + if not check_python_version(): + input("按回车键退出...") + sys.exit(1) + + print() + + # 安装依赖 + if not install_dependencies(): + input("按回车键退出...") + sys.exit(1) + + print() + + # 检查数据文件 + if not check_data_file(): + input("按回车键退出...") + sys.exit(1) + + print() + + # 检查模型文件 + if not check_model_files(): + input("按回车键退出...") + sys.exit(1) + + print() + + # 运行环境检查 + run_environment_check() + + # 启动应用 + launch_application() + + +if __name__ == "__main__": + try: + main() + except KeyboardInterrupt: + print() + print("安装已取消") + sys.exit(1) + except Exception as e: + print() + print(f"安装过程中出现错误: {e}") + import traceback + traceback.print_exc() + input("按回车键退出...") + sys.exit(1) diff --git a/install.bat b/install.bat new file mode 100644 index 0000000..b334040 --- /dev/null +++ b/install.bat @@ -0,0 +1,112 @@ +@echo off +chcp 65001 >nul +setlocal enabledelayedexpansion + +echo ============================================================ +echo 信用卡欺诈检测系统 - 一键安装脚本 +echo ============================================================ +echo. + +REM 检查Python是否安装 +python --version >nul 2>&1 +if %errorlevel% neq 0 ( + echo [错误] 未检测到Python，请先安装Python 3.10或更高版本 + echo 下载地址: https://www.python.org/downloads/ + pause + exit /b 1 +) + +echo [步骤 1/5] 检查Python版本... +for /f "tokens=2" %%i in ('python --version 2^>^&1') do set PYTHON_VERSION=%%i +echo Python版本: %PYTHON_VERSION% +echo. + +REM 检查Python版本是否满足要求 +for /f "tokens=1,2 delims=." %%a in ("%PYTHON_VERSION%") do ( + set MAJOR=%%a + set MINOR=%%b +) + +if %MAJOR% lss 3 ( + echo [错误] Python版本过低，需要3.10或更高版本 + pause + exit /b 1 +) + +if %MAJOR% equ 3 ( + if %MINOR% lss 10 ( + echo [错误] Python版本过低，需要3.10或更高版本 + pause + exit /b 1 + ) +) + +echo [步骤 2/5] 安装Python依赖... +echo 正在安装依赖包，这可能需要几分钟... +pip install -r requirements.txt +if %errorlevel% neq 0 ( + echo [错误] 依赖安装失败 + echo 请检查网络连接或尝试使用国内镜像源: + echo pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple + pause + exit /b 1 +) +echo 依赖安装完成 +echo. + +echo [步骤 3/5] 检查数据文件... +if not exist "data\creditcard.csv" ( + echo [警告] 未找到数据文件 data\creditcard.csv + echo. + echo 请从以下地址下载数据集: + echo https://www.kaggle.com/datasets/mlg-ulb/creditcardfraud + echo. + echo 下载后将 creditcard.csv 文件放入 data\ 目录 + echo. + set /p DATA_READY="数据文件已准备好吗？(Y/N): " + if /i not "!DATA_READY!"=="Y" ( + echo 安装已取消 + pause + exit /b 1 + ) +) else ( + echo 数据文件已存在 +) +echo. + +echo [步骤 4/5] 检查模型文件... +if not exist "models\random_forest_model.joblib" ( + echo 模型文件不存在，开始训练模型... + echo 这可能需要几分钟，请耐心等待... + python src\train.py + if %errorlevel% neq 0 ( + echo [错误] 模型训练失败 + pause + exit /b 1 + ) + echo 模型训练完成 +) else ( + echo 模型文件已存在 +) +echo. + +echo [步骤 5/5] 运行环境检查... +python check_environment.py +if %errorlevel% neq 0 ( + echo [警告] 环境检查发现问题，但将继续启动应用 +) +echo. + +echo ============================================================ +echo 安装完成！正在启动Web界面... +echo ============================================================ +echo. +echo 提示: +echo - Web界面将在浏览器中自动打开 +echo - 如果没有自动打开，请访问: http://localhost:8501 +echo - 按 Ctrl+C 可以停止服务 +echo. + +python src\agent_app.py + +pause diff --git a/install.sh b/install.sh new file mode 100644 index 0000000..e990438 --- /dev/null +++ b/install.sh @@ -0,0 +1,96 @@ +#!/bin/bash + +set -e + +echo "============================================================" +echo "信用卡欺诈检测系统 - 一键安装脚本" +echo "============================================================" +echo "" + +# 检查Python是否安装 +if ! command -v python3 &> /dev/null; then + echo "[错误] 未检测到Python，请先安装Python 3.10或更高版本" + echo "Ubuntu/Debian: sudo apt-get install python3 python3-pip" + echo "CentOS/RHEL: sudo yum install python3 python3-pip" + echo "macOS: brew install python3" + exit 1 +fi + +echo "[步骤 1/5] 检查Python版本..." +PYTHON_VERSION=$(python3 --version 2>&1 | awk '{print $2}') +echo "Python版本: $PYTHON_VERSION" +echo "" + +# 检查Python版本是否满足要求 +PYTHON_MAJOR=$(echo $PYTHON_VERSION | cut -d. -f1) +PYTHON_MINOR=$(echo $PYTHON_VERSION | cut -d. -f2) + +if [ "$PYTHON_MAJOR" -lt 3 ] || ([ "$PYTHON_MAJOR" -eq 3 ] && [ "$PYTHON_MINOR" -lt 10 ]); then + echo "[错误] Python版本过低，需要3.10或更高版本" + exit 1 +fi + +echo "[步骤 2/5] 安装Python依赖..." +echo "正在安装依赖包，这可能需要几分钟..." +pip3 install -r requirements.txt +if [ $? -ne 0 ]; then + echo "[错误] 依赖安装失败" + echo "请检查网络连接或尝试使用国内镜像源:" + echo "pip3 install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple" + exit 1 +fi +echo "依赖安装完成" +echo "" + +echo "[步骤 3/5] 检查数据文件..." +if [ ! -f "data/creditcard.csv" ]; then + echo "[警告] 未找到数据文件 data/creditcard.csv" + echo "" + echo "请从以下地址下载数据集:" + echo "https://www.kaggle.com/datasets/mlg-ulb/creditcardfraud" + echo "" + echo "下载后将 creditcard.csv 文件放入 data/ 目录" + echo "" + read -p "数据文件已准备好吗？(Y/N): " DATA_READY + if [[ ! "$DATA_READY" =~ ^[Yy]$ ]]; then + echo "安装已取消" + exit 1 + fi +else + echo "数据文件已存在" +fi +echo "" + +echo "[步骤 4/5] 检查模型文件..." +if [ ! -f "models/random_forest_model.joblib" ]; then + echo "模型文件不存在，开始训练模型..." + echo "这可能需要几分钟，请耐心等待..." + python3 src/train.py + if [ $? -ne 0 ]; then + echo "[错误] 模型训练失败" + exit 1 + fi + echo "模型训练完成" +else + echo "模型文件已存在" +fi +echo "" + +echo "[步骤 5/5] 运行环境检查..." +python3 check_environment.py +if [ $? -ne 0 ]; then + echo "[警告] 环境检查发现问题，但将继续启动应用" +fi +echo "" + +echo "============================================================" +echo "安装完成！正在启动Web界面..." +echo "============================================================" +echo "" +echo "提示:" +echo "- Web界面将在浏览器中自动打开" +echo "- 如果没有自动打开，请访问: http://localhost:8501" +echo "- 按 Ctrl+C 可以停止服务" +echo "" + +python3 src/agent_app.py