# PySmartServ

**Repository Path**: broken-bridge-and-misty-rain/smart-python-service

## Basic Information

- **Project Name**: PySmartServ
- **Description**: 智能客服Python：基于Python的开源智能客服系统，提供自然语言处理、对话管理等功能，适用于多种服务场景，助力开发者快速构建高效客服应用。
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-18
- **Last Updated**: 2026-04-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README



# 花语女装智能客服系统

🌸 **基于 RAG 技术的智能女装客服对话系统**

---

## 项目简介

花语女装智能客服系统是一个基于检索增强生成（RAG）技术的智能问答系统，专为花语女装品牌设计。系统通过构建本地知识库，结合大语言模型能力，为用户提供专业的女装咨询、尺码推荐、退换货政策等服务。

### 核心特性

- **智能问答**：基于知识库的精准回答，覆盖尺码、售后、物流等常见问题
- **多轮对话**：支持上下文理解，可进行连续追问
- **向量检索**：使用 Chroma 向量数据库，实现语义级别的文档检索
- **本地部署**：知识库数据存储在本地，保障数据安全
- **终端交互**：友好的命令行界面，即开即用

---

## 技术栈

| 组件 | 技术 |
|------|------|
| 大语言模型 | 阿里云通义千问（DashScope） |
| 向量数据库 | Chroma |
| 嵌入模型 | text-embedding-v3 |
| 开发框架 | LangChain |
| 环境配置 | python-dotenv |

---

## 系统要求

- Python 3.8 及以上版本
- 有效的阿里云 DashScope API Key
- 网络连接（用于调用 API 服务）

---

## 安装步骤

### 1. 克隆项目

```bash
git clone https://gitee.com/broken-bridge-and-misty-rain/smart-python-service
cd smart-python-service
```

### 2. 安装依赖

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

如遇网络问题，可使用国内镜像源：

```bash
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
```

### 3. 配置环境变量

复制配置文件模板：

**Windows：**
```bash
copy .env.example .env
```

**Linux / Mac：**
```bash
cp .env.example .env
```

编辑 `.env` 文件，填入您的 API Key：

```env
DASHSCOPE_API_KEY=your_api_key_here
DASHSCOPE_MODEL=qwen-plus
DASHSCOPE_EMBEDDING_MODEL=text-embedding-v3
```

### 获取 API Key

