# ServiceAI

**Repository Path**: aiPros_otter/ServiceAI

## Basic Information

- **Project Name**: ServiceAI
- **Description**: 智能客服系统
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-02-25
- **Last Updated**: 2026-02-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 智能客服问答平台

基于FastAPI + Vue 3的智能客服系统，支持知识库管理、智能问答、情感分析等功能。前后端完全分离，提供完整的Web界面和RESTful API。

## 功能特性

### 🎯 核心功能
- **智能问答**: 基于AI模型的智能对话系统
- **知识库管理**: 支持多种格式文档的知识库构建
- **文档处理**: 自动解析PDF、DOCX、TXT等格式文档
- **情感分析**: 自动分析用户情感倾向
- **意图识别**: 识别用户问题意图
- **对话管理**: 完整的对话历史管理

### 📚 知识库功能
- 创建和管理多个知识库
- 支持文档上传和批量导入
- 智能文档分块和索引
- 基于相似度的文档检索
- 支持关键词提取和标签管理

### 🔐 用户系统
- 用户注册和登录
- JWT令牌认证
- 用户权限管理
- 个人对话历史

## 技术栈

### 后端
- **后端框架**: FastAPI
- **数据库**: SQLAlchemy + SQLite/PostgreSQL
- **AI集成**: OpenAI API
- **文档处理**: PyPDF2, python-docx
- **文本处理**: jieba（中文分词）
- **认证**: JWT + OAuth2

### 前端（待开发）
- 本项目采用前后端分离架构
- 前端项目建议使用 Vue.js / React / Angular 等框架
- 前端项目需要单独创建和管理
- 后端提供完整的 RESTful API 接口

## 快速开始

### 后端启动

#### 1. 安装依赖

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

#### 2. 配置环境变量

复制 `.env.example` 到 `.env` 并修改配置：

```bash
cp .env.example .env
```

主要配置项：
- `AI_API_KEY`: OpenAI API密钥
- `SECRET_KEY`: JWT密钥
- `DATABASE_URL`: 数据库连接字符串

#### 3. 启动服务

```bash
python -m app.main
```

或使用uvicorn：

```bash
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

### 前端启动

#### 1. 进入前端目录

```bash
cd frontend
```

#### 2. 安装依赖

```bash
npm install
```

#### 3. 启动开发服务器

```bash
npm run dev
```

前端将运行在 `http://localhost:3000`

访问 http://localhost:3000 即可使用完整的智能客服系统！

### 4. 访问API文档

启动后端服务后，访问以下链接查看完整的API文档：

- **Swagger UI（交互式文档）**: http://localhost:8000/docs
- **ReDoc（可读性文档）**: http://localhost:8000/redoc

> 💡 **提示**: 在Swagger UI中可以直接测试所有API接口，无需手动编写curl命令。

## API使用示例

### 用户注册
```bash
curl -X POST "http://localhost:8000/api/v1/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "testuser",
    "email": "test@example.com",
    "password": "password123",
    "full_name": "Test User"
  }'
```

### 用户登录
```bash
curl -X POST "http://localhost:8000/api/v1/auth/login" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=testuser&password=password123"
```

### 创建知识库
```bash
curl -X POST "http://localhost:8000/api/v1/knowledge/knowledge-bases" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "产品知识库",
    "description": "产品相关信息"
  }'
```

### 上传文档
```bash
curl -X POST "http://localhost:8000/api/v1/knowledge/knowledge-bases/1/documents/upload" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@document.pdf"
```

### 智能问答
```bash
curl -X POST "http://localhost:8000/api/v1/chat/chat" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "如何使用这个产品？",
    "knowledge_base_ids": [1]
  }'
```

## 项目架构

本项目采用**前后端分离**架构：

```
┌─────────────────────────────────────────────────────────────┐
│                         前端项目                             │
│  (Vue.js / React / Angular - 独立部署)                      │
│                                                             │
│  - 用户界面展示                                              │
│  - 用户交互逻辑                                              │
│  - API 调用                                                 │
└────────────────────┬────────────────────────────────────────┘
                     │ HTTP/REST API
                     │ JWT Token
                     ▼
┌─────────────────────────────────────────────────────────────┐
│                      后端服务 (FastAPI)                      │
│                                                             │
│  - RESTful API 接口                                         │
│  - 业务逻辑处理                                              │
│  - 数据持久化                                               │
│  - AI 模型集成                                              │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│                      数据库/存储层                           │
│  - SQLite/PostgreSQL (业务数据)                             │
│  - 文档存储                                                 │
└─────────────────────────────────────────────────────────────┘
```

