# Redis数据灌入规范

## 📋 数据灌入概述

将离线生成的推荐索引加载到Redis，供在线系统实时查询使用。

## 🔑 Redis Key规范

### 通用规则
```
{namespace}:{function}:{algorithm}:{identifier}
```

- `namespace`: 业务命名空间（item, user, interest等）
- `function`: 功能类型（similar, feature, hot等）
- `algorithm`: 算法名称（swing, w2v, deepwalk等）
- `identifier`: 具体标识（item_id, dimension_key等）

## 📊 数据灌入规范表

| 模块名称 | 源数据地址 | 格式描述 | RedisKey模板 | RedisValue格式 | TTL |
|---------|-----------|---------|-------------|---------------|-----|
| **i2i_swing_cpp** | `offline_tasks/collaboration/output/swing_similar.txt` | `item_id\tsimilar_id1:score1,...` | `item:similar:swing_cpp:{item_id}` | `[[similar_id1,score1],[similar_id2,score2],...]` | 7天 |
| **i2i_swing** | `output/i2i_swing_YYYYMMDD.txt` | `item_id\titem_name\tsimilar_id1:score1,...` | `item:similar:swing:{item_id}` | `[[similar_id1,score1],[similar_id2,score2],...]` | 7天 |
| **i2i_session_w2v** | `output/i2i_session_w2v_YYYYMMDD.txt` | `item_id\titem_name\tsimilar_id1:score1,...` | `item:similar:w2v:{item_id}` | `[[similar_id1,score1],[similar_id2,score2],...]` | 7天 |
| **i2i_deepwalk** | `output/i2i_deepwalk_YYYYMMDD.txt` | `item_id\titem_name\tsimilar_id1:score1,...` | `item:similar:deepwalk:{item_id}` | `[[similar_id1,score1],[similar_id2,score2],...]` | 7天 |
| **i2i_content_name** | `output/i2i_content_name_YYYYMMDD.txt` | `item_id\titem_name\tsimilar_id1:score1,...` | `item:similar:content_name:{item_id}` | `[[similar_id1,score1],[similar_id2,score2],...]` | 30天 |
| **i2i_content_pic** | `output/i2i_content_pic_YYYYMMDD.txt` | `item_id\titem_name\tsimilar_id1:score1,...` | `item:similar:content_pic:{item_id}` | `[[similar_id1,score1],[similar_id2,score2],...]` | 30天 |
| **interest_hot** | `output/interest_aggregation_hot_YYYYMMDD.txt` | `dimension_key\titem_id1,item_id2,...` | `interest:hot:{dimension_key}` | `[item_id1,item_id2,item_id3,...]` | 3天 |
| **interest_cart** | `output/interest_aggregation_cart_YYYYMMDD.txt` | `dimension_key\titem_id1,item_id2,...` | `interest:cart:{dimension_key}` | `[item_id1,item_id2,item_id3,...]` | 3天 |
| **interest_new** | `output/interest_aggregation_new_YYYYMMDD.txt` | `dimension_key\titem_id1,item_id2,...` | `interest:new:{dimension_key}` | `[item_id1,item_id2,item_id3,...]` | 3天 |
| **interest_global** | `output/interest_aggregation_global_YYYYMMDD.txt` | `dimension_key\titem_id1,item_id2,...` | `interest:global:{dimension_key}` | `[item_id1,item_id2,item_id3,...]` | 7天 |

## 📝 详细说明

### 1. i2i相似度索引

#### 1.1 C++ Swing算法（高性能版本）

**源数据格式**
```
3600052	2704531:0.00431593,2503886:0.00431593,3371410:0.00431593,3186572:0.00431593
```

**Redis存储**

**Key**: `item:similar:swing_cpp:3600052`

**Value** (JSON格式):
```json
[[2704531, 0.00431593], [2503886, 0.00431593], [3371410, 0.00431593], [3186572, 0.00431593]]
```

**Value** (序列化后):
```python
import json
value = json.dumps([[2704531, 0.00431593], [2503886, 0.00431593], [3371410, 0.00431593], [3186572, 0.00431593]])
# 存储: "[[2704531,0.00431593],[2503886,0.00431593],[3371410,0.00431593],[3186572,0.00431593]]"
```

**特点**:
- 原始Swing分数（未归一化）
- 高性能C++计算
- 适合大规模数据

#### 1.2 Python Swing算法（标准版本）

**源数据格式**
```
12345	香蕉干	67890:0.8567,11223:0.7234,44556:0.6891
```

**Redis存储**

**Key**: `item:similar:swing:12345`

**Value** (JSON格式):
```json
[[67890, 0.8567], [11223, 0.7234], [44556, 0.6891]]
```

**Value** (序列化后):
```python
import json
value = json.dumps([[67890, 0.8567], [11223, 0.7234], [44556, 0.6891]])
# 存储: "[[67890,0.8567],[11223,0.7234],[44556,0.6891]]"
```

**特点**:
- 归一化分数（0-1区间）
- 支持时间衰减和日期维度
- 便于调试

#### 1.3 查询示例

