# 快充智能服务系统

**Repository Path**: hemeide2000/charging_robot

## Basic Information

- **Project Name**: 快充智能服务系统
- **Description**: 本项目是一个基于大语言模型（LLM）的充电智能客服机器人，旨在解决充电站客服咨询量激增的问题，主要覆盖"无法启动充电"、"计费疑问"、"故障报修"三大类高频场景问题，后续会扩展更多场景，比如异常订单自助处理、充电桩运维工单流转、情感分析等。
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-29
- **Last Updated**: 2026-02-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 充电智能客服机器人

## 项目介绍

本项目是一个基于大语言模型（LLM）的充电智能客服机器人，旨在解决充电站客服咨询量激增的问题，主要覆盖"无法启动充电"、"计费疑问"、"故障报修"三大类高频问题。

## 技术栈

- **大模型层**：OpenAI API（支持回退到本地模型）
- **框架层**：LangChain
- **向量数据库**：Chroma
- **前端层**：Streamlit
- **开发语言**：Python

## 项目结构

```
charging_robot/
├── backend/               # 后端核心代码
│   ├── __init__.py        # Python包初始化文件
│   ├── knowledge_base_manager.py  # 知识库管理模块
│   └── chat_bot.py        # 聊天机器人模块
├── frontend/              # 前端代码目录
├── knowledge_base/        # 知识库文档目录
├── vector_store/          # 向量数据库存储目录
├── config/                # 配置文件目录
├── .env                   # 环境变量配置文件
├── requirements.txt       # 项目依赖文件
├── streamlit_app.py       # Streamlit应用主文件
├── simple_app.py          # 简化版应用（无后端依赖）
├── simple_http_server.py  # 简单HTTP服务器（用于测试）
└── README.md              # 项目说明文档
```

## 环境配置

### 1. 安装依赖

```bash
# 安装项目依赖
pip install -r requirements.txt
```

### 2. 配置环境变量

编辑 `.env` 文件，配置以下环境变量：

```
# 大模型配置
LLM_API_KEY=XXXXX  # OpenAI或火山引擎API密钥
LLM_BASE_URL=https://ark.cn-beijing.volces.com/api/v3  # 火山引擎API地址，使用OpenAI时改为：https://api.openai.com/v1
LLM_MODEL=deepseek-v3-2-251201  # 支持火山引擎DeepSeek-V3.2、Doubao等模型，如：deepseek-v3-2-251201、doubao-pro、doubao-lite

# Embedding模型配置
EMBEDDING_MODEL=text-embedding-ada-002  # 支持火山引擎Doubao嵌入模型，如：doubao-embedding

# 向量数据库配置
VECTOR_STORE_PATH=./vector_store

# 知识库路径
KNOWLEDGE_BASE_PATH=./knowledge_base
```

## 运行应用

### 方法1：运行完整版应用（包含后端和前端）

```bash
# 运行Streamlit应用
streamlit run integrated_app.py --server.port 8501
```

访问地址：http://localhost:8501

### 方法2：运行简化版应用（仅前端，无后端依赖）

```bash
# 运行简化版Streamlit应用
streamlit run simple_app.py --server.port 8502
```

访问地址：http://localhost:8502

### 方法3：运行简单HTTP服务器（用于测试基本Web服务）

```bash
# 运行简单HTTP服务器
python simple_http_server.py
```

访问地址：http://localhost:8506

## 核心功能

### 1. 知识库管理

- 支持上传PDF/Word文档
- 自动进行文档切片和向量化处理
- 支持查看已上传文档列表
- 支持清空知识库

### 2. 智能问答

- 支持用户提问和机器人回复
- 基于向量数据库检索相关知识库内容
- 大模型生成回答
- 显示引用来源

### 3. 典型场景覆盖

- **故障排查类**：充电枪锁死处理、无法启动充电排查
- **资费政策类**：峰谷电价查询
- **站点查询类**：附近充电站查询

## 常见问题及解决方案

### 1. Streamlit应用无法启动

**问题**：运行 `streamlit run streamlit_app.py` 后，应用无法启动或报错。

**解决方案**：

- 检查是否安装了所有依赖：`pip install -r requirements.txt`
- 检查环境变量配置是否正确，特别是OpenAI API密钥
- 尝试运行简化版应用：`streamlit run simple_app.py`
- 检查端口是否被占用，尝试更换端口：`streamlit run streamlit_app.py --server.port 8503`

### 2. 机器人无法生成回答

**问题**：用户提问后，机器人无法生成回答或报错。

**解决方案**：

- 检查OpenAI API密钥是否有效
- 检查知识库是否已上传相关文档
- 尝试使用更明确的问题描述
- 检查网络连接是否正常

### 3. 文档上传失败

**问题**：上传PDF/Word文档时失败。

**解决方案**：

- 检查文档格式是否正确（仅支持PDF和Word）
- 检查文档大小是否过大（建议单个文档不超过100MB）
- 检查服务器内存是否充足

## 开发说明

### 代码结构说明

- `backend/knowledge_base_manager.py`：负责文档加载、切片和向量化处理
- `backend/chat_bot.py`：负责检索知识库和生成回答
- `streamlit_app.py`：Streamlit应用主文件，包含前端界面和交互逻辑

### 扩展功能

1. **添加新的故障类型**：在知识库中添加相应的故障处理文档
2. **支持更多文档格式**：在 `knowledge_base_manager.py` 中添加新的文档加载器
3. **接入真实地图API**：在 `chat_bot.py` 中修改 `handle_special_cases` 方法
4. **添加用户反馈功能**：在前端界面添加反馈按钮和处理逻辑

## 注意事项

1. 首次运行应用时，知识库为空，需要先上传相关文档
2. 建议先上传充电操作手册、资费政策等核心文档
3. 应用默认使用OpenAI API，需要确保API密钥有效
4. 向量数据库会自动创建在 `vector_store` 目录下
5. 已上传的文档会保存在 `knowledge_base` 目录下

## 许可证

本项目采用MIT许可证。