# 电商搜索引擎 SaaS 系统

一个可配置的多租户搜索引擎，专为跨境电商独立站（店匠 Shoplazza）设计。

## 系统特性

- **多语言支持**：支持中文、英文、俄文、阿拉伯文、西班牙文、日文，支持自动翻译
- **语义搜索**：基于 BGE-M3 文本向量和 CN-CLIP 图片向量的语义检索
- **混合排序**：结合 BM25 文本相关性和语义相似度
- **布尔表达式**：支持 AND、OR、RANK、ANDNOT 操作符，支持括号优先级
- **灵活过滤**：精确匹配过滤器和数值范围过滤器
- **分面搜索**：动态生成过滤选项，提供分组统计
- **可配置化**：客户特定的字段定义、分析器、排序表达式
- **多租户隔离**：通过 `tenant_id` 实现数据隔离，共享统一索引
- **RESTful API**：基于 FastAPI 的完整 API 服务
- **前端界面**：提供可视化搜索测试界面

## 系统架构

### 数据模型

- **SPU 级别索引**：所有租户共享 `search_products` 索引
- **嵌套结构**：每个 SPU 文档包含嵌套的 `variants` 数组（SKU 变体）
- **租户隔离**：通过 `tenant_id` 字段实现多租户数据隔离
- **数据源**：MySQL 数据库（`shoplazza_product_spu` 和 `shoplazza_product_sku` 表）

### 技术栈

- **后端框架**：Python 3.8+ / FastAPI
- **搜索引擎**：Elasticsearch 8.x
- **数据库**：MySQL（店匠数据表）
- **向量模型**：
  - 文本向量：BGE-M3（1024维）
  - 图片向量：CN-CLIP（1024维）
- **翻译服务**：DeepL API
- **前端**：HTML + JavaScript

## 快速开始

### 1. 环境准备

#### 安装依赖

```bash
pip install -r requirements.txt
```

#### 启动 Elasticsearch

```bash
# 使用 Docker
docker run -d \
  --name elasticsearch \
  -p 9200:9200 \
  -e "discovery.type=single-node" \
  -e "ES_JAVA_OPTS=-Xms2g -Xmx2g" \
  elasticsearch:8.11.0
```

#### 配置环境变量（可选）

创建 `.env` 文件：

```bash
DB_HOST=120.79.247.228
DB_PORT=3316
DB_DATABASE=saas
DB_USERNAME=saas
DB_PASSWORD=your_password
ES_HOST=http://localhost:9200
```

### 2. 脚本体系

项目提供统一的脚本系统，管理完整的工作流程：

#### 脚本说明

| 脚本 | 功能 | 说明 |
|------|------|------|
| `restart.sh` | 重启服务 | 停止并重新启动前后端服务 |
| `run.sh` | 启动服务 | 启动前端和后端服务 |
| `scripts/mock_data.sh` | 数据导入 | 将 Mock 数据或 CSV 数据导入 MySQL |
| `scripts/ingest.sh` | 数据索引 | 从 MySQL 导入数据到 Elasticsearch |

#### 使用示例

**1. 导入 Mock 数据到 MySQL（tenant_id=1）**

```bash
# 生成并导入 100 个 Mock SPU（默认）
./scripts/mock_data.sh

# 生成并导入指定数量的 SPU
./scripts/mock_data.sh 1 200

# 使用显式参数
./scripts/mock_data.sh --mode mock --tenant-id 1 --num-spus 200
```

**2. 导入 CSV 数据到 MySQL（tenant_id=2）**

```bash
# 导入 customer1 的 CSV 数据
./scripts/mock_data.sh --mode csv \
  --csv-file data/customer1/goods_with_pic.5years_congku.csv.shuf.1w \
  --tenant-id 2 \
  --start-spu-id 1
```

**3. 从 MySQL 导入数据到 Elasticsearch**

```bash
# 导入 tenant_id=1 的数据
./scripts/ingest.sh 1

# 重建索引并导入数据
./scripts/ingest.sh 1 true
```

**4. 启动服务**

```bash
# 启动前端和后端
./run.sh

# 重启所有服务
./restart.sh
```

#### 完整工作流程示例

```bash
# 1. 导入 Mock 数据（tenant_id=1）
./scripts/mock_data.sh 1 100

# 2. 导入 CSV 数据（tenant_id=2）
./scripts/mock_data.sh --mode csv \
  --csv-file data/customer1/goods_with_pic.5years_congku.csv.shuf.1w \
  --tenant-id 2

# 3. 将两个租户的数据导入 ES
./scripts/ingest.sh 1
./scripts/ingest.sh 2

# 4. 启动服务
./run.sh
```