1. 访问 [阿里云 DashScope 控制台](https://dashscope.console.aliyun.com/)
2. 登录阿里云账号
3. 进入 API-KEY 管理页面
4. 创建并复制新的 API Key

---

## 快速开始

### 启动系统

```bash
python main.py
```

首次运行会自动完成：
1. 加载知识库文档（5 个知识文件）
2. 构建向量数据库（约 10-30 秒）
3. 启动交互界面

### 系统界面

```
============================================================
🌸 花语女装智能客服系统 🌸
============================================================
你好，我是小花，您的专属女装客服~ 💕
有什么可以帮您的吗？

💡 提示：
  - 输入问题进行咨询
  - 输入 'clear' 清空对话历史
  - 输入 'exit' 或 'quit' 退出系统
  - 输入 'help' 查看更多命令
============================================================
💬 您:
```

---

## 使用示例

### 基础问答

```
💬 您: 你们尺码怎么选？
💬 小花: 感谢您的咨询～我们的尺码选择需要根据您的身高体重来对照尺码表哦。如果您不确定自己适合什么尺码，可以告诉我您的身高体重，我帮您推荐～ 💕

💬 您: 支持退货吗？
💬 小花: 亲爱的顾客您好～我们支持7天无理由退换货哦，衣服未经穿着、洗涤且保持原包装完好即可申请退换～ 📦

💬 您: 几天能收到货？
💬 小花: 发货时间方面，我们48小时内会发出，快递一般3-5个工作日送达哦～着急的顾客可以备注加急处理 ✨
```

### 多轮对话

```
💬 您: 你们尺码怎么选？
💬 小花: [回答尺码选择方式...]

💬 您: 那我165cm选什么码？
💬 小花: [根据165cm给出具体尺码建议...]

💬 您: 如果不合适能换吗？
💬 小花: [回答换货政策和运费说明...]
```

---

## 可用命令

| 命令 | 说明 |
|------|------|
| `clear` | 清空对话历史 |
| `help` | 显示帮助信息 |
| `stats` | 显示对话统计 |
| `exit` / `quit` | 退出系统 |

---

## 项目结构

```
smart-python-service/
├── main.py                    # 主程序入口 ⭐
├── requirements.txt            # 依赖包列表
├── .env                       # 环境配置（需自行创建）⭐
├── .env.example               # 配置模板
│
├── kb_builder.py               # 知识库构建器
│   └── class KnowledgeBaseBuilder
│       ├── load_documents()    # 加载知识文档
│       ├── split_documents()  # 文档分块
│       └── build_vector_store() # 构建向量库
│
├── rag_retriever.py            # RAG 检索器
│   └── class RAGRetriever
│       ├── retrieve()         # 语义检索
│       └── retrieve_with_scores() # 带评分检索
│
├── qa_engine.py               # 问答引擎
│   └── class QAEngine
│       ├── get_chat_history() # 获取对话历史
│       ├── generate_response() # 生成回答
│       └── clear_history()    # 清空历史
│
├── cli_chat.py                # 命令行交互
│   └── class CLIChat
│       ├── show_welcome()    # 显示欢迎界面
│       ├── process_query()   # 处理查询
│       └── handle_command()   # 处理命令
│
└── data/
    ├── knowledge_base/        # 知识库文档
    │   ├── 产品介绍.txt
    │   ├── 尺码表.txt
    │   ├── 退换货政策.txt
    │   ├── 发货规则.txt
    │   └── 常见问题.txt
    │
    └── vector_store/          # 向量数据库（运行时生成）
        └── chroma.sqlite3
```

---

## 知识库说明

系统知识库位于 `data/knowledge_base/` 目录，包含以下文档：

| 文件 | 内容 |
|------|------|
| 产品介绍.txt | 花语女装品牌介绍、产品特点 |
| 尺码表.txt | 各品类尺码对照表、测量方法 |
| 退换货政策.txt | 退换货规则、流程、运费说明 |
| 发货规则.txt | 发货时间、物流方式、加急服务 |
| 常见问题.txt | 日常咨询问题汇总 |

> 可根据业务需求扩展或修改知识库内容。

---

## 常见问题排查

### 问题 1：模块未找到

**错误信息：**
```
ModuleNotFoundError: No module named 'langchain'
```

**解决方案：** 运行 `pip install -r requirements.txt`

---

### 问题 2：API Key 未配置

**错误信息：**
```
请设置 DASHSCOPE_API_KEY 环境变量
```

**解决方案：**
1. 确认 `.env` 文件已创建
2. 检查 `DASHSCOPE_API_KEY=your_api_key_here` 已被替换为真实密钥

---

### 问题 3：网络连接失败

**错误信息：**
```
Connection error / Timeout
```

**解决方案：**
1. 检查网络连接状态
2. 确认防火墙未阻止 API 访问
3. 检查代理设置（如需要）

---

### 问题 4：知识库目录不存在

**错误信息：**
```
知识库目录不存在: data/knowledge_base
```

**解决方案：** 确认 `data/knowledge_base/` 目录下存在 5 个 `.txt` 知识文件

---

## 扩展与定制

测试通过后，您可以进行以下扩展：

| 方向 | 说明 |
|------|------|
| 扩展知识库 | 添加更多产品、FAQ 文档 |
| 优化回答 | 调整 prompt 模板提升回答质量 |
| Web 界面 | 开发浏览器端交互界面 |
| 集成微信 | 接入微信公众号/企业微信 |
| 部署上线 | 部署到云服务器实现线上服务 |

---

## 技术支持

如遇到问题，请依次检查：

1. Python 版本是否 >= 3.8
2. 所有依赖是否正确安装
3. API Key 是否正确配置
4. 网络连接是否正常
5. 知识库文件是否完整

---

祝您使用愉快！🌸