# ES向量相似度索引生成

## 概述

`i2i_content_similar.py` 脚本从Elasticsearch获取商品向量，计算并生成两种内容相似度索引：

1. **基于名称文本向量的相似度** (`i2i_content_name`)
2. **基于图片向量的相似度** (`i2i_content_pic`)

## 使用方法

### 运行脚本

```bash
cd /home/tw/recommendation/offline_tasks
python scripts/i2i_content_similar.py
```

脚本无需任何参数，所有配置都在代码中设置好。

### 配置说明

脚本内置配置（位于 `i2i_content_similar.py` 头部）：

```python
# ES配置
ES_CONFIG = {
    'host': 'http://localhost:9200',
    'index_name': 'spu',
    'username': 'essa',
    'password': '4hOaLaf41y2VuI8y'
}

# 算法参数
TOP_N = 50              # 每个商品返回的相似商品数量
KNN_K = 100             # knn查询返回的候选数
KNN_CANDIDATES = 200    # knn查询的候选池大小
```

## 工作流程

### 1. 获取活跃商品

从数据库查询最近1年内有过行为的商品：

```sql
SELECT DISTINCT item_id
FROM sensors_events
WHERE event IN ('click', 'contactFactory', 'addToPool', 'addToCart', 'purchase')
  AND create_time >= '1年前'
  AND item_id IS NOT NULL
```

### 2. 从ES获取向量

对每个活跃商品，从Elasticsearch查询：

```json
{
  "query": {
    "term": {
      "_id": "商品ID"
    }
  },
  "_source": {
    "includes": ["_id", "name_zh", "embedding_name_zh", "embedding_pic_h14", "on_sell_days_boost"]
  }
}
```

返回字段：
- `_id`: 商品ID
- `name_zh`: 中文名称（用于debug输出）
- `embedding_name_zh`: 名称文本向量 (1024维)
- `embedding_pic_h14`: 图片向量列表，每个元素包含：
  - `vector`: 向量 (1024维)
  - `url`: 图片URL
- `on_sell_days_boost`: 上架天数提权值 (0.9~1.1)

### 3. KNN向量相似度查询

使用商品的向量查询相似商品：

**名称向量查询：**
```json
{
  "knn": {
    "field": "embedding_name_zh",
    "query_vector": [向量值],
    "k": 100,
    "num_candidates": 200
  },
  "_source": ["_id", "name_zh", "on_sell_days_boost"],
  "size": 100
}
```

**图片向量查询：**
```json
{
  "knn": {
    "field": "embedding_pic_h14.vector",
    "query_vector": [向量值],
    "k": 100,
    "num_candidates": 200
  },
  "_source": ["_id", "name_zh", "on_sell_days_boost"],
  "size": 100
}
```

### 4. 应用上架天数提权

对每个查询结果，应用 `on_sell_days_boost` 提权：

```python
base_score = knn_result['_score']  # KNN基础分数
boost = knn_result['_source']['on_sell_days_boost']  # 提权值 (0.9~1.1)
final_score = base_score * boost  # 最终分数
```

**提权说明：**
- `on_sell_days_boost` 是基于商品上架天数计算的提权因子
- 取值范围: 0.9 ~ 1.1
- > 1.0: 提权（新品或热门商品）
- = 1.0: 不提权（正常商品）
- < 1.0: 降权（长尾商品）
- 如果字段缺失或异常，默认使用 1.0（不提权）

### 5. 生成索引文件

输出两个文件到 `output/` 目录：

- `i2i_content_name_YYYYMMDD.txt`: 基于名称向量的相似索引
- `i2i_content_pic_YYYYMMDD.txt`: 基于图片向量的相似索引

**文件格式：**
```
item_id\titem_name\tsimilar_id1:score1,similar_id2:score2,...
```

**示例：**
```
123456  香蕉干  234567:0.9234,345678:0.8756,456789:0.8432
```

## 输出说明

### Redis Key 格式

