5f6a242114
原 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)。无内容丢失。
71 lines
2.8 KiB
Markdown
71 lines
2.8 KiB
Markdown
← [返回主页](../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,...}
|
||
```
|