ShadowPEFT

ShadowPEFT bổ sung cho một mô hình decoder-only cơ sở đã đóng băng một mạng shadow nhẹ, có thể huấn luyện trước chạy song song với backbone. Một backbone shadow nhỏ tạo ra trạng thái shadow ban đầu s^(0), sau đó trạng thái này đi theo vòng lặp decoder của mô hình cơ sở: tại mỗi khối được nhắm tới, sự chênh lệch giữa các trạng thái ẩn của mô hình cơ sở và trạng thái shadow được tiêm ngược vào đầu vào của khối (một hiệu chỉnh hạng thấp), và trạng thái shadow được cập nhật bằng một cập nhật residual có cổng được tính từ đầu ra của khối. Chỉ các thành phần shadow được huấn luyện; mô hình cơ sở vẫn giữ nguyên trạng thái đóng băng.

Input
  ├──► Shadow backbone (small, trainable) ──► s^(0)
  └──► Base model (frozen, large)
         block_0 ◄── inject(h, s) ─► h_0 ──► update ─► s_1
         block_1 ◄── inject(h, s) ─► h_1 ──► update ─► s_2
         ...                       (the (hidden, shadow) pair rides the loop together)

Vì quá trình thích ứng là một quỹ đạo phụ thuộc vào đầu vào trong không gian lớp (trạng thái bóng tiến hóa cùng với dữ liệu) chứ không phải là một delta tĩnh trong không gian trọng số, ShadowPEFT không thể được hợp nhất vào trọng số gốc. Việc gọi merge, merge_adapter hoặc merge_and_unload sẽ gây ra một lỗi rõ ràng. Đối với các mô hình ngôn ngữ Transformers, bạn có thể lấy mạng bóng nhẹ độc lập bằng cách sử dụng model.base_model.unload_shadow(), hàm này trả về một DetachedShadowModel độc lập. Việc unloading độc lập không được hỗ trợ cho các mô hình Diffusers vì việc tái tạo một denoiser hoàn chỉnh phụ thuộc vào kiến trúc cụ thể.

Việc thêm nhiều adapter, chuyển đổi giữa chúng bằng set_adapter, xóa chúng, và bật/tắt chúng đều hoạt động giống như với các phương pháp PEFT khác. Chỉ có một adapter có thể hoạt động tại một thời điểm, vì trạng thái bóng (shadow state) là một quỹ đạo duy nhất xuyên qua mạng.

Khung xương bóng (shadow backbone) có thể được xây dựng theo hai cách, được điều khiển bởi ShadowConfig.shadow_model:

• "mirror" (mặc định): một backbone bóng nhỏ hơn được tạo ra tự động. Các mô hình ngôn ngữ sử dụng một bản sao rút gọn của kiến trúc cơ sở. Các kiến trúc Diffusers có backend được đăng ký sẽ sử dụng một mô hình tương tự kiến trúc rút gọn được khởi tạo từ các trọng số cơ sở được chọn; các kiến trúc tương thích không có backend sẽ chuyển sang sử dụng MLP dư theo từng token. Khi kích thước ẩn của bản bóng khác với kích thước của bản cơ sở, một phép chiếu đã được huấn luyện sẽ cầu nối khoảng cách đó.
• một id mô hình hoặc đường dẫn cục bộ: backbone được tải dưới dạng một mô hình pre-trained nhỏ hơn. Các mô hình Transformers sử dụng AutoModel; các backend Diffusers đã đăng ký định nghĩa việc tải checkpoint tương thích của riêng chúng.

Hỗ trợ Diffusers nhận diện kiến trúc được chọn tự động từ lớp mô hình. Flux2 hiện có một backend đã đăng ký; các mô hình Diffusers dựa trên transformer tương thích khác sử dụng phương án dự phòng MLP chung. Việc gọi unload_shadow() độc lập vẫn chưa được hỗ trợ cho tất cả các mô hình Diffusers vì việc tái tạo một denoiser hoàn chỉnh phụ thuộc vào kiến trúc cụ thể.

