From 116ee34b6f815c2f20050ce9fcc7a7d50f141bbf Mon Sep 17 00:00:00 2001 From: hz4th_coder Date: Sat, 11 Jul 2026 22:50:06 +0800 Subject: [PATCH] =?UTF-8?q?=E6=B7=BB=E5=8A=A0=E5=AE=8C=E6=95=B4API?= =?UTF-8?q?=E8=83=BD=E5=8A=9B=E6=96=87=E6=A1=A3=20API.md=EF=BC=8C=E6=9B=B4?= =?UTF-8?q?=E6=96=B0=20README.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- API.md | 764 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 31 ++- 2 files changed, 784 insertions(+), 11 deletions(-) create mode 100644 API.md diff --git a/API.md b/API.md new file mode 100644 index 0000000..1d599ee --- /dev/null +++ b/API.md @@ -0,0 +1,764 @@ +# ParamHub API 能力文档 + +> 本文档记录系统所有 API 能力，变更时请及时更新 +> +> 最后更新：2026-07-11 + +--- + +## 基础信息 + +- **基础地址**: `http://localhost:16041` +- **认证方式**: Session Cookie（登录后获取） +- **认证要求**: 所有 POST/PUT/DELETE 请求需先登录 + +--- + +## 1. 认证 API + +### 1.1 登录 +``` +POST /login +Content-Type: application/json + +请求体： +{ + "password": "admin123" +} + +响应： +{ + "success": true, + "redirect": "/admin" +} +``` + +### 1.2 登出 +``` +GET /logout +``` + +### 1.3 检查登录状态 +``` +GET /api/config (未登录返回 401) +``` + +--- + +## 2. 分类管理 API + +### 2.1 获取分类列表 +``` +GET /api/categories +GET /api/categories?all=1 (包含隐藏分类) +``` + +### 2.2 获取分类详情 +``` +GET /api/categories/{category_id} +``` + +### 2.3 创建分类 +``` +POST /api/categories +Content-Type: application/json + +请求体： +{ + "name": "分类名称", + "icon": "ri-icon-name", + "order": 0, + "visible": true, + "fields": ["field1", "field2"] // 动态字段配置 +} +``` + +### 2.4 更新分类 +``` +PUT /api/categories/{category_id} +Content-Type: application/json + +请求体：同创建 +``` + +### 2.5 删除分类 +``` +DELETE /api/categories/{category_id} +``` + +### 2.6 切换分类显示/隐藏 +``` +POST /api/categories/{category_id}/visible +``` + +### 2.7 导出分类 +``` +GET /api/categories/export // 导出所有分类 +GET /api/categories/export/{category_id} // 导出单个分类 +``` + +### 2.8 导入分类 +``` +POST /api/categories/import?mode=merge|replace +Content-Type: application/json + +请求体： +{ + "categories": [...] +} +``` + +--- + +## 3. AI模型 API + +### 3.1 获取模型列表 +``` +GET /api/models +GET /api/models?all=1 // 包含隐藏模型 +GET /api/models?q=关键词 // 搜索 +GET /api/models?sort=name&order=desc // 排序 +``` + +### 3.2 获取模型详情 +``` +GET /api/models/{model_id} +``` + +### 3.3 创建模型 +``` +POST /api/models +Content-Type: application/json + +请求体： +{ + "name": "模型名称", + "organization": "组织", + "parameters": "70B", + "context_length": 4096, + "mmlu": 85.5, + "publish_date": "2024-01-01", + "visible": true, + "is_pinned": false +} +``` + +### 3.4 更新模型 +``` +PUT /api/models/{model_id} +``` + +### 3.5 删除模型 +``` +DELETE /api/models/{model_id} +``` + +### 3.6 切换显示/隐藏 +``` +POST /api/models/{model_id}/visible +``` + +### 3.7 置顶/取消置顶 +``` +POST /api/models/{model_id}/pin +``` + +### 3.8 增加阅读数 +``` +POST /api/models/{model_id}/view +``` + +### 3.9 导出模型 +``` +GET /api/models/export +``` + +### 3.10 导入模型 +``` +POST /api/models/import?mode=merge|replace +Content-Type: application/json + +请求体： +{ + "type": "models", + "items": [...] +} +``` + +--- + +## 4. GPU API + +### 4.1 获取GPU列表 +``` +GET /api/gpus +GET /api/gpus?all=1 +GET /api/gpus?q=关键词 +GET /api/gpus?sort=memory_gb&order=desc +``` + +### 4.2 获取GPU详情 +``` +GET /api/gpus/{gpu_id} +``` + +### 4.3 创建GPU +``` +POST /api/gpus +Content-Type: application/json + +请求体： +{ + "name": "GPU名称", + "manufacturer": "NVIDIA", + "memory_gb": 80, + "cuda_cores": 10752, + "tensor_cores": 336, + "price_usd": 30000, + "release_year": 2024, + "visible": true, + "is_pinned": false +} +``` + +### 4.4 更新GPU +``` +PUT /api/gpus/{gpu_id} +``` + +### 4.5 删除GPU +``` +DELETE /api/gpus/{gpu_id} +``` + +### 4.6 切换显示/隐藏 +``` +POST /api/gpus/{gpu_id}/visible +``` + +### 4.7 置顶/取消置顶 +``` +POST /api/gpus/{gpu_id}/pin +``` + +### 4.8 增加阅读数 +``` +POST /api/gpus/{gpu_id}/view +``` + +### 4.9 导出GPU +``` +GET /api/gpus/export +``` + +### 4.10 导入GPU +``` +POST /api/gpus/import?mode=merge|replace +``` + +--- + +## 5. CPU API + +### 5.1 获取CPU列表 +``` +GET /api/cpus +GET /api/cpus?all=1 +GET /api/cpus?q=关键词 +GET /api/cpus?sort=cores&order=desc +``` + +### 5.2 获取CPU详情 +``` +GET /api/cpus/{cpu_id} +``` + +### 5.3 创建CPU +``` +POST /api/cpus +Content-Type: application/json + +请求体： +{ + "name": "CPU名称", + "manufacturer": "AMD", + "cores": 64, + "threads": 128, + "base_clock": 2.4, + "boost_clock": 3.7, + "price_usd": 8000, + "visible": true, + "is_pinned": false +} +``` + +### 5.4 更新CPU +``` +PUT /api/cpus/{cpu_id} +``` + +### 5.5 删除CPU +``` +DELETE /api/cpus/{cpu_id} +``` + +### 5.6 切换显示/隐藏 +``` +POST /api/cpus/{cpu_id}/visible +``` + +### 5.7 置顶/取消置顶 +``` +POST /api/cpus/{cpu_id}/pin +``` + +### 5.8 增加阅读数 +``` +POST /api/cpus/{cpu_id}/view +``` + +### 5.9 导出CPU +``` +GET /api/cpus/export +``` + +### 5.10 导入CPU +``` +POST /api/cpus/import?mode=merge|replace +``` + +--- + +## 6. 动态分类数据 API + +### 6.1 获取分类数据列表 +``` +GET /api/items/{category_id} +GET /api/items/{category_id}?all=1 +GET /api/items/{category_id}?sort=price&order=desc +``` + +### 6.2 获取数据详情 +``` +GET /api/items/{category_id}/{item_id} +``` + +### 6.3 创建数据 +``` +POST /api/items/{category_id} +Content-Type: application/json + +请求体： +{ + "name": "名称", + "visible": true, + "is_pinned": false, + // ... 其他动态字段 +} +``` + +### 6.4 更新数据 +``` +PUT /api/items/{category_id}/{item_id} +``` + +### 6.5 删除数据 +``` +DELETE /api/items/{category_id}/{item_id} +``` + +### 6.6 切换显示/隐藏 +``` +POST /api/items/{category_id}/{item_id}/visible +``` + +### 6.7 置顶/取消置顶 +``` +POST /api/items/{category_id}/{item_id}/pin +``` + +### 6.8 增加阅读数 +``` +POST /api/items/{category_id}/{item_id}/view +``` + +### 6.9 导出分类数据 +``` +GET /api/items/{category_id}/export +``` + +### 6.10 导入分类数据 +``` +POST /api/items/{category_id}/import?mode=merge|replace +``` + +--- + +## 7. 知识库 API + +### 7.1 获取知识库列表 +``` +GET /api/knowledge +GET /api/knowledge?all=1 +GET /api/knowledge?q=关键词 +GET /api/knowledge?category=分类名 +``` + +### 7.2 获取知识详情 +``` +GET /api/knowledge/{knowledge_id} +``` + +### 7.3 创建知识 +``` +POST /api/knowledge +Content-Type: application/json + +请求体： +{ + "title": "标题", + "content": "内容", + "category": "分类", + "order": 0, + "visible": true +} +``` + +### 7.4 更新知识 +``` +PUT /api/knowledge/{knowledge_id} +``` + +### 7.5 删除知识 +``` +DELETE /api/knowledge/{knowledge_id} +``` + +### 7.6 切换显示/隐藏 +``` +POST /api/knowledge/{knowledge_id}/visible +``` + +--- + +## 8. 审核系统 API + +### 8.1 获取待审核列表 +``` +GET /api/reviews +GET /api/reviews?status=pending // 待审核 +GET /api/reviews?status=approved // 已通过 +GET /api/reviews?status=rejected // 已拒绝 +GET /api/reviews?status=all // 全部 +``` + +### 8.2 获取待审核数量 +``` +GET /api/reviews/count +``` + +### 8.3 获取审核详情 +``` +GET /api/reviews/{review_id} +``` + +### 8.4 通过审核 +``` +POST /api/reviews/{review_id}/approve +``` + +### 8.5 拒绝审核 +``` +POST /api/reviews/{review_id}/reject +Content-Type: application/json + +请求体： +{ + "reason": "拒绝原因" +} +``` + +--- + +## 9. 通知系统 API + +### 9.1 获取通知列表 +``` +GET /api/notifications +GET /api/notifications?unread=1 // 仅未读 +GET /api/notifications?limit=20 +``` + +### 9.2 获取未读数量 +``` +GET /api/notifications/unread-count +``` + +### 9.3 标记已读 +``` +POST /api/notifications/{notification_id}/read +``` + +### 9.4 全部标记已读 +``` +POST /api/notifications/read-all +``` + +### 9.5 删除通知 +``` +DELETE /api/notifications/{notification_id} +``` + +--- + +## 10. 智能解析 API + +### 10.1 获取解析提示词模板 +``` +POST /api/parse-prompt +Content-Type: application/json + +请求体： +{ + "category_type": "model|gpu|cpu|dynamic", + "category_id": "分类ID", + "subcategory_id": "子分类ID" +} +``` + +### 10.2 图片解析 +``` +POST /api/parse-images +Content-Type: application/json + +请求体： +{ + "text": "附加文本描述", + "images": ["图片URL或Base64"], + "category_type": "model|gpu|cpu|dynamic", + "subcategory_id": "子分类ID", + "custom_prompt": "自定义提示词" +} + +响应： +{ + "success": true, + "count": 1, + "products": [解析结果] +} +``` + +### 10.3 智能添加 - AI模型 +``` +POST /api/models/smart-add +Content-Type: application/json + +请求体： +{ + "text": "文本描述", + "images": ["图片URL"], + "subcategory_id": "子分类ID", + "custom_prompt": "自定义提示词" +} +``` + +### 10.4 智能添加 - GPU +``` +POST /api/gpus/smart-add +``` + +### 10.5 智能添加 - CPU +``` +POST /api/cpus/smart-add +``` + +### 10.6 智能添加 - 动态分类 +``` +POST /api/items/{category_id}/smart-add +``` + +### 10.7 智能补充 - AI模型 +``` +POST /api/models/{model_id}/smart-update +Content-Type: application/json + +请求体： +{ + "text": "补充信息文本", + "images": ["图片URL"] +} + +响应： +{ + "success": true, + "updated_fields": ["field1", "field2"], + "model": 更新后的模型数据 +} +``` + +### 10.8 智能补充 - GPU +``` +POST /api/gpus/{gpu_id}/smart-update +``` + +### 10.9 智能补充 - CPU +``` +POST /api/cpus/{cpu_id}/smart-update +``` + +### 10.10 智能补充 - 动态分类 +``` +POST /api/items/{category_id}/{item_id}/smart-update +``` + +--- + +## 11. 搜索与统计 API + +### 11.1 全局搜索 +``` +GET /api/search?q=关键词 + +响应： +{ + "models": [...], + "gpus": [...], + "cpus": [...] +} +``` + +### 11.2 显存计算 +``` +GET /api/calculate/vram?params=7&precision=fp16 + +参数： +- params: 模型参数量（单位：B） +- precision: 精度 (fp32|fp16|int8|int4) + +响应： +{ + "model_vram": 14.0, // 模型显存需求(GB) + "total_vram": 18.2, // 总显存需求(含30%余量) + "suitable_gpus": [...] // 适用GPU列表 +} +``` + +### 11.3 统计数据 +``` +GET /api/stats + +响应： +{ + "models_count": 10, + "gpus_count": 5, + "cpus_count": 8, + "categories_count": 3, + "knowledge_count": 20, + "latest_models": [...] +} +``` + +--- + +## 12. 网站配置 API + +### 12.1 获取配置 +``` +GET /api/config + +响应： +{ + "site_name": "ParamHub", + "admin_password": "admin123", + ... +} +``` + +### 12.2 更新配置 +``` +PUT /api/config +Content-Type: application/json + +请求体： +{ + "site_name": "新名称", + "admin_password": "新密码" +} +``` + +--- + +## 13. 图片上传 API + +### 13.1 上传图片（文件） +``` +POST /api/upload/image +Content-Type: multipart/form-data + +请求体： +- file: 图片文件 + +响应： +{ + "success": true, + "filename": "abc123_1234567890.png", + "url": "/static/uploads/abc123_1234567890.png" +} +``` + +### 13.2 上传图片（Base64） +``` +POST /api/upload/image/base64 +Content-Type: application/json + +请求体： +{ + "image": "data:image/png;base64,xxxxx...", + "ext": "png" +} +``` + +### 13.3 删除图片 +``` +DELETE /api/upload/image/delete/{filename} +``` + +--- + +## 错误响应 + +所有 API 错误响应格式： +```json +{ + "error": "错误信息" +} +``` + +常见错误码： +- `400` - 请求参数错误 +- `401` - 未登录 +- `404` - 资源不存在 +- `500` - 服务器错误 + +--- + +## 审核模式说明 + +当系统开启审核模式（`REQUIRE_REVIEW = True`）时： + +1. 创建产品（POST /api/models, /api/gpus, /api/cpus, /api/items/{category_id}）时： + - 数据不会直接入库 + - 而是提交到审核队列 + - 返回 `{ "success": true, "message": "已提交审核", "review_id": "xxx" }` + +2. 管理员需通过审核 API 确认： + - `POST /api/reviews/{review_id}/approve` - 通过 + - `POST /api/reviews/{review_id}/reject` - 拒绝 + +--- + +## 变更日志 + +| 日期 | 变更内容 | +|------|----------| +| 2026-07-11 | 初始版本，记录所有 API 能力 | \ No newline at end of file diff --git a/README.md b/README.md index 63b2478..d2da9ba 100644 --- a/README.md +++ b/README.md @@ -54,18 +54,27 @@ param-hub-python/ ## API接口 -| 接口 | 方法 | 说明 | -|------|------|------| -| `/api/models` | GET | 获取模型列表 | -| `/api/models/` | GET | 获取模型详情 | -| `/api/gpus` | GET | 获取GPU列表 | -| `/api/gpus/` | GET | 获取GPU详情 | -| `/api/cpus` | GET | 获取CPU列表 | -| `/api/cpus/` | GET | 获取CPU详情 | -| `/api/search` | GET | 全局搜索 | -| `/api/calculate/vram` | GET | 显存计算 | -| `/api/stats` | GET | 统计数据 | +完整 API 能力文档请查看 [API.md](API.md) + +### 快速参考 + +| 模块 | 主要接口 | +|------|----------| +| 认证 | `/login`, `/logout` | +| 分类 | `/api/categories` CRUD + 导入导出 | +| AI模型 | `/api/models` CRUD + 置顶 + 热度 + 导入导出 | +| GPU | `/api/gpus` CRUD + 置顶 + 热度 + 导入导出 | +| CPU | `/api/cpus` CRUD + 置顶 + 热度 + 导入导出 | +| 动态分类 | `/api/items/{category_id}` CRUD | +| 知识库 | `/api/knowledge` CRUD | +| 审核 | `/api/reviews` 审核通过/拒绝 | +| 通知 | `/api/notifications` 通知管理 | +| 智能解析 | `/api/parse-images`, `/api/*/smart-add`, `/api/*/smart-update` | +| 搜索统计 | `/api/search`, `/api/calculate/vram`, `/api/stats` | +| 配置 | `/api/config` | +| 图片上传 | `/api/upload/image` | ## 版本 +- v2.0.0 - 产品审核发布 + 后台通知系统 + 完整API能力 - v0.1.0 - 初始版本 \ No newline at end of file