459 lines
10 KiB
Markdown
459 lines
10 KiB
Markdown
# 智能客服系统技术架构文档
|
||
|
||
## 1. 架构设计
|
||
|
||
```mermaid
|
||
graph TD
|
||
A[前端应用] --> B[Eino Framework后端服务:8302]
|
||
B --> C[Ollama模型服务:11434]
|
||
B --> D[ChromaDB向量数据库]
|
||
B --> E[订单API服务]
|
||
B --> F[Coze-Loop监控平台]
|
||
B --> G[SQLite数据库]
|
||
B --> H[Redis缓存:6379]
|
||
|
||
subgraph "后端API服务层 (端口8302)"
|
||
B
|
||
end
|
||
|
||
subgraph "AI模型层 (localhost:11434)"
|
||
C
|
||
I[Qwen3:8b 意图识别]
|
||
J[Deepseek-v3.1 对话生成]
|
||
C --> I
|
||
C --> J
|
||
end
|
||
|
||
subgraph "数据存储层"
|
||
D
|
||
G
|
||
H
|
||
K[(会话数据 - ./data/)]
|
||
L[(知识库文档 - ChromaDB)]
|
||
end
|
||
|
||
subgraph "外部服务层"
|
||
E
|
||
F
|
||
end
|
||
```
|
||
|
||
## 2.Technology Description
|
||
|
||
* Backend: Eino Framework + Kratos (Web框架)
|
||
- Eino Framework: https://github.com/cloudwego/eino (LLM应用开发框架)
|
||
- 集成文档: https://www.cloudwego.io/zh/docs/eino/
|
||
- Kratos: Go微服务框架，提供HTTP/gRPC服务能力
|
||
|
||
* AI Models: Ollama (qwen3:8b for intent, deepseek-v3.1 for chat - both cloud models)
|
||
|
||
* Database: SQLite + Redis (Docker) + ChromaDB
|
||
|
||
* Monitoring: Coze-Loop (simplified)
|
||
- Coze-Loop: https://github.com/coze-dev/coze-loop (AI应用监控平台)
|
||
|
||
* Deployment: Docker containers
|
||
|
||
* API Port: 8302
|
||
|
||
## 3. API路由定义
|
||
|
||
| API路由 | 方法 | 功能说明 | 端口 |
|
||
| ---------------------------- | ------ | ---------------- | ---- |
|
||
| /api/chat | POST | 聊天消息处理，支持SSE流式响应 | 8302 |
|
||
| /api/sessions | GET | 获取会话列表 | 8302 |
|
||
| /api/sessions | POST | 创建新会话 | 8302 |
|
||
| /api/knowledge/upload | POST | 知识库文档上传 | 8302 |
|
||
| /api/knowledge/list | GET | 获取知识库文档列表 | 8302 |
|
||
| /api/knowledge/{id} | DELETE | 删除知识库文档 | 8302 |
|
||
| /api/analytics/conversations | GET | 获取对话统计数据 | 8302 |
|
||
| /api/analytics/costs | GET | 获取AI成本统计 | 8302 |
|
||
| /api/system/status | GET | 系统健康检查 | 8302 |
|
||
|
||
## 4. API定义
|
||
|
||
### 4.1 核心API (最小MVP实现)
|
||
|
||
聊天对话接口 (端口: 8302)
|
||
|
||
```
|
||
POST /api/chat
|
||
```
|
||
|
||
Request:
|
||
|
||
| 参数名 | 参数类型 | 是否必需 | 描述 |
|
||
| ----------- | ------ | ----- | ------ |
|
||
| message | string | true | 用户输入消息 |
|
||
| session\_id | string | false | 会话ID |
|
||
|
||
Response (SSE Stream):
|
||
|
||
```json
|
||
{
|
||
"session_id": "default",
|
||
"timestamp": "2025-01-15T16:19:07.139531",
|
||
"type": "data|process|result|error",
|
||
"payload": {
|
||
"data_type": "general_chat_stream",
|
||
"content": {
|
||
"chunk": "我是",
|
||
"full_message": "您好！我是您的智能客服助手",
|
||
"is_final": false
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
订单查询接口 (Mock数据)
|
||
|
||
```
|
||
POST /api/order/query
|
||
```
|
||
|
||
Request:
|
||
|
||
| 参数名 | 参数类型 | 是否必需 | 描述 |
|
||
| --------- | ------ | ---- | --- |
|
||
| order\_id | string | true | 订单号 |
|
||
|
||
Mock Response:
|
||
|
||
```json
|
||
{
|
||
"order_id": "ORD123456",
|
||
"status": "已发货",
|
||
"need_ai": true,
|
||
"details": {
|
||
"product": "智能手机",
|
||
"amount": 2999.00,
|
||
"create_time": "2025-01-10"
|
||
}
|
||
}
|
||
```
|
||
|
||
知识库上传接口
|
||
|
||
```
|
||
POST /api/knowledge/upload
|
||
```
|
||
|
||
Request:
|
||
|
||
| 参数名 | 参数类型 | 是否必需 | 描述 |
|
||
| ---- | ---- | ---- | ---------- |
|
||
| file | file | true | Word/TXT文档 |
|
||
|
||
Response:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"file_id": "kb_001"
|
||
}
|
||
```
|
||
|
||
## 5. 服务架构图
|
||
|
||
```mermaid
|
||
graph TD
|
||
A[客户端请求] --> B[API网关层]
|
||
B --> C[业务逻辑层]
|
||
C --> D[AI服务层]
|
||
C --> E[数据访问层]
|
||
|
||
subgraph "Eino Framework + Kratos服务"
|
||
B
|
||
C
|
||
F[意图识别服务]
|
||
G[对话管理服务]
|
||
H[知识库服务]
|
||
I[订单服务]
|
||
C --> F
|
||
C --> G
|
||
C --> H
|
||
C --> I
|
||
end
|
||
|
||
subgraph "AI模型服务"
|
||
D
|
||
J[Ollama服务]
|
||
K[模型管理]
|
||
D --> J
|
||
D --> K
|
||
end
|
||
|
||
subgraph "数据层"
|
||
E
|
||
L[(ChromaDB)]
|
||
M[(会话存储)]
|
||
E --> L
|
||
E --> M
|
||
end
|
||
```
|
||
|
||
## 6. 数据模型
|
||
|
||
### 6.1 数据模型定义
|
||
|
||
```mermaid
|
||
erDiagram
|
||
CHAT_SESSION ||--o{ CHAT_MESSAGE : contains
|
||
CHAT_SESSION ||--o{ INTENT_LOG : tracks
|
||
CHAT_SESSION ||--o{ AI_COST_LOG : tracks
|
||
KNOWLEDGE_BASE ||--o{ DOCUMENT_CHUNK : contains
|
||
ORDER_QUERY ||--o{ AI_DIAGNOSIS : may_have
|
||
|
||
CHAT_SESSION {
|
||
string session_id PK
|
||
datetime created_at
|
||
datetime updated_at
|
||
string user_id
|
||
json metadata
|
||
}
|
||
|
||
CHAT_MESSAGE {
|
||
string message_id PK
|
||
string session_id FK
|
||
string role
|
||
text content
|
||
datetime timestamp
|
||
string message_type
|
||
}
|
||
|
||
INTENT_LOG {
|
||
string log_id PK
|
||
string session_id FK
|
||
string user_message
|
||
string predicted_intent
|
||
float confidence_score
|
||
datetime timestamp
|
||
}
|
||
|
||
KNOWLEDGE_BASE {
|
||
string doc_id PK
|
||
string title
|
||
text content
|
||
datetime created_at
|
||
datetime updated_at
|
||
json metadata
|
||
}
|
||
|
||
DOCUMENT_CHUNK {
|
||
string chunk_id PK
|
||
string doc_id FK
|
||
text chunk_content
|
||
vector embedding
|
||
json metadata
|
||
}
|
||
|
||
ORDER_QUERY {
|
||
string query_id PK
|
||
string session_id FK
|
||
string order_id
|
||
json order_data
|
||
boolean need_ai
|
||
datetime timestamp
|
||
}
|
||
|
||
AI_DIAGNOSIS {
|
||
string diagnosis_id PK
|
||
string query_id FK
|
||
text diagnosis_result
|
||
string model_used
|
||
datetime timestamp
|
||
}
|
||
|
||
AI_COST_LOG {
|
||
string cost_id PK
|
||
string session_id FK
|
||
string model_name
|
||
string operation_type
|
||
integer input_tokens
|
||
integer output_tokens
|
||
integer total_tokens
|
||
decimal cost_amount
|
||
datetime timestamp
|
||
}
|
||
```
|
||
|
||
### 6.2 数据定义语言 (最小MVP实现)
|
||
|
||
聊天会话表 (chat\_sessions)
|
||
|
||
```sql
|
||
CREATE TABLE chat_sessions (
|
||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||
session_id VARCHAR(100) UNIQUE NOT NULL,
|
||
title VARCHAR(200),
|
||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
|
||
);
|
||
```
|
||
|
||
消息记录表 (messages)
|
||
|
||
```sql
|
||
CREATE TABLE messages (
|
||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||
session_id VARCHAR(100) NOT NULL,
|
||
role VARCHAR(20) NOT NULL CHECK (role IN ('user', 'assistant')),
|
||
content TEXT NOT NULL,
|
||
intent_type VARCHAR(50),
|
||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
|
||
);
|
||
```
|
||
|
||
AI成本统计表 (ai\_cost\_logs)
|
||
|
||
```sql
|
||
CREATE TABLE ai_cost_logs (
|
||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||
session_id VARCHAR(100) NOT NULL,
|
||
operation_type VARCHAR(50) NOT NULL,
|
||
model_name VARCHAR(100) NOT NULL,
|
||
input_tokens INTEGER DEFAULT 0,
|
||
output_tokens INTEGER DEFAULT 0,
|
||
cost_amount DECIMAL(10,6) DEFAULT 0.000000,
|
||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
|
||
);
|
||
```
|
||
|
||
知识库文档表 (knowledge\_documents)
|
||
|
||
```sql
|
||
CREATE TABLE knowledge_documents (
|
||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||
file_name VARCHAR(255) NOT NULL,
|
||
file_type VARCHAR(20) NOT NULL CHECK (file_type IN ('docx', 'txt')),
|
||
content_preview TEXT,
|
||
upload_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||
status VARCHAR(20) DEFAULT 'completed'
|
||
);
|
||
```
|
||
|
||
\-- Mock初始数据
|
||
|
||
```sql
|
||
INSERT INTO knowledge_documents (file_name, file_type, content_preview) VALUES
|
||
('产品使用手册.docx', 'docx', '本手册详细介绍了产品的使用方法和注意事项...'),
|
||
('常见问题解答.txt', 'txt', 'Q: 如何重置密码？A: 请联系客服重置密码...');
|
||
|
||
INSERT INTO chat_sessions (session_id, title) VALUES
|
||
('default', '默认会话');
|
||
```
|
||
|
||
|
||
## 7. 部署配置
|
||
|
||
### 7.1 服务配置信息
|
||
|
||
**Eino Framework 集成**
|
||
- 官方文档: https://www.cloudwego.io/zh/docs/eino/
|
||
- 集成方式: 按照官方文档进行 Kratos 项目集成
|
||
- 版本要求: 最新稳定版本
|
||
|
||
**AI 模型服务配置**
|
||
- Ollama 服务地址: `http://localhost:11434`
|
||
- 可用模型:
|
||
- `qwen3:8b` - 用于意图识别
|
||
- `deepseek-v3.1` - 用于对话生成
|
||
- 模型调用: 通过 Eino Framework 统一调用
|
||
|
||
**数据存储配置**
|
||
- Redis 配置: `localhost:6379` (无密码)
|
||
- ChromaDB: Docker 容器部署
|
||
- SQLite 数据库: 文件存放在 `./data/` 目录下
|
||
|
||
**监控配置**
|
||
- Coze-Loop: 容器部署方式
|
||
- 监控数据: 简化收集，突出监控能力展示
|
||
- 集成方式: 轻量级集成，适合示例项目
|
||
|
||
**端口配置**
|
||
- 后端 API 服务: 8302 (无冲突)
|
||
- Ollama 服务: 11434
|
||
- Redis 服务: 6379
|
||
- ChromaDB: 8000 (默认)
|
||
|
||
### 7.2 Docker 部署架构
|
||
|
||
```mermaid
|
||
graph TD
|
||
A[智能客服后端:8302] --> B[Ollama容器:11434]
|
||
A --> C[Redis容器:6379]
|
||
A --> D[ChromaDB容器:8000]
|
||
A --> E[Coze-Loop容器]
|
||
A --> F[SQLite文件:./data/]
|
||
|
||
subgraph "Docker Compose 部署"
|
||
B
|
||
C
|
||
D
|
||
E
|
||
end
|
||
|
||
subgraph "本地文件系统"
|
||
F
|
||
G[知识库文档]
|
||
H[会话数据]
|
||
end
|
||
```
|
||
|
||
### 7.3 部署步骤
|
||
|
||
**1. 环境准备**
|
||
```bash
|
||
# 创建数据目录
|
||
mkdir -p ./data
|
||
|
||
# 启动 Docker 服务
|
||
docker-compose up -d redis chromadb coze-loop
|
||
```
|
||
|
||
**2. Eino Framework 集成**
|
||
```bash
|
||
# 安装 Eino 依赖
|
||
go get github.com/cloudwego/eino
|
||
|
||
# 按照官方文档配置 Kratos 集成
|
||
```
|
||
|
||
**3. 服务启动**
|
||
```bash
|
||
# 启动后端服务
|
||
go run cmd/server/main.go -conf configs/
|
||
|
||
# 服务健康检查
|
||
curl http://localhost:8302/api/system/status
|
||
```
|
||
|
||
### 7.4 配置文件示例
|
||
|
||
**config.yaml**
|
||
```yaml
|
||
server:
|
||
http:
|
||
addr: 0.0.0.0:8302
|
||
timeout: 1s
|
||
grpc:
|
||
addr: 0.0.0.0:9000
|
||
timeout: 1s
|
||
|
||
data:
|
||
database:
|
||
driver: sqlite3
|
||
source: ./data/customer_service.db
|
||
redis:
|
||
addr: localhost:6379
|
||
password: ""
|
||
db: 0
|
||
ollama:
|
||
endpoint: http://localhost:11434
|
||
chromadb:
|
||
endpoint: http://localhost:8000
|
||
coze_loop:
|
||
endpoint: http://localhost:8080
|
||
api_key: "demo_key"
|
||
```
|
||
|