# customer-churn-predict

**Repository Path**: mt4test/customer-churn-predict

## Basic Information

- **Project Name**: customer-churn-predict
- **Description**: No description available
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-08
- **Last Updated**: 2026-03-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 客户流失预警 Agent 系统

## 项目概述

本项目是一个基于 **AI Agent** 架构的客户流失预警与挽留计划生成系统。系统采用智能 Agent 设计，具备自主决策、任务规划、记忆管理等能力，能够理解自然语言指令并自动执行复杂的流失预警任务。

### 🚀 核心特性

- **🤖 AI Agent 架构**：具备自主决策、规划、记忆等智能能力
- **💬 自然语言交互**：支持对话式操作，无需记忆复杂命令
- **🔧 工具系统**：模块化工具设计，易于扩展和维护
- **📊 数据生成与模拟**：生成真实的证券客户行为数据集
- **🎯 机器学习模型训练**：基于XGBoost训练客户流失预测模型
- **📈 SHAP可解释性分析**：可视化关键流失驱动因素
- **⚠️ 风险客户预测**：批量识别高流失风险客户
- **🎁 个性化挽留计划**：利用大模型生成针对性的客户挽留策略
- **🌐 Web界面交互**：提供直观的前端操作界面
- **🔌 RESTful API**：支持系统集成与二次开发

## 系统架构

```
┌─────────────────────────────────────────────────────────────────┐
│                        前端界面 (index.html)                      │
│                     Web UI + 对话交互界面                         │
└────────────────────────────┬────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Flask API 服务层 (app.py)                    │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │ RESTful API  │  │ Agent Chat   │  │ 兼容旧接口    │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
└────────────────────────────┬────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    AI Agent 核心层 (agent.py)                     │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │ 决策规划     │  │ 记忆管理     │  │ 工具调用     │          │
│  │ Planning     │  │ Memory       │  │ Tool Calling │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
└────────────────────────────┬────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    工具系统层 (tools.py)                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │ 数据生成     │  │ 模型训练     │  │ 风险预测     │          │
│  │ SHAP分析     │  │ 挽留计划     │  │ 报告生成     │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
└────────────────────────────┬────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                  数据处理层 (churn_predict.py)                    │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │ XGBoost模型  │  │ 特征工程     │  │ 数据生成     │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
└─────────────────────────────────────────────────────────────────┘
```

## 技术栈

### 后端

- Python 3.12
- Flask 2.x - Web框架
- XGBoost - 机器学习模型
- SHAP - 模型解释工具
- Pandas, NumPy - 数据处理
- scikit-learn - 机器学习库
- Matplotlib, Seaborn - 数据可视化

### 前端

- HTML5/CSS3
- JavaScript (ES6+)
- Bootstrap 5 - UI框架
- Axios - HTTP客户端

### 大模型集成

- 字节跳动方舟大模型 API - 个性化挽留计划生成

## 安装与运行

### 环境准备

1. 确保已安装Python 3.10或以上版本
2. 安装依赖包：

```bash
pip install -r requirements.txt
```

或者手动安装：

```bash
pip install flask flask-cors pandas numpy matplotlib seaborn scikit-learn xgboost shap openai openpyxl python-dotenv
```

3. （可选）配置环境变量：

创建 `.env` 文件（可选）：

```bash
# LLM API 配置
LLM_API_KEY=your_api_key_here
LLM_BASE_URL=https://ark.cn-beijing.volces.com/api/v3
LLM_MODEL=kimi-k2-thinking-251104

# 数据配置
N_CUSTOMERS=3000
N_WEEKS=12

# Agent 配置
ENABLE_LLM=true
```

### 运行系统

#### 方式一：启动 Web 服务（推荐）

**最简单的方式**

```bash
# 1. 进入项目目录
cd customer_churn_predict

# 2. 启动 Flask 应用
python app.py
```

**访问界面**：

- 主界面：`http://localhost:8000`
- Agent 对话界面：`http://localhost:8000/agent`

**在浏览器中使用**：

1. 打开 http://localhost:8000/agent
2. 在输入框中输入指令，例如：
   - "请帮我训练一个流失预测模型"
   - "预测一下哪些客户有流失风险"
   - "生成一份分析报告"