### 前后端通信

- **通信协议**: RESTful API
- **认证方式**: JWT Token (Bearer Token)
- **数据格式**: JSON
- **CORS支持**: 已配置跨域支持，前端可独立部署

### 前端开发建议

1. **创建独立的前端项目**
   ```bash
   # Vue.js 示例
   npm create vue@latest frontend
   cd frontend
   npm install axios vue-router pinia
   ```

2. **API基础配置**
   ```javascript
   // axios配置示例
   import axios from 'axios'
   
   const api = axios.create({
     baseURL: 'http://localhost:8000/api/v1',
     headers: {
       'Content-Type': 'application/json'
     }
   })
   
   // 请求拦截器 - 添加token
   api.interceptors.request.use(config => {
     const token = localStorage.getItem('token')
     if (token) {
       config.headers.Authorization = `Bearer ${token}`
     }
     return config
   })
   ```

3. **调用示例**
   ```javascript
   // 登录
   const login = async (username, password) => {
     const response = await api.post('/auth/login', 
       `username=${username}&password=${password}`,
       { headers: { 'Content-Type': 'application/x-www-form-urlencoded' }}
     )
     localStorage.setItem('token', response.data.access_token)
     return response.data
   }
   
   // 智能问答
   const chat = async (message, knowledgeBaseIds = []) => {
     const response = await api.post('/chat/chat', {
       message,
       knowledge_base_ids: knowledgeBaseIds
     })
     return response.data
   }
   ```

## 项目结构

### 后端项目结构

```
app/
├── api/v1/                 # API路由
│   ├── endpoints/          # 端点实现
│   │   ├── auth.py        # 认证相关
│   │   ├── chat.py        # 聊天相关
│   │   └── knowledge.py   # 知识库相关
│   ├── api.py             # API路由聚合
│   └── deps.py            # 依赖注入
├── core/                  # 核心配置
│   ├── config.py          # 配置管理
│   └── database.py        # 数据库配置
├── models/                # 数据模型
│   ├── user.py           # 用户模型
│   ├── conversation.py   # 对话模型
│   ├── message.py        # 消息模型
│   ├── knowledge.py      # 知识库模型
│   └── feedback.py       # 反馈模型
├── schemas/               # Pydantic模型
│   ├── user.py           # 用户Schema
│   ├── conversation.py   # 对话Schema
│   ├── message.py        # 消息Schema
│   ├── knowledge.py      # 知识库Schema
│   └── feedback.py       # 反馈Schema
├── services/              # 业务逻辑
│   ├── chat_service.py   # 聊天服务
│   └── knowledge_service.py # 知识库服务
├── utils/                 # 工具函数
│   ├── text_processing.py # 文本处理
│   ├── document_processor.py # 文档处理
│   └── ai_client.py      # AI客户端
└── main.py               # 应用入口
```

### 前端项目结构

```
frontend/
├── src/
│   ├── api/               # API调用封装
│   │   ├── index.js      # Axios配置
│   │   ├── auth.js       # 认证API
│   │   ├── chat.js       # 聊天API
│   │   └── knowledge.js  # 知识库API
│   ├── assets/           # 静态资源
│   ├── components/       # 公共组件
│   ├── layouts/          # 布局组件
│   │   └── MainLayout.vue # 主布局
│   ├── views/            # 页面视图
│   │   ├── Login.vue     # 登录页
│   │   ├── Register.vue  # 注册页
│   │   ├── Chat.vue      # 聊天页
│   │   ├── Conversations.vue # 对话历史
│   │   ├── Knowledge.vue # 知识库管理
│   │   └── Profile.vue   # 个人设置
│   ├── router/           # 路由配置
│   │   └── index.js
│   ├── stores/           # Pinia状态管理
│   │   └── auth.js
│   ├── App.vue           # 根组件
│   └── main.js           # 入口文件
├── index.html
├── package.json
├── vite.config.js
├── .eslintrc.cjs
└── README.md
```

## 配置说明

