mysora/docs/api.md

# Open-Sora 推理 API 架构与使用说明

## 一、整体架构

```
                         ┌─────────────────────────────────────────┐
                         │            训练服务器 89.185.24.182       │
                         │                                          │
  外部请求                │  ┌──────────────────────────────────┐   │
─────────────►  :80      │  │  NGINX（反向代理 + 限流）          │   │
                         │  │  • 5 次/分钟/IP 限流              │   │
                         │  │  • 超时 3600s（适配长时生成）      │   │
                         │  └────────────────┬─────────────────┘   │
                         │                   │ :8000                │
                         │  ┌────────────────▼─────────────────┐   │
                         │  │  Gunicorn + FastAPI（4 workers）  │   │
                         │  │  • POST /v1/generate              │   │
                         │  │  • GET  /v1/jobs/{id}             │   │
                         │  │  • GET  /v1/videos/{id}           │   │
                         │  │  • GET  /health                   │   │
                         │  └────────────────┬─────────────────┘   │
                         │                   │                      │
                         │  ┌────────────────▼─────────────────┐   │
                         │  │  Redis（任务队列 + 结果存储）       │   │
                         │  │  • AOF 持久化（重启不丢任务）       │   │
                         │  │  • 结果保留 24 小时               │   │
                         │  └──┬──┬──┬──┬──┬──┬──┬──┬──────────┘   │
                         │     │  │  │  │  │  │  │  │              │
                         │  ┌──▼──▼──▼──▼──▼──▼──▼──▼──────────┐   │
                         │  │  8× Celery Worker（GPU 0–7）      │   │
                         │  │  • 每 Worker 独占一张 A100 80GB   │   │
                         │  │  • 并发=1，串行处理本 GPU 任务    │   │
                         │  │  • 每 10 任务自动重启（防碎片）   │   │
                         │  └──┬──────────────────────────────┘    │
                         │     │ subprocess                         │
                         │  ┌──▼──────────────────────────────┐    │
                         │  │  torchrun --nproc_per_node=1    │    │
                         │  │  scripts/diffusion/inference.py │    │
                         │  │  • 每次推理完全隔离              │    │
                         │  │  • 崩溃不影响其他 GPU            │    │
                         │  └──┬──────────────────────────────┘    │
                         │     │                                    │
                         │  ┌──▼──────────────────────────────┐    │
                         │  │  /data/train-output/api-outputs/│    │
                         │  │  视频文件存储（写盘 Huawei NVMe） │    │
                         │  └─────────────────────────────────┘    │
                         └─────────────────────────────────────────┘
```

### 关键设计决策

| 决策 | 原因 |
|------|------|
| subprocess 调用 torchrun | 进程级隔离，单卡崩溃不影响整体服务 |
| 每 Worker 独占一 GPU | 避免显存竞争，最大化并发吞吐（8 并发） |
| Celery `task_acks_late=True` | Worker 崩溃时任务重新入队，不丢失 |
| Redis AOF 持久化 | 服务器重启后任务状态不丢失 |
| systemd 守护所有进程 | 任何服务崩溃 5 秒内自动拉起 |
| NGINX 限流 5r/m | 防止单个调用方打满 GPU 队列 |

---

## 二、服务组件

### 文件结构

```
my-sora/
├── api/
│   ├── config.py        # 路径、GPU数量等配置
│   ├── schemas.py       # 请求/响应 Pydantic 模型
│   ├── tasks.py         # Celery 任务（核心推理逻辑）
│   └── main.py          # FastAPI 路由
├── deploy/
│   ├── nginx.conf                # NGINX 站点配置
│   ├── opensora-limit.conf       # 限流区定义（http 上下文）
│   ├── opensora-api.service      # FastAPI systemd 单元
│   ├── opensora-worker@.service  # Worker systemd 模板（GPU 0-7）
│   └── setup.sh                  # 一键部署脚本
└── requirements-api.txt
```

### 进程清单

| 进程 | 数量 | systemd 单元 |
|------|------|-------------|
| NGINX | 1 | nginx.service |
| Redis | 1 | redis-server.service |
| Gunicorn（FastAPI） | 1×4 workers | opensora-api.service |
| Celery Worker | 8（GPU 0-7） | opensora-worker@{0-7}.service |

---

## 三、API 接口

### 基础信息

- **Base URL**：`http://89.185.24.182`
- **认证**：无（内网使用）
- **Content-Type**：`application/json`
- **编码**：UTF-8

---

### 3.1 健康检查

```
GET /health
```

**响应示例：**

```json
{
  "status": "ok",
  "time": "2026-03-06T12:00:00.000000+00:00"
}
```

---

### 3.2 提交生成任务

