vLLM D3 튜토리얼: Python으로 AI 의사결정 모델을 로컬에서 실행하기

D3는 텍스트를 생성하는 대신 각 답변에 대한 확률을 반환하는 오픈 웨이트(open-weight) 의사결정 모델 계열입니다. 지원 티켓을 분류하거나, 기사를 점수화하거나, 비디오 클립을 점검하는 작업을 자체 머신에서 실행되는 모델에 단 한 번의 요청으로 처리할 수 있으며, 우리 테스트에서는 최소 87밀리초 만에 응답했습니다.

이 제품군은 6개의 모델로 구성되어 있으며, 6억에서 270억 매개변수까지 아우릅니다. 소형 모델은 보급형 하드웨어에서 실험해 볼 수 있고, 대형 모델은 더욱 까다로운 작업에 사용할 수 있습니다. D3 Edge는 매우 가벼워서 호환되는 스마트폰에서도 실행할 수 있습니다.

vLLM은 Structured Decisions 프레임워크를 통해 D3를 지원하므로, 모델을 로컬로 서빙하고 간단한 애플리케이션 프로그래밍 인터페이스(API)로 호출할 수 있습니다. 더 넓은 vLLM Semantic Router 프로젝트는 AI 애플리케이션을 위한 라우팅과 의사결정 기능을 추가합니다.

이 튜토리얼에서는 D3를 로컬에 설정하는 방법, 3가지 의사결정 타입, 그리고 첫 예측까지 다룹니다. 이후 다음 3가지 실용 프로젝트를 함께 만들어 보겠습니다:

1. AI 블로그 품질 분석기: TypeSafe Python 소프트웨어 개발 키트(SDK)와 Olostep을 사용해 실제 기사를 분류하고 평가합니다.
2. 이미지 이해: 상품 이미지를 분석해 카테고리를 식별하고 이미지 품질을 평가합니다.
3. 비디오 이해: 짧은 비디오를 분석해 움직임과 시각적 변화를 감지합니다.

마치면, D3를 로컬에서 실행하는 방법과 이를 활용해 텍스트, 이미지, 비디오 전반에 걸친 의사결정을 수행하는 애플리케이션을 만드는 방법을 익히게 됩니다. 또한 대규모 언어 모델을 로컬에서 실행하는 방법과 RTX 3090 GPU에서 로컬 추론 속도 높이기 가이드를 참고하실 수 있습니다.

요약

• D3는 텍스트를 생성하는 대신 선택형, 예/아니오(Noul), 점수형 질문에 대한 확률을 반환하는 오픈 웨이트 의사결정 모델 계열입니다.
• D3 Mini(40억)는 텍스트, 이미지, 비디오를 처리하며 vLLM과 함께 단일 NVIDIA RTX 3090 그래픽 처리 장치(GPU)에서 실행됩니다.
• vllm serve로 모델을 서빙하고 TypeSafe Python SDK 또는 /v1/systemone 엔드포인트로 호출합니다.
• 기사 품질 분석기, 상품 이미지 스크리너, 비디오 모션 분석기 등 3가지 프로젝트를 만듭니다.
• 우리 테스트에서 응답 시간은 87밀리초에서 1.11초 사이였습니다.

D3 의사결정 모델이란?

D3는 텍스트 생성을 목표로 하지 않고 의사결정을 위해 설계된 오픈 웨이트 AI 모델 계열입니다. 예를 들어 대규모 언어 모델(LLM)에 거래가 의심스러운지 설명해 달라고 묻는 대신, D3는 검토가 필요한지에 대한 확률을 직접 반환할 수 있습니다.

출처: vllm-sr/d3-mini · Hugging Face

다음 3가지 의사결정 타입을 지원합니다:

D3는 6억에서 270억 매개변수까지 6가지 크기로 제공되어, 엣지 디바이스부터 하이엔드 GPU까지 다양한 환경에 적합합니다. Hugging Face의 Decision 3.0 컬렉션에서 전체 제품군을 둘러볼 수 있습니다.

모델은 분류 정확도와 확률 품질을 측정하는 Typed Decisions 등 의사결정 중심 벤치마크로 평가됩니다.

