modelscope/FunASR
1
0
Fork 0
mirror of https://github.com/modelscope/FunASR.git synced 2026-10-12 02:19:18 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: align Gradio guides with isolated MOSS serving profiles

Browse Source 
Signed-off-by: zhifu gao <[email protected]>
This commit is contained in:
zhifu gao
2026-09-07 19:53:23 +00:00
parent d91d961e37
commit 11198050ce
7 changed files with 331 additions and 102 deletions
Download Patch File Download Diff File Expand all files Collapse all files
examples/openai_api/GRADIO.md
+85 -32
View File
@@ -1,66 +1,119 @@
# Gradio Browser Demo for the FunASR OpenAI-Compatible API
Use this demo when you want a browser UI for uploading or recording audio while the FunASR OpenAI-compatible API server runs locally, in Docker, or behind a private Kubernetes service.
Use this optional browser UI to upload a file or record audio for a prepared FunASR, native vLLM, or native SGLang Omni transcription service. The Gradio app is an HTTP client: it does not load models or install the server's acoustic dependencies. Recording is submitted as a complete file; this is not streaming transcription or a realtime wake-word service.
The Gradio app does not load FunASR models itself. It calls the same `/health`, `/v1/models`, and `/v1/audio/transcriptions` endpoints used by the smoke tests, SDK recipes, Postman collection, and OpenAPI spec.
Keep both listeners private. The demo is not an authentication gateway: it does not configure UI authentication or send backend `Authorization` credentials. The API base URL is editable, and requests originate from the **Gradio process**, not directly from the browser. Do not share this operator UI with untrusted users. Read the [security and gateway guide](SECURITY.md) before the first launch; its Basic gateway is not directly compatible with this client's unauthenticated requests.
## 1. Start the API server
From `examples/openai_api`:
For the repository's example API, start with the same prepared checkout as the [HTTP server guide](README.md#quick-start). In a POSIX shell with Python 3.11 available:
```bash
pip install funasr fastapi uvicorn python-multipart
python server.py --model sensevoice --device cuda --port 8000
git clone https://github.com/modelscope/FunASR.git FunASR-api
cd FunASR-api
git checkout --detach d91d961e37a005837b1523bcc6b09f087877be54
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
python -m pip install fastapi uvicorn python-multipart
python -m pip check
cd examples/openai_api
python server.py --host 127.0.0.1 --model sensevoice --device cpu --port 8000
```
For a portable CPU check, use `--device cpu`. For Docker Compose or Kubernetes, keep the service private and expose it locally with the documented port mapping or `kubectl port-forward`.
This pins source, not dependencies, model weights, decoders, or CUDA. It is an installation recipe, not a clean-install or acoustic validation result. Wait for model loading before checking the service. After preparing GPU dependencies, use the HTTP guide's CUDA alternative instead of running a second server on port 8000.
For MOSS, prepare the dedicated environment and pinned server/model revisions in the [MOSS deployment guide](../../docs/moss_transcribe_diarize.md). Choose its FunASR service, native vLLM, or native SGLang Omni path first; the UI profile does not launch, convert, or reconfigure that server. MOSS performs joint offline transcription and diarization without an external VAD or speaker model. Do not try to install its GPU environment into the lightweight Gradio environment below.
Docker and Kubernetes are alternative backend deployments. Publish container port 8000 only on host loopback, or use a private `kubectl port-forward`; container-internal `0.0.0.0` is different from host exposure. `ClusterIP` alone is not network isolation. A cluster DNS name works only where the Gradio process can resolve and reach it. From a laptop, use the locally forwarded address, not an unresolvable `*.svc.cluster.local` URL. See [Docker deployment](README.md#docker-deployment) and [Kubernetes deployment](kubernetes/README.md).
## 2. Install and launch the browser UI
In another terminal:
Open a **new terminal**, starting in the directory that contains `FunASR-api`. Use a separate Python 3.12 environment `.venv-gradio`, not the server's `.venv` or a native backend environment. The client recipe selects Gradio 6.26.0; this version pin alone is not evidence of a successful installation or compatibility with every backend release.
```bash
pip install gradio
python gradio_app.py --base-url http://localhost:8000
cd FunASR-api
python3.12 -m venv .venv-gradio
source .venv-gradio/bin/activate
python -m pip install "gradio==6.26.0"
python -m pip check
cd examples/openai_api
python gradio_app.py --backend funasr --model sensevoice --base-url http://127.0.0.1:8000 --host 127.0.0.1 --port 7860
```
Open the printed local URL, upload or record an audio file, choose a model alias, and click **Transcribe**.
No FunASR, Torch, CUDA, or model download is required by the Gradio client itself. The separately running backend still needs its own prepared dependencies and models. In subsequent client terminals, activate `.venv-gradio` from the checkout root and then enter `examples/openai_api` before running the commands below.
Open the printed local URL, allow microphone access only when needed, upload or record an audio file, choose **Model alias** and **Response format**, and click **Transcribe**. The CLI defaults are backend `funasr`, model `sensevoice`, and format `verbose_json`. The UI listens on port 7860, separate from the backend's port. Browser microphone access depends on permissions and a secure context; a remote plain-HTTP UI is not a portable microphone recipe.
The following launches are **alternatives**, using the same activated client environment and directory. Stop the previous UI before reusing port 7860; start the matching backend separately first. `--backend` explicitly selects a client profile: it does not detect or switch the running server. Use the service base URL **without `/v1`**, unlike an OpenAI SDK base URL. The client appends `/v1/audio/transcriptions`.
For the FunASR example or packaged service prepared with MOSS:
```bash
python gradio_app.py --backend funasr --model moss-transcribe-diarize --base-url http://127.0.0.1:8000 --host 127.0.0.1 --port 7860
```
For the pinned native vLLM recipe with `--served-model-name moss-transcribe-diarize`:
```bash
python gradio_app.py --backend vllm --model moss-transcribe-diarize --base-url http://127.0.0.1:8898 --host 127.0.0.1 --port 7860
```
For the native SGLang Omni recipe using its full model ID, the dropdown displays the shorter label `MOSS-Transcribe-Diarize`; the request still sends the complete ID:
```bash
python gradio_app.py --backend sglang-omni --model OpenMOSS-Team/MOSS-Transcribe-Diarize --base-url http://127.0.0.1:8898 --host 127.0.0.1 --port 7860
```
An explicit `--model` is an operator override, added to the choices and sent exactly as the request's `model`; it does not register a server alias or change the checkpoint. For example, only after configuring a vLLM service to accept the served name `meeting-asr`, use:
```bash
python gradio_app.py --backend vllm --model meeting-asr --base-url http://127.0.0.1:8898 --host 127.0.0.1 --port 7860
```
Do not substitute a full Hugging Face ID for a FunASR request alias. The example API validates its five aliases; the packaged service's `--model-path`/`--hub` deployment uses request model `custom`. The UI override does not bypass either server's model validation. Check the active profile, model, and format before sending audio.
## 3. Verify the backend first
The UI has a **Check service** button. You can run the same check in a terminal:
**Check service** requests `/health` and `/v1/models`. This is metadata inspection, not an acoustic test and not a model-readiness guarantee. Server schemas and route policies differ: a native service or gateway may deny a metadata route while allowing transcription. Do not expose private metadata or remove authentication merely to make the button succeed.
For the unauthenticated loopback FunASR example service, in the activated client environment and `examples/openai_api` directory:
```bash
python smoke_test.py --base-url http://localhost:8000
curl http://localhost:8000/v1/models
curl --fail --silent --show-error http://127.0.0.1:8000/health
curl --fail --silent --show-error http://127.0.0.1:8000/v1/models
python smoke_test.py --base-url http://127.0.0.1:8000 --model sensevoice
```
If the API server is remote, set the reachable URL explicitly:
The first two commands inspect metadata only. The optional `smoke_test.py` command is different: if its default `sample.wav` is missing, it downloads a public Chinese sample, writes it in the current directory, performs transcription, and prints the result. It is not a multilingual accuracy benchmark or a metadata-only check. Use controlled audio and protect diagnostic output. The smoke script's model must match the prepared service too; this command does not validate a MOSS/native deployment.
```bash
python gradio_app.py --base-url http://funasr-api.speech.svc.cluster.local:8000
```
For OpenAI SDK clients, remember that SDK base URLs include `/v1`; this Gradio demo expects the direct service base URL without `/v1`.
The UI's timeout defaults to 300 seconds and is passed to the HTTP client. It is not a total job deadline; a client timeout does not cancel backend inference or establish safe concurrency limits.
## Model aliases
| Alias | Good first use |
|---|---|
| `sensevoice` | Fast multilingual private transcription and agent voice input. |
| `paraformer` | Mandarin-oriented production transcription. |
| `paraformer-en` | English-only compatibility checks. |
| `fun-asr-nano` | LLM-based ASR and vLLM experiments. |
| `moss-transcribe-diarize` | Offline long-form transcription with timestamps and anonymous speaker labels; select `verbose_json`. |
The `funasr` profile offers these five request aliases. A listed alias does not mean the checkpoint is loaded, cached, or supported by the installed dependencies; selecting another model can cause the example API to load it on demand.
MOSS requires the dedicated GPU service environment and is not a realtime
microphone model. See the [MOSS deployment guide](../../docs/moss_transcribe_diarize.md).
- `sensevoice`: SenseVoice transcription through FunASR. HTTP text has its language/emotion/event tags removed; the UI's raw response is not the SDK's raw tagged output.
- `paraformer`: Mandarin-oriented transcription through the configured FunASR pipeline, not a throughput or production-capacity guarantee.
- `paraformer-en`: English transcription through the configured FunASR pipeline.
- `fun-asr-nano`: The base Fun-ASR-Nano model, not the separate 31-language Fun-ASR-MLT-Nano checkpoint; do not assume Korean support. Choosing this alias on example `server.py` does not start native vLLM.
- `moss-transcribe-diarize`: Third-party OpenMOSS joint offline transcription and diarization in its dedicated environment. Its recording-local anonymous speaker label is not an identity determination; it is not a realtime microphone model. Use `verbose_json` to inspect the FunASR service's segments.
Backend profiles deliberately have different defaults and formats:
**funasr** defaults to `sensevoice` and `verbose_json`, and also offers `json`. The example API's `json` contains `text`; its `verbose_json` maps `sentence_info` to `segments` with `start`/`end` in seconds and a model-dependent `speaker`. Segments can be empty; requesting verbose output does not create diarization. Example `duration` is inference time, whereas packaged FunASR reports audio duration. See [API boundaries](README.md#api-contract).
**vllm** defaults to `moss-transcribe-diarize` and `diarized_json`, and also offers `json`. On the pinned MOSS serving path, `diarized_json` contains structured speaker-attributed segments; `json` preserves compact tagged text. This is not a promise for arbitrary vLLM models or releases. Do not send `diarized_json` to the FunASR profile expecting the same result.
**sglang-omni** defaults to `OpenMOSS-Team/MOSS-Transcribe-Diarize` and offers only `verbose_json`. In the documented native contract, `[Sxx]` remains in `segments[].text`; it is not a separate `speaker` field. The Gradio client displays the returned `text` and JSON without stripping tags, inventing labels, or normalizing these backend differences. See the pinned [MOSS deployment guide](../../docs/moss_transcribe_diarize.md) for protocol/version limits and long-audio controls; this UI does not expose backend-specific token budgets.
See the [model selection guide](../../docs/model_selection.md) for a deeper comparison.
## Production notes
- Treat the Gradio app as a demo or internal operator UI, not a public production frontend.
- Add authentication, TLS, upload-size limits, and rate limits before exposing any audio upload UI outside a trusted network; see the [security and gateway guide](SECURITY.md).
- Keep browser uploads close to your backend; do not send private audio to an unauthenticated public endpoint.
- Log model alias, audio duration, latency, response format, and error text when debugging.
- Treat this as a private operator demo, not a public production frontend. Do not enable `--share` for sensitive audio. A loopback UI does not make a separately exposed backend private.
- The editable API URL controls server-side requests. There is no application target allowlist or redirect restriction; the HTTP client can follow redirects. Restrict who can operate the UI and the Gradio process's network access. Do not put passwords or access tokens into URLs.
- The demo does not configure Basic, Bearer, OIDC, or mTLS backend credentials. TLS, authentication, upload and response limits, rate/concurrency admission, and network isolation require a separately designed deployment. An OpenAI SDK `api_key` example does not add authentication to this Gradio client.
- Audio travels from browser to Gradio and then to the API. Gradio uses file-path inputs; the multipart builder reads the entire file into memory, and the example API also buffers and writes a temporary file. Do not promise no disk storage, immediate deletion, or safe unlimited uploads. Verify the chosen Gradio version's cache/retention behavior and provision private temporary storage, request-size and duration limits.
- The UI displays the server response and may show upstream error bodies, URLs, or exception details. Redact diagnostics before sharing; do not log raw error text, audio, or transcripts by default. Define access, retention, and deletion rules for both services.
- Validate the exact client/backend revisions with controlled files and your real gateway policy. Successful JSON display is not proof of diarization accuracy, identity recognition, throughput, cancellation, public-network isolation, or compatibility with every native server version.
examples/openai_api/GRADIO_zh.md
+86 -33
View File
@@ -1,66 +1,119 @@
# FunASR OpenAI 兼容 API Gradio 浏览器 Demo
当 FunASR OpenAI 兼容 API 已经在本地、Docker 或私有 Kubernetes 服务中运行，而你想用浏览器上传或录制音频时，可以使用这个 Gradio demo。
这个可选浏览器 UI 用于向已准备好的 FunASR、原生 vLLM 或原生 SGLang Omni 转写服务上传文件或录制音频。Gradio app 是 HTTP 客户端，不加载模型，也不安装服务端的声学依赖。录音完成后按完整文件提交；这不是流式识别或实时唤醒服务。
Gradio app 本身不加载 FunASR 模型。它调用和 smoke test、SDK 配方、Postman 集合、OpenAPI 规范相同的 `/health`、`/v1/models` 和 `/v1/audio/transcriptions` 接口。
两个服务都应保持私有。此 demo 不是鉴权网关：没有配置 UI 鉴权，也不向后端发送 `Authorization` 凭据。API base URL 可以编辑，请求由 **Gradio 进程**发起，而不是浏览器直接发起。不要把这个操作界面分享给不可信用户。首次启动前请阅读[安全与网关指南](SECURITY_zh.md)；其中的 Basic 网关不能直接接收此客户端的无鉴权请求。
## 1. 启动 API 服务
在 `examples/openai_api` 目录中执行：
使用仓库的 example API 时，先按 [HTTP 服务指南](README_zh.md#快速开始)准备同一份 checkout。在已安装 Python 3.11 的 POSIX shell 中执行：
```bash
pip install funasr fastapi uvicorn python-multipart
python server.py --model sensevoice --device cuda --port 8000
git clone https://github.com/modelscope/FunASR.git FunASR-api
cd FunASR-api
git checkout --detach d91d961e37a005837b1523bcc6b09f087877be54
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
python -m pip install fastapi uvicorn python-multipart
python -m pip check
cd examples/openai_api
python server.py --host 127.0.0.1 --model sensevoice --device cpu --port 8000
```
便携 CPU 验证可以使用 `--device cpu`。如果使用 Docker Compose 或 Kubernetes，请保持服务私有，并通过文档中的端口映射或 `kubectl port-forward` 暴露到本机验证。
这里只固定源码，不固定依赖、模型权重、解码器或 CUDA。这是安装配方，不是全新安装或声学验证结果。模型加载完成后再检查服务。准备好 GPU 依赖后，可改用 HTTP 指南中的 CUDA 替代命令，不要在 8000 端口再启动第二个服务。
MOSS 需要按 [MOSS 部署指南](../../docs/moss_transcribe_diarize_zh.md)准备专用环境以及固定的服务端和模型 revision。先选择其中的 FunASR 服务、原生 vLLM 或原生 SGLang Omni 路径；UI profile 不会启动、转换或重新配置后端。MOSS 联合完成离线转写和说话人分离，无需外部 VAD 或说话人模型。不要把其 GPU 环境安装到下文的轻量 Gradio 环境中。
Docker 和 Kubernetes 是后端的替代部署方式。容器 8000 端口只发布到主机 loopback，或使用私有 `kubectl port-forward`；容器内部监听 `0.0.0.0` 与主机端口暴露是不同边界。`ClusterIP` 本身不是网络隔离。只有 Gradio 进程能解析并访问集群 DNS 时才能使用该地址。在笔记本上应使用本地转发地址，而不是无法解析的 `*.svc.cluster.local` URL。参见 [Docker 部署](README_zh.md#docker-部署)和 [Kubernetes 部署](kubernetes/README_zh.md)。
## 2. 安装并启动浏览器 UI
在另一个终端执行：
打开**新终端**，从包含 `FunASR-api` 的目录开始。使用独立的 Python 3.12 环境 `.venv-gradio`，不要使用服务端 `.venv` 或原生后端环境。客户端配方选择 Gradio 6.26.0；仅固定版本不代表已成功安装，也不代表兼容所有后端发布版。
```bash
pip install gradio
python gradio_app.py --base-url http://localhost:8000
cd FunASR-api
python3.12 -m venv .venv-gradio
source .venv-gradio/bin/activate
python -m pip install "gradio==6.26.0"
python -m pip check
cd examples/openai_api
python gradio_app.py --backend funasr --model sensevoice --base-url http://127.0.0.1:8000 --host 127.0.0.1 --port 7860
```
打开命令行输出的本地 URL，上传或录制音频，选择模型 alias，然后点击 **Transcribe**。
Gradio 客户端本身不需要 FunASR、Torch、CUDA 或下载模型。独立运行的后端仍需要准备自己的依赖和模型。以后打开客户端终端时，先在 checkout 根目录激活 `.venv-gradio`，再进入 `examples/openai_api` 运行下列命令。
打开命令行输出的本地 URL，只在需要时允许麦克风访问，上传或录制音频，选择 **Model alias** 和 **Response format**，再点击 **Transcribe**。CLI 默认 backend 为 `funasr`，model 为 `sensevoice`，格式为 `verbose_json`。UI 使用 7860 端口，与后端端口分开。浏览器麦克风依赖权限和安全上下文；远程普通 HTTP UI 不是可通用的麦克风配方。
以下启动方式是**替代选项**，都在同一已激活的客户端环境和目录中执行。复用 7860 端口前先停止旧 UI，并另行启动匹配的后端。`--backend` 显式选择客户端 profile，不会探测或切换运行中的服务。服务 base URL **不带 `/v1`**，这与 OpenAI SDK 的 base URL 不同。客户端会追加 `/v1/audio/transcriptions`。
连接已为 MOSS 准备好的 FunASR example 或 packaged 服务：
```bash
python gradio_app.py --backend funasr --model moss-transcribe-diarize --base-url http://127.0.0.1:8000 --host 127.0.0.1 --port 7860
```
连接固定 revision 的原生 vLLM 配方，后端使用 `--served-model-name moss-transcribe-diarize`：
```bash
python gradio_app.py --backend vllm --model moss-transcribe-diarize --base-url http://127.0.0.1:8898 --host 127.0.0.1 --port 7860
```
连接使用完整模型 ID 的原生 SGLang Omni 配方时，下拉框显示较短的标签 `MOSS-Transcribe-Diarize`，请求仍发送完整 ID：
```bash
python gradio_app.py --backend sglang-omni --model OpenMOSS-Team/MOSS-Transcribe-Diarize --base-url http://127.0.0.1:8898 --host 127.0.0.1 --port 7860
```
显式 `--model` 是操作人员配置的覆盖值，会加入选项并作为请求的 `model` 原样发送，不会注册服务端 alias 或更换 checkpoint。例如，只有先把 vLLM 服务配置为接受 served name `meeting-asr` 后，才使用：
```bash
python gradio_app.py --backend vllm --model meeting-asr --base-url http://127.0.0.1:8898 --host 127.0.0.1 --port 7860
```
不要用完整 Hugging Face ID 替换 FunASR 请求 alias。example API 校验其五个 alias；packaged 服务的 `--model-path`/`--hub` 部署使用请求模型 `custom`。UI 的覆盖值不会绕过任何一类服务的模型校验。发送音频前检查当前 profile、model 和格式。
## 3. 先验证后端服务
UI 中有 **Check service** 按钮。你也可以在终端运行相同检查：
**Check service** 请求 `/health` 和 `/v1/models`。这是 metadata 检查，不是声学测试，也不代表模型就绪。不同服务的 schema 和路由策略不同：原生服务或网关可能拒绝某个 metadata 路由，但允许转写。不要为了让按钮成功而公开私有 metadata 或移除鉴权。
对于无鉴权、仅监听 loopback 的 FunASR example 服务，在已激活的客户端环境及 `examples/openai_api` 目录中执行：
```bash
python smoke_test.py --base-url http://localhost:8000
curl http://localhost:8000/v1/models
curl --fail --silent --show-error http://127.0.0.1:8000/health
curl --fail --silent --show-error http://127.0.0.1:8000/v1/models
python smoke_test.py --base-url http://127.0.0.1:8000 --model sensevoice
```
如果 API 服务在远端，请显式设置可访问的地址：
前两条命令只检查 metadata。可选的 `smoke_test.py` 命令不同：若默认的 `sample.wav` 不存在，它会下载公开中文样本，写入当前目录，执行转写并打印结果。它不是多语言准确率 benchmark，也不是仅检查 metadata。请使用受控音频并保护诊断输出。smoke 脚本的模型也必须与已准备的服务匹配；这条命令不验证 MOSS/native 部署。
```bash
python gradio_app.py --base-url http://funasr-api.speech.svc.cluster.local:8000
```
OpenAI SDK 的 base URL 需要包含 `/v1`；这个 Gradio demo 使用的是不带 `/v1` 的直接服务 base URL。
UI timeout 默认为 300 秒，并传给 HTTP 客户端。它不是整个任务的截止时间；客户端超时不会取消后端推理，也不能确定安全并发上限。
## 模型别名
| Alias | 适合场景 |
|---|---|
| `sensevoice` | 快速多语种私有转写和 Agent 语音输入。 |
| `paraformer` | 中文生产转写。 |
| `paraformer-en` | 英文兼容性检查。 |
| `fun-asr-nano` | LLM-based ASR 和 vLLM 实验。 |
| `moss-transcribe-diarize` | 离线长音频转写、时间戳和匿名说话人标签；请选择 `verbose_json`。 |
`funasr` profile 提供下列五个请求 alias。列出 alias 不代表 checkpoint 已加载、已缓存或被当前安装的依赖支持；选择其他模型可能触发 example API 按需加载。
MOSS 需要专用 GPU 服务环境，不适合作为实时麦克风模型。详见
[MOSS 部署指南](../../docs/moss_transcribe_diarize_zh.md)。
- `sensevoice`：通过 FunASR 进行 SenseVoice 转写。HTTP text 已移除语言、情绪和事件标签；UI 的原始响应不是 SDK 的原始标签输出。
- `paraformer`：通过已配置的 FunASR pipeline 进行中文转写，不保证吞吐或生产容量。
- `paraformer-en`：通过已配置的 FunASR pipeline 进行英文转写。
- `fun-asr-nano`：基础 Fun-ASR-Nano 模型，不是独立的 31 语言 Fun-ASR-MLT-Nano checkpoint，不应假定支持韩语。在 example `server.py` 中选择此 alias 不会启动原生 vLLM。
- `moss-transcribe-diarize`：第三方 OpenMOSS，在专用环境中联合完成离线转写和说话人分离。录音内的匿名说话人标签不是身份认定；它不是实时麦克风模型。使用 `verbose_json` 检查 FunASR 服务的 segments。
更完整的对比见 [模型选择指南](../../docs/model_selection_zh.md)。
不同 backend profile 有意采用不同默认值和格式：
**funasr** 默认 `sensevoice` 和 `verbose_json`，也可选 `json`。example API 的 `json` 包含 `text`；其 `verbose_json` 将 `sentence_info` 映射为 `segments`，`start`/`end` 单位为秒，`speaker` 取决于模型。segments 可以为空；请求 verbose 输出不会创建说话人分离能力。example 的 `duration` 是推理耗时，packaged FunASR 则报告音频时长。参见 [API 边界](README_zh.md#api-contract)。
**vllm** 默认 `moss-transcribe-diarize` 和 `diarized_json`，也可选 `json`。在固定 revision 的 MOSS 部署路径中，`diarized_json` 包含结构化说话人片段；`json` 保留紧凑标签文本。这不是对任意 vLLM 模型或发布版的承诺。不要向 FunASR profile 发送 `diarized_json` 并期待同样的结果。
**sglang-omni** 默认 `OpenMOSS-Team/MOSS-Transcribe-Diarize`，仅提供 `verbose_json`。在文档记录的原生契约中，`[Sxx]` 保留于 `segments[].text`，不是独立的 `speaker` 字段。Gradio 客户端展示返回的 `text` 和 JSON，不剥离标签、不生成说话人标签，也不归一化这些后端差异。协议、版本限制和长音频控制参见固定 revision 的 [MOSS 部署指南](../../docs/moss_transcribe_diarize_zh.md)；此 UI 没有暴露后端特定的 token 预算参数。
更完整的对比见[模型选择指南](../../docs/model_selection_zh.md)。
## 生产注意事项
- Gradio app 适合作为 demo 或内部操作界面，不建议直接作为公网生产前端。
- 任何音频上传 UI 对可信网络外开放前，都需要先增加鉴权、TLS、上传大小限制和限流；见 [安全与网关指南](SECURITY_zh.md)。
- 浏览器上传应尽量靠近你的后端服务，不要把私有音频发送到未鉴权的公网端点。
- 排查问题时记录模型 alias、音频时长、延迟、响应格式和错误文本。
- 把它当作私有操作 demo，而不是公网生产前端。敏感音频不要启用 `--share`。UI 监听 loopback 不会让另行暴露的后端变成私有服务。
- 可编辑 API URL 控制服务端请求。应用没有目标 allowlist 或重定向限制，HTTP 客户端可以跟随重定向。应限制 UI 使用者和 Gradio 进程的网络访问范围，不要把密码或访问 token 放进 URL。
- demo 没有配置 Basic、Bearer、OIDC 或 mTLS 后端凭据。TLS、鉴权、上传及响应大小限制、限流、并发准入和网络隔离都需要另行设计部署。OpenAI SDK 的 `api_key` 示例不会为此 Gradio 客户端增加鉴权。
- 音频从浏览器传到 Gradio，再传到 API。Gradio 使用文件路径输入，multipart builder 会将整文件读入内存，example API 也会缓冲并写入临时文件。不能承诺无落盘、立即删除或安全地无限上传。需核验所选 Gradio 版本的缓存和保留行为，准备私有临时存储、请求大小和时长限制。
- UI 显示服务端响应，也可能显示上游错误正文、URL 或异常详情。分享诊断信息前先脱敏，不要默认记录原始错误文本、音频或转写正文。为两类服务制定访问、保留和删除规则。
- 用受控文件和真实网关策略验证准确的客户端及后端 revision。成功显示 JSON 不能证明说话人分离准确率、身份识别、吞吐、取消能力、公网隔离或兼容所有原生服务版本。
examples/openai_api/README.md
+2 -9
View File
@@ -28,7 +28,7 @@ Use a fresh checkout and a POSIX shell with Python 3.11 installed:
```bash
git clone https://github.com/modelscope/FunASR.git FunASR-api
cd FunASR-api
git checkout --detach e19029adca384a06a2f60bd8c18cb98f1a0499aa
git checkout --detach d91d961e37a005837b1523bcc6b09f087877be54
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
@@ -69,14 +69,7 @@ curl http://localhost:8000/v1/audio/transcriptions \
## Browser demo with Gradio
If you want a local browser UI for upload or microphone testing, run the API server first and then launch the optional Gradio frontend:
```bash
python -m pip install gradio
python gradio_app.py --base-url http://localhost:8000
```
The browser demo calls the same OpenAI-compatible API endpoints as the smoke tests. See [Gradio browser demo](GRADIO.md) for Docker, Kubernetes, and production notes.
For local file upload or recorded microphone audio, follow the maintained [Gradio browser demo](GRADIO.md). It uses a separate Python 3.12 environment, `.venv-gradio`, rather than this API server's environment. The guide covers the `funasr`, `vllm`, and `sglang-omni` profiles, explicit model selection, Docker/Kubernetes connectivity, microphone permissions, and privacy limits. The UI is a separate HTTP client, not an authentication gateway or a realtime transcription service.
## Usage with OpenAI SDK (Python)
examples/openai_api/README_ja.md
+2 -9
View File
@@ -30,7 +30,7 @@ POSIX シェルと Python 3.11 を使い、新しいチェックアウトと仮
```bash
git clone https://github.com/modelscope/FunASR.git FunASR-api
cd FunASR-api
git checkout --detach e19029adca384a06a2f60bd8c18cb98f1a0499aa
git checkout --detach d91d961e37a005837b1523bcc6b09f087877be54
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
@@ -86,14 +86,7 @@ curl -fsS http://localhost:8000/v1/audio/transcriptions \
## Gradio ブラウザデモ
ローカルブラウザで音声ファイルのアップロードやマイク入力を試したい場合は、先に API サーバーを起動し、オプションの Gradio フロントエンドを起動します。
```bash
python -m pip install gradio
python gradio_app.py --base-url http://localhost:8000
```
このブラウザデモは smoke test と同じ API エンドポイントを呼び出す別のフロントエンドであり、API に認証を追加するものではありません。マイク権限、Docker、Kubernetes、本番利用の注意点は [Gradio ブラウザデモ](GRADIO.md)を参照してください。
ローカルファイルのアップロードやマイクで録音した音声の送信には、保守されている [Gradio ブラウザデモ](GRADIO.md)を参照してください。この API サーバーとは別の Python 3.12 環境 `.venv-gradio` を使用します。ガイドでは `funasr`、`vllm`、`sglang-omni` の profiles、明示的なモデル選択、Docker/Kubernetes への接続、マイク権限、プライバシー上の制約を説明しています。UI は独立した HTTP クライアントであり、認証ゲートウェイでもリアルタイム文字起こしサービスでもありません。
## OpenAI SDK で使う
examples/openai_api/README_ko.md
+2 -9
View File
@@ -30,7 +30,7 @@ POSIX 셸과 Python 3.11을 사용해 새 체크아웃과 가상 환경을 만
```bash
git clone https://github.com/modelscope/FunASR.git FunASR-api
cd FunASR-api
git checkout --detach e19029adca384a06a2f60bd8c18cb98f1a0499aa
git checkout --detach d91d961e37a005837b1523bcc6b09f087877be54
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
@@ -86,14 +86,7 @@ curl -fsS http://localhost:8000/v1/audio/transcriptions \
## Gradio 브라우저 데모
로컬 브라우저에서 파일 업로드나 마이크 입력을 테스트하려면 먼저 API 서버를 시작한 뒤 선택 사항인 Gradio 프런트엔드를 실행합니다.
```bash
python -m pip install gradio
python gradio_app.py --base-url http://localhost:8000
```
이 브라우저 데모는 smoke test와 같은 API 엔드포인트를 호출하는 별도 프런트엔드이며 API에 인증을 추가하지 않습니다. 마이크 권한, Docker, Kubernetes, 프로덕션 참고 사항은 [Gradio 브라우저 데모](GRADIO.md)를 확인하세요.
로컬 파일을 업로드하거나 마이크로 녹음한 음성을 보내려면 유지 관리되는 [Gradio 브라우저 데모](GRADIO.md)를 참고하세요. 이 API 서버와 별도의 Python 3.12 환경 `.venv-gradio`를 사용합니다. 가이드에서는 `funasr`, `vllm`, `sglang-omni` profiles, 명시적 모델 선택, Docker/Kubernetes 연결, 마이크 권한과 개인정보 보호상의 제한을 다룹니다. UI는 별도의 HTTP 클라이언트이며 인증 게이트웨이나 실시간 전사 서비스가 아닙니다.
## OpenAI SDK로 사용하기
examples/openai_api/README_zh.md
+2 -9
View File
@@ -28,7 +28,7 @@ SDK 的 `timestamp` 或 Nano 的 `timestamps` / `ctc_timestamps` 输出不会自
```bash
git clone https://github.com/modelscope/FunASR.git FunASR-api
cd FunASR-api
git checkout --detach e19029adca384a06a2f60bd8c18cb98f1a0499aa
git checkout --detach d91d961e37a005837b1523bcc6b09f087877be54
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
@@ -69,14 +69,7 @@ curl http://localhost:8000/v1/audio/transcriptions \
## Gradio 浏览器 Demo
如果希望用本地浏览器上传音频或测试麦克风，先启动 API 服务，再运行可选 Gradio 前端：
```bash
python -m pip install gradio
python gradio_app.py --base-url http://localhost:8000
```
这个浏览器 demo 调用的就是 smoke test 使用的 OpenAI 兼容 API 端点。Docker、Kubernetes 和生产注意事项见 [Gradio 浏览器 Demo](GRADIO_zh.md)。
本地文件上传或录制麦克风音频请使用维护中的 [Gradio 浏览器 Demo](GRADIO_zh.md)。它使用独立的 Python 3.12 环境 `.venv-gradio`，而不是本 API 服务的环境。指南覆盖 `funasr`、`vllm`、`sglang-omni` profiles、显式模型选择、Docker/Kubernetes 连通性、麦克风权限和隐私限制。UI 是独立 HTTP 客户端，不是鉴权网关或实时转写服务。
## 使用 OpenAI SDK