mirror of
https://github.com/modelscope/FunASR.git
synced 2026-10-12 02:19:18 +00:00
docs: add OpenAI API security gateway guide
Add English and Chinese gateway hardening docs for the OpenAI-compatible API and link them from deployment and recipe docs.
This commit is contained in:
zhifu gao
@@ -198,7 +198,7 @@ curl http://localhost:8000/v1/audio/transcriptions \
|
||||
docker pull registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-online-cpu-0.1.12
|
||||
```
|
||||
|
||||
[OpenAI API example →](./examples/openai_api/) · [Gradio demo →](./examples/openai_api/GRADIO.md) · [Client recipes →](./examples/openai_api/CLIENTS.md) · [JavaScript/TypeScript recipes →](./examples/openai_api/JAVASCRIPT.md) · [Kubernetes template →](./examples/openai_api/kubernetes/) · [Workflow recipes →](./examples/openai_api/WORKFLOWS.md) · [Postman collection →](./examples/openai_api/POSTMAN.md) · [OpenAPI spec →](./examples/openai_api/OPENAPI.md) · [Deployment matrix →](./docs/deployment_matrix.md) · [Deployment docs →](./runtime/readme.md) · [Agent integration →](https://modelscope.github.io/FunASR/agent.html)
|
||||
[OpenAI API example →](./examples/openai_api/) · [Gradio demo →](./examples/openai_api/GRADIO.md) · [Client recipes →](./examples/openai_api/CLIENTS.md) · [JavaScript/TypeScript recipes →](./examples/openai_api/JAVASCRIPT.md) · [Kubernetes template →](./examples/openai_api/kubernetes/) · [Workflow recipes →](./examples/openai_api/WORKFLOWS.md) · [Postman collection →](./examples/openai_api/POSTMAN.md) · [OpenAPI spec →](./examples/openai_api/OPENAPI.md) · [Security guide →](./examples/openai_api/SECURITY.md) · [Deployment matrix →](./docs/deployment_matrix.md) · [Deployment docs →](./runtime/readme.md) · [Agent integration →](https://modelscope.github.io/FunASR/agent.html)
|
||||
|
||||
---
|
||||
|
||||
|
||||
+1
-1
@@ -132,7 +132,7 @@ funasr-server --device cuda
|
||||
docker pull registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-online-cpu-0.1.12
|
||||
```
|
||||
|
||||
[OpenAI API example →](./examples/openai_api/) · [Client recipes →](./examples/openai_api/CLIENTS.md) · [Workflow recipes →](./examples/openai_api/WORKFLOWS.md) · [Postman collection →](./examples/openai_api/POSTMAN.md) · [OpenAPI spec →](./examples/openai_api/OPENAPI.md) · [Deployment matrix →](./docs/deployment_matrix.md) · [デプロイドキュメント →](./runtime/readme.md) · [Agent連携 →](https://modelscope.github.io/FunASR/agent.html)
|
||||
[OpenAI API example →](./examples/openai_api/) · [Client recipes →](./examples/openai_api/CLIENTS.md) · [Workflow recipes →](./examples/openai_api/WORKFLOWS.md) · [Postman collection →](./examples/openai_api/POSTMAN.md) · [OpenAPI spec →](./examples/openai_api/OPENAPI.md) · [Security guide →](./examples/openai_api/SECURITY.md) · [Deployment matrix →](./docs/deployment_matrix.md) · [デプロイドキュメント →](./runtime/readme.md) · [Agent連携 →](https://modelscope.github.io/FunASR/agent.html)
|
||||
|
||||
---
|
||||
|
||||
|
||||
+1
-1
@@ -132,7 +132,7 @@ funasr-server --device cuda
|
||||
docker pull registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-online-cpu-0.1.12
|
||||
```
|
||||
|
||||
[OpenAI API example →](./examples/openai_api/) · [Client recipes →](./examples/openai_api/CLIENTS.md) · [Workflow recipes →](./examples/openai_api/WORKFLOWS.md) · [Postman collection →](./examples/openai_api/POSTMAN.md) · [OpenAPI spec →](./examples/openai_api/OPENAPI.md) · [Deployment matrix →](./docs/deployment_matrix.md) · [배포 문서 →](./runtime/readme.md) · [Agent 연동 →](https://modelscope.github.io/FunASR/agent.html)
|
||||
[OpenAI API example →](./examples/openai_api/) · [Client recipes →](./examples/openai_api/CLIENTS.md) · [Workflow recipes →](./examples/openai_api/WORKFLOWS.md) · [Postman collection →](./examples/openai_api/POSTMAN.md) · [OpenAPI spec →](./examples/openai_api/OPENAPI.md) · [Security guide →](./examples/openai_api/SECURITY.md) · [Deployment matrix →](./docs/deployment_matrix.md) · [배포 문서 →](./runtime/readme.md) · [Agent 연동 →](https://modelscope.github.io/FunASR/agent.html)
|
||||
|
||||
---
|
||||
|
||||
|
||||
+1
-1
@@ -197,7 +197,7 @@ curl http://localhost:8000/v1/audio/transcriptions \
|
||||
docker pull registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-online-cpu-0.1.12
|
||||
```
|
||||
|
||||
[OpenAI API 示例 →](./examples/openai_api/README_zh.md) · [Gradio Demo →](./examples/openai_api/GRADIO_zh.md) · [客户端配方 →](./examples/openai_api/CLIENTS.md) · [JavaScript/TypeScript 配方 →](./examples/openai_api/JAVASCRIPT_zh.md) · [Kubernetes 模板 →](./examples/openai_api/kubernetes/README_zh.md) · [工作流配方 →](./examples/openai_api/WORKFLOWS_zh.md) · [Postman 集合 →](./examples/openai_api/POSTMAN_zh.md) · [OpenAPI 规范 →](./examples/openai_api/OPENAPI_zh.md) · [部署选型 →](./docs/deployment_matrix_zh.md) · [部署文档 →](./runtime/readme_cn.md) · [Agent 集成 →](https://modelscope.github.io/FunASR/agent.html)
|
||||
[OpenAI API 示例 →](./examples/openai_api/README_zh.md) · [Gradio Demo →](./examples/openai_api/GRADIO_zh.md) · [客户端配方 →](./examples/openai_api/CLIENTS.md) · [JavaScript/TypeScript 配方 →](./examples/openai_api/JAVASCRIPT_zh.md) · [Kubernetes 模板 →](./examples/openai_api/kubernetes/README_zh.md) · [工作流配方 →](./examples/openai_api/WORKFLOWS_zh.md) · [Postman 集合 →](./examples/openai_api/POSTMAN_zh.md) · [OpenAPI 规范 →](./examples/openai_api/OPENAPI_zh.md) · [安全指南 →](./examples/openai_api/SECURITY_zh.md) · [部署选型 →](./docs/deployment_matrix_zh.md) · [部署文档 →](./runtime/readme_cn.md) · [Agent 集成 →](https://modelscope.github.io/FunASR/agent.html)
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -25,7 +25,7 @@ Use the Python API from the README. It is the shortest route for validating inst
|
||||
|
||||
### I want a local replacement for cloud transcription
|
||||
|
||||
Use the OpenAI-compatible API. It exposes `/v1/audio/transcriptions`, `/v1/models`, `/health`, and Swagger docs. Start with `sensevoice`, run `examples/openai_api/smoke_test.sh` or `examples/openai_api/smoke_test.py`, then connect existing SDK or HTTP clients using [client recipes](../examples/openai_api/CLIENTS.md) and [JavaScript/TypeScript recipes](../examples/openai_api/JAVASCRIPT.md). For browser upload or microphone demos, use the [Gradio browser demo](../examples/openai_api/GRADIO.md). For Dify, n8n, HTTP nodes, or webhook workers, follow the [workflow recipes](../examples/openai_api/WORKFLOWS.md). For API gateways, developer portals, and schema-driven imports, use the [OpenAPI spec](../examples/openai_api/OPENAPI.md).
|
||||
Use the OpenAI-compatible API. It exposes `/v1/audio/transcriptions`, `/v1/models`, `/health`, and Swagger docs. Start with `sensevoice`, run `examples/openai_api/smoke_test.sh` or `examples/openai_api/smoke_test.py`, then connect existing SDK or HTTP clients using [client recipes](../examples/openai_api/CLIENTS.md) and [JavaScript/TypeScript recipes](../examples/openai_api/JAVASCRIPT.md). For browser upload or microphone demos, use the [Gradio browser demo](../examples/openai_api/GRADIO.md). For Dify, n8n, HTTP nodes, or webhook workers, follow the [workflow recipes](../examples/openai_api/WORKFLOWS.md). For API gateways, developer portals, and schema-driven imports, use the [OpenAPI spec](../examples/openai_api/OPENAPI.md). Before sharing the service, review the [security and gateway guide](../examples/openai_api/SECURITY.md).
|
||||
|
||||
### I want a repeatable container demo
|
||||
|
||||
@@ -57,7 +57,7 @@ Use the vLLM path for Fun-ASR-Nano. Benchmark with your own audio distribution a
|
||||
- Record FunASR version, model version, device, CUDA/PyTorch version, Docker image tag, and command line.
|
||||
- Run a short public smoke sample and at least one realistic private sample.
|
||||
- Log audio duration, model, device, latency, response format, and error type for every request.
|
||||
- Add upload-size limits, authentication, TLS, and rate limits before exposing an API outside a trusted network.
|
||||
- Add upload-size limits, authentication, TLS, and rate limits before exposing an API outside a trusted network; use the [security and gateway guide](../examples/openai_api/SECURITY.md) to plan the boundary.
|
||||
- For streaming, test silence, noise, overlapping speakers, long sessions, reconnects, and slow clients.
|
||||
- For benchmark claims, include input duration, hardware, batch size, model, runtime path, and whether model download/warmup time is excluded.
|
||||
|
||||
|
||||
@@ -25,7 +25,7 @@
|
||||
|
||||
### 我想替代云端转写服务
|
||||
|
||||
使用 OpenAI 兼容 API。它提供 `/v1/audio/transcriptions`、`/v1/models`、`/health` 和 Swagger docs。先用 `sensevoice` 跑通 `examples/openai_api/smoke_test.sh` 或 `examples/openai_api/smoke_test.py`，再根据 [客户端配方](../examples/openai_api/CLIENTS.md) 和 [JavaScript/TypeScript 配方](../examples/openai_api/JAVASCRIPT_zh.md) 接入 SDK 或 HTTP 客户端。浏览器上传或麦克风 demo 可使用 [Gradio 浏览器 Demo](../examples/openai_api/GRADIO_zh.md)。Dify、n8n、HTTP 节点或 webhook worker 可参考 [工作流配方](../examples/openai_api/WORKFLOWS_zh.md)。API 网关、开发者门户或按 schema 导入时可使用 [OpenAPI 规范](../examples/openai_api/OPENAPI_zh.md)。
|
||||
使用 OpenAI 兼容 API。它提供 `/v1/audio/transcriptions`、`/v1/models`、`/health` 和 Swagger docs。先用 `sensevoice` 跑通 `examples/openai_api/smoke_test.sh` 或 `examples/openai_api/smoke_test.py`，再根据 [客户端配方](../examples/openai_api/CLIENTS.md) 和 [JavaScript/TypeScript 配方](../examples/openai_api/JAVASCRIPT_zh.md) 接入 SDK 或 HTTP 客户端。浏览器上传或麦克风 demo 可使用 [Gradio 浏览器 Demo](../examples/openai_api/GRADIO_zh.md)。Dify、n8n、HTTP 节点或 webhook worker 可参考 [工作流配方](../examples/openai_api/WORKFLOWS_zh.md)。API 网关、开发者门户或按 schema 导入时可使用 [OpenAPI 规范](../examples/openai_api/OPENAPI_zh.md)。跨团队共享服务前，请先阅读 [安全与网关指南](../examples/openai_api/SECURITY_zh.md)。
|
||||
|
||||
### 我想要可复现的容器 demo
|
||||
|
||||
@@ -57,7 +57,7 @@ Fun-ASR-Nano 走 vLLM 路径。请用自己的音频分布做 benchmark，并关
|
||||
- 记录 FunASR 版本、模型版本、设备、CUDA/PyTorch 版本、Docker 镜像 tag 和启动命令。
|
||||
- 跑一个公开短音频 smoke sample，再跑至少一个真实私有样本。
|
||||
- 每次请求记录音频时长、模型、设备、延迟、响应格式和错误类型。
|
||||
- API 暴露到可信网络外之前，增加上传大小限制、鉴权、TLS 和限流。
|
||||
- API 暴露到可信网络外之前，增加上传大小限制、鉴权、TLS 和限流；可用 [安全与网关指南](../examples/openai_api/SECURITY_zh.md) 规划边界。
|
||||
- 流式场景需要测试静音、噪声、多人重叠、长连接、重连和慢客户端。
|
||||
- 发布 benchmark 结论时，说明输入时长、硬件、batch size、模型、运行路径，以及是否排除模型下载和 warmup 时间。
|
||||
|
||||
|
||||
@@ -41,7 +41,7 @@ Recommended next steps:
|
||||
- For browser upload or microphone demos, start from the [Gradio browser demo](../examples/openai_api/GRADIO.md).
|
||||
- For Node.js or Next.js services, start from the [JavaScript/TypeScript recipes](../examples/openai_api/JAVASCRIPT.md).
|
||||
- For cluster services, start from the [Kubernetes deployment template](../examples/openai_api/kubernetes/).
|
||||
- Add authentication and network controls at your service boundary.
|
||||
- Add authentication and network controls at your service boundary; start from the [security and gateway guide](../examples/openai_api/SECURITY.md).
|
||||
- Record model name, device, driver, and audio duration in bug reports and benchmarks.
|
||||
|
||||
### Agent speech input
|
||||
|
||||
@@ -41,7 +41,7 @@ curl http://localhost:8000/v1/audio/transcriptions \
|
||||
- 浏览器上传或麦克风 demo 可从 [Gradio 浏览器 Demo](../examples/openai_api/GRADIO_zh.md) 开始。
|
||||
- Node.js 或 Next.js 服务可从 [JavaScript/TypeScript 配方](../examples/openai_api/JAVASCRIPT_zh.md) 开始。
|
||||
- 集群内服务可从 [Kubernetes 部署模板](../examples/openai_api/kubernetes/README_zh.md) 开始。
|
||||
- 在服务边界增加鉴权、限流和网络访问控制。
|
||||
- 在服务边界增加鉴权、限流和网络访问控制；可从 [安全与网关指南](../examples/openai_api/SECURITY_zh.md) 开始。
|
||||
- 记录模型、设备、驱动、音频时长和处理耗时，便于复现问题和 benchmark。
|
||||
|
||||
### Agent 语音输入
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Client Recipes for the FunASR OpenAI-Compatible API
|
||||
|
||||
Use this page when `funasr-server` is already running and you want to connect an existing application, agent tool, or workflow engine to local speech recognition. For JavaScript, TypeScript, and Next.js examples, see the [JavaScript/TypeScript recipes](JAVASCRIPT.md) or [Chinese JavaScript/TypeScript recipes](JAVASCRIPT_zh.md). For Dify, n8n, HTTP nodes, and webhook workers, see the [workflow recipes](WORKFLOWS.md) or [Chinese workflow recipes](WORKFLOWS_zh.md). For browser upload or microphone demos, use the [Gradio browser demo](GRADIO.md). For no-code API smoke tests, import the [Postman collection](POSTMAN.md). For schema-driven imports or client generation, use the [OpenAPI spec](OPENAPI.md).
|
||||
Use this page when `funasr-server` is already running and you want to connect an existing application, agent tool, or workflow engine to local speech recognition. For JavaScript, TypeScript, and Next.js examples, see the [JavaScript/TypeScript recipes](JAVASCRIPT.md) or [Chinese JavaScript/TypeScript recipes](JAVASCRIPT_zh.md). For Dify, n8n, HTTP nodes, and webhook workers, see the [workflow recipes](WORKFLOWS.md) or [Chinese workflow recipes](WORKFLOWS_zh.md). For browser upload or microphone demos, use the [Gradio browser demo](GRADIO.md). For no-code API smoke tests, import the [Postman collection](POSTMAN.md). For schema-driven imports or client generation, use the [OpenAPI spec](OPENAPI.md). Before sharing the service, review the [security and gateway guide](SECURITY.md).
|
||||
|
||||
## Preflight
|
||||
|
||||
@@ -146,7 +146,7 @@ When the workflow system cannot send files directly, upload audio to an internal
|
||||
|
||||
## Production checklist
|
||||
|
||||
- Put TLS, authentication, rate limits, and upload-size limits in front of the service before exposing it outside a trusted network.
|
||||
- Put TLS, authentication, rate limits, and upload-size limits in front of the service before exposing it outside a trusted network; use the [security and gateway guide](SECURITY.md) as the rollout checklist.
|
||||
- Preload the default model at startup and use `/health` for readiness checks.
|
||||
- Set client timeouts based on maximum audio duration; long recordings need longer HTTP timeouts.
|
||||
- Log audio duration, model alias, device, latency, response format, and error type for every request.
|
||||
|
||||
@@ -57,6 +57,6 @@ See the [model selection guide](../../docs/model_selection.md) for a deeper comp
|
||||
## 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.
|
||||
- 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.
|
||||
|
||||
@@ -57,6 +57,6 @@ OpenAI SDK 的 base URL 需要包含 `/v1`；这个 Gradio demo 使用的是不
|
||||
## 生产注意事项
|
||||
|
||||
- Gradio app 适合作为 demo 或内部操作界面，不建议直接作为公网生产前端。
|
||||
- 任何音频上传 UI 对可信网络外开放前，都需要先增加鉴权、TLS、上传大小限制和限流。
|
||||
- 任何音频上传 UI 对可信网络外开放前，都需要先增加鉴权、TLS、上传大小限制和限流；见 [安全与网关指南](SECURITY_zh.md)。
|
||||
- 浏览器上传应尽量靠近你的后端服务，不要把私有音频发送到未鉴权的公网端点。
|
||||
- 排查问题时记录模型 alias、音频时长、延迟、响应格式和错误文本。
|
||||
|
||||
@@ -13,7 +13,7 @@ python server.py --model sensevoice --device cuda --port 8000
|
||||
|
||||
Server starts in ~20s (model loading). Health check: `GET /health`
|
||||
|
||||
Need copy-paste integration snippets for Python SDK, JavaScript/TypeScript, HTTP clients, agent tools, a browser demo, Postman, OpenAPI imports, Kubernetes deployment, or Dify/n8n-style workflows? See [Client recipes](CLIENTS.md), [JavaScript/TypeScript recipes](JAVASCRIPT.md), [Gradio browser demo](GRADIO.md), [workflow recipes](WORKFLOWS.md), the [Chinese workflow recipes](WORKFLOWS_zh.md), the [Postman collection](POSTMAN.md), the [OpenAPI spec](OPENAPI.md), and the [Kubernetes deployment template](kubernetes/README.md).
|
||||
Need copy-paste integration snippets for Python SDK, JavaScript/TypeScript, HTTP clients, agent tools, a browser demo, Postman, OpenAPI imports, Kubernetes deployment, or Dify/n8n-style workflows? See [Client recipes](CLIENTS.md), [JavaScript/TypeScript recipes](JAVASCRIPT.md), [Gradio browser demo](GRADIO.md), [workflow recipes](WORKFLOWS.md), the [Chinese workflow recipes](WORKFLOWS_zh.md), the [Postman collection](POSTMAN.md), the [OpenAPI spec](OPENAPI.md), the [security and gateway guide](SECURITY.md), and the [Kubernetes deployment template](kubernetes/README.md).
|
||||
|
||||
### End-to-end smoke test
|
||||
|
||||
@@ -162,6 +162,8 @@ python smoke_test.py --base-url http://localhost:8000
|
||||
|
||||
## Kubernetes Deployment
|
||||
|
||||
Before sharing the service across a team or exposing it through a gateway, review the [security and gateway guide](SECURITY.md) for TLS, authentication, upload limits, rate limits, and logging.
|
||||
|
||||
For an internal cluster service with persistent model cache, health probes, and a private `ClusterIP`, start from the [Kubernetes deployment template](kubernetes/README.md). Build and push the example image, apply the manifests, then verify through `kubectl port-forward` with `python smoke_test.py --base-url http://localhost:8000`.
|
||||
|
||||
Keep the default CPU mode until you have built a CUDA-capable image and configured GPU scheduling for your cluster.
|
||||
|
||||
@@ -13,7 +13,7 @@ python server.py --model sensevoice --device cuda --port 8000
|
||||
|
||||
服务通常会在模型加载后启动。健康检查：`GET /health`。
|
||||
|
||||
需要直接复制的接入示例？可以继续查看 [客户端配方](CLIENTS.md)、[JavaScript/TypeScript 配方](JAVASCRIPT_zh.md)、[Gradio 浏览器 Demo](GRADIO_zh.md)、[工作流配方](WORKFLOWS_zh.md)、[Postman 集合](POSTMAN_zh.md)、[OpenAPI 规范](OPENAPI_zh.md) 和 [Kubernetes 部署模板](kubernetes/README_zh.md)。
|
||||
需要直接复制的接入示例？可以继续查看 [客户端配方](CLIENTS.md)、[JavaScript/TypeScript 配方](JAVASCRIPT_zh.md)、[Gradio 浏览器 Demo](GRADIO_zh.md)、[工作流配方](WORKFLOWS_zh.md)、[Postman 集合](POSTMAN_zh.md)、[OpenAPI 规范](OPENAPI_zh.md)、[安全与网关指南](SECURITY_zh.md) 和 [Kubernetes 部署模板](kubernetes/README_zh.md)。
|
||||
|
||||
### 端到端 smoke test
|
||||
|
||||
@@ -150,6 +150,8 @@ python smoke_test.py --base-url http://localhost:8000
|
||||
|
||||
## Kubernetes 部署
|
||||
|
||||
在跨团队共享服务或通过网关暴露服务前，请先阅读 [安全与网关指南](SECURITY_zh.md)，补齐 TLS、鉴权、上传限制、限流和日志策略。
|
||||
|
||||
如果需要在集群内部提供带持久化模型缓存、健康检查和私有 `ClusterIP` 的语音 API，可以从 [Kubernetes 部署模板](kubernetes/README_zh.md) 开始。先构建并推送示例镜像，应用 manifests，再通过 `kubectl port-forward` 和 `python smoke_test.py --base-url http://localhost:8000` 验证。
|
||||
|
||||
在没有 CUDA-capable 镜像和 GPU 调度配置前，请保持默认 CPU 模式。
|
||||
|
||||
@@ -0,0 +1,132 @@
|
||||
# Security and Gateway Guide for the FunASR OpenAI-Compatible API
|
||||
|
||||
Use this guide before sharing the example OpenAI-compatible API with a team, workflow engine, browser UI, or service outside your laptop. The example server is intentionally small: it focuses on `/v1/audio/transcriptions` compatibility and does not enforce authentication by itself.
|
||||
|
||||
## Recommended topology
|
||||
|
||||
```text
|
||||
OpenAI SDK / Dify / n8n / browser UI
|
||||
|
|
||||
v
|
||||
TLS + auth + upload limits + logs
|
||||
(reverse proxy, API gateway, ingress, or service mesh)
|
||||
|
|
||||
v
|
||||
FunASR OpenAI-compatible API
|
||||
(private host, VM, container, or Kubernetes ClusterIP)
|
||||
```
|
||||
|
||||
Keep FunASR on a private network whenever possible. Put public TLS, identity, request limits, and audit logging at the boundary that your team already operates.
|
||||
|
||||
## Minimum controls before sharing
|
||||
|
||||
| Control | Why it matters | Where to enforce it |
|
||||
|---|---|---|
|
||||
| TLS | Audio often contains private data. | Reverse proxy, API gateway, or ingress. |
|
||||
| Authentication | The local example accepts any SDK `api_key` placeholder. | Gateway bearer token, basic auth, OAuth/OIDC, or internal SSO. |
|
||||
| Upload-size limits | Prevent accidental multi-GB uploads and memory pressure. | Gateway request-body limit and app-level checks. |
|
||||
| Timeouts | Long recordings need longer HTTP timeouts, but stuck clients should not hang forever. | Client, proxy, and server process manager. |
|
||||
| Rate limits | Protect GPU/CPU capacity from bursts. | Gateway, ingress controller, or queue worker. |
|
||||
| Private `/health` | Health output is useful operational data, not a public product endpoint. | Network allowlist or private monitoring path. |
|
||||
| Logs and retention | Request metadata is useful; raw audio may be sensitive. | Central logging policy and storage lifecycle. |
|
||||
|
||||
## NGINX reverse proxy sketch
|
||||
|
||||
This is a starting point, not a complete production policy. Add your own certificates, identity provider, and secret management.
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 443 ssl http2;
|
||||
server_name funasr.example.com;
|
||||
|
||||
client_max_body_size 200m;
|
||||
proxy_read_timeout 600s;
|
||||
proxy_send_timeout 600s;
|
||||
|
||||
location / {
|
||||
# Add auth_request, basic auth, mTLS, or an API gateway policy here.
|
||||
proxy_pass http://127.0.0.1:8000;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header Authorization $http_authorization;
|
||||
}
|
||||
|
||||
location = /health {
|
||||
allow 10.0.0.0/8;
|
||||
deny all;
|
||||
proxy_pass http://127.0.0.1:8000/health;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Caddy reverse proxy sketch
|
||||
|
||||
Generate the password hash with `caddy hash-password` and store the real credential outside the repository.
|
||||
|
||||
```caddyfile
|
||||
funasr.example.com {
|
||||
request_body {
|
||||
max_size 200MB
|
||||
}
|
||||
|
||||
basicauth /* {
|
||||
team_user <hashed-password>
|
||||
}
|
||||
|
||||
reverse_proxy 127.0.0.1:8000 {
|
||||
transport http {
|
||||
read_timeout 600s
|
||||
write_timeout 600s
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
For production teams, prefer your standard SSO/OIDC gateway over shared passwords.
|
||||
|
||||
## Kubernetes notes
|
||||
|
||||
The Kubernetes template keeps the service private with `ClusterIP`. Before adding an ingress or load balancer:
|
||||
|
||||
- Add an ingress controller or API gateway that enforces TLS, authentication, upload-size limits, and rate limits.
|
||||
- Keep model cache volumes private to the namespace or node pool that owns the service.
|
||||
- Use `NetworkPolicy` to restrict which namespaces can call the service.
|
||||
- Use `kubectl port-forward` plus `smoke_test.py` for first validation before exposing a route.
|
||||
- If you add GPUs, pin scheduling rules and record the image tag, CUDA runtime, and model alias in deployment notes.
|
||||
|
||||
## Client configuration
|
||||
|
||||
OpenAI SDKs usually require an API key string even when FunASR does not check it locally. After you add a gateway, use the gateway-issued token as the SDK key:
|
||||
|
||||
```python
|
||||
import os
|
||||
from openai import OpenAI
|
||||
|
||||
client = OpenAI(
|
||||
base_url="https://funasr.example.com/v1",
|
||||
api_key=os.environ["FUNASR_API_KEY"],
|
||||
)
|
||||
```
|
||||
|
||||
For internal HTTP workers, read tokens from environment variables or your secret manager. Do not commit tokens to workflow definitions, notebooks, screenshots, or Postman exports.
|
||||
|
||||
## Data handling checklist
|
||||
|
||||
- Decide whether raw audio can be stored, for how long, and who can access it.
|
||||
- Log request IDs, duration, model alias, status, latency, and error class; avoid logging raw transcript text unless your policy allows it.
|
||||
- If transcripts may contain personal data, document retention and deletion rules before onboarding users.
|
||||
- Keep public samples separate from private customer or employee audio when writing benchmark reports.
|
||||
- Redact headers, tokens, file names, and speaker names before opening GitHub issues.
|
||||
|
||||
## Rollout checklist
|
||||
|
||||
1. Start locally and run `bash smoke_test.sh` or `python smoke_test.py`.
|
||||
2. Add the gateway and verify `/health`, `/v1/models`, and `/v1/audio/transcriptions` through the gateway URL.
|
||||
3. Test a small file, a large allowed file, and a file above the upload limit.
|
||||
4. Confirm unauthorized requests fail before reaching FunASR.
|
||||
5. Confirm timeout behavior for long audio and slow clients.
|
||||
6. Record the model alias, device, image tag, FunASR version, and gateway policy.
|
||||
|
||||
Related guides: [OpenAI API README](README.md), [client recipes](CLIENTS.md), [workflow recipes](WORKFLOWS.md), [Gradio browser demo](GRADIO.md), [Kubernetes template](kubernetes/README.md), and the repository [security policy](../../SECURITY.md).
|
||||
@@ -0,0 +1,132 @@
|
||||
# FunASR OpenAI 兼容 API 安全与网关指南
|
||||
|
||||
当你准备把示例 OpenAI 兼容 API 提供给团队、工作流引擎、浏览器 UI 或笔记本之外的服务时，请先看这份指南。示例服务刻意保持轻量，主要关注 `/v1/audio/transcriptions` 兼容性，本身不内置鉴权策略。
|
||||
|
||||
## 推荐拓扑
|
||||
|
||||
```text
|
||||
OpenAI SDK / Dify / n8n / 浏览器 UI
|
||||
|
|
||||
v
|
||||
TLS + 鉴权 + 上传限制 + 日志
|
||||
(反向代理、API 网关、Ingress 或 Service Mesh)
|
||||
|
|
||||
v
|
||||
FunASR OpenAI 兼容 API
|
||||
(私有主机、虚机、容器或 Kubernetes ClusterIP)
|
||||
```
|
||||
|
||||
只要条件允许，就让 FunASR 保持在私有网络中。公网 TLS、身份认证、请求限制和审计日志应放在团队已有的边界组件上。
|
||||
|
||||
## 对团队开放前的最低控制项
|
||||
|
||||
| 控制项 | 为什么重要 | 建议在哪里实现 |
|
||||
|---|---|---|
|
||||
| TLS | 音频通常包含隐私信息。 | 反向代理、API 网关或 Ingress。 |
|
||||
| 鉴权 | 本地示例会接受任意 SDK `api_key` 占位符。 | 网关 Bearer token、Basic auth、OAuth/OIDC 或内部 SSO。 |
|
||||
| 上传大小限制 | 避免误传超大文件导致内存和磁盘压力。 | 网关 request body limit 和应用侧检查。 |
|
||||
| 超时 | 长音频需要更长 HTTP timeout，但异常客户端不能无限挂住。 | 客户端、代理和服务进程管理器。 |
|
||||
| 限流 | 防止突发请求打满 GPU/CPU。 | 网关、Ingress controller 或队列 worker。 |
|
||||
| 私有 `/health` | 健康信息是运维数据，不应作为公开产品端点。 | 网络 allowlist 或私有监控路径。 |
|
||||
| 日志与留存 | 请求元数据有价值，但原始音频可能敏感。 | 集中日志策略和存储生命周期。 |
|
||||
|
||||
## NGINX 反向代理示例
|
||||
|
||||
下面只是起点，不是完整生产策略。证书、身份系统和密钥管理需要按你的环境补齐。
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 443 ssl http2;
|
||||
server_name funasr.example.com;
|
||||
|
||||
client_max_body_size 200m;
|
||||
proxy_read_timeout 600s;
|
||||
proxy_send_timeout 600s;
|
||||
|
||||
location / {
|
||||
# 在这里增加 auth_request、Basic auth、mTLS 或 API 网关策略。
|
||||
proxy_pass http://127.0.0.1:8000;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header Authorization $http_authorization;
|
||||
}
|
||||
|
||||
location = /health {
|
||||
allow 10.0.0.0/8;
|
||||
deny all;
|
||||
proxy_pass http://127.0.0.1:8000/health;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Caddy 反向代理示例
|
||||
|
||||
使用 `caddy hash-password` 生成密码 hash，真实凭据不要写入仓库。
|
||||
|
||||
```caddyfile
|
||||
funasr.example.com {
|
||||
request_body {
|
||||
max_size 200MB
|
||||
}
|
||||
|
||||
basicauth /* {
|
||||
team_user <hashed-password>
|
||||
}
|
||||
|
||||
reverse_proxy 127.0.0.1:8000 {
|
||||
transport http {
|
||||
read_timeout 600s
|
||||
write_timeout 600s
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
生产团队优先使用已有 SSO/OIDC 网关，而不是共享密码。
|
||||
|
||||
## Kubernetes 注意事项
|
||||
|
||||
Kubernetes 模板默认使用私有 `ClusterIP`。在增加 Ingress 或 LoadBalancer 前，请先完成：
|
||||
|
||||
- 使用 Ingress controller 或 API 网关强制 TLS、鉴权、上传大小限制和限流。
|
||||
- 模型缓存卷只暴露给拥有该服务的 namespace 或 node pool。
|
||||
- 使用 `NetworkPolicy` 限制可调用服务的 namespace。
|
||||
- 第一次验证先用 `kubectl port-forward` 加 `smoke_test.py`，再开放路由。
|
||||
- 如果增加 GPU，固定调度规则，并在部署说明中记录镜像 tag、CUDA runtime 和模型 alias。
|
||||
|
||||
## 客户端配置
|
||||
|
||||
OpenAI SDK 通常要求传入 API key 字符串，即使本地 FunASR 不检查它。加上网关后，请使用网关发放的 token 作为 SDK key：
|
||||
|
||||
```python
|
||||
import os
|
||||
from openai import OpenAI
|
||||
|
||||
client = OpenAI(
|
||||
base_url="https://funasr.example.com/v1",
|
||||
api_key=os.environ["FUNASR_API_KEY"],
|
||||
)
|
||||
```
|
||||
|
||||
内部 HTTP worker 应从环境变量或密钥系统读取 token。不要把 token 提交到工作流定义、notebook、截图或 Postman 导出文件里。
|
||||
|
||||
## 数据处理清单
|
||||
|
||||
- 先决定原始音频是否允许存储、保存多久、谁可以访问。
|
||||
- 日志建议记录 request ID、音频时长、模型 alias、状态、延迟和错误类型；除非策略允许，不要记录原始转写文本。
|
||||
- 如果转写文本可能包含个人信息，请在接入用户前写清留存和删除规则。
|
||||
- 写 benchmark 报告时，把公开样例和客户/员工私有音频分开。
|
||||
- 打开 GitHub issue 前，先脱敏 header、token、文件名和说话人姓名。
|
||||
|
||||
## 上线检查清单
|
||||
|
||||
1. 先在本地启动，并运行 `bash smoke_test.sh` 或 `python smoke_test.py`。
|
||||
2. 增加网关后，通过网关 URL 验证 `/health`、`/v1/models` 和 `/v1/audio/transcriptions`。
|
||||
3. 分别测试小文件、允许范围内的大文件，以及超过上传限制的文件。
|
||||
4. 确认未授权请求会在到达 FunASR 前失败。
|
||||
5. 确认长音频和慢客户端的 timeout 行为。
|
||||
6. 记录模型 alias、设备、镜像 tag、FunASR 版本和网关策略。
|
||||
|
||||
相关文档：[OpenAI API README](README_zh.md)、[客户端配方](CLIENTS.md)、[工作流配方](WORKFLOWS_zh.md)、[Gradio 浏览器 Demo](GRADIO_zh.md)、[Kubernetes 模板](kubernetes/README_zh.md) 和仓库 [安全策略](../../SECURITY.md)。
|
||||
@@ -147,7 +147,7 @@ This worker is also the right place to add audio conversion, file-size checks, r
|
||||
|
||||
## Production guardrails
|
||||
|
||||
- Put authentication, TLS, upload-size limits, and rate limits in front of FunASR before sharing it across teams.
|
||||
- Put authentication, TLS, upload-size limits, and rate limits in front of FunASR before sharing it across teams; use the [security and gateway guide](SECURITY.md) for proxy and gateway patterns.
|
||||
- Use `/health` for workflow readiness checks and `/v1/models` to validate model aliases.
|
||||
- Log request id, audio duration, model alias, response format, device, latency, and error type.
|
||||
- Set workflow timeouts according to maximum audio duration; split very long recordings before sending them through low-code tools.
|
||||
|
||||
@@ -147,7 +147,7 @@ def transcribe_bytes(filename: str, payload: bytes, content_type: str = "audio/w
|
||||
|
||||
## 生产环境护栏
|
||||
|
||||
- 在跨团队共享 FunASR 服务前，先加好鉴权、TLS、上传大小限制和限流。
|
||||
- 在跨团队共享 FunASR 服务前，先加好鉴权、TLS、上传大小限制和限流；代理和网关模式见 [安全与网关指南](SECURITY_zh.md)。
|
||||
- 使用 `/health` 做工作流 readiness check，使用 `/v1/models` 校验模型别名。
|
||||
- 记录 request id、音频时长、模型别名、响应格式、设备、延迟和错误类型。
|
||||
- 按最长音频时长设置工作流超时；超长录音建议先切分，再交给低代码工具处理。
|
||||
|
||||
Reference in New Issue
Block a user