LibreVLM

LibreVLM nằm sau extra vlm tùy chọn. Extra này cài một phiên bản transformers mới và các helper mà một số processor cần. Nếu không có extra, việc import một họ VLM sẽ phát sinh ImportError dẫn đến trang này.

1
pip install 'libreyolo[vlm]'

Trọng số được tải xuống từ Hugging Face Hub trong lần sử dụng đầu tiên vào thư mục weights/ cục bộ. Một số họ được phát hành theo giấy phép không thuộc OSI và ghi một thông báo duy nhất trước khi tải xuống. Nên dùng GPU cho các backend lớn hơn, nhưng mọi mô hình cũng chạy được trên CPU với device="cpu".

Khởi tạo mô hình, khai báo các từ bạn quan tâm rồi dự đoán. Backend mặc định là Qwen3-VL-4B, bộ phát hiện mạnh nhất trong bậc và mang giấy phép Apache-2.0.

1
from libreyolo import LibreVLM
2
3
# Qwen3-VL-4B by default; weights autodownload on first use
4
model = LibreVLM()
5
6
# The vocabulary is just words. Any words.
7
model.set_classes(["pink car", "wheel"])
8
9
result = model.predict("street.jpg")
10
11
print(result.boxes.xyxy)   # pixel [x1, y1, x2, y2]
12
print(result.boxes.cls)    # ids into ["pink car", "wheel"]
13
result.plot()              # same drawing helpers as any LibreYOLO model
14
result.save("out.jpg")

Đó là toàn bộ quy trình. Mọi thứ sau predict() hoạt động như một bộ phát hiện thông thường, vì vậy mã trực quan hóa, cắt ảnh và theo dõi hiện có vẫn hoạt động.

Chọn backend bằng bí danh truyền cho LibreVLM(...). Tên họ không kèm kích thước sẽ được phân giải thành kích thước mặc định. Backend mặc định chung là qwen3-vl-4b. Trong thực tế, các bộ phát hiện mạnh nhất là Qwen3-VL, LFM2-VL và Florence-2.

Chọn backend

• Chất lượng tốt nhất: qwen3-vl-8b hoặc qwen3-vl-4b (mặc định).
• Bounding box khít, dung lượng nhỏ: florence-2-large.
• Thiết bị biên / CPU: lfm2-vl-450m hoặc smolvlm2-500m.
• Giấy phép hoàn toàn thoáng: mọi kích thước Qwen3-VL, SmolVLM2, Florence-2 hoặc Kosmos-2.

Từ vựng là phần cốt lõi của phát hiện với từ vựng mở. Gọi set_classes() với danh sách chuỗi nhãn. Danh sách này được giữ lại qua mọi lời gọi predict() và track() sau đó cho đến khi bạn thiết lập lại. Phương thức trả về self nên có thể nối chuỗi lời gọi.

1
# Sticky and chainable
2
model = LibreVLM("qwen3-vl-2b").set_classes(["person", "dog", "cat"])
3
4
# Set it once at construction instead
5
model = LibreVLM("lfm2-vl-450m", names=["boat"], device="cpu")
6
7
# Re-set any time to change what you are looking for
8
model.set_classes(["a red car", "a blue truck"])

Nhãn có thể là bất kỳ cụm từ nào. Chúng phải là duy nhất khi không phân biệt chữ hoa chữ thường và bạn phải truyền một danh sách, không phải một chuỗi đơn lẻ. Nếu không bao giờ gọi set_classes(), mô hình sẽ dùng từ vựng COCO-80 dự phòng để lời gọi predict() đơn thuần vẫn cho kết quả hợp lý.

predict() và lời gọi model(...) tương đương chấp nhận cùng các loại nguồn như mọi bộ phát hiện LibreYOLO: đường dẫn, ảnh PIL, mảng numpy, URL, thư mục hoặc video. stream=True và track() cũng hoạt động.

1
result = model.predict(
2
    source="image.jpg",  # path | PIL | ndarray | URL | folder | video
3
    conf=0.25,           # see note below: scoring is synthetic
4
    classes=[0],         # optional: keep only these vocabulary ids
5
    max_det=300,
6
)

Cấu trúc trả về

Bạn nhận lại đối tượng Results chuẩn, giống hệt bộ phát hiện với từ vựng đóng:

Bên trong, LibreVLM phân tích đầu ra mô hình theo cách linh hoạt, xử lý khối Markdown, văn bản thừa, bounding box trùng lặp và mảng bị cắt ngắn, ánh xạ nhãn văn bản tự do về ID lớp đối tượng của bạn và loại bỏ mọi nhãn không có trong từ vựng. Bước cuối cùng này khiến một bộ sinh tự do hoạt động như bộ phát hiện tập đóng.

Phát hiện đối tượng có màu cụ thể

1
from libreyolo import LibreVLM
2
3
model = LibreVLM("qwen3-vl-4b")
4
model.set_classes(["red car"])
5
6
result = model.predict("parking_lot.jpg")
7
print(f"Found {len(result.boxes.cls)} red car(s)")
8
result.save("red_cars.jpg")

Bounding box khít với Florence-2

1
# Florence-2 is a purpose-built grounder: very tight pixel boxes.
2
model = LibreVLM("florence-2-large")
3
model.set_classes(["a red car", "license plate"])
4
5
result = model.predict("car.jpg")
6
result.plot()

Lọc nhanh về một lớp đối tượng

1
model = LibreVLM("qwen3-vl-2b").set_classes(["person", "dog", "cat"])
2
3
# classes= filters the configured vocabulary by id
4
people_only = model.predict("street.jpg", classes=[0])

Chạy trên CPU với ảnh mẫu tích hợp sẵn

1
from libreyolo import LibreVLM, SAMPLE_IMAGE
2
3
model = LibreVLM("lfm2-vl-450m", device="cpu")
4
# No set_classes() -> falls back to the COCO-80 vocabulary
5
result = model.predict(SAMPLE_IMAGE)
6
print(model.names[result.boxes.cls[0]])  # e.g. "person"

Batch, thư mục và video

1
model = LibreVLM().set_classes(["forklift", "pallet"])
2
3
# A whole folder
4
for result in model.predict("warehouse_frames/", stream=True):
5
    result.save()
6
7
# A video file (frames are processed one at a time)
8
model.predict("warehouse.mp4", save=True)

Đôi khi bạn cần mô hình chứ không phải bộ phát hiện. Các họ dùng chat template cung cấp chat(), nhận một ảnh cùng prompt tự do và trả về nguyên văn phần văn bản đã giải mã. Hãy dùng phương thức này để đếm, tạo chú thích hoặc đặt câu hỏi nhanh về hình ảnh.

1
model = LibreVLM("qwen3-vl-4b")
2
3
answer = model.chat("harbor.jpg", "How many boats are docked? Answer with a number.")
4
print(answer)

Mọi họ đều trả về cùng một Results, nhưng theo những cách khác nhau. Bạn hiếm khi cần quan tâm đến điều này, tuy nhiên việc hiểu lý do một số backend hoạt động khác biệt vẫn hữu ích. Các họ chat được prompt để trả về một mảng JSON chứa bounding box; các mô hình grounding dùng task token chuyên biệt.

Với các họ chat, bạn có thể ghi đè prompt phát hiện bằng đối số constructor prompt= và giới hạn độ dài sinh bằng max_new_tokens=. Thiết bị và dtype được phân giải tự động: bf16 hoặc fp16 trên CUDA, fp32 trên CPU.

LibreVLM mạnh mẽ nhưng còn non trẻ. Biết trước các giới hạn sẽ tránh những bất ngờ về sau.

• Độ tin cậy tổng hợp. Mọi bounding box đều có điểm 1.0. Vì vậy bộ lọc conf= hoạt động theo kiểu tất cả hoặc không có gì thay vì dùng ngưỡng thực.
• Không có mAP / kiểm định. val() phát sinh lỗi vì điểm tổng hợp sẽ khiến mAP COCO gây hiểu lầm.
• Không huấn luyện hoặc xuất. train() và export() phát sinh lỗi. Thay vào đó, hãy tinh chỉnh VLM thượng nguồn rồi tải trọng số thu được.
• Khả năng theo dõi bị suy giảm. track() vẫn chạy, nhưng điểm số đồng nhất khiến giai đoạn khôi phục với độ tin cậy thấp của tracker không hoạt động.
• Mỗi lần một ảnh. Quá trình sinh diễn ra tuần tự trong v1 nên giá trị batch= lớn hơn không giúp tăng tốc.
• Chỉ có API Python. CLI libreyolo chưa phân giải bí danh VLM.