# 开发与配置指南

新人入口：环境、服务、模块、请求示例、基础配置、Provider 架构、模块扩展规范，一文档搞定。

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

---

## 为什么这样整合

本文已合并并替代以下文档中的核心内容：

- `docs/PROVIDER_ARCHITECTURE.md`
- `docs/MODULE_EXTENSION_SPEC.md`
- `docs/基础配置指南.md`
- 原 `docs/QUICKSTART.md`

关于 `docs/Usage-Guide.md`：保留为**运行/运维手册**更清晰（日志、故障排查、多环境切换、建议索引运行细节），本文只保留开发常用且高频的信息，避免一个文档同时承担“开发规范 + 运维 runbook”导致冗长和混乱。

---

## 目录

1. [快速上手](#1-快速上手)
2. [基础配置与搜索行为](#2-基础配置与搜索行为)
3. [Provider 架构](#3-provider-架构)
4. [模块扩展规范（Embedding / Rerank）](#4-模块扩展规范embedding--rerank)
5. [验证、日志与常见排障入口](#5-验证日志与常见排障入口)
6. [相关文档](#6-相关文档)
7. [持续集成测试（最小可维护方案）](#7-持续集成测试最小可维护方案)

---

## 1. 快速上手

### 1.1 环境准备

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

依赖：Python 3.8+、Elasticsearch 8.x、MySQL、Redis（可选，缓存用途）。

如果需要本地运行 embedding 模型（torch/transformers 等重依赖）：

```bash
INSTALL_ML=1 ./scripts/create_venv.sh
source activate.sh
```

详细环境说明见 `docs/环境配置说明.md`。

### 1.2 服务与端口

| 服务 | 端口 | 默认启动 | 说明 |
|------|-----:|:--------:|------|
| backend | 6002 | ✓ | 搜索 API（`/search/*`）+ 管理接口（`/admin/*`） |
| indexer | 6004 | ✓ | 索引 API（`/indexer/*`） |
| frontend | 6003 | ✓ | 调试 UI |
| embedding | 6005 | - | 向量服务（`/embed/text`, `/embed/image`） |
| translator | 6006 | - | 翻译服务（`/translate`） |
| reranker | 6007 | - | 重排服务（`/rerank`） |

启动与停止：

```bash
./run.sh
# 启动全部能力
START_EMBEDDING=1 START_TRANSLATOR=1 START_RERANKER=1 ./run.sh

./scripts/service_ctl.sh status
./scripts/stop.sh
```

### 1.3 常用 API 请求示例

#### 搜索 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}'

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

# 健康与统计
curl http://localhost:6002/admin/health
curl http://localhost:6002/admin/stats
```

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

#### 索引 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}'

# 增量索引
curl -X POST http://localhost:6004/indexer/index \
  -H "Content-Type: application/json" \
  -d '{"tenant_id": "162", "spu_ids": ["1001", "1002"]}'

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

API 文档：`http://localhost:6004/docs`

#### 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"]'

curl -X POST http://localhost:6005/embed/image \
  -H "Content-Type: application/json" \
  -d '["https://example.com/img.jpg"]'
```

#### 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"}'
```

#### 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"]}'
```

### 1.4 配置入口总览

- **搜索行为配置**：`config/config.yaml`
- **索引结构定义**：`mappings/search_products.json`
- **provider/服务配置**：`config/config.yaml` 的 `services` 块
- **环境变量**：`.env`

---

## 2. 基础配置与搜索行为

### 2.1 总体原则

- **统一索引结构**：所有租户使用同一套 mapping（按租户数据分索引名 + 文档内 `tenant_id` 隔离）
- **SPU 级索引**：每个文档是一个 SPU，包含嵌套 `skus`、`specifications`
- **配置文件驱动**：搜索权重、搜索域、重排融合、provider 全在 `config/config.yaml`，不再以“硬编码配置”为主

### 2.2 索引结构（Mapping）

文件：`mappings/search_products.json`

核心字段可分为：

- 标识字段：`tenant_id`, `spu_id`
- 多语言文本：`title.zh/en`, `brief.zh/en`, `description.zh/en`, `vendor.zh/en`, `category_path.zh/en`, `category_name_text.zh/en`
- 类目过滤：`category1_name`, `category2_name`, `category3_name` 等
- 规格/变体：`specifications`（nested）、`skus`（nested）
- 价格库存：`min_price`, `max_price`, `total_inventory` 等
- 向量：`title_embedding`（dense vector）、`image_embedding`（nested）

### 2.3 查询、权重、排序（`config/config.yaml`）

- `field_boosts`：字段权重（如标题、品牌、类目）
- `indexes`：搜索域（default/title/vendor/category/tags）
- `query_config`：语言、embedding 开关、source_fields、knn_boost、翻译提示词等
- `ranking.expression`：融合表达式（例如 `bm25() + 0.25*text_embedding_relevance()`）
- `function_score`：ES 层加权函数
- `rerank`：重排窗口、超时、ES/AI 融合权重

### 2.4 分面与返回字段

- 分面字段通常包括：`category1_name`、`category2_name`、`category3_name`、`specifications.*`
- `query_config.source_fields` 控制返回字段（`null`=全部，`[]`=不返回 source，列表=指定字段）
- 多语言返回遵循请求 language 与字段回退策略

### 2.5 修改配置时怎么做

| 修改项 | 操作 |
|--------|------|
| 索引结构（mapping） | 修改 `mappings/search_products.json` → `./scripts/create_tenant_index.sh <tenant_id>` → 重新导入 |
| 搜索域/权重/排序/重排 | 修改 `config/config.yaml` 对应块 |
| provider 与服务 URL | 修改 `config/config.yaml` 的 `services` 块，或用环境变量覆盖 |

---

## 3. Provider 架构

目标：调用方稳定、配置可切换、单一配置源。

### 3.1 当前代码结构

- 模块：`providers/`
- 工厂：`create_translation_provider()`、`create_embedding_provider()`、`create_rerank_provider()`
- 配置解析：`config/services_config.py`

| 能力 | Provider 实现 | 调用方 |
|------|---------------|--------|
| translation | `providers/translation.py`（direct/http） | `query/query_parser.py`、索引链路 |
| embedding | `providers/embedding.py`（http） | 文本/图像编码调用 |
| rerank | `providers/rerank.py`（http） | `search/rerank_client.py` |

### 3.2 配置与覆盖

统一在 `config/config.yaml`：

```yaml
services:
  translation:
    provider: "direct"
    providers:
      direct: { model: "qwen" }
      http: { base_url: "http://127.0.0.1:6006", model: "qwen", timeout_sec: 10.0 }
  embedding:
    provider: "http"
    providers:
      http: { base_url: "http://127.0.0.1:6005" }
  rerank:
    provider: "http"
    providers:
      http: { base_url: "http://127.0.0.1:6007", service_url: "http://127.0.0.1:6007/rerank" }
```

环境变量覆盖（优先级更高）：

- `TRANSLATION_PROVIDER`
- `TRANSLATION_SERVICE_URL`
- `EMBEDDING_SERVICE_URL`
- `RERANKER_SERVICE_URL`
- `RERANK_BACKEND`（服务内后端）

### 3.3 新增 provider 的最小步骤

1. 在 `providers/<capability>.py` 实现 provider 类
2. 在 `create_*_provider()` 注册
3. 在 `config/config.yaml` 的 `services.<capability>.providers` 新增配置

---

## 4. 模块扩展规范（Embedding / Rerank）

这里重点区分两层：

- **Provider 层（调用方式）**：调用方如何访问能力（http/direct）
- **Backend 层（推理实现）**：服务进程内部具体模型实现（bge / qwen3_vllm / ...）

### 4.1 Rerank（重排）扩展

调用链：

`search/rerank_client.py` -> `create_rerank_provider()` -> `HttpRerankProvider` -> `POST /rerank`

服务实现：

- `reranker/server.py`
- `reranker/backends/__init__.py`（工厂）
- `reranker/backends/bge.py`
- `reranker/backends/qwen3_vllm.py`

后端协议（服务内）：

- 实现 `score_with_meta(query, docs, normalize) -> (scores, meta)`
- 返回 `scores` 与输入 `docs` 等长且顺序一致

配置位置：

`config/config.yaml` -> `services.rerank.backend` + `services.rerank.backends.<name>`

### 4.2 Embedding（向量化）扩展

调用链：

`create_embedding_provider()` -> `POST /embed/text` / `POST /embed/image`

服务实现：

- `embeddings/server.py`（文本和图像可独立加载）
- 文本后端现用 BGE
- 图像后端支持本地 CLIP 或 clip-as-service

扩展建议：

- 文本后端统一提供批量编码能力（与输入索引对齐）
- 图像后端实现 `ImageEncoderProtocol`（`encode_image_urls`）
- 如后续后端增多，建议与 rerank 一样在 `services.embedding.backend(s)` 统一配置

### 4.3 新增后端检查清单（以 `qwen3_vllm` 为例）

1. 实现后端协议（服务内）
2. 在后端工厂注册（如 `get_rerank_backend`）
3. 增加 `config/config.yaml` 对应 backend 配置
4. 提供健康检查中的 backend/model 可观测信息
5. 保持外部 HTTP 契约不变，调用方无需改造

---

## 5. 验证、日志与常见排障入口

### 5.1 快速健康检查

```bash
curl http://localhost:6002/health
curl http://localhost:6002/admin/health
curl http://localhost:6004/health
curl http://localhost:6005/health
curl http://localhost:6006/health
curl http://localhost:6007/health
```

### 5.2 常看日志

- `logs/backend.log`
- `logs/indexer.log`
- `logs/frontend.log`
- `logs/embedding.log`
- `logs/translator.log`
- `logs/reranker.log`
- `logs/search_engine.log`
- `logs/errors.log`

### 5.3 常用排障命令

```bash
./scripts/service_ctl.sh status
curl http://localhost:9200
lsof -i :6002
lsof -i :6004
```

更完整的运行排障（多环境切换、Suggestion 构建、FAQ）见 `docs/Usage-Guide.md`。

---

## 6. 相关文档

| 文档 | 用途 |
|------|------|
| `docs/DEVELOPER_GUIDE.md` | 项目全貌、规范、协作方式 |
| `docs/Usage-Guide.md` | 运行运维手册：日志、多环境、故障排查、Suggestion 运维 |
| `docs/搜索API速查表.md` | 搜索 API 参数速查 |
| `docs/搜索API对接指南.md` | 搜索 API 完整说明 |
| `indexer/README.md` | 索引模块职责与接口 |
| `embeddings/README.md` | 向量化服务说明 |
| `reranker/README.md` | 重排服务说明 |

---

## 7. 持续集成测试（最小可维护方案）

目标：让后续开发者在不依赖真实 ES/MySQL/模型服务的前提下，快速验证核心服务契约不被破坏。

### 7.1 测试范围

`tests/ci/test_service_api_contracts.py` 覆盖：

- 搜索接口：`/search/`、`/search/image`、`/search/suggestions`
- 索引接口：`/indexer/reindex`、`/indexer/index`、`/indexer/build-docs`
- 向量服务：`/embed/text`、`/embed/image`
- 翻译服务：`/translate`、`/health`
- 重排服务：`/rerank`、`/health`

### 7.2 运行方式

```bash
source activate.sh
python -m pytest tests/ci -q
```

### 7.3 设计取舍

- 使用 mock/stub 注入依赖，确保测试快且稳定
- 重点测“接口契约与参数行为”，而不是底层模型质量
- 作为 PR 级门禁；真实环境联调放在运维/预发布流程