Transformers documentation
Trình xuất
Trình xuất
Các backend xuất mới có thể được thêm vào Transformers bằng cách kế thừa HfExporter và đăng ký nó với register_backend().
Tìm hiểu cách sử dụng các trình xuất có sẵn trong hướng dẫn Exporters.
AutoHfExporter
Lớp Auto-HF exporter chịu trách nhiệm tự động khởi tạo thành HfExporter phù hợp dựa trên ExportConfig được cung cấp.
AutoExportConfig
Lớp cấu hình xuất Auto-HF chịu trách nhiệm tự động chuyển hướng đến cấu hình xuất chính xác dựa trên cấu hình xuất được lưu trong một từ điển.
register_backend
transformers.exporters.register_backend
< source >( exporter: type[HfExporter]runner: type[ModelRunner] | None = None )
Đăng ký một exporter, cùng với config_class của nó, dưới export_format của nó, và runner thực hiện các xuất của nó,
để các lớp auto có thể tìm thấy chúng.
HfExporter
Lớp trừu tượng cơ sở cho tất cả các trình xuất của Transformers.
Để thêm một backend, hãy kế thừa và triển khai ~HfExporter.export_program để trace một graph, cùng với ~HfExporter.save_program / ~HfExporter.load_program để ghi ra và đọc lại. Các phương thức công khai ~HfExporter.export và ~HfExporter.export_for_generation sẽ xây dựng một ExportedModel dựa trên chúng.
export
< source >( model: PreTrainedModelsample_inputs: MutableMapping[str, torch.Tensor | Cache]config: ExportConfigMixin | dict[str, Any] ) → ExportedModel
Trả về
ExportedModel
Một thành phần "model" duy nhất; chương trình của backend là .program, và
save_pretrained sẽ ghi nó cùng với metadata và cấu hình model.
Xuất mô hình dưới dạng một đồ thị duy nhất.
Nhận cùng các tham số forward như ~HfExporter.export_program.
export_for_generation
< source >( model: PreTrainedModelsample_inputs: MutableMapping[str, torch.Tensor | Cache]config: ExportConfigMixin | dict[str, ExportConfigMixin]generation_config: GenerationConfig | None = Nonemulti_token_decode: bool = False ) → ExportedModel
Tham số
- model (PreTrainedModel) —
Mô hình sinh cần xuất. Phải hỗ trợ
model.generate(**sample_inputs). - sample_inputs (
dict[str, torch.Tensor | Cache]) — Generate kwargs — những gì bạn sẽ truyền vàomodel.generate(**sample_inputs)(thường làinput_ids+attention_mask, cùng với các đầu vào đa giác quan nhưpixel_values/input_featurescho các mô hình đa phương tiện). Các forward kwargs cho từng giai đoạn được ghi nhận bên trong. - config (
ExportConfigMixinhoặcdict[str, ExportConfigMixin]) — Cấu hình cụ thể cho backend. Truyền một cấu hình duy nhất để áp dụng cho mọi thành phần, hoặc mộtdictcó khóa là tên thành phần (ví dụ"image_encoder","language_model","lm_head","decode") để ghi đè theo từng thành phần — tất cả tên thành phần phải có mặt trong dict. - generation_config (GenerationConfig, optional) —
Được chuyển tiếp đến capture
generate()(mặc định là của chính model). Truyền một cấu hình cócache_implementation="static"để xuất đối vớiStaticCachecó kích thước cố định. - multi_token_decode (
bool, tùy chọn, mặc định làFalse) — Xác định xem thành phầndecodecó xử lý nhiều token truy vấn cùng lúc — một trục truy vấn động (prefill trên cache trống, hoặc tiếp nối từ quá khứ trong các trường hợp khác) — hay là bước đơn token cổ điển (xem decompose_for_generation()). Chỉ giữ trạng thái động khi xuất với hình dạng động (config.dynamic=True).
Trả về
ExportedModel
Một ExportedComponent cho mỗi giai đoạn, với các khóa giống như trong
decompose_for_generation().
Phân tách một mô hình sinh và xuất từng thành phần một cách độc lập.
Lớp bọc mỏng quanh decompose_for_generation(), gọi ~HfExporter.export_program trên mỗi cặp (submodel, forward_inputs) được trả về. Nếu bạn cần các cặp (submodel, forward_inputs) trung gian (để xác minh, đầu vào tùy chỉnh, bỏ qua một giai đoạn, …), hãy gọi trực tiếp decompose_for_generation().
export_program
< source >( model: PreTrainedModelsample_inputs: MutableMapping[str, torch.Tensor | Cache]config: ExportConfigMixin ) → tuple[Any, ExportMetadata]
Tham số
- model (PreTrainedModel) — Mô hình cần xuất.
- sample_inputs (
dict[str, torch.Tensor | Cache]) — Forward kwargs — những gì bạn sẽ truyền vàomodel(**sample_inputs). Chúng được sử dụng trực tiếp làm đầu vào mẫu trong quá trình tracing. Đối với xuất khẩu bước giải mã tự hồi quy, điều này có nghĩa là bạn cần bao gồmpast_key_values,cache_position, v.v. Nếu bạn chỉ có các đầu vào kiểu generation, hãy sử dụng~HfExporter.export_for_generationthay thế — nó sẽ chạymodel.generatecho bạn và xuất khẩu từng giai đoạn. - config (
ExportConfigMixin) — Cấu hình cụ thể cho backend.
Trả về
tuple[Any, ExportMetadata]
Đối tượng chương trình của backend (ExportedProgram, onnx_ir.Model,
ExecutorchProgramManager, openvino.Model) và các metadata được ghi lại trong quá trình tracing
(build_export_metadata()), được trả về riêng biệt vì chỉ một số định dạng mới có thể
chứa chúng.
Truy vết một đồ thị. Điểm mở rộng backend, kết hợp với ~HfExporter.save_program.
Đọc lại một chương trình được viết bởi ~HfExporter.save_program. Nó có thể khác với những gì ~HfExporter.export_program đã trả về: một Program thời gian chạy cho ExecuTorch, mà ExecutorchProgramManager của nó không thể được xây dựng lại từ tệp.
Các tệp mà ~HfExporter.save_program ghi cho một chương trình được lưu dưới tên filename: chính tệp đó, cùng với bất kỳ tệp nào khác mà định dạng giữ bên cạnh nó (trọng số, dữ liệu bên ngoài).
Viết một chương trình được trả về bởi ~HfExporter.export_program vào path, theo định dạng tệp của backend.
Kiểm tra required_packages đã được cài đặt và cảnh báo khi có sự lệch phiên bản so với tested_versions.
ExportedModel
lớp transformers.exporters.ExportedModel
< source >( components: dict[str, ExportedComponent]export_format: ExportFormat | strconfig: PreTrainedConfig | None = Nonegeneration_config: GenerationConfig | None = None )
Một mô hình đã xuất: các đồ thị của nó (components, {name: ExportedComponent}) và các cấu hình mà chúng được theo dõi, được gọi theo cách bạn sẽ gọi mô hình mà chúng bắt nguồn từ đó.
~HfExporter.export tạo ra một thành phần "model" duy nhất, có chương trình là .program; ~HfExporter.export_for_generation tạo ra một thành phần cho mỗi giai đoạn generation.
>>> exported = OnnxExporter().export(model, inputs, OnnxConfig(dynamic=True))
>>> exported.save_pretrained("exported")
>>> outputs = ExportedModel.from_pretrained("exported", device="cuda")(**inputs)
>>> outputs.last_hidden_stateChạy xuất đơn đồ thị, trả về kết quả mà mô hình nguồn trả về. Các kwargs mà quá trình xuất không được trace sẽ bị loại bỏ, do đó toàn bộ đầu ra của một processor có thể được truyền vào. share_inputs và share_outputs được chuyển đến runner (xem ModelRunner.__call__): với share_outputs, các đầu ra sẽ hợp lệ cho đến lần gọi tiếp theo.
Chương trình của chính backend, dành cho xuất một đồ thị đơn.
Tải các chương trình lên runtime của backend, trên device (mặc định của backend khi là None). runner_kwargs được truyền đến runner của backend: providers và session_options cho ONNX Runtime, config (các thuộc tính biên dịch) và torch_threads (chia CPU với công việc của torch xung quanh mô hình) cho OpenVINO.
save_pretrained
< source >( save_directory: str | Pathpush_to_hub: bool = False**kwargs )
Tham số
- save_directory (
strhoặcPath) — Thư mục để ghi vào, sẽ được tạo nếu chưa tồn tại. - push_to_hub (
bool, tùy chọn, mặc định làFalse) — Có nên tải các tệp đã lưu lên Hub không, đếnrepo_id(mặc định là tên củasave_directorytrong namespace của bạn). - kwargs (
dict[str, Any], tùy chọn) — Được truyền cho việc tải lên Hub:repo_id,commit_message,token,private, …
Viết các thành phần (mỗi thành phần một tệp), các cấu hình và một tệp manifest ghi tên tệp của từng thành phần cùng với các metadata được ghi lại khi theo dõi (tracing) chúng. ~ExportedModel.from_pretrained sẽ nạp lại chúng.
from_pretrained
< source >( pretrained_model_name_or_path: str | Pathdevice = Nonecache_dir: str | os.PathLike | None = Noneforce_download: bool = Falselocal_files_only: bool = Falsetoken: str | bool | None = Nonerevision: str = 'main'subfolder: str = ''trust_remote_code: bool = False**runner_kwargs )
Tham số
- pretrained_model_name_or_path (
strhoặcPath) — Một thư mục cục bộ, hoặc một id kho trên Hub. Từ Hub, chỉ các tệp được nêu tên trong manifest mới được tải xuống, do đó một bản xuất có thể nằm cạnh trọng số của chính mô hình. - device (
strhoặctorch.device, tùy chọn) — Nơi để chạy (mặc định của backend khiNone). - cache_dir (
Union[str, os.PathLike], tùy chọn) — Đường dẫn đến thư mục mà cấu hình mô hình được huấn luyện trước đã tải xuống sẽ được lưu đệm nếu không sử dụng bộ lưu đệm tiêu chuẩn. - force_download (
bool, tùy chọn, mặc định làFalse) — Có nên buộc tải lại (re-download) trọng số mô hình và các tệp cấu hình, ghi đè lên các phiên bản đã được lưu trong bộ nhớ đệm nếu chúng tồn tại hay không. - local_files_only (
bool, tùy chọn, mặc định làFalse) — Có chỉ xem các tệp cục bộ hay không (tức là không cố gắng tải xuống mô hình). - token (
strhoặcbool, tùy chọn) — Token được sử dụng làm HTTP bearer authorization cho các tệp từ xa. NếuTrue, hoặc không được chỉ định, sẽ sử dụng token được tạo khi chạyhf auth login(được lưu trong~/.huggingface). - revision (
str, tuỳ chọn, mặc định là"main") — Phiên bản mô hình cụ thể cần sử dụng. Nó có thể là tên nhánh, tên tag hoặc id commit, vì chúng tôi sử dụng hệ thống dựa trên git để lưu trữ mô hình và các artifact khác trên huggingface.co, do đórevisioncó thể là bất kỳ định danh nào được git cho phép.Để kiểm tra một pull request bạn đã tạo trên Hub, bạn có thể truyền
revision="refs/pr/<pr_number>". - subfolder (
str, tùy chọn, mặc định là"") — Trong trường hợp các tệp liên quan nằm trong một thư mục con của kho mô hình trên huggingface.co, bạn có thể chỉ định tên thư mục ở đây. - trust_remote_code (
bool, tùy chọn, mặc định làFalse) — Có nên nạp cấu hình của một model mà mã của nó nằm trong repo của nó hay không, giống như với from_pretrained(). - runner_kwargs (tùy chọn) —
Các tùy chọn runner của backend, giống như
~ExportedModel.to:providersvàsession_optionscho ONNX Runtime,configvàtorch_threadscho OpenVINO.
Tải những gì ~ExportedModel.save_pretrained đã ghi: mỗi thành phần thông qua ~HfExporter.load_program của backend tương ứng, cùng với metadata của nó và các cấu hình được lưu ngay bên cạnh. Các chương trình được tải lên runtime của backend ngay lập tức, sẵn sàng để chạy.
ExportedComponent
Một đồ thị đã xuất: chương trình của backend, và những gì trình xuất đã ghi lại về nó.
ExportMetadata
lớp transformers.exporters.ExportMetadata
< source >( architecture: str | None = Nonepackages: dict[str, str] = <factory>export_config: dict[str, Any] = <factory>export_dtype: str | None = Noneexport_device: str | None = Nonekwargs: dict[str, dict] = <factory>in_spec: str | None = Noneout_spec: str | None = Nonein_constants: dict[str, Any] = <factory>out_constants: list = <factory> )
Những gì trình xuất ghi lại về một đồ thị (build_export_metadata()).
Xây dựng metadata từ dict đã lưu, bỏ qua các trường mà lớp này không có (được thêm bởi một phiên bản mới hơn).
ModelRunner
Chạy một chương trình đã xuất trên backend của nó: runner(**kwargs) trả về kết quả mà mô hình nguồn trả về.
Một runner cho một chương trình dưới dạng export sẽ trả về nó, hoặc ~HfExporter.load_program sẽ đọc lại nó trên device (mặc định của backend khi là None).
Xây dựng lại các đầu ra của mô hình từ các đầu ra phẳng của chương trình (nằm ở cuối) và các hằng số đã được ghi lại.
DynamoExporter
Trình xuất chuyển đổi PreTrainedModel thành ExportedProgram.
Ví dụ:
>>> from transformers.exporters.exporter_dynamo import DynamoExporter, DynamoConfig
>>> exporter = DynamoExporter()
>>> exported = exporter.export(model, inputs, config=DynamoConfig(dynamic=True))
>>> outputs = exported(**inputs)
>>> exported.save_pretrained("exported") # `model.pt2`, its metadata and the model configexport
< source >( model: PreTrainedModelsample_inputs: MutableMapping[str, torch.Tensor | Cache]config: ExportConfigMixin | dict[str, Any] ) → ExportedModel
Trả về
ExportedModel
Một thành phần "model" duy nhất; chương trình của backend là .program, và
save_pretrained sẽ ghi nó cùng với metadata và cấu hình model.
Xuất mô hình dưới dạng một đồ thị duy nhất.
Nhận cùng các tham số forward như ~HfExporter.export_program.
OnnxExporter
Trình xuất chuyển đổi PreTrainedModel thành đồ thị ONNX (một onnx_ir.Model).
Ví dụ:
>>> from transformers.exporters.exporter_onnx import OnnxExporter, OnnxConfig
>>> exporter = OnnxExporter()
>>> exported = exporter.export(model, inputs, config=OnnxConfig(dynamic=True))
>>> outputs = exported(**inputs) # on ONNX Runtime
>>> onnx_model = exported.program # an `onnx_ir.Model`
>>> exported.save_pretrained("exported") # `model.onnx`, its metadata and the model configexport
< source >( model: PreTrainedModelsample_inputs: MutableMapping[str, torch.Tensor | Cache]config: ExportConfigMixin | dict[str, Any] ) → ExportedModel
Trả về
ExportedModel
Một thành phần "model" duy nhất; chương trình của backend là .program, và
save_pretrained sẽ ghi nó cùng với metadata và cấu hình model.
Xuất mô hình dưới dạng một đồ thị duy nhất.
Nhận cùng các tham số forward như ~HfExporter.export_program.
ExecutorchExporter
Trình xuất chuyển đổi PreTrainedModel thành ExecutorchProgramManager của ExecuTorch.
Ví dụ:
>>> from transformers.exporters.exporter_executorch import ExecutorchExporter, ExecutorchConfig
>>> exporter = ExecutorchExporter()
>>> exported = exporter.export(model, inputs, config=ExecutorchConfig(backend="xnnpack"))
>>> outputs = exported(**inputs) # on the ExecuTorch runtime
>>> exported.save_pretrained("exported") # `model.pte`, its metadata and the model configexport
< source >( model: PreTrainedModelsample_inputs: MutableMapping[str, torch.Tensor | Cache]config: ExportConfigMixin | dict[str, Any] ) → ExportedModel
Trả về
ExportedModel
Một thành phần "model" duy nhất; chương trình của backend là .program, và
save_pretrained sẽ ghi nó cùng với metadata và cấu hình model.
Xuất mô hình dưới dạng một đồ thị duy nhất.
Nhận cùng các tham số forward như ~HfExporter.export_program.
DynamoConfig
lớp transformers.exporters.DynamoConfig
< source >( export_format: ExportFormat = <ExportFormat.DYNAMO: 'dynamo'>dynamic: bool = Falsestrict: bool = Falsedynamic_shapes: dict[str, Any] | None = Noneprefer_deferred_runtime_asserts_over_guards: bool = Falsequantizer: ExportQuantizer | None = None )
Tham số
- dynamic (bool, optional, mặc định là False) — Có xuất với các hình dạng động (symbolic) hay không. Khi True và dynamic_shapes không được đặt, tất cả các chiều tensor sẽ được đặt thành Dim.AUTO một cách tự động.
- strict (bool, tuỳ chọn, mặc định là False) — Có bật chế độ nghiêm ngặt trong torch.export hay không. Chạy quá trình truy vết biểu tượng đầy đủ và bắt được nhiều lỗi hơn, nhưng chậm hơn và dễ thất bại hơn trên các mô hình phức tạp.
- dynamic_shapes (dict[str, Any], optional) — Quy định hình dạng động cụ thể cho từng đầu vào được truyền vào torch.export. Có ưu tiên cao hơn dynamic.
- prefer_deferred_runtime_asserts_over_guards (bool, optional, mặc định là False) —
Khi True, các guard hình dạng phụ thuộc vào dữ liệu sẽ được phát ra dưới dạng runtime asserts trong đồ thị đã xuất thay vì khiến quá trình xuất thất bại tại thời điểm trace nếu guard không được giữ nguyên trên toàn bộ phạm vi hình dạng biểu tượng. Hầu hết các LLM transformer cần đặt giá trị này thành True khi sử dụng các ràng buộc
Dim(min=, max=)chi tiết. Không cần thiết khi dùngdynamic=True/Dim.AUTO, nơitorch.exportsuy luận các quan hệ hình dạng thay vì kiểm chứng chúng với các ràng buộc do người dùng khai báo. - quantizer ([~exporters.quantizers.ExportQuantizer], optional) — Lượng tử hóa sau huấn luyện được áp dụng trong quá trình xuất: [~exporters.quantizers.PT2EQuantizer] hoặc [~exporters.quantizers.NNCFTorchFXQuantizer] trên đồ thị FX cho mọi backend, [~exporters.quantizers.OnnxRuntimeQuantizer] trên mô hình ONNX đã chuyển đổi, hoặc [~exporters.quantizers.NNCFOpenVINOQuantizer] / [~exporters.quantizers.NNCFOnnxQuantizer] trên mô hình OpenVINO / ONNX đã chuyển đổi.
Lớp cấu hình để xuất mô hình thông qua torch.export.
OnnxConfig
lớp transformers.exporters.OnnxConfig
< source >( export_format: ExportFormat = <ExportFormat.ONNX: 'onnx'>dynamic: bool = Falsestrict: bool = Falsedynamic_shapes: dict[str, Any] | None = Noneprefer_deferred_runtime_asserts_over_guards: bool = Falsequantizer: ExportQuantizer | None = Noneopset_version: int | None = Noneoptimize: bool = Trueort_fusions: Literal['cpu', 'cuda', 'webgpu', 'dml'] | None = None )
Tham số
- opset_version (
int, tùy chọn) — Phiên bản opset ONNX cần nhắm tới. Mặc định là phiên bản opset mới nhất được hỗ trợ bởi phiên bảnonnxscriptđã cài đặt. - optimize (
bool, tùy chọn, mặc định làTrue) — Chạy các bước tối ưu hóa củaonnxscript(gấp hằng số, loại bỏ mã chết, …) trên đồ thị đã xuất. Tắt đối với các mô hình gặp lỗi của trình tối ưu hóaonnxscriptở thượng nguồn. - ort_fusions (
str, tùy chọn) — Nối (fuse) đồ thị thành các ops của ONNX Runtime cho execution provider mà nó chạy trên:"cpu","cuda","webgpu"hoặc"dml". Đồ thị đã nối chỉ chạy trên ONNX Runtime. Yêu cầuoptimize=True.
Lớp cấu hình để xuất mô hình sang ONNX thông qua torch.onnx.export.
Kế thừa tất cả các trường từ DynamoConfig (dynamic, strict, dynamic_shapes, prefer_deferred_runtime_asserts_over_guards).
ExecutorchConfig
lớp transformers.exporters.ExecutorchConfig
< source >( export_format: ExportFormat = <ExportFormat.EXECUTORCH: 'executorch'>dynamic: bool = Falsestrict: bool = Falsedynamic_shapes: dict[str, Any] | None = Noneprefer_deferred_runtime_asserts_over_guards: bool = Falsequantizer: ExportQuantizer | None = Nonebackend: str = 'xnnpack'alloc_graph_input: bool = Truealloc_graph_output: bool = Truealloc_mutable_buffers: bool = True )
Tham số
- backend (
str, tùy chọn, mặc định là"xnnpack") — Backend ExecuTorch đích. Các giá trị được hỗ trợ:"xnnpack"— suy luận CPU thông qua thư viện XNNPACK (mặc định; chạy ở mọi nơi)."cuda"— suy luận GPU thông qua backend CUDA của ExecuTorch."mlx"— suy luận GPU thông qua backend ExecuTorch MLX trên Apple Silicon.
- alloc_graph_input (
bool, tuỳ chọn, mặc định làTrue) — Xác định xem bước lập kế hoạch bộ nhớ có dành vùng nhớ arena cho các đầu vào của đồ thị hay không. KhiFalse, thời gian chạy sẽ sử dụng trực tiếp các bộ đệm đầu vào do người gọi cung cấp thay vì sao chép vào arena — do đó, một thao tácUSER_INPUT_MUTATIONtại chỗ (ví dụ: ghi vàoStaticCache) sẽ được thực hiện trên tensor của người gọi thay vì trên bản sao trong arena. - alloc_graph_output (
bool, tuỳ chọn, mặc định làTrue) — Xác định xem bước lập kế hoạch bộ nhớ có dành trước bộ nhớ arena cho các đầu ra của đồ thị hay không. KhiFalse, người gọi phải liên kết các bộ đệm đầu ra vào thời điểm thực thi (Method::set_output_data_ptr); việc liên kết một đầu ra với bộ đệm của đầu vào đã bị thay đổi sẽ tránh được vòng lặp sao chép ra ngoài. - alloc_mutable_buffers (
bool, tuỳ chọn, mặc định làTrue) — Xác định xem bước lập kế hoạch bộ nhớ có dành vùng nhớ arena cho các bộ đệm có thể thay đổi (trạng thái nằm trong mô hình) hay không. Giá trị này được truyền qua choMemoryPlanningPass.
Lớp cấu hình để xuất mô hình sang định dạng ExecuTorch.
Kế thừa tất cả các trường từ DynamoConfig (dynamic, strict, dynamic_shapes, prefer_deferred_runtime_asserts_over_guards).
OpenVINOConfig
lớp transformers.exporters.OpenVINOConfig
< source >( export_format: ExportFormat = <ExportFormat.OPENVINO: 'openvino'>dynamic: bool = Falsestrict: bool = Falsedynamic_shapes: dict[str, Any] | None = Noneprefer_deferred_runtime_asserts_over_guards: bool = Falsequantizer: ExportQuantizer | None = Nonecompress_to_fp16: bool = Falsestateful: bool = True )
Tham số
- compress_to_fp16 (bool, optional, mặc định là False) — Nén trọng số float32 của mô hình đã chuyển đổi sang float16, giảm một nửa kích thước. Mặc định là tắt do phạm vi hẹp hơn.
- stateful (bool, optional, defaults to True) —
Fold round-tripped state tensors (KV cache, SSM states, …) into internal OV
variables (
ReadValue/Assign`). The runtime then carries state across `infer()` calls instead of marshalling cache tensors through inputs/outputs on every step, and a fused `beam_idxinput reorders state in-graph for beam search. No-op for models without round-tripped state (encoders, prefill-only exports). Set it to False for targets that take no stateful model, such as the NPU plugin.
Lớp cấu hình để xuất mô hình sang OpenVINO IR thông qua openvino.convert_model.
Kế thừa tất cả các trường từ [DynamoConfig] (dynamic, strict, dynamic_shapes, prefer_deferred_runtime_asserts_over_guards).
Bộ lượng tử hóa
lớp transformers.exporters.ExportQuantizer
< source >( calibration_dataset: Iterable[dict[str, Any]] | None = None )
Tham số
- calibration_dataset (
Iterable[dict], tùy chọn) — Các dict đầu vào mà bộ lượng tử hóa dùng để hiệu chuẩn: một danh sách, hoặc mộtDataLoadercó các batch được collate thành đầu vào của model. Đối với~HfExporter.export_for_generation, chúng là các kwargs của generate, được thu thập thành một tập hiệu chuẩn cho mỗi thành phần. KhiNone, một bộ lượng tử hóa cần dữ liệu sẽ hiệu chuẩn trên các đầu vào mẫu của chính quá trình xuất, kèm theo một cảnh báo.
Lớp cơ sở cho các bộ lượng tử hóa sau huấn luyện được áp dụng trong quá trình xuất.
Bộ lượng tử hóa khai báo các định dạng xuất mà nó hỗ trợ và các gói cần thiết (kèm theo các phiên bản đã được kiểm thử, tương tự như các bộ xuất) cũng như việc nó lượng tử hóa đồ thị FX của torch.export trước bất kỳ bước chuyển đổi nào (để mọi backend đều nhận kết quả) hay lượng tử hóa mô hình mà một backend chuyển đổi nó thành (onnx_ir.Model, openvino.Model). Bộ xuất xác thực nó với quá trình xuất ngay từ đầu, sau đó gọi ~ExportQuantizer.quantize với mô hình đó và các đầu vào mẫu của quá trình xuất. Hãy kế thừa lớp này và triển khai quantize để thêm một phương pháp lượng tử hóa mới; một CalibrationSet ánh xạ các mẫu hiệu chuẩn sang các đầu vào của chính mô hình.
Lượng tử hóa model (đồ thị FX nếu quantizes_fx_graph, ngược lại là model backend) và trả về kết quả, được hiệu chuẩn trên calibration_dataset, hoặc trên sample_inputs của bản xuất khi không có bộ dữ liệu hiệu chuẩn.
Các mẫu hiệu chuẩn dưới dạng kwargs được theo dõi, dành cho các bộ lượng tử hóa FX-graph.
Ném lỗi nếu quantizer này không thể chạy trên export export_format, hoặc một gói cần thiết bị thiếu hoặc quá cũ;
cảnh báo khi một gói khác với phiên bản đã được kiểm thử.
Một bản sao của bộ lượng tử hóa này, được hiệu chuẩn trên calibration_dataset.
lớp transformers.exporters.quantizers.CalibrationSet
< source >( calibration_dataset: Iterable[dict[str, Any]] | Nonesample_inputs: dict[str, Any]transform: Callable[[dict[str, Any]], Any] )
Xem lại có thể lặp lại các mẫu hiệu chuẩn dưới dạng đầu vào của mô hình.
Các mẫu là calibration_dataset của bộ lượng tử hóa, hoặc chính sample_inputs của bản xuất (kèm một cảnh báo, một lần duy nhất khi chúng được đọc) nếu không có bộ lượng tử hóa. Chúng có thể là bất kỳ ánh xạ nào, chẳng hạn như BatchEncoding của bộ mã hóa. transform ánh xạ từng mẫu forward-kwarg thành những gì mô hình đã lượng tử hóa nhận vào (các kwargs được theo dõi, các feed ONNX, các feed cổng OpenVINO), một cách lười biếng, từng mẫu một, trong mỗi lượt chạy.
lớp transformers.exporters.PT2EQuantizer
< source >( quantizer: Anycalibration_dataset: Iterable[dict[str, Any]] | None = None )
Tham số
- quantizer (
torchao.quantization.pt2e.quantizer.Quantizer) — Bộ lượng tử hóa PT2E dùng để chú thích đồ thị. Các toán tử lượng tử hóa/giải lượng tử hóa của nó phải là những toán tử được backend đích hỗ trợ:X86InductorQuantizercho inductor, ONNX (QDQ) hoặc OpenVINO,XNNPACKQuantizercho ExecuTorch. - calibration_dataset (
Iterable[dict], tùy chọn) — Các dict đầu vào mà các observer dùng để hiệu chuẩn (xemExportQuantizer), mỗi dict tương ứng với một lần forward. Để hiệu chuẩn trên các batch, hãy truyền mộtDataLoadergộp các mẫu thành các dict đầu vào dạng batch thay vì một danh sách các mẫu đơn lẻ.
Thực hiện lượng hóa đồ thị FX bằng lượng hóa PyTorch 2 Export (PT2E): prepare_pt2e chèn các observer, tập hiệu chuẩn điều khiển chúng, và convert_pt2e thay thế chúng bằng các toán tử quantize/dequantize. Hoạt động với mọi backend xuất.
Ví dụ:
>>> from torchao.quantization.pt2e.quantizer.x86_inductor_quantizer import (
... X86InductorQuantizer,
... get_default_x86_inductor_quantization_config,
... )
>>> from transformers.exporters import DynamoConfig, PT2EQuantizer
>>> x86 = X86InductorQuantizer().set_global(get_default_x86_inductor_quantization_config())
>>> DynamoConfig(quantizer=PT2EQuantizer(x86, calibration_dataset=samples))lớp transformers.exporters.OnnxRuntimeQuantizer
< source >( config: OnnxRuntimeStaticConfig | OnnxRuntimeDynamicConfig | None = Nonecalibration_dataset: Iterable[dict[str, Any]] | None = None )
Lượng tử hóa mô hình ONNX đã chuyển đổi bằng các công cụ riêng của ONNX Runtime (onnxruntime.quantization): quantize_static với OnnxRuntimeStaticConfig (mặc định), hoặc quantize_dynamic với OnnxRuntimeDynamicConfig.
Ví dụ:
>>> from transformers.exporters import (
... OnnxConfig,
... OnnxRuntimeDynamicConfig,
... OnnxRuntimeQuantizer,
... OnnxRuntimeStaticConfig,
... )
>>> static = OnnxRuntimeStaticConfig(per_channel=True)
>>> OnnxConfig(quantizer=OnnxRuntimeQuantizer(static, calibration_dataset=samples))
>>> OnnxConfig(quantizer=OnnxRuntimeQuantizer(OnnxRuntimeDynamicConfig()))lớp transformers.exporters.OnnxRuntimeStaticConfig
< source >( quant_format: Any = Noneop_types_to_quantize: list[str] | None = Noneper_channel: bool | None = Nonereduce_range: bool | None = Noneactivation_type: Any = Noneweight_type: Any = Nonenodes_to_quantize: list[str] | None = Nonenodes_to_exclude: list[str] | None = Nonecalibrate_method: Any = Nonecalibration_providers: list[str] | None = Noneextra_options: dict[str, Any] | None = None )
Các tham số của onnxruntime.quantization.quantize_static: kích hoạt và trọng số int8 (mặc định là QDQ), được hiệu chuẩn trên calibration_dataset của bộ lượng tử hóa. Một trường được đặt thành None sẽ giữ nguyên giá trị mặc định của ONNX Runtime. Xem quantize_static cho từng tham số.
lớp transformers.exporters.OnnxRuntimeDynamicConfig
< source >( op_types_to_quantize: list[str] | None = Noneper_channel: bool | None = Nonereduce_range: bool | None = Noneweight_type: Any = Nonenodes_to_quantize: list[str] | None = Nonenodes_to_exclude: list[str] | None = Noneextra_options: dict[str, Any] | None = None )
Các tham số của onnxruntime.quantization.quantize_dynamic: trọng số int8, kích hoạt được lượng tử hóa khi chạy, không hiệu chuẩn. Một trường được đặt thành None sẽ giữ nguyên giá trị mặc định của ONNX Runtime. Xem quantize_dynamic cho từng tham số.
lớp transformers.exporters.NNCFOpenVINOQuantizer
< source >( config: NNCFQuantizationConfig | NNCFWeightCompressionConfig | None = Nonecalibration_dataset: Iterable[dict[str, Any]] | None = None )
Thực hiện lượng tử hóa mô hình OpenVINO đã chuyển đổi bằng NNCF: nncf.quantize với NNCFQuantizationConfig (mặc định), hoặc nncf.compress_weights với NNCFWeightCompressionConfig.
Ví dụ:
>>> import nncf
>>> from transformers.exporters import NNCFOpenVINOQuantizer, NNCFWeightCompressionConfig, OpenVINOConfig
>>> OpenVINOConfig(quantizer=NNCFOpenVINOQuantizer(calibration_dataset=samples))
>>> OpenVINOConfig(
... quantizer=NNCFOpenVINOQuantizer(NNCFWeightCompressionConfig(mode=nncf.CompressWeightsMode.INT4_SYM))
... )lớp transformers.exporters.NNCFOnnxQuantizer
< source >( config: NNCFQuantizationConfig | NNCFWeightCompressionConfig | None = Nonecalibration_dataset: Iterable[dict[str, Any]] | None = None )
Thực hiện lượng tử hóa mô hình ONNX đã chuyển đổi bằng NNCF thông qua backend ONNX của nó: nncf.quantize với NNCFQuantizationConfig (mặc định, int8 QDQ), hoặc nncf.compress_weights với NNCFWeightCompressionConfig (int4 dưới dạng MatMulNBits của ONNX Runtime).
Ví dụ:
>>> import nncf
>>> from transformers.exporters import NNCFOnnxQuantizer, NNCFWeightCompressionConfig, OnnxConfig
>>> OnnxConfig(quantizer=NNCFOnnxQuantizer(calibration_dataset=samples))
>>> OnnxConfig(quantizer=NNCFOnnxQuantizer(NNCFWeightCompressionConfig(mode=nncf.CompressWeightsMode.INT4_SYM)))lớp transformers.exporters.NNCFTorchFXQuantizer
< source >( config: NNCFQuantizationConfig | NNCFWeightCompressionConfig | None = Nonecalibration_dataset: Iterable[dict[str, Any]] | None = None )
Lượng tử hóa đồ thị FX của torch.export bằng NNCF thông qua backend TorchFX của nó: nncf.quantize với NNCFQuantizationConfig (mặc định, các op quantize/dequantize), hoặc nncf.compress_weights với NNCFWeightCompressionConfig. Giống như PT2EQuantizer, nó chạy trước bất kỳ bước chuyển đổi nào, nên mọi backend đều nhận kết quả của nó. ExecuTorch chỉ hạ thấp kết quả weight-only: XNNPACK không ủy quyền cho các op quantize/dequantize, và ExecuTorch không có kernel cho chúng.
lớp transformers.exporters.NNCFQuantizationConfig
< source >( mode: Any = Nonepreset: Any = Nonetarget_device: Any = Nonesubset_size: int | None = Nonefast_bias_correction: bool | None = Nonemodel_type: Any = Noneignored_scope: Any = Noneadvanced_parameters: Any = None )
Các tham số của nncf.quantize: kích hoạt và trọng số int8, được hiệu chuẩn trên calibration_dataset của bộ lượng tử hóa.
Một trường được đặt thành None sẽ giữ nguyên giá trị mặc định của NNCF, ngoại trừ model_type, có giá trị mặc định là nncf.ModelType.TRANSFORMER.
Xem nncf.quantize cho từng tham số.
lớp transformers.exporters.NNCFWeightCompressionConfig
< source >( mode: Any = Noneratio: float | None = Nonegroup_size: int | None = Noneignored_scope: Any = Noneall_layers: bool | None = Nonesensitivity_metric: Any = Nonesubset_size: int | None = Noneawq: bool | None = Nonescale_estimation: bool | None = Nonegptq: bool | None = Nonelora_correction: bool | None = Nonebackup_mode: Any = Nonecompression_format: Any = Noneadvanced_parameters: Any = None )
Các tham số của nncf.compress_weights: int8 hoặc int4 chỉ cho trọng số, với các phương pháp nhận thức dữ liệu (AWQ, ước lượng tỷ lệ,
GPTQ) cho các chế độ int4. Các chế độ int8 không cần dữ liệu; các chế độ khác hiệu chuẩn trên calibration_dataset của bộ lượng tử hóa. gptq và lora_correction chỉ dành cho OpenVINO. Một trường được đặt thành None sẽ giữ nguyên giá trị mặc định của NNCF. Xem nncf.compress_weights cho
từng tham số.
Công cụ tiện ích
Các hàm cấp thấp hơn hỗ trợ export_for_generation, hữu ích khi bạn cần can thiệp giữa việc phân rã mô hình và xuất từng thành phần.
transformers.exporters.utils.get_leaf_tensors
< source >( obj: Any ) → dict[str, torch.Tensor]
Lấy đệ quy tất cả các tensor lá từ một cấu trúc có thể lồng nhau.
transformers.exporters.utils.prepare_for_export
< source >( model: PreTrainedModel | torch.nn.Moduleinputs: MutableMapping[str, Any] )
Cấu hình model và inputs để xuất. Thay đổi cả model và inputs tại chỗ,
trả về (model, inputs, output_flags) trong đó output_flags chứa các giá trị đã được lấy ra
từ inputs cho use_cache, return_dict, v.v. (để được áp dụng một cách có thể đảo ngược lên model.config bởi patch_model_config trong quá trình trace).
- Loại bỏ các đầu vào nhãn (
labels,future_values) — không hỗ trợ tính toán loss. - Lấy các cờ đầu ra (
use_cache,return_dict, …) ra khỏiinputsđể chúng không xuất hiện dưới dạng kwargs được theo dõi; các giá trị này được trả về để khối trace áp dụng lênmodel.config. - Tiền xử lý các tham số kwargs của thị giác/âm thanh phụ thuộc vào dữ liệu đã được đăng ký thông qua
@register_export_input_preparervà ghi chúng vàoinputs. - Chuyển đổi các tensor đầu vào để khớp với
dtype/devicecủa mô hình.
transformers.exporters.utils.decompose_prefill_decode
< source >( model: PreTrainedModelinputs: dict[str, Any]generation_config: Any = Nonemulti_token_decode: bool = False ) → dict[str, tuple[torch.nn.Module, dict]]
Trả về
dict[str, tuple[torch.nn.Module, dict]]
{"prefill": (model, prefill_inputs), "decode": (model, decode_inputs)}.
Chạy model.generate() và ghi nhận các đầu vào của prefill và decode.
Tái sử dụng toàn bộ cơ chế sinh để mọi kiến trúc (chỉ có decoder, SSM, encoder-decoder, đa phương thức, …) đều nhận được các đầu vào chính xác mà không cần cài đặt lại vòng lặp.
generation_config được chuyển tiếp đến generate() (mặc định là cấu hình của chính model), do đó các đầu vào được ghi lại sẽ sử dụng bất kỳ cache nào mà generate() sẽ xây dựng. Truyền một cấu hình có cache_implementation="static" và max_cache_len=N để ghi lại một cache có kích thước tĩnh trong các đầu vào decode — nền tảng cho việc xuất (export) cache tĩnh. max_cache_len xác định kích thước cache độc lập với quá trình ghi lại, nên bản decode được xuất sẽ nhận một cache cố định [..., N, ...] thay vì một cache tăng dần.
Khi multi_token_decode, thành phần decode được bắt giữ dưới dạng multi-token decode — hai bước decode liên tiếp được gộp lại (xem _merge_decode_calls) để trục query-sequence của nó vẫn ở dạng biểu tượng (một bước decode single-token sẽ đặc biệt hóa trục đó thành 1). Sau đó, nó xử lý cả trường hợp một token (giải mã thông thường) và nhiều token (tiếp nối từ quá khứ, hoặc prefill thông thường khi cache trống). Ngược lại, decode là bước decode single-token cổ điển.
transformers.exporters.utils.decompose_multimodal
< source >( model: PreTrainedModelinputs: dict[str, Any] ) → dict[str, tuple[torch.nn.Module, dict]]
Trả về
dict[str, tuple[torch.nn.Module, dict]]
Một mục name: (module, inputs) cho mỗi submodule được phát hiện (bộ mã hóa hình ảnh/âm thanh, bộ chiếu, mô hình ngôn ngữ, lm_head).
Gây ra
ValueError
ValueError— nếu không tìm thấy các module con đa phương thức đã biết nào trên model.
Thu thập đầu vào cho từng mô-đun con đa phương thức thông qua một lần truyền tiến duy nhất.
Phát hiện tất cả các module con đa phương thức đã biết theo tên thuộc tính (vision tower, projector,
language model, lm_head, …) và ghi lại các tham số kwargs của forward trong một lần gọi model(**inputs).
Mỗi submodule được trả về dưới dạng một mục name: (module, inputs) riêng biệt để xuất độc lập. Bước hợp nhất token (ví dụ masked_scatter cho các model đa phương thức) được cố ý giữ bên ngoài các đồ thị đã xuất — trách nhiệm của người gọi là lắp ráp inputs_embeds từ đầu ra của encoder trước khi chạy decoder.
transformers.exporters.utils.decompose_for_generation
< source >( model: PreTrainedModelinputs: dict[str, Any]generation_config: Any = Nonemulti_token_decode: bool = False ) → `{component_name
Tham số
- model — Mô hình tạo sinh. Phải hỗ trợ
model.generate(**inputs). - inputs — Generate kwargs — những gì bạn sẽ truyền vào
model.generate(**inputs). - generation_config — Tùy chọn
GenerationConfigđược chuyển đếngenerate()trong quá trình capture. Truyền một cấu hình cócache_implementation="static"+max_cache_len=Nđể xuất đối với cache có kích thước tĩnh (xemdecompose_prefill_decode). - multi_token_decode — Khi
True, bắt (capture) thành phầndecodedưới dạng multi-token decode (trục query sequence động: nhiều token cùng lúc — tiếp nối từ quá khứ, hoặc prefill thông thường khi cache trống); single-token decode không thể giữ ở chế độ động (xemdecompose_prefill_decode).
Trả về
`{component_name
(submodel, forward_inputs)}. Keys are “prefill”/“decode”for plain generative models and”<modality>_encoder”/“multi_modal_projector”/“language_model”/“lm_head”/“decode”` for multi-modal generative models.
Phân tách một mô hình sinh thành thành các cặp (model, forward_inputs) có thể xuất độc lập.
Chạy decompose_prefill_decode để thu thập các kwargs của forward cho prefill và decode từ một model.generate(**inputs, max_new_tokens=2) thực tế. Nếu prefill là đa phương thức (theo is_multimodal),
nó sẽ tách thêm thành một mục cho mỗi submodule (encoder thị giác/âm thanh, projector, mô hình ngôn ngữ, lm_head) thông qua decompose_multimodal.
Trả về True nếu mô hình là đa phương thức với các bộ mã hóa phương thức và một mô hình ngôn ngữ.
Một mô hình không phải là PreTrainedModel (ví dụ: một nn.Module thuần túy) không có các bộ truy cập chuẩn get_encoder/get_decoder và rõ ràng không phải là đa phương thức, do đó nó sẽ trả về False ngay lập tức.