### 3. 手动启动 API 服务（可选）

如果不想使用脚本，可以手动启动：

```bash
python -m api.app \
  --host 0.0.0.0 \
  --port 6002 \
  --es-host http://localhost:9200 \
  --reload
```

### 4. 测试搜索

#### 简单搜索

```bash
curl -X POST http://localhost:6002/search/ \
  -H "Content-Type: application/json" \
  -d '{
    "query": "蓝牙耳机",
    "size": 10
  }'
```

#### 带过滤器的搜索

```bash
curl -X POST http://localhost:6002/search/ \
  -H "Content-Type: application/json" \
  -d '{
    "query": "玩具",
    "size": 10,
    "filters": {
      "categoryName_keyword": "玩具"
    },
    "range_filters": {
      "min_price": {
        "gte": 50,
        "lte": 200
      }
    }
  }'
```

#### 布尔表达式搜索

```bash
curl -X POST http://localhost:6002/search/ \
  -H "Content-Type: application/json" \
  -d '{
    "query": "蓝牙 AND (耳机 OR 音响)",
    "size": 10
  }'
```

#### 图片搜索

```bash
curl -X POST http://localhost:6002/search/image \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://oss.essa.cn/example.jpg",
    "size": 10
  }'
```

#### 分面搜索

```bash
curl -X POST http://localhost:6002/search/ \
  -H "Content-Type: application/json" \
  -d '{
    "query": "玩具",
    "size": 10,
    "facets": [
      {
        "field": "categoryName_keyword",
        "label": "分类"
      },
      {
        "field": "brandName_keyword",
        "label": "品牌"
      }
    ]
  }'
```

## 项目结构

```
SearchEngine/
├── api/                      # API 服务
│   ├── app.py               # FastAPI 应用主入口
│   ├── models.py            # 请求/响应模型
│   └── routes/              # API 路由
│       ├── search.py        # 搜索接口
│       └── admin.py         # 管理接口
├── config/                   # 配置系统
│   ├── field_types.py       # 字段类型定义
│   ├── config_loader.py     # 配置加载器
│   └── schema/              # 租户配置文件
│       └── base/            # Base 配置（店匠通用）
│           └── config.yaml
├── indexer/                  # 数据索引
│   ├── mapping_generator.py # ES mapping 生成器
│   ├── spu_transformer.py   # SPU 数据转换器
│   ├── bulk_indexer.py      # 批量索引器
│   └── ingest_shoplazza.py  # 店匠数据导入脚本
├── query/                    # 查询处理
│   ├── query_parser.py      # 查询解析器
│   ├── language_detector.py # 语言检测
│   ├── translator.py        # 翻译服务
│   └── query_rewriter.py    # 查询改写
├── search/                   # 搜索执行
│   ├── searcher.py          # 主搜索器
│   ├── multilang_query_builder.py  # 多语言查询构建器
│   ├── boolean_parser.py    # 布尔表达式解析器
│   ├── es_query_builder.py   # ES 查询构建器
│   └── ranking_engine.py    # 排序引擎
├── embeddings/               # 向量编码
│   ├── text_encoder.py      # BGE-M3 文本编码器
│   └── image_encoder.py     # CN-CLIP 图片编码器
├── utils/                    # 工具类
│   ├── db_connector.py      # MySQL 连接器
│   ├── es_client.py         # ES 客户端封装
│   └── cache.py             # 向量缓存
├── scripts/                  # 脚本工具
│   ├── mock_data.sh         # Mock 数据导入脚本
│   ├── ingest.sh            # 数据索引脚本
│   ├── generate_test_data.py # 生成测试数据
│   ├── import_tenant2_csv.py # Tenant2 CSV 导入脚本
│   └── import_test_data.py  # 数据导入脚本
├── frontend/                 # 前端界面
│   └── unified.html         # 统一搜索界面
├── data/                     # 数据文件
│   └── customer1/           # customer1 测试数据
├── run.sh                    # 启动脚本
├── restart.sh                # 重启脚本
└── requirements.txt         # Python 依赖
```

## 配置系统

### 配置文件结构

配置文件位于 `config/schema/{tenant_id}/config.yaml`，Base 配置位于 `config/schema/base/config.yaml`。

### 配置内容

#### 1. 字段定义 (fields)