So với các phương pháp kiểu LoRA, ShadowPEFT bổ sung thêm tham số và tính toán (chạy một mạng song song và bao bọc toàn bộ các khối decoder), nhưng adapter là một mạng tự chứa có thể được huấn luyện tập trung, tái sử dụng giữa các tác vụ và khởi tạo từ một mô hình nhỏ đã được huấn luyện trước. Một tổn thất phụ tùy chọn (auxiliary_loss_weight) áp dụng đầu tác vụ lên trạng thái bóng ban đầu s^(0) và cộng nó vào tổn thất tác vụ, khuyến khích đường bóng có thể tách rời giải quyết tác vụ một cách độc lập. Đối với LM nhân quả, đầu output cơ sở được tái sử dụng; bao gồm "lm_head" trong modules_to_save để huấn luyện và lưu trữ nó thông qua cơ chế PEFT tiêu chuẩn.

Bộ đệm KV

ShadowPEFT hỗ trợ giải mã tăng dần với bộ đệm KV dual: một cho mô hình cơ sở đóng băng và một cho khung xương bóng. Việc tiêm/cập nhật là cục bộ theo token, nên một token mới chỉ cần trạng thái bóng riêng của nó s; tính nhân quả giữ cho các khóa/giá trị tiền tố cơ sở (được tính dưới chế độ tiêm) vẫn hợp lệ. Đối tượng ghép đôi là ShadowCache, được trả về dưới dạng past_key_values khi use_cache=True. Bạn có thể truyền use_cache=True vào generate() như bình thường.

out = model.generate(input_ids, max_new_tokens=32)  # dual KV cache enabled by default
# or explicitly:
out = model.generate(input_ids, use_cache=True, max_new_tokens=32)

use_cache=False vẫn hoạt động và xử lý lại toàn bộ chuỗi ở mỗi bước (hữu ích cho việc gỡ lỗi).

Cách sử dụng

from transformers import AutoModelForCausalLM
from peft import ShadowConfig, get_peft_model

model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen3-0.6B")
config = ShadowConfig(r=8, shadow_num_hidden_layers=1, task_type="CAUSAL_LM")
model = get_peft_model(model, config)
model.print_healthcheck()

out = model.generate(input_ids, max_new_tokens=32)

Để khởi tạo shadow backbone từ một mô hình pre-trained nhỏ hơn, hãy truyền id hoặc đường dẫn của nó vào shadow_model:

config = ShadowConfig(shadow_model="Qwen/Qwen3-0.6B", task_type="CAUSAL_LM")
model = get_peft_model(base_model, config)

Đánh giá đường dẫn bóng

Mặc định, đầu ra của mô hình (logits) là mô hình cơ bản đã thích ứng bóng: các hiệu chỉnh bóng được tiêm vào trạng thái ẩn của mô hình cơ bản ở mỗi lớp, do đó logits đã phản ánh ShadowPEFT (dùng model.disable_adapter() để lấy mô hình cơ bản thuần túy nhằm so sánh). Mất phụ trợ ngoài ra còn huấn luyện đường bóng để tự giải quyết tác vụ.

Để đánh giá mạng bóng độc lập cho một mô hình ngôn ngữ Transformers (mô hình nhẹ, có thể tách rời — tương đương của merge_and_unload trong ShadowPEFT), hãy sử dụng unload_shadow(). Phương thức này trả về head(projection(backbone(x))) dưới dạng một mô hình tác vụ thông thường mà bạn có thể đánh giá như bất kỳ mô hình nào khác: đối với tác vụ causal-LM, nó là một causal LM có khả năng sinh (hỗ trợ generate() và bộ nhớ đệm KV), còn đối với tác vụ phân loại chuỗi, nó sẽ gom token cuối cùng và trả về logits của các lớp. Việc gọi phương thức này cho một mô hình Diffusers sẽ gây ra NotImplementedError.

shadow = model.base_model.unload_shadow()  # a DetachedShadowModel (a PreTrainedModel)
shadow.eval()
# causal LM:
out = shadow.generate(input_ids, max_new_tokens=32)
# sequence classification:
logits = shadow(input_ids=input_ids, attention_mask=attention_mask).logits  # (batch, num_labels)

Mặc định (copy=False), model được trả về chia sẻ các module của nó với model PEFT, và một shadow backbone chia sẻ các input embeddings gốc đã đóng băng sẽ tiếp cận chúng thông qua một tham chiếu không phải là submodule. Điều này không thành vấn đề cho việc đánh giá, nhưng nó có nghĩa là save_pretrained sẽ ghi một checkpoint không có bảng embedding. Truyền copy=True khi bạn muốn lưu hoặc đẩy model độc lập:

shadow = model.base_model.unload_shadow(copy=True)
shadow.save_pretrained("standalone-shadow")

API

ShadowConfig

ShadowModel

ShadowCache