Sử dụng hình ảnh Docker

Mỗi Job chạy bên trong một image Docker, cung cấp môi trường phần mềm cho nó, bao gồm các công cụ hệ thống và thư viện đã cài đặt. Với hf jobs run, bạn cung cấp một image và một lệnh. Với hf jobs uv run, uv chuẩn bị môi trường Python cho script của bạn, và Jobs sẽ chọn một image mặc định trừ khi bạn chỉ định một image khác.

Chọn cách chạy tác vụ của bạn

Bắt đầu với hf jobs uv run khi các phụ thuộc của script Python có thể được cài đặt bằng uv, như minh họa trong Quickstart. Chọn một image khi bạn cần các công cụ hệ thống bổ sung hoặc muốn sử dụng một môi trường phần mềm đã được chuẩn bị sẵn.

Hình ảnh mặc định bao gồm Python và uv. Xem cấu hình UV Jobs để biết hình ảnh mặc định hiện tại và các tùy chọn khả dụng.

Bạn có thể sử dụng một hình ảnh có sẵn từ một registry như Docker Hub, hoặc tự xây dựng và lưu trữ hình ảnh của bạn bằng một Docker Space.

Sử dụng hình ảnh có sẵn

Sử dụng hf jobs run với một image và lệnh cần chạy bên trong nó. Bất kỳ image công khai nào từ Docker Hub hoặc registry khác đều hoạt động, bao gồm cả một tag cụ thể. Hãy bắt đầu với một image nhỏ:

hf jobs run ubuntu echo 'Hello from the cloud!'

Job sẽ kéo image, chạy lệnh và thoát. Để sử dụng phần mềm mà image đã cung cấp, hãy chọn image có sẵn phần mềm đó. Ví dụ, sử dụng image PyTorch để tạo tensor trên GPU và nhân đôi giá trị của nó:

hf jobs run --flavor t4-small --timeout 5m \
    pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel \
    -- python -c 'import torch; x = torch.ones(3, device="cuda"); print(x * 2)'

Hình ảnh cung cấp PyTorch và phần mềm CUDA. --flavor t4-small chọn GPU, --timeout 5m giới hạn thời gian chạy của Job, và lệnh Python sử dụng gói PyTorch đã cài đặt trong hình ảnh. Kết quả xuất hiện trong log của Job.

-- phân tách các tùy chọn của Jobs khỏi lệnh và các đối số của nó. Ví dụ, --help sau dấu phân tách này sẽ được truyền đến lệnh của bạn. Xem Truyền đối số.

Chạy script của bạn với tệp đầu vào và tệp đầu ra

Một script được chạy bởi hf jobs run phải khả dụng bên trong Job. Bạn có thể sử dụng một script có sẵn trong image, hoặc gắn một thư mục cục bộ.

Ví dụ, giả sử bạn có một script suy luận sử dụng các gói Transformers và PyTorch trong image huggingface/trl. Thư mục work cục bộ của bạn chứa inference.py và inputs.jsonl, và script chấp nhận các đường dẫn --input và --output. Sau khi tạo một Storage Bucket cho kết quả, hãy chạy nó với:

hf jobs run --flavor t4-small --timeout 10m \
    -v ./work:/work \
    -v hf://buckets/YOUR_USERNAME/results:/output \
    huggingface/trl \
    -- python /work/inference.py --input /work/inputs.jsonl --output /output/results.jsonl

Thay YOUR_USERNAME bằng namespace của chủ bucket. CLI sẽ tải lên thư mục cục bộ và gắn nó tại /work. Script của bạn sẽ đọc dữ liệu đầu vào tại đó và ghi kết quả vào bucket được gắn tại /output, nơi chúng vẫn khả dụng sau khi Job kết thúc. Hãy điều chỉnh các tham số, phần cứng và thời gian chờ của lệnh cho phù hợp với script của bạn; xem Volumes để biết các tùy chọn đầu vào và đầu ra khác.

Sử dụng một image với uv

Sử dụng hf jobs uv run --image khi script của bạn cần các công cụ hệ thống ngoài hình ảnh mặc định trong khi vẫn giữ nguyên quy trình phụ thuộc Python của uv. Hình ảnh được chọn phải đã cài đặt uv.

Môi trường bao gồm ba phần:

• Các công cụ và thư viện hệ thống trong image, chẳng hạn như ffmpeg hoặc bộ công cụ CUDA, có sẵn cho Job theo cấu hình của image.
• Các gói Python được cài đặt trong image thuộc về môi trường Python hiện có của nó.
• Các phụ thuộc của script. Với tiêu đề phụ thuộc inline, uv cài đặt các gói Python của bạn trong một môi trường cô lập. Các gói đã được cài đặt sẵn trong image sẽ không tự động khả dụng.

