# 使用指南 - 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使用

### 搜索接口（v3.0 更新）

**基础搜索**：
```bash
curl -X POST http://localhost:6002/search/ \
  -H "Content-Type: application/json" \
  -d '{
    "query": "芭比娃娃",
    "size": 20
  }'
```

**带过滤器的搜索**：
```bash
curl -X POST http://localhost:6002/search/ \
  -H "Content-Type: application/json" \
  -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" \
  -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" \
  -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`