UForm

袖珍型多模态人工智能
用于内容理解和生成

                       

多模态嵌入，维度从64到768 • 10亿参数的聊天模型
短文本 • 图片 • 🔜 视频片段 • 🔜 长文档
ONNX • CoreML • PyTorch
Python • JavaScript • Swift

---

欢迎来到 UForm，一个既通用又高效的__多模态__ AI 库。UForm 的小型嵌入模型可以帮助您理解并搜索多种语言的视觉和文本内容。而 UForm 的小型生成模型不仅支持对话和聊天场景，还非常适合快速生成图片标题以及进行视觉问答（VQA）。借助紧凑的__自定义预训练 Transformer 模型__，它可以在从您的服务器集群到智能手机的任何设备上运行。

特性

• 小型嵌入：64 维的 套娃式 嵌入，可用于极其快速的 搜索。
• 吞吐量：由于模型体积小，推理速度比竞争对手快 2–4 倍。
• 便携性：模型原生支持 ONNX，因此可以轻松部署在任何平台上。
• 量化感知：将嵌入从 f32 降为 i8 而几乎不损失召回率。
• 多语言：基于均衡的数据集训练，可在 20 多种语言中实现出色的召回效果。

模型

有关准确性和速度的基准测试，请参阅评估页面。

嵌入模型

模型	参数	语言	架构
uform3-image-text-english-large 🆕	3.65 亿	1	12 层 BERT，ViT-L/14
uform3-image-text-english-base	1.43 亿	1	4 层 BERT，ViT-B/16
uform3-image-text-english-small 🆕	7900 万	1	4 层 BERT，ViT-S/16
uform3-image-text-multilingual-base	2.06 亿	21	12 层 BERT，ViT-B/16

生成模型

模型	参数	用途	架构
uform-gen2-dpo 🆕	12 亿	聊天、图片描述、VQA	qwen1.5-0.5B，ViT-H/14
uform-gen2-qwen-500m	12 亿	聊天、图片描述、VQA	qwen1.5-0.5B，ViT-H/14
uform-gen ⚠️	15 亿	图片描述、VQA	llama-1.3B，ViT-B/16

快速入门示例

嵌入模型

首先，运行 pip install uform。 然后加载模型：

from uform import get_model, Modality

# 默认使用 `dtype='bfloat16'`，可在几乎不损失精度的情况下实现约2倍的加速
processors, models = get_model('unum-cloud/uform3-image-text-english-small', device='cuda')

model_text = models[Modality.TEXT_ENCODER]
model_image = models[Modality.IMAGE_ENCODER]
processor_text = processors[Modality.TEXT_ENCODER]
processor_image = processors[Modality.IMAGE_ENCODER]

嵌入图像：

import requests
from io import BytesIO
from PIL import Image

image_url = 'https://media-cdn.tripadvisor.com/media/photo-s/1b/28/6b/53/lovely-armenia.jpg'
image = Image.open(BytesIO(requests.get(image_url).content))
image_data = processor_image(image)
image_features, image_embedding = model_image.encode(image_data, return_features=True)

嵌入查询：

text = '沐浴在温暖阳光下的城市景观，拥有多种建筑风格，背景中巍峨耸立着一座白雪皑皑的高山'
text_data = processor_text(text)
text_features, text_embedding = model_text.encode(text_data, return_features=True)

更多详情请参阅：

• Python 文档中的嵌入模型部分，位于 python/README.md
• JavaScript 文档中的嵌入模型部分，位于 javascript/README.md
• Swift 文档中的嵌入模型部分，位于 swift/README.md

生成式模型

生成式模型原生兼容以下代码：

from transformers import AutoModel, AutoProcessor

model = AutoModel.from_pretrained('unum-cloud/uform-gen2-dpo', trust_remote_code=True)
processor = AutoProcessor.from_pretrained('unum-cloud/uform-gen2-dpo', trust_remote_code=True)

prompt = '问题或指令'
image = Image.open('image.jpg')

inputs = processor(text=[prompt], images=[image], return_tensors='pt')

with torch.inference_mode():
     output = model.generate(
        **inputs,
        do_sample=False,
        use_cache=True,
        max_new_tokens=256,
        eos_token_id=151645,
        pad_token_id=processor.tokenizer.pad_token_id
    )
prompt_len = inputs['input_ids'].shape[1]
decoded_text = processor.batch_decode(output[:, prompt_len:])[0]

更多详情请参阅：