```
POST /v1/generate
```

**请求参数：**

| 字段 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `prompt` | string | ✅ | — | 文本提示词，1–2000 字符 |
| `resolution` | string | | `"256px"` | 分辨率：`"256px"` 或 `"768px"` |
| `aspect_ratio` | string | | `"16:9"` | 比例：`"16:9"` `"9:16"` `"1:1"` `"2.39:1"` |
| `num_frames` | int | | `49` | 帧数，建议 `49`（≈2s）`97`（≈4s）`129`（≈5s） |
| `motion_score` | int | | `4` | 运动幅度 1–7，1=几乎静止，7=剧烈运动 |
| `num_steps` | int | | `50` | 扩散步数 10–100，越大质量越高越慢 |
| `seed` | int | | 随机 | 随机种子，固定可复现 |
| `cond_type` | string | | `"t2v"` | `"t2v"`（文生视频）或 `"i2v_head"`（图生视频） |

**请求示例：**

```bash
curl -X POST http://89.185.24.182/v1/generate \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a golden retriever running on the beach at sunset, slow motion",
    "resolution": "256px",
    "aspect_ratio": "16:9",
    "num_frames": 49,
    "motion_score": 5,
    "num_steps": 50
  }'
```

**响应示例（HTTP 202）：**

```json
{
  "job_id": "3b7e2a1c-4f8d-4b9e-a12c-8d7f3e6b2c1a",
  "message": "任务已提交"
}
```

---

### 3.3 查询任务状态

```
GET /v1/jobs/{job_id}
```

**响应字段：**

| 字段 | 说明 |
|------|------|
| `job_id` | 任务 ID |
| `status` | `pending`（排队）/ `processing`（生成中）/ `completed`（完成）/ `failed`（失败） |
| `video_url` | 完成后的视频下载路径（仅 `completed` 状态有） |
| `error` | 失败原因（仅 `failed` 状态有） |
| `completed_at` | 完成时间（ISO 8601） |

**轮询示例：**

```bash
curl http://89.185.24.182/v1/jobs/3b7e2a1c-4f8d-4b9e-a12c-8d7f3e6b2c1a
```

**生成中响应：**

```json
{
  "job_id": "3b7e2a1c-4f8d-4b9e-a12c-8d7f3e6b2c1a",
  "status": "processing",
  "video_url": null,
  "error": null,
  "completed_at": null
}
```

**完成响应：**

```json
{
  "job_id": "3b7e2a1c-4f8d-4b9e-a12c-8d7f3e6b2c1a",
  "status": "completed",
  "video_url": "/v1/videos/3b7e2a1c-4f8d-4b9e-a12c-8d7f3e6b2c1a",
  "error": null,
  "completed_at": "2026-03-06T12:01:05.123456+00:00"
}
```

---

### 3.4 下载视频

```
GET /v1/videos/{job_id}
```

返回 `video/mp4` 文件流，文件名为 `{job_id}.mp4`。

```bash
curl -O http://89.185.24.182/v1/videos/3b7e2a1c-4f8d-4b9e-a12c-8d7f3e6b2c1a
```

---

## 四、使用示例

### Python 客户端（完整轮询流程）

```python
import time
import requests

BASE_URL = "http://89.185.24.182"

def generate_video(prompt: str, **kwargs) -> str:
    """提交任务并等待完成，返回本地视频路径。"""
    # 1. 提交任务
    resp = requests.post(f"{BASE_URL}/v1/generate", json={"prompt": prompt, **kwargs})
    resp.raise_for_status()
    job_id = resp.json()["job_id"]
    print(f"任务已提交: {job_id}")

    # 2. 轮询等待（每 10 秒查一次）
    while True:
        status_resp = requests.get(f"{BASE_URL}/v1/jobs/{job_id}")
        status_resp.raise_for_status()
        data = status_resp.json()
        status = data["status"]
        print(f"状态: {status}")

        if status == "completed":
            break
        if status == "failed":
            raise RuntimeError(f"生成失败: {data['error']}")

        time.sleep(10)

    # 3. 下载视频
    video_resp = requests.get(f"{BASE_URL}/v1/videos/{job_id}", stream=True)
    video_resp.raise_for_status()
    local_path = f"{job_id}.mp4"
    with open(local_path, "wb") as f:
        for chunk in video_resp.iter_content(chunk_size=8192):
            f.write(chunk)
    print(f"视频已保存: {local_path}")
    return local_path


if __name__ == "__main__":
    generate_video(
        prompt="a panda eating bamboo in a misty forest, cinematic",
        resolution="256px",
        num_frames=49,
        motion_score=4,
    )
```

### Shell 一行命令（快速测试）

