Skip to content

README_zh.md

Latest commit

 

History

History
184 lines (132 loc) · 6.45 KB

README_zh.md

File metadata and controls

184 lines (132 loc) · 6.45 KB

(English|简体中文|日本語|한국어)

FunASR OpenAI 兼容 API 服务

FunASR OpenAI 兼容 API 提供 /v1/audio/transcriptions，可作为私有语音转写服务接入 OpenAI 风格 SDK、Agent 框架、Dify、n8n、HTTP 节点和内部业务系统。

快速开始

pip install funasr fastapi uvicorn python-multipart
python server.py --model sensevoice --device cuda --port 8000

服务通常会在模型加载后启动。健康检查：GET /health。

需要直接复制的接入示例？可以继续查看 客户端配方、JavaScript/TypeScript 配方、Gradio 浏览器 Demo、工作流配方、Postman 集合、OpenAPI 规范、安全与网关指南 和 Kubernetes 部署模板。

端到端 smoke test

在另一个终端运行：

bash smoke_test.sh
# 不依赖 curl/bash 的跨平台方式：
python smoke_test.py

等价手动命令：

curl -L https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/BAC009S0764W0121.wav -o sample.wav
curl http://localhost:8000/health
curl http://localhost:8000/v1/audio/transcriptions \
  -F file=@sample.wav \
  -F model=sensevoice \
  -F response_format=verbose_json

Gradio 浏览器 Demo

如果希望用本地浏览器上传音频或测试麦克风，先启动 API 服务，再运行可选 Gradio 前端：

pip install gradio
python gradio_app.py --base-url http://localhost:8000

这个浏览器 demo 调用的就是 smoke test 使用的 OpenAI 兼容 API 端点。Docker、Kubernetes 和生产注意事项见 Gradio 浏览器 Demo。

使用 OpenAI SDK

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="not-needed")

result = client.audio.transcriptions.create(
    model="sensevoice",  # 也可以使用 "paraformer"、"paraformer-en"、"fun-asr-nano"
    file=open("meeting.wav", "rb"),
)
print(result.text)

verbose = client.audio.transcriptions.create(
    model="sensevoice",
    file=open("meeting.wav", "rb"),
    response_format="verbose_json",
)
print(verbose.segments)

使用 curl

curl http://localhost:8000/v1/audio/transcriptions \
  -F file=@audio.wav \
  -F model=sensevoice

curl http://localhost:8000/v1/audio/transcriptions \
  -F file=@audio.wav \
  -F model=sensevoice \
  -F response_format=verbose_json

可用模型

Model GPU 速度 CPU 速度 语言 特性
sensevoice 170x realtime 17x realtime zh/en/ja/ko/yue 情感与事件标签
paraformer 120x realtime 15x realtime zh/en 标点恢复
paraformer-en 120x realtime 15x realtime en 英文识别
fun-asr-nano 17x realtime 3.6x realtime 31 languages LLM-based，时间戳

API 端点

Endpoint Method 说明
/v1/audio/transcriptions POST OpenAI 兼容音频转写
/v1/models GET 列出模型别名
/health GET 健康检查、已加载模型和可用模型
/docs GET FastAPI Swagger 文档

不想写代码验证接口时，可以使用 Gradio 浏览器 Demo 做本地上传或麦克风测试，也可以导入 Postman 集合。如果要接入 API 网关、开发者门户或生成内部客户端，可以使用 OpenAPI 规范。

Agent 与低代码工作流

适用场景包括 LangChain、LlamaIndex、AutoGen、CrewAI、Semantic Kernel、Dify、n8n 和任何支持 OpenAI audio API 或 multipart HTTP 的系统。

Docker 部署

默认镜像以 CPU 模式启动，适合作为可复现 smoke test。

cd examples/openai_api
cp .env.example .env

docker compose up --build

等价 docker run：

docker build -t funasr-api .

docker run --rm -p 8000:8000 \
  -e FUNASR_DEVICE=cpu \
  -e FUNASR_MODEL=sensevoice \
  funasr-api

GPU 环境需要 NVIDIA Container Toolkit 和 CUDA-capable PyTorch/FunASR 镜像。适配 CUDA 依赖后，可使用：

docker run --rm --gpus all -p 8000:8000 \
  -e FUNASR_DEVICE=cuda \
  -e FUNASR_MODEL=sensevoice \
  funasr-api

验证容器：

BASE_URL=http://localhost:8000 bash smoke_test.sh
python smoke_test.py --base-url http://localhost:8000

Kubernetes 部署

在跨团队共享服务或通过网关暴露服务前，请先阅读 安全与网关指南，补齐 TLS、鉴权、上传限制、限流和日志策略。

如果需要在集群内部提供带持久化模型缓存、健康检查和私有 ClusterIP 的语音 API，可以从 Kubernetes 部署模板 开始。先构建并推送示例镜像，应用 manifests，再通过 kubectl port-forward 和 python smoke_test.py --base-url http://localhost:8000 验证。

在没有 CUDA-capable 镜像和 GPU 调度配置前，请保持默认 CPU 模式。

配置

参数 默认值 说明
--host 0.0.0.0 监听地址
--port 8000 监听端口
--device cuda cuda、cpu 或 mps
--model sensevoice 启动时预加载模型

Docker 环境变量：

Env 默认值 说明
FUNASR_PORT 8000 传给 server.py 的容器端口
FUNASR_DEVICE cpu 容器设备模式；只有在镜像已适配 CUDA 时才设为 cuda
FUNASR_MODEL sensevoice 容器启动时加载的模型别名

故障排查

现象 处理方式
CUDA 不可用 先用 --device cpu 跑通 smoke test。
8000 端口被占用 改用 --port 9000，并运行 BASE_URL=http://localhost:9000 bash smoke_test.sh 或 python smoke_test.py --base-url http://localhost:9000。
模型下载很慢 换稳定网络，或提前从 ModelScope/Hugging Face 下载模型。
Dify/n8n 容器里访问 localhost 失败 使用工作流运行时可访问的主机名、Compose service name 或 Kubernetes service name。
响应中没有 segments 设置 response_format=verbose_json。