clossers/didi-lot1-ai
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
didi-lot1-ai/ai_platform/modules/video-analysis/INDEX.md

7.6 KiB
Raw Blame History

video-analysis — INDEX

Video analysis service for DIDI. Performs deepfake detection and semantic temporal analysis on video content via uniform / chunked frame extraction plus a vision-language model backend (vLLM). Exposes a small FastAPI surface used by agent-v3 for video media sessions.

  • Stack: Python 3.11+, FastAPI, uvicorn, OpenCV (headless), Pillow, NumPy, httpx/requests, ffmpeg toolchain (via OpenCV), pydantic-settings + YAML
  • URL (Dev): http://10.11.10.12:54600
  • Container: runs on GPU host (network_mode: host in deploy/docker-compose.yml); the service itself is CPU-only — GPU is consumed by the upstream vLLM server
  • Vision backend: external vLLM server (default: BusterX 7B @ port 54500); same endpoint also drives semantic analysis. Optional alternative: Qwen3-VL-30B @ port 14002 for richer semantic narratives. The wider DIDI vision cascade (Qwen Vision local → Gemini Flash → GPT-4o) lives in agent-v3; this service only talks to one vLLM at a time.

Ce face

  • Receives a video file via multipart/form-data upload (no URL/path indirection — file bytes are POSTed)
  • Extracts frames via OpenCV (video_sampling.py) with two strategies:
    • Uniform sampling for fast deepfake check (default 16 frames over the whole video)
    • Temporal chunking for semantic analysis (default 10s chunks × 24 frames per chunk)
  • Encodes frames to JPEG (configurable max_side, jpeg_quality) and ships them to the vLLM server as base64 image payloads
  • Runs vision-language model inference and returns:
    • verdict (REAL / FAKE / UNCERTAIN) plus explanation for the deepfake endpoint
    • per-chunk description array + optional aggregated final_summary (narrative) for the semantic endpoint
  • Persists request artifacts (frames, prompts, responses) to a runs/<request_id>/ directory for reproducibility/debugging
  • Used by didi-backend agent-v3 for video media sessions (techniques + ai_tampered components)

API endpoints

Defined in src/video_analysis/app.py:

Endpoint Method Description
/health GET Liveness probe — {"status":"ok"}
/analyze/video POST Deepfake detection. Form field file (video). Fast path, ~16 frames. Returns verdict, explanation, usage, latency_s, meta.
/analyze/video/semantic POST Semantic temporal analysis. Form fields: file, chunk_duration_s (default 10.0, range 1–60), frames_per_chunk (default 24, range 4–64), enable_aggregation (default true). Returns chunk_results[], optional final_summary, meta.

Auth: none (called over private network / through Kong upstream by agent-v3).

How didi-backend uses it

  • agent-v3 video pipeline calls /analyze/video for fast deepfake screening and (where enabled) /analyze/video/semantic for chunked scene narration
  • Output feeds the ai_tampered component (verdict + explanation) and contributes visual cues to the techniques component
  • Frame metadata (fps, duration_s, sampled, indices, timestamps_s) is surfaced upstream so the agent can correlate detections with timestamps
  • Long inference times (~77s for 60s video, semantic mode) are the reason agent-v3 routes video through the async session path (not the sync pipeline)

Frame extraction logic

  • Deepfake path: uniform interval sampling — interval = total_frames / frames where frames defaults to 16; min effectively 1 frame, capped by video length. Tunable via VIDEO_ANALYSIS_FRAMES.
  • Semantic path: temporal chunking — video is split into chunk_duration_s slices, each slice gets frames_per_chunk uniformly sampled frames; total frames analyzed scales with duration (e.g. 60s @ defaults → 6 chunks × 24 = 144 frames, ~8% of source).
  • Frames are downscaled so the longer side ≤ max_side (default 960 px), encoded JPEG at jpeg_quality (default 85), then base64-embedded into the chat-completions request.
  • All sampled frames + indices + timestamps are returned in meta and persisted under runs/<request_id>/.

Vision cascade

