Skip to content

FAQ

FAQ

General Questions

What is the Woven City AI Vision Engine?
The Woven City AI Vision Engine is a multimodal large-scale foundation AI designed for video analysis. It interprets visual scenes by identifying objects, understanding behaviors and situations, and providing contextual insights through text-based responses.

System Requirements & Setup

What are the system requirements?
See the Introduction page for detailed system requirements including GPU specifications, memory requirements, and supported operating systems.
How do I activate my license?
Follow the License Activation guide for step-by-step instructions on activating your software license using CodeMeter.
Can I use the SDK without a GUI on Ubuntu Server?
Yes. The License Activation page includes instructions for headless mode using XQuartz for X11 forwarding from a Mac client.
The SDK fails with "LICENSE_NOT_AVAILABLE" (Error 35) — what does it mean?
CodeMeter could not find a valid license for the SDK's tier. The message looks like: 
CodeMeter License: <FirmCode>:<ProductCode> : The Expiration Time is overrun
- the en-/decryption cannot be operated, Error 35. (LICENSE_NOT_AVAILABLE)
Common causes:
  • The license has expired — check the Expiration Date with cmu --list-content.
  • No license for your tier is activated in any connected CmContainer.
  • The CodeMeter service is not running (sudo systemctl status codemeter).
To resolve, ensure the CodeMeter service is running and that cmu --list-content shows a valid, non-expired license for your tier (see License Activation). For license renewal, please contact your sales representative.

API Usage

What are the minimum image size requirements?
Images should not be smaller than 448x448 pixels for optimal performance.
What is the difference between image_chat, rgb_image_chat, and rgb_images_chat?
  • image_chat: Uses an image file path
  • rgb_image_chat: Uses a single in-memory RGB NumPy array (HWC format)
  • rgb_images_chat: Uses a list of in-memory RGB NumPy arrays
How do I maintain conversation history across multiple turns?
Set return_history=True and pass the returned chat_history to subsequent API calls: 
response1, chat_history = client.video_chat(
    prompt=prompt1,
    video_path=video_path,
    return_history=True
)

response2, chat_history = client.video_chat(
    prompt=prompt2,
    video_path=video_path,
    chat_history=chat_history,
    return_history=True
)
What do the API methods return?
By default, only the generated text is returned. With return_history or return_sampling_info enabled, the function returns a tuple: (text, history, sampling_info). Unpack based on which options you enabled.
Can I use the same chat history across different videos or images?
Technically yes, but it's not recommended. Chat history is designed for multi-turn conversations about the same visual content. Using it across different content may lead to confusing or incorrect responses.

Sampling Methods

What is the difference between min_num_frames and max_num_frames?
These parameters control the frame count range when using "duration", "middle", or "random" sampling methods:
  • min_num_frames: Minimum frames to sample (default: 64)
  • max_num_frames: Maximum frames to sample (default: 512)
The actual number sampled depends on video duration and the selected method.
How can I see which frames were sampled?
Set return_sampling_info=True to receive detailed sampling metadata including frame indices and timestamps.
How does the SDK handle very short videos?
For very short videos with "duration" sampling, frames are calculated from the video's FPS and adjusted to the nearest lower multiple of 8. For example, a 1-second video at 30 FPS will sample 24 frames.

Generation Configuration

How do I control the randomness of generated text?
Use the generation_config parameter with temperature: 
generation_config = {"temperature": 0.7}
response = client.video_chat(
    prompt=prompt,
    video_path=video_path,
    generation_config=generation_config
)
Lower temperature (e.g., 0.2) produces more deterministic output, while higher values (e.g., 0.8) increase creativity.
What other generation parameters can I configure?
See the Generation Configuration page for details on top_k, top_p, max_new_tokens, do_sample, and other parameters.

Performance & Optimization

How can I improve inference speed?
- Reduce max_num_frames to process fewer frames
- Use appropriate sampling methods for your use case
- Choose shorter input videos when possible
- Warm up the model with dummy inferences for real-time applications
Does processing time increase with more frames?
Yes, processing time increases with the number of frames. Balance speed and output quality by selecting appropriate sampling strategies and frame limits.
Why is the first inference slower than subsequent ones?
The first inference includes initialization overhead (loading model weights, allocating GPU memory, and optimizing execution). For real-time applications, run a few dummy inferences to warm up the model after loading.
What is the inference speed?
Inference speed varies based on hardware configuration, input resolution, and sampling settings. Please contact your sales representative for detailed performance information.

Application Integration

Should I validate inputs before passing them to the SDK?
Yes, the SDK assumes inputs are already validated. Validate file paths, image arrays, and parameters before API calls to avoid errors.
What is the maximum number of frames for inference?
The maximum number of frames depends on your GPU specifications. We recommend testing with your hardware to find the optimal limit. Note that processing more frames requires more GPU memory and increases inference time.
Why is latency high when integrating with other systems?
Image transfer between services is often the bottleneck. We recommend profiling data transfer times across your services. Consider compressing images or reducing image size to minimize transfer time. Test different compression levels and sizes to find the balance between transfer speed and quality that meets your business requirements.

Deployment & Support

What hardware do I need to run WAVE? New
See the Introduction page for GPU memory, driver, and CUDA version requirements.
Why is my license activation failing? New
Confirm the CodeMeter dongle/container is connected, the license has not expired, and the FC/PC codes match your purchased tier. See License Activation.
Why does installation fail? New
Verify your Python version matches the supported version, dependencies installed without conflicts, and CodeMeter Runtime is installed and running (sudo systemctl status codemeter).
Why is inference not responding? New
Confirm the GPU is not occupied by another process, the model finished loading, and your request has not exceeded the configured timeout.
Why are SDK API calls failing? New
Check that input parameters match the expected format/types described in the API Usage Examples, and review the returned error code.
How should I write prompts for the model? New
See API Usage Examples for recommended prompt structures.
How can I balance performance and speed? New
Adjust generation parameters such as max_new_tokens to balance latency and output quality. See Generation Configuration.
How do I manage memory usage for long videos? New
Split the input into smaller chunks and process sequentially; the SDK does not automatically manage chunking.
Does the SDK include RAG? New
No. RAG is not included; you will need to implement retrieval and a vector database on your side.
Does the SDK include search or other post-processing capabilities? New
No. Search-style post-processing requires your own NLP and vector DB implementation on top of the SDK output.
What's the overall cost of integrating a VLM application? New
Cost depends on GPU tier, number of camera streams, and any additional components (RAG, DB, frontend) you build around the SDK.
Can I run inference on multiple camera streams in parallel on one GPU? New
Not currently supported — a single GPU processes one stream at a time. Multiple simultaneous streams require multiple GPUs or a queuing mechanism.
What trigger methods are available for invoking the VLM? New
Common approaches include periodic polling or event-based triggers (e.g., a lightweight upstream detector signaling when to invoke the VLM). Choice depends on your latency and cost requirements.
How should I evaluate performance if it doesn't meet my expectations? New
Use standard multimodal benchmarks appropriate to your use case, and compare against your accuracy/latency targets. Contact your sales representative for guidance on evaluation methodology.
How will I know about SDK updates? New
Releases are communicated in advance, and customers are notified directly upon release.
What happens if an SDK update breaks my existing integration? New
Review the changelog for interface changes before updating, and test in a staging environment first. Contact support if you encounter breaking changes not documented in the Changelog.
What should I do if an update fails? New
Follow the SDK Installation guide as if performing a fresh install, and contact support with the specific error if it persists.
← Previous: Sampling Methods
Next: Changelog →