### AI配置
- `AI_MODEL_NAME`: 使用的AI模型名称
- `AI_API_KEY`: OpenAI API密钥
- `AI_MAX_TOKENS`: 最大生成token数
- `AI_TEMPERATURE`: 生成随机性

### 知识库配置
- `MAX_DOCUMENT_SIZE_MB`: 最大文档大小
- `CHUNK_SIZE`: 文档分块大小
- `CHUNK_OVERLAP`: 分块重叠大小

### 智能客服配置
- `MAX_CONVERSATION_HISTORY`: 最大对话历史数
- `ENABLE_SENTIMENT_ANALYSIS`: 是否启用情感分析
- `AUTO_CLOSE_CONVERSATION_HOURS`: 自动关闭对话时间

## 部署

### 后端部署

#### Docker部署

```dockerfile
FROM python:3.9-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .

CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
```

#### 使用Docker Compose

```yaml
version: '3.8'

services:
  backend:
    build: .
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=postgresql://user:pass@db:5432/chatbot
      - AI_API_KEY=${AI_API_KEY}
      - SECRET_KEY=${SECRET_KEY}
    depends_on:
      - db
  
  db:
    image: postgres:14
    environment:
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=pass
      - POSTGRES_DB=chatbot
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:
```

### 前端部署

前端项目需要单独构建和部署：

```bash
# Vue.js 项目示例
cd frontend
npm install
npm run build

# 构建后的静态文件在 dist/ 目录
# 可以使用 Nginx、Apache 或 Vercel、Netlify 等平台部署
```

#### Nginx配置示例

```nginx
server {
    listen 80;
    server_name your-domain.com;
    
    # 前端静态文件
    location / {
        root /var/www/frontend/dist;
        try_files $uri $uri/ /index.html;
    }
    
    # 后端API代理
    location /api {
        proxy_pass http://localhost:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}
```

### 生产环境配置

#### 后端配置
1. 使用PostgreSQL替代SQLite
2. 配置Redis缓存
3. 设置合适的SECRET_KEY
4. 配置反向代理（Nginx）
5. 启用HTTPS
6. 配置环境变量文件（.env）

#### 前端配置
1. 配置API基础URL指向后端服务
2. 启用生产环境优化（代码压缩、tree-shaking等）
3. 配置CDN加速静态资源
4. 启用Gzip压缩

## 扩展功能

### 向量数据库集成
项目支持集成ChromaDB、Pinecone等向量数据库：

```python
# 在config.py中配置
VECTOR_DB_TYPE="chroma"
VECTOR_DB_URL="http://localhost:8000"
```

### 多语言支持
可以通过修改AI模型的system prompt来支持多语言：

```python
system_prompt = """你是一个多语言智能客服助手..."""
```

### 自定义AI模型
支持集成其他AI服务提供商：

```python
# 修改ai_client.py中的API调用
async def _call_custom_api(self, messages):
    # 自定义API调用逻辑
    pass
```

## 快速参考

### API端点概览

#### 认证相关
- `POST /api/v1/auth/register` - 用户注册
- `POST /api/v1/auth/login` - 用户登录

#### 聊天相关
- `POST /api/v1/chat/chat` - 发送消息
- `GET /api/v1/chat/conversations` - 获取对话列表
- `GET /api/v1/chat/conversations/{id}` - 获取对话详情

#### 知识库相关
- `POST /api/v1/knowledge/knowledge-bases` - 创建知识库
- `GET /api/v1/knowledge/knowledge-bases` - 获取知识库列表
- `POST /api/v1/knowledge/knowledge-bases/{id}/documents/upload` - 上传文档
- `GET /api/v1/knowledge/knowledge-bases/{id}/documents` - 获取文档列表

> 📖 查看完整的API文档：http://localhost:8000/docs

### 常用配置项

```bash
# .env 文件配置示例
AI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
SECRET_KEY=your-secret-key-here
DATABASE_URL=sqlite:///./chatbot.db
AI_MODEL_NAME=gpt-3.5-turbo
ALLOWED_HOSTS=["*"]
```

## 技术支持

遇到问题？请查看：
- 📘 [使用指南](USAGE.md)
- 📚 [API文档](http://localhost:8000/docs)
- 🐛 [提交Issue](https://github.com/your-repo/issues)

## 贡献

欢迎提交Issue和Pull Request来改进这个项目。

## 许可证

MIT License