Holo1 3B GGUF

🚀 Holo1-3B GGUF模型

Holo1-3B GGUF模型是基于Transformer架构的多模态模型，可用于视觉文档检索任务。该模型在WebVoyager基准测试中表现出色，在准确性和成本之间取得了良好的平衡。

🚀 快速开始

本模型基于Qwen2.5-VL架构，支持transformers库。以下是一个简单的使用示例，展示了如何加载模型和处理器：

import json
import os
from typing import Any, Literal

from transformers import AutoModelForImageTextToText, AutoProcessor

# 默认：将模型加载到可用设备上
# 建议启用flash_attention_2以实现更好的加速和内存节省
model = AutoModelForImageTextToText.from_pretrained(
    "Hcompany/Holo1-3B",
    torch_dtype="auto",
    # torch_dtype=torch.bfloat16,
    # attn_implementation="flash_attention_2",
    device_map="auto",
)

# 默认处理器
processor = AutoProcessor.from_pretrained("Hcompany/Holo1-3B")
# 模型中每张图像的视觉令牌数量的默认范围是4 - 1280
# 可以根据需要设置min_pixels和max_pixels，例如令牌范围为256 - 1280，以平衡性能和成本
# processor = AutoProcessor.from_pretrained(model_dir, min_pixels=min_pixels, max_pixels=max_pixels)

# 运行推理的辅助函数
def run_inference(messages: list[dict[str, Any]]) -> str:
    # 推理准备
    text = processor.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
    inputs = processor(
        text=[text],
        images=image,
        padding=True,
        return_tensors="pt",
    )
    inputs = inputs.to("cuda")

    generated_ids = model.generate(**inputs, max_new_tokens=128)
    generated_ids_trimmed = [out_ids[len(in_ids) :] for in_ids, out_ids in zip(inputs.input_ids, generated_ids)]
    return processor.batch_decode(generated_ids_trimmed, skip_special_tokens=True, clean_up_tokenization_spaces=False)

✨ 主要特性

• 超低比特量化：引入了针对超低比特模型（1 - 2比特）的精度自适应量化方法，在Llama - 3 - 8B上经过基准测试验证有显著改进。
• 多任务处理能力：可用于AI网络监控，包括函数调用、Nmap扫描、量子就绪检查和网络监控任务。
• 高精度与低成本：在WebVoyager基准测试中，基于Holo1的代理在准确性和成本之间取得了最佳平衡。
• UI定位能力：在多个UI定位基准测试中表现出色，如Screenspot、Screenspot - V2等。

📦 安装指南

文档未提及具体安装步骤，暂无法提供。

💻 使用示例

基础用法

import json
import os
from typing import Any, Literal

from transformers import AutoModelForImageTextToText, AutoProcessor

# default: Load the model on the available device(s)
# We recommend enabling flash_attention_2 for better acceleration and memory saving.
model = AutoModelForImageTextToText.from_pretrained(
    "Hcompany/Holo1-3B",
    torch_dtype="auto",
    # torch_dtype=torch.bfloat16,
    # attn_implementation="flash_attention_2",
    device_map="auto",
)

# default processor
processor = AutoProcessor.from_pretrained("Hcompany/Holo1-3B")
# The default range for the number of visual tokens per image in the model is 4-1280.
# You can set min_pixels and max_pixels according to your needs, such as a token range of 256-1280, to balance performance and cost.
# processor = AutoProcessor.from_pretrained(model_dir, min_pixels=min_pixels, max_pixels=max_pixels)

# Helper function to run inference
def run_inference(messages: list[dict[str, Any]]) -> str:
    # Preparation for inference
    text = processor.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
    inputs = processor(
        text=[text],
        images=image,
        padding=True,
        return_tensors="pt",
    )
    inputs = inputs.to("cuda")

    generated_ids = model.generate(**inputs, max_new_tokens=128)
    generated_ids_trimmed = [out_ids[len(in_ids) :] for in_ids, out_ids in zip(inputs.input_ids, generated_ids)]
    return processor.batch_decode(generated_ids_trimmed, skip_special_tokens=True, clean_up_tokenization_spaces=False)

高级用法

准备图像和指令

from PIL import Image
from transformers.models.qwen2_vl.image_processing_qwen2_vl import smart_resize

# Prepare image and instruction
image_url = "https://huggingface.co/Hcompany/Holo1-3B/resolve/main/calendar_example.jpg" 
image = Image.open(requests.get(image_url, stream=True).raw)

# Resize the image so that predicted absolute coordinates match the size of the image.
image_processor = processor.image_processor
resized_height, resized_width = smart_resize(
    image.height,
    image.width,
    factor=image_processor.patch_size * image_processor.merge_size,
    min_pixels=image_processor.min_pixels,
    max_pixels=image_processor.max_pixels,
)
image = image.resize(size=(resized_width, resized_height), resample=None)  # type: ignore

