admin
29a1a87e52
- 后端 SAM2 引擎新增 sam2.1_hiera_tiny、sam2.1_hiera_small、sam2.1_hiera_base_plus、sam2.1_hiera_large 四个变体定义，并按变体维护 checkpoint/config、image predictor、video predictor、加载状态、错误信息和真实状态回报。 - 后端 SAM registry 仅暴露当前产品启用的 SAM2.1 变体，保留 sam2 作为 tiny 兼容别名，拒绝 sam3 产品入口，并把 point、box、interactive、auto、propagate 都分发到所选 SAM2.1 变体。 - 后端默认配置和下载脚本切换到 SAM2.1 checkpoint 命名，支持 legacy SAM2 checkpoint fallback，并在状态消息中标出 fallback 使用情况。 - 前端全局 AI 模型状态新增 SAM2.1 tiny/small/base+/large 类型和默认 tiny，API 请求默认携带 sam2.1_hiera_tiny，AI 页面提供模型变体选择和所选模型状态展示。 - AI 智能分割页移除当前产品不使用的 SAM3/文本提示入口，保留正向点、反向点、框选和参数开关；AI 页只展示本页生成的候选 mask，并支持遮罩清晰度调节、候选 mask 上继续加正/反点、清空本页候选、推送到工作区编辑。 - 工作区和 Canvas 补强 SAM2 交互式细化链路：框选后正/反点继续细化同一个候选 mask，反向点请求启用背景过滤，空结果会移除被否定候选；AI 推送到工作区后保留选中态和未保存 draft mask。 - 工作区标注保存闭环补强：未保存 mask 可归档保存，dirty saved mask 可更新，保存后用后端 saved annotation 替换已提交 draft，清空/删除已保存 mask 时同步后端删除。 - Dashboard 任务进度区改为展示 queued、running、success、failed、cancelled 最近任务，处理中统计只计算 queued/running，并保留近期完成记录。 - 时间轴在顶部时间进度条和底部缩略图导航轴之间新增已编辑帧标记带，基于当前项目帧内 masks 标出已有编辑/标注的帧，并支持点击标记跳转。 - 前端测试覆盖 SAM2.1 变体选择、模型状态徽标、AI 页候选隔离、遮罩透明度、候选上追加正/反点、推送工作区保留选择、Canvas 交互式细化、VideoWorkspace 传播/保存、Dashboard 进度和时间轴已编辑帧标记。 - 后端测试覆盖 SAM2.1 变体状态、sam2 alias 兼容、sam3 禁用、semantic 禁用、传播标注保存、Dashboard 最近任务状态和 SAM3 历史测试跳过说明。 - README、AGENTS 和 doc 文档同步当前真实进度，更新 SAM2.1 变体、SAM3 禁用、接口契约、设计冻结、需求冻结、前端元素审计、实施计划、FastAPI docs 说明和测试矩阵。
104 lines
3.2 KiB
Markdown
104 lines
3.2 KiB
Markdown
# `/docs` 是什么
|
||
|
||
地址：
|
||
|
||
- 本机：`http://localhost:8000/docs`
|
||
- 局域网：`http://192.168.3.11:8000/docs`
|
||
|
||
这个页面不是文件列表，也不是项目文档目录。它是 FastAPI 自动生成的 Swagger UI，用来展示和调试后端 HTTP API。
|
||
|
||
## 为什么会自动出现
|
||
|
||
FastAPI 会根据代码里的路由和 Pydantic schema 自动生成 OpenAPI 描述，然后用 Swagger UI 展示出来。
|
||
|
||
相关代码在：
|
||
|
||
- `backend/main.py` 创建 `FastAPI(...)`
|
||
- `backend/routers/*.py` 定义 `@router.get(...)`、`@router.post(...)` 等接口
|
||
- `backend/schemas.py` 定义请求体和响应体
|
||
|
||
## 页面上 GET / POST / PATCH / DELETE 是什么
|
||
|
||
这些是 HTTP 方法，不是文件。
|
||
|
||
| 方法 | 含义 | 例子 |
|
||
|------|------|------|
|
||
| GET | 读取数据 | `GET /api/projects` 获取项目列表 |
|
||
| POST | 创建或触发动作 | `POST /api/media/upload` 上传文件 |
|
||
| PATCH | 局部更新 | `PATCH /api/templates/{template_id}` 更新模板 |
|
||
| DELETE | 删除 | `DELETE /api/projects/{project_id}` 删除项目 |
|
||
|
||
你看到的每一行，都是后端暴露给前端调用的一个接口。
|
||
|
||
## `/docs` 能做什么
|
||
|
||
可以：
|
||
|
||
- 查看后端目前有哪些接口。
|
||
- 展开接口查看参数、请求体和响应格式。
|
||
- 点击 `Try it out` 直接发请求测试后端。
|
||
- 检查接口返回错误，比如 400、401、404、500。
|
||
|
||
不能：
|
||
|
||
- 查看前端页面源码。
|
||
- 直接代表某个功能已经完整可用。
|
||
- 展示 WebSocket 的完整交互，因为 OpenAPI 主要描述 HTTP 接口。
|
||
|
||
## 和前端有什么关系
|
||
|
||
前端的 `src/lib/api.ts` 会调用这些接口。例如：
|
||
|
||
- 登录页调用 `/api/auth/login`
|
||
- 项目库调用 `/api/projects`
|
||
- 上传视频调用 `/api/media/upload`
|
||
- 拆帧调用 `/api/media/parse`
|
||
- 模板库调用 `/api/templates`
|
||
|
||
所以 `/docs` 是检查“后端提供了什么”的地方；前端是否真的用对了，还要对照 `src/lib/api.ts`。
|
||
|
||
## 目前通过 `/docs` 能看到的接口
|
||
|
||
当前后端接口包括：
|
||
|
||
- Auth：登录
|
||
- Projects：项目 CRUD、项目帧 CRUD
|
||
- Templates：模板 CRUD
|
||
- Media：上传视频/DICOM、触发拆帧
|
||
- AI：当前启用 SAM 2 推理、模型状态、自动分割、保存标注；SAM 3 源码保留但产品入口禁用
|
||
- Export：导出 COCO JSON、导出 PNG masks
|
||
- Health：健康检查
|
||
|
||
## 为什么看起来像“列举文件和请求”
|
||
|
||
因为 Swagger UI 默认按接口分组，把每个 endpoint 展开成一行。它列举的是“后端可被调用的功能入口”，不是项目文件。
|
||
|
||
真正的项目文件在本地目录里，例如：
|
||
|
||
- 前端：`src/components/*.tsx`
|
||
- 后端路由：`backend/routers/*.py`
|
||
- 后端模型：`backend/models.py`
|
||
|
||
## 如何用 `/docs` 验证一个接口
|
||
|
||
以项目列表为例：
|
||
|
||
1. 打开 `/docs`。
|
||
2. 找到 `GET /api/projects`。
|
||
3. 点开。
|
||
4. 点击 `Try it out`。
|
||
5. 点击 `Execute`。
|
||
6. 查看 Response body。
|
||
|
||
如果这里能返回数据，但前端项目库加载失败，那问题多半在前端 API 地址、CORS、字段映射或浏览器网络请求。
|
||
|
||
## 另一个机器可读入口
|
||
|
||
OpenAPI JSON 在：
|
||
|
||
```text
|
||
http://localhost:8000/openapi.json
|
||
```
|
||
|
||
这是给工具读取的接口描述，Swagger UI 就是基于它渲染出来的。
|