---
title: Model-API-2
canonical_url: "https://www.modelscope.cn/studios/AMD_Dev/Model-API-2"
md_url: "https://www.modelscope.cn/studios/AMD_Dev/Model-API-2.md"
repository: AMD_Dev/Model-API-2
last_updated: 2026-10-15
sdk_type: docker
sdk_version: 6.17.3
downloads: 0
stars: 3
---

# Model-API-2

> Model-API-2 - AMD_Dev 在 ModelScope 创建的在线 Demo。DeepSeek-V4-Flash-Vision-Exp 多模态服务

AMD_Dev/Model-API-2 是 ModelScope 魔搭社区上的在线可交互 Demo（创空间），基于 docker 6.17.3 构建。

- **Repository**: AMD_Dev/Model-API-2
- **SDK**: docker
- **SDK version**: 6.17.3
- **Downloads**: 0
- **Stars**: 3
- **Last updated**: 2026-10-15

Source: https://www.modelscope.cn/studios/AMD_Dev/Model-API-2

---

# DeepSeek-V4-Flash-Vision-Exp 多模态服务

基于 SGLang 和 ROCm 的单节点四卡推理服务，提供 ModelScope 创空间网页以及
OpenAI 兼容 API，支持文本、图片和视频输入。视频会在网关侧校验并均匀抽帧后
交给模型。

## 运行基线

| 项目 | 配置 |
|---|---|
| 模型仓库 | `AMD_Dev/DeepSeek-V4-Flash-Vision-Exp-FP8-DSpark`（AtlasCloud 原版的逐文件镜像） |
| 模型 revision | `fp8-a6ff5e` |
| 权重 | 48 个 safetensors 分片，306,752,882,784 bytes（285.686 GiB） |
| 参数量 | 约 304.6B elements |
| 精度 | FP8 E4M3 权重、UE8M0 scales、FP8 E4M3 KV Cache；不是 FP4 experts |
| 本机验证 | 4 × AMD Instinct GPU，Tensor Parallel 4 |
| 线上配置 | 固定使用 GPU `0,1,2,3`，Tensor Parallel 4 |
| SGLang 镜像 | `lmsysorg/sglang-rocm:v0.5.18-rocm720-mi30x-20260829` |
| 镜像 digest | `sha256:9773c77dffed04510602ce4f0def134fcefffec78c7af9b19656452fb09bdf36` |
| 服务端口 | `7860` |
| OpenAI Base URL | `https://studio-amd-dev-model-api-2.api-inference.modelscope.net/v1` |

启动时会检查模型配置、权重索引哈希、量化格式、safetensors dtype、分片数量和
总大小，避免把官方 FP4/FP8 混合 checkpoint 当成本机验证版本加载。锁定的 dtype
集合为 `F8_E4M3`、`F8_E8M0`、`BF16`、`F32`、`I64`；少量非 FP8 tensor 属于
模型结构的正常组成，不代表专家权重为 FP4。SGLang 兼容补丁由
[patches/SHA256SUMS](patches/SHA256SUMS) 校验。

## 部署到 ModelScope 创空间

1. 打开 `AMD_Dev/Model-API-2`，运行方式选择 Docker。
2. 分配同一节点上的至少 4 张 AMD GPU。启动脚本会锁定
   `ROCR_VISIBLE_DEVICES=0,1,2,3`、`HIP_VISIBLE_DEVICES=0,1,2,3` 和
   `TENSOR_PARALLEL_SIZE=4`，避免平台按整机 8 卡自动改成 TP8。
3. 该 checkpoint 本身约 285.686 GiB，下载前至少保留 330 GiB 可用空间。若 PVC
   还保留旧的 156.3 GiB 混合 checkpoint，应扩容或人工清理；程序不会自动删除。
4. 上传项目生产文件及完整的 `patches/sglang/` 目录。
5. 服务端口保持为 `7860`。模型从 `AMD_Dev` 自有的 ModelScope FP8 镜像下载；
   公开仓库无需额外 Token。
