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

# Model-API

> Model-API - AMD_Dev 在 ModelScope 创建的在线 Demo。GLM-5.3-Flash Model API · FlyDSL

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

- **Repository**: AMD_Dev/Model-API
- **SDK**: docker
- **SDK version**: 6.17.3
- **Downloads**: 0
- **Stars**: 16
- **Last updated**: 2026-10-21

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

---

# GLM-5.3-Flash Model API · FlyDSL

面向 ModelScope 创空间部署的 GLM-5.3-Flash 推理服务。项目提供网页对话界面和
OpenAI 兼容 API，针对单节点 8 张 AMD Instinct MI308X（ROCm）环境进行了部署配置，
并包含多模态输入、服务自恢复、健康检查、隐私安全日志和异步用量统计。

推理后端合入了 `runtime/model-api:/workspace/fhd_glm53-gfx942-port` 验证的 FlyDSL
indexer 和 sparse-prefill 启动参数优化。优化以进程内兼容层实现，不修改基础镜像中的
vLLM 文件，并完整保留日志下载、用量计量和 Prompt Capture。

当前创空间：[`AMD_Dev/Model-API`](https://modelscope.cn/studios/AMD_Dev/Model-API)。

## 主要能力

- OpenAI 兼容接口：`/v1/chat/completions`、`/v1/completions`、`/v1/models`
- 创空间网页对话：支持文本、图片、视频和文档
- 单会话附件上限：4 张图片、2 个视频、5 个文档
- 文档支持：PDF、DOCX、Markdown、文本、代码、CSV、JSON、XML、YAML
- 流式输出、思考内容展示和工具调用兼容
- vLLM 自动拉起、健康监控、异常恢复与启动预热
- 本机优先的溢出路由：本机繁忙或不可用时，API 流量分担到
  [`AMD_Dev/GLM-5.3-Flash2`](https://www.modelscope.cn/studios/AMD_Dev/GLM-5.3-Flash2)
- 长上下文请求准入控制，降低大 Prompt 对在线流式请求的影响
- gfx942 FlyDSL FP8 MQA indexer（`mfma_r4_w4`）
- shape-scoped sparse-prefill 调优（`512:16:16 -> warps=1/stages=1`）
- 隐私安全的运行日志下载
- 完全异步的本地用量统计，以及管理员每日 JSON/CSV 导出

## 部署规格

| 项目 | 默认配置 |
|---|---|
| 模型 | `ZhipuAI/GLM-5.3-Flash` |
| Served model name | `glm-5.3-flash` |
| GPU / 并行 | 8 × AMD Instinct MI308X / TP8 |
| 最大上下文 | 262144 tokens |
| 最大输出 | 32768 tokens |
| Long-prefill chunk | 2048 tokens |
| FlyDSL variant | `mfma_r4_w4` |
| Sparse-prefill launch | `512:16:16 -> num_warps=1, num_stages=1` |
| Web / API 端口 | `7860` |
| 内部 vLLM 端口 | `8000` |
| 模型目录 | `/mnt/workspace/models/GLM-5.3-Flash` |
| 运行日志目录 | `/workspace/logs/glm53-flash/model-api-tp8-256k-graph256` |
| 持久用量数据库 | `/mnt/workspace/logs/glm53-flash/model-api-tp8-256k-graph256/usage.sqlite3` |

完整运行参数位于
[`config/model-api-tp8-8k-graph256.env.sh`](config/model-api-tp8-8k-graph256.env.sh)。
文件名保留了历史命名，实际配置为 256K 上下文。

## FlyDSL 优化

优化代码位于
[`compat/mi300test-20260907/mi300test_fallback.py`](compat/mi300test-20260907/mi300test_fallback.py)，
由 vLLM worker 的 `sitecustomize` 自动安装：

- 将 vLLM 的 `fp8_mqa_logits_gfx942` 模块属性替换为 AITER FlyDSL 实现；为了避免八个
  TP worker 串行编译导致 rendezvous 超时，FlyDSL 模块在第一次真正调用时才延迟导入。
- 只对 `head_dim=512, BLOCK_K=16, BLOCK_H=16` 使用 `num_warps=1`、
  `num_stages=1`；其他 shape 保留 vLLM 原生启动参数。
- 两项优化都只在 `GLM53_VLLM_PROCESS=1` 的 vLLM 子进程中生效，不影响 Gradio/API
  主进程及日志、计量和 Prompt Capture。

现场验证记录显示，FlyDSL indexer 在约 8.6K-token prefill 的 TP8 A/B 中将 median TTFT
从 2987 ms 降至 1986 ms，并将 prefill throughput 从 10456 提升至 16146 tok/s；
sparse-prefill kernel 从 7.86 ms 降至 4.78 ms，16K/64K 服务测试的 TTFT 约下降
7.5%～8.0%。Sparse-prefill 只调整 wave 数，输出与原 kernel byte-identical；FlyDSL
使用另一套 kernel 实现，仅保证数值等价，不保证 bit-exact。详细边界、开关和回退方式见
[`docs/flydsl-optimization.md`](docs/flydsl-optimization.md)。

## 构建与启动

```bash
docker build -t model-api:fp8-tp8-256k-graph256-aiter-flydsl .
```

运行时需要提供 8 张 ROCm GPU，并挂载：

| 容器路径 | 用途 |
|---|---|
| `/mnt/workspace/models` | 模型权重 |
| `/workspace/logs` | 运行日志 |
| `/mnt/workspace/logs` | 持久用量数据库 |
| `/cache` | vLLM、Triton 和 Inductor 缓存 |

镜像入口会自动加载生产配置并启动服务。服务探针：

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

`/healthz` 用于存活检查；本机模型加载并完成文本、图片预热后，或溢出路由可用时，
`/readyz` 返回成功。返回 JSON 中的 `ready` 只表示本机 vLLM，`api_ready` 表示 `/v1`
是否可接收流量。Kubernetes readinessProbe 应使用 `/readyz`。

## API 调用

```python
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://studio-amd-dev-model-api.api-inference.modelscope.net/v1",
    api_key=os.environ["MODELSCOPE_SDK_TOKEN"],
    timeout=1800,
)

response = client.chat.completions.create(
    model="glm-5.3-flash",
    messages=[{"role": "user", "content": "介绍一下 ROCm。"}],
    stream=False,
)
print(response.choices[0].message.content)
```

图片使用 OpenAI 的 `image_url` 内容块，视频使用 `video_url` 内容块。网页端可直接上传
受支持的图片、视频和文档。

### 服务繁忙响应

`/v1` 上的服务端故障统一返回 HTTP 429，提示“当前使用人数较多，请稍后再试。”，不向调用方
暴露内部地址或 vLLM 错误详情。流式请求在 SSE 中返回相同的 `error` 事件：

| 场景 | `error.code` | `Retry-After` |
|---|---|---|
| 本机 vLLM 未就绪且无可用溢出 | `model_not_ready` | — |
| 推理后端读超时 | `upstream_timeout` | `UPSTREAM_TIMEOUT_RETRY_AFTER_SECONDS`（60） |
| 推理后端连接失败或返回 5xx | `upstream_error` | — |
| 统一准入服务不可用 | `admission_unavailable` | 5 |

请求参数错误等 4xx 仍原样返回。真实原因保留在运行日志和用量统计的 `error_type`
（如 `ReadTimeout`、`UpstreamHTTP500`）中。`/readyz` 和管理接口仍使用 503。
ModelScope 公网入口自身产生的 502/504（例如非流式请求约 120 秒被断开、容器重启期间）
不经过本服务，无法由此改写。

## 溢出路由

`/v1` API 请求默认由本创空间的 vLLM 处理。以下情况会把请求转发到
[`AMD_Dev/GLM-5.3-Flash2`](https://www.modelscope.cn/studios/AMD_Dev/GLM-5.3-Flash2)
（`https://studio-amd-dev-glm-5-3-flash2.api-inference.modelscope.net/v1`）：

- 本机在途 API 请求达到 `OVERFLOW_PRIMARY_CAPACITY × OVERFLOW_TRIGGER_UTILIZATION`
  （默认 128 × 0.8 ≈ 103）后，按请求 ID 稳定哈希，将 `OVERFLOW_TRAFFIC_SHARE`
  （默认 50%）的新请求转给远端；在途请求达到容量后，新请求全部优先发往远端
- 本机 vLLM 未就绪（启动、预热、重启）时，所有 API 请求转给远端

路由在 `api.py` 进程内完成，请求体原样透传（包括 `video_url` 等多模态内容），不经过
vllm-router 或 nginx。转发到远端时：

- 使用 ModelScope Secret `GLM_WORKER_SERVICE_TOKEN` 作为 `Authorization`，并移除调用方
  的 `Authorization`、Cookie 和所有 `X-ModelScope-*` 头
- 添加 `X-Model-API-Overflow-Hop: 1`；带此头的请求只在本机处理，不会再次溢出，
  两个创空间互相配置溢出时不会循环转发

失败处理：在尚未向调用方输出任何内容前，连接失败可在本机与远端之间互相回退；远端返回
401/403/408/429/5xx 时回退到本机，并在 `OVERFLOW_FAILURE_COOLDOWN_SECONDS`（默认 60 秒）
内暂停溢出。后台每 `OVERFLOW_HEALTH_INTERVAL_SECONDS`（默认 10 秒）请求一次远端
`/readyz`，只有远端本机 vLLM 就绪（JSON `ready=true`）时才参与路由。网页对话始终使用
本机 vLLM，不计入在途统计。

| 变量 | 默认值 | 说明 |
|---|---|---|
| `OVERFLOW_ROUTING_ENABLED` | `1` | `0` 关闭溢出，全部请求回到本机 |
| `OVERFLOW_WORKER_BASE_URL` | `https://studio-amd-dev-glm-5-3-flash2.api-inference.modelscope.net` | 远端创空间 API 地址，末尾 `/v1` 可省略 |
| `GLM_WORKER_SERVICE_TOKEN` | 空 | 访问远端的服务 Token，必须配置为 Secret；为空时溢出自动关闭 |
| `OVERFLOW_PRIMARY_CAPACITY` | `128` | 本机在途请求容量，与 `MAX_NUM_SEQS` 一致 |
| `OVERFLOW_TRIGGER_UTILIZATION` | `0.8` | 开始溢出的本机占用比例 |
| `OVERFLOW_TRAFFIC_SHARE` | `0.5` | 繁忙但未满时转给远端的请求比例 |
| `OVERFLOW_NONSTREAM_WHEN_BUSY` | `1` | `0` 时本机繁忙也不溢出非流式请求（本机不可用时仍会溢出） |
| `OVERFLOW_FAILURE_COOLDOWN_SECONDS` | `60` | 远端请求失败后暂停溢出的时间 |

`/healthz` 的 `overflow_routing` 字段显示当前配置、本机/远端在途数、远端健康状态、
冷却剩余时间以及累计路由、回退次数（不包含 Token）。请求日志中的 `upstream_backend`
（`primary`/`overflow`）和 `routing_reason` 记录每个请求的实际后端和路由原因。

注意事项：

- 远端的统一试用准入按 Token 所属账号计数，而不是原调用方。该账号需完成 ADP 登记，
  否则远端会在试用次数用尽后返回 403；此时请求回退到本机，溢出暂停一个冷却周期
- 经 ModelScope 公网入口的非流式请求约 120 秒后可能被网关断开，长生成建议使用流式
- 溢出请求在本机和远端都会记录用量；远端统计归属于 Token 账号
- 本机繁忙时转给远端的请求不做本机 tokenize 预检，也不占用本机长上下文准入队列
- 回滚：设置 `OVERFLOW_ROUTING_ENABLED=0`（或删除 Token）后重启创空间

## 用户认证与额度

当前 Worker 不负责用户认证、开发者 Key、试用额度或 ADP 状态。上述策略全部由统一
LLM-Gateway 处理；Worker 只接收 Gateway 转发的请求并执行模型推理。旧 `/developer`
入口和 `X-Model-API-Key` 均不再使用。

## 用量统计与管理员导出

服务会异步统计 API 与网页对话的请求时间、入口、模型、结果、延迟、媒体数量，以及
请求体字节数、消息数、Prompt 数、请求的最大输出、`n`、工具数、推理强度，以及
prompt、completion、reasoning 和 total token。统计数据写入持久化 SQLite；不会保存
提示词、回复正文、原始 Access Token、Cookie 或 `studio_token`。统计功能采用异步写入，
异常不会中断或延迟推理请求，也不会作为 Worker 放行或拒绝请求的依据。历史 SQLite 表和
数据继续保留，旧开发者 Key 与试用额度状态仅用于历史兼容，不再参与请求准入。

ModelScope Docker 创空间只保证 `/mnt/workspace` 下的数据在重新部署后保留。生产环境
必须将 `USAGE_DB_PATH` 放在该目录下，并通过 Secret 设置至少 32 字节、长期稳定的
身份 HMAC 密钥：

```bash
USAGE_DB_PATH=/mnt/workspace/logs/glm53-flash/model-api-tp8-256k-graph256/usage.sqlite3
USAGE_IDENTITY_HMAC_KEY=<随机且长期稳定的高强度密钥>
```

该密钥不可随重新部署轮换；更换后，所有已签发应用 Key 都需要重新签发。

从旧版 `/workspace/logs` 路径升级时，必须在重新部署前于当前容器内生成一致性备份；
不要直接复制运行中的 WAL 数据库：

```bash
python3 - <<'PY'
from pathlib import Path
import sqlite3

source_path = Path(
    "/workspace/logs/glm53-flash/model-api-tp8-256k-graph256/usage.sqlite3"
)
target_path = Path(
    "/mnt/workspace/logs/glm53-flash/model-api-tp8-256k-graph256/usage.sqlite3"
)
target_path.parent.mkdir(parents=True, exist_ok=True)
source = sqlite3.connect(f"file:{source_path}?mode=ro", uri=True)
target = sqlite3.connect(target_path)
source.backup(target)
if target.execute("PRAGMA quick_check").fetchone()[0] != "ok":
    raise RuntimeError("usage SQLite backup failed integrity check")
target.close()
source.close()
target_path.chmod(0o600)
print(target_path)
PY
```

每日数据导出接口：

```bash
curl --fail \
  -H "Authorization: Bearer $MODELSCOPE_SDK_TOKEN" \
  -H "X-ModelScope-Access-Token: $MODELSCOPE_SDK_TOKEN" \
  "https://studio-amd-dev-model-api.api-inference.modelscope.net/admin/usage/daily?date=2026-09-09&timezone=US%2FCentral&format=json"

curl --fail -o usage-2026-09-09.csv \
  -H "Authorization: Bearer $MODELSCOPE_SDK_TOKEN" \
  -H "X-ModelScope-Access-Token: $MODELSCOPE_SDK_TOKEN" \
  "https://studio-amd-dev-model-api.api-inference.modelscope.net/admin/usage/daily?date=2026-09-09&timezone=US%2FCentral&format=csv"
```

公网网关使用 `Authorization` 完成 API 鉴权，应用使用
`X-ModelScope-Access-Token` 校验管理员权限，因此公网导出必须同时发送两个请求头。
只有对 `AMD_Dev/Model-API` 创空间具有编辑及以上权限的 ModelScope 账号可以导出。
创空间创建者和组织管理员也会根据创建人及权限级别识别。普通用户无法访问报表。当前
版本仅保存在本地数据库并提供导出；中央统计平台将在后续版本接入。

管理员可以检查公网网关实际转发的请求头名称：

```bash
curl --fail \
  -H "Authorization: Bearer $MODELSCOPE_SDK_TOKEN" \
  -H "X-ModelScope-Access-Token: $MODELSCOPE_SDK_TOKEN" \
  "https://studio-amd-dev-model-api.api-inference.modelscope.net/admin/usage/identity-headers"
```

该接口只返回请求头名称和身份头是否存在，不读取或返回任何请求头值，并设置
`Cache-Control: no-store`。它用于确认平台是否注入可信身份头，不能作为身份认证依据。

逐请求明细仅保留 `USAGE_RAW_RETENTION_DAYS` 指定的天数，可按用户、内部 UUID、
结果、模型和端点过滤，并使用 `next_cursor` 翻页：

```bash
curl --fail \
  -H "Authorization: Bearer $MODELSCOPE_SDK_TOKEN" \
  -H "X-ModelScope-Access-Token: $MODELSCOPE_SDK_TOKEN" \
  "https://studio-amd-dev-model-api.api-inference.modelscope.net/admin/usage/events?date=2026-09-11&timezone=Asia%2FShanghai&limit=100&format=json"
```

## Prompt 数据集采集与下载

Prompt 数据集采集与上述隐私安全用量统计相互独立，默认关闭。取得用户授权并确认数据
用途后，通过部署环境显式开启：

```bash
PROMPT_CAPTURE_ENABLED=1
PROMPT_CAPTURE_DB_PATH=/mnt/workspace/datasets/glm53-flash/model-api-tp8-256k-graph256/prompt-capture.sqlite3
```

开启后同时覆盖 OpenAI `/v1/chat/completions`、`/v1/completions`、
`/v1/responses` 与 Studio 网页对话。服务保存完整文本 `messages` / `input` /
`prompt`、相关生成参数及模型回复；图片、视频的 URL 和 base64 数据替换为媒体占位符。
Authorization、Cookie、ModelScope Token、应用 Key 和用户身份不会进入采集数据库。

主服务通过非阻塞 IPC 将记录交给独立低优先级子进程，所有 SQLite 写入均不在推理请求
线程中执行。IPC 暂时不可用、采集子进程退出或持久存储不可写时，会静默暂停接收新记录，
推理服务继续工作；恢复后继续收集新的 Prompt。暂停期间的请求无法事后补采。数据库没有
自动保留期或清理任务，已保存内容只会在开发人员明确删除数据库时消失。

具有 `AMD_Dev/Model-API` Studio 编辑权限的管理员可以导出全部已落盘记录：

```bash
curl --fail --location \
  -H "Authorization: Bearer $MODELSCOPE_SDK_TOKEN" \
  -H "X-ModelScope-Access-Token: $MODELSCOPE_SDK_TOKEN" \
  "https://studio-amd-dev-model-api.api-inference.modelscope.net/admin/dataset/prompts/download" \
  -o model-api-prompts-all.jsonl
```

也可按本地日期、入口或结果筛选：

```bash
curl --fail --location --get \
  -H "Authorization: Bearer $MODELSCOPE_SDK_TOKEN" \
  -H "X-ModelScope-Access-Token: $MODELSCOPE_SDK_TOKEN" \
  --data-urlencode "date=2026-09-18" \
  --data-urlencode "timezone=Asia/Shanghai" \
  --data-urlencode "entrypoint=openai_api" \
  --data-urlencode "outcome=success" \
  "https://studio-amd-dev-model-api.api-inference.modelscope.net/admin/dataset/prompts/download" \
  -o model-api-prompts-2026-09-18.jsonl
```

JSONL 每行包含 `request`、`response`、`request_id`、`model`、`endpoint`、
`entrypoint`、时间和结果状态，可进一步审核并转换为 SFT `messages` 格式。

## 常用配置

| 环境变量 | 默认值 | 说明 |
|---|---:|---|
| `MAX_IMAGES_PER_PROMPT` | `4` | 单会话图片上限 |
| `MAX_VIDEOS_PER_PROMPT` | `2` | 单会话视频上限 |
| `MAX_DOCUMENTS_PER_PROMPT` | `5` | 单会话文档上限 |
| `MAX_OUTPUT_TOKENS` | `32768` | 网页最大输出 |
| `LONG_PREFILL_TOKEN_THRESHOLD` | `2048` | 与已验证 FlyDSL 容器一致的 vLLM prefill chunk |
| `GLM53_GFX942_FLYDSL_INDEXER` | `1` | 启用 AITER FlyDSL FP8 MQA indexer |
| `GLM53_GFX942_FLYDSL_INDEXER_VARIANT` | `mfma_r4_w4` | 已验证的 FlyDSL kernel variant |
| `GLM53_GFX942_SPARSE_PREFILL_TUNE` | `1` | 启用 shape-scoped sparse-prefill 调优 |
| `USAGE_TELEMETRY_ENABLED` | `1` | 启用本地用量统计 |
| `USAGE_DB_PATH` | `/mnt/workspace/logs/glm53-flash/model-api-tp8-256k-graph256/usage.sqlite3` | 用量数据库 |
| `USAGE_RAW_RETENTION_DAYS` | `7` | 原始事件保留天数 |
| `USAGE_REPORT_TIMEZONE` | `US/Central` | 默认日报时区 |
| `USAGE_ADMIN_EXPORT_ENABLED` | `1` | 启用管理员导出接口 |
| `USAGE_ADMIN_STUDIO_NAME` | `Model-API` | 管理员权限校验对应的创空间名称 |
| `MODEL_API_KEY_ENABLED` | `0`（强制） | Worker 旧应用 Key 功能关闭 |
| `MODEL_API_KEY_REQUIRED` | `0`（强制） | Worker 不执行用户鉴权 |
| `MODEL_API_TRIAL_QUOTA_ENABLED` | `0`（强制） | Worker 不执行本地试用额度 |
| `PROMPT_CAPTURE_ENABLED` | `0` | 是否采集完整文本 Prompt 与模型回复 |
| `PROMPT_CAPTURE_DB_PATH` | `/mnt/workspace/datasets/glm53-flash/model-api-tp8-256k-graph256/prompt-capture.sqlite3` | 独立持久采集数据库 |
| `PROMPT_CAPTURE_ADMIN_EXPORT_ENABLED` | `1` | 启用管理员 JSONL 下载接口 |

更多可调参数及默认值见 [`.env.example`](.env.example)。

## 健康与日志

- `/healthz`：Web 服务、GPU、vLLM 状态和统计队列状态
- `/readyz`：对外流量就绪状态
- `/logs/download/all`：下载脱敏后的完整日志
- `/logs/download/recent`：下载脱敏后的最近 10000 行日志

日志下载会移除终端控制符并遮蔽常见 Token、API Key 和 Authorization 字段。