```python
import redis
import json

r = redis.Redis(host='localhost', port=6379, db=0)

# 方式1: 获取C++ Swing结果（生产推荐）
similar_items_cpp = json.loads(r.get('item:similar:swing_cpp:3600052'))
# 返回: [[2704531, 0.00431593], [2503886, 0.00431593], ...]

# 方式2: 获取Python Swing结果（开发测试）
similar_items = json.loads(r.get('item:similar:swing:12345'))
# 返回: [[67890, 0.8567], [11223, 0.7234], [44556, 0.6891]]

# 获取Top5相似商品
top_5 = similar_items[:5]

# 多算法融合（可选）
swing_cpp = json.loads(r.get('item:similar:swing_cpp:3600052') or '[]')
swing_py = json.loads(r.get('item:similar:swing:3600052') or '[]')
w2v = json.loads(r.get('item:similar:w2v:3600052') or '[]')
# 融合多个算法结果...
```

### 2. 兴趣点聚合索引

#### 源数据格式
```
platform:pc	12345,67890,11223,44556,22334
category_level2:200	67890,12345,22334,55667,11223
```

#### Redis存储

**Key**: `interest:hot:platform:pc`

**Value** (JSON格式):
```json
[12345, 67890, 11223, 44556, 22334]
```

**Value** (序列化后):
```python
import json
value = json.dumps([12345, 67890, 11223, 44556, 22334])
# 存储: "[12345,67890,11223,44556,22334]"
```

#### 查询示例
```python
import redis
import json

r = redis.Redis(host='localhost', port=6379, db=0)

# 获取PC平台的热门商品
hot_items = json.loads(r.get('interest:hot:platform:pc'))
# 返回: [12345, 67890, 11223, 44556, 22334]

# 获取Top10热门商品
top_10 = hot_items[:10]
```

## 🔄 数据加载流程

### 1. 加载i2i索引

#### 1.1 加载C++ Swing索引（无商品名）

```python
def load_cpp_swing_index(file_path, redis_client, expire_seconds=604800):
    """
    加载C++ Swing索引到Redis
    
    Args:
        file_path: 索引文件路径（collaboration/output/swing_similar.txt）
        redis_client: Redis客户端
        expire_seconds: 过期时间（秒），默认7天
    """
    import json
    
    count = 0
    with open(file_path, 'r', encoding='utf-8') as f:
        for line in f:
            parts = line.strip().split('\t')
            if len(parts) < 2:
                continue
            
            item_id = parts[0]
            similar_str = parts[1]  # similar_id1:score1,similar_id2:score2,...
            
            # 解析相似商品
            similar_items = []
            for pair in similar_str.split(','):
                if ':' in pair:
                    sim_id, score = pair.split(':')
                    similar_items.append([int(sim_id), float(score)])
            
            # 存储到Redis
            redis_key = f"item:similar:swing_cpp:{item_id}"
            redis_value = json.dumps(similar_items)
            
            redis_client.set(redis_key, redis_value)
            redis_client.expire(redis_key, expire_seconds)
            
            count += 1
    
    return count
```

#### 1.2 加载Python i2i索引（含商品名）

```python
def load_i2i_index(file_path, algorithm_name, redis_client, expire_seconds=604800):
    """
    加载Python i2i相似度索引到Redis
    
    Args:
        file_path: 索引文件路径
        algorithm_name: 算法名称（swing, w2v, deepwalk, content）
        redis_client: Redis客户端
        expire_seconds: 过期时间（秒），默认7天
    """
    import json
    
    count = 0
    with open(file_path, 'r', encoding='utf-8') as f:
        for line in f:
            parts = line.strip().split('\t')
            if len(parts) < 3:
                continue
            
            item_id = parts[0]
            # item_name = parts[1]  # 可选：如果需要缓存商品名
            similar_str = parts[2]  # similar_id1:score1,similar_id2:score2,...
            
            # 解析相似商品
            similar_items = []
            for pair in similar_str.split(','):
                if ':' in pair:
                    sim_id, score = pair.split(':')
                    similar_items.append([int(sim_id), float(score)])
            
            # 存储到Redis
            redis_key = f"item:similar:{algorithm_name}:{item_id}"
            redis_value = json.dumps(similar_items)
            
            redis_client.set(redis_key, redis_value)
            redis_client.expire(redis_key, expire_seconds)
            
            count += 1
    
    return count
```

### 2. 加载兴趣聚合索引

```python
def load_interest_index(file_path, list_type, redis_client, expire_seconds=259200):
    """
    加载兴趣点聚合索引到Redis
    
    Args:
        file_path: 索引文件路径
        list_type: 列表类型（hot, cart, new, global）
        redis_client: Redis客户端
        expire_seconds: 过期时间（秒），默认3天
    """
    import json
    
    count = 0
    with open(file_path, 'r', encoding='utf-8') as f:
        for line in f:
            parts = line.strip().split('\t')
            if len(parts) != 2:
                continue
            
            dimension_key = parts[0]  # platform:pc
            item_ids_str = parts[1]   # 12345,67890,11223,...
            
            # 解析商品ID列表
            item_ids = [int(item_id) for item_id in item_ids_str.split(',')]
            
            # 存储到Redis
            redis_key = f"interest:{list_type}:{dimension_key}"
            redis_value = json.dumps(item_ids)
            
            redis_client.set(redis_key, redis_value)
            redis_client.expire(redis_key, expire_seconds)
            
            count += 1
    
    return count
```

