调用模型，返回事件的时间线

2026-05-27 16:02:44 +08:00
parent 556fa2f3ca
commit 883f09e6df
12 changed files with 1230 additions and 0 deletions
--- a/API文档.md
+++ b/API文档.md
@@ -0,0 +1,185 @@
+# Marlin-2B Video VLM API 文档
+
+## 基础信息
+- 服务地址：`http://0.0.0.0:8900`
+- 模型：Marlin-2B
+- 设备：Apple Silicon (MPS) / CUDA / CPU
+
+---
+
+## 1. 健康检查接口
+
+**接口路径**：`GET /health`
+
+**请求示例**：
+```bash
+curl http://localhost:8900/health
+```
+
+**返回参数**：
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| status | string | 状态：ok（已加载）或 loading（加载中） |
+| model | string | 模型名称，固定为 "Marlin-2B" |
+| device | string | 运行设备：mps/cuda/cpu |
+
+**返回示例**：
+```json
+{
+  "status": "ok",
+  "model": "Marlin-2B",
+  "device": "mps"
+}
+```
+
+---
+
+## 2. 视频字幕生成接口
+
+**接口路径**：`POST /caption`
+
+**功能说明**：为视频生成结构化字幕，包括场景描述和带时间戳的事件列表。
+
+**请求参数**（multipart/form-data）：
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| video | 文件 | 是 | 视频文件（支持 mp4, avi, mov, webm 等格式） |
+| max_new_tokens | int | 否 | 最大生成 token 数，默认值 2048 |
+
+**请求示例**：
+```bash
+curl -X POST http://localhost:8900/caption \
+  -F "video=@/path/to/video.mp4" \
+  -F "max_new_tokens=2048"
+```
+
+**返回参数**：
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| caption | string \| null | 完整的原始字幕文本 |
+| scene | string \| null | 场景描述段落 |
+| events | array \| null | 事件列表，每个事件包含 start/end/description |
+
+**events 数组元素**：
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| start | float | 事件开始时间（秒） |
+| end | float | 事件结束时间（秒） |
+| description | string | 事件描述 |
+
+**返回示例**：
+```json
+{
+  "caption": "Scene: ... Events: ...",
+  "scene": "这是一个室内场景...",
+  "events": [
+    {
+      "start": 0.0,
+      "end": 5.0,
+      "description": "一个人走进房间"
+    },
+    {
+      "start": 5.5,
+      "end": 10.0,
+      "description": "这个人坐在沙发上"
+    }
+  ]
+}
+```
+
+---
+
+## 3. 事件时间定位接口
+
+**接口路径**：`POST /find`
+
+**功能说明**：在视频中查找指定事件发生的时间区间（时间定位）。
+
+**请求参数**（multipart/form-data）：
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| video | 文件 | 是 | 视频文件 |
+| event | 字符串 | 是 | 自然语言事件查询，例如 "一个人进入房间" |
+
+**请求示例**：
+```bash
+curl -X POST http://localhost:8900/find \
+  -F "video=@/path/to/video.mp4" \
+  -F "event=一个人进入房间"
+```
+
+**返回参数**：
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| raw | string \| null | 原始模型输出，例如 "From 14.3 to 18.2." |
+| span | array \| null | 时间区间 [开始时间, 结束时间]，单位秒 |
+| format_ok | bool | 输出格式是否符合训练格式 |
+
+**返回示例**：
+```json
+{
+  "raw": "From 14.3 to 18.2.",
+  "span": [14.3, 18.2],
+  "format_ok": true
+}
+```
+
+---
+
+## 4. 自定义提示生成接口
+
+**接口路径**：`POST /generate`
+
+**功能说明**：使用自定义提示词与视频进行交互，实现更灵活的问答。
+
+**注意**：此接口需要安装 `torchvision` 库才能正常工作。
+
+**请求参数**（multipart/form-data）：
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| video | 文件 | 是 | 视频文件 |
+| prompt | 字符串 | 是 | 自定义文本提示词 |
+| max_new_tokens | int | 否 | 最大生成 token 数，默认值 512 |
+| do_sample | bool | 否 | 是否启用采样，默认 false（确定性输出） |
+| temperature | float | 否 | 温度参数，控制随机性，默认 1.0 |
+| top_p | float | 否 | top-p 采样参数，默认 1.0 |
+
+**请求示例**：
+```bash
+curl -X POST http://localhost:8900/generate \
+  -F "video=@/path/to/video.mp4" \
+  -F "prompt=描述这个视频的内容" \
+  -F "max_new_tokens=512" \
+  -F "temperature=0.7"
+```
+
+**返回参数**：
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| text | string | 生成的文本内容 |
+
+**返回示例**：
+```json
+{
+  "text": "这个视频展示了..."
+}
+```
+
+---
+
+## 错误响应
+
+当请求失败时，接口返回 HTTP 错误码和错误信息：
+
+| HTTP 状态码 | 说明 |
+|-------------|------|
+| 400 | 请求参数错误 |
+| 500 | 服务器内部错误 |
+| 503 | 模型尚未加载完成 |
+
+**错误响应示例**：
+```json
+{
+  "detail": "Caption failed: 错误详情"
+}
+```