From 38f530ff071f42c3bae325ebef73eb0080b4e87a Mon Sep 17 00:00:00 2001 From: tangwang Date: Fri, 14 Nov 2025 13:36:14 +0800 Subject: [PATCH] 文档完善 --- .env | 7 ++----- .env.example | 7 ++----- TEST_DATA_GUIDE.md | 481 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ USAGE_GUIDE.md | 441 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ USER_GUIDE.md | 539 ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- docs/店匠相关资料/python-app-demo/main.py | 6 +++--- scripts/import_tenant2_csv.py | 6 +++--- scripts/mock_data.sh | 2 +- user_guide.md | 448 ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- 9 files changed, 933 insertions(+), 1004 deletions(-) create mode 100644 TEST_DATA_GUIDE.md create mode 100644 USAGE_GUIDE.md delete mode 100644 USER_GUIDE.md delete mode 100644 user_guide.md diff --git a/.env b/.env index 78af395..24111f6 100644 --- a/.env +++ b/.env @@ -11,9 +11,6 @@ REDIS_PASSWORD=BMfv5aI31kgHWtlx # DeepL Translation API DEEPL_AUTH_KEY=c9293ab4-ad25-479b-919f-ab4e63b429ed -# Customer Configuration -CUSTOMER_ID=customer1 - # API Service Configuration API_HOST=0.0.0.0 API_PORT=6002 @@ -26,8 +23,8 @@ DB_USERNAME=saas DB_PASSWORD=P89cZHS5d7dFyc9R # Model Directories -TEXT_MODEL_DIR=/data/tw/models/bge-m3 -IMAGE_MODEL_DIR=/data/tw/models/cn-clip +TEXT_MODEL_DIR=/data/tw/models/bge-m3 # 已经改为web请求了，不使用本地模型 +IMAGE_MODEL_DIR=/data/tw/models/cn-clip # 已经改为web请求了，不使用本地模型 # Cache Directory CACHE_DIR=.cache diff --git a/.env.example b/.env.example index 89e9239..b875008 100644 --- a/.env.example +++ b/.env.example @@ -14,16 +14,13 @@ REDIS_PASSWORD= # DeepL Translation API DEEPL_AUTH_KEY= -# Customer Configuration -CUSTOMER_ID=customer1 - # API Service Configuration API_HOST=0.0.0.0 API_PORT=6002 # Embedding Models -TEXT_MODEL_DIR=/data/tw/models/bge-m3 -IMAGE_MODEL_DIR=/data/tw/models/cn-clip +TEXT_MODEL_DIR=/data/tw/models/bge-m3 # 已经改为web请求了，不使用本地模型 +IMAGE_MODEL_DIR=/data/tw/models/cn-clip # 已经改为web请求了，不使用本地模型 # Cache Directory CACHE_DIR=.cache diff --git a/TEST_DATA_GUIDE.md b/TEST_DATA_GUIDE.md new file mode 100644 index 0000000..1744b9b --- /dev/null +++ b/TEST_DATA_GUIDE.md @@ -0,0 +1,481 @@ +# 测试数据构造指南 - SearchEngine + +本文档说明如何构造测试数据，包括两种数据源的准备和导入流程。 + +## 目录 + +1. [数据说明](#数据说明) +2. [构造Mock数据（tenant_id=1）](#构造mock数据tenant_id1) +3. [从CSV导入数据（tenant_id=2）](#从csv导入数据tenant_id2) +4. [从MySQL导入到Elasticsearch](#从mysql导入到elasticsearch) +5. [完整工作流程](#完整工作流程) +6. [常见问题](#常见问题) + +--- + +## 数据说明 + +系统支持两种测试数据源： + +1. **Tenant ID = 1**: 自动生成的Mock数据（使用 `generate_test_data.py` 生成） +2. **Tenant ID = 2**: 从CSV文件导入的真实数据（使用 `import_tenant2_csv.py` 导入） + +### 数据表结构 + +系统使用店匠标准表结构： + +- **SPU表**: `shoplazza_product_spu` - 商品SPU数据 +- **SKU表**: `shoplazza_product_sku` - 商品SKU数据 + +表结构详见 `INDEX_FIELDS_DOCUMENTATION.md`。 + +--- + +## 构造Mock数据（tenant_id=1） + +### 使用一键脚本（推荐） + +`mock_data.sh` 脚本会自动生成并导入 tenant_id=1 的Mock数据： + +```bash +cd /home/tw/SearchEngine +./scripts/mock_data.sh +``` + +脚本会自动： +- 生成 1000 个SPU的Mock数据 +- 导入数据到MySQL +- 自动计算起始ID，避免主键冲突 + +### 手动分步执行 + +如果需要自定义参数，可以分步执行： + +#### 步骤1: 生成Mock测试数据 + +```bash +python scripts/generate_test_data.py \ + --num-spus 1000 \ + --tenant-id "1" \ + --output test_data_tenant1.sql \ + --db-host 120.79.247.228 \ + --db-port 3316 \ + --db-database saas \ + --db-username saas \ + --db-password <密码> +``` + +参数说明： +- `--num-spus`: 生成的SPU数量（默认：1000） +- `--tenant-id`: 租户ID（默认：1） +- `--output`: 输出的SQL文件路径 +- `--db-host`, `--db-port`, `--db-database`, `--db-username`, `--db-password`: 数据库连接信息 + +#### 步骤2: 导入数据到MySQL + +```bash +python scripts/import_test_data.py \ + --db-host 120.79.247.228 \ + --db-port 3316 \ + --db-database saas \ + --db-username saas \ + --db-password <密码> \ + --sql-file test_data_tenant1.sql \ + --tenant-id "1" +``` + +参数说明： +- `--sql-file`: SQL文件路径 +- `--tenant-id`: 租户ID（用于清理旧数据） +- 其他参数：数据库连接信息 + +**注意**: 导入会先清理该 tenant_id 的旧数据，再导入新数据。 + +--- + +## 从CSV导入数据（tenant_id=2） + +### 使用一键脚本（推荐） + +`mock_data.sh` 脚本会自动从CSV文件导入 tenant_id=2 的数据： + +```bash +cd /home/tw/SearchEngine +./scripts/mock_data.sh +``` + +**前提条件**: 确保CSV文件存在于以下路径： +``` +data/customer1/goods_with_pic.5years_congku.csv.shuf.1w +``` + +如果CSV文件路径不同，需要修改 `scripts/mock_data.sh` 中的 `TENANT2_CSV_FILE` 变量。 + +### CSV文件格式要求 + +CSV文件需要包含以下列（列名不区分大小写）： + +- `skuId` - SKU ID +- `name` - 商品名称 +- `name_pinyin` - 拼音（可选） +- `create_time` - 创建时间（格式：YYYY-MM-DD HH:MM:SS） +- `ruSkuName` - 俄文SKU名称（可选） +- `enSpuName` - 英文SPU名称（可选） +- `categoryName` - 类别名称 +- `supplierName` - 供应商名称 +- `brandName` - 品牌名称 +- `file_id` - 文件ID（可选） +- `days_since_last_update` - 更新天数（可选） +- `id` - 商品ID（可选） +- `imageUrl` - 图片URL（可选） + +### 手动分步执行 + +如果需要自定义参数，可以分步执行： + +#### 步骤1: 从CSV生成SQL文件 + +```bash +python scripts/import_tenant2_csv.py \ + --csv-file data/customer1/goods_with_pic.5years_congku.csv.shuf.1w \ + --tenant-id "2" \ + --output customer1_data.sql \ + --db-host 120.79.247.228 \ + --db-port 3316 \ + --db-database saas \ + --db-username saas \ + --db-password <密码> +``` + +参数说明： +- `--csv-file`: CSV文件路径 +- `--tenant-id`: 租户ID（默认：2） +- `--output`: 输出的SQL文件路径 +- 其他参数：数据库连接信息 + +#### 步骤2: 导入数据到MySQL + +```bash +python scripts/import_test_data.py \ + --db-host 120.79.247.228 \ + --db-port 3316 \ + --db-database saas \ + --db-username saas \ + --db-password <密码> \ + --sql-file customer1_data.sql \ + --tenant-id "2" +``` + +**注意**: +- CSV导入会先清理该 tenant_id 的旧数据，再导入新数据 +- 脚本会自动计算起始ID，避免主键冲突 + +--- + +## 从MySQL导入到Elasticsearch + +数据导入到MySQL后，需要使用 `ingest.sh` 脚本将数据从MySQL导入到Elasticsearch。 + +### 基本用法 + +```bash +./scripts/ingest.sh [recreate_index] +``` + +参数说明： +- `tenant_id`: **必需**，租户ID，用于筛选数据库中的数据 +- `recreate_index`: 可选，是否删除并重建索引（true/false，默认：false） + +### 使用示例 + +#### 重建索引并导入数据（推荐首次导入） + +```bash +# 导入tenant_id=1的数据并重建索引 +./scripts/ingest.sh 1 true + +# 导入tenant_id=2的数据并重建索引 +./scripts/ingest.sh 2 true +``` + +#### 增量导入（不重建索引） + +```bash +# 增量导入tenant_id=1的数据 +./scripts/ingest.sh 1 false + +# 增量导入tenant_id=2的数据 +./scripts/ingest.sh 2 false +``` + +### 手动执行 + +如果需要自定义参数，可以手动执行： + +```bash +python scripts/ingest_shoplazza.py \ + --db-host 120.79.247.228 \ + --db-port 3316 \ + --db-database saas \ + --db-username saas \ + --db-password <密码> \ + --tenant-id 1 \ + --es-host http://localhost:9200 \ + --recreate \ + --batch-size 500 +``` + +参数说明： +- `--db-host`, `--db-port`, `--db-database`, `--db-username`, `--db-password`: MySQL连接信息 +- `--tenant-id`: 租户ID（必需） +- `--es-host`: Elasticsearch地址 +- `--recreate`: 是否重建索引 +- `--batch-size`: 批量处理大小（默认：500） + +### 检查可用的 tenant_id + +如果导入时显示 "No documents to index"，脚本会自动显示调试信息，包括： +- 该 tenant_id 的统计信息（总数、活跃数、已删除数） +- 数据库中存在的其他 tenant_id 列表 + +也可以直接查询数据库： + +```sql +-- 查看有哪些 tenant_id +SELECT tenant_id, COUNT(*) as count, + SUM(CASE WHEN deleted = 0 THEN 1 ELSE 0 END) as active +FROM shoplazza_product_spu +GROUP BY tenant_id; + +-- 检查特定 tenant_id 的数据 +SELECT COUNT(*) FROM shoplazza_product_spu +WHERE tenant_id = 2 AND deleted = 0; +``` + +**注意**: +- 只有 `deleted=0` 的记录会被导入 +- 首次运行会下载模型文件（BGE-M3和CN-CLIP），大约需要10-30分钟 +- 确保MySQL中存在对应 tenant_id 的数据 + +--- + +## 完整工作流程 + +### 完整示例：构造并导入所有测试数据 + +```bash +# 1. 构造并导入 tenant_id=1 的Mock数据到MySQL +./scripts/mock_data.sh + +# 脚本会自动完成： +# - 生成 tenant_id=1 的Mock数据（1000个SPU） +# - 从CSV导入 tenant_id=2 的数据 +# - 导入数据到MySQL + +# 2. 从MySQL导入 tenant_id=1 的数据到ES +./scripts/ingest.sh 1 true + +# 3. 从MySQL导入 tenant_id=2 的数据到ES +./scripts/ingest.sh 2 true + +# 4. 验证数据导入 +curl http://localhost:9200/search_products/_count +``` + +### 分步执行示例 + +如果需要更细粒度的控制，可以分步执行： + +```bash +# ===== Part 1: 构造 tenant_id=1 的Mock数据 ===== + +# 1.1 生成Mock数据 +python scripts/generate_test_data.py \ + --num-spus 1000 \ + --tenant-id "1" \ + --output test_data_tenant1.sql \ + --db-host 120.79.247.228 \ + --db-port 3316 \ + --db-database saas \ + --db-username saas \ + --db-password <密码> + +# 1.2 导入到MySQL +python scripts/import_test_data.py \ + --db-host 120.79.247.228 \ + --db-port 3316 \ + --db-database saas \ + --db-username saas \ + --db-password <密码> \ + --sql-file test_data_tenant1.sql \ + --tenant-id "1" + +# ===== Part 2: 从CSV导入 tenant_id=2 的数据 ===== + +# 2.1 从CSV生成SQL +python scripts/import_tenant2_csv.py \ + --csv-file data/customer1/goods_with_pic.5years_congku.csv.shuf.1w \ + --tenant-id "2" \ + --output customer1_data.sql \ + --db-host 120.79.247.228 \ + --db-port 3316 \ + --db-database saas \ + --db-username saas \ + --db-password <密码> + +# 2.2 导入到MySQL +python scripts/import_test_data.py \ + --db-host 120.79.247.228 \ + --db-port 3316 \ + --db-database saas \ + --db-username saas \ + --db-password <密码> \ + --sql-file customer1_data.sql \ + --tenant-id "2" + +# ===== Part 3: 从MySQL导入到ES ===== + +# 3.1 导入 tenant_id=1 的数据到ES +./scripts/ingest.sh 1 true + +# 3.2 导入 tenant_id=2 的数据到ES +./scripts/ingest.sh 2 true + +# ===== Part 4: 验证 ===== + +# 4.1 检查ES中的数据量 +curl http://localhost:9200/search_products/_count + +# 4.2 测试搜索 +curl -X POST http://localhost:6002/search/ \ + -H "Content-Type: application/json" \ + -H "X-Tenant-ID: 1" \ + -d '{"query": "玩具", "size": 10}' +``` + +--- + +## 常见问题 + +### Q1: 数据导入失败 + +**症状**: `Error during data ingestion` + +**解决方案**: +```bash +# 检查MySQL数据是否存在 +mysql -h 120.79.247.228 -P 3316 -u saas -p saas -e \ + "SELECT COUNT(*) FROM shoplazza_product_spu WHERE tenant_id=1" + +# 检查ES索引是否存在 +curl http://localhost:9200/search_products + +# 查看详细错误日志 +python scripts/ingest_shoplazza.py --tenant-id 1 --recreate +``` + +### Q2: CSV文件找不到 + +**症状**: `ERROR: CSV file not found` + +**解决方案**: +```bash +# 检查CSV文件是否存在 +ls -lh data/customer1/goods_with_pic.5years_congku.csv.shuf.1w + +# 如果路径不同，修改 scripts/mock_data.sh 中的 TENANT2_CSV_FILE 变量 +``` + +### Q3: 导入时没有数据 + +**症状**: `WARNING: No documents to index` 或 `Transformed 0 SPU documents` + +**可能原因**: +1. 数据库中不存在该 tenant_id 的数据 +2. 数据都被标记为 `deleted=1` +3. tenant_id 类型不匹配 + +**解决步骤**: + +1. **查看调试信息**: 脚本会自动显示调试信息，包括： + ``` + DEBUG: tenant_id=1000: total=0, active=0, deleted=0 + DEBUG: Available tenant_ids in shoplazza_product_spu: + tenant_id=1: total=100, active=100 + tenant_id=2: total=50, active=50 + ``` + +2. **检查数据库**: 直接查询MySQL确认数据 + ```sql + -- 查看有哪些 tenant_id + SELECT tenant_id, COUNT(*) as count, + SUM(CASE WHEN deleted = 0 THEN 1 ELSE 0 END) as active + FROM shoplazza_product_spu + GROUP BY tenant_id; + + -- 检查特定 tenant_id 的数据 + SELECT COUNT(*) FROM shoplazza_product_spu + WHERE tenant_id = 2 AND deleted = 0; + ``` + +3. **如果数据库中没有数据，需要先导入数据**: + - 如果有CSV文件，使用CSV导入脚本 + - 如果没有CSV文件，可以使用mock数据生成脚本 + +4. **使用正确的 tenant_id**: 根据调试信息显示的可用 tenant_id，使用正确的值重新导入 + ```bash + ./scripts/ingest.sh 2 true # 使用调试信息中显示的 tenant_id + ``` + +### Q4: 模型下载慢或失败 + +**症状**: 首次运行时模型下载很慢或超时 + +**解决方案**: +```bash +# 跳过embedding快速测试（不推荐，但可以快速验证流程） +# 注意：这会导致搜索功能不完整 + +# 或手动下载模型到指定目录 +# TEXT_MODEL_DIR=/data/tw/models/bge-m3 +# IMAGE_MODEL_DIR=/data/tw/models/cn-clip +``` + +### Q5: 内存不足 + +**症状**: `Out of memory` + +**解决方案**: +```bash +# 减少批量大小 +python scripts/ingest_shoplazza.py \ + --tenant-id 1 \ + --batch-size 200 # 默认500，可以减少到100-200 +``` + +### Q6: 主键冲突 + +**症状**: `Duplicate entry` 错误 + +**解决方案**: +- Mock数据脚本会自动计算起始ID，避免冲突 +- 如果仍有冲突，可以手动清理旧数据： + ```sql + DELETE FROM shoplazza_product_spu WHERE tenant_id = 1; + DELETE FROM shoplazza_product_sku WHERE tenant_id = 1; + ``` + +--- + +## 相关文档 + +- **使用文档**: `USAGE_GUIDE.md` - 环境、启动、配置、日志查看 +- **字段说明文档**: `INDEX_FIELDS_DOCUMENTATION.md` - 索引字段详细说明 +- **API接口文档**: `API_INTEGRATION_GUIDE.md` - 完整的API对接指南 +- **README**: `README.md` - 项目概述和快速开始 + +--- + +**文档版本**: v2.0 +**最后更新**: 2024-12 + diff --git a/USAGE_GUIDE.md b/USAGE_GUIDE.md new file mode 100644 index 0000000..8305050 --- /dev/null +++ b/USAGE_GUIDE.md @@ -0,0 +1,441 @@ +# 使用指南 - SearchEngine + +本文档提供完整的使用指南，包括环境准备、服务启动、配置说明、日志查看等。 + +## 目录 + +1. [环境准备](#环境准备) +2. [服务启动](#服务启动) +3. [配置说明](#配置说明) +4. [查看日志](#查看日志) +5. [测试验证](#测试验证) +6. [常见问题](#常见问题) + +--- + +## 环境准备 + +### 系统要求 + +- **操作系统**: Linux (推荐 CentOS 7+ / Ubuntu 18.04+) +- **Python**: 3.8+ +- **内存**: 建议 8GB+ +- **磁盘**: 10GB+ (包含模型文件) +- **Elasticsearch**: 8.x (可通过Docker运行) + +### 安装依赖 + +#### 1. 安装Python依赖 + +```bash +cd /home/tw/SearchEngine +pip install -r requirements.txt +``` + +#### 2. 启动Elasticsearch + +**方式1: 使用Docker（推荐）** + +```bash +docker run -d \ + --name elasticsearch \ + -p 9200:9200 \ + -e "discovery.type=single-node" \ + -e "ES_JAVA_OPTS=-Xms2g -Xmx2g" \ + elasticsearch:8.11.0 +``` + +**方式2: 本地安装** + +参考 [Elasticsearch官方文档](https://www.elastic.co/guide/en/elasticsearch/reference/8.11/install-elasticsearch.html) + +#### 3. 配置环境变量 + +创建 `.env` 文件： + +```bash +# MySQL配置 +DB_HOST=120.79.247.228 +DB_PORT=3316 +DB_DATABASE=saas +DB_USERNAME=saas +DB_PASSWORD=your_password + +# Elasticsearch配置 +ES_HOST=http://localhost:9200 +ES_USERNAME=essa +ES_PASSWORD=4hOaLaf41y2VuI8y + +# Redis配置（可选，用于缓存） +REDIS_HOST=localhost +REDIS_PORT=6479 +REDIS_PASSWORD=BMfv5aI31kgHWtlx + +# DeepL翻译API（可选） +DEEPL_AUTH_KEY=c9293ab4-ad25-479b-919f-ab4e63b429ed + +# API服务配置 +API_HOST=0.0.0.0 +API_PORT=6002 +``` + +--- + +## 服务启动 + +### 方式1: 一键启动（推荐） + +```bash +cd /home/tw/SearchEngine +./run.sh +``` + +这个脚本会自动： +1. 创建日志目录 +2. 启动后端API服务（后台运行） +3. 启动前端Web界面（后台运行） +4. 等待服务就绪 + +启动完成后，访问： +- **前端界面**: http://localhost:6003 +- **后端API**: http://localhost:6002 +- **API文档**: http://localhost:6002/docs + +### 方式2: 分步启动 + +#### 启动后端服务 + +```bash +./scripts/start_backend.sh +``` + +后端API会在 http://localhost:6002 启动 + +#### 启动前端服务 + +```bash +./scripts/start_frontend.sh +``` + +前端界面会在 http://localhost:6003 启动 + +### 方式3: 手动启动 + +#### 启动后端API服务 + +```bash +python -m api.app \ + --host 0.0.0.0 \ + --port 6002 \ + --es-host http://localhost:9200 \ + --reload +``` + +#### 启动前端服务（可选） + +```bash +# 使用Python简单HTTP服务器 +cd frontend +python -m http.server 6003 +``` + +### 停止服务 + +```bash +# 停止后端 +kill $(cat logs/backend.pid) + +# 停止前端 +kill $(cat logs/frontend.pid) + +# 或使用停止脚本 +./scripts/stop.sh +``` + +### 服务端口 + +| 服务 | 端口 | URL | +|------|------|-----| +| Elasticsearch | 9200 | http://localhost:9200 | +| Backend API | 6002 | http://localhost:6002 | +| Frontend Web | 6003 | http://localhost:6003 | +| API Docs | 6002 | http://localhost:6002/docs | + +--- + +## 配置说明 + +### 环境配置文件 (.env) + +主要配置项说明： + +```bash +# Elasticsearch配置 +ES_HOST=http://localhost:9200 +ES_USERNAME=essa +ES_PASSWORD=4hOaLaf41y2VuI8y + +# MySQL配置 +DB_HOST=120.79.247.228 +DB_PORT=3316 +DB_DATABASE=saas +DB_USERNAME=saas +DB_PASSWORD=your_password + +# Redis配置（可选，用于缓存） +REDIS_HOST=localhost +REDIS_PORT=6479 +REDIS_PASSWORD=BMfv5aI31kgHWtlx + +# DeepL翻译API +DEEPL_AUTH_KEY=c9293ab4-ad25-479b-919f-ab4e63b429ed + +# API服务配置 +API_HOST=0.0.0.0 +API_PORT=6002 +``` + +### 修改配置 + +1. 编辑 `.env` 文件 +2. 重启相关服务 + +--- + +## 查看日志 + +### 日志文件位置 + +日志文件存储在 `logs/` 目录下： + +- `logs/backend.log` - 后端服务日志 +- `logs/frontend.log` - 前端服务日志 +- `logs/search_engine.log` - 应用主日志（按天轮转） +- `logs/errors.log` - 错误日志（按天轮转） + +### 查看实时日志 + +```bash +# 查看后端日志 +tail -f logs/backend.log + +# 查看前端日志 +tail -f logs/frontend.log + +# 查看应用主日志 +tail -f logs/search_engine.log + +# 查看错误日志 +tail -f logs/errors.log +``` + +### 日志级别 + +日志级别可以通过环境变量 `LOG_LEVEL` 设置： + +```bash +# 在 .env 文件中设置 +LOG_LEVEL=DEBUG # DEBUG, INFO, WARNING, ERROR, CRITICAL +``` + +### 日志轮转 + +日志文件按天自动轮转，保留30天的历史日志。 + +--- + +## 测试验证 + +### 1. 健康检查 + +```bash +curl http://localhost:6002/admin/health +``` + +**预期响应**: +```json +{ + "status": "healthy", + "elasticsearch": "connected" +} +``` + +### 2. 索引统计 + +```bash +curl http://localhost:6002/admin/stats +``` + +### 3. 简单搜索测试 + +```bash +curl -X POST http://localhost:6002/search/ \ + -H "Content-Type: application/json" \ + -H "X-Tenant-ID: 2" \ + -d '{ + "query": "玩具", + "size": 10 + }' +``` + +或者通过查询参数： + +```bash +curl -X POST "http://localhost:6002/search/?tenant_id=2" \ + -H "Content-Type: application/json" \ + -d '{ + "query": "玩具", + "size": 10 + }' +``` + +### 4. 带过滤器的搜索 + +```bash +curl -X POST http://localhost:6002/search/ \ + -H "Content-Type: application/json" \ + -H "X-Tenant-ID: 2" \ + -d '{ + "query": "玩具", + "size": 10, + "filters": { + "categoryName_keyword": ["玩具", "益智玩具"] + }, + "range_filters": { + "price": {"gte": 50, "lte": 200} + } + }' +``` + +### 5. 分面搜索测试 + +```bash +curl -X POST http://localhost:6002/search/ \ + -H "Content-Type: application/json" \ + -H "X-Tenant-ID: 2" \ + -d '{ + "query": "玩具", + "size": 10, + "facets": [ + {"field": "categoryName_keyword", "size": 15}, + {"field": "brandName_keyword", "size": 15} + ] + }' +``` + +### 6. 图片搜索测试 + +```bash +curl -X POST http://localhost:6002/search/image \ + -H "Content-Type: application/json" \ + -H "X-Tenant-ID: 2" \ + -d '{ + "image_url": "https://oss.essa.cn/example.jpg", + "size": 10 + }' +``` + +### 7. 前端界面测试 + +访问 http://localhost:6003 或 http://localhost:6002/ 进行可视化测试。 + +**注意**: 所有搜索接口都需要通过 `X-Tenant-ID` 请求头或 `tenant_id` 查询参数指定租户ID。 + +--- + +## 常见问题 + +### Q1: MySQL连接失败 + +**症状**: `Failed to connect to MySQL` + +**解决方案**: +```bash +# 检查MySQL服务状态 +mysql -h 120.79.247.228 -P 3316 -u saas -p -e "SELECT 1" + +# 检查配置 +cat .env | grep DB_ +``` + +### Q2: Elasticsearch连接失败 + +**症状**: `Failed to connect to Elasticsearch` + +**解决方案**: +```bash +# 检查ES服务状态 +curl http://localhost:9200 + +# 检查ES版本 +curl http://localhost:9200 | grep version + +# 确认配置 +cat .env | grep ES_ +``` + +### Q3: 服务启动失败 + +**症状**: `Address already in use` 或端口被占用 + +**解决方案**: +```bash +# 查看占用端口的进程 +lsof -i :6002 # 后端 +lsof -i :6003 # 前端 +lsof -i :9200 # ES + +# 杀掉进程 +kill -9 + +# 或修改端口配置 +``` + +### Q4: 搜索无结果 + +**症状**: 搜索返回空结果 + +**解决方案**: +```bash +# 检查ES中是否有数据 +curl http://localhost:9200/search_products/_count + +# 检查tenant_id过滤是否正确 +curl -X POST http://localhost:6002/search/ \ + -H "Content-Type: application/json" \ + -H "X-Tenant-ID: 2" \ + -d '{"query": "*", "size": 10, "debug": true}' +``` + +### Q5: 前端无法连接后端 + +**症状**: CORS错误 + +**解决方案**: +- 确保后端在 http://localhost:6002 运行 +- 检查浏览器控制台错误信息 +- 检查后端日志中的CORS配置 + +### Q6: 翻译不工作 + +**症状**: 翻译返回原文 + +**解决方案**: +- 检查DEEPL_AUTH_KEY是否正确 +- 如果没有API key，系统会使用mock模式（返回原文） + +--- + +## 相关文档 + +- **测试数据构造文档**: `TEST_DATA_GUIDE.md` - 如何构造和导入测试数据 +- **API接口文档**: `API_INTEGRATION_GUIDE.md` - 完整的API对接指南 +- **字段说明文档**: `INDEX_FIELDS_DOCUMENTATION.md` - 索引字段详细说明 +- **设计文档**: `设计文档.md` - 系统架构和设计说明 +- **README**: `README.md` - 项目概述和快速开始 + +--- + +**文档版本**: v2.0 +**最后更新**: 2024-12 + diff --git a/USER_GUIDE.md b/USER_GUIDE.md deleted file mode 100644 index 4e8de6b..0000000 --- a/USER_GUIDE.md +++ /dev/null @@ -1,539 +0,0 @@ -# 使用指南 - SearchEngine - -## 快速启动（推荐） - -### 一键启动所有服务 - -```bash -cd /data/tw/SearchEngine -./start_all.sh -``` - -这个脚本会自动完成： -1. 设置conda环境 -2. 检查并导入测试数据（如果需要） -3. 启动后端API服务（后台运行） -4. 启动前端Web界面 - -启动完成后，访问： -- **前端界面**: http://localhost:6003 -- **后端API**: http://localhost:6002 -- **API文档**: http://localhost:6002/docs - -### 停止服务 - -```bash -# 停止后端 -kill $(cat logs/backend.pid) - -# 前端按 Ctrl+C -``` - ---- - -## 分步启动（自定义） - -### 1. 环境设置 - -```bash -cd /data/tw/SearchEngine -./setup.sh -``` - -这会： -- 创建/激活conda环境 `searchengine` -- 加载配置文件 -- 检查Elasticsearch连接 - -### 2. 数据导入 - -#### 2.1 从MySQL导入到Elasticsearch - -数据导入脚本需要指定 `tenant_id` 参数，用于从MySQL中筛选对应租户的数据。 - -**基本用法**： -```bash -./scripts/ingest.sh [recreate_index] -``` - -参数说明： -- `tenant_id`: **必需**，租户ID，用于筛选数据库中的数据 -- `recreate_index`: 可选，是否删除并重建索引（true/false，默认：false） - -**示例**： - -快速测试（tenant_id=2，重建索引）： -```bash -./scripts/ingest.sh 2 true -``` - -增量导入（tenant_id=2，不重建索引）： -```bash -./scripts/ingest.sh 2 false -``` - -**检查可用的 tenant_id**： - -如果导入时显示 "No documents to index"，脚本会自动显示调试信息，包括： -- 该 tenant_id 的统计信息（总数、活跃数、已删除数） -- 数据库中存在的其他 tenant_id 列表 - -#### 2.2 构造测试数据（Mock Data） - -`mock_data.sh` 脚本用于构造完整的测试数据，包含两部分： - -1. **tenant_id=1**: 自动生成的mock数据（1000条SPU） -2. **tenant_id=2**: 从CSV文件导入的数据（10000条SPU） - -**使用方法**： - -将CSV文件放在 `data/customer1/goods_with_pic.5years_congku.csv.shuf.1w`，然后直接运行： -```bash -./scripts/mock_data.sh -``` - -脚本会自动： -- 生成 tenant_id=1 的mock数据并导入MySQL -- 从CSV文件读取数据，生成 tenant_id=2 的数据并导入MySQL -- 自动计算起始ID，避免主键冲突 - -**注意**： -- 所有配置（数据库地址、CSV路径等）都写死在脚本中，这是测试数据构造脚本，不需要配置化 -- 如果CSV文件路径不同，需要修改 `scripts/mock_data.sh` 中的 `TENANT2_CSV_FILE` 变量 - -**手动分步执行**（如果需要自定义参数）： - -1. **生成SQL文件**： -```bash -python scripts/import_tenant2_csv.py \ - --csv-file data/customer1/goods_with_pic.5years_congku.csv.shuf.1w \ - --tenant-id 2 \ - --output customer1_data.sql \ - --db-host 120.79.247.228 \ - --db-port 3316 \ - --db-database saas \ - --db-username saas \ - --db-password <密码> -``` - -2. **导入SQL到MySQL**： -```bash -python scripts/import_test_data.py \ - --db-host 120.79.247.228 \ - --db-port 3316 \ - --db-database saas \ - --db-username saas \ - --db-password <密码> \ - --sql-file customer1_data.sql \ - --tenant-id 2 -``` - -**CSV文件格式要求**： - -CSV文件需要包含以下列（列名不区分大小写）： -- `skuId` - SKU ID -- `name` - 商品名称 -- `name_pinyin` - 拼音（可选） -- `create_time` - 创建时间（格式：YYYY-MM-DD HH:MM:SS） -- `ruSkuName` - 俄文SKU名称（可选） -- `enSpuName` - 英文SPU名称（可选） -- `categoryName` - 类别名称 -- `supplierName` - 供应商名称 -- `brandName` - 品牌名称 -- `file_id` - 文件ID（可选） -- `days_since_last_update` - 更新天数（可选） -- `id` - 商品ID（可选） -- `imageUrl` - 图片URL（可选） - -**注意**: -- 首次运行会下载模型文件（BGE-M3和CN-CLIP），大约需要10-30分钟 -- 确保MySQL中存在对应 tenant_id 的数据（`shoplazza_product_spu` 和 `shoplazza_product_sku` 表） -- 只有 `deleted=0` 的记录会被导入 -- CSV导入会先清理该 tenant_id 的旧数据，再导入新数据 - -### 3. 启动后端 - -```bash -./scripts/start_backend.sh -``` - -后端API会在 http://localhost:6002 启动 - -### 4. 启动前端 - -```bash -./scripts/start_frontend.sh -``` - -前端界面会在 http://localhost:6003 启动 - ---- - -## 配置说明 - -### 环境配置文件 (.env) - -```bash -# Elasticsearch配置 -ES_HOST=http://localhost:9200 -ES_USERNAME=essa -ES_PASSWORD=4hOaLaf41y2VuI8y - -# Redis配置（可选，用于缓存） -REDIS_HOST=localhost -REDIS_PORT=6479 -REDIS_PASSWORD=BMfv5aI31kgHWtlx - -# DeepL翻译API -DEEPL_AUTH_KEY=c9293ab4-ad25-479b-919f-ab4e63b429ed - -# 客户配置 -TENANT_ID=tenant1 - -# API服务配置 -API_HOST=0.0.0.0 -API_PORT=6002 -``` - -### 修改配置 - -1. 编辑 `.env` 文件 -2. 重启相关服务 - ---- - -## 使用Web界面 - -### 搜索功能 - -1. **简单搜索**: 直接输入关键词 - - 中文: "芭比娃娃" - - 英文: "fire control set" - - 俄文: "Наборы для пожаротушения" - -2. **布尔搜索**: 使用操作符 - - AND: "toy AND barbie" - - OR: "barbie OR doll" - - ANDNOT: "toy ANDNOT cheap" - - 组合: "toy AND (barbie OR doll) ANDNOT cheap" - -3. **域搜索**: 指定搜索域 - - 品牌: "brand:ZHU LIN" - - 类别: "category:玩具" - -### 搜索选项 - -- **启用翻译**: 自动翻译查询到其他语言 -- **启用语义搜索**: 使用embedding进行语义匹配 -- **启用自定义排序**: 使用配置的ranking表达式 -- **结果数量**: 10/20/50条 - ---- - -## API使用 - -### 搜索接口（v3.0 更新） - -**基础搜索**（需要指定 tenant_id）： -```bash -curl -X POST http://localhost:6002/search/ \ - -H "Content-Type: application/json" \ - -H "X-Tenant-ID: 2" \ - -d '{ - "query": "芭比娃娃", - "size": 20 - }' -``` - -或者通过查询参数： -```bash -curl -X POST "http://localhost:6002/search/?tenant_id=2" \ - -H "Content-Type: application/json" \ - -d '{ - "query": "芭比娃娃", - "size": 20 - }' -``` - -**带过滤器的搜索**： -```bash -curl -X POST http://localhost:6002/search/ \ - -H "Content-Type: application/json" \ - -H "X-Tenant-ID: 2" \ - -d '{ - "query": "玩具", - "size": 20, - "filters": { - "categoryName_keyword": ["玩具", "益智玩具"] - }, - "range_filters": { - "price": {"gte": 50, "lte": 200} - } - }' -``` - -**带分面搜索**： -```bash -curl -X POST http://localhost:6002/search/ \ - -H "Content-Type: application/json" \ - -H "X-Tenant-ID: 2" \ - -d '{ - "query": "玩具", - "size": 20, - "facets": [ - {"field": "categoryName_keyword", "size": 15}, - {"field": "brandName_keyword", "size": 15} - ] - }' -``` - -### 图片搜索 - -```bash -curl -X POST http://localhost:6002/search/image \ - -H "Content-Type: application/json" \ - -H "X-Tenant-ID: 2" \ - -d '{ - "image_url": "https://oss.essa.cn/example.jpg", - "size": 10 - }' -``` - -**注意**: 所有搜索接口都需要通过 `X-Tenant-ID` 请求头或 `tenant_id` 查询参数指定租户ID。 - -### 健康检查 - -```bash -curl http://localhost:6002/admin/health -``` - -### 查看配置 - -```bash -curl http://localhost:6002/admin/config -``` - -### 索引统计 - -```bash -curl http://localhost:6002/admin/stats -``` - ---- - -## 常见问题 - -### 1. Elasticsearch连接失败 - -**问题**: `Failed to connect to Elasticsearch` - -**解决**: -```bash -# 检查ES是否运行 -curl http://localhost:9200 - -# 检查配置 -cat .env | grep ES_ -``` - -### 2. 导入数据时内存不足 - -**问题**: `Out of memory` - -**解决**: -```bash -# 减少batch size或跳过embedding -./scripts/ingest.sh 1000 true -``` - -### 3. 模型下载失败 - -**问题**: 模型文件下载超时 - -**解决**: -- 检查网络连接 -- 使用国内镜像源 -- 手动下载模型到指定目录 - -### 4. 翻译不工作 - -**问题**: 翻译返回原文 - -**解决**: -- 检查DEEPL_AUTH_KEY是否正确 -- 如果没有API key，系统会使用mock模式（返回原文） - -### 5. 前端无法连接后端 - -**问题**: CORS错误 - -**解决**: -- 确保后端在 http://localhost:6002 运行 -- 检查浏览器控制台错误信息 - -### 6. 数据导入时没有数据 - -**问题**: `WARNING: No documents to index` 或 `Transformed 0 SPU documents` - -**可能原因**: -1. 数据库中不存在该 tenant_id 的数据 -2. 数据都被标记为 `deleted=1` -3. tenant_id 类型不匹配 - -**解决步骤**: - -1. **查看调试信息**: 脚本会自动显示调试信息，包括： - ``` - DEBUG: tenant_id=1000: total=0, active=0, deleted=0 - DEBUG: Available tenant_ids in shoplazza_product_spu: - tenant_id=1: total=100, active=100 - tenant_id=2: total=50, active=50 - ``` - -2. **检查数据库**: 直接查询MySQL确认数据 - ```sql - -- 查看有哪些 tenant_id - SELECT tenant_id, COUNT(*) as count, - SUM(CASE WHEN deleted = 0 THEN 1 ELSE 0 END) as active - FROM shoplazza_product_spu - GROUP BY tenant_id; - - -- 检查特定 tenant_id 的数据 - SELECT COUNT(*) FROM shoplazza_product_spu - WHERE tenant_id = 1000 AND deleted = 0; - ``` - -3. **如果数据库中没有数据，需要先导入数据**: - - 如果有CSV文件，使用CSV导入脚本（见"2.2 从CSV导入数据到MySQL"） - - 如果没有CSV文件，可以使用mock数据生成脚本 - -4. **使用正确的 tenant_id**: 根据调试信息显示的可用 tenant_id，使用正确的值重新导入 - ```bash - ./scripts/ingest.sh 2 true # 使用调试信息中显示的 tenant_id - ``` - ---- - -## 开发和调试 - -### 查看日志 - -```bash -# 后端日志 -tail -f logs/backend.log - -# 实时日志（如果前台运行） -./scripts/start_backend.sh -``` - -### Python命令行测试 - -```bash -# 激活环境 -source /home/tw/miniconda3/etc/profile.d/conda.sh -conda activate searchengine - -# 测试搜索（需要指定 tenant_id） -python -c " -from config import ConfigLoader -from utils.es_client import ESClient -from search.searcher import Searcher -from config.env_config import ES_CONFIG - -config_loader = ConfigLoader('config/config.yaml') -config = config_loader.load_config() - -es_client = ESClient(hosts=[ES_CONFIG['host']], - username=ES_CONFIG.get('username'), - password=ES_CONFIG.get('password')) - -searcher = Searcher(config, es_client) -result = searcher.search('芭比娃娃', tenant_id='2', size=5) - -print(f'找到 {result.total} 个结果') -for hit in result.hits: - print(f' - {hit[\"title\"]} (分数: {hit[\"_score\"]:.4f})') -" -``` - -### 重新导入数据 - -```bash -# 删除现有索引并重新导入（需要指定 tenant_id） -./scripts/ingest.sh true - -# 例如：导入 tenant_id=2 的数据并重建索引 -./scripts/ingest.sh 2 true -``` - -### 检查数据库中的 tenant_id - -如果不知道应该使用哪个 tenant_id，可以： - -1. **运行导入脚本查看调试信息**（即使没有数据也会显示）: - ```bash - ./scripts/ingest.sh 999 true - ``` - 脚本会显示数据库中存在的 tenant_id 列表 - -2. **直接查询数据库**: - ```bash - mysql -h 120.79.247.228 -P 3316 -u saas -p saas -e \ - "SELECT tenant_id, COUNT(*) as count FROM shoplazza_product_spu GROUP BY tenant_id;" -``` - ---- - -## 性能优化 - -### 1. 使用embedding缓存 - -首次生成embedding后会自动缓存到 `.cache/` 目录，后续导入会更快。 - -### 2. 批量大小调整 - -```bash -# 修改批量大小（在ingest_tenant1.py中） ---batch-size 200 # 默认100 -``` - -### 3. GPU加速 - -确保CUDA可用以加速embedding生成： -```bash -python -c "import torch; print(f'CUDA available: {torch.cuda.is_available()}')" -``` - ---- - -## 项目结构 - -``` -SearchEngine/ -├── .env # 环境配置 -├── setup.sh # 环境设置脚本 -├── start_all.sh # 一键启动脚本 -├── scripts/ # 运行脚本 -│ ├── ingest.sh # 数据导入 -│ ├── start_backend.sh # 启动后端 -│ └── start_frontend.sh # 启动前端 -├── frontend/ # Web前端 -│ ├── index.html -│ └── static/ -├── logs/ # 日志文件 -├── config/ # 配置模块 -├── indexer/ # 数据导入 -├── query/ # 查询处理 -├── search/ # 搜索引擎 -├── embeddings/ # 向量模型 -└── api/ # REST API -``` - ---- - -## 支持 - -遇到问题请查看： -- **日志**: `logs/backend.log` -- **API文档**: http://localhost:6002/docs -- **配置**: `config/schema/tenant1_config.yaml` diff --git a/docs/店匠相关资料/python-app-demo/main.py b/docs/店匠相关资料/python-app-demo/main.py index 654ddef..ee50289 100644 --- a/docs/店匠相关资料/python-app-demo/main.py +++ b/docs/店匠相关资料/python-app-demo/main.py @@ -69,7 +69,7 @@ def auth(): if not shop: return jsonify({"error": "shop parameter is required"}), 400 - scopes = "read_customer" + scopes = "read_tenant" state = secrets.token_hex(16) # 生成随机state auth_url = ( @@ -117,8 +117,8 @@ def auth_callback(): # 这里可以调用Shoplazza OpenAPI获取更多数据 # headers = {"Access-Token": token_data.get("access_token")} - # customers_url = f"https://{shop}/openapi/2022-01/customers" - # customers_response = requests.get(customers_url, headers=headers) + # tenants_url = f"https://{shop}/openapi/2022-01/tenants" + # tenants_response = requests.get(tenants_url, headers=headers) # return redirect(LAST_URL) except requests.exceptions.RequestException as e: diff --git a/scripts/import_tenant2_csv.py b/scripts/import_tenant2_csv.py index d137fd3..063dd77 100755 --- a/scripts/import_tenant2_csv.py +++ b/scripts/import_tenant2_csv.py @@ -303,7 +303,7 @@ def generate_sql_inserts(spus: list, skus: list, output_file: str): output_file: Output file path """ with open(output_file, 'w', encoding='utf-8') as f: - f.write("-- SPU Data from customer1 CSV\n") + f.write("-- SPU Data from tenant2 CSV\n") f.write("INSERT INTO shoplazza_product_spu (\n") f.write(" id, shop_id, shoplazza_id, handle, title, brief, description, spu,\n") f.write(" vendor, vendor_url, seo_title, seo_description, seo_keywords,\n") @@ -345,7 +345,7 @@ def generate_sql_inserts(spus: list, skus: list, output_file: str): else: f.write(";\n\n") - f.write("-- SKU Data from customer1 CSV\n") + f.write("-- SKU Data from tenant2 CSV\n") f.write("INSERT INTO shoplazza_product_sku (\n") f.write(" id, spu_id, shop_id, shoplazza_id, shoplazza_product_id, shoplazza_image_id,\n") f.write(" title, sku, barcode, position, price, compare_at_price, cost_price,\n") @@ -425,7 +425,7 @@ def main(): parser.add_argument('--csv-file', required=True, help='CSV file path') parser.add_argument('--tenant-id', default='2', help='Tenant ID (default: 2)') parser.add_argument('--start-spu-id', type=int, default=None, help='Starting SPU ID (default: auto-calculate from DB)') - parser.add_argument('--output', default='customer1_data.sql', help='Output SQL file (default: customer1_data.sql)') + parser.add_argument('--output', default='tenant2_data.sql', help='Output SQL file (default: tenant2_data.sql)') parser.add_argument('--db-host', help='Database host (for auto-calculating start IDs)') parser.add_argument('--db-port', type=int, default=3306, help='Database port (default: 3306)') parser.add_argument('--db-database', help='Database name (for auto-calculating start IDs)') diff --git a/scripts/mock_data.sh b/scripts/mock_data.sh index 7c2bf65..1184447 100755 --- a/scripts/mock_data.sh +++ b/scripts/mock_data.sh @@ -121,7 +121,7 @@ echo -e "\n${YELLOW}========================================${NC}" echo -e "${YELLOW}Part 2/2: 生成并导入 tenant_id=2 的CSV数据${NC}" echo -e "${YELLOW}========================================${NC}" -TENANT2_SQL_FILE="customer1_data.sql" +TENANT2_SQL_FILE="tenant2_data.sql" echo -e "\n${YELLOW}Step 2.1: 从CSV生成数据${NC}" python scripts/import_tenant2_csv.py \ diff --git a/user_guide.md b/user_guide.md deleted file mode 100644 index 46db384..0000000 --- a/user_guide.md +++ /dev/null @@ -1,448 +0,0 @@ -# 使用指南 - -本文档提供完整的使用指南，包括环境准备、数据导入、服务启动、测试等。 - -## 目录 - -1. [环境准备](#环境准备) -2. [数据准备](#数据准备) -3. [数据导入](#数据导入) -4. [服务启动](#服务启动) -5. [测试验证](#测试验证) -6. [常见问题](#常见问题) - ---- - -## 环境准备 - -### 系统要求 - -- **操作系统**: Linux (推荐 CentOS 7+ / Ubuntu 18.04+) -- **Python**: 3.8+ -- **内存**: 建议 8GB+ -- **磁盘**: 10GB+ (包含模型文件) -- **Elasticsearch**: 8.x (可通过Docker运行) - -### 安装依赖 - -#### 1. 安装Python依赖 - -```bash -cd /home/tw/SearchEngine -pip install -r requirements.txt -``` - -#### 2. 启动Elasticsearch - -**方式1: 使用Docker（推荐）** - -```bash -docker run -d \ - --name elasticsearch \ - -p 9200:9200 \ - -e "discovery.type=single-node" \ - -e "ES_JAVA_OPTS=-Xms2g -Xmx2g" \ - elasticsearch:8.11.0 -``` - -**方式2: 本地安装** - -参考 [Elasticsearch官方文档](https://www.elastic.co/guide/en/elasticsearch/reference/8.11/install-elasticsearch.html) - -#### 3. 配置环境变量（可选） - -创建 `.env` 文件： - -```bash -# MySQL配置 -DB_HOST=120.79.247.228 -DB_PORT=3316 -DB_DATABASE=saas -DB_USERNAME=saas -DB_PASSWORD=your_password - -# Elasticsearch配置 -ES_HOST=http://localhost:9200 - -# DeepL翻译API（可选） -DEEPL_AUTH_KEY=your_deepl_api_key -``` - ---- - -## 数据准备 - -### Mock数据说明 - -项目提供了两套写死的Mock数据，用于测试： - -1. **Tenant ID = 1**: 生成的Mock数据（100个SPU） -2. **Tenant ID = 2**: 从CSV导入的真实数据 - -### 数据表结构 - -系统使用店匠标准表结构： - -- **SPU表**: `shoplazza_product_spu` - 商品SPU数据 -- **SKU表**: `shoplazza_product_sku` - 商品SKU数据 - -表结构详见 `INDEX_FIELDS_DOCUMENTATION.md`。 - ---- - -## 数据导入 - -### 步骤1: 导入Mock数据到MySQL - -#### 方式1: 使用脚本（推荐） - -```bash -# 导入tenant_id=1的Mock数据（默认100个SPU） -./scripts/mock_data.sh - -# 指定tenant_id和SPU数量 -./scripts/mock_data.sh 1 200 - -# 使用显式参数 -./scripts/mock_data.sh --mode mock --tenant-id 1 --num-spus 200 -``` - -#### 方式2: 导入CSV数据（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: 手动导入SQL - -```bash -# 导入tenant_id=1的测试数据 -mysql -h 120.79.247.228 -P 3316 -u saas -p saas < test_data_tenant1.sql - -# 导入tenant_id=2的CSV数据 -mysql -h 120.79.247.228 -P 3316 -u saas -p saas < customer1_data.sql -``` - -### 步骤2: 从MySQL导入数据到Elasticsearch - -#### 使用脚本（推荐） - -```bash -# 导入tenant_id=1的数据 -./scripts/ingest.sh 1 - -# 重建索引并导入数据 -./scripts/ingest.sh 1 true - -# 导入tenant_id=2的数据 -./scripts/ingest.sh 2 -``` - -#### 手动执行 - -```bash -python scripts/ingest_shoplazza.py \ - --db-host 120.79.247.228 \ - --db-port 3316 \ - --db-database saas \ - --db-username saas \ - --db-password your_password \ - --tenant-id 1 \ - --config base \ - --es-host http://localhost:9200 \ - --recreate \ - --batch-size 500 -``` - -### 完整工作流程示例 - -```bash -# 1. 导入tenant_id=1的Mock数据（100个SPU） -./scripts/mock_data.sh 1 100 - -# 2. 导入tenant_id=2的CSV数据 -./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. 验证数据导入 -curl http://localhost:9200/search_products/_count -``` - ---- - -## 服务启动 - -### 方式1: 使用启动脚本（推荐） - -```bash -# 启动前端和后端服务 -./run.sh - -# 重启所有服务 -./restart.sh -``` - -### 方式2: 手动启动 - -#### 启动后端API服务 - -```bash -python -m api.app \ - --host 0.0.0.0 \ - --port 6002 \ - --es-host http://localhost:9200 \ - --reload -``` - -#### 启动前端服务（可选） - -```bash -# 使用Python简单HTTP服务器 -cd frontend -python -m http.server 6003 -``` - -### 服务端口 - -| 服务 | 端口 | URL | -|------|------|-----| -| Elasticsearch | 9200 | http://localhost:9200 | -| Backend API | 6002 | http://localhost:6002 | -| Frontend Web | 6003 | http://localhost:6003 | -| API Docs | 6002 | http://localhost:6002/docs | - ---- - -## 测试验证 - -### 1. 健康检查 - -```bash -curl http://localhost:6002/admin/health -``` - -**预期响应**: -```json -{ - "status": "healthy", - "elasticsearch": "connected" -} -``` - -### 2. 索引统计 - -```bash -curl http://localhost:6002/admin/stats -``` - -### 3. 简单搜索测试 - -```bash -curl -X POST http://localhost:6002/search/ \ - -H "Content-Type: application/json" \ - -d '{ - "query": "玩具", - "size": 10 - }' -``` - -### 4. 带过滤器的搜索 - -```bash -curl -X POST http://localhost:6002/search/ \ - -H "Content-Type: application/json" \ - -d '{ - "query": "玩具", - "size": 10, - "filters": { - "category_keyword": "益智玩具" - }, - "range_filters": { - "min_price": { - "gte": 50, - "lte": 200 - } - } - }' -``` - -### 5. 分面搜索测试 - -```bash -curl -X POST http://localhost:6002/search/ \ - -H "Content-Type: application/json" \ - -d '{ - "query": "玩具", - "size": 10, - "facets": [ - "category_keyword", - "vendor_keyword" - ] - }' -``` - -### 6. 布尔表达式搜索 - -```bash -curl -X POST http://localhost:6002/search/ \ - -H "Content-Type: application/json" \ - -d '{ - "query": "玩具 AND (乐高 OR 芭比)", - "size": 10 - }' -``` - -### 7. 图片搜索测试 - -```bash -curl -X POST http://localhost:6002/search/image \ - -H "Content-Type: application/json" \ - -d '{ - "image_url": "https://example.com/image.jpg", - "size": 10 - }' -``` - -### 8. 前端界面测试 - -访问 http://localhost:6003 或 http://localhost:6002/ 进行可视化测试。 - ---- - -## 常见问题 - -### Q1: MySQL连接失败 - -**症状**: `Failed to connect to MySQL` - -**解决方案**: -```bash -# 检查MySQL服务状态 -mysql -h 120.79.247.228 -P 3316 -u saas -p -e "SELECT 1" - -# 检查配置 -cat .env | grep DB_ -``` - -### Q2: Elasticsearch连接失败 - -**症状**: `Failed to connect to Elasticsearch` - -**解决方案**: -```bash -# 检查ES服务状态 -curl http://localhost:9200 - -# 检查ES版本 -curl http://localhost:9200 | grep version - -# 确认配置 -cat .env | grep ES_ -``` - -### Q3: 数据导入失败 - -**症状**: `Error during data ingestion` - -**解决方案**: -```bash -# 检查MySQL数据是否存在 -mysql -h 120.79.247.228 -P 3316 -u saas -p saas -e "SELECT COUNT(*) FROM shoplazza_product_spu WHERE tenant_id=1" - -# 检查ES索引是否存在 -curl http://localhost:9200/search_products - -# 查看详细错误日志 -python scripts/ingest_shoplazza.py --tenant-id 1 --recreate -``` - -### Q4: 服务启动失败 - -**症状**: `Address already in use` 或端口被占用 - -**解决方案**: -```bash -# 查看占用端口的进程 -lsof -i :6002 # 后端 -lsof -i :6003 # 前端 -lsof -i :9200 # ES - -# 杀掉进程 -kill -9 - -# 或修改端口配置 -``` - -### Q5: 模型下载慢或失败 - -**症状**: 首次运行时模型下载很慢或超时 - -**解决方案**: -```bash -# 跳过embedding快速测试 -./scripts/ingest.sh 1 true - -# 或手动下载模型到指定目录 -# TEXT_MODEL_DIR=/data/tw/models/bge-m3 -# IMAGE_MODEL_DIR=/data/tw/models/cn-clip -``` - -### Q6: 搜索无结果 - -**症状**: 搜索返回空结果 - -**解决方案**: -```bash -# 检查ES中是否有数据 -curl http://localhost:9200/search_products/_count - -# 检查tenant_id过滤是否正确 -curl -X POST http://localhost:6002/search/ \ - -H "Content-Type: application/json" \ - -d '{"query": "*", "size": 10, "debug": true}' - -# 查看调试信息 -``` - -### Q7: 向量计算很慢 - -**症状**: 生成embedding很慢 - -**解决方案**: -- 使用GPU加速（如果可用） -- 减少批量大小 -- 启用向量缓存 -- 首次导入时跳过embedding，后续再生成 - ---- - -## 下一步 - -1. **查看API文档**: 参考 `API_INTEGRATION_GUIDE.md` 了解完整的API接口 -2. **查看字段说明**: 参考 `INDEX_FIELDS_DOCUMENTATION.md` 了解索引字段 -3. **查看设计文档**: 参考 `设计文档.md` 了解系统架构 -4. **自定义配置**: 编辑 `config/config.yaml` 调整搜索配置 - ---- - -## 相关文档 - -- **API接口文档**: `API_INTEGRATION_GUIDE.md` - 完整的API对接指南 -- **字段说明文档**: `INDEX_FIELDS_DOCUMENTATION.md` - 索引字段详细说明 -- **设计文档**: `设计文档.md` - 系统架构和设计说明 -- **README**: `README.md` - 项目概述和快速开始 - ---- - -**文档版本**: v1.0 -**最后更新**: 2024-12 - -- libgit2 0.21.2