# 搜索引擎通用化开发进度

## 项目概述

对后端搜索技术 做通用化。
通用化的本质 是 对于各种业务数据、各种检索需求，都可以  用少量定制+配置化 来实现效果。


**通用化的本质**：对于各种业务数据、各种检索需求，都可以用少量定制+配置化来实现效果。

---

## 1. 原始数据层的约定

所有租户共用主表、独立配置和扩展表，有自己独立的ES索引。

### 1.1 店匠主表

所有租户共用以下主表：
- `shoplazza_product_sku` - SKU级别商品数据
- `shoplazza_product_spu` - SPU级别商品数据

### 1.2 每个租户的扩展表

各个租户有自己的扩展表，不同的租户根据不同的业务需要、以及不同的数据源，来定制自己的扩展表：
- 自定义属性体系
- 多语言商品标题（中文、英文、俄文等）
- 品牌名、不同的类目和标签体系
- 业务过滤和聚合字段
- 权重（提权）字段

**数据关联方式**：
- 入索引时，商品主表 `shoplazza_product_sku` 的 `id` + `shopid` 与租户扩展表关联
- 例如：`customer1_extension` 表存储 customer1 的自定义字段

### 1.3 配置化方案

统一通过配置文件定义：
1. ES 字段定义（字段类型、分析器、来源表/列）
2. ES mapping 结构生成
3. 数据入库映射关系

---

## 2. 配置系统实现

### 2.1 应用结构配置（字段定义）

**配置文件位置**：`config/schema/{customer_id}_config.yaml`

**配置内容**：定义了 ES 的输入数据有哪些字段、关联 MySQL 的哪些字段。

**实现情况**：

#### 字段类型支持
- **TEXT**：文本字段，支持多语言分析器
- **KEYWORD**：关键词字段，用于精确匹配和聚合
- **TEXT_EMBEDDING**：文本向量字段（1024维，dot_product相似度）
- **IMAGE_EMBEDDING**：图片向量字段（1024维，dot_product相似度）
- **INT/LONG**：整数类型
- **FLOAT/DOUBLE**：浮点数类型
- **DATE**：日期类型
- **BOOLEAN**：布尔类型

#### 分析器支持
- **chinese_ecommerce**：中文电商分词器（index_ansj/query_ansj）
- **english**：英文分析器
- **russian**：俄文分析器
- **arabic**：阿拉伯文分析器
- **spanish**：西班牙文分析器
- **japanese**：日文分析器
- **standard**：标准分析器
- **keyword**：关键词分析器

#### 字段配置示例

```yaml
fields:
  # 主键字段
  - name: "skuId"
    type: "LONG"
    source_table: "main"          # 主表
    source_column: "id"
    required: true
    index: true
    store: true

  # 多语言文本字段
  - name: "name"
    type: "TEXT"
    source_table: "extension"     # 扩展表
    source_column: "name"
    analyzer: "chinese_ecommerce"
    boost: 2.0
    index: true
    store: true

  - name: "enSpuName"
    type: "TEXT"
    source_table: "extension"
    source_column: "enSpuName"
    analyzer: "english"
    boost: 2.0

  - name: "ruSkuName"
    type: "TEXT"
    source_table: "extension"
    source_column: "ruSkuName"
    analyzer: "russian"
    boost: 2.0

  # 文本向量字段
  - name: "name_embedding"
    type: "TEXT_EMBEDDING"
    source_table: "extension"
    source_column: "name"
    embedding_dims: 1024
    embedding_similarity: "dot_product"
    index: true

  # 图片向量字段
  - name: "image_embedding"
    type: "IMAGE_EMBEDDING"
    source_table: "extension"
    source_column: "imageUrl"
    embedding_dims: 1024
    embedding_similarity: "dot_product"
    nested: false
```

**实现模块**：
- `config/config_loader.py` - 配置加载器
- `config/field_types.py` - 字段类型定义
- `indexer/mapping_generator.py` - ES mapping 生成器
- `indexer/data_transformer.py` - 数据转换器

### 2.2 索引结构配置（查询域配置）

**配置内容**：定义了 ES 的字段索引 mapping 配置，支持各个域的查询，包括默认域的查询。

