0342d897
 tangwang
搜索API对接指南 拆分
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
|
# 搜索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 |
|
|
0342d897
tangwang
搜索API对接指南 拆分
|
93
94
95
96
97
98
99
100
101
102
103
104
105
|
| 索引健康检查 | 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` | 检索结果重排 |
|