Ví dụ, một script vLLM có thể cần một image chứa công cụ CUDA trong khi vẫn sử dụng uv để cài đặt các phụ thuộc Python đã khai báo của nó. Công cụ hệ thống vẫn phải tương thích với các gói mà uv cài đặt.

Nếu bạn muốn sử dụng trực tiếp PyTorch, TRL hoặc vLLM đã cài đặt sẵn trong image, hãy dùng hf jobs run. Nếu bạn cũng cần uv để cài đặt các phụ thuộc bổ sung, xem Tái sử dụng các gói của image và thêm phụ thuộc với uv.

Tự xây dựng hình ảnh của bạn với một Docker Space

Một Docker Space có thể xây dựng và lưu trữ một image chứa các công cụ mà tác vụ của bạn cần, bao gồm cả các script riêng của bạn, và image có thể là private mà không cần tài khoản registry. Ví dụ, thêm FFmpeg vào một image Python để chuẩn bị môi trường cho việc xử lý âm thanh hoặc video.

Tạo một Docker Space và thêm Dockerfile này vào thư mục gốc của kho lưu trữ của nó:

FROM python:3.12-slim-bookworm

# Install FFmpeg for audio and video processing.
RUN apt-get update \
    && apt-get install -y --no-install-recommends ffmpeg \
    && rm -rf /var/lib/apt/lists/*

# Match the non-root user ID used by Docker Spaces.
RUN useradd --create-home --uid 1000 user
USER user

# Check that FFmpeg is available.
CMD ["ffmpeg", "-version"]

FROM cung cấp Python. FFmpeg không có sẵn trong ảnh cơ sở này, nên RUN cài đặt nó vào lúc build. useradd tạo một người dùng có thư mục home và UID 1000, khớp với Docker Spaces; USER chạy các lệnh với tư cách người dùng đó. CMD đặt lệnh mặc định, ở đây là kiểm tra việc cài đặt FFmpeg.

Commit tệp và chờ cho đến khi log build của Space hiển thị rằng image đã được push. Sau đó, truyền URL của Space vào vị trí mà bạn thường đặt tên image, thay YOUR_USERNAME/video-tools bằng ID Space của bạn:

hf jobs run --flavor cpu-basic --timeout 5m \
    hf.co/spaces/YOUR_USERNAME/video-tools -- ffmpeg -version

Phiên bản sẽ hiển thị trong log của Job. Cung cấp một lệnh khác sau URL của Space để sử dụng FFmpeg hoặc Python cho tác vụ của bạn. Để bao gồm script riêng của bạn trong image, thêm một dòng như COPY --chown=user:user process.py /app/process.py vào Dockerfile và chạy python /app/process.py. Xem file đầu vào và đầu ra để gắn (mount) dữ liệu và lưu kết quả.

Ví dụ này in ra phiên bản rồi thoát, do đó Space sẽ hiển thị lỗi runtime sau khi build. Điều này không sao: Jobs chỉ cần image đã build, không cần một Space đang chạy.

Ảnh đã được xây dựng của một Space không được đảm bảo là luôn có thể kéo (pull) được. Nó có thể bị mất do bảo trì registry hoặc do di chuyển vùng. Nếu một Job báo rằng không tìm thấy ảnh, hãy khởi động lại (factory reboot) Space để xây dựng lại nó. Các Job luôn sử dụng bản xây dựng mới nhất, do đó một commit mới cũng sẽ thay thế ảnh.

Hình ảnh minh họa

Hình ảnh trong Registry được duy trì bởi nhà phát hành và có thể được cố định vào một tag cụ thể.

Sử dụng hf jobs run để chạy các lệnh với các gói đã cài đặt trong image. Đối với hf jobs uv run, hãy kiểm tra xem image đã cài đặt uv chưa và làm theo hướng dẫn về môi trường ở trên. Xem Ví dụ & Hướng dẫn để tìm các tác vụ cần chạy và điều chỉnh cho phù hợp.

Tái sử dụng các gói của hình ảnh và thêm các phụ thuộc bằng uv

Framework images cung cấp các gói đã cài đặt sẵn, có thể chậm hoặc khó để build, chẳng hạn như PyTorch, vLLM và các phần mở rộng CUDA của chúng. Bạn vẫn có thể cần thêm các gói Python khác cho script của mình — ví dụ, để tải một định dạng dữ liệu cụ thể hoặc theo dõi các thí nghiệm.

Bạn có thể tái sử dụng bộ cài đặt có sẵn trong ảnh (image) trong khi dùng uv để cài đặt các gói bổ sung. Khai báo các gói bổ sung trong phần phụ thuộc # /// script của script, sau đó trỏ uv đến trình thông dịch của ảnh và thêm site-packages của nó vào đường dẫn import:

hf jobs uv run \
    --image vllm/vllm-openai \
    --flavor l4x4 \
    --python /usr/bin/python3 \
    -e PYTHONPATH=/usr/local/lib/python3.12/dist-packages \
    -s HF_TOKEN \
    generate-responses.py

• --python tạo môi trường uv với trình thông dịch của image, khớp với phiên bản Python được sử dụng bởi các phần mở rộng đã biên dịch của nó. Nó không tự động phơi bày các gói của image.
• -e PYTHONPATH=... khiến import vllm trỏ đến bản build được xây dựng sẵn trong image cho lần chạy đó.
• Cắt giảm các phụ thuộc trong # /// script của bạn xuống những gì mà image thiếu. PYTHONPATH được tìm kiếm trước môi trường của uv, do đó image sẽ che khuất bất kỳ thứ gì mà header của bạn khai báo cho cùng một package — bao gồm cả một phiên bản mới hơn mà bạn đã cố định. Các phụ thuộc mà bạn giữ lại vẫn có thể kéo theo những package đó một cách gián tiếp; uv không sử dụng PYTHONPATH để đáp ứng việc phân giải phụ thuộc.

Đường dẫn khác nhau cho từng hình ảnh, vì vậy hãy kiểm tra chúng trên cpu-basic thay vì hardcode:

hf jobs run --flavor cpu-basic vllm/vllm-openai bash -c 'which python3; which uv; python3 -m pip show vllm | grep Location'

/usr/bin/python3                              # pass to --python
/usr/local/bin/uv                             # uv is present, so `uv run` works
Location: /usr/local/lib/python3.12/dist-packages   # pass to PYTHONPATH

Thay vllm bằng thư viện bạn đang tái sử dụng. Bố cục có thể khác nhau — vllm/vllm-openai và lmsysorg/sglang dùng dist-packages của hệ thống ở trên, unsloth/unsloth dùng virtualenv (/opt/venv/...), còn huggingface/trl dùng conda (/opt/conda/lib/python3.11/site-packages, kế thừa từ pytorch/pytorch).

Điều này chọn các bản build của image cho các lệnh import, chứ không phải cho trình phân giải phụ thuộc của uv. Việc cắt bớt phần header có thể giảm các lần cài đặt trùng lặp, nhưng không đảm bảo chúng sẽ bị loại bỏ hoàn toàn. Lệnh uv run --system-site-packages có thể bỏ qua bước PYTHONPATH đã được yêu cầu ở upstream.

Đối với hình ảnh huggingface/trl, các đường dẫn tương ứng cho trình thông dịch và gói là:

hf jobs uv run \
    --image huggingface/trl \
    --flavor a100-large \
    --python /opt/conda/bin/python3 \
    -e PYTHONPATH=/opt/conda/lib/python3.11/site-packages \
    -s HF_TOKEN \
    train.py

Các lệnh này sử dụng generate-responses.py và train.py làm tên cho các script của bạn.

Xử lý sự cố

Sử dụng hình ảnh framework cho các thư viện GPU

Một số thư viện GPU cần thêm các công cụ hệ thống, chẳng hạn như trình biên dịch CUDA (nvcc), NCCL hoặc cuDNN. Việc cài đặt các gói Python của chúng không đảm bảo rằng image chứa đầy đủ mọi công cụ cần thiết. Ví dụ, sampler của FlashInfer có thể gặp lỗi khi cố gắng biên dịch một kernel trong image không có CUDA toolkit:

RuntimeError: Could not find nvcc and default cuda_home='/usr/local/cuda' doesn't exist

Việc truyền một hình ảnh framework có chứa các công cụ CUDA cần thiết sẽ khắc phục lỗi thiếu bộ công cụ này:

hf jobs uv run --image vllm/vllm-openai --flavor l4x4 -s HF_TOKEN generate-responses.py

uv vẫn phân giải và cài đặt các phụ thuộc của script của bạn một cách riêng biệt. Ảnh cung cấp các công cụ hệ thống, nhưng không đảm bảo rằng các gói Python đã được phân giải tương thích với chúng.