**实现情况**：

#### 域（Domain）配置
每个域定义了：
- 域名称（如 `default`, `title`, `category`, `brand`）
- 域标签（中文描述）
- 搜索字段列表
- 默认分析器
- 权重（boost）
- **多语言字段映射**（`language_field_mapping`）

#### 多语言字段映射

支持将不同语言的查询路由到对应的字段：

```yaml
indexes:
  - name: "default"
    label: "默认索引"
    fields:
      - "name"
      - "enSpuName"
      - "ruSkuName"
      - "categoryName"
      - "brandName"
    analyzer: "chinese_ecommerce"
    boost: 1.0
    language_field_mapping:
      zh:
        - "name"
        - "categoryName"
        - "brandName"
      en:
        - "enSpuName"
      ru:
        - "ruSkuName"

  - name: "title"
    label: "标题索引"
    fields:
      - "name"
      - "enSpuName"
      - "ruSkuName"
    analyzer: "chinese_ecommerce"
    boost: 2.0
    language_field_mapping:
      zh:
        - "name"
      en:
        - "enSpuName"
      ru:
        - "ruSkuName"
```

**工作原理**：
1. 检测查询语言（中文、英文、俄文等）
2. 如果查询语言在 `language_field_mapping` 中，使用原始查询搜索对应语言的字段
3. 将查询翻译到其他支持的语言，分别搜索对应语言的字段
4. 组合多个语言查询的结果，提高召回率

**实现模块**：
- `search/multilang_query_builder.py` - 多语言查询构建器
- `query/query_parser.py` - 查询解析器（支持语言检测和翻译）

---

## 3. 测试数据灌入

### 3.1 数据源

**主表**：`shoplazza_product_sku`
- 所有租户共用
- 包含基础商品信息（id, shopid 等）

**扩展表**：`customer1_extension`
- 每个租户独立
- 包含自定义字段和多语言字段

### 3.2 数据灌入方式

**实现情况**：

#### 命令行工具
```bash
python main.py ingest \
    --customer customer1 \
    --csv-file data/customer1_data.csv \
    --es-host http://localhost:9200 \
    --recreate \
    --batch-size 100
```

#### 数据流程
1. **数据加载**：从 CSV 文件或 MySQL 数据库加载数据
2. **数据转换**：
   - 字段映射（根据配置将源字段映射到 ES 字段）
   - 类型转换（字符串、数字、日期等）
   - 向量生成（文本向量、图片向量）
   - 向量缓存（避免重复计算）
3. **索引创建**：
   - 根据配置生成 ES mapping
   - 创建或更新索引
4. **批量入库**：
   - 批量写入 ES（默认每批 500 条）
   - 错误处理和重试机制

#### 配置映射示例

**customer1_config.yaml** 配置：
```yaml
main_table: "shoplazza_product_sku"
extension_table: "customer1_extension"
es_index_name: "search_customer1"

fields:
  - name: "skuId"
    source_table: "main"
    source_column: "id"
  - name: "name"
    source_table: "extension"
    source_column: "name"
  - name: "enSpuName"
    source_table: "extension"
    source_column: "enSpuName"
```

**数据转换**：
- 主表字段：直接从 `shoplazza_product_sku` 表的 `id` 字段读取
- 扩展表字段：从 `customer1_extension` 表的对应列读取
- 向量字段：对源文本/图片生成向量并缓存

**实现模块**：
- `indexer/data_transformer.py` - 数据转换器
- `indexer/bulk_indexer.py` - 批量索引器
- `indexer/indexing_pipeline.py` - 索引流水线
- `embeddings/bge_encoder.py` - 文本向量编码器
- `embeddings/clip_image_encoder.py` - 图片向量编码器

---

## 4. QueryParser 实现


### 4.1 查询改写（Query Rewriting）

配置词典的key是query，value是改写后的查询表达式，比如。比如品牌词 改写为在brand|query OR name|query，类别词、标签词等都可以放进去。纠错、规范化、查询改写等 都可以通过这个词典来配置。
**实现情况**：

#### 配置方式
在 `query_config.rewrite_dictionary` 中配置查询改写规则：

