| # VectorLLM HF 0407 |
|
|
| 这是当前可直接分发使用的 Hugging Face 版本导出目录模板，已经包含： |
|
|
| - C-RADIO 视觉塔实现与权重映射逻辑 |
| - VectorLLM 自定义 `AutoModel` / `AutoProcessor` |
| - 本地可加载的 processor / image processor / modeling 代码 |
| - `bfloat16` 推理配置 |
|
|
| 当前推荐在 GPU 上使用，推荐环境： |
|
|
| ```bash |
| /home/zhangtao/env/xtuner/bin/python |
| ``` |
|
|
| ## 目录说明 |
|
|
| - `model.safetensors`: 合并后的主模型权重 |
| - `config.json`: 主配置 |
| - `generation_config.json`: 生成配置 |
| - `preprocessor_config.json`: 图像预处理配置 |
| - `test_hf.py`: 单图推理与可视化示例脚本 |
| - `gradio_bbox_demo.py`: 整图画框、后端裁剪和全图回映射的 Gradio 脚本 |
| - `conversion_report.json`: 与 xtuner 对齐验证结果 |
| - `radio_bundle/`: 打包后的 C-RADIO 相关实现 |
|
|
| ## 设计目标 |
|
|
| - 可通过 `AutoModel` 和 `AutoProcessor` 拉起 |
| - 不依赖外部 Hugging Face cache 中的自定义代码 |
| - 不要求 `trust_remote_code=True` |
| - 适用于“单个物体已裁剪好”的输入图像，不做二次裁剪 |
|
|
| ## 快速开始 |
|
|
| ### 1. 命令行推理 |
|
|
| 推荐直接使用目录内置的 [test_hf.py](/home/zhangtao/hf_model/vectorllm_hf_0407/test_hf.py)： |
|
|
| ```bash |
| /home/zhangtao/env/xtuner/bin/python \ |
| /home/zhangtao/hf_model/vectorllm_hf_0407/test_hf.py \ |
| /home/zhangtao/hf_model/vectorllm_hf_0407 \ |
| /path/to/your_image.png \ |
| --save-dir /tmp/vectorllm_hf_demo |
| ``` |
|
|
| 输出： |
|
|
| - `overlay.png`: 叠加 polygon 的可视化结果 |
| - `report.json`: 文本输出、网格坐标、回映射后的 polygon |
|
|
| ### 2. Python 方式加载 |
|
|
| 必须先把模型目录的父目录加入 `sys.path`，再导入包本身完成本地注册： |
|
|
| ```python |
| import sys |
| from pathlib import Path |
| |
| import torch |
| from PIL import Image |
| from transformers import AutoModel, AutoProcessor, GenerationConfig |
| |
| model_path = Path("/home/zhangtao/hf_model/vectorllm_hf_0407") |
| sys.path.insert(0, str(model_path.parent)) |
| import vectorllm_hf_0407 # noqa: F401 |
| |
| from vectorllm_hf_0407.test_hf import DEFAULT_RAW_PROMPT, decode_generated_text, get_stop_criteria |
| |
| model = AutoModel.from_pretrained( |
| model_path, |
| trust_remote_code=False, |
| torch_dtype=torch.bfloat16, |
| ).cuda().eval() |
| processor = AutoProcessor.from_pretrained(model_path, trust_remote_code=False) |
| tokenizer = processor.tokenizer |
| |
| image = Image.open("/path/to/your_image.png").convert("RGB") |
| model_inputs = processor(text=[DEFAULT_RAW_PROMPT], images=[image], return_tensors="pt") |
| model_inputs = { |
| key: value.to(model.device) if torch.is_tensor(value) else value |
| for key, value in model_inputs.items() |
| } |
| |
| stop_criteria = get_stop_criteria(tokenizer, ["<|im_end|>", "<|endoftext|>"]) |
| output = model.generate( |
| **model_inputs, |
| generation_config=GenerationConfig( |
| max_new_tokens=640, |
| do_sample=False, |
| eos_token_id=tokenizer.eos_token_id, |
| pad_token_id=tokenizer.pad_token_id or tokenizer.eos_token_id, |
| temperature=0.0, |
| top_k=1, |
| ), |
| bos_token_id=tokenizer.bos_token_id, |
| stopping_criteria=stop_criteria, |
| output_hidden_states=False, |
| return_dict_in_generate=True, |
| do_sample=False, |
| temperature=0.0, |
| top_k=1, |
| ) |
| |
| text = decode_generated_text(output, model_inputs, tokenizer) |
| print(text) |
| ``` |
|
|
| ### 3. Gradio 交互 |
|
|
| 若输入是整图，希望在图上手动画 bbox，再由后端扩框裁剪后送入模型，可直接启动： |
|
|
| ```bash |
| /home/zhangtao/env/xtuner/bin/python \ |
| /home/zhangtao/hf_model/vectorllm_hf_0407/gradio_bbox_demo.py \ |
| --model-path /home/zhangtao/hf_model/vectorllm_hf_0407 \ |
| --server-name 0.0.0.0 \ |
| --server-port 7861 |
| ``` |
|
|
| 功能说明： |
|
|
| - 前端直接在整图上拖拽一个或多个 bbox |
| - 后端按 `1.0-1.3` 可调扩展比例裁剪 |
| - 裁剪图送入 VectorLLM HF 模型推理 |
| - 结果会回映射到整图，并展示全图 overlay、裁剪预览和结构化 JSON |
|
|
| 使用步骤： |
|
|
| 1. 打开页面后先上传整图。 |
| 2. 在左侧画布上拖拽 bbox，可连续画多个框。 |
| 3. `Prompt Target` 选择 `Building` 或 `Object`。 |
| 4. `BBox Expand Ratio` 控制后端扩框比例。`1.0` 表示仅按原框裁剪，`1.15` 或 `1.2` 通常更稳，`1.3` 适合给目标留更多上下文。 |
| 5. 点击 `Run` 执行推理，点击 `Clear` 清空当前图像和框。 |
|
|
| 页面输出说明： |
|
|
| - `Full-Image Overlay`: 全图可视化结果，同时叠加原始 bbox、扩框后的 bbox 和回映射后的 polygon |
| - `Expanded Crop Preview`: 每个 bbox 对应的裁剪图及其局部 polygon，可用来快速检查裁剪是否合理 |
| - `Model Text Output`: 模型原始输出文本，便于排查 `<xN><yN>` 序列 |
| - `Structured Result`: 结构化 JSON，包含原框、扩框、裁剪尺寸、网格坐标和全图坐标 polygon |
|
|
| 补充说明： |
|
|
| - 当前脚本默认监听 `7861` 端口，可通过 `--server-port` 调整 |
| - 服务启动后若需停止，终端里直接 `Ctrl+C` 即可 |
| - 首次启动会加载大模型，耗时会明显长于后续推理 |
|
|
| ## 输入要求 |
|
|
| - 输入应为单个目标的裁剪图 |
| - 当前默认 prompt 针对建筑轮廓提取 |
| - 模型输出为 `<xN><yN>` 格式的离散 polygon 点序列 |
|
|
| ## 结果说明 |
|
|
| - 网格坐标范围默认是 `0~127` |
| - [test_hf.py](/home/zhangtao/hf_model/vectorllm_hf_0407/test_hf.py) 会自动把离散点映射回原图坐标并可视化 |
| - [gradio_bbox_demo.py](/home/zhangtao/hf_model/vectorllm_hf_0407/gradio_bbox_demo.py) 会把裁剪区域内的离散点恢复到全图坐标后再叠加显示 |
| - 当前 GPU 实测下，回载后的 HF 输出与 xtuner 已基本对齐，可能存在极轻微的离散点差异 |
|
|
| ## 备注 |
|
|
| - 若从别的工作目录调用，不要省略 `sys.path.insert(...)` 和 `import vectorllm_hf_0407` |
| - 若只想快速跑 demo，优先使用 [test_hf.py](/home/zhangtao/hf_model/vectorllm_hf_0407/test_hf.py) |
|
|
