اگر داده یا مدل حجیم را داخل Git گذاشته‌اید، با ریپوی سنگین و خطای فایل‌های بزرگ روبه‌رو شده‌اید. DVC یک ابزار خط فرمان است که کنار Git می‌نشیند تا داده و مدل را جدا نگه دارد و فقط یک متادیتای کوچک به Git بسپارد. نتیجه این است که با دستورهای Git بین نسخه‌های داده جابه‌جا می‌شوید، اما مخزن کد سبک می‌ماند. این راهنما از نصب تا پایپ‌لاین بازتولیدپذیر و رفع خطاهای رایج پیش می‌رود.

DVC در پایتون چیست و چه مشکلی را حل می‌کند؟

DVC ابزاری برای نسخه‌بندی داده و مدل در کنار کد است. به‌جای ذخیره فایل چند گیگابایتی در Git، محتوا را در کش DVC نگه می‌دارد و یک فایل .dvc کوچک را وارد Git می‌کند. با dvc add، dvc push و dvc repro نسخه داده، مدل و مراحل پردازش را بازتولید می‌کنید. از بخش نصب ادامه دهید.

فهرست مطالب

DVC در پایتون چیست و چه مشکلی را حل می‌کند؟
پیش‌نیازها و نصب DVC
نسخه‌بندی داده با dvc add
ذخیره‌سازی ریموت و dvc push/pull
ساخت پایپ‌لاین با dvc stage add و dvc repro
کاربرد واقعی در پروژه‌های هوش مصنوعی
نکات امنیتی و مدیریت حجم
خطاهای رایج در استفاده از DVC
سوالات متداول
جمع‌بندی

پیش‌نیازها و نصب DVC

برای شروع به پایتون ۳٫۹ یا جدیدتر، Git و یک ترمینال نیاز دارید. DVC 3.x روی ویندوز، مک و لینوکس اجرا می‌شود. اگر uv را در پایتون نصب کرده‌اید، سریع‌ترین راه نصب DVC به‌صورت ابزار مستقل است تا وابستگی‌های پروژه دست‌نخورده بمانند:

python --version
git --version
uv tool install dvc
dvc --version

اگر uv یا pipx ندارید، داخل محیط مجازی نصب کنید تا نسخه DVC هر پروژه مستقل بماند:

python -m venv .venv
.venv\Scripts\activate
pip install dvc
dvc --version

در مک و لینوکس، فعال‌سازی با source .venv/bin/activate انجام می‌شود. بعد از نصب، dvc --help باید دستورها را نشان دهد.

نسخه‌بندی داده با dvc add

اول یک ریپوی Git بسازید و DVC را در همان ریشه فعال کنید. فایل‌های داخلی dvc init باید در Git ثبت شوند، چون ساختار پروژه را توصیف می‌کنند:

mkdir dvc-demo
cd dvc-demo
git init
dvc init
git add .dvc .dvcignore
git commit -m "initialize DVC"

حالا یک فایل داده، مثلاً data/train.csv، را در پروژه بگذارید و با DVC ردیابی کنید:

mkdir data
rem فایل train.csv را داخل پوشه data قرار دهید
dvc add data/train.csv
git add data/train.csv.dvc data/.gitignore
git commit -m "track train data with DVC"

بعد از dvc add، فایل CSV از دید Git خارج می‌شود و یک فایل کوچک data/train.csv.dvc جای آن را می‌گیرد. این فایل فقط هش و اندازه داده را نگه می‌دارد:

outs:
- md5: 8f14e45fceea167a5a36dedd4bea2543
  size: 2457600
  path: train.csv

داده در .dvc/cache ذخیره می‌شود و data/.gitignore مانع اضافه شدن تصادفی آن به Git می‌شود. اگر داده را عوض کردید، دوباره dvc add بزنید و فایل .dvc را کامیت کنید. Git تاریخچه متادیتا و DVC تاریخچه محتوا را نگه می‌دارد.

ذخیره‌سازی ریموت و dvc push/pull

کش محلی برای یک سیستم کافی است، اما برای اشتراک داده با هم‌تیمی‌ها باید ریموت تعریف کنید. برای آزمایش، یک پوشه محلی بسازید:

mkdir D:\dvcstore
dvc remote add -d storage D:\dvcstore
dvc push

در محیط واقعی معمولاً از S3، فضای ابری، SSH یا WebDAV استفاده می‌شود. مثلاً برای S3 پس از تنظیم اعتبارنامه‌ها:

dvc remote add -d storage s3://my-bucket/dvcstore
dvc push

وقتی هم‌تیمی ریپو را کلون می‌کند، فایل‌های .dvc را دارد اما خود داده را نه. او بعد از کلون یا هر git pull باید dvc pull بزند تا داده از ریموت مستقر شود:

git clone <repo-url>
cd <repo>
dvc pull
dvc checkout

dvc pull دانلود و استقرار را با هم انجام می‌دهد و dvc checkout فضای کاری را با فایل‌های .dvc همگام می‌کند. اگر ریموت یا اعتبارنامه درست نباشد این مرحله متوقف می‌شود؛ با dvc remote list مسیر و باکت را بررسی کنید.

ساخت پایپ‌لاین با dvc stage add و dvc repro

بخش قدرتمند DVC تعریف مراحل پردازش است. فرض کنید می‌خواهید ردیف‌های خالی را حذف کنید و تعداد ردیف‌های تمیز را به‌عنوان متریک ذخیره کنید:

# src/prepare.py
import csv
import json
from pathlib import Path

rows = list(csv.DictReader(open("data/train.csv", encoding="utf-8")))
clean = [row for row in rows if row.get("text", "").strip()]
out = Path("data/prepared")
out.mkdir(parents=True, exist_ok=True)

with open(out / "clean.csv", "w", newline="", encoding="utf-8") as f:
    writer = csv.DictWriter(f, fieldnames=rows[0].keys())
    writer.writeheader()
    writer.writerows(clean)

Path("metrics.json").write_text(
    json.dumps({"rows": len(clean)}, ensure_ascii=False),
    encoding="utf-8",
)
print(f"prepared {len(clean)} rows")

سپس مرحله را با dvc stage add تعریف کنید. -d وابستگی، -o خروجی و -m فایل متریک را مشخص می‌کند و دستور آخر همان چیزی است که DVC اجرا می‌کند:

dvc stage add -n prepare \
  -d src/prepare.py \
  -d data/train.csv \
  -o data/prepared \
  -m metrics.json \
  python src/prepare.py

این دستور dvc.yaml را می‌سازد. حالا پایپ‌لاین را اجرا کنید تا خروجی‌ها ساخته و در dvc.lock ثبت شوند:

dvc repro
dvc dag
dvc status
git add dvc.yaml dvc.lock metrics.json
git commit -m "add prepare stage"

dvc repro فقط مراحلی را اجرا می‌کند که وابستگی‌هایشان تغییر کرده و نتیجه اجراهای قبلی را از کش برمی‌دارد. dvc dag نمودار مراحل و dvc status تغییرات خارج از مرحله را نشان می‌دهد. بعد از تغییر داده اول dvc add و سپس dvc repro بزنید.

کاربرد واقعی در پروژه‌های هوش مصنوعی

در پروژه یادگیری ماشین، داده خام، فایل پردازش‌شده، وزن مدل و متریک هر کدام نسخه دارند. داده خام را با dvc add ردیابی کنید و مراحل آماده‌سازی و آموزش را در dvc.yaml بنویسید. بعد از هر آموزش موفق، مدل را پوش و کامیت و تگ کنید:

dvc add models/model.pkl
git add models/model.pkl.dvc
git commit -m "model v1"
git tag -a model-v1 -m "first model version"
dvc push

برای مقایسه اجراها از dvc exp run و dvc metrics show استفاده کنید. اگر مدل را با Scikit-learn می‌سازید، آموزش Scikit-learn در پایتون نقطه شروع خوبی است. در CI هم بعد از git pull دستورهای dvc pull، dvc repro و در صورت موفقیت dvc push اجرا می‌شوند.

نکات امنیتی و مدیریت حجم