이 튜토리얼에서는 텍스트, 이미지, 비디오 이해를 지원하면서도 로컬 NVIDIA RTX 3090 GPU에서 실행할 수 있을 만큼 작은 D3 Mini(40억)를 사용하겠습니다.

vLLM으로 D3를 로컬에서 실행하는 방법

vLLM Semantic Router(vLLM SR)는 vLLM 생태계의 오픈 소스 프로젝트로, AI 애플리케이션의 지능적인 의사결정을 돕습니다. 모델 라우팅, 안전성 점검, 시맨틱 캐싱, D3 같은 특화 의사결정 모델을 지원합니다. vLLM이 모델 추론을 담당하는 반면, vLLM SR은 요청을 어떻게 평가하고 라우팅할지에 초점을 맞춥니다.

이 튜토리얼에서는 vLLM의 새로운 Structured Decisions 지원을 사용해 Semantic Router 자체를 설치하지 않고도 로컬에서 D3 Mini를 실행합니다. vLLM은 D3를 빠르고 직관적인 "시스템 1" 사고에서 이름을 딴 System One API를 통해 서빙합니다. 이 API는 타입이 지정된 질문에 단일 패스로 답하고, 생성 텍스트 대신 확률을 반환합니다.

우리는 TypeSafe Python SDK로 모델에 연결해 분류, 확률 추정, 점수화 방식을 살펴보겠습니다.

1. vLLM 설치 및 D3 로컬 실행

Ubuntu Linux, Python 3.12, NVIDIA RTX 3090 GPU를 사용하겠습니다. Windows 사용자는 Windows Subsystem for Linux 2(WSL2)에서 Ubuntu를 통해 따라오실 수 있습니다.

먼저 uv를 설치합니다. 설치가 완료되면 터미널을 재시작해 uv 명령을 사용할 수 있도록 하세요.

curl -LsSf https://astral.sh/uv/install.sh | sh제공

이제 Python 3.12 환경을 만들고 활성화합니다:

uv venv --python 3.12 --seed
source .venv/bin/activate제공

다음으로, 새로운 Structured Decisions 지원이 포함된 vLLM 나이틀리 빌드를 설치합니다:

uv pip install -U vllm --torch-backend=auto \
  --extra-index-url https://wheels.vllm.ai/nightly제공

이제 로컬 테스트에 적합한 GPU 메모리 설정으로 D3 Mini 모델을 시작합니다:

vllm serve vllm-sr/d3-mini \
  --gpu-memory-utilization 0.75 \
  --max-model-len 4096 \
  --max-num-seqs 4 \
  --enforce-eager제공

첫 실행 시 모델이 Hugging Face에서 다운로드됩니다. 로드가 완료되면 vLLM은 로컬 System One API를 http://localhost:8000/v1/systemone에서 노출합니다.

이 터미널은 계속 실행해 두세요. 우리는 Jupyter 노트북에서 모델에 접속하겠습니다.

2. TypeSafe Python SDK로 D3에 연결

HTTP 요청을 직접 구성하는 대신, TypeSafe Python SDK를 사용해 로컬에서 실행 중인 모델과 통신하겠습니다.

필요한 라이브러리를 설치합니다:

%pip install typesafe-sdk olostep제공

3가지 의사결정 타입을 임포트하고 클라이언트를 설정해 로컬 vLLM 서버에 연결합니다:

from typesafe_sdk import TypeSafeClient, Choice, Noul, Score

client = TypeSafeClient(
    base_url="http://localhost:8000",
    api_key="local",
    model="vllm-sr/d3-mini"
)제공

로컬 서버는 호스팅된 TypeSafe 자격 증명을 요구하지 않으므로, API 키는 플레이스홀더를 사용합니다.

3. 첫 AI 의사결정 만들기

간단한 이상 거래 탐지 예시로 시작해 보겠습니다. 비정상적인 거래를 제시하고 검토 대상으로 표시해야 하는지 물어보겠습니다.

%%time
result = client.system_one(
    state="""
    A customer usually spends $20-100 in the US.
    A new $2,500 transaction was made from another country.
    """,
    questions={
        "suspicious": Noul(
            instructions="Should this transaction be flagged for fraud review?"
        )
    }
)

