# 内容相似索引更新说明

## 📋 更新概述

重构了 `i2i_content_similar.py`，从基于数据库属性计算改为基于Elasticsearch向量计算，生成两份内容相似索引。

## 🔄 主要变化

### 1. 算法改变

**之前 (旧版本):**
- 基于商品属性（分类、供应商、包装等）
- 使用TF-IDF + 余弦相似度
- 提供 `--method` 参数选择: tfidf / category / hybrid
- 复杂的参数配置

**现在 (新版本):**
- 基于Elasticsearch的向量相似度
- 使用KNN向量查询
- **无需任何参数，开箱即用**
- 自动生成两份索引

### 2. 生成的索引

| 索引名称 | 向量来源 | 文件名 | Redis Key | TTL |
|---------|---------|--------|-----------|-----|
| **名称向量相似** | `embedding_name_zh` | `i2i_content_name_YYYYMMDD.txt` | `item:similar:content_name:{item_id}` | 30天 |
| **图片向量相似** | `embedding_pic_h14` | `i2i_content_pic_YYYYMMDD.txt` | `item:similar:content_pic:{item_id}` | 30天 |

### 3. 参数简化

**之前:**
```bash
python i2i_content_similar.py --top_n 50 --method hybrid --debug
```

**现在:**
```bash
python i2i_content_similar.py
# 就这么简单！无需任何参数
```

所有配置都在代码中预设好：
- `TOP_N = 50`: 返回前50个相似商品
- `KNN_K = 100`: KNN查询返回100个候选
- `KNN_CANDIDATES = 200`: 候选池大小200

## 📝 更新的文件

### 核心代码
1. ✅ `offline_tasks/scripts/i2i_content_similar.py` - 完全重写
   - 连接Elasticsearch
   - 查询最近1年活跃商品
   - 获取向量并计算相似度
   - 生成两份索引

### 配置文档
2. ✅ `offline_tasks/REDIS_DATA_SPEC.md` - 更新Redis数据规范
   - 添加 `i2i_content_name` 规范
   - 添加 `i2i_content_pic` 规范
   - 更新内存占用估算（270,000 keys, ~160MB）

### 调度脚本
3. ✅ `offline_tasks/run_all.py` - 简化参数
   - 移除 `--only-*` 参数
   - 移除 `--skip-*` 参数
   - 移除 `--lookback_days` 和 `--top_n` 参数
   - 只保留 `--debug` 参数
   - 添加内容相似任务

4. ✅ `offline_tasks/scripts/load_index_to_redis.py` - 更新加载逻辑
   - 添加 `content_name` 和 `content_pic` 到索引类型列表

### 新增文档
5. ✅ `offline_tasks/scripts/ES_VECTOR_SIMILARITY.md` - ES向量相似度说明
   - ES配置说明
   - 工作流程详解
   - 性能说明和优化建议
   - 故障排查指南

6. ✅ `offline_tasks/CONTENT_SIMILARITY_UPDATE.md` - 本文档

## 🚀 使用指南

### 安装依赖

需要安装Elasticsearch客户端：
```bash
pip install elasticsearch
```

### 配置ES连接

在 `i2i_content_similar.py` 中修改ES配置（如需要）：
```python
ES_CONFIG = {
    'host': 'http://localhost:9200',
    'index_name': 'spu',
    'username': 'essa',
    'password': '4hOaLaf41y2VuI8y'
}
```

### 运行脚本

#### 单独运行
```bash
cd /home/tw/recommendation/offline_tasks
python scripts/i2i_content_similar.py
```

#### 通过run_all运行
```bash
python run_all.py
```

### 加载到Redis
```bash
python scripts/load_index_to_redis.py --date 20251017
```

## 📊 输出示例

### 文件格式
```
3302275    香蕉干    3302276:0.9234,3302277:0.8756,3302278:0.8432
```

### Redis存储
```python
# 名称向量相似
GET item:similar:content_name:3302275
# 返回: [[3302276,0.9234],[3302277,0.8756],[3302278,0.8432]]

# 图片向量相似
GET item:similar:content_pic:3302275
# 返回: [[4503826,0.8123],[4503827,0.7856],[4503828,0.7645]]
```

## 🔍 技术细节

### 数据源

1. **活跃商品列表**
   - 来源: 数据库 `sensors_events` 表
   - 条件: 最近1年内有行为记录
   - 行为类型: click, contactFactory, addToPool, addToCart, purchase

2. **向量数据**
   - 来源: Elasticsearch `spu` 索引
   - 字段:
     - `embedding_name_zh`: 名称文本向量 (1024维)
     - `embedding_pic_h14.vector`: 图片向量 (1024维)
     - `name_zh`: 商品中文名称

### ES查询

#### 1. 获取商品向量
```json
{
  "query": {
    "term": {"_id": "商品ID"}
  },
  "_source": {
    "includes": ["_id", "name_zh", "embedding_name_zh", "embedding_pic_h14"]
  }
}
```

#### 2. KNN相似度查询
```json
{
  "knn": {
    "field": "embedding_name_zh",
    "query_vector": [向量],
    "k": 100,
    "num_candidates": 200
  },
  "_source": ["_id", "name_zh"],
  "size": 100
}
```

## ⚡ 性能说明

### 运行时间
- 活跃商品数: ~50,000
- 向量查询: ~50,000次 × 10ms = 8-10分钟
- KNN查询: ~50,000次 × 50ms = 40-50分钟
- **总计: 约50-60分钟**

### 优化建议
1. 批量查询: 使用 `_mget` 批量获取向量
2. 并发处理: 多线程/异步IO
3. 增量更新: 只处理变化的商品
4. 缓存向量: 避免重复查询

## 🆚 与其他算法对比

| 算法 | 数据源 | 计算方式 | 特点 | 更新频率 |
|-----|-------|---------|------|---------|
| **Swing** | 用户行为 | 共现关系 | 捕获真实交互 | 每天 |
| **W2V** | 用户会话 | 序列学习 | 捕获序列关系 | 每天 |
| **DeepWalk** | 行为图 | 图游走 | 发现深层关联 | 每天 |
| **名称向量** | ES向量 | KNN查询 | 语义相似 | 每周 |
| **图片向量** | ES向量 | KNN查询 | 视觉相似 | 每周 |

## 📋 待办事项

- [x] 重写 `i2i_content_similar.py`
- [x] 更新 `REDIS_DATA_SPEC.md`
- [x] 简化 `run_all.py` 参数
- [x] 更新 `load_index_to_redis.py`
- [x] 编写技术文档
- [ ] 添加单元测试
- [ ] 性能优化（批量查询）
- [ ] 添加监控和告警

## ⚠️ 注意事项

1. **ES连接**: 确保能访问ES服务器
2. **向量缺失**: 部分商品可能没有向量，会被跳过
3. **网络延迟**: ES查询受网络影响，建议内网部署
4. **内存占用**: 处理大量商品时注意内存使用
5. **依赖安装**: 需要安装 `elasticsearch` Python包

## 🔗 相关文档

- `ES_VECTOR_SIMILARITY.md` - ES向量相似度详细说明
- `REDIS_DATA_SPEC.md` - Redis数据规范
- `OFFLINE_INDEX_SPEC.md` - 离线索引规范
- `QUICKSTART.md` - 快速开始指南

## 📞 联系方式

如有问题或建议，请联系开发团队。

---

**更新日期**: 2025-10-17  
**版本**: v2.0  
**作者**: AI Assistant