跳转至

HTTP 服务（FastAPI）

omnirt serve 是当前推荐的服务化入口。它在同一个进程里组合了：

  • FastAPI 路由
  • OmniEngine
  • Prometheus /metrics
  • 可选 Redis-backed JobStore
  • 可选 OTLP trace exporter
  • 可选远程 gRPC worker 调度

启动方式

python -m pip install -e '.[runtime,server]'

omnirt serve \
  --host 0.0.0.0 \
  --port 8000 \
  --backend auto

常用参数

参数 说明
--backend 请求未显式指定时的默认后端
--max-concurrency 本地 engine 最大并发
--pipeline-cache-size 常驻 executor / pipeline 缓存数量
--batch-window-ms batching 等待窗口
--max-batch-size batching 上限
--device-map / --devices 作为默认请求配置透传给所有入口
--model-tier 只启用指定维护层级；可重复，例如 --model-tier core --model-tier adjacent
--api-key-file API key 文件
--model-aliases OpenAI 兼容模型别名表
--redis-url 启用 RedisJobStore
--otlp-endpoint 启用 OTLP/HTTP trace 导出
--remote-worker 注册远程 gRPC worker

路由总览

Method Path 用途
GET /healthz 存活探针
GET /readyz 就绪探针，附带 job_store_backend、remote_worker_count 和 allowed_model_tiers
GET /metrics Prometheus 文本指标
GET /v1/models OpenAI 兼容模型清单，返回 tier / status，支持 ?tier=core
POST /v1/generate 同步或异步生成
GET /v1/jobs/{id} job 状态与结果
DELETE /v1/jobs/{id} 取消 job
GET /v1/jobs/{id}/events SSE 事件流
GET /v1/jobs/{id}/trace job trace 视图
WS /v1/jobs/{id}/stream WebSocket 事件流与 cancel
POST /v1/images/generations OpenAI 兼容文生图
POST /v1/images/edits OpenAI 兼容图像编辑
POST /v1/videos/generations OpenAI 兼容视频生成
WS /v1/realtime OpenAI Realtime 最小子集
WS / FlashTalk-compatible 根路径别名，适配 ws://127.0.0.1:8765
GET /v1/audio2video/models 实时 audio2video 模型可用性
WS /v1/audio2video/{model} FlashTalk-compatible audio2video 实时入口
WS /v1/avatar/{model} 兼容旧版 OpenTalking 的别名
WS /v1/avatar/realtime OmniRT 原生 Realtime Avatar 入口

POST /v1/jobs 当前保留，不作为提交入口。

同步生成

curl -sS http://127.0.0.1:8000/v1/generate \
  -H 'content-type: application/json' \
  -d '{
    "task": "text2image",
    "model": "sdxl-base-1.0",
    "inputs": {"prompt": "a lighthouse at dusk"},
    "config": {"preset": "fast"}
  }'

异步生成

curl -sS http://127.0.0.1:8000/v1/generate \
  -H 'content-type: application/json' \
  -d '{
    "task": "text2video",
    "model": "wan2.2-t2v-14b",
    "inputs": {"prompt": "a paper ship drifting on moonlit water"},
    "config": {"num_frames": 81},
    "async_run": true
  }'

之后使用：

curl -sS http://127.0.0.1:8000/v1/jobs/<job_id>
curl -sS -N http://127.0.0.1:8000/v1/jobs/<job_id>/events

OpenAI 兼容

from openai import OpenAI

client = OpenAI(base_url="http://127.0.0.1:8000/v1", api_key="sk-local")
resp = client.images.generate(model="sdxl-base-1.0", prompt="a lighthouse at dusk")
print(resp.data[0].url)

模型发现可以按维护层级过滤：

curl -sS 'http://127.0.0.1:8000/v1/models?tier=core'
curl -sS 'http://127.0.0.1:8000/v1/models?tier=adjacent'

如果服务启动时指定了 --model-tier core，/v1/models 只会返回 core 模型，生成接口也会拒绝其它层级的请求。生产环境可以用 --model-tier core --model-tier adjacent 暴露数字人主线和相邻素材能力，把 experimental 模型保留在开发/兼容入口。

注意：

  • audio/speech 目前仍返回 501
  • images/videos/edits 也会继承 serve 启动时设置的默认 device_map / devices

远程 worker

omnirt worker --host 0.0.0.0 --port 50061 --worker-id sdxl-a --backend cuda

omnirt serve \
  --remote-worker 'sdxl-a=127.0.0.1:50061@sdxl-base-1.0,sdxl-refiner-1.0'

完整部署建议见 分布式服务。

可观测性

omnirt serve \
  --redis-url redis://127.0.0.1:6379/0 \
  --otlp-endpoint http://127.0.0.1:4318/v1/traces

验收建议：

  • curl /readyz
  • curl /metrics
  • 跑一个异步 job，确认 /v1/jobs/{id}/trace 可读

相关