print(result.nouls["suspicious"].noul)제공

출력:

0.9990723773071258
CPU times: user 1.89 ms, sys: 2.01 ms, total: 3.91 ms
Wall time: 87.4 ms제공

D3는 약 99.9%의 확률을 반환해, 해당 거래를 검토 대상으로 표시해야 함을 나타냅니다. 추론에는 약 87밀리초가 소요되었습니다.

세 가지 의사결정 타입을 한 번의 요청으로 결합할 수도 있습니다. 이번에는 지원자를 평가하면서 최적의 역할을 식별하고, 자격 여부를 확인하며, 적합도를 점수화하도록 요청해 보겠습니다.

%%time
result = client.system_one(
    state="""
    Candidate: 4 years of Python experience, 2 years working
    with machine learning, and strong SQL skills.
    No experience with frontend development.
    Available roles: Data Scientist, Backend Developer,
    Frontend Developer.
    """,
    questions={
        "role": Choice(
            instructions="Which role best matches the candidate?",
            criteria={
                "data_scientist": "Python, SQL, and machine learning",
                "backend": "Python, APIs, and backend systems",
                "frontend": "JavaScript, React, and UI development"
            }
        ),
        "qualified": Noul(
            instructions="Does the candidate meet the basic requirements for the best-matching role?"
        ),
        "fit": Score(
            instructions="How well does the candidate match the best-fitting role?",
            criteria=["Low", "Medium", "High"]
        )
    }
)

print("Best Role:", result.choices["role"].choice)
print("Qualified:", result.nouls["qualified"].noul)
print("Candidate Fit:", result.scores["fit"].score)제공

출력:

Best Role: data_scientist
Qualified: 0.9446079177060042
Candidate Fit: 1.6421276950866912
CPU times: user 4.18 ms, sys: 3.11 ms, total: 7.29 ms
Wall time: 165 ms제공

모델은 최적 역할로 Data Scientist를 정확히 식별하고, 자격 충족 확률을 94.5%로 부여했으며, 0~2 스케일에서 적합도 점수 1.64를 반환했습니다. 세 가지 결정이 165밀리초 만에 반환되었습니다.

이제 로컬에서 D3를 실행했으니, 이를 활용해 3가지 실용 AI 애플리케이션을 만들어 보겠습니다.

프로젝트 1: D3 Mini로 AI 블로그 품질 분석기 만들기

출간 전 검토해야 하는 수십 편의 기사를 관리하는 기술 매체를 운영한다고 가정해 보겠습니다. 모든 기사를 직접 읽는 대신, Olostep으로 웹사이트 콘텐츠를 추출하고 로컬에서 실행 중인 D3 Mini 모델로 분류 및 점수화하는 AI 품질 분석기를 구축할 수 있습니다.

제가 작성한 실제 기사인 KTransformers 튜토리얼로 테스트해 보겠습니다.

1. KTransformers 튜토리얼 스크레이핑

먼저 Olostep Python SDK를 사용해 기사 콘텐츠를 Markdown으로 추출하겠습니다.

from getpass import getpass
from olostep import Olostep

olostep = Olostep(api_key=getpass("Enter your Olostep API key: "))

url = "https://www.datacamp.com/tutorial/ktransformers-tutorial"
page = olostep.scrapes.create(
    url_to_scrape=url,
    formats=["markdown"]
)

content = page.result.markdown_content
print(content[:1000])제공

Olostep은 분석을 위해 기사 내용을 Markdown으로 가져오며, 제목, 본문, 코드 예시를 그대로 보존합니다.

2. D3로 기사 분류 및 평가

다음으로 Choice로 기사의 카테고리를 식별하고, Score로 교육적 품질을 5점 척도로 평가하겠습니다.

%%time
result = client.system_one(
    state=content[:12000],
    questions={
        "category": Choice(
            instructions="What is the main topic of this article?",
            criteria={
                "ai": "Artificial intelligence and LLMs",
                "data_science": "Data science and analytics",
                "programming": "Software development",
                "other": "Other technical topics"
            }
        ),
        "quality": Score(
            instructions=(
                "Rate the article's educational quality based on "
                "clarity, technical depth, practical examples, "
                "and usefulness to readers."
            ),
            criteria=[
                "Very poor: Confusing and lacks useful information",
                "Poor: Limited depth and unclear explanations",
                "Average: Understandable but missing important details",
                "Good: Clear explanations and useful examples",
                "Excellent: Detailed, practical, and easy to follow"
            ]
        )
    }
)

