Livrare LOT 1 - Didi

ai_platform/modules/video-analysis/INDEX.md

@@ -0,0 +1,100 @@
+# 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