结构化输出导航

import json
from . import navigation

task = "Book a hotel in Paris on August 3rd for 3 nights"
prompt = navigation.get_navigation_prompt(task, image, step=1)
navigation_str = run_inference(prompt)[0]
navigation = navigation.NavigationStep(**json.loads(navigation_str))
print(navigation)
# Expected NavigationStep(note='', thought='I need to select the check-out date as August 3rd and then proceed to search for hotels.', action=ClickElementAction(action='click_element', element='August 3rd on the calendar', x=777, y=282))

点击定位

from . import localization

instruction = "Select July 14th as the check-out date"
prompt = localization.get_localization_prompt(image, instruction)
coordinates = run_inference(prompt)[0]
print(coordinates)
# Expected Click(352, 348)

结构化输出定位

import json
from . import localization

instruction = "Select July 14th as the check-out date"
prompt = localization.get_localization_prompt_structured_output(image, instruction)
coordinates_structured_str = run_inference(prompt)[0]
coordinates_structured = localization.ClickAction(**json.loads(coordinates_structured_str))
print(coordinates_structured)
# Expected ClickAction(action='click', x=352, y=340)

📚 详细文档

模型生成细节

本模型使用llama.cpp在提交版本71bdbdb5时生成。

超低比特量化（1 - 2比特）

我们最新的量化方法为超低比特模型（1 - 2比特）引入了精度自适应量化，在Llama - 3 - 8B上经过基准测试验证有改进。该方法采用特定层策略，在保持极高内存效率的同时保留准确性。

基准测试环境

所有测试均在Llama - 3 - 8B - Instruct上进行，使用：

• 标准困惑度评估管道
• 2048令牌上下文窗口
• 所有量化方法使用相同的提示集

方法

• 动态精度分配：
  • 前/后25%的层 → IQ4_XS（选定层）
  • 中间50% → IQ2_XXS/IQ3_S（提高效率）
• 关键组件保护：
  • 嵌入/输出层使用Q5_K
  • 与标准1 - 2比特量化相比，误差传播降低38%

量化性能比较（Llama - 3 - 8B）

量化方法	标准困惑度	DynamicGate困惑度	困惑度变化	标准大小	DynamicGate大小	大小变化	标准速度	DynamicGate速度
IQ2_XXS	11.30	9.84	-12.9%	2.5G	2.6G	+0.1G	234s	246s
IQ2_XS	11.72	11.63	-0.8%	2.7G	2.8G	+0.1G	242s	246s
IQ2_S	14.31	9.02	-36.9%	2.7G	2.9G	+0.2G	238s	244s
IQ1_M	27.46	15.41	-43.9%	2.2G	2.5G	+0.3G	206s	212s
IQ1_S	53.07	32.00	-39.7%	2.1G	2.4G	+0.3G	184s	209s

主要改进

• IQ1_M：困惑度大幅降低43.9%（从27.46降至15.41）
• IQ2_S：困惑度降低36.9%，仅增加0.2GB大小
• IQ1_S：尽管是1比特量化，但准确性提高39.7%

权衡

• 所有变体的大小增加适中（0.1 - 0.3GB）
• 推理速度相当（差异<5%）

使用场景

• 将模型装入GPU显存
• 内存受限的部署
• CPU和边缘设备：可以容忍1 - 2比特误差的场景
• 超低比特量化研究

选择合适的模型格式

选择正确的模型格式取决于你的硬件能力和内存限制。

BF16（Brain Float 16） - 若支持BF16加速则使用

• 一种16位浮点格式，专为更快的计算而设计，同时保留良好的精度。
• 提供与FP32相似的动态范围，但内存使用更低。
• 如果你的硬件支持BF16加速（检查设备规格），建议使用。
• 与FP32相比，适用于高性能推理且内存占用减少的场景。

使用场景：

• 你的硬件具有原生BF16支持（如较新的GPU、TPU）
• 你希望在节省内存的同时获得更高的精度
• 你计划将模型重新量化为其他格式

避免场景：

• 你的硬件不支持BF16（可能会回退到FP32并运行较慢）
• 你需要与缺乏BF16优化的旧设备兼容

F16（Float 16） - 比BF16更广泛支持

• 一种16位浮点格式，精度较高，但值的范围比BF16小。
• 适用于大多数支持FP16加速的设备（包括许多GPU和一些CPU）。
• 数值精度略低于BF16，但通常足以进行推理。

使用场景：

• 你的硬件支持FP16但不支持BF16
• 你需要在速度、内存使用和准确性之间取得平衡
• 你在GPU或其他针对FP16计算优化的设备上运行

避免场景：

• 你的设备缺乏原生FP16支持（可能运行比预期慢）
• 你有内存限制

量化模型（Q4_K、Q6_K、Q8等） - 用于CPU和低显存推理

量化可以在尽可能保持准确性的同时减小模型大小和内存使用。

