库名称：transformers 标签：

• torchao
• phi
• phi4
• 自然语言处理
• 代码
• 数学
• 聊天
• 对话式 许可证：MIT 语言：
• 多语言 基础模型：
• microsoft/Phi-4-mini-instruct 流水线标签：文本生成

Phi4-mini 由 PyTorch 团队使用 torchao 进行量化，采用8位嵌入和8位动态激活，以及4位权重线性层（8da4w）。 该模型适合通过 ExecuTorch 进行移动端部署。

我们提供了可直接在 ExecuTorch 中使用的量化 pte 文件。 （提供的 pte 文件导出时默认最大序列长度/上下文长度为128；如需修改，请按照导出到 ExecuTorch部分的说明重新导出量化模型。）

在移动应用中运行

pte 文件 可以在手机上通过 ExecuTorch 运行。iOS 上的操作请参考说明。 在 iPhone 15 Pro 上，模型运行速度为每秒17.3个令牌，内存占用为3206 MB。

量化方案

首先需要安装必要的包：

pip install git+https://github.com/huggingface/transformers@main
pip install torchao

解绑嵌入权重

我们需要对嵌入层和 lm_head 进行不同的量化。由于这些层是绑定的，首先需要解绑模型：

from transformers import (
  AutoModelForCausalLM,
  AutoProcessor,
  AutoTokenizer,
)
import torch

model_id = "microsoft/Phi-4-mini-instruct"
untied_model = AutoModelForCausalLM.from_pretrained(model_id, torch_dtype="auto", device_map="auto")
tokenizer = AutoTokenizer.from_pretrained(model_id)

print(untied_model)
from transformers.modeling_utils import find_tied_parameters
print("绑定的权重:", find_tied_parameters(untied_model))
if getattr(untied_model.config.get_text_config(decoder=True), "tie_word_embeddings"):
    setattr(untied_model.config.get_text_config(decoder=True), "tie_word_embeddings", False)

untied_model._tied_weights_keys = []
untied_model.lm_head.weight = torch.nn.Parameter(untied_model.lm_head.weight.clone())

print("绑定的权重:", find_tied_parameters(untied_model))

USER_ID = "YOUR_USER_ID"
MODEL_NAME = model_id.split("/")[-1]
save_to = f"{USER_ID}/{MODEL_NAME}-untied-weights"

untied_model.push_to_hub(save_to)
tokenizer.push_to_hub(save_to)

# 或本地保存
save_to_local_path = f"{MODEL_NAME}-untied-weights"
untied_model.save_pretrained(save_to_local_path)
tokenizer.save_pretrained(save_to)

注意：使用 push_to_hub 需要运行

pip install -U "huggingface_hub[cli]"
huggingface-cli login

并使用具有写入权限的令牌，从 https://huggingface.co/settings/tokens 获取。

量化

我们使用以下代码获取量化模型：

from transformers import (
  AutoModelForCausalLM,
  AutoProcessor,
  AutoTokenizer,
  TorchAoConfig,
)
from torchao.quantization.quant_api import (
    IntxWeightOnlyConfig,
    Int8DynamicActivationIntxWeightConfig,
    AOPerModuleConfig,
    quantize_,
)
from torchao.quantization.granularity import PerGroup, PerAxis
import torch

# 从解绑权重的模型开始
model_id = "microsoft/Phi-4-mini-instruct"
USER_ID = "YOUR_USER_ID"
MODEL_NAME = model_id.split("/")[-1]
untied_model_id = f"{USER_ID}/{MODEL_NAME}-untied-weights"
untied_model_local_path = f"{MODEL_NAME}-untied-weights"

embedding_config = IntxWeightOnlyConfig(
    weight_dtype=torch.int8,
    granularity=PerAxis(0),
)
linear_config = Int8DynamicActivationIntxWeightConfig(
    weight_dtype=torch.int4,
    weight_granularity=PerGroup(32),
    weight_scale_dtype=torch.bfloat16,
)
quant_config = AOPerModuleConfig({"_default": linear_config, "model.embed_tokens": embedding_config})
quantization_config = TorchAoConfig(quant_type=quant_config, include_embedding=True, untie_embedding_weights=True, modules_to_not_convert=[])