6. 不要添加 `--weight-loader-disable-mmap`。程序会主动忽略该参数，因为它会让
   当前 safetensors 路径在解析 `F8_E8M0` scale tensor 时抛出 `KeyError`。
7. 重新部署并等待 `/readyz` 返回 200；只有它返回 200 才表示模型实际部署成功。

默认模型目录为：

```text
/mnt/workspace/models/DeepSeek-V4-Flash-Vision-Exp-FP8-DSpark
```

首次启动会从 ModelScope 自有仓库下载锁定 revision，随后复用持久化目录。启动顺序为模型
校验、权重预热、SGLang 加载、文本与图片冒烟验证。模型未就绪时 `/v1/*` 返回 503。

## 本地 Docker 运行

```bash
docker build -t model-api-2:dsv4-vision-fp8 .

docker run --rm \
  --device=/dev/kfd \
  --device=/dev/dri \
  --group-add video \
  --ipc=host \
  --shm-size=64g \
  -p 7860:7860 \
  -v dsv4-model:/mnt/workspace/models \
  -v dsv4-cache:/cache \
  -v dsv4-logs:/mnt/workspace/logs \
  model-api-2:dsv4-vision-fp8
```

也可以使用：

```bash
docker compose up
```

已有本地权重时：

```bash
MODEL_PATH=/path/to/DeepSeek-V4-Flash-Vision-Exp-FP8-DSpark docker compose up
```

## API 调用

```python
from openai import OpenAI

token = "YOUR_MODELSCOPE_SDK_TOKEN"
client = OpenAI(
    base_url="https://studio-amd-dev-model-api-2.api-inference.modelscope.net/v1",
    api_key=token,
    # Authorization is consumed by the public gateway. This copy reaches the
    # application so usage can be attributed to the same ModelScope account.
    default_headers={"X-ModelScope-Access-Token": token},
    timeout=3600,
)

response = client.chat.completions.create(
    model="DeepSeek-V4-Flash-Vision-Exp",
    messages=[{"role": "user", "content": "你好"}],
    max_tokens=256,
)
print(response.choices[0].message.content)
```

用户只填写一次 `token`。OpenAI SDK 自动把它放入 `Authorization`，同时通过
`default_headers` 复制到应用身份 Header；请求会携带两个 Header，但不需要用户输入两次。
如果旧客户端暂时只发送 `Authorization`，默认兼容模式仍会继续推理，但该请求只能匿名
统计。设置 `MODELSCOPE_IDENTITY_REQUIRED=1` 后会切换到严格模式，缺少应用身份 Header
的生成请求将返回 401。

图片使用 OpenAI 标准 `image_url` 内容块。`video_url` 是本服务提供的网关扩展，
当前接受 `data:video/*;base64,...`，默认限制为 64 MiB、60 秒、最多抽取 4 帧；
视频会先转换为图片帧，再发送给模型。

```python
messages = [{
    "role": "user",
    "content": [
        {"type": "video_url", "video_url": {"url": video_data_url}},
        {"type": "text", "text": "请按时间顺序描述视频内容。"},
    ],
}]
```

## 健康检查

```bash
curl http://127.0.0.1:7860/healthz
curl --fail http://127.0.0.1:7860/readyz
```

- `/healthz`：Web 服务存活状态和启动诊断。
- `/readyz`：模型加载及文本、图片冒烟验证全部通过后返回 200。

## 异步用量统计

API 和创空间网页请求都会生成统一 usage 事件。推理进程只进行非阻塞 Unix datagram
投递；独立低优先级 worker 负责身份解析、SQLite/WAL 持久化和小时汇总。worker、
磁盘或身份服务异常不会阻塞推理，也不会影响健康状态。

默认数据库：

```text
/mnt/workspace/logs/dsv4-flash-vision/usage/usage.sqlite3
```

统计内容包括用户、入口、模型、模态、请求结果、耗时及 prompt、completion、
reasoning、total token。不会保存提示词、回复正文、媒体内容或 URL、原始 Token、
Cookie、Email 和 Git AccessToken。本版本只在本地生成汇总与 outbox，不上传中央服务。

