搜索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。

1.2 最简单的搜索请求

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

1.3 带过滤与分页的搜索

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 开启分面的搜索

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
内容理解字段生成	POST	/indexer/enrich-content	根据商品标题批量生成 qanchors、enriched_attributes、tags，供微服务组合方式使用
索引健康检查	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 内）	6004	POST /indexer/enrich-content	根据商品标题生成 qanchors、tags 等，供 indexer 微服务组合方式使用

---