文档完善

tangwang
1 parent 8d227b96
Showing 1 changed file with 22 additions and 71 deletions Show diff stats
docs/搜索API对接指南.md
@@ -6,10 +6,9 @@
 1. [快速开始](#快速开始)
 2. [接口概览](#接口概览)
-3. [文本搜索接口](#文本搜索接口)
-4. [图片搜索接口](#图片搜索接口)
-5. [响应格式说明](#响应格式说明)
-6. [常见场景示例](#常见场景示例)
+3. [搜索接口](#搜索接口)
+4. [响应格式说明](#响应格式说明)
+5. [常见场景示例](#常见场景示例)
 ---
@@ -79,7 +78,7 @@ curl -X POST &quot;http://localhost:6002/search/&quot; \
 ---
-## 文本搜索接口
+## 搜索接口
 ### 接口信息
@@ -112,19 +111,19 @@ curl -X POST &quot;http://localhost:6002/search/&quot; \
 | 参数 | 类型 | 必填 | 默认值 | 说明 |
 |------|------|------|--------|------|
-| `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（用于分析，预留） |
+| `tenant_id` | string | Y | - | 租户ID，用于隔离不同站点或客户的数据 |
+| `query` | string | Y | - | 搜索查询字符串，支持布尔表达式（AND, OR, RANK, ANDNOT） |
+| `size` | integer | N | 10 | 返回结果数量（1-100） |
+| `from` | integer | N | 0 | 分页偏移量（用于分页） |
+| `filters` | object | N | null | 精确匹配过滤器（见下文） |
+| `range_filters` | object | N | null | 数值范围过滤器（见下文） |
+| `facets` | array | N | null | 分面配置（见下文） |
+| `sort_by` | string | N | null | 排序字段名（如 `min_price`, `max_price`, `title`） |
+| `sort_order` | string | N | "desc" | 排序方向：`asc`（升序）或 `desc`（降序） |
+| `min_score` | float | N | null | 最小相关性分数阈值 |
+| `debug` | boolean | N | false | 是否返回调试信息 |
+| `user_id` | string | N | null | 用户ID（用于个性化，预留） |
+| `session_id` | string | N | null | 会话ID（用于分析，预留） |
 ### 过滤器详解
@@ -264,54 +263,6 @@ curl -X POST &quot;http://localhost:6002/search/&quot; \
 ---
-## 图片搜索接口
-
-### 接口信息
-
-- **端点**: `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
-      }
-    }
-  }'
-```
-
----
-
 ## 响应格式说明
 ### 标准响应结构
@@ -557,9 +508,9 @@ curl -X POST &quot;http://localhost:6002/search/image&quot; \
 | 参数 | 类型 | 必填 | 默认值 | 描述 |
 |------|------|------|--------|------|
-| `q` | string | ✅ | - | 查询字符串（至少 1 个字符） |
-| `size` | integer | ❌ | 5 | 返回建议数量（1-20） |
-| `types` | string | ❌ | `query` | 建议类型（逗号分隔）：`query`, `product`, `category`, `brand` |
+| `q` | string | Y | - | 查询字符串（至少 1 个字符） |
+| `size` | integer | N | 5 | 返回建议数量（1-20） |
+| `types` | string | N | `query` | 建议类型（逗号分隔）：`query`, `product`, `category`, `brand` |
 #### 响应示例
@@ -595,8 +546,8 @@ curl &quot;http://localhost:6002/search/suggestions?q=芭&amp;size=5&amp;types=query,product&quot;
 | 参数 | 类型 | 必填 | 默认值 | 描述 |
 |------|------|------|--------|------|
-| `q` | string | ✅ | - | 搜索查询（至少 2 个字符） |
-| `size` | integer | ❌ | 5 | 返回结果数量（1-20） |
+| `q` | string | Y | - | 搜索查询（至少 2 个字符） |
+| `size` | integer | N | 5 | 返回结果数量（1-20） |
 #### 请求示例