# 搜索API对接指南-00-总览与快速开始

本文档旨在为搜索服务的使用方提供完整的API对接指南，包括接口说明、请求参数、响应格式和使用示例。
拆分目录：
- `-01-搜索接口（POST /search/ 与响应）`
- `-02-搜索建议与即时搜索`
- `-03-获取文档（GET /search/{doc_id}）`
- `-05-索引接口（Indexer）`
- `-06-管理接口（Admin）`
- `-07-微服务接口（Embedding/Reranker/Translation）`
- `-08-数据模型与字段速查`
- `-10-接口级压测脚本`

## 快速开始

### 1.1 基础信息

- **Base URL**: `http://43.166.252.75:6002`
- **协议**: HTTP/HTTPS
- **数据格式**: JSON
- **字符编码**: UTF-8
- **请求方法**: POST（搜索接口）

**重要提示**: `tenant_id` 通过 HTTP Header `X-Tenant-ID` 传递，不在请求体中。

**环境与凭证**：MySQL、Redis、Elasticsearch 等外部服务的 AI 生产地址与凭证见 [QUICKSTART.md §1.6](./QUICKSTART.md#16-外部服务与-env含生产凭证)。

### 1.2 最简单的搜索请求

```bash
curl -X POST "http://43.166.252.75:6002/search/" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: 162" \
  -d '{"query": "芭比娃娃"}'
```

### 1.3 带过滤与分页的搜索

```bash
curl -X POST "http://43.166.252.75:6002/search/" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: 162" \
  -d '{
    "query": "芭比娃娃",
    "size": 5,
    "from": 10,
    "range_filters": {
      "min_price": {
        "gte": 50,
        "lte": 200
      },
      "create_time": {
        "gte": "2020-01-01T00:00:00Z" 
      }
    },
    "sort_by": "price",
    "sort_order": "asc"
  }'
```

### 1.4 开启分面的搜索

```bash
curl -X POST "http://43.166.252.75:6002/search/" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: 162" \
  -d '{
    "query": "芭比娃娃",
    "facets": [
      {"field": "category1_name", "size": 10, "type": "terms"},
      {"field": "specifications.color", "size": 10, "type": "terms"},
      {"field": "specifications.size", "size": 10, "type": "terms"}
    ],
    "min_score": 0.2
  }'
```

---

## 接口概览

| 接口 | HTTP Method | Endpoint | 说明 |
|------|------|------|------|
| 搜索 | POST | `/search/` | 执行搜索查询 |
| 搜索建议 | GET | `/search/suggestions` | 搜索建议（自动补全/热词，多语言） |
| 即时搜索 | GET | `/search/instant` | 即时搜索预留接口（当前返回 `501 Not Implemented`） |
| 获取文档 | GET | `/search/{doc_id}` | 获取单个文档 |
| 全量索引 | POST | `/indexer/reindex` | 全量索引接口（导入数据，不删除索引，仅推荐自测使用） |
| 增量索引 | POST | `/indexer/index` | 增量索引接口（指定SPU ID列表进行索引，支持自动检测删除和显式删除，仅推荐自测使用） |
| 查询文档 | POST | `/indexer/documents` | 查询SPU文档数据（不写入ES） |
| 构建ES文档（正式对接） | POST | `/indexer/build-docs` | 基于上游提供的 MySQL 行数据构建 ES doc，不写入 ES，供 Java 等调用后自行写入 |
| 构建ES文档（测试用） | POST | `/indexer/build-docs-from-db` | 仅在测试/调试时使用，根据 `tenant_id + spu_ids` 内部查库并构建 ES doc |
| 索引健康检查 | GET | `/indexer/health` | 检查索引服务状态 |
| 健康检查 | GET | `/admin/health` | 服务健康检查 |
| 获取配置 | GET | `/admin/config` | 获取租户配置 |
| 索引统计 | GET | `/admin/stats` | 获取租户索引统计信息（需 tenant_id） |

**微服务（独立端口或 Indexer 内，外部可直连）**：

| 服务 | 端口 | 接口 | 说明 |
|------|------|------|------|
| 向量服务（文本） | 6005 | `POST /embed/text` | 文本向量化 |
| 向量服务（图片） | 6008 | `POST /embed/image` | 图片向量化 |
| 翻译服务 | 6006 | `POST /translate` | 文本翻译（支持 qwen-mt / llm / deepl / 本地模型） |
| 重排服务 | 6007 | `POST /rerank` | 检索结果重排 |
---

> 注：`/indexer/enrich-content` 已迁移到独立项目，不再由本仓库的 Indexer 服务提供；本仓库保留 `build-docs` / `build-docs-from-db` 等索引构建接口。

---