first commit
This commit is contained in:
717
docs/api-reference.md
Normal file
717
docs/api-reference.md
Normal file
@@ -0,0 +1,717 @@
|
||||
# 智能算法展示平台 API 文档
|
||||
|
||||
## 概述
|
||||
|
||||
智能算法展示平台提供了一套完整的API，用于管理算法、调用算法以及获取结果。API遵循RESTful设计原则，返回JSON格式的数据。
|
||||
|
||||
### 基础URL
|
||||
|
||||
```
|
||||
http://localhost:8000/api/v1
|
||||
```
|
||||
|
||||
### 认证
|
||||
|
||||
大多数API端点需要认证。认证通过在请求头中添加 `Authorization` 字段实现：
|
||||
|
||||
```
|
||||
Authorization: Bearer <your-token>
|
||||
```
|
||||
|
||||
## 算法管理API
|
||||
|
||||
### 获取算法列表
|
||||
|
||||
**GET** `/algorithms`
|
||||
|
||||
获取所有可用算法的列表。
|
||||
|
||||
#### 参数
|
||||
- `type` (可选): 算法类型 (computer_vision, nlp, ml等)
|
||||
- `skip` (可选): 跳过的记录数，默认为0
|
||||
- `limit` (可选): 返回的最大记录数，默认为100
|
||||
|
||||
#### 响应
|
||||
```json
|
||||
{
|
||||
"algorithms": [
|
||||
{
|
||||
"id": "alg-001",
|
||||
"name": "图像分类算法",
|
||||
"description": "基于深度学习的图像分类算法",
|
||||
"type": "computer_vision",
|
||||
"status": "active",
|
||||
"versions": [],
|
||||
"created_at": "2023-01-01T00:00:00Z",
|
||||
"updated_at": "2023-01-01T00:00:00Z"
|
||||
}
|
||||
],
|
||||
"total": 1
|
||||
}
|
||||
```
|
||||
|
||||
### 获取算法详情
|
||||
|
||||
**GET** `/algorithms/{algorithm_id}`
|
||||
|
||||
获取特定算法的详细信息。
|
||||
|
||||
#### 参数
|
||||
- `algorithm_id`: 算法ID
|
||||
|
||||
#### 响应
|
||||
```json
|
||||
{
|
||||
"id": "alg-001",
|
||||
"name": "图像分类算法",
|
||||
"description": "基于深度学习的图像分类算法",
|
||||
"type": "computer_vision",
|
||||
"status": "active",
|
||||
"versions": [
|
||||
{
|
||||
"id": "ver-001",
|
||||
"algorithm_id": "alg-001",
|
||||
"version": "v1.0",
|
||||
"url": "http://algorithm-service:8000/classify",
|
||||
"params": {
|
||||
"confidence_threshold": {
|
||||
"type": "float",
|
||||
"default": 0.5,
|
||||
"min": 0.0,
|
||||
"max": 1.0
|
||||
}
|
||||
},
|
||||
"input_schema": {},
|
||||
"output_schema": {},
|
||||
"is_default": true,
|
||||
"created_at": "2023-01-01T00:00:00Z",
|
||||
"updated_at": "2023-01-01T00:00:00Z"
|
||||
}
|
||||
],
|
||||
"created_at": "2023-01-01T00:00:00Z",
|
||||
"updated_at": "2023-01-01T00:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
### 创建算法
|
||||
|
||||
**POST** `/algorithms`
|
||||
|
||||
创建新算法（需要管理员权限）。
|
||||
|
||||
#### 请求体
|
||||
```json
|
||||
{
|
||||
"name": "新算法",
|
||||
"description": "算法描述",
|
||||
"type": "ml",
|
||||
"status": "active"
|
||||
}
|
||||
```
|
||||
|
||||
#### 响应
|
||||
```json
|
||||
{
|
||||
"id": "alg-002",
|
||||
"name": "新算法",
|
||||
"description": "算法描述",
|
||||
"type": "ml",
|
||||
"status": "active",
|
||||
"versions": [],
|
||||
"created_at": "2023-01-01T00:00:00Z",
|
||||
"updated_at": "2023-01-01T00:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
## 算法调用API
|
||||
|
||||
### 调用算法
|
||||
|
||||
**POST** `/algorithms/call`
|
||||
|
||||
调用指定算法。
|
||||
|
||||
#### 请求体
|
||||
```json
|
||||
{
|
||||
"algorithm_id": "alg-001",
|
||||
"version_id": "ver-001",
|
||||
"input_data": {
|
||||
"image_url": "https://example.com/image.jpg"
|
||||
},
|
||||
"params": {
|
||||
"confidence_threshold": 0.7
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 响应
|
||||
```json
|
||||
{
|
||||
"id": "call-001",
|
||||
"user_id": "user-001",
|
||||
"algorithm_id": "alg-001",
|
||||
"version_id": "ver-001",
|
||||
"input_data": {
|
||||
"image_url": "https://example.com/image.jpg"
|
||||
},
|
||||
"params": {
|
||||
"confidence_threshold": 0.7
|
||||
},
|
||||
"output_data": {
|
||||
"predictions": [
|
||||
{
|
||||
"class": "cat",
|
||||
"confidence": 0.95
|
||||
}
|
||||
]
|
||||
},
|
||||
"status": "success",
|
||||
"response_time": 1.2,
|
||||
"error_message": null,
|
||||
"created_at": "2023-01-01T00:00:00Z",
|
||||
"updated_at": "2023-01-01T00:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
### 获取调用结果
|
||||
|
||||
**GET** `/algorithms/calls/{call_id}`
|
||||
|
||||
获取特定调用的结果。
|
||||
|
||||
#### 参数
|
||||
- `call_id`: 调用ID
|
||||
|
||||
#### 响应
|
||||
```json
|
||||
{
|
||||
"id": "call-001",
|
||||
"user_id": "user-001",
|
||||
"algorithm_id": "alg-001",
|
||||
"version_id": "ver-001",
|
||||
"input_data": {
|
||||
"image_url": "https://example.com/image.jpg"
|
||||
},
|
||||
"params": {
|
||||
"confidence_threshold": 0.7
|
||||
},
|
||||
"output_data": {
|
||||
"predictions": [
|
||||
{
|
||||
"class": "cat",
|
||||
"confidence": 0.95
|
||||
}
|
||||
]
|
||||
},
|
||||
"status": "success",
|
||||
"response_time": 1.2,
|
||||
"error_message": null,
|
||||
"created_at": "2023-01-01T00:00:00Z",
|
||||
"updated_at": "2023-01-01T00:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
## 用户管理API
|
||||
|
||||
### 用户登录
|
||||
|
||||
**POST** `/users/login`
|
||||
|
||||
用户登录并获取访问令牌。
|
||||
|
||||
#### 请求体
|
||||
```json
|
||||
{
|
||||
"username": "testuser",
|
||||
"password": "password123"
|
||||
}
|
||||
```
|
||||
|
||||
#### 响应
|
||||
```json
|
||||
{
|
||||
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||||
"token_type": "bearer"
|
||||
}
|
||||
```
|
||||
|
||||
## 历史记录API
|
||||
|
||||
### 获取调用历史
|
||||
|
||||
**GET** `/history/user-calls`
|
||||
|
||||
获取用户的调用历史。
|
||||
|
||||
#### 参数
|
||||
- `algorithm_id` (可选): 算法ID
|
||||
- `status` (可选): 调用状态
|
||||
- `start_date` (可选): 开始日期
|
||||
- `end_date` (可选): 结束日期
|
||||
- `skip` (可选): 跳过的记录数
|
||||
- `limit` (可选): 返回的最大记录数
|
||||
|
||||
#### 响应
|
||||
```json
|
||||
{
|
||||
"history": [
|
||||
{
|
||||
"id": "call-001",
|
||||
"user_id": "user-001",
|
||||
"algorithm_id": "alg-001",
|
||||
"version_id": "ver-001",
|
||||
"input_data": {},
|
||||
"params": {},
|
||||
"output_data": {},
|
||||
"status": "success",
|
||||
"response_time": 1.2,
|
||||
"error_message": null,
|
||||
"created_at": "2023-01-01T00:00:00Z",
|
||||
"updated_at": "2023-01-01T00:00:00Z"
|
||||
}
|
||||
],
|
||||
"count": 1,
|
||||
"skip": 0,
|
||||
"limit": 100
|
||||
}
|
||||
```
|
||||
|
||||
### 获取调用统计
|
||||
|
||||
**GET** `/history/statistics`
|
||||
|
||||
获取调用统计信息。
|
||||
|
||||
#### 参数
|
||||
- `user_id` (可选): 用户ID
|
||||
- `algorithm_id` (可选): 算法ID
|
||||
|
||||
#### 响应
|
||||
```json
|
||||
{
|
||||
"total_calls": 156,
|
||||
"status_counts": {
|
||||
"success": 145,
|
||||
"failed": 11
|
||||
},
|
||||
"success_rate": 92.3,
|
||||
"avg_response_time": 1.45,
|
||||
"today_calls": 12
|
||||
}
|
||||
```
|
||||
|
||||
## 监控API
|
||||
|
||||
### 获取系统健康状况
|
||||
|
||||
**GET** `/monitoring/health`
|
||||
|
||||
获取系统健康状况。
|
||||
|
||||
#### 响应
|
||||
```json
|
||||
{
|
||||
"status": "healthy",
|
||||
"timestamp": "2023-01-01T00:00:00Z",
|
||||
"system_metrics": {
|
||||
"cpu_percent": 25.5,
|
||||
"memory_percent": 45.2,
|
||||
"disk_percent": 60.1
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 获取算法性能指标
|
||||
|
||||
**GET** `/monitoring/performance/algorithm/{algorithm_id}`
|
||||
|
||||
获取特定算法的性能指标。
|
||||
|
||||
#### 参数
|
||||
- `algorithm_id`: 算法ID
|
||||
- `days`: 统计天数（默认为7）
|
||||
|
||||
#### 响应
|
||||
```json
|
||||
{
|
||||
"algorithm_id": "alg-001",
|
||||
"period_days": 7,
|
||||
"total_calls": 50,
|
||||
"success_calls": 48,
|
||||
"failed_calls": 2,
|
||||
"success_rate": 96.0,
|
||||
"average_response_time": 1.234,
|
||||
"status_distribution": {
|
||||
"success": 48,
|
||||
"failed": 2
|
||||
},
|
||||
"timestamp": "2023-01-01T00:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
## 权限管理API
|
||||
|
||||
### 检查权限
|
||||
|
||||
**POST** `/permissions/check`
|
||||
|
||||
检查用户对特定算法的权限。
|
||||
|
||||
#### 请求体
|
||||
```json
|
||||
{
|
||||
"algorithm_id": "alg-001",
|
||||
"permission_type": "execute"
|
||||
}
|
||||
```
|
||||
|
||||
#### 响应
|
||||
```json
|
||||
{
|
||||
"has_permission": true,
|
||||
"user_id": "user-001",
|
||||
"algorithm_id": "alg-001",
|
||||
"permission_type": "execute"
|
||||
}
|
||||
```
|
||||
|
||||
## OpenAI集成API
|
||||
|
||||
### 生成仿真数据
|
||||
|
||||
**POST** `/openai/generate-data`
|
||||
|
||||
使用OpenAI生成仿真输入数据。
|
||||
|
||||
#### 请求体
|
||||
```json
|
||||
{
|
||||
"prompt": "一张包含猫和狗的照片",
|
||||
"data_type": "image"
|
||||
}
|
||||
```
|
||||
|
||||
#### 响应
|
||||
```json
|
||||
{
|
||||
"data": "生成的仿真数据",
|
||||
"type": "image"
|
||||
}
|
||||
```
|
||||
|
||||
## API网关API
|
||||
|
||||
### 通过网关调用算法
|
||||
|
||||
**POST** `/gateway/call`
|
||||
|
||||
通过API网关调用算法，提供统一的访问接口和安全控制。
|
||||
|
||||
#### 请求体
|
||||
```json
|
||||
{
|
||||
"algorithm_id": "alg-001",
|
||||
"version_id": "ver-001",
|
||||
"input_data": {
|
||||
"image_url": "https://example.com/image.jpg"
|
||||
},
|
||||
"params": {
|
||||
"confidence_threshold": 0.7
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 响应
|
||||
```json
|
||||
{
|
||||
"id": "call-001",
|
||||
"user_id": "user-001",
|
||||
"algorithm_id": "alg-001",
|
||||
"version_id": "ver-001",
|
||||
"input_data": {
|
||||
"image_url": "https://example.com/image.jpg"
|
||||
},
|
||||
"params": {
|
||||
"confidence_threshold": 0.7
|
||||
},
|
||||
"output_data": {
|
||||
"predictions": [
|
||||
{
|
||||
"class": "cat",
|
||||
"confidence": 0.95
|
||||
}
|
||||
]
|
||||
},
|
||||
"status": "success",
|
||||
"response_time": 1.2,
|
||||
"error_message": null,
|
||||
"created_at": "2023-01-01T00:00:00Z",
|
||||
"updated_at": "2023-01-01T00:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
### 获取网关统计信息
|
||||
|
||||
**GET** `/gateway/stats`
|
||||
|
||||
获取API网关的调用统计信息。
|
||||
|
||||
#### 响应
|
||||
```json
|
||||
{
|
||||
"total_requests": 1250,
|
||||
"successful_requests": 1200,
|
||||
"failed_requests": 50,
|
||||
"blocked_requests": 10,
|
||||
"rate_limited_requests": 40,
|
||||
"last_updated": "2023-01-01T00:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
## 算法仓库管理API
|
||||
|
||||
### 获取算法仓库列表
|
||||
|
||||
**GET** `/repositories`
|
||||
|
||||
获取所有算法仓库的列表。
|
||||
|
||||
#### 响应
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"repositories": [
|
||||
{
|
||||
"id": "repo-001",
|
||||
"name": "图像分类算法仓库",
|
||||
"description": "图像分类算法的代码仓库",
|
||||
"type": "code",
|
||||
"repo_url": "https://gitea.example.com/owner/repo.git",
|
||||
"branch": "main",
|
||||
"local_path": "",
|
||||
"algorithm_id": null,
|
||||
"status": "active",
|
||||
"created_at": "2023-01-01T00:00:00Z",
|
||||
"updated_at": "2023-01-01T00:00:00Z"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 获取单个算法仓库详情
|
||||
|
||||
**GET** `/repositories/{repo_id}`
|
||||
|
||||
获取特定算法仓库的详细信息。
|
||||
|
||||
#### 参数
|
||||
- `repo_id`: 仓库ID
|
||||
|
||||
#### 响应
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"repository": {
|
||||
"id": "repo-001",
|
||||
"name": "图像分类算法仓库",
|
||||
"description": "图像分类算法的代码仓库",
|
||||
"type": "code",
|
||||
"repo_url": "https://gitea.example.com/owner/repo.git",
|
||||
"branch": "main",
|
||||
"local_path": "",
|
||||
"algorithm_id": null,
|
||||
"status": "active",
|
||||
"created_at": "2023-01-01T00:00:00Z",
|
||||
"updated_at": "2023-01-01T00:00:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 添加算法仓库
|
||||
|
||||
**POST** `/repositories`
|
||||
|
||||
添加新的算法仓库。
|
||||
|
||||
#### 请求体
|
||||
```json
|
||||
{
|
||||
"name": "新算法仓库",
|
||||
"description": "新算法的代码仓库",
|
||||
"type": "code",
|
||||
"repo_url": "https://gitea.example.com/owner/repo.git",
|
||||
"branch": "main",
|
||||
"local_path": ""
|
||||
}
|
||||
```
|
||||
|
||||
#### 响应
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Repository created successfully",
|
||||
"repository": {
|
||||
"id": "repo-002",
|
||||
"name": "新算法仓库",
|
||||
"description": "新算法的代码仓库",
|
||||
"type": "code",
|
||||
"repo_url": "https://gitea.example.com/owner/repo.git",
|
||||
"branch": "main",
|
||||
"local_path": "",
|
||||
"algorithm_id": null,
|
||||
"status": "active",
|
||||
"created_at": "2023-01-01T00:00:00Z",
|
||||
"updated_at": "2023-01-01T00:00:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 更新算法仓库
|
||||
|
||||
**PUT** `/repositories/{repo_id}`
|
||||
|
||||
更新特定算法仓库的信息。
|
||||
|
||||
#### 参数
|
||||
- `repo_id`: 仓库ID
|
||||
|
||||
#### 请求体
|
||||
```json
|
||||
{
|
||||
"name": "更新后的算法仓库",
|
||||
"description": "更新后的算法仓库描述",
|
||||
"type": "code"
|
||||
}
|
||||
```
|
||||
|
||||
#### 响应
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Repository updated successfully",
|
||||
"repository": {
|
||||
"id": "repo-001",
|
||||
"name": "更新后的算法仓库",
|
||||
"description": "更新后的算法仓库描述",
|
||||
"type": "code",
|
||||
"repo_url": "https://gitea.example.com/owner/repo.git",
|
||||
"branch": "main",
|
||||
"local_path": "",
|
||||
"algorithm_id": null,
|
||||
"status": "active",
|
||||
"created_at": "2023-01-01T00:00:00Z",
|
||||
"updated_at": "2023-01-01T00:00:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 删除算法仓库
|
||||
|
||||
**DELETE** `/repositories/{repo_id}`
|
||||
|
||||
删除特定的算法仓库。
|
||||
|
||||
#### 参数
|
||||
- `repo_id`: 仓库ID
|
||||
|
||||
#### 响应
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Repository deleted successfully",
|
||||
"gitea_deleted": true
|
||||
}
|
||||
```
|
||||
|
||||
## Gitea集成API
|
||||
|
||||
### 获取Gitea配置
|
||||
|
||||
**GET** `/gitea/config`
|
||||
|
||||
获取Gitea配置信息。
|
||||
|
||||
#### 响应
|
||||
```json
|
||||
{
|
||||
"server_url": "https://gitea.example.com",
|
||||
"access_token": "your-access-token",
|
||||
"default_owner": "owner",
|
||||
"repo_prefix": "alg-"
|
||||
}
|
||||
```
|
||||
|
||||
### 设置Gitea配置
|
||||
|
||||
**POST** `/gitea/config`
|
||||
|
||||
设置Gitea配置信息。
|
||||
|
||||
#### 请求体
|
||||
```json
|
||||
{
|
||||
"server_url": "https://gitea.example.com",
|
||||
"access_token": "your-access-token",
|
||||
"default_owner": "owner",
|
||||
"repo_prefix": "alg-"
|
||||
}
|
||||
```
|
||||
|
||||
#### 响应
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Gitea config saved successfully"
|
||||
}
|
||||
```
|
||||
|
||||
### 创建Gitea仓库
|
||||
|
||||
**POST** `/gitea/repos/create`
|
||||
|
||||
在Gitea上创建仓库。
|
||||
|
||||
#### 请求体
|
||||
```json
|
||||
{
|
||||
"algorithm_id": "alg-001",
|
||||
"algorithm_name": "图像分类算法",
|
||||
"description": "图像分类算法的代码仓库"
|
||||
}
|
||||
```
|
||||
|
||||
#### 响应
|
||||
```json
|
||||
{
|
||||
"id": 1,
|
||||
"name": "alg-001",
|
||||
"full_name": "owner/alg-001",
|
||||
"description": "图像分类算法的代码仓库",
|
||||
"private": false,
|
||||
"html_url": "https://gitea.example.com/owner/alg-001"
|
||||
}
|
||||
```
|
||||
|
||||
### 更新Gitea仓库信息
|
||||
|
||||
**PATCH** `/gitea/repos/update`
|
||||
|
||||
更新Gitea仓库信息。
|
||||
|
||||
#### 请求体
|
||||
```json
|
||||
{
|
||||
"algorithm_id": "alg-001",
|
||||
"description": "更新后的仓库描述",
|
||||
"private": false
|
||||
}
|
||||
```
|
||||
|
||||
#### 响应
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Repository updated successfully"
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user