ai-saas / saas-search

README.md 10.2 KB

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中搜索，从而辅助召回和相关性的计算。

对外： embedding服务： curl -X POST http://43.166.252.75:6005/embed/text \ -H "Content-Type: application/json" \ -d '["衣服", "Bohemian Maxi Dress"]'

翻译服务：

方式1：直接运行

python api/translator_app.py

方式2：使用 uvicorn

uvicorn api.translator_app:app --host 0.0.0.0 --port 6006 --reload

curl -X POST http://localhost:6006/translate -H "Content-Type: application/json" -d '{ "text": "商品名称", "target_lang": "en", "source_lang": "zh" }'

localhost替换为 服务器内网地址： 10.0.163.168 公网地址： 43.166.252.75

电商搜索引擎 SaaS

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

项目环境

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

# 推荐：首次创建 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=

  1. 后端：自动同步到mysql

  2. mysql到ES：

python scripts/recreate_and_import.py \ --tenant-id 162 \ --db-host \ --db-database saas \ --db-username saas \ --db-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/前端

快速上手（概览）

步骤 去哪里看 摘要
1. 准备环境 docs/环境配置说明.md / Usage-Guide.md Conda、activate.sh、依赖、ES/MySQL、.env
2. 构造测试数据 测试数据指南.md Tenant1 Mock、Tenant2 CSV、mock_data.sh
3. 启动与验证 Usage-Guide.md run.sh 一键启动、分步脚本、日志与健康检查
4. 理解架构 系统设计文档.md 数据流、配置系统、查询/搜索/索引模块
5. 接入搜索 API 搜索API对接指南.md / 搜索API速查表.md REST 端点、参数、响应、最佳实践
6. 查字段定义 索引字段说明.md search_products 映射、字段来源、类型与用途

README 仅保留最常用命令的“索引”。细节以主题文档为准。

Runtimes & 命令示例

# 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/环境配置说明.md 系统要求、activate.sh、Conda/依赖、外部服务、CONDA_ROOT 首次部署、新机器环境
docs/SERVICE_MATRIX.md 服务分层、端口、统一启动/停止入口 运维值守、联调启动
Usage-Guide.md 环境准备、服务启动、配置、日志、验证手册 日常运维、调试
基础配置指南.md 统一硬编码配置说明、索引结构、查询配置 了解系统配置、修改配置
测试数据指南.md 两个租户的模拟/CSV 数据构造 & MySQL→ES 流程 数据准备、联调
测试Pipeline说明.md 测试流水线、CI 脚本、上下文说明 自动化测试、追踪流水线
系统设计文档.md 架构、配置系统、索引/查询/排序模块细节 研发/扩展功能
索引字段说明v2.md search_products 字段、类型、来源、嵌套结构 新增字段、数据对齐
搜索API对接指南.md REST API（文本/图片/管理）详解、示例、响应格式 API 使用、测试
搜索API速查表.md 常用请求体、过滤器、分面速查表 支持团队快速查阅
Search-API-Examples.md Python/JS/cURL 端到端示例 客户工程、SDK 参考
环境配置说明.md + .env 模板 运行依赖账号、端口、密钥对照表 交付 & 运维

更多补充材料：

  • 测试数据指南.md：包含完整工作流脚本示例
  • 商品数据源入ES配置规范.md：数据源映射约定
  • MULTILANG_FEATURE.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/           运营及中文资料