Tạo một phần mở rộng CLI

CLI hf hỗ trợ các phần mở rộng, là các lệnh tùy chỉnh do cộng đồng cung cấp, được tích hợp liền mạch vào CLI. Các phần mở rộng được lưu trữ dưới dạng các kho GitHub công khai và có thể được cài đặt bằng một lệnh duy nhất. Sau khi cài đặt, chúng xuất hiện như các lệnh cấp cao của hf, tương tự như các lệnh tích hợp sẵn.

Hệ thống này được lấy cảm hứng từ mở rộng của GitHub CLI. Trong hướng dẫn này, bạn sẽ học cách tạo mở rộng của riêng mình, phát hành nó và giúp người dùng dễ dàng tìm thấy.

Để xem tài liệu dành cho người dùng về việc cài đặt và quản lý các phần mở rộng, hãy xem tham chiếu CLI cho hf extensions.

Tổng quan

Có hai loại phần mở rộng:

1. Mở rộng script shell: một tệp thực thi duy nhất (script bash, binary đã biên dịch, v.v.) được đặt ở gốc của kho.
2. Mở rộng Python: một gói Python tiêu chuẩn có pyproject.toml. Được cài đặt trong môi trường ảo cách ly để các phụ thuộc không xung đột với hệ thống của người dùng.

Cả hai loại đều chia sẻ cùng các quy ước:

• Kho lưu trữ GitHub phải được đặt tên là hf-<name> (ví dụ: hf-claude, hf-mem).
• Sau khi cài đặt, người dùng chạy tiện ích mở rộng bằng hf <name> (ví dụ: hf claude).
• Phần mở rộng được liệt kê trong hf --help dưới mục “Extension commands”.

Khi người dùng chạy hf extensions install [OWNER/]hf-<name>, hệ thống trước tiên tìm kiếm tệp binary/script có tên hf-<name> ở gốc repository. Nếu tìm thấy, nó sẽ cài đặt dưới dạng extension shell script. Nếu không, nó sẽ chuyển sang cài đặt repository như một gói Python.

Tạo một phần mở rộng script shell

Mở rộng script shell là loại đơn giản nhất. Bạn chỉ cần một kho GitHub có chứa tệp thực thi đặt tên là hf-<name> ở thư mục gốc.

Các phần mở rộng script shell không được hỗ trợ trên Windows. Nếu phần mở rộng của bạn phải hoạt động trên Windows, hãy tạo nó thành phần mở rộng Python thay thế.

Ví dụ tối giản

Tạo một kho có tên hf-hello trên GitHub với một tệp duy nhất:

hf-hello (ở thư mục gốc của kho):

#!/usr/bin/env bash
set -euo pipefail

echo "Hello from hf-hello extension!"
echo "Arguments: $@"

Xong rồi! Người dùng giờ có thể cài đặt và chạy nó:

>>> hf extensions install <your-username>/hf-hello
>>> hf hello
Hello from hf-hello extension!
Arguments:

Mẹo cho các phần mở rộng của script shell

