Improve deployment documentation and fix configuration inconsistencies

[drunksu]

Acknowledgments

First, thank you for this excellent work! UGround achieves impressive accuracy on visual grounding tasks and the model quality is outstanding. The approach of fine-tuning Qwen2-VL for coordinate prediction works really well in practice.

Issues encountered during deployment

However, I encountered several configuration and documentation issues that made deployment challenging, especially for users with limited experience:

1. Missing dependencies

• pyairports not listed in requirements but required by vLLM 0.6.1
• flash-attn installation instructions incomplete, causing performance warnings

2. Parameter inconsistencies

• uground_qwen2vl.py lacks --max-model-len parameter needed for GPU memory management
• vLLM server mode and local inference mode have different parameter sets
• No default GPU memory utilization settings for different GPU configurations

3. Documentation gaps

• No mention of GPU memory requirements (model needs ~16GB for 7B version)
• Missing troubleshooting guide for common CUDA/memory errors
• Path handling edge cases not documented (e.g., relative vs absolute paths)

Suggested improvements

1. Add complete requirements.txt with version constraints
2. Standardize parameters across inference scripts
3. Include deployment examples for different hardware setups (single/multi-GPU)
4. Add validation and better error messages for common issues

This would make the excellent UGround model much more accessible to the community!

[boyugou]

Hi, apologies for the very late reply!

Thank you so much for the detailed suggestions and for the kind words about UGround, even though UGround is now becoming a very early work in GUI grounding and has fallen behind more recent models in terms of performance.

A large part of the issue is that third-party training and inference libraries like vLLM and LLaMA Factory tend to have significant breaking changes (and even bugs) across versions, and users deploying on different GPU setups (e.g., A100 vs. H100 can behave differently under certain library versions) can end up running into varied issues. Unfortunately, I haven't had the bandwidth to keep the documentation up to date with all of these moving parts.

If time permits, I may try to revisit the documentation and polish it against a more recent version of vLLM.

Thanks again for the thoughtful feedback!