**使用 cURL 调用 API**：

```bash
# 与 Agent 对话
curl -X POST http://localhost:8000/api/agent/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "请帮我训练一个流失预测模型"}'

# 查询 Agent 状态
curl http://localhost:8000/api/agent/status

# 查看 Agent 记忆
curl http://localhost:8000/api/agent/memory?limit=10
```

**使用 Python 调用 API**：

```python
import requests

# 与 Agent 对话
response = requests.post(
    'http://localhost:8000/api/agent/chat',
    json={'message': '请帮我训练一个流失预测模型'}
)
print(response.json())

# 查询状态
response = requests.get('http://localhost:8000/api/agent/status')
print(response.json())
```

#### 方式二：直接使用 Python 代码

**运行示例脚本**：

```bash
cd customer_churn_predict
python start_agent.py
```

**在代码中使用**：

```python
from agent.core import ChurnPredictionAgent
from tools import get_tools
from config.settings import get_config

# 初始化
config = get_config()
agent = ChurnPredictionAgent(config=config['llm'])
tools = get_tools()

# 注册工具
agent.register_tool('generate_data', tools.generate_data, '生成客户数据')
agent.register_tool('train_model', tools.train_model, '训练流失预测模型')
agent.register_tool('predict_risk', tools.predict_risk, '预测客户流失风险')

# 与 Agent 对话
response = agent.chat("请帮我训练一个流失预测模型")
print(response['response'])

# 查看状态
status = agent.get_status()
print(status)
```

#### 方式三：使用 Docker

1. 构建并启动容器：

```bash
docker-compose up -d
```

2. 查看日志：

```bash
docker-compose logs -f
```

3. 访问服务：

   - 主界面: http://localhost:8000
   - Agent 界面: http://localhost:8000/agent
4. 停止服务：

```bash
docker-compose down
```

## Agent 使用指南

### Agent 对话接口

Agent 支持自然语言交互，您可以直接用中文描述需求，Agent 会自动理解并执行相应任务。

#### 示例对话

```bash
# 训练模型
用户: "请帮我训练一个流失预测模型"
Agent: 我已经为您制定了执行计划，包含 4 个步骤：
  1. 生成客户数据
  2. 进行特征工程
  3. 训练流失预测模型
  4. 进行模型可解释性分析

# 预测风险
用户: "预测一下哪些客户有流失风险"
Agent: 我已经为您制定了执行计划，包含 2 个步骤：
  1. 预测客户流失风险
  2. 生成挽留计划

# 生成报告
用户: "生成一份分析报告"
Agent: 我已经为您制定了执行计划，包含 1 个步骤：
  1. 生成分析报告
```

### Agent API 接口

#### 1. Agent 对话

- **URL**: `/api/agent/chat`
- **方法**: `POST`
- **描述**: 与 Agent 进行对话
- **请求体**:

```json
{
  "message": "请帮我训练一个流失预测模型",
  "context": {}
}
```

- **响应示例**:

```json
{
  "status": "success",
  "response": "我已经为您制定了执行计划...",
  "plan": [...],
  "results": {...}
}
```

#### 2. Agent 状态查询

- **URL**: `/api/agent/status`
- **方法**: `GET`
- **描述**: 获取 Agent 当前状态
- **响应示例**:

```json
{
  "status": "success",
  "agent_status": {
    "capabilities": {...},
    "tools_count": 8,
    "memory_count": 15,
    "has_llm": true
  }
}
```

#### 3. Agent 记忆查询

- **URL**: `/api/agent/memory`
- **方法**: `GET`
- **描述**: 获取 Agent 历史记忆
- **参数**: `limit` (可选，默认10)
- **响应示例**:

```json
{
  "status": "success",
  "memory": "[2025-01-01T10:00:00] train_model: 执行成功...",
  "memory_count": 15
}
```

#### 4. 清空 Agent 记忆

- **URL**: `/api/agent/memory/clear`
- **方法**: `POST`
- **描述**: 清空 Agent 的所有记忆

## API接口说明

### 1. 健康检查

- **URL**: `/api/health`
- **方法**: `GET`
- **描述**: 检查API服务器运行状态
- **响应示例**:

```json
{
  "status": "ok",
  "message": "API服务器运行正常"
}
```

### 2. 模型训练

- **URL**: `/api/train`
- **方法**: `POST`
- **描述**: 生成模拟数据并训练流失预测模型
- **请求体**:

```json
{
  "n_customers": 3000,
  "n_weeks": 12
}
```

- **响应示例**:

```json
{
  "status": "success",
  "message": "模型训练完成",
  "customer_count": 3000,
  "feature_count": 29
}
```

### 3. 风险预测

- **URL**: `/api/predict`
- **方法**: `POST`
- **描述**: 预测客户流失风险并生成挽留计划
- **请求体**:

```json
{
  "top_k": 30
}
```

- **响应示例**:

```json
{
  "status": "success",
  "high_risk_count": 30,
  "plans_count": 30,
  "retention_plans": [...]
}
```

### 4. 客户信息查询

- **URL**: `/api/customer/<customer_id>`
- **方法**: `GET`
- **描述**: 获取单个客户的详细信息
- **响应示例**:

```json
{
  "status": "success",
  "customer_info": {...}
}
```

### 5. 挽留计划下载

- **URL**: `/api/plans/download`
- **方法**: `GET`
- **描述**: 下载挽留计划Excel文件
- **响应示例**:

```json
{
  "status": "success",
  "plans": [...]
}
```

## 使用指南

### 基本使用流程

1. **启动系统**：运行 `python app.py`启动服务器
2. **访问界面**：打开浏览器访问 `http://localhost:8000`
3. **训练模型**：点击"训练模型"按钮，系统将生成模拟数据并训练模型
4. **查看特征重要性**：模型训练完成后，页面将显示SHAP特征重要性分析
5. **预测风险与生成计划**：点击"预测与生成计划"按钮，系统将识别高风险客户并生成挽留策略
6. **查看结果**：在页面上查看预测结果和挽留计划，或下载Excel文件

### 常用指令示例

#### 训练模型

```python
# Python
agent.chat("请帮我训练一个流失预测模型")

# cURL
curl -X POST http://localhost:8000/api/agent/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "请帮我训练一个流失预测模型"}'
```

#### 预测风险

```python
# Python
agent.chat("预测一下哪些客户有流失风险")

# cURL
curl -X POST http://localhost:8000/api/agent/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "预测一下哪些客户有流失风险"}'
```

#### 生成报告

```python
# Python
agent.chat("生成一份分析报告")

# cURL
curl -X POST http://localhost:8000/api/agent/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "生成一份分析报告"}'
```

#### 查看状态

```python
# Python
status = agent.get_status()
print(status)

# cURL
curl http://localhost:8000/api/agent/status
```

#### 查看记忆

```python
# Python
memory = agent.get_memory_summary(limit=10)
print(memory)

# cURL
curl http://localhost:8000/api/agent/memory?limit=10
```

### 故障排查

#### 1. 端口被占用

如果 8000 端口被占用，可以修改 `app.py` 中的端口号：

```python
app.run(host='0.0.0.0', port=8001, debug=True)  # 改为其他端口
```

#### 2. 依赖包缺失

```bash
pip install -r requirements.txt
```

#### 3. 模块导入错误

确保在 `customer_churn_predict` 目录下运行，或者设置 PYTHONPATH：

```bash
export PYTHONPATH=$PYTHONPATH:/path/to/py4zinia
```

## 文件结构

```
py4zinia/
├── customer_churn_predict/
│   ├── agent/                      # Agent 模块
│   │   ├── __init__.py
│   │   ├── core.py                 # Agent 核心逻辑
│   │   ├── report_generator.py     # 报告生成器
│   │   └── prompts.py              # Prompt 模板
│   ├── config/                     # 配置模块
│   │   ├── __init__.py
│   │   ├── settings.py             # 配置项
│   │   └── prompts.yaml            # Prompt 配置
│   ├── static/                      # 静态资源
│   │   └── css/
│   │       └── style.css
│   ├── templates/                   # 模板文件
│   │   ├── index.html
│   │   └── agent.html               # Agent 页面
│   ├── app.py                       # Flask 主应用
│   ├── churn_predict.py             # 预测核心逻辑
│   ├── tools.py                     # 工具系统
│   ├── feature_translation.py       # 特征翻译工具
│   └── requirements.txt             # 依赖列表
├── data/
│   ├── raw/                         # 原始数据
│   ├── processed/                   # 处理后数据
│   └── models/                      # 模型文件
├── reports/                         # 报告目录
├── Dockerfile                       # Docker 配置
├── docker-compose.yml               # Docker Compose
├── requirements.txt                 # 依赖列表（根目录）
├── README.md                        # 项目文档
└── API.md                           # API 文档
```

