LibreVLM

LibreVLM은 선택 사항인 vlm 추가 패키지로 제공됩니다. 최신 transformers와 일부 프로세서에 필요한 도우미를 설치합니다. 추가 패키지 없이 VLM 계열을 가져오면 이 페이지를 안내하는 ImportError가 발생합니다.

1
pip install 'libreyolo[vlm]'

가중치는 처음 사용할 때 Hugging Face Hub에서 로컬 weights/ 폴더로 내려받습니다. 일부 계열은 비 OSI 라이선스로 배포되며 내려받기 전에 일회성 안내를 기록합니다. 대형 백엔드에는 GPU 사용을 권장하지만 모든 모델은 device="cpu"를 사용하여 CPU에서도 실행됩니다.

모델을 생성하고 필요한 단어를 선언한 다음 예측합니다. 기본 백엔드는 이 티어에서 가장 강력한 탐지기인 Qwen3-VL-4B이며 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")

이것이 전체 과정입니다. predict() 이후의 모든 기능은 일반 탐지기와 동일하게 작동하므로 기존 시각화, 잘라내기, 추적 코드를 계속 사용할 수 있습니다.

LibreVLM(...)에 전달할 별칭으로 백엔드를 선택합니다. 크기를 생략한 계열 이름은 기본 크기로 해석됩니다. 전체 기본 백엔드는 qwen3-vl-4b입니다. 실제로 가장 강력한 탐지기는 Qwen3-VL, LFM2-VL, Florence-2입니다.

백엔드 선택

• 최고 품질: qwen3-vl-8b 또는 qwen3-vl-4b(기본값).
• 정밀한 바운딩 박스와 작은 설치 공간: florence-2-large.
• 엣지 / CPU: lfm2-vl-450m 또는 smolvlm2-500m.
• 완전한 허용적 라이선스: 모든 크기의 Qwen3-VL, SmolVLM2, Florence-2 또는 Kosmos-2.

보캐뷸러리는 오픈 보캐뷸러리 탐지의 핵심입니다. 레이블 문자열 목록을 set_classes()에 전달합니다. 이 설정은 다시 설정할 때까지 이후 모든 predict()와 track() 호출에 유지됩니다. self를 반환하므로 호출을 연결할 수 있습니다.

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"])

레이블에는 어떤 구문이든 사용할 수 있습니다. 대소문자를 구분하지 않았을 때 고유해야 하며 단일 문자열이 아닌 목록을 전달해야 합니다. set_classes()를 호출하지 않으면 모델이 COCO-80 보캐뷸러리를 사용하므로 인수 없는 predict()도 적절한 결과를 생성합니다.

predict()와 이에 해당하는 model(...) 호출은 다른 LibreYOLO 탐지기와 동일한 소스 유형을 받습니다. 경로, PIL 이미지, NumPy 배열, URL, 폴더 또는 비디오를 사용할 수 있습니다. stream=True와 track()도 작동합니다.

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
)

반환 구조

폐쇄형 보캐뷸러리 탐지기와 동일한 표준 Results 객체가 반환됩니다.

내부적으로 LibreVLM은 모델 출력을 유연하게 파싱합니다. 마크다운 펜스, 불필요한 산문, 중복 바운딩 박스, 잘린 배열을 처리하고 자유 형식 레이블을 클래스 ID에 다시 매핑하며 보캐뷸러리에 없는 레이블을 삭제합니다. 마지막 단계 덕분에 자유 형식 생성기가 폐쇄형 탐지기처럼 작동합니다.

특정 색상의 객체 탐지

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")

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()

실행 중 단일 클래스로 필터링

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])

내장 샘플 이미지로 CPU에서 실행

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"

배치, 폴더, 비디오

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)

탐지기가 아닌 모델 자체가 필요할 때도 있습니다. 채팅 템플릿 계열은 이미지와 자유 형식 프롬프트를 받아 디코딩한 텍스트를 그대로 반환하는 chat()을 제공합니다. 계수, 캡션 생성 또는 간단한 시각 질의에 사용합니다.

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)

모든 계열은 동일한 Results를 반환하지만 도달 방식은 서로 다릅니다. 대부분 신경 쓸 필요는 없지만 일부 백엔드가 특정 방식으로 작동하는 이유를 이해하는 데 도움이 됩니다. 채팅 계열에는 바운딩 박스의 JSON 배열을 요청하는 프롬프트를 제공하고 그라운딩 모델은 전용 작업 토큰을 사용합니다.

채팅 계열에서는 prompt= 생성자 인수로 탐지 프롬프트를 재정의하고 max_new_tokens=로 생성 길이를 제한할 수 있습니다. 장치와 dtype은 자동으로 결정됩니다. CUDA에서는 bf16 또는 fp16, CPU에서는 fp32를 사용합니다.

LibreVLM은 강력하지만 아직 초기 단계입니다. 한계를 미리 파악하면 나중에 예상치 못한 문제를 줄일 수 있습니다.

• 합성 신뢰도. 모든 바운딩 박스의 점수는 1.0입니다. 따라서 conf= 필터는 실제 임계값이 아니라 전부 통과하거나 전부 제외하는 방식으로 작동합니다.
• mAP 및 검증 미지원. 합성 점수는 COCO mAP에 오해를 일으키므로 val()에서 예외가 발생합니다.
• 학습 및 내보내기 미지원. train()과 export()에서 예외가 발생합니다. 대신 업스트림에서 VLM을 파인튜닝하고 생성된 가중치를 불러오십시오.
• 제한된 추적 성능. track()은 실행되지만 모든 점수가 같으므로 추적기의 낮은 신뢰도 복구 단계가 작동하지 않습니다.
• 한 번에 이미지 한 장. v1에서는 순차적으로 생성하므로 batch= 값을 늘려도 속도가 향상되지 않습니다.
• Python API 전용. libreyolo CLI는 아직 VLM 별칭을 해석하지 못합니다.