• Python 文档中的生成式模型部分，位于 python/README.md
• JavaScript 文档中的生成式模型部分 🔜
• Swift 文档中的生成式模型部分 🔜

技术细节

降精度、量化、套娃与切片

根据具体应用场景，嵌入向量可以在不显著降低召回率的前提下，降为更小的数值表示形式。在几乎所有情况下，都建议从 f32 切换到 f16，除非您使用的硬件非常老旧且不支持半精度运算。此外，也可以采用线性缩放的方式将数据转换为 i8 格式，不过对于包含数百万条可搜索记录的大规模数据集而言，这种做法可能会对召回率产生明显影响。同样地，对于高维嵌入（如512或768维），一种常见的策略是将其量化为单比特表示，以提升检索速度。

import numpy as np

f32_embedding: np.ndarray = model.encode_text(text_data, return_features=False)
f16_embedding: np.ndarray = f32_embedding.astype(np.float16)
i8_embedding: np.ndarray = (f32_embedding * 127).astype(np.int8)
b1_embedding: np.ndarray = np.packbits((f32_embedding > 0).astype(np.uint8))

另一种量化方法是使用“套娃”嵌入，即将嵌入向量切分为多个较小的部分，并以层次化的方式进行检索。

import numpy as np

large_embedding: np.ndarray = model.encode_text(text_data, return_features=False)
small_embedding: np.ndarray = large_embedding[:, :256]
tiny_embedding: np.ndarray = large_embedding[:, :64]

这两种方法均得到 USearch 向量搜索引擎和 SimSIMD 数值计算库的原生支持。当处理小型数据集（最多数百万条记录）并需要低延迟的余弦距离计算时，借助 SimSIMD 库，您可以实现比 PyTorch、NumPy、SciPy 和原生 Python 快 5 至 2500 倍的性能提升report-simsimd。

from simsimd import cosine, hamming

distance: float = cosine(f32_embedding, f32_embedding) # 在 Apple M2 CPU 上性能是 SciPy 的 32 倍
distance: float = cosine(f16_embedding, f16_embedding) # 在 Apple M2 CPU 上性能是 SciPy 的 79 倍
distance: float = cosine(i8_embedding, i8_embedding) # 在 Apple M2 CPU 上性能是 SciPy 的 133 倍
distance: float = hamming(b1_embedding, b1_embedding) # 在 Apple M2 CPU 上性能是 SciPy 的 17 倍

类似地，当处理大型数据集（每台服务器可达数十亿条记录）并追求高吞吐量检索时，使用 USearch 可以实现比 FAISS 和其他向量搜索引擎快 100 倍的性能提升report-usearch。以下是几个示例：

from usearch.index import Index

f32_index = Index(ndim=64, metric='cos', dtype='f32') # 用于套娃嵌入
f16_index = Index(ndim=64, metric='cos', dtype='f16') # 用于套娃嵌入
i8_index = Index(ndim=256, metric='cos', dtype='i8') # 用于量化后的嵌入
b1_index = Index(ndim=768, metric='hamming', dtype='b1') # 用于二进制嵌入

紧凑封装

PyTorch 是一个较为庞大的依赖项，尤其是在边缘设备或物联网设备上运行时。通过使用原生 ONNX 运行时，可以显著降低内存占用和部署延迟。

$ conda create -n uform_torch python=3.10 -y
$ conda create -n uform_onnx python=3.10 -y
$ conda activate uform_torch && pip install -e ".[torch]" && conda deactivate
$ conda activate uform_onnx && pip install -e ".[onnx]" && conda deactivate
$ du -sh $(conda info --envs | grep 'uform_torch' | awk '{print $2}')
> 5.2G    ~/conda/envs/uform_torch
$ du -sh $(conda info --envs | grep 'uform_onnx' | awk '{print $2}')
> 461M    ~/conda/envs/uform_onnx

其中大部分体积还可以进一步压缩至仅 100 MB，包括模型和运行时。您可以选择众多受支持的 ONNX 执行提供者，其中包括适用于 Nvidia GPU 的 XNNPACK、CUDA 和 TensorRT，适用于 Intel 的 OpenVINO，适用于 Windows 的 DirectML，适用于 AMD 的 ROCm，适用于 Apple 设备的 CoreML，以及更多即将支持的选项。

命令行中的多模态聊天

生成式模型可以在命令行中用于类聊天的交互体验。 为此，您可以使用 UForm 包中提供的 uform-chat 命令行工具。

