docs: README 分层重构 — 主页精简到 150 行 + 6 个子文档
原 883 行单体 README 信息密度过高且重复(配置差异表出现 2 次、缓存说明 散落多处)。按主题拆分: 主页 README.md (150行): - 一句话简介 + 功能特性(精简) + 架构(目录树+数据流) + 快速开始 - 文档索引表(链接到 6 个子文档,每行一句话说明) - 入口地址表 + 依赖(精简) docs/ 子文档(原样搬运,不重写): - DEPLOYMENT.md (170行) CPU/GPU 部署、模型选型、CPU↔GPU 切换 - CONFIG.md (187行) 配置差异表、完整字段表、配置示例 - DOCKER.md (185行) 构建/重建/缓存分层/until根因/Volume - API.md (70行) HTTP接口表、分片上传协议、示例 - ARCHITECTURE.md(140行) 断句算法、显存策略、GPU优化、缓存清理 - FAQ.md (42行) 6 条常见问题 每个子文档顶部加「← 返回主页」链接,相关处加交叉引用 (如 DEPLOYMENT 提到缓存时链接 DOCKER.md)。无内容丢失。
This commit is contained in:
70
docs/API.md
Normal file
70
docs/API.md
Normal file
@@ -0,0 +1,70 @@
|
||||
← [返回主页](../README.md)
|
||||
|
||||
# HTTP 接口
|
||||
|
||||
---
|
||||
|
||||
## 接口一览
|
||||
|
||||
| 方法 | 路径 | 认证 | 说明 |
|
||||
|---|---|---|---|
|
||||
| GET | `/` | 无 | 主页(上传入口 + 最近 10 任务进度卡片) |
|
||||
| GET | `/health` | 无 | 存活探针 + 设备/模型配置信息 |
|
||||
| GET | `/history` | 无 | 历史任务页(分页表格,可按文件名搜索、下载字幕) |
|
||||
| GET | `/logs` | 无 | 实时日志页(按级别过滤、自动刷新、可展开 traceback) |
|
||||
| GET | `/docs` `/redoc` | Basic Auth | API 文档 |
|
||||
| POST | `/api/tasks/chunk-uploads` | 无 | 创建分片上传会话 |
|
||||
| GET | `/api/tasks/chunk-uploads/{id}/status` | 无 | 查已传分片(断点续传) |
|
||||
| POST | `/api/tasks/chunk-uploads/{id}/chunks/{index}` | 无 | 上传单个分片(原始二进制 body) |
|
||||
| POST | `/api/tasks/chunk-uploads/{id}/complete` | 无 | 拼接 + 创建转写任务 |
|
||||
| GET | `/api/tasks` | 无 | 任务列表(`limit` / `offset` 分页,`q` 按文件名模糊搜索) |
|
||||
| GET | `/api/tasks/{id}` | 无 | 任务状态(status / progress / error) |
|
||||
| GET | `/api/tasks/{id}/subtitle?type=bilingual\|en\|zh` | 无 | 下载字幕 |
|
||||
| GET | `/api/logs?level=debug\|info\|warning\|error&tail=N` | 无 | 查询日志(按级别过滤,最近 N 条) |
|
||||
| DELETE | `/api/logs` | 无 | 清空日志缓冲 |
|
||||
|
||||
---
|
||||
|
||||
## 分片上传协议
|
||||
|
||||
1. **建会话** `POST /api/tasks/chunk-uploads`,body 含 `filename` / `size_bytes` /
|
||||
`chunk_size` / `total_chunks`,返回 `upload_id`。
|
||||
2. **查状态** `GET .../status`,返回 `uploaded_chunks`(已传分片下标列表)。
|
||||
断点续传时先查此接口,只补传缺失分片。
|
||||
3. **传分片** `POST .../chunks/{index}`,body 为原始二进制。分片可乱序、可重传覆盖。
|
||||
4. **完成** `POST .../complete`,服务端按 index 顺序拼接为正式视频文件,创建转写 Task
|
||||
并入队。complete 幂等:重复调用返回同一 `task_id`。
|
||||
|
||||
---
|
||||
|
||||
## 请求/响应示例
|
||||
|
||||
创建会话:
|
||||
|
||||
```bash
|
||||
curl -X POST http://127.0.0.1:8000/api/tasks/chunk-uploads \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{"filename":"demo.mp4","size_bytes":10485760,"chunk_size":4194304,"total_chunks":3}'
|
||||
# → {"upload_id":"a1b2...","filename":"demo.mp4","size_bytes":10485760,"chunk_size":4194304,"total_chunks":3}
|
||||
```
|
||||
|
||||
查任务状态:
|
||||
|
||||
```bash
|
||||
curl http://127.0.0.1:8000/api/tasks/1
|
||||
# → {"id":1,"filename":"demo.mp4","status":"done","progress":100.0,"error":null,"has_subtitle":true,...}
|
||||
```
|
||||
|
||||
下载字幕:
|
||||
|
||||
```bash
|
||||
curl -OJ http://127.0.0.1:8000/api/tasks/1/subtitle?type=bilingual
|
||||
```
|
||||
|
||||
健康检查(含设备与模型配置):
|
||||
|
||||
```bash
|
||||
curl -s http://127.0.0.1:8001/health | python -m json.tool
|
||||
# → {"status":"ok","cuda_available":true,"gpu":"NVIDIA GeForce RTX 3090",
|
||||
# "asr_model":"large-v3-turbo","asr_batch_size":32,"asr_beam_size":2,...}
|
||||
```
|
||||
Reference in New Issue
Block a user