定义 ES 索引的字段结构：

```yaml
fields:
  title_zh:
    type: TEXT
    analyzer: chinese_ecommerce
    index: true
    store: true
    boost: 2.0
  title_en:
    type: TEXT
    analyzer: english
    index: true
    store: true
  categoryName_keyword:
    type: KEYWORD
    index: true
    store: true
  min_price:
    type: FLOAT
    index: true
    store: true
  title_embedding:
    type: TEXT_EMBEDDING
    dimension: 1024
    similarity: dot_product
```

#### 2. 查询域配置 (indexes)

定义多域查询配置：

```yaml
indexes:
  default:
    fields: ["title_zh", "title_en", "title_ru"]
    weights: {"title_zh": 2.0, "title_en": 1.5}
  title:
    fields: ["title_zh", "title_en"]
  brand:
    fields: ["brandName_keyword"]
```

#### 3. 查询配置 (query_config)

多语言和翻译配置：

```yaml
query_config:
  languages: ["zh", "en", "ru"]
  auto_translate: true
  translation_api: "deepl"
  enable_embeddings: true
  embedding_model: "bge-m3"
```

#### 4. 排序配置 (ranking)

相关性排序表达式：

```yaml
ranking:
  expression: "bm25() + 0.2*text_embedding_relevance() + general_score*2"
  enable_function_score: true
```

#### 5. SPU 配置 (spu_config)

SPU 聚合配置：

```yaml
spu_config:
  enabled: true
  spu_field: "product_id"
  inner_hits_size: 3
```

### 字段类型

| 类型 | 说明 | 示例 |
|------|------|------|
| `TEXT` | 文本字段，支持分词 | 商品标题、描述 |
| `KEYWORD` | 关键词字段，精确匹配 | 分类、品牌 |
| `TEXT_EMBEDDING` | 文本向量（1024维） | 语义搜索 |
| `IMAGE_EMBEDDING` | 图片向量（1024维） | 图片搜索 |
| `INT/LONG` | 整数类型 | 库存、ID |
| `FLOAT/DOUBLE` | 浮点数类型 | 价格 |
| `DATE` | 日期类型 | 创建时间 |
| `BOOLEAN` | 布尔类型 | 是否上架 |

### 分析器

| 分析器 | 说明 | 适用语言 |
|--------|------|----------|
| `chinese_ecommerce` | 中文电商分词器（Ansj） | 中文 |
| `english` | 英文分析器 | 英文 |
| `russian` | 俄文分析器 | 俄文 |
| `arabic` | 阿拉伯文分析器 | 阿拉伯文 |
| `spanish` | 西班牙文分析器 | 西班牙文 |
| `japanese` | 日文分析器 | 日文 |
| `standard` | 标准分析器 | 通用 |
| `keyword` | 关键词分析器 | 精确匹配 |

## API 接口

### 搜索接口

#### 1. 文本搜索

**端点**: `POST /search/`

**请求示例**:

```json
{
  "query": "蓝牙耳机",
  "size": 10,
  "from": 0,
  "filters": {
    "categoryName_keyword": "电子产品"
  },
  "range_filters": {
    "min_price": {
      "gte": 50,
      "lte": 500
    }
  },
  "facets": [
    {
      "field": "categoryName_keyword",
      "label": "分类"
    }
  ],
  "sort_by": "min_price",
  "sort_order": "asc"
}
```

#### 2. 图片搜索

**端点**: `POST /search/image`

**请求示例**:

```json
{
  "image_url": "https://oss.essa.cn/example.jpg",
  "size": 10,
  "filters": {
    "categoryName_keyword": "玩具"
  }
}
```

#### 3. 获取文档

**端点**: `GET /search/{doc_id}`

### 管理接口

#### 1. 健康检查

**端点**: `GET /admin/health`

#### 2. 获取配置

**端点**: `GET /admin/config?tenant_id=1`

#### 3. 索引统计

**端点**: `GET /admin/stats?tenant_id=1`

#### 4. 查询改写规则

**端点**: 
- `GET /admin/rewrite-rules?tenant_id=1` - 获取规则
- `POST /admin/rewrite-rules` - 更新规则

详细 API 文档请参考 `API_DOCUMENTATION.md`。

## 高级功能

### 布尔表达式

支持的操作符（优先级从高到低）：

1. `()` - 括号
2. `ANDNOT` - 排除
3. `AND` - 必须全部匹配
4. `OR` - 任意匹配
5. `RANK` - 排序提升