```yaml
query_config:
  enable_query_rewrite: true
  rewrite_dictionary:
    "芭比": "brand:芭比 OR name:芭比娃娃"
    "玩具": "category:玩具"
    "消防": "category:消防 OR name:消防"
```

#### 功能特性
- **精确匹配**：查询完全匹配词典 key 时，替换为 value
- **部分匹配**：查询包含词典 key 时，替换该部分
- **支持布尔表达式**：value 可以是复杂的布尔表达式（AND, OR, 域查询等）

#### 实现模块
- `query/query_rewriter.py` - 查询改写器
- `query/query_parser.py` - 查询解析器（集成改写功能）

### 4.2 翻译（Translation）

**实现情况**：

#### 配置方式
```yaml
query_config:
  supported_languages:
    - "zh"
    - "en"
    - "ru"
  default_language: "zh"
  enable_translation: true
  translation_service: "deepl"
  translation_api_key: null  # 通过环境变量设置
```

#### 功能特性
1. **语言检测**：自动检测查询语言
2. **智能翻译**：
   - 如果查询是中文，翻译为英文、俄文
   - 如果查询是英文，翻译为中文、俄文
   - 如果查询是其他语言，翻译为所有支持的语言
3. **域感知翻译**：
   - 如果域有 `language_field_mapping`，只翻译到映射中存在的语言
   - 避免不必要的翻译，提高效率
4. **翻译缓存**：缓存翻译结果，避免重复调用 API

#### 工作流程
```
查询输入 → 语言检测 → 确定目标语言 → 翻译 → 多语言查询构建
```

#### 实现模块
- `query/language_detector.py` - 语言检测器
- `query/translator.py` - 翻译器（DeepL API）
- `query/query_parser.py` - 查询解析器（集成翻译功能）

### 4.3 文本向量化（Text Embedding）

如果配置打开了text_embedding查询，并且query 包含了default域的查询，那么要把default域的查询词转向量，后面searcher会用这个向量参与查询。

**实现情况**：

#### 配置方式
```yaml
query_config:
  enable_text_embedding: true
```

#### 功能特性
1. **条件生成**：
   - 仅当 `enable_text_embedding=true` 时生成向量
   - 仅对 `default` 域查询生成向量
2. **向量模型**：BGE-M3 模型（1024维向量）
3. **用途**：用于语义搜索（KNN 检索）

#### 实现模块
- `embeddings/bge_encoder.py` - BGE 文本编码器
- `query/query_parser.py` - 查询解析器（集成向量生成）

---

## 5. Searcher 实现

参考opensearch，他们自己定义的一套索引结构配置、支持自定义的一套检索表达式、排序表达式，这是各个客户进行配置化的基础，包括索引结构配置、排序策略配置。
比如各种业务过滤策略 可以简单的通过表达式满足，比如brand|耐克 AND cate2|xxx。指定字段排序可以通过排序的表达式实现。

查询默认在default域，相也会对这个域的查询做一些相关性的重点优化，包括融合语义相关性、多语言相关性（可以基于配置 将查询翻译到指定语言并在对应的语言的字段进行查询）来弥补传统查询分析手段（比如查询改写 纠错 词权重等）的不足，也支持通过配置一些词表转为泛查询模式来优化相关性。

### 5.1 布尔表达式解析

**实现情况**：

#### 支持的运算符
- **AND**：所有项必须匹配
- **OR**：任意项匹配
- **RANK**：排序增强（类似 OR 但影响排序）
- **ANDNOT**：排除（第一项匹配，第二项不匹配）
- **()**：括号分组

#### 优先级（从高到低）
1. `()` - 括号
2. `ANDNOT` - 排除
3. `AND` - 与
4. `OR` - 或
5. `RANK` - 排序

#### 示例
```
laptop AND (gaming OR professional) ANDNOT cheap
```

#### 实现模块
- `search/boolean_parser.py` - 布尔表达式解析器
- `search/searcher.py` - 搜索器（集成布尔解析）

### 5.2 多语言搜索

**实现情况**：

#### 工作原理
1. **查询解析**：
   - 提取域（如 `title:查询` → 域=`title`，查询=`查询`）
   - 检测查询语言
   - 生成翻译
