# 使用指南 - 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. 数据导入
  
  #### 快速测试（1000条，不生成embedding）
  ```bash
  ./scripts/ingest.sh 1000 true
  ```
  
  #### 完整导入（10000条，包含embedding）
  ```bash
  ./scripts/ingest.sh 10000 false
  ```
  
  **注意**: 首次运行会下载模型文件（BGE-M3和CN-CLIP），大约需要10-30分钟。
  
  ### 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
  
  # 客户配置
  CUSTOMER_ID=customer1
  
  # 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使用
  
  ### 搜索接口
  
  ```bash

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

    -H "Content-Type: application/json" \
    -d '{
      "query": "芭比娃娃",
      "size": 10,
      "enable_translation": true,
      "enable_embedding": true
    }'
  ```
  
  ### 图片搜索
  
  ```bash

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

    -H "Content-Type: application/json" \
    -d '{
      "image_url": "https://oss.essa.cn/example.jpg",
      "size": 10
    }'
  ```
  
  ### 健康检查
  
  ```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 运行

  - 检查浏览器控制台错误信息
  
  ---
  
  ## 开发和调试
  
  ### 查看日志
  
  ```bash
  # 后端日志
  tail -f logs/backend.log
  
  # 实时日志（如果前台运行）
  ./scripts/start_backend.sh
  ```
  
  ### Python命令行测试
  
  ```bash
  # 激活环境
  source /home/tw/miniconda3/etc/profile.d/conda.sh
  conda activate searchengine
  
  # 测试搜索
  python -c "
  from config import ConfigLoader
  from utils import ESClient
  from search import Searcher
  from config.env_config import get_es_config
  
  config_loader = ConfigLoader('config/schema')
  config = config_loader.load_customer_config('customer1')
  
  es_config = get_es_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('芭比娃娃', size=5)
  
  print(f'找到 {result.total} 个结果')
  for hit in result.hits:
      print(f'  - {hit[\"_source\"][\"name\"]} (分数: {hit[\"_score\"]:.4f})')
  "
  ```
  
  ### 重新导入数据
  
  ```bash
  # 删除现有索引并重新导入
  ./scripts/ingest.sh 1000 true
  ```
  
  ---
  
  ## 性能优化
  
  ### 1. 使用embedding缓存
  
  首次生成embedding后会自动缓存到 `.cache/` 目录，后续导入会更快。
  
  ### 2. 批量大小调整
  
  ```bash
  # 修改批量大小（在ingest_customer1.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/customer1_config.yaml`