**示例**:

```
蓝牙 AND (耳机 OR 音响) ANDNOT 便宜
laptop AND (gaming OR professional) ANDNOT cheap
```

### 查询改写

配置品牌/分类映射：

```yaml
rewrite_dictionary:
  "苹果": "brand:苹果 OR name:iPhone"
  "玩具": "category:玩具"
```

### 排序表达式

可配置的相关性排序：

```
bm25() + 0.2*text_embedding_relevance() + general_score*2 + timeliness(end_time)
```

支持的函数：
- `bm25()` - BM25 相关性分数
- `text_embedding_relevance()` - 文本向量相似度
- `image_embedding_relevance()` - 图片向量相似度
- `field_value(field_name)` - 字段值
- `timeliness(date_field)` - 时间衰减

### 多语言查询

系统自动检测查询语言，并支持：

- **自动翻译**：将查询翻译到配置的所有语言
- **语言路由**：根据语言选择对应的字段
- **混合查询**：同时查询多个语言字段

### SPU 聚合

启用 SPU 聚合后，每个 SPU 只返回一个代表性 SKU：

```yaml
spu_config:
  enabled: true
  spu_field: "product_id"
  inner_hits_size: 3  # 每个 SPU 内部返回的 SKU 数量
```

## 数据导入

### MySQL 表结构

系统使用店匠的标准表结构：

- **SPU 表**: `shoplazza_product_spu`
- **SKU 表**: `shoplazza_product_sku`

### 数据导入流程

1. **生成 SQL**：使用 `scripts/generate_test_data.py` 或 `scripts/import_tenant2_csv.py` 生成 SQL 文件
2. **导入 MySQL**：使用 `scripts/mock_data.sh` 或 `scripts/import_test_data.py` 导入数据
3. **索引到 ES**：使用 `scripts/ingest.sh` 或 `scripts/ingest_shoplazza.py` 将数据索引到 Elasticsearch

### CSV 数据格式

CSV 文件应包含以下字段：

- `skuId` - SKU ID
- `name` - 商品名称（中文）
- `name_pinyin` - 拼音
- `create_time` - 创建时间
- `ruSkuName` - 俄文名称
- `enSpuName` - 英文名称
- `categoryName` - 分类名称
- `supplierName` - 供应商名称
- `brandName` - 品牌名称
- `file_id` - 文件 ID
- `id` - 商品 ID
- `imageUrl` - 图片 URL

## 性能优化

### 1. 向量缓存

启用向量缓存可以避免重复计算：

```python
# 在配置中启用缓存
cache:
  enabled: true
  ttl: 3600  # 缓存过期时间（秒）
```

### 2. 批量处理

调整批量大小以优化性能：

- **数据转换批量大小**：默认 100（根据内存调整）
- **索引批量大小**：默认 500（根据 ES 性能调整）

### 3. GPU 加速

使用 GPU 加速向量计算：

```bash
# 安装 CUDA 版本的 PyTorch
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118
```

### 4. ES 分片配置

根据数据量配置 ES 分片：

```yaml
# 在 mapping 生成器中配置
settings:
  number_of_shards: 3
  number_of_replicas: 1
```

## 开发指南

### 运行测试

```bash
pytest tests/
```

### 代码格式化

```bash
black .
```

### 类型检查

```bash
mypy .
```

### 日志查看

```bash
# 查看服务日志
tail -f logs/search_service.log
```

## 常见问题

### 1. 如何添加新的租户？

1. 创建配置文件 `config/schema/{tenant_id}/config.yaml`
2. 导入数据到 MySQL（使用 `scripts/mock_data.sh`）
3. 索引数据到 ES（使用 `scripts/ingest.sh {tenant_id}`）

### 2. 如何修改排序规则？

编辑配置文件中的 `ranking.expression` 字段。

### 3. 如何添加新的分析器？

在 `config/field_types.py` 中定义新的分析器，然后在字段配置中使用。

### 4. 向量计算很慢怎么办？

- 启用向量缓存
- 使用 GPU 加速
- 减少批量大小

### 5. 如何调试搜索查询？

在 API 请求中设置 `debug: true`，返回详细的调试信息。

## 相关文档

- **API 文档**: `API_DOCUMENTATION.md`
- **设计文档**: `设计文档.md`
- **部署指南**: `DEPLOYMENT.md`
- **用户指南**: `USER_GUIDE.md`

## 许可证

专有软件 - 保留所有权利