```bash
# 提交 → 拿 job_id → 等 90 秒 → 下载
JOB=$(curl -s -X POST http://89.185.24.182/v1/generate \
  -H "Content-Type: application/json" \
  -d '{"prompt":"ocean waves at sunset","num_frames":49}' \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['job_id'])")
echo "job_id: $JOB"
sleep 90
curl -O http://89.185.24.182/v1/videos/$JOB
```

---

## 五、性能参考

基于官方 H100 基准数据，A100 80GB 性能略低，实际参考：

| 分辨率 | 帧数 | GPU 数 | 预计耗时 | 显存峰值 |
|--------|------|--------|---------|---------|
| 256px  | 49   | 1      | ~60s    | ~52GB   |
| 256px  | 129  | 1      | ~90s    | ~55GB   |
| 768px  | 49   | 1      | ~900s   | ~62GB   |
| 768px  | 129  | 8      | ~350s   | ~44GB/卡 |

> **最大并发**：8 个 256px 任务可同时执行（每卡一个）。768px 高质量视频建议串行或减少并发。

---

## 六、测试流程

### 6.1 环境就绪检查

```bash
# 服务全部 active
ssh ceshi@89.185.24.182 "sudo systemctl is-active opensora-api opensora-worker@{0..7} nginx redis-server"

# API 健康检查
curl http://89.185.24.182/health

# Redis 连通
ssh ceshi@89.185.24.182 "redis-cli ping"

# 权重文件确认
ssh ceshi@89.185.24.182 "ls -lh /data/train-input/ckpts/*.safetensors"
```

### 6.2 冒烟测试（首次验证）

```bash
# 提交一个最简单的任务
curl -X POST http://89.185.24.182/v1/generate \
  -H "Content-Type: application/json" \
  -d '{"prompt": "a red ball bouncing", "num_frames": 17, "num_steps": 20}'
```

查询直到 `completed`，预计 30–60 秒。

### 6.3 并发测试（8 GPU 全满）

```bash
# 同时提交 8 个任务，验证 8 卡并发
for i in $(seq 1 8); do
  curl -s -X POST http://89.185.24.182/v1/generate \
    -H "Content-Type: application/json" \
    -d "{\"prompt\": \"test video $i, nature scene\", \"num_frames\": 17, \"num_steps\": 10}" &
done
wait
echo "8 个任务已提交"
```

### 6.4 故障恢复测试

```bash
# 模拟 API 服务崩溃后自动恢复
sudo systemctl kill opensora-api
sleep 8
curl http://89.185.24.182/health   # 应在 5-10 秒内恢复返回 200

# 模拟某个 Worker 崩溃后恢复
sudo systemctl kill opensora-worker@3
sleep 15
sudo systemctl is-active opensora-worker@3   # 应为 active
```

---

## 七、运维操作

### 查看日志

```bash
# API 服务实时日志
sudo journalctl -u opensora-api -f

# GPU 0 Worker 日志
tail -f /data/train-output/logs/worker-gpu0.log

# NGINX 访问日志
tail -f /data/train-output/logs/api-access.log
```

### 重启服务

```bash
# 重启 API
sudo systemctl restart opensora-api

# 重启单个 Worker
sudo systemctl restart opensora-worker@2

# 重启全部 Worker
for i in $(seq 0 7); do sudo systemctl restart opensora-worker@$i; done

# 重启全栈
sudo systemctl restart opensora-api redis-server nginx
for i in $(seq 0 7); do sudo systemctl restart opensora-worker@$i; done
```

### 磁盘清理

视频文件存储在 `/data/train-output/api-outputs/`，每个任务占约 50–300MB。

```bash
# 查看占用
du -sh /data/train-output/api-outputs/

# 删除 7 天前的视频
find /data/train-output/api-outputs/ -maxdepth 1 -type d -mtime +7 -exec rm -rf {} +
```

### 查看 GPU 使用

```bash
# 实时监控各 GPU 显存
watch -n 2 nvidia-smi --query-gpu=index,name,memory.used,memory.free,utilization.gpu --format=csv
```

---

## 八、常见问题

| 现象 | 原因 | 解决 |
|------|------|------|
| 任务长时间 `pending` | Worker 全部在忙 | 等待或减少并发请求 |
| 任务 `failed`，报 OOM | 768px 显存不足 | 改用 256px 或减少 num_frames |
| `/health` 返回 502 | API 服务未启动 | `sudo systemctl restart opensora-api` |
| 任务 `failed`，报权重找不到 | 权重未下载完成 | 检查 `/data/train-input/ckpts/` 目录 |
| Worker 一直重启 | 模型加载失败 | `tail /data/train-output/logs/worker-gpu0.log` |