185 lines
4.4 KiB
Markdown
185 lines
4.4 KiB
Markdown
# 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: 错误详情"
|
||
}
|
||
``` |