# TODO

  **多语言索引**：已改为可配置的 `index_languages`（默认为 `["en", "zh"]`），商家可勾选主市场语言。支持语言见 `config.tenant_config_loader.SUPPORTED_INDEX_LANGUAGES`（含 en, zh, zh_tw, ru, ja, ko, es, fr, pt, de, it, th, vi, id, ms, ar, hi, he, my, ta, ur, bn, pl, nl, ro, tr, km, lo, yue, cs, el, sv, hu, da, fi, uk, bg 等）。
  

  前端：
  搜索模态框
  点击搜索的时候，弹出 搜索模态框，参考 react、AJAX等技术来实现，搜索模态框的页面宽度和原始页面相同（占满），左侧是suggestions，右侧是即使刷新的搜索结果（每输入一个字母都刷新一次结果）。
  但是要注意：搜索过程中，后端不要触发翻译（因为输入过程中的query翻译结果会有问题），因此需要增加一个参数：搜索类型，默认为当前的回车后发起的搜索，如果是输入过程中的结果刷新则类型为typing。
  
  
  

  多语言：
  语义：

  多语言：
  1. dis_max的方式
  "query" : {
    "dis_max" : {
      "queries" : [

        {"match" : { "title.en" : xxx }},
        {"match" : { "title.zh" : xxx }},

        {"match" : { "title_xx" : xxx }}    
      ],
      "tie_breakler" : 0.8
    }
  }
  
  
  
  "corss_field":
  "multi_match" : {
    "query" : 
    "fields" : [...],
    "type": "cross_fields",
    "operator" : "and"
  }
  
  
  支持英文的拼写接错：
  title： multi_field
  "query" : {
    "query_string" : {
      "query": "xxx",
      "default_field": "title.ngram",
      "minimum_should_match": "85%"
    }
  }
  
  
  
  业务提权：
  rescore： window_size query_weight rescore_query_weight
  
  function_score:
  boost
  以及 可以把每个子查询用function_score包一下
  
  

  query anchor  

  我想给elasticsearch 增加字段 query anchor ，即哪些query点击到了这个doc，一个doc下面有多个query anchor，每个query anchor又有这两个属性：weight、dweight，分别代表 query在doc下的点击分布权重、doc在query下的点击分布权重。请问该如何设计这两个ES字段。
  
  需要有zh en两套query anchor，因为他们的解析器不一样。
  
  他的功能是辅助召回和排序。我搜索一个query，那么每个query跟 doc中的query anchor的相关性，也就是，除了将query到title 和keywords / brief等文本字段中搜索，也到 query anchor中搜索，从而辅助召回和相关性的计算。
  
  
  
  

  # 电商搜索引擎 SaaS

  一个针对跨境独立站（店匠 Shoplazza 等）的多租户可配置搜索平台。README 作为项目导航入口，帮助你在不同阶段定位到更详细的文档。

  ## 项目环境

  以项目根目录的 **`activate.sh`** 为准（**优先激活 venv：`./.venv`，并加载 `.env`；兼容 Conda 回退**）：

  
  ```bash

  # 推荐：首次创建 venv（默认安装基础依赖）
  ./scripts/create_venv.sh
  
  # 如需本地向量/图片编码（会安装 torch/transformers 等重依赖）
  # INSTALL_ML=1 ./scripts/create_venv.sh

  source activate.sh
  ```
  

  新机器首次需创建环境，见 `docs/环境配置说明.md`（推荐 venv；Conda 为兼容旧流程）。

  ## 测试pipeline
  

  1. 
  店铺1  tenant_id=162：
  fake数据 生成商品导入数据 提交到店匠的店铺：

  cd /data/saas-search && source activate.sh && python scripts/csv_to_excel_multi_variant.py --output with_colors.xlsx

  店铺2  tenant_id= 
  
  

  2. 后端：自动同步到mysql
  
  3. mysql到ES：

  
  python scripts/recreate_and_import.py \
      --tenant-id 162 \
      --db-host <mysql_host> \
      --db-database saas \
      --db-username saas \
      --db-password <password> \
      --es-host http://localhost:9200
  
  构造查询：

  参考 @常用查询 - ES.md

  ## 核心能力速览

  - **多语言 + 自动翻译**：中文、英文、俄文等语言检测与路由（BGE-M3、DeepL）
  - **语义 + 关键词混排**：BM25、dense vector（BGE-M3/CN-CLIP）融合
  - **布尔与分面**：AND / OR / ANDNOT / RANK、Terms & Range facets
  - **多租户隔离**：共享 `search_products` 索引，通过 `tenant_id` 严格隔离
  - **可配置化**：字段/索引域/排序表达式/查询改写全部配置驱动
  - **脚本化流水线**：Mock/CSV 数据 → MySQL → Elasticsearch → API/前端

  ## 新人入口

  **→ 开发者必读**：[docs/DEVELOPER_GUIDE.md](docs/DEVELOPER_GUIDE.md) — 项目全貌、设计原则、扩展规范与迭代检查清单，保证后续开发在统一框架内进行。
  
  **→ 快速上手**：[docs/QUICKSTART.md](docs/QUICKSTART.md) — 环境、服务、模块、请求示例一页搞定。

  | 步骤 | 文档 |
  |------|------|

  | 0. 框架与规范（推荐首读） | `docs/DEVELOPER_GUIDE.md` |

  | 1. 环境与启动 | `docs/QUICKSTART.md` |
  | 2. 搜索/索引 API | `docs/QUICKSTART.md` §3、`docs/搜索API速查表.md` |
  | 3. 运维与故障 | `docs/Usage-Guide.md` |

  | 4. 架构与扩展 | `docs/PROVIDER_ARCHITECTURE.md`、`docs/MODULE_EXTENSION_SPEC.md`、`docs/系统设计文档.md` |

  ### Runtimes & 命令示例

  
  ```bash

  # 1. 安装依赖与准备服务（环境创建见 docs/环境配置说明.md）
  source activate.sh   # 或先 export CONDA_ROOT=你的conda路径
  pip install -r requirements.txt   # 若用 environment.yml 创建环境可省略

  docker run -d --name es -p 9200:9200 elasticsearch:8.11.0

  # 2. 构造测试数据并导入 MySQL
  ./scripts/mock_data.sh                               # 详见 TEST_DATA_GUIDE.md

  # 3. 创建租户索引结构并导入数据（推荐）
  ./scripts/create_tenant_index.sh 162
  curl -X POST "http://localhost:6004/indexer/reindex" \
    -H "Content-Type: application/json" \
    -d '{"tenant_id":"162","batch_size":500}'

  # 4. 启动核心服务（backend/indexer/frontend）

  ./run.sh

  # （可选）附加启动 embedding / translator / reranker
  START_EMBEDDING=1 START_TRANSLATOR=1 START_RERANKER=1 ./run.sh

  #

  # 查看服务状态 / 停止
  ./scripts/service_ctl.sh status
  ./scripts/stop.sh

  # 5. 调用文本搜索 API

  curl -X POST http://localhost:6002/search/ \

    -H "Content-Type: application/json" \

    -H "X-Tenant-ID: 1" \
    -d '{"query": "玩具", "size": 10}'

  ```
  

  ## 文档索引
  
  | 文档 | 用途 |
  |------|------|

  | `docs/DEVELOPER_GUIDE.md` | **开发者开放指南**：全貌、原则、规范、检查清单 |
  | `docs/QUICKSTART.md` | 新人上手：环境、服务、模块、请求 |

  | `docs/Usage-Guide.md` | 运维：日志、多环境、故障排查 |
  | `docs/搜索API速查表.md` | 搜索 API 参数速查 |
  | `docs/搜索API对接指南.md` | 搜索 API 完整说明 |
  | `docs/PROVIDER_ARCHITECTURE.md` | 翻译/向量/重排 provider 扩展 |

  | `docs/MODULE_EXTENSION_SPEC.md` | 向量/重排后端可插拔规范 |

  | `docs/环境配置说明.md` | 首次部署、新机器环境 |
  | `docs/系统设计文档.md` | 架构与模块细节 |

  ## 关键工作流指引

  - **数据构建 → MySQL → Elasticsearch**  
    - `scripts/mock_data.sh`：Tenant1 Mock + Tenant2 CSV 一条龙  

    - `scripts/create_tenant_index.sh <tenant_id>` + `POST /indexer/reindex`：推荐导入链路

    - 详解：`测试数据指南.md`

  - **索引富化 & Java 对接**  
    - Java 索引程序负责：全量/增量调度 + 从 MySQL 查询 `shoplazza_product_spu/sku/option/...`  
    - Python `indexer` 模块负责：**MySQL 行 → ES doc** 的全部逻辑（多语言、翻译、向量、规格聚合等）  
    - 正式对接接口（推荐）：  
      - `POST http://<indexer_host>:6004/indexer/build-docs`  
        - 入参：`tenant_id + items[{spu, skus, options}]`  
        - 出参：与 `mappings/search_products.json` 完全一致的 `docs` 列表，上游自行写入 ES  
    - 调试/自测接口（内部使用）：  
      - `POST http://127.0.0.1:6004/indexer/build-docs-from-db`，只需要 `tenant_id + spu_ids`，由服务内部查库并返回 ES doc  
    - 详解：`indexer/README.md`、`docs/索引字段说明v2.md`
  

  - **搜索服务 & API**  
    - `api/`（FastAPI）承载 REST API，`search/` + `query/` 负责查询解析与下发  

    - API、分页、过滤、Facet、KNN 等：`搜索API对接指南.md`
    - 对接案例、示例与错误码：`搜索API对接指南.md`、`Search-API-Examples.md`

  - **统一配置**  
    - 所有租户共享统一的索引结构和查询配置（硬编码）  
    - 索引 mapping: `mappings/search_products.json`  
    - 查询配置: `search/query_config.py`  
    - 详解：`基础配置指南.md`、`索引字段说明v2.md`

  ## 仓库结构（概览）

  ```

  api/            FastAPI 服务与路由
  config/         字段/索引/查询配置体系
  indexer/        MySQL → ES 管道（mapping / transformer / bulk）
  query/          查询解析、改写、翻译、embedding
  search/         多语言构建、布尔解析、排序引擎
  scripts/        数据/服务脚本（mock_data, ingest, run 等）
  frontend/       简易调试页面
  docs/           运营及中文资料

  ```