Skip to main content

FAQs

System overview​

Q1: What is Vision Agents?​

Vision Agents is an intelligent video analytics system that uses AI to automatically recognize faces, count people in/out, check shift-opening meetings, and monitor camera health. The system consists of a Stream Gateway (ingests video), a DeepStream Engine (runs AI on GPU), and a Platform Backend (management and reporting) — see Vision Agents overview.

Q2: What camera types does the system support?​

The system supports IP cameras that can provide a stream via RTSP or through a vendor's API (e.g. fcam.vn). Cameras need to support H.264 or H.265 codecs, a minimum resolution of 1080p (2MP), and a stable Internet connection.

Q3: How many cameras can the system handle at once?​

Each Stream Gateway instance handles up to 32 concurrent camera streams. The system scales by adding Gateway instances — e.g. 4 gateways support 128 cameras, 8 gateways support 256 cameras. When a gateway reaches > 28/32 streams (87.5% capacity), you need to add another instance — see Camera diagnostics — Gateway overloaded.

Q4: Where is video data stored, and for how long?​

Video is H.265-encoded and uploaded to S3-compatible storage (FCloud). Retention time depends on each organization's configuration, typically 7–90 days. Metadata (events, alerts) is stored in MongoDB and can be kept longer.

Camera connectivity​

Q5: A camera won't connect to the system — what should I do?​