# 使用 `untied_model_id` 或 `untied_model_local_path`
quantized_model = AutoModelForCausalLM.from_pretrained(untied_model_id, torch_dtype=torch.float32, device_map="auto", quantization_config=quantization_config)
tokenizer = AutoTokenizer.from_pretrained(model_id)

# 推送到 Hub
MODEL_NAME = model_id.split("/")[-1]
save_to = f"{USER_ID}/{MODEL_NAME}-untied-8da4w"
quantized_model.push_to_hub(save_to, safe_serialization=False)
tokenizer.push_to_hub(save_to)

# 手动测试
prompt = "嘿，你有意识吗？能和我说话吗？"
messages = [
    {
        "role": "system",
        "content": "",
    },
    {"role": "user", "content": prompt},
]
templated_prompt = tokenizer.apply_chat_template(
    messages,
    tokenize=False,
    add_generation_prompt=True,
)
print("提示:", prompt)
print("模板化提示:", templated_prompt)
inputs = tokenizer(
    templated_prompt,
    return_tensors="pt",
).to("cuda")
generated_ids = quantized_model.generate(**inputs, max_new_tokens=128)
output_text = tokenizer.batch_decode(
    generated_ids, skip_special_tokens=True, clean_up_tokenization_spaces=False
)
print("响应:", output_text[0][len(prompt):])

手动测试的响应为：

你好！作为AI，我没有人类那样的意识，但我完全运行正常，随时为你提供帮助。今天有什么可以帮你的吗？

模型质量

我们依赖 lm-evaluation-harness 来评估量化模型的质量。

需要从源码安装 lm-eval：https://github.com/EleutherAI/lm-evaluation-harness#install

基准测试

lm_eval --model hf --model_args pretrained=microsoft/Phi-4-mini-instruct --tasks hellaswag --device cuda:0 --batch_size 8

int8 动态激活和 int4 权重量化 (8da4w)

lm_eval --model hf --model_args pretrained=pytorch/Phi-4-mini-instruct-8da4w --tasks hellaswag --device cuda:0 --batch_size 8

导出到 ExecuTorch

我们可以使用 ExecuTorch 在手机上运行量化模型。 一旦 设置好 ExecuTorch，导出并在设备上运行模型就变得轻而易举。

我们首先将量化检查点转换为 ExecuTorch 的 LLM 导出脚本所期望的格式，通过重命名一些检查点键。 以下脚本为你完成这一操作。为了方便，我们已经上传了转换后的检查点 pytorch_model_converted.bin。

python -m executorch.examples.models.phi_4_mini.convert_weights pytorch_model.bin pytorch_model_converted.bin

一旦检查点转换完成，我们就可以使用 XNNPACK 委托导出到 ExecuTorch 的 pte 格式。 以下命令以默认值 max_seq_length/max_context_length 128 导出，但可以根据需要修改。

PARAMS="executorch/examples/models/phi_4_mini/config.json"
python -m executorch.examples.models.llama.export_llama \
  --model "phi_4_mini" \
  --checkpoint "pytorch_model_converted.bin" \
  --params "$PARAMS" \
  -kv \
  --use_sdpa_with_kv_cache \
  -X \
  --metadata '{"get_bos_id":199999, "get_eos_ids":[200020,199999]}' \
  --max_seq_length 128 \
  --max_context_length 128 \
  --output_name="phi4-mini-8da4w.pte"

之后，你可以在移动应用中运行模型（参见在移动应用中运行）。

免责声明

PyTorch 尚未对量化模型进行安全性评估或红队测试。性能特征、输出和行为可能与原始模型有所不同。用户全权负责选择适当的用例，评估和减轻准确性、安全性和公平性问题，确保安全性，并遵守所有适用的法律法规。

本模型卡中的任何内容均不应被解释为或视为对模型发布许可证的限制或修改，包括其中提供的任何责任限制或免责声明。