## 🚀 快速加载命令

### 加载所有索引
```bash
cd /home/tw/recommendation/offline_tasks

# 加载所有索引（使用今天的数据，包括C++ Swing）
python3 scripts/load_index_to_redis.py --redis-host localhost --redis-port 6379

# 加载指定日期的索引
python3 scripts/load_index_to_redis.py --date 20251016 --redis-host localhost

# 只加载i2i索引（包括C++ Swing）
python3 scripts/load_index_to_redis.py --load-i2i --redis-host localhost

# 只加载C++ Swing索引
python3 scripts/load_index_to_redis.py \
    --file collaboration/output/swing_similar.txt \
    --algorithm swing_cpp \
    --redis-host localhost

# 只加载兴趣聚合索引
python3 scripts/load_index_to_redis.py --load-interest --redis-host localhost
```

### 验证数据
```bash
# 连接Redis
redis-cli

# 检查key数量
DBSIZE

# 查看某个商品的相似推荐（C++ Swing）
GET item:similar:swing_cpp:3600052

# 查看某个商品的相似推荐（Python Swing）
GET item:similar:swing:12345

# 查看平台热门商品
GET interest:hot:platform:pc

# 查看所有i2i相关的key
KEYS item:similar:*

# 查看C++ Swing的key
KEYS item:similar:swing_cpp:*

# 查看Python Swing的key
KEYS item:similar:swing:*

# 查看所有interest相关的key
KEYS interest:*

# 检查key的过期时间
TTL item:similar:swing_cpp:3600052
TTL item:similar:swing:12345
```

## 📊 数据统计

### Redis内存占用估算

| 索引类型 | Key数量 | 单条Value大小 | 总内存 |
|---------|--------|-------------|--------|
| i2i_swing_cpp | 50,000 | ~400B | ~20MB |
| i2i_swing | 50,000 | ~500B | ~25MB |
| i2i_w2v | 50,000 | ~500B | ~25MB |
| i2i_deepwalk | 50,000 | ~500B | ~25MB |
| i2i_content_name | 50,000 | ~500B | ~25MB |
| i2i_content_pic | 50,000 | ~500B | ~25MB |
| interest_hot | 10,000 | ~1KB | ~10MB |
| interest_cart | 10,000 | ~1KB | ~10MB |
| interest_new | 5,000 | ~1KB | ~5MB |
| interest_global | 10,000 | ~1KB | ~10MB |
| **总计** | **320,000** | - | **~180MB** |

**说明**:
- C++ Swing数据更紧凑（无商品名），单条大小约400B
- 建议生产环境使用C++ Swing (`swing_cpp`)，性能更优
- Python Swing可作为对照组或特殊场景使用

### 过期策略

| 索引类型 | TTL | 原因 |
|---------|-----|------|
| i2i行为相似 | 7天 | 用户行为变化快，需要频繁更新 |
| i2i内容相似 | 30天 | 商品属性变化慢，可以保留更久 |
| 热门/加购 | 3天 | 热度变化快，需要及时更新 |
| 新品 | 3天 | 新品概念有时效性 |
| 全局热门 | 7天 | 相对稳定，可以保留更久 |

## ⚠️ 注意事项

1. **原子性**: 使用Pipeline批量写入，提高性能
2. **过期时间**: 合理设置TTL，避免过期数据
3. **内存管理**: 定期清理过期key，监控内存使用
4. **数据版本**: 使用日期标记，支持数据回滚
5. **容错处理**: 加载失败时不影响线上服务
6. **监控告警**: 监控加载成功率、Redis内存、查询延迟

## 🔍 监控指标

### 数据质量指标
```python
# 检查加载成功率
total_keys = redis_client.dbsize()
expected_keys = 320000  # 更新：包含C++ Swing
success_rate = total_keys / expected_keys * 100

# 检查数据完整性
sample_keys = [
    'item:similar:swing_cpp:3600052',  # C++ Swing
    'item:similar:swing:12345',        # Python Swing
    'item:similar:w2v:12345',
    'interest:hot:platform:pc'
]
for key in sample_keys:
    if not redis_client.exists(key):
        print(f"Missing key: {key}")

# 检查C++ Swing vs Python Swing覆盖率
cpp_swing_count = len(redis_client.keys('item:similar:swing_cpp:*'))
py_swing_count = len(redis_client.keys('item:similar:swing:*'))
print(f"C++ Swing keys: {cpp_swing_count}")
print(f"Python Swing keys: {py_swing_count}")
```

### 性能指标
- 加载耗时: < 5分钟
- 内存占用: < 200MB
- 查询延迟: < 1ms
- 成功率: > 99%

## 🔗 相关文档

- **离线索引规范**: `OFFLINE_INDEX_SPEC.md`
- **API接口文档**: `RECOMMENDATION_API.md`
- **运维手册**: `OPERATIONS.md`