# 智能客服系统技术架构文档

## 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"
```