2. **多语言查询构建**：
   - 如果域有 `language_field_mapping`：
     - 使用检测到的语言查询对应字段（boost * 1.5）
     - 使用翻译后的查询搜索其他语言字段（boost * 1.0）
   - 如果域没有 `language_field_mapping`：
     - 使用所有字段进行搜索
3. **查询组合**：
   - 多个语言查询组合为 `should` 子句
   - 提高召回率

#### 示例
```
查询: "芭比娃娃"
域: default
检测语言: zh

生成的查询:
- 中文查询 "芭比娃娃" → 搜索 name, categoryName, brandName (boost * 1.5)
- 英文翻译 "Barbie doll" → 搜索 enSpuName (boost * 1.0)
- 俄文翻译 "Кукла Барби" → 搜索 ruSkuName (boost * 1.0)
```

#### 实现模块
- `search/multilang_query_builder.py` - 多语言查询构建器
- `search/searcher.py` - 搜索器（使用多语言构建器）

### 5.3 相关性计算（Ranking）

**实现情况**：

#### 当前实现
**公式**：`bm25() + 0.2 * text_embedding_relevance()`

- **bm25()**：BM25 文本相关性得分
  - 包括多语言打分
  - 内部通过配置翻译为多种语言
  - 分别到对应的字段搜索
  - 中文字段使用中文分词器，英文字段使用英文分词器
- **text_embedding_relevance()**：文本向量相关性得分（KNN 检索的打分）
  - 权重：0.2

#### 配置方式
```yaml
ranking:
  expression: "bm25() + 0.2*text_embedding_relevance()"
  description: "BM25 text relevance combined with semantic embedding similarity"
```

#### 扩展性
- 支持表达式配置（未来可扩展）
- 支持自定义函数（如 `timeliness()`, `field_value()`）

#### 实现模块
- `search/ranking_engine.py` - 排序引擎
- `search/searcher.py` - 搜索器（集成排序功能）

---

## 6. 已完成功能总结

### 6.1 配置系统
- ✅ 字段定义配置（类型、分析器、来源表/列）
- ✅ 索引域配置（多域查询、多语言映射）
- ✅ 查询配置（改写词典、翻译配置）
- ✅ 排序配置（表达式配置）
- ✅ 配置验证（字段存在性、类型检查、分析器匹配）

### 6.2 数据索引
- ✅ 数据转换（字段映射、类型转换）
- ✅ 向量生成（文本向量、图片向量）
- ✅ 向量缓存（避免重复计算）
- ✅ 批量索引（错误处理、重试机制）
- ✅ ES mapping 自动生成

### 6.3 查询处理
- ✅ 查询改写（词典配置）
- ✅ 语言检测
- ✅ 多语言翻译（DeepL API）
- ✅ 文本向量化（BGE-M3）
- ✅ 域提取（支持 `domain:query` 语法）

### 6.4 搜索功能
- ✅ 布尔表达式解析（AND, OR, RANK, ANDNOT, 括号）
- ✅ 多语言查询构建（语言路由、字段映射）
- ✅ 语义搜索（KNN 检索）
- ✅ 相关性排序（BM25 + 向量相似度）
- ✅ 结果聚合（Faceted Search）

### 6.5 API 服务
- ✅ RESTful API（FastAPI）
- ✅ 搜索接口（文本搜索、图片搜索）
- ✅ 文档查询接口
- ✅ 前端界面（HTML + JavaScript）

---

## 7. 技术栈

- **后端**：Python 3.6+
- **搜索引擎**：Elasticsearch
- **数据库**：MySQL（Shoplazza）
- **向量模型**：BGE-M3（文本）、CN-CLIP（图片）
- **翻译服务**：DeepL API
- **API 框架**：FastAPI
- **前端**：HTML + JavaScript

---

## 8. 配置文件示例

完整配置示例请参考：`config/schema/customer1_config.yaml`

---

## 9. 相关文档

- `MULTILANG_FEATURE.md` - 多语言功能详细说明
- `QUICKSTART.md` - 快速开始指南
- `HighLevelDesign.md` - 高层设计文档
- `IMPLEMENTATION_SUMMARY.md` - 实现总结
- `商品数据源入ES配置规范.md` - 数据源配置规范