From 12ac6559e39c109d0aaf4f980c68bd9728be1602 Mon Sep 17 00:00:00 2001 From: tangwang Date: Wed, 12 Nov 2025 14:17:22 +0800 Subject: [PATCH] 接口文档 --- API_DOCUMENTATION.md | 121 ++++++++++++++----------------------------------------------------------------------------------------------------------- 1 file changed, 14 insertions(+), 107 deletions(-) diff --git a/API_DOCUMENTATION.md b/API_DOCUMENTATION.md index eb57019..eee6522 100644 --- a/API_DOCUMENTATION.md +++ b/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 "http://localhost:6002/search/" \ --- -## 性能优化建议 - -### 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 "http://localhost:6002/search/" \ --- -## 联系与支持 - -- **API 文档**: http://localhost:6002/docs（Swagger UI） -- **ReDoc 文档**: http://localhost:6002/redoc -- **问题反馈**: 请联系技术支持团队 - ---- - ## 附录 ### A. 支持的分析器 @@ -1028,8 +940,3 @@ curl -X POST "http://localhost:6002/search/" \ | `TEXT_EMBEDDING` | dense_vector | 文本向量（1024维） | | `IMAGE_EMBEDDING` | dense_vector | 图片向量（1024维） | ---- - -**文档版本**: 3.0 -**最后更新**: 2024-11-12 - -- libgit2 0.21.2