tangwang / SearchEngine

搜索API对接指南.md 17.8 KB

搜索API接口对接指南

本文档为搜索服务的使用方提供完整的API对接指南，包括接口说明、请求参数、响应格式和使用示例。

目录

  1. 快速开始
  2. 接口概览
  3. 文本搜索接口
  4. 图片搜索接口
  5. 响应格式说明
  6. 常见场景示例

快速开始

基础信息

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

最简单的搜索请求

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

curl示例：带过滤与分页

curl -X POST "http://localhost:6002/search/" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "demo-tenant",
    "query": "芭比娃娃 AND 配件",
    "size": 5,
    "from": 10,
    "filters": {
      "vendor_keyword": ["乐高", "孩之宝"]
    },
    "sort_by": "min_price",
    "sort_order": "asc"
  }'

curl示例：开启调试与分面

curl -X POST "http://localhost:6002/search/" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "demo-tenant",
    "query": "芭比娃娃",
    "facets": ["category_keyword", "vendor_keyword"],
    "min_score": 0.2,
    "debug": true
  }'

接口概览

接口 方法 路径 说明
文本搜索 POST /search/ 执行文本搜索查询
图片搜索 POST /search/image 基于图片相似度搜索
搜索建议 GET /search/suggestions 获取搜索建议（框架，暂未实现）
获取文档 GET /search/{doc_id} 根据ID获取单个文档
健康检查 GET /admin/health 检查服务状态

文本搜索接口

接口信息

  • 端点: POST /search/
  • 描述: 执行文本搜索查询，支持多语言、布尔表达式、过滤器和分面搜索

请求参数

完整请求体结构

{
  "tenant_id": "string (required)",
  "query": "string (required)",
  "size": 10,
  "from": 0,
  "filters": {},
  "range_filters": {},
  "facets": [],
  "sort_by": "string",
  "sort_order": "desc",
  "min_score": 0.0,
  "debug": false,
  "user_id": "string",
  "session_id": "string"
}

参数详细说明

参数 类型 必填 默认值 说明
tenant_id string ✅ - 租户ID，用于隔离不同站点或客户的数据
query string ✅ - 搜索查询字符串，支持布尔表达式（AND, OR, RANK, ANDNOT）
size integer ❌ 10 返回结果数量（1-100）
from integer ❌ 0 分页偏移量（用于分页）
filters object ❌ null 精确匹配过滤器（见下文）
range_filters object ❌ null 数值范围过滤器（见下文）
facets array ❌ null 分面配置（见下文）
sort_by string ❌ null 排序字段名（如 min_price, max_price, title）
sort_order string ❌ "desc" 排序方向：asc（升序）或 desc（降序）
min_score float ❌ null 最小相关性分数阈值
debug boolean ❌ false 是否返回调试信息
user_id string ❌ null 用户ID（用于个性化，预留）
session_id string ❌ null 会话ID（用于分析，预留）

过滤器详解

1. 精确匹配过滤器 (filters)

用于精确匹配或多值匹配（OR 逻辑）。

格式:

{
  "filters": {
    "category_keyword": "玩具",                    // 单值：精确匹配
    "vendor_keyword": ["乐高", "孩之宝"],          // 数组：匹配任意值（OR）
    "product_type_keyword": "益智玩具"              // 单值：精确匹配
  }
}

支持的值类型:

  • 字符串：精确匹配
  • 整数：精确匹配
  • 布尔值：精确匹配
  • 数组：匹配任意值（OR 逻辑）

常用过滤字段:

  • category_keyword: 类目
  • vendor_keyword: 品牌/供应商
  • product_type_keyword: 商品类型
  • tags_keyword: 标签

2. 范围过滤器 (range_filters)

用于数值字段的范围过滤。

格式:

{
  "range_filters": {
    "min_price": {
      "gte": 50,    // 大于等于
      "lte": 200    // 小于等于
    },
    "max_price": {
      "gt": 100     // 大于
    },
    "create_time": {
      "gte": "2024-01-01T00:00:00Z"  // 日期时间字符串
    }
  }
}