• 低比特模型（Q4_K） → 内存使用最少，但精度可能较低
• 高比特模型（Q6_K、Q8_0） → 准确性更好，但需要更多内存

使用场景：

• 你在CPU上运行推理，需要优化的模型
• 你的设备显存较低，无法加载全精度模型
• 你希望在保持合理准确性的同时减少内存占用

避免场景：

• 你需要最高的准确性（全精度模型更适合）
• 你的硬件有足够的显存用于更高精度的格式（BF16/F16）

极低比特量化（IQ3_XS、IQ3_S、IQ3_M、Q4_K、Q4_0）

这些模型针对极端内存效率进行了优化，适用于低功耗设备或大规模部署，其中内存是关键限制因素。

• IQ3_XS：超低比特量化（3比特），具有极端内存效率。
  • 使用场景：最适合超低内存设备，即使Q4_K也太大的情况。
  • 权衡：与高比特量化相比，准确性较低。
• IQ3_S：小块大小，实现最大内存效率。
  • 使用场景：最适合低内存设备，IQ3_XS过于激进的情况。
• IQ3_M：中等块大小，比IQ3_S准确性更好。
  • 使用场景：适用于低内存设备，IQ3_S限制过多的情况。
• Q4_K：4比特量化，具有逐块优化以提高准确性。
  • 使用场景：最适合低内存设备，Q6_K太大的情况。
• Q4_0：纯4比特量化，针对ARM设备进行了优化。
  • 使用场景：最适合基于ARM的设备或低内存环境。

模型格式选择总结表

模型格式	精度	内存使用	设备要求	最佳使用场景
BF16	最高	高	支持BF16的GPU/CPU	高速推理且内存占用减少
F16	高	高	支持FP16的设备	BF16不可用时的GPU推理
Q4_K	中低	低	CPU或低显存设备	内存受限环境
Q6_K	中等	适中	内存较多的CPU	量化模型中准确性较好
Q8_0	高	适中	有足够显存的CPU或GPU	量化模型中最佳准确性
IQ3_XS	非常低	非常低	超低内存设备	极端内存效率和低准确性
Q4_0	低	低	ARM或低内存设备	llama.cpp可针对ARM设备进行优化

模型测试

如果你发现这些模型有用，请点击“点赞”！帮助测试AI网络监控助手，进行量子就绪安全检查： 免费网络监控

测试方法： 选择一个AI助手类型：

• TurboLLM (GPT - 4o - mini)
• HugLLM (Hugginface开源)
• TestLLM (仅支持CPU的实验性模型)

测试内容

正在探索小型开源模型在AI网络监控中的极限，具体包括：

• 针对实时网络服务的函数调用
• 模型可以多小同时仍能处理：
  • 自动Nmap扫描
  • 量子就绪检查
  • 网络监控任务

TestLLM - 当前实验性模型（llama.cpp在2个CPU线程上）

• 零配置设置
• 30秒加载时间（推理慢，但无API成本）
• 寻求帮助！ 如果你对边缘设备AI感兴趣，让我们合作！

其他助手

• TurboLLM - 使用gpt - 4o - mini进行：
  • 创建自定义cmd处理器以在免费网络监控代理上运行.net代码
  • 实时网络诊断和监控
  • 安全审计
  • 渗透测试（Nmap/Metasploit）
• HugLLM - 最新的开源模型：
  • 在Hugging Face推理API上运行

示例命令

1. "Give me info on my websites SSL certificate"
2. "Check if my server is using quantum safe encyption for communication"
3. "Run a comprehensive security audit on my server"
4. '"Create a cmd processor to .. (what ever you want)" 注意，你需要安装免费网络监控代理才能运行.net代码。这是一个非常灵活和强大的功能，请谨慎使用！

🔧 技术细节

本模型是一个基于Qwen2.5-VL架构的多模态模型，用于视觉文档检索。它在多个基准测试中表现出色，通过超低比特量化等技术在准确性和成本之间取得了良好的平衡。模型的训练数据包括开放访问、合成和自生成的数据。

📄 许可证

本模型的许可证信息请参考：https://huggingface.co/Hcompany/Holo1-3B/blob/main/LICENSE

引用

@misc{andreux2025surferhmeetsholo1costefficient,
      title={Surfer-H Meets Holo1: Cost-Efficient Web Agent Powered by Open Weights}, 
      author={Mathieu Andreux and Breno Baldas Skuk and Hamza Benchekroun and Emi

注意事项

⚠️ 重要提示

Holo1使用绝对坐标（像素数），而HuggingFace处理器会对图像进行调整大小。为了使坐标匹配，需要对图像进行智能调整大小。

使用建议

💡 使用建议

如果你的硬件支持BF16加速，建议使用BF16格式以获得更好的性能和内存效率。在选择量化模型时，需要根据设备的内存和性能需求进行权衡。