tangwang / SearchEngine

TEST_DATA_GUIDE.md 12 KB

测试数据构造指南 - SearchEngine

本文档说明如何构造测试数据，包括两种数据源的准备和导入流程。

目录

  1. 数据说明
  2. 构造Mock数据（tenant_id=1）
  3. 从CSV导入数据（tenant_id=2）
  4. 从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数据：

cd /home/tw/SearchEngine
./scripts/mock_data.sh

脚本会自动：

  • 生成 1000 个SPU的Mock数据
  • 导入数据到MySQL
  • 自动计算起始ID，避免主键冲突

手动分步执行

如果需要自定义参数，可以分步执行：

步骤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 <密码>

参数说明：

  • --num-spus: 生成的SPU数量（默认：1000）
  • --tenant-id: 租户ID（默认：1）
  • --output: 输出的SQL文件路径
  • --db-host, --db-port, --db-database, --db-username, --db-password: 数据库连接信息

步骤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"

参数说明：

  • --sql-file: SQL文件路径
  • --tenant-id: 租户ID（用于清理旧数据）
  • 其他参数：数据库连接信息

注意: 导入会先清理该 tenant_id 的旧数据，再导入新数据。

从CSV导入数据（tenant_id=2）

使用一键脚本（推荐）

mock_data.sh 脚本会自动从CSV文件导入 tenant_id=2 的数据：

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文件

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

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。

基本用法

./scripts/ingest.sh <tenant_id> [recreate_index]

参数说明：

  • tenant_id: 必需，租户ID，用于筛选数据库中的数据
  • recreate_index: 可选，是否删除并重建索引（true/false，默认：false）

使用示例

重建索引并导入数据（推荐首次导入）

# 导入tenant_id=1的数据并重建索引
./scripts/ingest.sh 1 true

# 导入tenant_id=2的数据并重建索引
./scripts/ingest.sh 2 true

增量导入（不重建索引）

# 增量导入tenant_id=1的数据
./scripts/ingest.sh 1 false

# 增量导入tenant_id=2的数据
./scripts/ingest.sh 2 false

手动执行

如果需要自定义参数，可以手动执行：

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 列表

也可以直接查询数据库：

-- 查看有哪些 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 的数据

完整工作流程

完整示例：构造并导入所有测试数据

# 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

分步执行示例

如果需要更细粒度的控制，可以分步执行：

# ===== 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

解决方案:

# 检查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

解决方案:

# 检查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确认数据

    -- 查看有哪些 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: 模型下载慢或失败

症状: 首次运行时模型下载很慢或超时

解决方案:

# 跳过embedding快速测试（不推荐，但可以快速验证流程）
# 注意：这会导致搜索功能不完整

# 或手动下载模型到指定目录
# TEXT_MODEL_DIR=/data/tw/models/bge-m3
# IMAGE_MODEL_DIR=/data/tw/models/cn-clip

Q5: 内存不足

症状: Out of memory

解决方案:

# 减少批量大小
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