公网 API 的 `Authorization` 会被 ModelScope 网关用于鉴权，默认不会到达应用。客户端推荐
自动复制同一个 Token 到 `X-ModelScope-Access-Token`；服务使用它调用
`GET /openapi/v1/users/me`，优先取得不可变用户 ID，再生成本地 HMAC 账号键。因此同一账号
创建或轮换多个 Token 仍会归并为同一用户。只有旧响应不提供用户 ID 时才兼容回退到用户名。
默认兼容模式下，缺少该 Header 的生成请求继续执行并记为匿名；Token 不会转发给内部
SGLang，也不会以原文写入用量数据库。

拥有 `AMD_Dev/Model-API-2` 可编辑或更高权限的 ModelScope 用户可以导出聚合数据：

```bash
curl --fail-with-body \
  -H "Authorization: Bearer ${MODELSCOPE_API_TOKEN}" \
  -H "X-ModelScope-Access-Token: ${MODELSCOPE_API_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{"date":"2026-09-09","timezone":"Asia/Shanghai","granularity":"daily","format":"csv"}' \
  -o usage-2026-09-09.csv \
  'https://studio-amd-dev-model-api-2.api-inference.modelscope.net/admin/usage/export'
```

公网管理员请求必须同时携带这两个请求头：`Authorization` 由 ModelScope 公网
网关鉴权，`X-ModelScope-Access-Token` 会原样传给应用，用于校验目标创空间权限。
直接访问本地服务时仍兼容单独使用 `Authorization: Bearer ...`。

导出权限授予普通直接编辑者、创空间创建者以及 `AccessLevel >= 50` 的组织管理员；
其他用户返回 403。

容器管理员也可以直接导出：

```bash
python /workspace/Model-API-2/usage_report.py daily \
  --date 2026-09-09 \
  --timezone Asia/Shanghai \
  --format csv \
  --output /tmp/usage-2026-09-09.csv
```

## 常用配置

完整配置见 [.env.example](.env.example)。

| 变量 | 默认值 | 说明 |
|---|---|---|
| `MODEL_HUB` | `modelscope` | 锁定的模型下载来源 |
| `MODEL_ID` | `AMD_Dev/DeepSeek-V4-Flash-Vision-Exp-FP8-DSpark` | 自有的本机验证 FP8 镜像 |
| `MODEL_REVISION` | `fp8-a6ff5e` | 上传完成后锁定的 ModelScope tag |
| `MODEL_DIR` | `/mnt/workspace/models/DeepSeek-V4-Flash-Vision-Exp-FP8-DSpark` | 持久化权重目录 |
| `EXPECTED_GPU_COUNT` | `4` | 锁定的部署 GPU 数量 |
| `TENSOR_PARALLEL_SIZE` | `4` | 锁定的 Tensor Parallel 大小 |
| `SGLANG_MEM_FRACTION_STATIC` | `0.80` | SGLang 静态显存比例 |
| `STUDIO_SLUG` | `amd-dev-model-api-2` | 公网 Base URL 标识 |
| `MAX_VIDEO_FILE_MB` | `64` | 单视频大小限制 |
| `MAX_VIDEO_DURATION_SECONDS` | `60` | 单视频时长限制 |
| `MAX_VIDEO_FRAMES` | `4` | 视频最大抽帧数 |
| `USAGE_TELEMETRY_ENABLED` | `1` | 开启本地异步统计 |
| `USAGE_ADMIN_EXPORT_ENABLED` | `1` | 开启管理员导出接口 |
| `MODELSCOPE_IDENTITY_HEADER` | `X-ModelScope-Access-Token` | 客户端自动复制 SDK Token 的应用身份 Header |

## 校验

无需 GPU 的部署前检查：

```bash
python3 verify_package.py
bash -n start.sh
docker build --check .
```

服务启动后再通过 `/readyz` 和文本、图片、视频请求确认实际推理。