Check in this order:

  1. Is the camera online (check via the vendor's app)?
  2. Is the stream vendor's API key still valid?
  3. Has the camera been assigned to the correct gateway?
  4. Is the corresponding gateway instance running (check its heartbeat)?
  5. Network bandwidth at the camera's location (needs ≥ 4 Mbps for 1080p).

See the full procedure at Camera diagnostics — Camera disconnected.

Q6: The camera reports "STREAM_UNAVAILABLE" — how do I fix it?​

This error occurs when the Stream Gateway can't get a stream URL from the vendor:

  1. Check the stream vendor's API key in the camera's configuration.
  2. Confirm the camera is still online on the vendor's system.
  3. Try restarting the stream.
  4. If it still fails, recheck the camera's identity info against the vendor's system.

Q7: Why does a camera suddenly disconnect and then reconnect on its own?​

This is normal behavior from the stream refresh mechanism — not an incident. See the full explanation at Camera diagnostics.

Stream quality​

Q8: Video stutters/lags when viewed on the Portal — why?​

Common causes:

  • Camera network bandwidth: check the upload speed at the camera's location.
  • Gateway overloaded: check its capacity (if near 32/32 streams).
  • Browser: try refreshing or a different browser.
  • Incompatible codec: H.265 video may need an additional codec on some browsers.

Q9: The system reports "STREAM_FREEZE" — is the camera broken?​

Not necessarily. A freeze means the video repeats the same frame for an extended period, usually due to a temporary network drop, hung camera firmware, or insufficient bandwidth. Try restarting the stream first; if it still fails, check the camera physically — see Camera diagnostics.

Q10: How do I know a camera is working well?​

Each camera has a health status shown on the Portal (normal / needs checking with an error description) — see Managing cameras — Monitoring status.

AI accuracy​

Q11: Why does the system miscount people in/out?​

The most common cause is no ROI configured or an ROI that's too wide. Without an ROI, the system picks up people walking past in the hallway, leading to overcounting. Also check whether the gate-type label (in/out) is correct, whether the camera captures faces clearly (angle, lighting), and note that people wearing a full face covering may not be recognized. See People counting in/out to configure it correctly.

Q12: The shift-opening meeting happened, but the system reports MISSING?​

Check in this order:

  1. Is the camera recording the meeting room (check the stream status)?
  2. Does the ROI cover the meeting table area?
  3. Is the meeting room lighting sufficient (the VLM needs to see people clearly)?
  4. Is the schedule in the task configuration set to the correct shift hours?
  5. Is the video chunk being uploaded to storage (check Data Summary — see Configuring Task AI)?

Q13: Can the 0.5 cosine similarity threshold be adjusted?​

Currently, face matching uses the default threshold built into the people-counting service. The 0.5 threshold is optimized for most real-world environments — too high (> 0.6) misses many people (false negatives), too low (< 0.4) miscounts other people (false positives). If you need it adjusted for a special case (low-quality camera, poor lighting), contact the development team.

Q14: What does DeepStream's sampling interval mean? Does it affect accuracy?​

DeepStream processes only a portion of frames instead of every consecutive frame, which significantly improves performance (processing time drops from tens of minutes to ~6 minutes per site). Accuracy loss is negligible since people move slowly — they're still captured in the frames that are processed.

Reports and data​

Q15: What time zone are reports shown in?​

All reports are shown in Vietnam time (Asia/Ho_Chi_Minh, UTC+7). Data is stored in the database as UTC and converted automatically when generating reports.

Q16: How do I export a report to Excel/CSV?​

Use the Export CSV button on each report type — see Generating and exporting reports. The CSV file opens directly in Excel.

Q17: Report data is empty even though the camera is running?​

Check in this order:

  1. Has the camera been assigned the corresponding task (people counting / meeting check)?
  2. Does the task have the correct schedule?
  3. Is the task in an active state?
  4. Is the Stream Gateway recording video for that camera (check Data Summary)?
  5. Is the video being processed by AI?

Q18: Why do numbers for the same day change when I query again?​

The system processes video in batches — video is uploaded to storage and only analyzed afterward. If you view a report the same day, some of that day's video may not be fully processed yet, so the numbers may be incomplete. Numbers stabilize once all of that day's video has been analyzed (usually the next day). This is normal behavior, not a bug — see Generating and exporting reports — Usage notes.

API integration​

Q19: What authentication method does the API use?​

The system uses Keycloak for authentication. Every API request needs a Bearer token in the header, obtained from the corresponding authentication endpoint for the deployment environment.

Q20: Does the API have a request rate limit?​

The API currently doesn't enforce hard rate limiting, but the report endpoint can be slow for wide date ranges (> 30 days). We recommend no more than 100 requests/minute to the report endpoint.

Q21: Are webhooks supported?​

The Stream Gateway sends internal webhooks to the Platform Backend when there's a new video segment, a stream quality error, or a camera status change. Webhooks to external systems aren't directly supported yet; integration is possible via subscribing to events from MongoDB Change Streams or RabbitMQ.

Scaling and performance​

Q22: When do I need to add a new Gateway instance?​

When any of the following happens: the current gateway reaches > 28/32 streams (87.5% capacity), CPU usage stays above 80%, or you need to add cameras but have no slots left. Estimate formula: number of gateways = total cameras ÷ camera capacity per gateway, rounded up (with capacity headroom).

Q23: Does the system support High Availability (HA)?​

Currently each camera is fixed to one Gateway — if that Gateway goes down, the camera goes offline until the Gateway recovers or is reassigned. To improve availability: use a MongoDB Replica Set (auto failover), Redis Sentinel/Cluster, monitoring + alerting on Gateway heartbeats, and keep a standby Gateway ready.

Q24: Which GPU is suitable for production?​

ScaleRecommended GPUStreams
Small (< 16 cameras)RTX 3060 12GB8-16
Medium (16-32 cameras)RTX 3090 24GB16-32
Large (32-64 cameras)A100 40GB32-64

Q25: Do Redis and MongoDB need to be clustered for production?​

  • < 50 cameras: standalone Redis + standalone MongoDB is enough.
  • 50-200 cameras: Redis Sentinel + MongoDB Replica Set (3 nodes).
  • > 200 cameras: Redis Cluster + MongoDB Sharded Cluster.

Prioritize a MongoDB Replica Set first, since it holds critical data (cameras, events, alerts).

Couldn't find your answer?​

Contact FPT AI technical support — support@fpt.ai / Hotline 1900 638 399.

On this page