diff --git a/docs/搜索API对接指南.md b/docs/搜索API对接指南.md index 17dcae2..79a213b 100644 --- a/docs/搜索API对接指南.md +++ b/docs/搜索API对接指南.md @@ -6,10 +6,9 @@ 1. [快速开始](#快速开始) 2. [接口概览](#接口概览) -3. [文本搜索接口](#文本搜索接口) -4. [图片搜索接口](#图片搜索接口) -5. [响应格式说明](#响应格式说明) -6. [常见场景示例](#常见场景示例) +3. [搜索接口](#搜索接口) +4. [响应格式说明](#响应格式说明) +5. [常见场景示例](#常见场景示例) --- @@ -79,7 +78,7 @@ curl -X POST "http://localhost:6002/search/" \ --- -## 文本搜索接口 +## 搜索接口 ### 接口信息 @@ -112,19 +111,19 @@ curl -X POST "http://localhost:6002/search/" \ | 参数 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| -| `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 "http://localhost:6002/search/" \ --- -## 图片搜索接口 - -### 接口信息 - -- **端点**: `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 "http://localhost:6002/search/image" \ | 参数 | 类型 | 必填 | 默认值 | 描述 | |------|------|------|--------|------| -| `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 "http://localhost:6002/search/suggestions?q=芭&size=5&types=query,product" | 参数 | 类型 | 必填 | 默认值 | 描述 | |------|------|------|--------|------| -| `q` | string | ✅ | - | 搜索查询(至少 2 个字符) | -| `size` | integer | ❌ | 5 | 返回结果数量(1-20) | +| `q` | string | Y | - | 搜索查询(至少 2 个字符) | +| `size` | integer | N | 5 | 返回结果数量(1-20) | #### 请求示例 -- libgit2 0.21.2