## 关键功能模块

### 1. AI Agent 核心模块 (`agent.py`)

- **自主决策**：根据用户意图自动选择执行工具
- **任务规划**：将复杂任务分解为多个步骤
- **记忆管理**：记录历史操作和结果，支持记忆查询和清空
- **工具调用**：统一管理所有可用工具
- **自然语言交互**：理解用户意图并生成响应

### 2. 工具系统模块 (`tools.py`)

- **数据生成工具**：生成模拟客户数据
- **特征工程工具**：进行特征提取和转换
- **模型训练工具**：训练流失预测模型
- **风险预测工具**：预测客户流失风险
- **SHAP分析工具**：进行模型可解释性分析
- **挽留计划工具**：生成个性化挽留计划
- **报告生成工具**：生成分析报告

### 3. 数据生成模块

- 生成3000个客户的12周行为数据
- 包含客户类型、风险承受能力、资产状况等29个特征
- 模拟30%的客户流失行为模式

### 4. 模型训练模块

- 使用XGBoost算法训练流失预测模型
- 采用分层抽样确保训练集和测试集的分布一致
- 处理样本不平衡问题，提升模型性能

### 5. SHAP分析模块

- 生成特征重要性柱状图
- 创建SHAP值散点图
- 绘制特征依赖关系图
- 支持中文特征名称展示

### 6. 挽留计划生成模块

- 调用字节跳动方舟大模型API生成个性化挽留策略
- 根据客户风险等级制定不同优先级的计划
- 包含优惠力度、沟通话术和预期效果

## 模型性能

- **AUC-ROC**: 约0.92（测试集）
- **准确率**: 约87%
- **召回率**: 约85%（针对流失客户）
- **F1分数**: 约86%

## 注意事项

1. 系统默认使用模拟数据，实际应用时需替换为真实客户数据
2. 大模型调用需要有效的字节跳动方舟大模型API密钥
3. 模型训练可能需要2-3分钟时间，具体取决于系统性能
4. SHAP分析结果会自动保存为PNG图像文件
5. 挽留计划将自动保存为Excel文件

## Agent 扩展与定制

### 添加新工具

1. 在 `tools.py` 中的 `ChurnPredictionTools` 类中添加新方法：

```python
def your_new_tool(self, param1: str, param2: int) -> Dict[str, Any]:
    """新工具描述"""
    try:
        # 实现工具逻辑
        result = do_something(param1, param2)
        return {
            'status': 'success',
            'message': '工具执行成功',
            'result': result
        }
    except Exception as e:
        return {
            'status': 'error',
            'message': f'工具执行失败: {str(e)}'
        }
```

2. 在 `app.py` 中注册新工具：

```python
agent.register_tool('your_new_tool', tools.your_new_tool, '新工具描述')
```

### 自定义 Agent 行为

1. **修改规划逻辑**：编辑 `agent.py` 中的 `plan()` 方法
2. **自定义响应生成**：编辑 `agent.py` 中的 `_generate_response()` 方法
3. **扩展记忆功能**：在 `AgentMemory` 类中添加新字段

### 其他扩展

1. **数据集成**：修改 `generate_securities_data`函数以支持真实数据源
2. **模型优化**：调整XGBoost参数或尝试其他机器学习算法
3. **界面定制**：修改 `index.html`以适应不同的业务需求
4. **大模型替换**：修改 `generate_retention_strategy`函数以支持其他大模型

## 许可证

本项目采用MIT许可证，可自由使用、修改和分发。

## 联系方式

如有问题或建议，请联系项目维护人员。

---

---

**版本**: v2.0.0 (Agent 版本)
**更新日期**: 2025-01-01
**维护者**: AI助手