接口文档

tangwang
1 parent a00c3672
Showing 1 changed file with 14 additions and 107 deletions Show diff stats
API_DOCUMENTATION.md
@@ -14,40 +14,14 @@
 ## 基础信息
-- **Base URL**: `http://your-domain:6002`
+- **Base URL**: `http://your-domain:6002`  (http://120.76.41.98:6002)
 - **协议**: HTTP/HTTPS
 - **数据格式**: JSON
 - **字符编码**: UTF-8
 ## 认证
-当前版本暂不需要认证。未来版本将支持 API Key 或 OAuth 2.0。
-
-## 通用响应格式
-
-### 成功响应
-
-HTTP Status: `200 OK`
-
-### 错误响应
-
-HTTP Status: `4xx` 或 `5xx`
-
-```json
-{
-  "error": "错误消息",
-  "detail": "详细错误信息",
-  "timestamp": 1699800000
-}
-```
-
-常见错误码：
-- `400 Bad Request`: 请求参数错误
-- `404 Not Found`: 资源不存在
-- `500 Internal Server Error`: 服务器内部错误
-- `503 Service Unavailable`: 服务不可用
-
----
+目前适配店匠，作为店匠搜索插件的一部分。（店匠插件认证方式为OAuth 2.0）
 ## 搜索接口
@@ -80,18 +54,18 @@ HTTP Status: `4xx` 或 `5xx`
 | 参数 | 类型 | 必填 | 默认值 | 描述 |
 |------|------|------|--------|------|
-| `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 | 排序字段名 |
-| `sort_order` | string | ❌ | "desc" | 排序方向：`asc` 或 `desc` |
-| `min_score` | float | ❌ | null | 最小相关性分数阈值 |
-| `debug` | boolean | ❌ | false | 是否返回调试信息 |
-| `user_id` | string | ❌ | null | 用户ID（用于个性化，预留） |
-| `session_id` | string | ❌ | null | 会话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 | 排序字段名 |
+| `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（用于分析，预留） |
 #### 过滤器详解
@@ -838,60 +812,6 @@ curl -X POST &quot;http://localhost:6002/search/&quot; \
 ---
-## 性能优化建议
-
-### 1. 分页
-
-使用 `size` 和 `from` 参数进行分页：
-
-```json
-{
-  "query": "玩具",
-  "size": 20,
-  "from": 0   // 第1页
-}
-
-{
-  "query": "玩具",
-  "size": 20,
-  "from": 20  // 第2页
-}
-```
-
-**建议**: 
-- 单页结果数不超过 100
-- 深度分页（from > 10000）性能较差，建议使用 `search_after`（未来版本支持）
-
-### 2. 字段选择
-
-默认返回所有字段。如果只需要部分字段，可以在后端配置中设置。
-
-### 3. 缓存
-
-系统自动缓存：
-- 查询向量（避免重复计算）
-- 翻译结果
-- 常见查询结果（未来版本）
-
-### 4. 批量查询
-
-如需批量查询，建议：
-- 使用异步并发请求
-- 控制并发数（建议 ≤ 10）
-- 添加请求间隔（避免限流）
-
----
-
-## 限流规则
-
-| 端点 | 限制 |
-|------|------|
-| `/search/` | 无限制（生产环境建议配置） |
-| `/search/suggestions` | 60次/分钟 |
-| `/search/instant` | 120次/分钟 |
-| `/admin/*` | 60次/分钟 |
-
----
 ## 常见问题
@@ -994,14 +914,6 @@ curl -X POST &quot;http://localhost:6002/search/&quot; \
 ---
-## 联系与支持
-
-- **API 文档**: http://localhost:6002/docs（Swagger UI）
-- **ReDoc 文档**: http://localhost:6002/redoc
-- **问题反馈**: 请联系技术支持团队
-
----
-
 ## 附录
 ### A. 支持的分析器
@@ -1028,8 +940,3 @@ curl -X POST &quot;http://localhost:6002/search/&quot; \
 | `TEXT_EMBEDDING` | dense_vector | 文本向量（1024维） |
 | `IMAGE_EMBEDDING` | dense_vector | 图片向量（1024维） |
----
-
-**文档版本**: 3.0  
-**最后更新**: 2024-11-12
-