#### 名称向量相似
- **Key**: `item:similar:content_name:{item_id}`
- **Value**: `[[similar_id1,score1],[similar_id2,score2],...]`
- **TTL**: 30天

#### 图片向量相似
- **Key**: `item:similar:content_pic:{item_id}`
- **Value**: `[[similar_id1,score1],[similar_id2,score2],...]`
- **TTL**: 30天

### 使用示例

```python
import redis
import json

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

# 获取基于名称向量的相似商品
similar_items = json.loads(r.get('item:similar:content_name:123456'))
# 返回: [[234567, 0.9234], [345678, 0.8756], ...]

# 获取基于图片向量的相似商品
similar_items = json.loads(r.get('item:similar:content_pic:123456'))
# 返回: [[567890, 0.8123], [678901, 0.7856], ...]
```

## 性能说明

### 运行时间估算

假设有 50,000 个活跃商品：

- ES查询获取向量: ~50,000次，每次约10ms = 8-10分钟
- KNN相似度查询: ~50,000次，每次约50ms = 40-50分钟
- 总计: 约50-60分钟

### 优化建议

如果性能不够：

1. **批量处理**: 使用ES的 `_mget` 批量获取向量
2. **并发查询**: 使用多线程/异步IO提高查询并发
3. **增量更新**: 只处理新增/更新的商品
4. **缓存结果**: 将ES向量缓存到本地，避免重复查询

## ES向量字段说明

### embedding_name_zh

- **类型**: `dense_vector`
- **维度**: 1024
- **相似度**: `dot_product`
- **用途**: 基于商品名称的语义向量

### embedding_pic_h14

- **类型**: `nested`
- **结构**:
  ```json
  [
    {
      "vector": [1024维向量],
      "url": "图片URL"
    }
  ]
  ```
- **相似度**: `dot_product`
- **用途**: 基于商品图片的视觉向量

### on_sell_days_boost

- **类型**: `float`
- **取值范围**: 0.9 ~ 1.1
- **默认值**: 1.0
- **用途**: 基于上架天数的提权因子
- **计算逻辑**: 最终分数 = KNN分数 × on_sell_days_boost

## 注意事项

1. **网络连接**: 确保能访问ES服务器
2. **权限**: 确保ES用户有查询权限
3. **向量缺失**: 部分商品可能没有向量，会被跳过
4. **向量格式**: 图片向量是嵌套结构，取第一个图片的向量
5. **自我排除**: KNN结果会排除商品自己
6. **提权应用**: 所有相似度分数都已应用 `on_sell_days_boost` 提权
7. **提权范围**: boost值会被限制在0.9~1.1范围内，异常值使用1.0

## 故障排查

### 连接ES失败

```python
# 检查ES配置
curl -u essa:4hOaLaf41y2VuI8y http://localhost:9200/_cat/indices
```

### 查询超时

调整超时参数：
```python
es = Elasticsearch(
    [ES_CONFIG['host']],
    basic_auth=(ES_CONFIG['username'], ES_CONFIG['password']),
    request_timeout=60  # 增加到60秒
)
```

### 向量字段不存在

检查ES mapping：
```bash
curl -u essa:4hOaLaf41y2VuI8y http://localhost:9200/spu/_mapping
```

## 与其他相似度算法的对比

| 算法 | 数据源 | 优势 | 适用场景 |
|------|--------|------|---------|
| **Swing** | 用户行为 | 捕获真实交互关系 | 行为相似推荐 |
| **W2V** | 用户会话 | 捕获序列关系 | 下一个商品推荐 |
| **DeepWalk** | 行为图 | 发现深层关联 | 潜在兴趣挖掘 |
| **名称向量** | ES语义向量 | 语义理解强 | 文本相似推荐 |
| **图片向量** | ES视觉向量 | 视觉相似性强 | 外观相似推荐 |

## 更新频率建议

- **名称向量相似**: 每周更新（商品名称变化少）
- **图片向量相似**: 每周更新（商品图片变化少）
- **Redis TTL**: 30天（内容相似度变化慢）