اطلاعات اتصال ریموت را در .dvc/config عمومی ننویسید؛ DVC فایل محلی .dvc/config.local را برای مقادیر حساس پشتیبانی می‌کند. کلید S3 یا رمز SSH را در متغیر محیطی یا فایل اعتبارنامه سیستم نگه دارید و دسترسی ریموت را محدود کنید.

حجم کش با هر نسخه داده رشد می‌کند. dvc gc -w نسخه‌های بدون استفاده در فضای کاری را پاک می‌کند؛ قبل از اجرا مطمئن شوید نسخه‌های قدیمی را پوش کرده‌اید. برای فایل‌های غیرلازم .dvcignore و برای بررسی سلامت نصب dvc doctor را به کار ببرید.

خطاهای رایج در استفاده از DVC

کامیت کردن خود داده به‌جای فایل .dvc: اگر git add data/train.csv بزنید، داده وارد تاریخچه Git می‌شود و پاک کردنش سخت است. فقط .dvc و .gitignore را کامیت کنید.
فراموش کردن dvc push: کامیت موفق یعنی متادیتا در Git است، نه اینکه داده در ریموت هست. بعد از هر تغییر، هم git push و هم dvc push لازم است.
اجرای dvc pull قبل از git checkout: اگر .dvc مربوط به نسخه دیگری باشد، داده اشتباه مستقر می‌شود. اول وضعیت Git را درست کنید.
تغییر دستی خروجی stage: اگر فایل داخل data/prepared را دستی عوض کنید، DVC آن را ناسازگار می‌بیند. خروجی را با اسکریپت و dvc repro بسازید.
مسیر یا اعتبارنامه اشتباه ریموت: در ویندوز بک‌اسلش و در لینوکس اسلش به کار ببرید و با dvc push آزمایشی اتصال را بسنجید.

سوالات متداول

آیا DVC جایگزین Git است؟

نه. DVC روی Git سوار می‌شود. Git کد و متادیتا را نسخه‌بندی می‌کند و DVC محتوای داده و مدل را در کش و ریموت جدا نگه می‌دارد. برای کار با DVC باید Git را هم بلد باشید.

آیا فایل داده واقعاً داخل Git ذخیره می‌شود؟

خیر. فقط .dvc با هش و اندازه در Git می‌رود. داده در کش محلی و ریموت DVC قرار می‌گیرد؛ به همین دلیل کلون Git سبک و سریع است.

برای پروژه کوچک هم DVC لازم است؟

اگر داده چند مگابایت است و تغییرات کمی دارد، Git کافی است. DVC وقتی ارزش دارد که داده یا مدل بزرگ باشد، چند نفر روی آن کار کنند یا بازتولید دقیق آموزش لازم باشد.

تفاوت dvc add و dvc stage add چیست؟

dvc add یک فایل یا پوشه را بدون مرحله پردازش ردیابی می‌کند. dvc stage add مرحله‌ای با دستور، وابستگی و خروجی می‌سازد که با dvc repro بازتولید می‌شود؛ برای داده خام اولی و برای خروجی اسکریپت‌ها دومی مناسب است.

آیا می‌توان از Google Drive یا سرور شخصی استفاده کرد؟

بله. DVC از انواع ریموت مثل S3، Google Drive، SSH، WebDAV و فضای محلی پشتیبانی می‌کند. انتخاب درست به حجم داده، سطح دسترسی و هزینه نگهداری بستگی دارد؛ برای داده حساس، سرور شخصی یا باکت با دسترسی محدود مناسب‌تر است.

جمع‌بندی

برای شروع، این چک‌لیست را دنبال کنید:

پایتون ۳٫۹+ و Git را آماده و DVC را نصب کنید.
با dvc init پروژه را فعال و فایل‌های داخلی را کامیت کنید.
داده را با dvc add ردیابی و فقط فایل .dvc را وارد Git کنید.
ریموت بسازید و بعد از هر تغییر dvc push بزنید.
مراحل را در dvc.yaml تعریف و با dvc repro بازتولید کنید.
dvc.lock و متریک‌ها را کامیت و مدل را تگ کنید.
اعتبارنامه‌ها را در config.local یا متغیر محیطی نگه دارید و کش را مدیریت کنید.

آموزش DVC در پایتون؛ مدیریت نسخه داده و مدل در پروژه‌های AI