README.md
电商搜索引擎 SaaS
一个针对跨境独立站（店匠 Shoplazza 等）的多租户可配置搜索平台。README 作为项目导航入口，帮助你在不同阶段定位到更详细的文档。
核心能力速览
- 多语言 + 自动翻译：中文、英文、俄文等语言检测与路由（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. 准备环境 | 环境相关.md / USAGE_GUIDE.md |
Conda/依赖、Elasticsearch、MySQL、必需的变量 |
| 2. 构造测试数据 | TEST_DATA_GUIDE.md |
Tenant1 Mock、Tenant2 CSV、mock_data.sh / ingest.sh |
| 3. 启动与验证 | USAGE_GUIDE.md |
run.sh 一键启动、分步脚本、日志与健康检查 |
| 4. 理解架构 | 设计文档.md |
数据流、配置系统、查询/搜索/索引模块 |
| 5. 接入搜索 API | API_DOCUMENTATION.md / API_INTEGRATION_GUIDE.md |
REST 端点、参数、响应、最佳实践 |
| 6. 查字段定义 | INDEX_FIELDS_DOCUMENTATION.md |
search_products 映射、字段来源、类型与用途 |
README 仅保留最常用命令的“索引”。细节以主题文档为准。
Runtimes & 命令示例
# 1. 安装依赖与准备服务
pip install -r requirements.txt # 详见 USAGE_GUIDE.md
docker run -d --name es -p 9200:9200 elasticsearch:8.11.0
# 2. 构造测试数据并导入 MySQL
./scripts/mock_data.sh # 详见 TEST_DATA_GUIDE.md
# 3. 从 MySQL 注入到 Elasticsearch
./scripts/ingest.sh 1 true
./scripts/ingest.sh 2 true
# 4. 启动服务
./run.sh
# 5. 调用文本搜索 API
curl -X POST http://localhost:6002/search/ \
-H "Content-Type: application/json" \
-H "X-Tenant-ID: 1" \
-d '{"query": "玩具", "size": 10}'
文档地图
| 文档 | 内容提要 | 适用场景 |
|---|---|---|
环境相关.md |
系统要求、Conda/依赖、外部服务账号、常用端口 | 首次部署、环境核对 |
USAGE_GUIDE.md |
环境准备、服务启动、配置、日志、验证手册 | 日常运维、调试 |
TEST_DATA_GUIDE.md |
两个租户的模拟/CSV数据构造 & MySQL→ES流程 | 数据准备、联调 |
设计文档.md |
架构、配置系统、索引/查询/排序模块细节 | 研发/扩展功能 |
INDEX_FIELDS_DOCUMENTATION.md |
search_products 字段、类型、来源、嵌套结构 |
新增字段、数据对齐 |
API_DOCUMENTATION.md |
REST API（搜索/图片/管理）详解、示例、响应格式 | API 使用、测试 |
API_INTEGRATION_GUIDE.md |
客户对接指引、最佳实践、错误处理、语言说明 | 第三方集成、SDK 开发 |
API_QUICK_REFERENCE.md |
常用请求体速查表 | 支持团队快速查阅 |
环境相关.md + .env 模板 |
运行依赖账号、端口、密钥对照表 | 交付 & 运维 |
更多补充材料：
TEST_DATA_GUIDE.md：包含完整工作流脚本示例商品数据源入ES配置规范.md：数据源映射约定MULTILANG_FEATURE.md：多语言处理细节
关键工作流指引
数据构建 → MySQL → Elasticsearch
scripts/mock_data.sh：Tenant1 Mock + Tenant2 CSV 一条龙scripts/ingest.sh <tenant_id> [recreate]：驱动indexer/模块写入search_products- 详解：
TEST_DATA_GUIDE.md
搜索服务 & API
api/（FastAPI）承载 REST API，search/+query/负责查询解析与下发- API、分页、过滤、Facet、KNN 等：
API_DOCUMENTATION.md - 对接案例与错误码：
API_INTEGRATION_GUIDE.md
配置驱动能力
config/schema/{tenant_id}/config.yaml：字段定义、索引域、排序表达式、SPU 聚合- 详解与设计理念：
设计文档.md、INDEX_FIELDS_DOCUMENTATION.md
仓库结构（概览）
api/ FastAPI 服务与路由
config/ 字段/索引/查询配置体系
indexer/ MySQL → ES 管道（mapping / transformer / bulk）
query/ 查询解析、改写、翻译、embedding
search/ 多语言构建、布尔解析、排序引擎
scripts/ 数据/服务脚本（mock_data, ingest, run 等）
frontend/ 简易调试页面
docs/ 运营及中文资料
常用参考
- 运行/排障：
USAGE_GUIDE.md、环境相关.md - 功能设计：
设计文档.md - 字段/数据对齐：
INDEX_FIELDS_DOCUMENTATION.md - API 对接：
API_DOCUMENTATION.md、API_INTEGRATION_GUIDE.md - 测试数据：
TEST_DATA_GUIDE.md
许可证
专有软件 - 保留所有权利