add stable media support and sync skillhub UI
This commit is contained in:
wtgoku
@@ -0,0 +1,129 @@
|
||||
# popiartServer Stable Media URL V1
|
||||
|
||||
这份文档只描述 `popiartServer` 这一层为了支持稳定媒体 URL 所做的职责扩展，不覆盖 `popiartcli` 的命令面，也不要求修改 `PopiNewAPI` 的现有通道实现。
|
||||
|
||||
## 背景
|
||||
|
||||
原有本地开发版 `popiartServer` 更偏向：
|
||||
|
||||
- `artifact` read-through
|
||||
- `result_refs_json` 存 `data_url` 或上游临时 `url`
|
||||
- `GET /artifacts/:id/content` 由 server 当场去解码或代理下载
|
||||
|
||||
这种实现能跑通基本流程，但不适合多模态 skill 的复用：
|
||||
|
||||
- `img2img` 经常还要重新拉流或转 base64
|
||||
- 上游签名 URL 可能过期
|
||||
- 前一个 job 的输出不能稳定地作为下一个 job 的 URL 输入
|
||||
|
||||
## V1 目标
|
||||
|
||||
`popiartServer` 在不依赖外部对象存储的前提下，先提供一套本地可运行的稳定媒体 URL 能力：
|
||||
|
||||
- 本地上传文件可立即获得稳定 URL
|
||||
- 新生成的 job 结果会被 re-host 到本地 media store
|
||||
- 新 artifact 会携带 `media_id` 和 `url`
|
||||
- `image2video` 的 `vidu*` 路由可以直接复用 artifact URL
|
||||
|
||||
## 新接口
|
||||
|
||||
### `POST /v1/media/upload`
|
||||
|
||||
上传一个本地文件，直接创建 media 记录并返回：
|
||||
|
||||
- `id`
|
||||
- `project_id`
|
||||
- `filename`
|
||||
- `content_type`
|
||||
- `size_bytes`
|
||||
- `created_at`
|
||||
- `url`
|
||||
- `visibility`
|
||||
- `sha256`
|
||||
|
||||
### `GET /v1/media/:id`
|
||||
|
||||
读取 media 元数据。这个接口需要登录态，并要求 media 属于当前用户。
|
||||
|
||||
### `GET /v1/media/:id/content`
|
||||
|
||||
读取稳定内容 URL。这个接口默认允许匿名 GET，以便模型提供商可以直接 fetch。
|
||||
|
||||
## Artifact 行为变化
|
||||
|
||||
`POST /v1/artifacts/upload` 现在不再只把内容塞成 `data_url`：
|
||||
|
||||
1. server 先把上传文件写入本地 media store
|
||||
2. 再创建本地 upload job
|
||||
3. 最终 artifact 返回：
|
||||
- `id`
|
||||
- `media_id`
|
||||
- `url`
|
||||
- `visibility`
|
||||
- `sha256`
|
||||
- `storage_status`
|
||||
|
||||
## Job 结果行为变化
|
||||
|
||||
对于新的 `text2image`、`img2img`、`image2video` 结果：
|
||||
|
||||
1. 先从 `PopiNewAPI` 或上游临时结果读出真实内容
|
||||
2. re-host 到 `POPIART_DATA_DIR/media/`
|
||||
3. 把 `local_path + media_id + stable url` 写回 `result_refs_json`
|
||||
|
||||
这样新的 artifact 不再依赖上游临时 URL。
|
||||
|
||||
## 本地 media store
|
||||
|
||||
V1 的本地开发版不引入 S3/R2/OSS，而是用本地文件系统：
|
||||
|
||||
- blob 文件：`POPIART_DATA_DIR/media/blobs/`
|
||||
- metadata JSON：`POPIART_DATA_DIR/media/meta/`
|
||||
|
||||
如果 `POPIART_DATA_DIR` 没显式配置，但 `POPIART_SQLITE_PATH` 已配置，则 `DataDir` 会自动落到 SQLite 所在目录，避免测试把 media 文件写进源码目录。
|
||||
|
||||
## 当前已打通的 URL 复用
|
||||
|
||||
### Artifact / media
|
||||
|
||||
- `media upload` -> stable URL
|
||||
- `artifact upload` -> stable URL
|
||||
- 新 `artifact` 的 `GET /artifacts/:id` -> `url`
|
||||
|
||||
### Runtime output
|
||||
|
||||
- `text2image` 输出会 re-host
|
||||
- `img2img` 输出会 re-host
|
||||
- `image2video` 输出会 re-host
|
||||
|
||||
### URL-first dispatch
|
||||
|
||||
当前已优先 URL 化的路径是：
|
||||
|
||||
- `video.image2video`
|
||||
- 当模型 ID 以 `vidu` 开头，且 reference 已有 stable URL 时，server 会优先用 JSON `images` 传给 `/v1/videos`
|
||||
|
||||
这是为了先覆盖当前测试环境最常用的 `viduq2-pro-fast` 路由。
|
||||
|
||||
## 兼容策略
|
||||
|
||||
旧数据仍然兼容：
|
||||
|
||||
- 如果 `result_ref.kind == data_url`，继续解码读取
|
||||
- 如果 `result_ref.kind == url`，继续代理下载
|
||||
- 如果 `result_ref.kind == local_path`，优先从本地 media store 读取
|
||||
|
||||
也就是说：
|
||||
|
||||
- 历史 artifact 不会立即失效
|
||||
- 新 artifact 才开始享受稳定 URL
|
||||
|
||||
## 后续阶段
|
||||
|
||||
后续如果要走生产化路线，可以保持接口不变，只把存储实现替换成对象存储：
|
||||
|
||||
- 本地 `media/blobs/` -> S3 / R2 / OSS / COS
|
||||
- metadata JSON -> 独立 media table 或对象存储元数据
|
||||
- `GET /v1/media/:id/content` -> CDN / 受控稳定 URL
|
||||
|
||||
但这一步不是 V1 本地开发验证的前置条件。
|
||||
Reference in New Issue
Block a user