撰写接口文档

tangwang
1 parent cd3799c6
Showing 6 changed files with 1018 additions and 110 deletions Show diff stats
API_INTEGRATION_GUIDE.md
ES_QUERY_RESTRUCTURE_COMPLETE.md
HighLevelDesign.md
INDEX_FIELDS_DOCUMENTATION.md
config/config.yaml
config/config_loader.py
@@ -0,0 +1,791 @@
+# 搜索API接口对接指南
+
+本文档为搜索服务的使用方提供完整的API对接指南，包括接口说明、请求参数、响应格式和使用示例。
+
+## 目录
+
+1. [快速开始](#快速开始)
+2. [接口概览](#接口概览)
+3. [文本搜索接口](#文本搜索接口)
+4. [图片搜索接口](#图片搜索接口)
+5. [响应格式说明](#响应格式说明)
+6. [常见场景示例](#常见场景示例)
+7. [错误处理](#错误处理)
+8. [最佳实践](#最佳实践)
+
+---
+
+## 快速开始
+
+### 基础信息
+
+- **Base URL**: `http://your-domain:6002` 或 `http://120.76.41.98:6002`
+- **协议**: HTTP/HTTPS
+- **数据格式**: JSON
+- **字符编码**: UTF-8
+- **请求方法**: POST（搜索接口）
+
+### 最简单的搜索请求
+
+```bash
+curl -X POST "http://localhost:6002/search/" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "query": "芭比娃娃"
+  }'
+```
+
+### Python示例
+
+```python
+import requests
+
+url = "http://localhost:6002/search/"
+response = requests.post(url, json={"query": "芭比娃娃"})
+data = response.json()
+print(f"找到 {data['total']} 个结果")
+```
+
+### JavaScript示例
+
+```javascript
+const response = await fetch('http://localhost:6002/search/', {
+    method: 'POST',
+    headers: {
+        'Content-Type': 'application/json'
+    },
+    body: JSON.stringify({
+        query: '芭比娃娃'
+    })
+});
+const data = await response.json();
+console.log(`找到 ${data.total} 个结果`);
+```
+
+---
+
+## 接口概览
+
+| 接口 | 方法 | 路径 | 说明 |
+|------|------|------|------|
+| 文本搜索 | POST | `/search/` | 执行文本搜索查询 |
+| 图片搜索 | POST | `/search/image` | 基于图片相似度搜索 |
+| 搜索建议 | GET | `/search/suggestions` | 获取搜索建议（框架，暂未实现） |
+| 获取文档 | GET | `/search/{doc_id}` | 根据ID获取单个文档 |
+| 健康检查 | GET | `/admin/health` | 检查服务状态 |
+
+---
+
+## 文本搜索接口
+
+### 接口信息
+
+- **端点**: `POST /search/`
+- **描述**: 执行文本搜索查询，支持多语言、布尔表达式、过滤器和分面搜索
+
+### 请求参数
+
+#### 完整请求体结构
+
+```json
+{
+  "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"
+}
+```
+
+#### 参数详细说明
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `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 逻辑）。
+
+**格式**:
+```json
+{
+  "filters": {
+    "category_keyword": "玩具",                    // 单值：精确匹配
+    "vendor_keyword": ["乐高", "孩之宝"],          // 数组：匹配任意值（OR）
+    "product_type_keyword": "益智玩具"              // 单值：精确匹配
+  }
+}
+```
+
+**支持的值类型**:
+- 字符串：精确匹配
+- 整数：精确匹配
+- 布尔值：精确匹配
+- 数组：匹配任意值（OR 逻辑）
+
+**常用过滤字段**:
+- `category_keyword`: 类目
+- `vendor_keyword`: 品牌/供应商
+- `product_type_keyword`: 商品类型
+- `tags_keyword`: 标签
+
+#### 2. 范围过滤器 (range_filters)
+
+用于数值字段的范围过滤。
+
+**格式**:
+```json
+{
+  "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。
+
+**简单模式**（字符串数组）:
+```json
+{
+  "facets": ["category_keyword", "vendor_keyword"]
+}
+```
+
+**高级模式**（配置对象数组）:
+```json
+{
+  "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`
+- **描述**: 基于图片相似度进行搜索，使用图片向量进行语义匹配
+
+### 请求参数
+
+```json
+{
+  "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 | 数值范围过滤器 |
+
+### 请求示例
+
+```bash
+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
+      }
+    }
+  }'
+```
+
+---
+
+## 响应格式说明
+
+### 标准响应结构
+
+```json
+{
+  "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个结果
+
+```json
+{
+  "query": "玩具",
+  "size": 20,
+  "from": 0,
+  "sort_by": "min_price",
+  "sort_order": "asc"
+}
+```
+
+### 场景2：带筛选的商品搜索
+
+**需求**: 搜索"玩具"，筛选类目为"益智玩具"，价格在50-200之间
+
+```json
+{
+  "query": "玩具",
+  "size": 20,
+  "filters": {
+    "category_keyword": "益智玩具"
+  },
+  "range_filters": {
+    "min_price": {
+      "gte": 50,
+      "lte": 200
+    }
+  }
+}
+```
+
+### 场景3：带分面的商品搜索
+
+**需求**: 搜索"玩具"，获取类目和品牌的分面统计，用于构建筛选器
+
+```json
+{
+  "query": "玩具",
+  "size": 20,
+  "facets": [
+    "category_keyword",
+    "vendor_keyword"
+  ]
+}
+```
+
+### 场景4：多条件组合搜索
+
+**需求**: 搜索"玩具"，筛选多个品牌，价格范围，并获取分面统计
+
+```json
+{
+  "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：布尔表达式搜索
+
+**需求**: 搜索包含"玩具"和"乐高"的商品，排除"电动"
+
+```json
+{
+  "query": "玩具 AND 乐高 ANDNOT 电动",
+  "size": 20
+}
+```
+
+### 场景6：分页查询
+
+**需求**: 获取第2页结果（每页20条）
+
+```json
+{
+  "query": "玩具",
+  "size": 20,
+  "from": 20
+}
+```
+
+---
+
+## 错误处理
+
+### 错误响应格式
+
+```json
+{
+  "error": "错误信息",
+  "detail": "详细错误信息（可选）"
+}
+```
+
+### 常见错误码
+
+| HTTP状态码 | 说明 | 处理建议 |
+|-----------|------|---------|
+| 200 | 成功 | - |
+| 400 | 请求参数错误 | 检查请求参数格式和必填字段 |
+| 404 | 接口不存在 | 检查接口路径 |
+| 500 | 服务器内部错误 | 联系技术支持 |
+
+### 错误处理示例
+
+**Python**:
+```python
+import requests
+
+try:
+    response = requests.post(url, json=payload, timeout=10)
+    response.raise_for_status()
+    data = response.json()
+except requests.exceptions.HTTPError as e:
+    print(f"HTTP错误: {e}")
+    if response.status_code == 400:
+        error_data = response.json()
+        print(f"错误详情: {error_data.get('detail')}")
+except requests.exceptions.RequestException as e:
+    print(f"请求异常: {e}")
+```
+
+**JavaScript**:
+```javascript
+try {
+    const response = await fetch(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(payload)
+    });
+    
+    if (!response.ok) {
+        const error = await response.json();
+        throw new Error(error.error || `HTTP ${response.status}`);
+    }
+    
+    const data = await response.json();
+} catch (error) {
+    console.error('搜索失败:', error.message);
+}
+```
+
+---
+
+### 5. 代码示例
+
+**完整的搜索函数（Python）**:
+
+```python
+import requests
+from typing import Dict, Any, Optional, List
+
+class SearchClient:
+    def __init__(self, base_url: str = "http://localhost:6002"):
+        self.base_url = base_url
+        self.timeout = 10
+    
+    def search(
+        self,
+        query: str,
+        size: int = 20,
+        from_: int = 0,
+        filters: Optional[Dict] = None,
+        range_filters: Optional[Dict] = None,
+        facets: Optional[List] = None,
+        sort_by: Optional[str] = None,
+        sort_order: str = "desc"
+    ) -> Dict[str, Any]:
+        """
+        执行搜索查询
+        
+        Args:
+            query: 搜索查询字符串
+            size: 返回结果数量
+            from_: 分页偏移量
+            filters: 精确匹配过滤器
+            range_filters: 范围过滤器
+            facets: 分面配置
+            sort_by: 排序字段
+            sort_order: 排序方向
+        
+        Returns:
+            搜索结果字典
+        """
+        url = f"{self.base_url}/search/"
+        payload = {
+            "query": query,
+            "size": size,
+            "from": from_,
+        }
+        
+        if filters:
+            payload["filters"] = filters
+        if range_filters:
+            payload["range_filters"] = range_filters
+        if facets:
+            payload["facets"] = facets
+        if sort_by:
+            payload["sort_by"] = sort_by
+            payload["sort_order"] = sort_order
+        
+        try:
+            response = requests.post(
+                url,
+                json=payload,
+                timeout=self.timeout
+            )
+            response.raise_for_status()
+            return response.json()
+        except requests.exceptions.RequestException as e:
+            raise Exception(f"搜索请求失败: {e}")
+
+# 使用示例
+client = SearchClient()
+result = client.search(
+    query="玩具",
+    size=20,
+    filters={"category_keyword": "益智玩具"},
+    range_filters={"min_price": {"gte": 50, "lte": 200}},
+    facets=["category_keyword", "vendor_keyword"],
+    sort_by="min_price",
+    sort_order="asc"
+)
+
+print(f"找到 {result['total']} 个结果")
+for product in result['results']:
+    print(f"{product['title']} - ¥{product['price']}")
+```
+
+**完整的搜索函数（JavaScript）**:
+
+```javascript
+class SearchClient {
+    constructor(baseUrl = 'http://localhost:6002') {
+        this.baseUrl = baseUrl;
+        this.timeout = 10000;
+    }
+    
+    async search({
+        query,
+        size = 20,
+        from = 0,
+        filters = null,
+        rangeFilters = null,
+        facets = null,
+        sortBy = null,
+        sortOrder = 'desc'
+    }) {
+        const url = `${this.baseUrl}/search/`;
+        const payload = {
+            query,
+            size,
+            from,
+        };
+        
+        if (filters) payload.filters = filters;
+        if (rangeFilters) payload.range_filters = rangeFilters;
+        if (facets) payload.facets = facets;
+        if (sortBy) {
+            payload.sort_by = sortBy;
+            payload.sort_order = sortOrder;
+        }
+        
+        try {
+            const response = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json'
+                },
+                body: JSON.stringify(payload),
+                signal: AbortSignal.timeout(this.timeout)
+            });
+            
+            if (!response.ok) {
+                const error = await response.json();
+                throw new Error(error.error || `HTTP ${response.status}`);
+            }
+            
+            return await response.json();
+        } catch (error) {
+            throw new Error(`搜索请求失败: ${error.message}`);
+        }
+    }
+}
+
+// 使用示例
+const client = new SearchClient();
+const result = await client.search({
+    query: '玩具',
+    size: 20,
+    filters: { category_keyword: '益智玩具' },
+    rangeFilters: { min_price: { gte: 50, lte: 200 } },
+    facets: ['category_keyword', 'vendor_keyword'],
+    sortBy: 'min_price',
+    sortOrder: 'asc'
+});
+
+console.log(`找到 ${result.total} 个结果`);
+result.results.forEach(product => {
+    console.log(`${product.title} - ¥${product.price}`);
+});
+```
+
+---
+
+## 附录
+
+### 常用字段列表
+
+#### 过滤字段（使用 `*_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`: 相关性分数（默认）
+
@@ -218,7 +218,7 @@ from .rerank_engine import RerankEngine  # 原 RankingEngine
                   },
                   {
                     "knn": {
-                      "field": "name_embedding",
+                      "field": "title_embedding",
                       "query_vector": [...],
                       "k": 50,
                       "num_candidates": 200
@@ -51,112 +51,6 @@ updater	varchar(64)
 update_time	datetime
 deleted	bit(1)
  
-所有租户共用这个主表
-
-### 每个租户的辅表
-各个租户，有自己的扩展表。 入索引的时候，商品主表 shoplazza_product_sku 的 id + shopid，拼接租户自己单独的扩展表（比如可以放一些自己的属性体系、各种语言的商品名、品牌名、标签、分类等）
-
-但是，各个租户，可能有不一样的业务数据，比如不同租户有不同的属性的体系、不同语言的商品标题（一般至少有中英文两种满足跨境的搜索需求），有不同的权重（提权）字段、业务过滤和聚合字段。
-能够统一的 只能是 sku表 按照一套配置规范、做一个配置文件，按照配置文件建设ES mapping结构以及做数据的入库。
-
-## SearchEngine
-
-### IndexerConfig
- @阿里opensearch电商行业.md， 有两套配置
-1. 应用结构配置 ： 定义了ES的输入数据有哪些字段、关联mysql的哪些字段.
-2. 索引结构配置 : 定义了ES的字段，每个字段的索引mapping配置，支持各个域的查询，包括默认的域的查询。索引配置预定一号了一堆分析方式 由 @商品数据源入ES配置规范.md 定义。
-
-
-
-### 测试数据灌入
-
-灌入数据、mysql到ES的自动同步，不在本项目的范围内，另外有java项目负责。
-但是，该项目 为了提供测试数据，需要 构造一个实例 tenant1.
-我们为他构造一套应用配置和索引配置。
-灌入一批测试数据，可以些一个简单的 全量灌入的实现。
-数据源地址在：data/tenant1/goods_with_pic.5years_congku.csv.shuf.1w
-请根据这里面的字段，建设辅助表（注意看哪些字段在主表有，哪些需要放到辅表）
-然后写一个程序，将数据分别灌入主表和辅表。
-
-
-### queryParser
-query分析，做以下几个事情：
-
-1. 查询改写。 配置词典的key是query，value是改写后的查询表达式，比如。比如品牌词 改写为在brand|query OR name|query，类别词、标签词等都可以放进去。纠错、规范化、查询改写等 都可以通过这个词典来配置。
-2. 翻译。配置需要得到的几种目标语言。 在tenant1测试案例中，我们配置 zh en两种语言。先对query做语言检测，如果query是中文那么要翻译一下en，如果是en那么要翻译zh，如果两者都不是那么zh en都需要翻译。
-3. 如果配置打开了text_embedding查询，并且query 包含了default域的查询，那么要把default域的查询词转向量，后面searcher会用这个向量参与查询。
-翻译代码参考：
-```
-import requests
-api_url = "https://api.deepl.com/v2/translate"
-headers = {
-    "Authorization": "DeepL-Auth-Key YOUR_AUTH_KEY",
-    "Content-Type": "application/json",
-}
-payload = {
-    "text": ["要翻译的文本"],
-    "target_lang": "ZH",  # 中文
-}
-
-response = requests.post(api_url, headers=headers, json=payload, timeout=10)
-
-if response.status_code == 200:
-    data = response.json()
-    translation = data["translations"][0]["text"]
-    print(translation)
-```
-
-### searcher
-
-支持多种检索表达式：
-支持多种匹配方式，如AND、OR、RANK、NOTAND以及()，优先级从高到低为()，ANDNOT，AND，OR，RANK。
-
-default域的相关性，是代码里面单独计算，是特定的深度定制优化的，暂时不做配置化。
-
-暂时具体实现为 bm25()+0.2*text_embedding_relevence（也就是knn检索表达式的打分）
-bm25() 包括多语言的打分：内部需要通过配置翻译为多种语言（配置几种目标语言 默认中文、英文，并且设置对应的检索域），然后分别到对应的字段搜索，中文字段到配置的中文title搜索，英文到对应的英文title搜索。
-bm25打分（base_query）：
-"multi_match": {
-    "query": search_query,
-    "fields": match_fields,
-    "minimum_should_match": "67%",
-    "tie_breaker": 0.9,
-    "boost": 1.0,  # Low boost for auxiliary keyword query
-    "_name": "base_query"
-}
-
-text_embedding_relevence:
-        knn_query = {
-            "knn": {
-                "field": text_embedding_field,
-                "query_vector": query_vector.tolist(),
-                "k": KNN_K,
-                "num_candidates": KNN_NUM_CANDIDATES
-            }
-        }
-
-支持配置化的排序打分：
-default域 支持配置的排序方式：
-| 场景 | 表达式 | 含义 |
-|------|--------|------|
-| 电商 | `text_re()+general_score*2+timeliness(end_time)` | 文本分、宝贝综合分值、过期时间 |
-
-
-有一个配置，是否按照spu聚合，如果打开spu聚合，那么 要配置spu_id的字段，检索表达上需要加上：
-es_query["aggs"]["unique_count"] = {
-    "cardinality": {
-        "field": spu_id_field_name
-    }
-}
-es_query["collapse"]["inner_hits"] = {
-    "_source": False,
-    "name": "top_docs",
-    "size": INNER_HITS_SIZE
-}
-
-
-## 相关配置
-
 ES_CONFIG = {
     'host': 'http://localhost:9200',
     'username': 'essa',
@@ -0,0 +1,223 @@
+# 索引字段说明文档
+
+本文档详细说明了 Elasticsearch 索引中所有字段的类型、索引方式、数据来源等信息。
+
+## 索引基本信息
+
+- **索引名称**: `search_products`
+- **索引级别**: SPU级别（商品级别）
+- **数据结构**: SPU文档包含嵌套的variants（SKU）数组
+
+## 字段说明表
+
+### 基础字段
+
+| 索引字段名 | ES字段类型 | 是否索引 | 索引方式 | 数据来源表 | 表中字段名 | 表中字段类型 | 说明 |
+|-----------|-----------|---------|---------|-----------|-----------|-------------|------|
+| tenant_id | KEYWORD | 是 | 精确匹配 | SPU表 | tenant_id | BIGINT | 租户ID，用于多租户隔离 |
+| product_id | KEYWORD | 是 | 精确匹配 | SPU表 | id | BIGINT | 商品ID（SPU ID） |
+| handle | KEYWORD | 是 | 精确匹配 | SPU表 | handle | VARCHAR(255) | 商品URL handle |
+
+### 文本搜索字段
+
+| 索引字段名 | ES字段类型 | 是否索引 | 索引方式 | 数据来源表 | 表中字段名 | 表中字段类型 | Boost权重 | 说明 |
+|-----------|-----------|---------|---------|-----------|-----------|-------------|-----------|------|
+| title | TEXT | 是 | chinese_ecommerce分析器 | SPU表 | title | VARCHAR(512) | 3.0 | 商品标题，权重最高 |
+| brief | TEXT | 是 | chinese_ecommerce分析器 | SPU表 | brief | VARCHAR(512) | 1.5 | 商品简介 |
+| description | TEXT | 是 | chinese_ecommerce分析器 | SPU表 | description | TEXT | 1.0 | 商品详细描述 |
+
+### SEO字段
+
+| 索引字段名 | ES字段类型 | 是否索引 | 索引方式 | 数据来源表 | 表中字段名 | 表中字段类型 | Boost权重 | 是否返回 | 说明 |
+|-----------|-----------|---------|---------|-----------|-----------|-------------|-----------|---------|------|
+| seo_title | TEXT | 是 | chinese_ecommerce分析器 | SPU表 | seo_title | VARCHAR(512) | 2.0 | 否 | SEO标题，用于提升相关性 |
+| seo_description | TEXT | 是 | chinese_ecommerce分析器 | SPU表 | seo_description | TEXT | 1.5 | 否 | SEO描述 |
+| seo_keywords | TEXT | 是 | chinese_ecommerce分析器 | SPU表 | seo_keywords | VARCHAR(1024) | 2.0 | 否 | SEO关键词 |
+
+### 分类和标签字段
+
+| 索引字段名 | ES字段类型 | 是否索引 | 索引方式 | 数据来源表 | 表中字段名 | 表中字段类型 | Boost权重 | 是否返回 | 说明 |
+|-----------|-----------|---------|---------|-----------|-----------|-------------|-----------|---------|------|
+| vendor | TEXT | 是 | chinese_ecommerce分析器 | SPU表 | vendor | VARCHAR(255) | 1.5 | 是 | 供应商/品牌（文本搜索） |
+| vendor_keyword | KEYWORD | 是 | 精确匹配 | SPU表 | vendor | VARCHAR(255) | - | 否 | 供应商/品牌（精确匹配，用于过滤） |
+| product_type | TEXT | 是 | chinese_ecommerce分析器 | SPU表 | category | VARCHAR(255) | 1.5 | 是 | 商品类型（文本搜索） |
+| product_type_keyword | KEYWORD | 是 | 精确匹配 | SPU表 | category | VARCHAR(255) | - | 否 | 商品类型（精确匹配，用于过滤） |
+| tags | TEXT | 是 | chinese_ecommerce分析器 | SPU表 | tags | VARCHAR(1024) | 1.0 | 是 | 标签（文本搜索） |
+| tags_keyword | KEYWORD | 是 | 精确匹配 | SPU表 | tags | VARCHAR(1024) | - | 否 | 标签（精确匹配，用于过滤） |
+| category | TEXT | 是 | chinese_ecommerce分析器 | SPU表 | category | VARCHAR(255) | 1.5 | 是 | 类目（文本搜索） |
+| category_keyword | KEYWORD | 是 | 精确匹配 | SPU表 | category | VARCHAR(255) | - | 否 | 类目（精确匹配，用于过滤） |
+
+### 价格字段
+
+| 索引字段名 | ES字段类型 | 是否索引 | 索引方式 | 数据来源表 | 表中字段名 | 表中字段类型 | 说明 |
+|-----------|-----------|---------|---------|-----------|-----------|-------------|------|
+| min_price | FLOAT | 是 | 数值范围 | SKU表（聚合计算） | price | DECIMAL(10,2) | 最低价格（从所有SKU中取最小值） |
+| max_price | FLOAT | 是 | 数值范围 | SKU表（聚合计算） | price | DECIMAL(10,2) | 最高价格（从所有SKU中取最大值） |
+| compare_at_price | FLOAT | 是 | 数值范围 | SKU表（聚合计算） | compare_at_price | DECIMAL(10,2) | 原价（从所有SKU中取最大值） |
+
+**价格计算逻辑**：
+- `min_price`: 取该SPU下所有SKU的price字段的最小值
+- `max_price`: 取该SPU下所有SKU的price字段的最大值
+- `compare_at_price`: 取该SPU下所有SKU的compare_at_price字段的最大值（如果存在）
+
+### 图片字段
+
+| 索引字段名 | ES字段类型 | 是否索引 | 索引方式 | 数据来源表 | 表中字段名 | 表中字段类型 | 说明 |
+|-----------|-----------|---------|---------|-----------|-----------|-------------|------|
+| image_url | KEYWORD | 否 | 不索引 | SPU表 | image_src | VARCHAR(500) | 商品主图URL，仅用于展示 |
+
+### 文本嵌入字段
+
+| 索引字段名 | ES字段类型 | 是否索引 | 索引方式 | 数据来源表 | 表中字段名 | 表中字段类型 | 说明 |
+|-----------|-----------|---------|---------|-----------|-----------|-------------|------|
+| title_embedding | TEXT_EMBEDDING | 是 | 向量相似度（dot_product） | 计算生成 | title | VARCHAR(512) | 标题的文本向量（1024维），用于语义搜索 |
+
+**说明**：
+- 向量维度：1024
+- 相似度算法：dot_product（点积）
+- 数据来源：基于title字段通过BGE-M3模型生成
+
+### 时间字段
+
+| 索引字段名 | ES字段类型 | 是否索引 | 索引方式 | 数据来源表 | 表中字段名 | 表中字段类型 | 是否返回 | 说明 |
+|-----------|-----------|---------|---------|-----------|-----------|-------------|---------|------|
+| create_time | DATE | 是 | 日期范围 | SPU表 | create_time | DATETIME | 是 | 创建时间 |
+| update_time | DATE | 是 | 日期范围 | SPU表 | update_time | DATETIME | 是 | 更新时间 |
+| shoplazza_created_at | DATE | 是 | 日期范围 | SPU表 | shoplazza_created_at | DATETIME | 否 | 店匠系统创建时间 |
+| shoplazza_updated_at | DATE | 是 | 日期范围 | SPU表 | shoplazza_updated_at | DATETIME | 否 | 店匠系统更新时间 |
+
+### 嵌套Variants字段（SKU级别）
+
+| 索引字段名 | ES字段类型 | 是否索引 | 索引方式 | 数据来源表 | 表中字段名 | 表中字段类型 | 说明 |
+|-----------|-----------|---------|---------|-----------|-----------|-------------|------|
+| variants | JSON (nested) | 是 | 嵌套对象 | SKU表 | - | - | 商品变体数组（嵌套结构） |
+
+#### Variants子字段
+
+| 索引字段名 | ES字段类型 | 是否索引 | 索引方式 | 数据来源表 | 表中字段名 | 表中字段类型 | 说明 |
+|-----------|-----------|---------|---------|-----------|-----------|-------------|------|
+| variants.variant_id | keyword | 是 | 精确匹配 | SKU表 | id | BIGINT | 变体ID（SKU ID） |
+| variants.title | text | 是 | chinese_ecommerce分析器 | SKU表 | title | VARCHAR(500) | 变体标题 |
+| variants.price | float | 是 | 数值范围 | SKU表 | price | DECIMAL(10,2) | 变体价格 |
+| variants.compare_at_price | float | 是 | 数值范围 | SKU表 | compare_at_price | DECIMAL(10,2) | 变体原价 |
+| variants.sku | keyword | 是 | 精确匹配 | SKU表 | sku | VARCHAR(100) | SKU编码 |
+| variants.stock | long | 是 | 数值范围 | SKU表 | inventory_quantity | INT(11) | 库存数量 |
+| variants.options | object | 是 | 对象 | SKU表 | option1/option2/option3 | VARCHAR(255) | 选项（颜色、尺寸等） |
+
+**Variants结构说明**：
+- `variants` 是一个嵌套对象数组，每个元素代表一个SKU
+- 使用ES的nested类型，支持对嵌套字段进行独立查询和过滤
+- `options` 对象包含 `option1`、`option2`、`option3` 三个字段，分别对应SKU表中的选项值
+
+## 字段类型说明
+
+### ES字段类型映射
+
+| ES字段类型 | Elasticsearch映射 | 用途 |
+|-----------|------------------|------|
+| KEYWORD | keyword | 精确匹配、过滤、聚合、排序 |
+| TEXT | text | 全文检索（支持分词） |
+| FLOAT | float | 浮点数（价格、权重等） |
+| LONG | long | 整数（库存、计数等） |
+| DATE | date | 日期时间 |
+| TEXT_EMBEDDING | dense_vector | 文本向量（1024维） |
+| JSON | object/nested | 嵌套对象 |
+
+### 分析器说明
+
+| 分析器名称 | 语言 | 说明 |
+|-----------|------|------|
+| chinese_ecommerce | 中文 | Ansj中文分词器（电商优化），用于中文文本的分词和搜索 |
+
+## 索引配置
+
+### 索引设置
+
+- **分片数**: 1
+- **副本数**: 0
+- **刷新间隔**: 30秒
+
+### 查询域（Query Domains）
+
+系统定义了多个查询域，用于在不同场景下搜索不同的字段组合：
+
+1. **default（默认索引）**: 搜索所有文本字段
+   - 包含字段：title, brief, description, seo_title, seo_description, seo_keywords, vendor, product_type, tags, category
+   - Boost: 1.0
+
+2. **title（标题索引）**: 仅搜索标题相关字段
+   - 包含字段：title, seo_title
+   - Boost: 2.0
+
+3. **vendor（品牌索引）**: 仅搜索品牌字段
+   - 包含字段：vendor
+   - Boost: 1.5
+
+4. **category（类目索引）**: 仅搜索类目字段
+   - 包含字段：category
+   - Boost: 1.5
+
+5. **tags（标签索引）**: 搜索标签和SEO关键词
+   - 包含字段：tags, seo_keywords
+   - Boost: 1.0
+
+## 数据转换规则
+
+### 数据类型转换
+
+1. **BIGINT → KEYWORD**: 数字ID转换为字符串（如 `product_id`, `variant_id`）
+2. **DECIMAL → FLOAT**: 价格字段从DECIMAL转换为FLOAT
+3. **INT → LONG**: 库存数量从INT转换为LONG
+4. **DATETIME → DATE**: 时间字段转换为ISO格式字符串
+
+### 特殊处理
+
+1. **价格聚合**: 从多个SKU的价格中计算min_price、max_price、compare_at_price
+2. **图片URL处理**: 如果image_src不是完整URL，会自动添加协议前缀
+3. **选项合并**: 将SKU表的option1、option2、option3合并为options对象
+
+## 注意事项
+
+1. **多租户隔离**: 所有查询必须包含 `tenant_id` 过滤条件
+2. **嵌套查询**: 查询variants字段时需要使用nested查询语法
+3. **字段命名**: 用于过滤的字段应使用 `*_keyword` 后缀的字段
+4. **向量搜索**: title_embedding字段用于语义搜索，需要配合文本查询使用
+5. **Boost权重**: 不同字段的boost权重影响搜索结果的相关性排序
+
+## 数据来源表结构
+
+### SPU表（shoplazza_product_spu）
+
+主要字段：
+- `id`: BIGINT - 主键ID
+- `tenant_id`: BIGINT - 租户ID
+- `handle`: VARCHAR(255) - URL handle
+- `title`: VARCHAR(512) - 商品标题
+- `brief`: VARCHAR(512) - 商品简介
+- `description`: TEXT - 商品描述
+- `vendor`: VARCHAR(255) - 供应商/品牌
+- `category`: VARCHAR(255) - 类目
+- `tags`: VARCHAR(1024) - 标签
+- `seo_title`: VARCHAR(512) - SEO标题
+- `seo_description`: TEXT - SEO描述
+- `seo_keywords`: VARCHAR(1024) - SEO关键词
+- `image_src`: VARCHAR(500) - 图片URL
+- `create_time`: DATETIME - 创建时间
+- `update_time`: DATETIME - 更新时间
+- `shoplazza_created_at`: DATETIME - 店匠创建时间
+- `shoplazza_updated_at`: DATETIME - 店匠更新时间
+
+### SKU表（shoplazza_product_sku）
+
+主要字段：
+- `id`: BIGINT - 主键ID（对应variant_id）
+- `spu_id`: BIGINT - SPU ID（关联字段）
+- `title`: VARCHAR(500) - 变体标题
+- `price`: DECIMAL(10,2) - 价格
+- `compare_at_price`: DECIMAL(10,2) - 原价
+- `sku`: VARCHAR(100) - SKU编码
+- `inventory_quantity`: INT(11) - 库存数量
+- `option1`: VARCHAR(255) - 选项1
+- `option2`: VARCHAR(255) - 选项2
+- `option3`: VARCHAR(255) - 选项3
+
@@ -169,7 +169,7 @@ fields:
     return_in_source: true
  
   # 文本嵌入字段（用于语义搜索）
-  - name: "name_embedding"
+  - name: "title_embedding"
     type: "TEXT_EMBEDDING"
     embedding_dims: 1024
     embedding_similarity: "dot_product"
@@ -296,7 +296,7 @@ query_config:
   enable_query_rewrite: true
  
   # Embedding field names (if not set, will auto-detect from fields)
-  text_embedding_field: "name_embedding"  # Field name for text embeddings
+  text_embedding_field: "title_embedding"  # Field name for text embeddings
   image_embedding_field: null  # Field name for image embeddings (if not set, will auto-detect)
  
   # Translation API (DeepL)
@@ -55,7 +55,7 @@ class QueryConfig:
     translation_context: str = "e-commerce product search"  # Context hint for translation
  
     # Embedding field names - if not set, will auto-detect from fields
-    text_embedding_field: Optional[str] = None  # Field name for text embeddings (e.g., "name_embedding")
+    text_embedding_field: Optional[str] = None  # Field name for text embeddings (e.g., "title_embedding")
     image_embedding_field: Optional[str] = None  # Field name for image embeddings (e.g., "image_embedding")
  
     # ES source fields configuration - fields to return in search results