支持的操作符:

  • gte: 大于等于 (>=)
  • gt: 大于 (>)
  • lte: 小于等于 (
  • lt: 小于 (

注意: 至少需要指定一个操作符。

常用范围字段:

  • min_price: 最低价格
  • max_price: 最高价格
  • compare_at_price: 原价
  • create_time: 创建时间
  • update_time: 更新时间

3. 分面配置 (facets)

用于生成分面统计（分组聚合），常用于构建筛选器UI。

简单模式（字符串数组）:

{
  "facets": ["category_keyword", "vendor_keyword"]
}

高级模式（配置对象数组）:

{
  "facets": [
    {
      "field": "category_keyword",
      "size": 15,
      "type": "terms"
    },
    {
      "field": "min_price",
      "type": "range",
      "ranges": [
        {"key": "0-50", "to": 50},
        {"key": "50-100", "from": 50, "to": 100},
        {"key": "100-200", "from": 100, "to": 200},
        {"key": "200+", "from": 200}
      ]
    }
  ]
}

分面配置参数:

  • field: 字段名（必填）
  • size: 返回的分组数量（默认：10，范围：1-100）
  • type: 分面类型，terms（分组统计）或 range（范围统计）
  • ranges: 范围定义（仅当 type='range' 时需要）

布尔表达式语法

搜索查询支持布尔表达式，提供更灵活的搜索能力。

支持的操作符:

操作符 描述 示例
AND 所有词必须匹配 玩具 AND 乐高
OR 任意词匹配 芭比 OR 娃娃
ANDNOT 排除特定词 玩具 ANDNOT 电动
RANK 排序加权（不强制匹配） 玩具 RANK 乐高
() 分组 玩具 AND (乐高 OR 芭比)

操作符优先级（从高到低）:

  1. () - 括号
  2. ANDNOT - 排除
  3. AND - 与
  4. OR - 或
  5. RANK - 排序

示例:

"芭比娃娃"                    // 简单查询
"玩具 AND 乐高"               // AND 查询
"芭比 OR 娃娃"                // OR 查询
"玩具 ANDNOT 电动"            // 排除查询
"玩具 AND (乐高 OR 芭比)"      // 复杂查询

图片搜索接口

接口信息

  • 端点: POST /search/image
  • 描述: 基于图片相似度进行搜索，使用图片向量进行语义匹配

请求参数

{
  "image_url": "string (required)",
  "size": 10,
  "filters": {},
  "range_filters": {}
}

参数说明

参数 类型 必填 默认值 描述
image_url string ✅ - 查询图片的 URL
size integer ❌ 10 返回结果数量（1-100）
filters object ❌ null 精确匹配过滤器
range_filters object ❌ null 数值范围过滤器

请求示例

curl -X POST "http://localhost:6002/search/image" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/barbie.jpg",
    "size": 20,
    "filters": {
      "category_keyword": "玩具"
    },
    "range_filters": {
      "min_price": {
        "lte": 100
      }
    }
  }'

响应格式说明

标准响应结构

{
  "results": [
    {
      "product_id": "12345",
      "title": "芭比时尚娃娃",
      "handle": "barbie-doll",
      "description": "高品质芭比娃娃",
      "vendor": "美泰",
      "product_type": "玩具",
      "tags": "娃娃, 玩具, 女孩",
      "price": 89.99,
      "compare_at_price": 129.99,
      "currency": "USD",
      "image_url": "https://example.com/image.jpg",
      "in_stock": true,
      "variants": [
        {
          "variant_id": "67890",
          "title": "粉色款",
          "price": 89.99,
          "compare_at_price": 129.99,
          "sku": "BARBIE-001",
          "stock": 100,
          "options": {
            "option1": "粉色",
            "option2": "标准款"
          }
        }
      ],
      "relevance_score": 8.5
    }
  ],
  "total": 118,
  "max_score": 8.5,
  "facets": [
    {
      "field": "category_keyword",
      "label": "category_keyword",
      "type": "terms",
      "values": [
        {
          "value": "玩具",
          "label": "玩具",
          "count": 85,
          "selected": false
        }
      ]
    }
  ],
  "query_info": {
    "original_query": "芭比娃娃",
    "detected_language": "zh",
    "translations": {
      "en": "barbie doll"
    }
  },
  "suggestions": [],
  "related_searches": [],
  "took_ms": 45,
  "performance_info": null,
  "debug_info": null
}

响应字段说明

字段 类型 说明
results array 搜索结果列表（ProductResult对象数组）
results[].product_id string 商品ID
results[].title string 商品标题
results[].price float 价格（min_price）
results[].variants array 变体列表（SKU列表）
results[].relevance_score float 相关性分数
total integer 匹配的总文档数
max_score float 最高相关性分数
facets array 分面统计结果
query_info object 查询处理信息
took_ms integer 搜索耗时（毫秒）

ProductResult字段说明

字段 类型 说明
product_id string 商品ID（SPU ID）
title string 商品标题
handle string 商品URL handle
description string 商品描述
vendor string 供应商/品牌
product_type string 商品类型
tags string 标签
price float 价格（min_price）
compare_at_price float 原价
currency string 货币单位（默认USD）
image_url string 主图URL
in_stock boolean 是否有库存（任意变体有库存即为true）
variants array 变体列表
relevance_score float 相关性分数

VariantResult字段说明

字段 类型 说明
variant_id string 变体ID（SKU ID）
title string 变体标题
price float 价格
compare_at_price float 原价
sku string SKU编码
stock integer 库存数量
options object 选项（颜色、尺寸等）

常见场景示例

场景1：商品列表页搜索

需求: 搜索"玩具"，按价格从低到高排序，显示前20个结果

{
  "query": "玩具",
  "size": 20,
  "from": 0,
  "sort_by": "min_price",
  "sort_order": "asc"
}

场景2：带筛选的商品搜索

需求: 搜索"玩具"，筛选类目为"益智玩具"，价格在50-200之间

{
  "query": "玩具",
  "size": 20,
  "filters": {
    "category_keyword": "益智玩具"
  },
  "range_filters": {
    "min_price": {
      "gte": 50,
      "lte": 200
    }
  }
}

场景3：带分面的商品搜索

需求: 搜索"玩具"，获取类目和品牌的分面统计，用于构建筛选器

{
  "query": "玩具",
  "size": 20,
  "facets": [
    "category_keyword",
    "vendor_keyword"
  ]
}

场景4：多条件组合搜索

需求: 搜索"玩具"，筛选多个品牌，价格范围，并获取分面统计

{
  "query": "玩具",
  "size": 20,
  "filters": {
    "vendor_keyword": ["乐高", "孩之宝", "美泰"]
  },
  "range_filters": {
    "min_price": {
      "gte": 50,
      "lte": 200
    }
  },
  "facets": [
    {
      "field": "category_keyword",
      "size": 15
    },
    {
      "field": "min_price",
      "type": "range",
      "ranges": [
        {"key": "0-50", "to": 50},
        {"key": "50-100", "from": 50, "to": 100},
        {"key": "100-200", "from": 100, "to": 200},
        {"key": "200+", "from": 200}
      ]
    }
  ],
  "sort_by": "min_price",
  "sort_order": "asc"
}

场景5：布尔表达式搜索

需求: 搜索包含"玩具"和"乐高"的商品，排除"电动"

{
  "query": "玩具 AND 乐高 ANDNOT 电动",
  "size": 20
}

场景6：分页查询

需求: 获取第2页结果（每页20条）

{
  "query": "玩具",
  "size": 20,
  "from": 20
}

其他接口

搜索建议（框架）

  • 端点: GET /search/suggestions
  • 描述: 返回搜索建议（自动补全/热词）。当前为框架实现，接口和响应格式已经固定，可平滑扩展。

查询参数

参数 类型 必填 默认值 描述
q string ✅ - 查询字符串（至少 1 个字符）
size integer ❌ 5 返回建议数量（1-20）
types string ❌ query 建议类型（逗号分隔）：query, product, category, brand

响应示例

{
  "query": "芭",
  "suggestions": [
    {
      "text": "芭比娃娃",
      "type": "query",
      "highlight": "<em>芭</em>比娃娃",
      "popularity": 850
    }
  ],
  "took_ms": 5
}

请求示例

curl "http://localhost:6002/search/suggestions?q=芭&size=5&types=query,product"

即时搜索（框架）

  • 端点: GET /search/instant
  • 描述: 边输入边搜索，采用轻量参数响应当前输入。底层复用标准搜索能力。

查询参数

参数 类型 必填 默认值 描述
q string ✅ - 搜索查询（至少 2 个字符）
size integer ❌ 5 返回结果数量（1-20）

请求示例

curl "http://localhost:6002/search/instant?q=玩具&size=5"

获取单个文档

  • 端点: GET /search/{doc_id}
  • 描述: 根据文档 ID 获取单个商品详情，用于点击结果后的详情页或排查问题。

路径参数

参数 类型 描述
doc_id string 商品或文档 ID

响应示例

{
  "id": "12345",
  "source": {
    "title": "芭比时尚娃娃",
    "min_price": 89.99,
    "category_keyword": "玩具"
  }
}

请求示例

curl "http://localhost:6002/search/12345"

管理接口

健康检查

  • 端点: GET /admin/health
  • 描述: 检查服务与依赖（如 Elasticsearch）状态。
{
  "status": "healthy",
  "elasticsearch": "connected",
  "tenant_id": "tenant1"
}

获取配置

  • 端点: GET /admin/config
  • 描述: 返回当前租户的脱敏配置，便于核对索引及排序表达式。
{
  "tenant_id": "tenant1",
  "tenant_name": "Tenant1 Test Instance",
  "es_index_name": "search_tenant1",
  "num_fields": 20,
  "num_indexes": 4,
  "supported_languages": ["zh", "en", "ru"],
  "ranking_expression": "bm25() + 0.2*text_embedding_relevance()",
  "spu_enabled": false
}

索引统计

  • 端点: GET /admin/stats
  • 描述: 获取索引文档数量与磁盘大小，方便监控。
{
  "index_name": "search_tenant1",
  "document_count": 10000,
  "size_mb": 523.45
}

数据模型

商品字段

字段名 类型 描述
product_id keyword 商品 ID（SPU）
sku_id keyword/long SKU ID（主键）
title text 商品名称（中文）
en_title text 商品名称（英文）
ru_title text 商品名称（俄文）
category_keyword keyword 类目（精确匹配）
vendor_keyword keyword 品牌/供应商（精确匹配）
product_type_keyword keyword 商品类型
tags_keyword keyword 标签
min_price double 最低价格
max_price double 最高价格
compare_at_price double 原价
create_time date 创建时间
update_time date 更新时间
in_stock boolean 是否有库存
text_embedding dense_vector 文本向量（1024 维）
image_embedding dense_vector 图片向量（1024 维）

不同租户可自定义字段名称，但最佳实践是对可过滤字段建立 *_keyword 版本，对可排序字段显式建 keyword/数值映射。

附录

常用字段列表

过滤字段（使用 *_keyword 后缀）

  • category_keyword: 类目
  • vendor_keyword: 品牌/供应商
  • product_type_keyword: 商品类型
  • tags_keyword: 标签

范围字段

  • min_price: 最低价格
  • max_price: 最高价格
  • compare_at_price: 原价
  • create_time: 创建时间
  • update_time: 更新时间

排序字段

  • min_price: 最低价格
  • max_price: 最高价格
  • title: 标题（字母序）
  • create_time: 创建时间
  • update_time: 更新时间
  • relevance_score: 相关性分数（默认）

支持的分析器

分析器 语言 描述
chinese_ecommerce 中文 基于 Ansj 的电商优化中文分析器
english 英文 标准英文分析器
russian 俄文 俄文分析器
arabic 阿拉伯文 阿拉伯文分析器
spanish 西班牙文 西班牙文分析器
japanese 日文 日文分析器

字段类型速查

类型 ES Mapping 用途
TEXT text 全文检索
KEYWORD keyword 精确匹配、聚合、排序
LONG long 整数
DOUBLE double 浮点数
DATE date 日期时间
BOOLEAN boolean 布尔值
TEXT_EMBEDDING dense_vector 文本语义向量
IMAGE_EMBEDDING dense_vector 图片语义向量