$ pip install uform
$ uform-chat --model unum-cloud/uform-gen2-dpo --image=zebra.jpg
$ uform-chat --model unum-cloud/uform-gen2-dpo \
>     --image="https://bit.ly/3tIVg9M" \
>     --device="cuda:0" \
>     --fp16

UForm 快速上手指南

UForm 是一款轻量级多模态 AI 库，专为内容理解与生成设计。它提供从 64 维到 768 维的紧凑嵌入模型（Embedding）以及参数量约 1B 的生成式模型（Generative），支持文本、图像的多语言处理，并原生兼容 ONNX、CoreML 和 PyTorch，可轻松部署于服务器至移动端。

环境准备

• 系统要求：支持 Linux、macOS 和 Windows。若需 GPU 加速，请确保已安装对应的 CUDA 驱动。
• 前置依赖：
  • Python 3.8+
  • PyTorch (用于加载和运行模型)
  • Pillow (用于图像处理)
  • Requests (用于示例中获取网络图片)
• 硬件建议：虽然模型小巧可在 CPU 运行，但推荐使用 NVIDIA GPU 以获得最佳推理速度。

安装步骤

使用 pip 安装核心库及依赖：

pip install uform torch pillow requests

提示：国内开发者如遇下载缓慢，可指定清华或阿里镜像源加速安装：

pip install uform torch pillow requests -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

1. 嵌入模型 (Embedding Models)

适用于跨模态搜索、以图搜图或文本检索。以下示例展示如何加载小型多模态模型并分别编码图像与文本。

from uform import get_model, Modality
import requests
from io import BytesIO
from PIL import Image

# 加载模型 (默认使用 bfloat16 以提升速度)
# device='cuda' 可启用 GPU 加速，若无 GPU 可改为 'cpu'
processors, models = get_model('unum-cloud/uform3-image-text-english-small', device='cuda')

model_text = models[Modality.TEXT_ENCODER]
model_image = models[Modality.IMAGE_ENCODER]
processor_text = processors[Modality.TEXT_ENCODER]
processor_image = processors[Modality.IMAGE_ENCODER]

# 编码图像
image_url = 'https://media-cdn.tripadvisor.com/media/photo-s/1b/28/6b/53/lovely-armenia.jpg'
image = Image.open(BytesIO(requests.get(image_url).content))
image_data = processor_image(image)
image_features, image_embedding = model_image.encode(image_data, return_features=True)

# 编码文本查询
text = 'a cityscape bathed in the warm glow of the sun, with varied architecture and a towering, snow-capped mountain rising majestically in the background'
text_data = processor_text(text)
text_features, text_embedding = model_text.encode(text_data, return_features=True)

# 此时 image_embedding 和 text_embedding 可用于计算相似度进行跨模态检索

2. 生成式模型 (Generative Models)

适用于视觉问答 (VQA)、图像描述生成及多模态对话。UForm 的生成模型原生兼容 Hugging Face transformers 接口。

from transformers import AutoModel, AutoProcessor
from PIL import Image
import torch

# 加载生成式模型
model = AutoModel.from_pretrained('unum-cloud/uform-gen2-dpo', trust_remote_code=True)
processor = AutoProcessor.from_pretrained('unum-cloud/uform-gen2-dpo', trust_remote_code=True)

# 准备输入
prompt = 'What is in this image?'
image = Image.open('image.jpg') # 请替换为本地图片路径

inputs = processor(text=[prompt], images=[image], return_tensors='pt')

# 执行生成
with torch.inference_mode():
     output = model.generate(
        **inputs,
        do_sample=False,
        use_cache=True,
        max_new_tokens=256,
        eos_token_id=151645,
        pad_token_id=processor.tokenizer.pad_token_id
    )

# 解码输出
prompt_len = inputs['input_ids'].shape[1]
decoded_text = processor.batch_decode(output[:, prompt_len:])[0]
print(decoded_text)

进阶技巧：量化与降维

为了极致性能，UForm 支持将嵌入向量从 f32 降级为 f16、i8 甚至二值化 (b1)，或使用 Matryoshka 风格切片（如截取前 64 维），配合 USearch 或 SimSIMD 库可实现数倍至数千倍的搜索加速。

import numpy as np

# 假设已获得 f32 格式的嵌入向量
f32_embedding = model.encode_text(text_data, return_features=False)

# 方案 A: 数据类型转换 (量化)
f16_embedding = f32_embedding.astype(np.float16)
i8_embedding = (f32_embedding * 127).astype(np.int8)

# 方案 B: Matryoshka 切片 (降维)
tiny_embedding = f32_embedding[:, :64]  # 仅保留前 64 维