This service does not implement a multi-provider cascade. It is a thin client over a single vLLM endpoint configured at startup:

  • Primary (deepfake): BusterX (Qwen2.5-VL-7B fine-tune, l8cv/BusterX_plusplus) at VIDEO_ANALYSIS_VLLM_BASE_URL — typically http://didiAI-video-vllm-buster:54500 on the GPU host
  • Optional (semantic): Qwen3-VL-30B at http://didiAI-llm-vllm-vision:14002 — swap by editing deploy/.env and rebuilding
  • DIDI-wide cascade (Qwen Vision local → OpenRouter Gemini Flash → GPT-4o) is implemented in agent-v3, NOT here. This service is a leaf node in that chain — agent-v3 calls it as one of several vision options.
  • Service refuses to start if VIDEO_ANALYSIS_VLLM_BASE_URL is not set or the vLLM endpoint is unreachable (see buster_client.py, settings.py).

Configuration

Env vars (prefix VIDEO_ANALYSIS_), loaded from deploy/.env:

Variable Required Description
VIDEO_ANALYSIS_VLLM_BASE_URL yes Upstream vLLM server URL
VIDEO_ANALYSIS_VLLM_MODEL yes Model name passed to vLLM (busterx, qwen3-vl, l8cv/BusterX_plusplus, …)
VIDEO_ANALYSIS_RUNS_DIR yes Where to drop per-request artifacts (default /app/runs in container)
VIDEO_ANALYSIS_EXTERNAL_URL yes External URL embedded in the OpenAPI spec
HF_TOKEN, HF_CACHE_DIR yes (when running bundled vLLM) HuggingFace creds + shared cache for the vLLM container
VIDEO_ANALYSIS_FRAMES no (default 16) Uniform-sampling frame count
VIDEO_ANALYSIS_MAX_SIDE no (default 960) Frame downscale cap
VIDEO_ANALYSIS_JPEG_QUALITY no (default 85) JPEG quality 1–100
VIDEO_ANALYSIS_MAX_TOKENS no (default 750) Model response cap
VIDEO_ANALYSIS_TEMPERATURE no (default 0.000001) Near-deterministic decoding
VIDEO_ANALYSIS_REPETITION_PENALTY no (default 1.05) Repetition penalty
NGINX_CONNECT_TIMEOUT / _SEND_TIMEOUT / _READ_TIMEOUT no nginx upstream timeouts (only api-nginx profile)

Tuning defaults live in deploy/config.yaml; env vars override YAML.

Deployment

  • GPU host required for the vLLM upstream (NVIDIA driver 535+, NVIDIA Container Toolkit, ≥16 GB VRAM). The video-analysis container itself is CPU-only.
  • Compose lives in deploy/:
    • deploy/docker-compose.yml — services + profiles (api, api-nginx)
    • deploy/Dockerfile — Python 3.11 + OpenCV-headless + uv
    • deploy/deploy.sh — wrapper around docker compose (loads env strictly from deploy/.env)
    • deploy/nginx.conf / nginx.conf.template — optional reverse proxy
  • Typical bring-up:
    • cp .env.example deploy/.env && $EDITOR deploy/.env
    • cd deploy && ./deploy.sh --profile api --detach
  • Port allocation: 54600 video-analysis API, 54500 BusterX vLLM (Dev).
  • Restart: cd deploy && docker compose restart video-analysis-api (or docker restart video_analysis).

Related

  • agent-v3 video pipeline — /home/admin365/didi_mono/backend/services/orchestration-layer/agent-v3 is the consumer; orchestrates async video sessions and merges this service's verdict into ai_tampered + techniques results
  • BusterX vLLM (port 54500) — sibling service in the AI platform; the actual GPU-backed model that this service queries (referenced in main CLAUDE.md ports section)
  • Qwen3-VL vision vLLM (port 14002) — alternative semantic backend (didiAI-llm-vllm-vision)
  • AI platform shared assets — ../../README.md, ../../ruff.toml
  • Internal package layout: src/video_analysis/{app.py, buster_client.py, schemas.py, settings.py, video_sampling.py}
  • Sibling docs: README.md, API.md, TESTING.md in this folder