category = result.choices["category"].choice
quality = result.scores["quality"].score + 1

print("Category:", category)
print(f"Quality: {quality:.1f}/5")제공

출력:

Category: ai
Quality: 4.6/5
CPU times: user 3.29 ms, sys: 2.96 ms, total: 6.25 ms
Wall time: 1.11 s제공

D3는 기사를 정확히 AI로 분류하고 4.6/5의 품질 점수를 부여했으며, 약 1.11초 만에 분석을 완료했습니다.

프로젝트 2: D3 Mini로 상품 이미지 분석

이번 프로젝트에서는 전자상거래 스토어를 위한 간단한 상품 이미지 심사 워크플로를 만들어 보겠습니다. 목표는 D3 Mini로 상품 카테고리를 식별하고, 상품이 명확히 보이는지 확인하며, 카탈로그에 추가하기 전 이미지 품질을 평가하는 것입니다.

다음 코드는 vLLM System One API를 직접 사용하며, 결과를 올바른 answers 필드에서 읽습니다.

1. 상품 이미지 불러오기

먼저 샘플 상품 이미지를 다운로드해 노트북에 표시하고, 모델에 전송할 수 있도록 base64로 변환합니다.

import base64
import requests
from IPython.display import Image, display

image_url = "https://images.unsplash.com/photo-1542291026-7eec264c27ff?w=600"
image_data = requests.get(image_url, timeout=20).content

display(Image(data=image_data))제공

image_base64 = base64.b64encode(image_data).decode()
image_input = f"data:image/jpeg;base64,{image_base64}"제공

이제 D3 Mini가 직접 분석할 수 있는 전송 준비 완료 이미지 입력을 얻었습니다.

2. D3 Mini로 이미지 분석

다음으로, 상품이 어떤 카테고리에 속하는지, 물리적 상품이 명확히 보이는지, 온라인 스토어에 적합한 이미지인지 한 번에 3가지를 요청하겠습니다.

%%time
result = client.system_one(
    state="Review this product image for an online store.",
    images=[image_input],
    questions={
        "category": Choice(
            instructions="What product category is shown?",
            criteria={
                "footwear": "Shoes, sneakers, or boots",
                "clothing": "Shirts, jackets, or trousers",
                "electronics": "Electronic devices",
                "other": "Other products"
            }
        ),
        "product_visible": Noul(
            instructions="Is a physical product clearly visible?"
        ),
        "quality": Score(
            instructions="Rate the image suitability for an online store.",
            criteria=["Poor", "Average", "Good", "Excellent"]
        )
    }
)

print("Category:", result.choices["category"].choice)
print("Product Visible:", result.nouls["product_visible"].noul)
print("Image Quality:", result.scores["quality"].score)제공

출력:

Product Category: footwear
Product Visibility: 97.11%
Image Quality: 2.30/3
CPU times: user 4.91 ms, sys: 952 μs, total: 5.86 ms
Wall time: 282 ms제공

모델은 항목을 footwear로 식별하고, 상품이 명확히 보인다고 확인했으며, 단 282밀리초 만에 이미지에 탄탄한 품질 점수를 부여했습니다.

프로젝트 3: D3 Mini로 비디오 모션 분석기 만들기

마지막 프로젝트에서는 D3 Mini를 사용해 간단한 비디오 모션 분석기를 만들어 보겠습니다. 장문의 비디오 설명을 생성하는 대신, 짧은 클립에서 어떤 일이 일어나는지 이해하고, 이동 방향을 식별하며, 시각적 변화를 감지하도록 모델을 사용합니다. 이 접근 방식은 비디오 모니터링, 이벤트 감지, 자동 콘텐츠 분석에 유용할 수 있습니다.

1. 샘플 비디오 다운로드

Hugging Face의 공식 D3 Mini 샘플 비디오를 사용하겠습니다. 먼저 필요한 라이브러리를 설치합니다:

%pip install huggingface_hub제공

다음으로 샘플 비디오를 다운로드해 로컬에서 분석할 수 있도록 합니다.

from huggingface_hub import hf_hub_download
from IPython.display import Video, display

video_path = hf_hub_download(
    repo_id="vllm-sr/d3-mini",
    filename="assets/example-video.mp4"
)제공

비디오는 파란색에서 녹색으로 색이 바뀌면서 왼쪽에서 오른쪽으로 이동하는 상자를 보여줍니다.

2. 비디오 분석

먼저 비디오를 base64 형식으로 변환해 로컬 vLLM 서버로 전송할 수 있도록 합니다.

import base64
import requests

with open(video_path, "rb") as f:
    video_base64 = base64.b64encode(f.read()).decode()

video_input = f"data:video/mp4;base64,{video_base64}"제공

이제 System One API를 사용해 정사각형이 어느 방향으로 이동하는지와 색이 변하는지를 D3 Mini에 두 가지 질문으로 요청하겠습니다.

%%time
response = requests.post(
    "http://localhost:8000/v1/systemone",
    json={
        "model": "vllm-sr/d3-mini",
        "state": "Analyze the movement of the object in this video.",
        "videos": [video_input],
        "questions": {
            "direction": {
                "type": "choice",
                "instructions": "Which direction does the square move?",
                "criteria": {
                    "left": "From right to left",
                    "right": "From left to right",
                    "still": "The square does not move"
                }
            },
            "color_change": {
                "type": "noul",
                "instructions": "Does the square change color during the video?"
            }
        }
    },
    timeout=120
)
response.raise_for_status()

answers = response.json()["answers"]

print("Movement:", answers["direction"]["choice"])
print(f"Color Change: {answers['color_change']['noul']:.1%}")제공

출력:

Movement: right
Color Change: 93.7%
CPU times: user 3.01 ms, sys: 5.04 ms, total: 8.05 ms
Wall time: 723 ms제공

D3 Mini는 이동 방향을 right로 정확히 식별하고, 색 변화에 93.7%의 확률을 부여했으며, 단 723밀리초 만에 분석을 완료했습니다.

마무리 생각

D3 Mini는 단일 NVIDIA RTX 3090 GPU에서 텍스트, 이미지, 비디오 전반에 걸친 분류, 예/아니오 확인, 점수화를 처리합니다. 로컬에 D3를 설정하는 과정은 놀라울 정도로 간단했습니다. 제가 겪은 유일한 문제는 CUDA 메모리 부족 오류였는데, GPU 메모리 사용량을 줄여 해결했습니다.

그 외에는 모든 것이 매끄럽게 동작했습니다. 이미 vLLM에 익숙하시다면 설정을 더 최적화할 수도 있을 것입니다.

가장 인상 깊었던 점은 속도였습니다. 짧은 텍스트 결정은 87밀리초, 전체 기사 분석은 1.11초, 비디오 예시는 723밀리초가 소요되었습니다. 이 모든 것이 제 GPU에서 구동됐습니다.

팀 전체를 위한 로컬 서버에서 의사결정 모델을 운영하는 것이 점점 실용적인 단계에 이르고 있다고 생각합니다. 모든 요청에 대규모 추론 모델이 필요한 것은 아닙니다.

분류, 라우팅, 점수화, 콘텐츠 필터링 같은 일상적 작업에는 더 작은 의사결정 모델로 충분합니다. 그런 다음 실제로 더 깊은 분석이나 자세한 설명이 필요한 작업에만 비용이 큰 추론 모델을 할당하면 됩니다.

물론, 프로덕션에 도입하기 전에는 반드시 자체 워크로드에 대해 정확도와 성능을 평가해야 합니다. 텍스트, 이미지, 비디오 전반에서 D3를 테스트한 뒤 제가 얻은 간단한 원칙은 이렇습니다: 작업이 분류이거나 예/아니오 확인 또는 평점이라면 먼저 D3 모델을 시도하고, 설명이 필요할 때만 추론 모델로 넘어가세요.

오픈 모델로 작업하는 방법을 더 배우고 싶다면 Working with Hugging Face 과정을 살펴보시기 바랍니다.