• Luôn bắt đầu bằng shebang (#!/usr/bin/env bash) và set -euo pipefail để đảm bảo an toàn.
• Script nhận tất cả các đối số bổ sung do người dùng truyền vào. Ví dụ, hf hello --name world sẽ truyền --name world cho script.
• Bạn có thể truy cập token Hugging Face của người dùng qua biến môi trường HF_TOKEN nếu họ đã đăng nhập.
• Thêm manifest.json ở gốc kho để cung cấp mô tả (xem Thêm mô tả).
• Các phụ thuộc bên ngoài (ví dụ: fzf, jq, v.v.) sẽ không được cài đặt tự động cùng với extension của bạn. Hãy kiểm tra các công cụ cần thiết ở đầu script và xử lý lỗi một cách thân thiện với thông báo lỗi hữu ích nếu chúng bị thiếu.

Một ví dụ thực tế, xem hanouticelina/hf-claude — một phần mở rộng shell script khởi chạy Claude Code với HF Inference Providers.

Tạo một phần mở rộng Python

Mở rộng Python là các gói Python đầy đủ được cài đặt trong môi trường ảo cách ly. Đây là lựa chọn tốt nhất khi mở rộng của bạn có các phụ thuộc Python hoặc logic phức tạp hơn.

Ví dụ tối giản

Tạo một kho có tên hf-hello trên GitHub với cấu trúc này:

hf-hello/
├── pyproject.toml
└── src/
    └── hf_hello/
        ├── __init__.py
        └── cli.py

pyproject.toml:

[build-system]
requires = ["setuptools>=64"]
build-backend = "setuptools.backends._legacy:_Backend"

[project]
name = "hf-hello"
version = "0.1.0"
description = "A hello-world hf CLI extension"
requires-python = ">=3.10"

[project.scripts]
hf-hello = "hf_hello.cli:main"

src/hf_hello/cli.py:

import sys

def main():
    print("Hello from hf-hello extension!")
    print(f"Arguments: {sys.argv[1:]}")

if __name__ == "__main__":
    main()

Phần quan trọng là điểm vào [project.scripts]: nó phải được đặt tên là hf-<name> (ở đây là hf-hello). Đây là cách CLI hf phát hiện và thực thi phần mở rộng của bạn.

Người dùng cài đặt và chạy theo cách tương tự:

>>> hf extensions install <your-username>/hf-hello
>>> hf hello
Hello from hf-hello extension!
Arguments: []

Cách các phần mở rộng Python được cài đặt

Khi một người dùng cài đặt một phần mở rộng Python, các bước sau sẽ diễn ra:

1. Một môi trường ảo được tạo tại ~/.local/share/hf/extensions/hf-<name>/venv/.
2. Gói của bạn được cài đặt thông qua pip install từ kho lưu trữ GitHub.
3. Hệ thống xác minh rằng một script console hf-<name> đã được tạo trong venv.

Điều này có nghĩa là các phụ thuộc của phần mở rộng của bạn được cách ly hoàn toàn — chúng sẽ không xung đột với các gói Python khác của người dùng.

Một ví dụ thực tế là alvarobartt/hf-mem — một phần mở rộng Python ước tính yêu cầu bộ nhớ suy luận cho các mô hình HF.

Thêm mô tả

Mô tả giúp người dùng hiểu phần mở rộng của bạn làm gì. Nó xuất hiện trong hf extensions list và trong hf --help.

Hệ thống tìm kiếm mô tả theo thứ tự sau:

1. manifest.json ở gốc kho:

{
    "description": "A short description of what your extension does"
}

2. pyproject.toml trường description (cho các phần mở rộng Python):

[project]
description = "A short description of what your extension does"

3. Mô tả kho GitHub (trường “About” trên trang kho).

Đối với các phần mở rộng Python, việc đặt description trong pyproject.toml là cách tiếp cận tự nhiên nhất. Đối với các phần mở rộng shell script, hãy sử dụng tệp manifest.json hoặc đặt mô tả cho kho GitHub.

Làm cho phần mở rộng của bạn dễ được tìm thấy

Để giúp người dùng tìm thấy phần mở rộng của bạn, hãy thêm chủ đề hf-extension vào kho GitHub của bạn:

1. Truy cập kho lưu trữ của bạn trên GitHub.
2. Nhấp vào biểu tượng bánh răng bên cạnh “About” trên thanh bên phải.
3. Trong mục “Topics”, thêm hf-extension.

Đây là một quy ước của cộng đồng giúp dễ dàng duyệt qua tất cả các phần mở rộng có sẵn trên trang chủ đề hf-extension.

Người dùng sau đó có thể khám phá phần mở rộng của bạn trực tiếp từ CLI bằng hf extensions search, liệt kê tất cả các kho GitHub được gắn thẻ với chủ đề hf-extension, sắp xếp theo số sao:

>>> hf extensions search
NAME   REPO                    STARS DESCRIPTION                         INSTALLED
------ ----------------------- ----- ----------------------------------- ---------
claude hanouticelina/hf-claude     2 Extension for `hf` CLI to launch... yes
agents hanouticelina/hf-agents       HF extension to run local coding...

Cột INSTALLED hiển thị các phần mở rộng đã được cài đặt cục bộ. Từ đó, người dùng có thể cài đặt bất kỳ phần mở rộng nào được liệt kê bằng hf extensions install <repo>.

Kiểm tra phần mở rộng của bạn

Trong quá trình phát triển, bạn có thể cài đặt phần mở rộng của mình trực tiếp từ kho GitHub của bạn:

# Install from your repo
>>> hf extensions install <your-username>/hf-<name>

# Run it
>>> hf <name>

# Reinstall after making changes (push to GitHub first)
>>> hf extensions install <your-username>/hf-<name> --force

# Update to the latest version (only if a newer commit is available)
>>> hf extensions update <name>

# List installed extensions
>>> hf extensions list

# Remove when done
>>> hf extensions remove <name>

Sử dụng --force để ghi đè lên phiên bản đã cài đặt trước đó khi kiểm tra các bản cập nhật.

Cập nhật các phần mở rộng đã cài đặt

Sau khi cài đặt một phần mở rộng, bạn có thể cập nhật nó lên phiên bản mới nhất được phát hành trên GitHub:

# Update a single extension (accepts `<name>`, `hf-<name>` or `OWNER/hf-<name>`)
>>> hf extensions update hf-claude

# Check every installed extension and update the outdated ones
>>> hf extensions update

hf extensions update chỉ cập nhật các extension đã được cài đặt. Nếu extension chưa được cài đặt, một lỗi sẽ được ném ra. Các extension đã ở phiên bản mới nhất sẽ bị bỏ qua.

Phiên bản của một extension là commit mà nó được cài đặt từ đó, hiển thị dưới dạng SHA ngắn trong cột VERSION của hf extensions list. Cột LATEST được kiểm tra khi không có commit mới hơn nào khả dụng trên GitHub, và việc chạy một extension cũ sẽ in ra một gợi ý đề xuất hf extensions update <name>. Để nằm trong giới hạn tần suất yêu cầu (rate limits) của GitHub cho các yêu cầu không xác thực, hf chỉ tra cứu commit mới nhất của mỗi extension tối đa một lần mỗi ngày. Đặt HF_HUB_DISABLE_UPDATE_CHECK=1 để tắt các kiểm tra này.

Nếu một phần mở rộng Python ngừng hoạt động vì phiên bản Python được dùng để cài đặt nó đã bị xóa (ví dụ: sau khi nâng cấp Homebrew), hf extensions update <name> sẽ tạo lại môi trường ảo của nó.

Quy tắc đặt tên

Tên phần mở rộng phải tuân theo các quy tắc sau:

• Kho GitHub phải được đặt tên là hf-<name>.
• <name> phải bắt đầu bằng một chữ cái hoặc chữ số.
• <name> có thể chứa chữ cái, chữ số, ., _ và -.
• <name> không được xung đột với lệnh hf tích hợp (ví dụ: download, upload, auth).

Khi cài đặt, người dùng có thể chỉ định đầy đủ OWNER/hf-<name> hoặc chỉ hf-<name> (mặc định là tổ chức huggingface).

Các phần mở rộng hiện có

Dưới đây là một số phần mở rộng của cộng đồng mà bạn có thể tham khảo: