# 开发者快速上手

新人入口文档：环境、服务、模块、请求示例一页搞定。

**建议**：首次参与开发请先阅读 [DEVELOPER_GUIDE.md](./DEVELOPER_GUIDE.md) 建立项目全貌与规范，再使用本页做环境与请求速查。

## 1. 环境

```bash
source activate.sh
# 首次：./scripts/create_venv.sh 或 conda env create -f environment.yml
```

依赖：Python 3.8+、Elasticsearch 8.x、MySQL、Redis（可选）。详见 `docs/环境配置说明.md`。

## 2. 服务与端口

| 服务 | 端口 | 默认启动 | 说明 |
|------|-----:|:--------:|------|
| backend | 6002 | ✓ | 搜索 API |
| indexer | 6004 | ✓ | 索引 API |
| frontend | 6003 | ✓ | 调试 UI |
| embedding | 6005 | - | 向量服务 |
| translator | 6006 | - | 翻译服务 |
| reranker | 6007 | - | 重排服务 |

```bash
./run.sh
# 全功能：START_EMBEDDING=1 START_TRANSLATOR=1 START_RERANKER=1 ./run.sh
./scripts/service_ctl.sh status
./scripts/stop.sh
```

## 3. 模块与请求

### 3.1 搜索 API（backend 6002）

```bash
# 文本搜索
curl -X POST http://localhost:6002/search/ \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: 162" \
  -d '{"query": "玩具", "size": 10}'

# 图片搜索
curl -X POST http://localhost:6002/search/image \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: 162" \
  -d '{"image_url": "https://example.com/img.jpg", "size": 10}'

# 建议
curl "http://localhost:6002/search/suggestions?q=玩&size=5" -H "X-Tenant-ID: 162"
```

API 文档：http://localhost:6002/docs

### 3.2 索引 API（indexer 6004）

```bash
# 创建租户索引
./scripts/create_tenant_index.sh 162

# 全量索引
curl -X POST http://localhost:6004/indexer/reindex \
  -H "Content-Type: application/json" \
  -d '{"tenant_id": "162", "batch_size": 500}'

# 构建文档（不写 ES，供上游调用）
curl -X POST http://localhost:6004/indexer/build-docs \
  -H "Content-Type: application/json" \
  -d '{"tenant_id": "162", "items": [{"spu": {...}, "skus": [...], "options": [...]}]}'
```

### 3.3 向量服务（embedding 6005）

```bash
./scripts/start_embedding_service.sh

# 文本向量
curl -X POST http://localhost:6005/embed/text \
  -H "Content-Type: application/json" \
  -d '["衣服", "Bohemian Maxi Dress"]'

# 图片向量（URL 列表）
curl -X POST http://localhost:6005/embed/image \
  -H "Content-Type: application/json" \
  -d '["https://example.com/img.jpg"]'
```

### 3.4 翻译服务（translator 6006）

```bash
./scripts/start_translator.sh

curl -X POST http://localhost:6006/translate \
  -H "Content-Type: application/json" \
  -d '{"text": "商品名称", "target_lang": "en", "source_lang": "zh"}'
```

### 3.5 重排服务（reranker 6007）

```bash
./scripts/start_reranker.sh

curl -X POST http://localhost:6007/rerank \
  -H "Content-Type: application/json" \
  -d '{"query": "wireless mouse", "docs": ["logitech mx master", "usb cable"]}'
```

## 4. 配置

- **主配置**：`config/config.yaml`（搜索行为、字段权重、分面等）
- **服务 provider**：`config/config.yaml` 的 `services` 块（翻译/向量/重排的 provider 与 URL）
- **环境变量**：`.env`（DB、ES、Redis、API Key 等）

## 5. 延伸阅读

| 文档 | 用途 |
|------|------|
| `docs/Usage-Guide.md` | 运维：日志、多环境、故障排查 |
| `docs/搜索API速查表.md` | 搜索 API 参数速查 |
| `docs/搜索API对接指南.md` | 搜索 API 完整说明 |
| `docs/PROVIDER_ARCHITECTURE.md` | 翻译/向量/重排 provider 扩展 |
| `indexer/README.md` | 索引模块职责与接口 |