[bugfix] Harden OpenAI serving after post-merge review (#1782)

Author: SolitaryThinker

docs/design/inference_schema_parity_inventory.yaml

@@ -626,7 +626,6 @@ surfaces:
       max_sequence_length: request.sampling.max_sequence_length
       boundary_ratio: request.sampling.boundary_ratio
       extra_params: request.extensions
-      output_path: request.output.output_path
     compatibility_only:
       seconds:
         target: request.sampling.num_frames

docs/design/server_contracts/openai.md

@@ -73,8 +73,9 @@ spellings.
 Reference objects support URL or local-path strings through `image_url`,
 `video_url`, and `audio_url`. `file_id` references are schema-compatible but
 return HTTP 400 because FastVideo does not provide an OpenAI Files store.
-Multipart `input_reference` uploads are saved under the configured output
-directory.
+Image URLs, data URLs, local paths, and multipart `input_reference` uploads are
+materialized and decoded under the configured output directory during
+admission. Invalid media returns HTTP 400 before a job is created.
 
 ## Jobs and synchronous responses
 
@@ -85,7 +86,12 @@ timings, and peak-memory metadata when the pipeline reports them.
 
 `POST /v1/videos/sync` returns `video/mp4` bytes. It includes
 `X-Request-Id`, `X-Model`, `X-Inference-Time-S`, `X-Stage-Durations`, and
-`X-Peak-Memory-MB` headers.
+`X-Peak-Memory-MB` headers. Its temporary MP4 is removed after the response is
+streamed. Asynchronous artifacts remain available until their job is deleted.
+
+Output paths are controlled by the server. Clients cannot choose filesystem
+destinations; every video is written beneath `server.output_dir` with a unique
+request id.
 
 FastVideo's synchronous CUDA execution cannot be interrupted after launch.
 Deleting an in-progress resource removes it from the API immediately; the
@@ -98,8 +104,8 @@ checkpoint path is used. Requests that name another model fail with HTTP 400.
 
 LoRAs are configured under
 `generator.pipeline.components.{lora_path,lora_nickname,lora_strength}`. The
-startup adapter appears in `/v1/models`, and requests can use either its model
-nickname or a vLLM-Omni selector:
+startup adapter is the only model advertised by a LoRA server, and requests can
+select it by its model nickname or with a selector:
 
 ```json
 {
@@ -156,3 +162,9 @@ Errors use the OpenAI envelope:
 Parse, model-selection, startup-LoRA, and unsupported-parameter failures are
 HTTP 400; missing resources are HTTP 404; generation failures are stored on
 asynchronous jobs and returned as HTTP 500 when that job is retrieved.
+Unknown top-level fields are rejected. `extra_params` accepts only the explicit
+request-batch passthrough fields supported by the typed request adapter.
+
+`GET /health` also verifies that the generation engine is open and all local
+multiprocess workers are alive. It returns HTTP 503 when the worker pool is no
+longer usable.

examples/serving/openai_fasth3_lora.yaml

@@ -34,7 +34,7 @@ server:
   host: 0.0.0.0
   port: 8000
   output_dir: outputs/openai_fasth3_lora
-  served_model_name: minimax-h3
+  served_model_name: fasth3-dense-datafree
 
 default_request:
   negative_prompt: ""
@@ -49,4 +49,3 @@ default_request:
     seed: 1000
   output:
     return_frames: false
-

fastvideo/entrypoints/cli/bench_serving.py

@@ -626,7 +626,9 @@ async def benchmark(args: argparse.Namespace) -> None:
         ) as resp:
             if resp.status == 200:
                 info = await resp.json()
-                if "model_path" in info and info["model_path"]:
+                if info.get("served_model_name"):
+                    args.model = info["served_model_name"]
+                elif info.get("model_path"):
                     args.model = info["model_path"]
                     logger.info("Updated model name from server: %s", args.model)
     except Exception as e:

fastvideo/entrypoints/openai/api_server.py

@@ -3,6 +3,7 @@
 
 from contextlib import asynccontextmanager
 from collections.abc import AsyncIterator
+import os
 
 import uvicorn
 from fastapi import FastAPI, HTTPException, Request
@@ -151,6 +152,11 @@ async def openai_validation_error(_request: Request, exc: RequestValidationError
 
     @app.get("/health")
     async def health():
+        from fastvideo.entrypoints.openai.state import get_serving_engine
+
+        engine = get_serving_engine()
+        if not engine.healthy:
+            raise HTTPException(status_code=503, detail=engine.unhealthy_reason or "generation engine is unhealthy")
         return {"status": "ok"}
 
     return app
@@ -187,6 +193,7 @@ def run_server(
     served_model_name: str | None = None,
 ):
     """Create the app and run it with uvicorn"""
+    os.environ.setdefault("FASTVIDEO_STAGE_LOGGING", "1")
     if default_request is not None:
         _validate_default_request_against_preset(default_request, fastvideo_args.model_path)
 

fastvideo/entrypoints/openai/common_api.py

@@ -29,8 +29,6 @@ async def available_models():
     """Show available models"""
     args = get_server_args()
     cards = [ModelCard(id=get_served_model_name(), root=args.model_path)]
-    if args.lora_path and args.lora_nickname != get_served_model_name():
-        cards.append(ModelCard(id=args.lora_nickname, root=args.model_path))
     return {"object": "list", "data": [card.model_dump() for card in cards]}
 
 
@@ -40,8 +38,6 @@ async def retrieve_model(model: str):
     args = get_server_args()
     served_model_name = get_served_model_name()
     available = {served_model_name}
-    if args.lora_path:
-        available.add(args.lora_nickname)
     if model not in available:
         return ORJSONResponse(
             status_code=404,

fastvideo/entrypoints/openai/protocol.py

@@ -6,7 +6,7 @@
 from enum import Enum
 from typing import Annotated, Any, Literal
 
-from pydantic import BaseModel, ConfigDict, Field, StringConstraints
+from pydantic import BaseModel, ConfigDict, Field, StringConstraints, field_validator
 
 
 class ImageResponseData(BaseModel):
@@ -82,7 +82,7 @@ class FileImageReference(BaseModel):
 
 class UrlImageReference(BaseModel):
     model_config = ConfigDict(extra="forbid")
-    image_url: str
+    image_url: str = Field(min_length=1)
 
 
 ImageReference = UrlImageReference | FileImageReference
@@ -95,15 +95,15 @@ class FileVideoReference(BaseModel):
 
 class UrlVideoReference(BaseModel):
     model_config = ConfigDict(extra="forbid")
-    video_url: str
+    video_url: str = Field(min_length=1)
 
 
 VideoReference = UrlVideoReference | FileVideoReference
 
 
 class UrlAudioReference(BaseModel):
     model_config = ConfigDict(extra="forbid")
-    audio_url: str
+    audio_url: str = Field(min_length=1)
 
 
 AudioReference = UrlAudioReference
@@ -117,11 +117,11 @@ class VideoGenerationRequest(BaseModel):
     predate vLLM-Omni's typed reference objects.
     """
 
-    model_config = ConfigDict(extra="allow")
+    model_config = ConfigDict(extra="forbid")
 
-    prompt: str
+    prompt: str = Field(min_length=1)
     model: str | None = None
-    seconds: int | SecondStr | None = None
+    seconds: Annotated[int, Field(ge=1, le=_INT64_MAX)] | SecondStr | None = None
     size: SizeStr | None = None
     image_reference: ImageReference | list[ImageReference] | None = None
     video_reference: VideoReference | list[VideoReference] | None = None
@@ -145,7 +145,7 @@ class VideoGenerationRequest(BaseModel):
     # SGLang spelling retained as an alias-like input field.
     n: int | None = Field(default=None, ge=1, le=10)
     start_time_seconds: float | None = Field(default=None, ge=0.0)
-    quality: str | None = None
+    quality: Literal["auto", "default", "standard", "hd"] | None = None
     negative_prompt: str | None = None
     num_inference_steps: int | None = Field(default=None, ge=1, le=200)
     guidance_scale: float | None = Field(default=None, ge=0.0, le=20.0)
@@ -166,7 +166,13 @@ class VideoGenerationRequest(BaseModel):
 
     lora: dict[str, Any] | None = None
     extra_params: dict[str, Any] | None = None
-    output_path: str | None = None
+
+    @field_validator("prompt")
+    @classmethod
+    def validate_prompt(cls, value: str) -> str:
+        if not value.strip():
+            raise ValueError("prompt must not be empty")
+        return value
 
     def resolve_video_params(self) -> VideoParams:
         """Resolve top-level, nested, and ``size`` dimensions like vLLM-Omni."""