{
"canonical_name": "huggingface/peft",
"compilation_id": "pack_a02000bd12f24a57a473f2e9ccd223cf",
"created_at": "2026-05-16T07:05:30.291728+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=prompt, recipe, host_instruction, eval, preflight",
"recommended_asset_types=prompt, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `pip install peft` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "pip install peft",
"sandbox_container_image": "python:3.12-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "llm_execute_isolated_install",
"sandbox_validation_id": "sbx_7d8281dca874491b83a7ef2cdc38c88e"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_3ce41141eeec5d9030f64e6e8073cbc7",
"canonical_name": "huggingface/peft",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/huggingface/peft",
"slug": "peft",
"source_packet_id": "phit_8d55a2720e4e4eb1addf9adafd871ad0",
"source_validation_id": "dval_fcee8ef0f7c24b199e4017e7b27c247f"
},
"merchandising": {
"best_for": "需要软件开发与交付能力，并使用 local_cli的用户",
"github_forks": 2292,
"github_stars": 21112,
"one_liner_en": "🤗 PEFT: State-of-the-art Parameter-Efficient Fine-Tuning.",
"one_liner_zh": "🤗 PEFT: State-of-the-art Parameter-Efficient Fine-Tuning.",
"primary_category": {
"category_id": "software-development",
"confidence": "high",
"name_en": "Software Development",
"name_zh": "软件开发与交付",
"reason": "matched_keywords:git, ci, cli"
},
"target_user": "使用 local_cli 等宿主 AI 的用户",
"title_en": "peft",
"title_zh": "peft 能力包",
"visible_tags": [
{
"label_en": "Knowledge Retrieval",
"label_zh": "知识检索",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-knowledge-retrieval",
"type": "product_domain"
},
{
"label_en": "Knowledge Base Q&A",
"label_zh": "知识库问答",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-knowledge-base-q-a",
"type": "user_job"
},
{
"label_en": "Structured Extraction",
"label_zh": "结构化提取",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-structured-extraction",
"type": "core_capability"
},
{
"label_en": "Checkpoint Resume",
"label_zh": "断点恢复流程",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-checkpoint-resume",
"type": "workflow_pattern"
},
{
"label_en": "Evaluation Suite",
"label_zh": "评测体系",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-evaluation-suite",
"type": "selection_signal"
}
]
},
"packet_id": "phit_8d55a2720e4e4eb1addf9adafd871ad0",
"page_model": {
"artifacts": {
"artifact_slug": "peft",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "pip install peft",
"label": "Python / pip · 官方安装入口",
"source": "https://github.com/huggingface/peft#readme",
"verified": true
}
],
"display_tags": [
"知识检索",
"知识库问答",
"结构化提取",
"断点恢复流程",
"评测体系"
],
"eyebrow": "软件开发与交付",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要软件开发与交付能力，并使用 local_cli的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "🤗 PEFT: State-of-the-art Parameter-Efficient Fine-Tuning."
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "local_cli",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "prompt, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[BUG] peft 0.19 target_modules (str) use `set`",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_bd098228d56f4251949a351ac90335fc | https://github.com/huggingface/peft/issues/3229 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：[BUG] peft 0.19 target_modules (str) use `set`",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Comparison of Different Fine-Tuning Techniques for Conversational AI",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_408252d26b4a4d87b9ca9362c3b4b37b | https://github.com/huggingface/peft/issues/2310 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Comparison of Different Fine-Tuning Techniques for Conversational AI",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Feature Request: Improve offline support for custom architectures in get_peft_model_state_dict",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_32e0990aa35b430bac525df543e75cac | https://github.com/huggingface/peft/issues/3211 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Feature Request: Improve offline support for custom architectures in get_peft_model_state_dict",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：0.17.0: SHiRA, MiSS, LoRA for MoE, and more",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_a7ec4779d09a4fcebe0901d73f869bf0 | https://github.com/huggingface/peft/releases/tag/v0.17.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：0.17.0: SHiRA, MiSS, LoRA for MoE, and more",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Applying Dora to o_proj of Meta-Llama-3.1-8B results in NaN",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_ce144c340d9f40929a6551e9dbca770d | https://github.com/huggingface/peft/issues/2049 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Applying Dora to o_proj of Meta-Llama-3.1-8B results in NaN",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:570384908 | https://github.com/huggingface/peft | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：0.17.1",
"category": "运行坑",
"evidence": [
"community_evidence:github | cevd_cd675dc497c44319af556a2e7059dd95 | https://github.com/huggingface/peft/releases/tag/v0.17.1 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：0.17.1",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.15.1",
"category": "运行坑",
"evidence": [
"community_evidence:github | cevd_66bfe8be731a44de971b991569f61e57 | https://github.com/huggingface/peft/releases/tag/v0.15.1 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v0.15.1",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.15.2",
"category": "运行坑",
"evidence": [
"community_evidence:github | cevd_3d5933ee300d4f68bfab2f0440fae679 | https://github.com/huggingface/peft/releases/tag/v0.15.2 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v0.15.2",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：0.16.0: LoRA-FA, RandLoRA, C³A, and much more",
"category": "维护坑",
"evidence": [
"community_evidence:github | cevd_5ef66863f7c64b3e9e3ba6a72eaab639 | https://github.com/huggingface/peft/releases/tag/v0.16.0 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：0.16.0: LoRA-FA, RandLoRA, C³A, and much more",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:570384908 | https://github.com/huggingface/peft | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | github_repo:570384908 | https://github.com/huggingface/peft | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:570384908 | https://github.com/huggingface/peft | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：0.18.0: RoAd, ALoRA, Arrow, WaveFT, DeLoRA, OSF, and more",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_b28315fbb2d44b748ca46f87fafd3d33 | https://github.com/huggingface/peft/releases/tag/v0.18.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：0.18.0: RoAd, ALoRA, Arrow, WaveFT, DeLoRA, OSF, and more",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.15.0",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_1a3ce413d14349658dc005c25754bb1f | https://github.com/huggingface/peft/releases/tag/v0.15.0 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v0.15.0",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.19.0",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_abcf15a2812744f0a37ad5c5d75643cf | https://github.com/huggingface/peft/releases/tag/v0.19.0 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v0.19.0",
"user_impact": "可能影响授权、密钥配置或安全边界。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 18 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：配置坑 - 来源证据：[BUG] peft 0.19 target_modules (str) use `set`。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 295,
"forks": 2292,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 21112
},
"source_url": "https://github.com/huggingface/peft",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "🤗 PEFT: State-of-the-art Parameter-Efficient Fine-Tuning.",
"title": "peft 能力包",
"trial_prompt": "# peft - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 peft 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: 🤗 PEFT: State-of-the-art Parameter-Efficient Fine-Tuning. 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. overview：PEFT概述与快速入门。围绕“PEFT概述与快速入门”模拟一次用户任务，不展示安装或运行结果。\n2. core-modules：核心模块与架构。围绕“核心模块与架构”模拟一次用户任务，不展示安装或运行结果。\n3. config-system：配置系统。围绕“配置系统”模拟一次用户任务，不展示安装或运行结果。\n4. lora-tuners：LoRA及其变体实现。围绕“LoRA及其变体实现”模拟一次用户任务，不展示安装或运行结果。\n5. examples-overview：示例与用例概览。围绕“示例与用例概览”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. overview\n输入：用户提供的“PEFT概述与快速入门”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. core-modules\n输入：用户提供的“核心模块与架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. config-system\n输入：用户提供的“配置系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. lora-tuners\n输入：用户提供的“LoRA及其变体实现”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. examples-overview\n输入：用户提供的“示例与用例概览”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / overview：Step 1 必须围绕“PEFT概述与快速入门”形成一个小中间产物，并等待用户确认。\n- Step 2 / core-modules：Step 2 必须围绕“核心模块与架构”形成一个小中间产物，并等待用户确认。\n- Step 3 / config-system：Step 3 必须围绕“配置系统”形成一个小中间产物，并等待用户确认。\n- Step 4 / lora-tuners：Step 4 必须围绕“LoRA及其变体实现”形成一个小中间产物，并等待用户确认。\n- Step 5 / examples-overview：Step 5 必须围绕“示例与用例概览”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/huggingface/peft\n- https://github.com/huggingface/peft#readme\n- README.md\n- docs/source/quicktour.md\n- docs/source/install.md\n- src/peft/__init__.py\n- src/peft/peft_model.py\n- src/peft/mapping.py\n- src/peft/helpers.py\n- src/peft/auto.py\n- src/peft/tuners/tuners_utils.py\n- src/peft/config.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 peft 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_issue: Feature Request: Improve offline support for custom architectures in get（https://github.com/huggingface/peft/issues/3211）；github/github_issue: Applying Dora to o_proj of Meta-Llama-3.1-8B results in NaN（https://github.com/huggingface/peft/issues/2049）；github/github_issue: Comparison of Different Fine-Tuning Techniques for Conversational AI（https://github.com/huggingface/peft/issues/2310）；github/github_issue: [BUG] peft 0.19 target_modules (str) use `set`（https://github.com/huggingface/peft/issues/3229）；github/github_release: v0.19.1（https://github.com/huggingface/peft/releases/tag/v0.19.1）；github/github_release: v0.19.0（https://github.com/huggingface/peft/releases/tag/v0.19.0）；github/github_release: 0.18.1（https://github.com/huggingface/peft/releases/tag/v0.18.1）；github/github_release: 0.18.0: RoAd, ALoRA, Arrow, WaveFT, DeLoRA, OSF, and more（https://github.com/huggingface/peft/releases/tag/v0.18.0）；github/github_release: 0.17.1（https://github.com/huggingface/peft/releases/tag/v0.17.1）；github/github_release: 0.17.0: SHiRA, MiSS, LoRA for MoE, and more（https://github.com/huggingface/peft/releases/tag/v0.17.0）；github/github_release: 0.16.0: LoRA-FA, RandLoRA, C³A, and much more（https://github.com/huggingface/peft/releases/tag/v0.16.0）；github/github_release: v0.15.2（https://github.com/huggingface/peft/releases/tag/v0.15.2）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "Feature Request: Improve offline support for custom architectures in get",
"url": "https://github.com/huggingface/peft/issues/3211"
},
{
"kind": "github_issue",
"source": "github",
"title": "Applying Dora to o_proj of Meta-Llama-3.1-8B results in NaN",
"url": "https://github.com/huggingface/peft/issues/2049"
},
{
"kind": "github_issue",
"source": "github",
"title": "Comparison of Different Fine-Tuning Techniques for Conversational AI",
"url": "https://github.com/huggingface/peft/issues/2310"
},
{
"kind": "github_issue",
"source": "github",
"title": "[BUG] peft 0.19 target_modules (str) use `set`",
"url": "https://github.com/huggingface/peft/issues/3229"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.19.1",
"url": "https://github.com/huggingface/peft/releases/tag/v0.19.1"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.19.0",
"url": "https://github.com/huggingface/peft/releases/tag/v0.19.0"
},
{
"kind": "github_release",
"source": "github",
"title": "0.18.1",
"url": "https://github.com/huggingface/peft/releases/tag/v0.18.1"
},
{
"kind": "github_release",
"source": "github",
"title": "0.18.0: RoAd, ALoRA, Arrow, WaveFT, DeLoRA, OSF, and more",
"url": "https://github.com/huggingface/peft/releases/tag/v0.18.0"
},
{
"kind": "github_release",
"source": "github",
"title": "0.17.1",
"url": "https://github.com/huggingface/peft/releases/tag/v0.17.1"
},
{
"kind": "github_release",
"source": "github",
"title": "0.17.0: SHiRA, MiSS, LoRA for MoE, and more",
"url": "https://github.com/huggingface/peft/releases/tag/v0.17.0"
},
{
"kind": "github_release",
"source": "github",
"title": "0.16.0: LoRA-FA, RandLoRA, C³A, and much more",
"url": "https://github.com/huggingface/peft/releases/tag/v0.16.0"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.15.2",
"url": "https://github.com/huggingface/peft/releases/tag/v0.15.2"
}
],
"status": "已收录 12 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "软件开发与交付",
"desc": "🤗 PEFT: State-of-the-art Parameter-Efficient Fine-Tuning.",
"effort": "安装已验证",
"forks": 2292,
"icon": "code",
"name": "peft 能力包",
"risk": "可发布",
"slug": "peft",
"stars": 21112,
"tags": [
"知识检索",
"知识库问答",
"结构化提取",
"断点恢复流程",
"评测体系"
],
"thumb": "gray",
"type": "Prompt Preview"
},
"manual": {
"markdown": "# https://github.com/huggingface/peft 项目说明书\n\n生成时间：2026-05-16 06:44:08 UTC\n\n## 目录\n\n- [PEFT概述与快速入门](#overview)\n- [核心模块与架构](#core-modules)\n- [配置系统](#config-system)\n- [LoRA及其变体实现](#lora-tuners)\n- [其他PEFT方法](#other-tuners)\n- [高级调谐器与实验性方法](#advanced-tuners)\n- [模型合并与融合工具](#merge-utils)\n- [量化支持与加速优化](#quantization)\n- [示例与用例概览](#examples-overview)\n- [开发者指南与贡献](#developer-guides)\n\n\n\n## PEFT概述与快速入门\n\n### 相关页面\n\n相关主题：[核心模块与架构](#core-modules), [示例与用例概览](#examples-overview)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/huggingface/peft/blob/main/README.md)\n- [src/peft/peft_model.py](https://github.com/huggingface/peft/blob/main/src/peft/peft_model.py)\n- [src/peft/helpers.py](https://github.com/huggingface/peft/blob/main/src/peft/helpers.py)\n- [src/peft/tuners/lora/model.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/lora/model.py)\n- [src/peft/tuners/tuners_utils.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/tuners_utils.py)\n- [src/peft/tuners/shira/model.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/shira/model.py)\n- [src/peft/tuners/gralora/model.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/gralora/model.py)\n- [src/peft/tuners/xlora/model.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/xlora/model.py)\n- [src/peft/tuners/miss/model.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/miss/model.py)\n- [src/peft/tuners/oft/model.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/oft/model.py)\n \n\n# PEFT概述与快速入门\n\n## 什么是PEFT\n\nPEFT（Parameter-Efficient Fine-Tuning，参数高效微调）是一个用于将大型预训练模型高效适配到各种下游应用的Python库。该库由Hugging Face团队维护，通过仅微调少量（额外）模型参数而非全部模型参数，显著降低计算和存储成本。资料来源：[README.md:1-10]()\n\nPEFT的核心设计目标是：\n\n| 目标 | 说明 |\n|------|------|\n| 参数效率 | 只需训练少量参数即可实现与全量微调相当的性能 |\n| 计算效率 | 大幅降低GPU显存占用和训练时间 |\n| 模块化设计 | 支持多种PEFT方法，便于扩展 |\n| 框架集成 | 无缝对接Transformers、Diffusers和Accelerate |\n\n## PEFT架构概览\n\nPEFT采用模块化架构，主要包含以下几个核心组件：\n\n```mermaid\ngraph TD\n A[PeftModel 基类] --> B[任务特定模型]\n A --> C[Tuner层]\n A --> D[配置管理]\n \n B --> B1[PeftModelForCausalLM]\n B --> B2[PeftModelForSeq2SeqLM]\n B --> B3[PeftModelForSequenceClassification]\n B --> B4[PeftModelForTokenClassification]\n B --> B5[PeftModelForQuestionAnswering]\n B --> B6[PeftModelForFeatureExtraction]\n \n C --> C1[LoraModel]\n C --> C2[ShiraModel]\n C --> C3[GraloraModel]\n C --> C4[XloraModel]\n C --> C5[MissModel]\n C --> C6[OFTModel]\n \n D --> D1[PeftConfig]\n D --> D2[get_peft_config]\n D --> D3[from_pretrained]\n```\n\n资料来源：[src/peft/peft_model.py:1-50]()\n\n## 支持的PEFT方法\n\nPEFT库支持多种参数高效微调方法，每种方法适用于不同的场景和模型架构。\n\n| 方法 | 简称 | 描述 | 适用场景 |\n|------|------|------|----------|\n| LoRA | Low-Rank Adaptation | 通过低秩矩阵分解近似权重更新 | 通用场景，支持大多数模型 |\n| QLoRA | Quantized LoRA | 结合量化技术的LoRA变体 | 大模型int4/int8量化训练 |\n| Prefix Tuning | 前缀微调 | 在输入前添加可学习前缀 | 生成任务 |\n| Prompt Tuning | 提示微调 | 仅学习软提示向量 | 极端参数高效场景 |\n| P-Tuning | P-tuning | 使用LSTM/MLP编码提示 | NLU任务 |\n| IA³ | Infused Adapter by Inhibiting Amplify | 注入式适配器 | 任务迁移 |\n| AdaLoRA | Adaptive LoRA | 自适应秩分配 | 资源受限场景 |\n| LoHa | LoRA with Hadamard Product | 使用Hadamard积 | 低参数场景 |\n| LoKR | LoRA with Kronecker Product | 使用Kronecker积 | 高效参数利用 |\n| OFT | Orthogonal Finetuning | 正交微调 | 扩散模型 |\n| SHiRA | 层级正则化适配器 | 分层正则化策略 | 多任务场景 |\n| GraLoRA | Gradient-aware LoRA | 梯度感知LoRA | 复杂任务 |\n| xLoRA | 专家混合LoRA | 多专家LoRA组合 | 大模型高效适配 |\n| MiSS | 模型分片共享 | 分片权重共享结构 | 资源受限训练 |\n\n资料来源：[src/peft/tuners/lora/model.py:1-30]()、[src/peft/tuners/shira/model.py:1-20]()、[src/peft/tuners/gralora/model.py:1-20]()\n\n## 安装指南\n\n### 基础安装\n\n```bash\npip install peft\n```\n\n### 完整安装（包含所有依赖）\n\n```bash\npip install peft[dev,models,diffusers,qualcomm]\n```\n\n### 从源码安装\n\n```bash\ngit clone https://github.com/huggingface/peft.git\ncd peft\npip install -e .\n```\n\n### GPU特定版本\n\n对于需要GPU支持的环境：\n\n```bash\npip install peft --extra-index-url https://download.pytorch.org/whl/cu118\n```\n\n## 快速入门\n\n### 基本使用流程\n\n使用PEFT进行模型微调的标准流程如下：\n\n```mermaid\ngraph LR\n A[加载基础模型] --> B[创建PeftConfig]\n B --> C[初始化PeftModel]\n C --> D[训练PeftModel]\n D --> E[保存Adapter]\n E --> F[加载Inference]\n```\n\n### LoRA快速示例\n\n以下示例展示如何使用LoRA方法对因果语言模型进行微调：\n\n```python\nfrom transformers import AutoModelForCausalLM, AutoTokenizer\nfrom peft import LoraConfig, get_peft_model, TaskType\n\n# 1. 加载基础模型\nbase_model = AutoModelForCausalLM.from_pretrained(\"facebook/opt-125m\")\n\n# 2. 配置LoRA参数\nlora_config = LoraConfig(\n task_type=TaskType.CAUSAL_LM, # 任务类型\n r=16, # LoRA秩\n lora_alpha=32, # LoRA alpha参数\n lora_dropout=0.05, # Dropout率\n target_modules=[\"q_proj\", \"v_proj\"], # 目标模块\n bias=\"none\",\n)\n\n# 3. 创建PeftModel\npeft_model = get_peft_model(base_model, lora_config)\n\n# 4. 查看可训练参数\npeft_model.print_trainable_parameters()\n# 输出: trainable params: 8388608 || all params: 125018880 || trainable%: 6.710\n\n# 5. 训练模型\n# ... 训练代码 ...\n\n# 6. 保存Adapter\npeft_model.save_pretrained(\"lora_adapter\")\n\n# 7. 推理时加载\nfrom peft import PeftModel\nmodel = AutoModelForCausalLM.from_pretrained(\"facebook/opt-125m\")\npeft_model = PeftModel.from_pretrained(model, \"lora_adapter\")\n```\n\n资料来源：[src/peft/helpers.py:1-50]()\n\n### 不同任务的模型适配\n\nPEFT为不同任务类型提供了专门的模型类：\n\n| 任务类型 | 模型类 | 典型应用 |\n|----------|--------|----------|\n| 因果语言模型 | `PeftModelForCausalLM` | 文本生成 |\n| Seq2Seq | `PeftModelForSeq2SeqLM` | 翻译、摘要 |\n| 序列分类 | `PeftModelForSequenceClassification` | 情感分析、文本分类 |\n| Token分类 | `PeftModelForTokenClassification` | NER、词性标注 |\n| 问答 | `PeftModelForQuestionAnswering` | 问答系统 |\n| 特征提取 | `PeftModelForFeatureExtraction` | 嵌入向量生成 |\n\n资料来源：[src/peft/peft_model.py:50-150]()\n\n### PeftModel.from_pretrained方法\n\n从预训练加载PEFT模型的核心参数：\n\n```python\nPeftModel.from_pretrained(\n model, # 基础模型 (torch.nn.Module)\n model_id, # 模型ID或本地路径 (str)\n adapter_name=\"default\", # Adapter名称 (str)\n is_trainable=False, # 是否可训练 (bool)\n config=None, # 配置对象 (PeftConfig, optional)\n autocast_adapter_dtype=True # 是否自动转换dtype (bool)\n)\n```\n\n资料来源：[src/peft/peft_model.py:150-200]()\n\n### QLoRA配置示例\n\n对于大模型，推荐使用QLoRA进行高效训练：\n\n```python\nfrom transformers import AutoModelForCausalLM, BitsAndBytesConfig\nfrom peft import prepare_model_for_kbit_training, LoraConfig, get_peft_model\n\n# 量化配置\nquantization_config = BitsAndBytesConfig(\n load_in_8bit=True,\n llm_int8_threshold=6.0,\n llm_int8_has_fp16_weight=False\n)\n\n# 加载量化模型\nmodel = AutoModelForCausalLM.from_pretrained(\n \"mistralai/Mistral-7B-Instruct-v0.1\",\n quantization_config=quantization_config,\n device_map=\"auto\"\n)\n\n# 准备kbit训练\nmodel = prepare_model_for_kbit_training(model)\n\n# 配置LoRA\nlora_config = LoraConfig(\n r=64,\n lora_alpha=16,\n target_modules=[\"q_proj\", \"v_proj\", \"k_proj\", \"o_proj\"],\n lora_dropout=0.05,\n bias=\"none\",\n task_type=TaskType.CAUSAL_LM\n)\n\n# 创建PeftModel\npeft_model = get_peft_model(model, lora_config)\n```\n\n## 配置详解\n\n### LoraConfig主要参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `r` | int | 8 | LoRA秩，决定低秩矩阵的维度 |\n| `lora_alpha` | int | 16 | 缩放因子，通常设为2倍r |\n| `lora_dropout` | float | 0.0 | LoRA层的Dropout率 |\n| `target_modules` | List[str] | None | 要应用LoRA的模块名 |\n| `bias` | str | \"none\" | 偏置更新策略: none/all/lora_only |\n| `fan_in_fan_out` | bool | False | 是否转置权重矩阵 |\n| `modules_to_save` | List[str] | None | 需要保存的额外模块 |\n| `init_lora_weights` | bool | True | 是否初始化LoRA权重 |\n\n资料来源：[src/peft/tuners/lora/model.py:30-80]()\n\n### 任务类型枚举\n\n```python\nclass TaskType:\n CAUSAL_LM = \"CAUSAL_LM\" # 因果语言模型\n SEQ_CLS = \"SEQ_CLS\" # 序列分类\n TOKEN_CLS = \"TOKEN_CLS\" # Token分类\n QUESTION_ANS = \"QUESTION_ANS\" # 问答\n FEATURE_EXTRACTION = \"FEATURE_EXTRACTION\" # 特征提取\n SEQ_2_SEQ_LM = \"SEQ_2_SEQ_LM\" # 序列到序列\n```\n\n## 高级功能\n\n### 模型合并与卸载\n\nPEFT支持将adapter与基础模型合并，或完全卸载adapter：\n\n```python\n# 合并并卸载（生成独立模型）\nmerged_model = peft_model.merge_and_unload()\n\n# 仅卸载adapter（返回原始基础模型）\nbase_model = peft_model.unload()\n```\n\n资料来源：[src/peft/tuners/tuners_utils.py:50-80]()\n\n### Adapter热切换\n\n使用hotswap功能在不重新加载模型的情况下切换adapter：\n\n```python\nfrom peft import hotswap_adapter\n\n# 热切换adapter\nhotswap_adapter(model, \"path-to-new-adapter\", adapter_name=\"default\")\n```\n\n### 多Adapter管理\n\nPEFT支持同时加载和使用多个adapter：\n\n```python\n# 加载多个adapter\nmodel.add_adapter(\"adapter_1\", config_1)\nmodel.add_adapter(\"adapter_2\", config_2)\n\n# 设置活动adapter\nmodel.set_adapter(\"adapter_1\")\n\n# 使用特定adapter推理\nmodel.eval()\n```\n\n### 辅助函数\n\nPEFT提供了多个辅助函数用于签名更新和模型检查：\n\n```python\nfrom peft.helpers import update_signature, check_if_peft_model\n\n# 更新forward/generate签名\nupdate_signature(peft_model, method=\"forward\")\nupdate_signature(peft_model, method=\"generate\")\nupdate_signature(peft_model, method=\"all\")\n\n# 检查是否为PEFT模型\nis_peft = check_if_peft_model(\"path-to-model\")\n```\n\n资料来源：[src/peft/helpers.py:1-100]()\n\n## 模型适配器注入机制\n\nPEFT通过`inject_adapter`方法将adapter注入到基础模型：\n\n```python\ndef inject_adapter(\n model, # 目标模型\n adapter_name, # Adapter名称\n autocast_adapter_dtype=True, # 自动转换dtype\n low_cpu_mem_usage=False, # 低内存使用\n state_dict=None # 可选的状态字典\n)\n```\n\n该过程会遍历模型模块，将目标层替换为对应的tuner层：\n\n```mermaid\ngraph TD\n A[inject_adapter调用] --> B[遍历模型模块]\n B --> C{检查模块类型}\n C -->|Linear层| D[创建TunerLayer]\n C -->|其他层| E[跳过]\n D --> F[替换原模块]\n F --> G[注册adapter]\n```\n\n资料来源：[src/peft/tuners/tuners_utils.py:80-120]()\n\n## 与主流框架的集成\n\n### Transformers集成\n\nPEFT与Hugging Face Transformers库深度集成，支持直接使用`AutoModel`系列加载预训练模型并应用PEFT：\n\n```python\nfrom transformers import AutoModelForCausalLM\nfrom peft import get_peft_model, LoraConfig\n\nmodel = AutoModelForCausalLM.from_pretrained(\"meta-llama/Llama-2-7b\")\npeft_model = get_peft_model(model, lora_config)\n```\n\n### Diffusers集成\n\n对于扩散模型，PEFT提供了专门的适配器：\n\n```python\nfrom diffusers import StableDiffusionPipeline\nfrom peft import OFTModel, OFTConfig\n\nconfig = OFTConfig(\n r=8,\n target_modules=[\"k_proj\", \"q_proj\", \"v_proj\"]\n)\nmodel.unet = OFTModel(model.unet, config, \"default\")\n```\n\n资料来源：[src/peft/tuners/miss/model.py:1-30]()、[src/peft/tuners/oft/model.py:1-30]()\n\n### Accelerate集成\n\n对于分布式训练和超大规模模型，PEFT支持与Accelerate配合使用：\n\n```python\nfrom accelerate import Accelerator\nfrom peft import get_peft_model\n\naccelerator = Accelerator()\nmodel = get_peft_model(model, config)\nmodel = accelerator.prepare_model(model)\n```\n\n## 性能基准\n\nPEFT方法在保持参数效率的同时，能够达到与全量微调相当甚至更好的性能：\n\n| 方法 | 可训练参数量 | 性能对比 |\n|------|-------------|----------|\n| 全量微调 | 100% | 基准 |\n| LoRA (r=8) | ~0.1-1% | 相当 |\n| QLoRA | ~0.1-1% | 略低于全量 |\n| Prefix Tuning | ~0.1% | 因任务而异 |\n| Prompt Tuning | ~0.01% | 需更多数据 |\n\n## 下一步\n\n- 深入阅读[PEFT支持的PEFT方法文档](https://huggingface.co/docs/peft)\n- 查看[示例代码库](https://github.com/huggingface/peft/tree/main/examples)\n- 了解[自定义Tuner开发指南](https://huggingface.co/docs/peft/developer_guides/custom_models)\n- 尝试使用[多模态模型微调](https://huggingface.co/docs/peft/multimodal)\n\n---\n\n\n\n## 核心模块与架构\n\n### 相关页面\n\n相关主题：[配置系统](#config-system), [LoRA及其变体实现](#lora-tuners)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/peft/peft_model.py](https://github.com/huggingface/peft/blob/main/src/peft/peft_model.py)\n- [src/peft/mixed_model.py](https://github.com/huggingface/peft/blob/main/src/peft/mixed_model.py)\n- [src/peft/helpers.py](https://github.com/huggingface/peft/blob/main/src/peft/helpers.py)\n- [src/peft/tuners/tuners_utils.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/tuners_utils.py)\n- [src/peft/tuners/shira/model.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/shira/model.py)\n- [src/peft/tuners/gralora/model.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/gralora/model.py)\n- [src/peft/tuners/xlora/model.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/xlora/model.py)\n- [src/peft/tuners/miss/model.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/miss/model.py)\n- [src/peft/tuners/oft/model.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/oft/model.py)\n- [src/peft/tuners/adamss/model.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/adamss/model.py)\n \n\n# 核心模块与架构\n\n## 概述\n\nPEFT（Parameter-Efficient Fine-Tuning）库的核心架构围绕适配器模式设计，通过在不修改原始预训练模型参数的情况下添加少量可训练参数来实现高效的模型微调。该架构采用模块化设计，核心组件包括PeftModel基类、各类任务专用模型类、通用适配器注入机制以及丰富的工具函数。资料来源：[src/peft/peft_model.py:1-200]()\n\n## 核心模块架构图\n\n```mermaid\ngraph TD\n A[PeftModel 基类] --> B[PeftModelForSequenceClassification]\n A --> C[PeftModelForQuestionAnswering]\n A --> D[PeftModelForTokenClassification]\n A --> E[PeftModelForSeq2SeqLM]\n A --> F[PeftModelForFeatureExtraction]\n G[BaseTuner] --> A\n H[TunersUtils] --> G\n I[各Tuner模型类] --> H\n J[ShiraModel] --> I\n K[GraloraModel] --> I\n L[XloraModel] --> I\n M[MissModel] --> I\n N[OFTModel] --> I\n O[AdamssModel] --> I\n```\n\n## PeftModel 基类\n\n### 类职责与定位\n\nPeftModel是整个库的核心基类，负责管理适配器的加载、切换、合并与卸载。它封装了底层的基础模型，并提供了统一的接口供各任务类型模型继承使用。资料来源：[src/peft/peft_model.py:100-150]()\n\n### 主要方法\n\n| 方法名 | 功能描述 | 返回类型 |\n|--------|----------|----------|\n| `from_pretrained()` | 从预训练路径加载PEFT模型和适配器 | `PeftModel` |\n| `merge_and_unload()` | 合并适配器权重到基础模型并卸载适配器 | `torch.nn.Module` |\n| `unload()` | 返回基础模型，移除所有PEFT模块 | `torch.nn.Module` |\n| `inject_adapter()` | 注入适配器层并替换目标模块 | `None` |\n\n### from_pretrained 方法参数\n\n```python\n@classmethod\ndef from_pretrained(\n cls,\n model: torch.nn.Module,\n model_id: str or os.PathLike,\n adapter_name: str = \"default\",\n is_trainable: bool = False,\n config: PeftConfig = None,\n autocast_adapter_dtype: bool = True,\n **kwargs\n) -> PeftModel\n```\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `model` | `torch.nn.Module` | 必需 | 被适配的基础模型 |\n| `model_id` | `str` 或 `os.PathLike` | 必需 | PEFT配置的模型ID或本地路径 |\n| `adapter_name` | `str` | `\"default\"` | 适配器名称，支持加载多个适配器 |\n| `is_trainable` | `bool` | `False` | 是否训练模式，False时适配器被冻结 |\n| `config` | `PeftConfig` | `None` | 预定义的配置对象，与model_id互斥 |\n| `autocast_adapter_dtype` | `bool` | `True` | 是否自动转换适配器数据类型 |\n\n资料来源：[src/peft/peft_model.py:150-200]()\n\n## 任务专用模型类\n\nPEFT针对不同任务类型提供了专用的模型封装类，每个类针对特定任务进行了输入输出接口的适配。\n\n### 模型类列表与继承关系\n\n```mermaid\ngraph LR\n A[PeftModel] --> B[PeftModelForSequenceClassification]\n A --> C[PeftModelForQuestionAnswering]\n A --> D[PeftModelForTokenClassification]\n A --> E[PeftModelForSeq2SeqLM]\n A --> F[PeftModelForFeatureExtraction]\n```\n\n### PeftModelForSequenceClassification\n\n用于序列分类任务（如情感分析），自动配置分类层。构造函数中定义了默认的分类器模块名称列表：\n\n```python\nclassifier_module_names = [\"classifier\", \"score\"]\n```\n\n资料来源：[src/peft/peft_model.py:50-80]()\n\n### PeftModelForQuestionAnswering\n\n用于问答任务，配置问答输出层名称：\n\n```python\nqa_module_names = [\"qa_outputs\"]\n```\n\n资料来源：[src/peft/peft_model.py:30-50]()\n\n### PeftModelForTokenClassification\n\n用于令牌级分类任务（如命名实体识别），使用与序列分类相同的分类器模块名称：\n\n```python\nclassifier_module_names = [\"classifier\", \"score\"]\n```\n\n资料来源：[src/peft/peft_model.py:180-210]()\n\n### PeftModelForSeq2SeqLM\n\n用于序列到序列生成任务（如翻译、摘要），继承基类并额外保存生成相关方法引用：\n\n```python\nself.base_model_prepare_inputs_for_generation = self.base_model.prepare_inputs_for_generation\nself.base_model_prepare_encoder_decoder_kwargs_for_generation = (\n self.base_model._prepare_encoder_decoder_kwargs_for_generation\n)\n```\n\n资料来源：[src/peft/peft_model.py:230-260]()\n\n### PeftModelForFeatureExtraction\n\n用于特征提取任务，支持标准forward接口并提供灵活的输入处理能力。\n\n资料来源：[src/peft/peft_model.py:80-110]()\n\n## BaseTuner 与适配器注入机制\n\n### inject_adapter 方法\n\n`inject_adapter` 是将适配器层注入到目标模型的核心方法，负责创建适配器层并替换原模型中的目标模块。\n\n```python\ndef inject_adapter(\n self,\n model: nn.Module,\n adapter_name: str,\n autocast_adapter_dtype: bool = True,\n low_cpu_mem_usage: bool = False,\n state_dict: Optional[dict[str, torch.Tensor]] = None,\n) -> None:\n```\n\n| 参数名 | 类型 | 说明 |\n|--------|------|------|\n| `model` | `nn.Module` | 需要注入适配器的模型 |\n| `adapter_name` | `str` | 适配器名称 |\n| `autocast_adapter_dtype` | `bool` | 是否自动转换适配器数据类型 |\n| `low_cpu_mem_usage` | `bool` | 是否在元设备上创建空适配器权重以加速加载 |\n| `state_dict` | `Optional[dict]` | 可选的预定义状态字典 |\n\n资料来源：[src/peft/tuners/tuners_utils.py:100-150]()\n\n### _check_target_module_compatibility 方法\n\n该方法防止将LoRA等适配器应用于不兼容的模块（如Mamba架构）：\n\n```python\ndef _check_target_module_compatiblity(\n self, peft_config: PeftConfig, model: nn.Module, target_name: str\n):\n _check_lora_target_modules_mamba(peft_config, model, target_name)\n```\n\n资料来源：[src/peft/tuners/tuners_utils.py:90-95]()\n\n## 各类型Tuner模型\n\n### Tuner模型通用架构\n\n每种Tuner模型（如SHiRA、GrALoRA、xLoRA、MiSS、OFT、Adamss）都遵循统一的架构模式：\n\n```mermaid\ngraph TD\n A[BaseTuner] --> B[各TunerModel类]\n B --> C{_create_and_replace}\n C -->|Linear层| D[update_layer]\n C -->|非Linear层| E[_create_new_module]\n D --> F[替换原模块]\n E --> F\n```\n\n### SHiRA 模型\n\nSHiRA（Structured HieraRchy Adapter）模型具有以下特征：\n\n| 属性 | 值 |\n|------|-----|\n| `prefix` | `\"shira_\"` |\n| `tuner_layer_cls` | `ShiraLayer` |\n| `mask_type` | 支持 `\"random\"` 类型 |\n\n创建新模块时，支持通过 `random_seed` 参数控制随机性：\n\n```python\nkwargs[\"random_seed\"] = shira_config.random_seed\n```\n\n资料来源：[src/peft/tuners/shira/model.py:30-80]()\n\n### Gralora 模型\n\nGradoRA模型专注于梯度相关的高效微调：\n\n| 属性 | 值 |\n|------|-----|\n| `prefix` | `\"gralora_\"` |\n| `tuner_layer_cls` | `GraloraLayer` |\n\n对于Linear层，直接调用 `update_layer` 方法进行参数更新：\n\n```python\nif isinstance(target, Linear):\n target.update_layer(\n adapter_name,\n current_key,\n r=r,\n config=gralora_config,\n )\n```\n\n资料来源：[src/peft/tuners/gralora/model.py:40-70]()\n\n### xLoRA 模型\n\nxLoRA是一种支持混合适配器配置的模型类型：\n\n```python\ndef __init__(\n self,\n model: nn.Module,\n config: Union[dict[str, XLoraConfig], XLoraConfig],\n adapter_name: str,\n torch_device: Optional[str] = None,\n ephemeral_gpu_offload: bool = False,\n autocast_adapter_dtype: bool = True,\n **kwargs,\n) -> None:\n```\n\n| 参数名 | 类型 | 说明 |\n|--------|------|------|\n| `config` | `XLoraConfig` 或 `dict` | 支持单个或多个适配器配置 |\n| `torch_device` | `str` | 加载适配器的目标设备 |\n| `ephemeral_gpu_offload` | `bool` | 是否启用临时GPU卸载 |\n\n资料来源：[src/peft/tuners/xlora/model.py:40-80]()\n\n### MiSS 模型\n\nMiSS（Multi-Adapter Integration for Stable Diffusion）专为扩散模型设计：\n\n| 属性 | 值 |\n|------|-----|\n| `prefix` | `\"miss_\"` |\n| `tuner_layer_cls` | `MissLayer` |\n| `target_module_mapping` | `TRANSFORMERS_MODELS_TO_MISS_TARGET_MODULES_MAPPING` |\n\n创建新模块时的处理逻辑区分普通层和MissLayer：\n\n```python\nif not isinstance(target, MissLayer):\n new_module = self._create_new_module(miss_config, adapter_name, target, **kwargs)\n # 新适配器默认不训练\n new_module.requires_grad_(False)\n self._replace_module(parent, target_name, new_module, target)\nelse:\n target.update_layer(adapter_name, config=miss_config, **kwargs)\n```\n\n资料来源：[src/peft/tuners/miss/model.py:40-90]()\n\n### OFT 模型\n\nOFT（Orthogonal Fine-Tuning）模型保持参数的正交性约束：\n\n| 属性 | 值 |\n|------|-----|\n| `prefix` | `\"oft_\"` |\n| `tuner_layer_cls` | `OFTLayer` |\n| `loaded_in_8bit` | 支持8位量化加载 |\n\n```python\nkwargs = {\n \"r\": oft_config.r,\n \"fan_in_fan_out\": oft_config.fan_in_fan_out,\n \"loaded_in_8bit\": getattr(self.model, \"is_loaded_in_8bit\", False)\n}\n```\n\n资料来源：[src/peft/tuners/oft/model.py:40-80]()\n\n### Adamss 模型\n\nAdamss模型采用多子空间注意力机制：\n\n| 属性 | 值 |\n|------|-----|\n| `prefix` | `\"adamss_\"` |\n| `tuner_layer_cls` | `(AdamssLayer,)` |\n| `_asa_total_subspaces` | ASA子空间跟踪字典 |\n\n初始化时在BaseTuner注入适配器之前创建ASA跟踪属性：\n\n```python\ndef __init__(\n self, model, config, adapter_name, low_cpu_mem_usage: bool = False, state_dict: Optional[dict] = None\n) -> None:\n self._asa_total_subspaces = {}\n super().__init__(model, config, adapter_name, low_cpu_mem_usage, state_dict)\n```\n\n资料来源：[src/peft/tuners/adamss/model.py:50-70]()\n\n## 工具函数模块\n\n### helpers.py 核心功能\n\n#### check_if_peft_model\n\n检测指定路径的模型是否为PEFT模型：\n\n```python\ndef check_if_peft_model(model_name_or_path: str) -> bool:\n is_peft_model = True\n try:\n PeftConfig.from_pretrained(model_name_or_path)\n except Exception:\n is_peft_model = False\n return is_peft_model\n```\n\n资料来源：[src/peft/helpers.py:40-60]()\n\n#### update_signature\n\n更新PeftModel的接口签名以包含父类方法的参数：\n\n```python\ndef update_signature(model: PeftModel, method: str = \"all\") -> None:\n if method == \"forward\":\n update_forward_signature(model)\n elif method == \"generate\":\n update_generate_signature(model)\n elif method == \"all\":\n update_forward_signature(model)\n update_generate_signature(model)\n```\n\n| method参数值 | 效果 |\n|-------------|------|\n| `\"forward\"` | 仅更新forward方法签名 |\n| `\"generate\"` | 仅更新generate方法签名 |\n| `\"all\"` | 同时更新两者 |\n\n资料来源：[src/peft/helpers.py:1-30]()\n\n#### rescale_adapter_scale\n\n上下文管理器，用于临时调整适配器缩放因子：\n\n```python\n@contextmanager\ndef rescale_adapter_scale(model, multiplier):\n # 临时修改缩放值\n yield\n # 恢复原始值\n```\n\n资料来源：[src/peft/helpers.py:60-90]()\n\n#### update_forward_signature\n\n当forward签名仅包含 `*args` 和 `**kwargs` 时，用基类的完整签名替换：\n\n```python\ncurrent_signature = inspect.signature(model.forward)\nif (\n len(current_signature.parameters) == 2\n and \"args\" in current_signature.parameters\n and \"kwargs\" in current_signature.parameters\n):\n forward = deepcopy(model.forward.__func__)\n update_wrapper(forward, type(model.get_base_model()).forward, ...)\n```\n\n资料来源：[src/peft/helpers.py:90-130]()\n\n#### update_generate_signature\n\n类似地更新generate方法签名，支持处理单参数（仅kwargs）情况：\n\n```python\nif (\n len(current_signature.parameters) == 2\n and \"args\" in current_signature.parameters\n and \"kwargs\" in current_signature.parameters\n) or (len(current_signature.parameters) == 1 and \"kwargs\" in current_signature.parameters):\n generate = deepcopy(model.generate.__func__)\n update_wrapper(generate, type(model.get_base_model()).generate, ...)\n```\n\n资料来源：[src/peft/helpers.py:130-170]()\n\n## MixedModel 混合适配器模型\n\nMixedModel支持同时使用多个不同类型的PEFT适配器。其 `from_pretrained` 方法架构如下：\n\n```mermaid\ngraph LR\n A[from_pretrained] --> B[load config]\n B --> C[PEFT_TYPE_TO_MIXED_MODEL_MAPPING]\n C --> D[创建MixedModel实例]\n```\n\n```python\n@classmethod\ndef from_pretrained(\n cls,\n model: nn.Module,\n model_id: str or os.PathLike,\n adapter_name: str = \"default\",\n is_trainable: bool = False,\n config: PeftConfig = None,\n low_cpu_mem_usage: bool = False,\n **kwargs,\n) -> PeftModel:\n```\n\n资料来源：[src/peft/mixed_model.py:100-150]()\n\n## 适配器生命周期管理\n\n```mermaid\ngraph TD\n A[from_pretrained] --> B[inject_adapter]\n B --> C[创建新模块或更新现有层]\n C --> D[active_adapters管理]\n D --> E{merge_and_unload?}\n E -->|是| F[合并权重并卸载]\n E -->|否| G[继续训练/推理]\n F --> H[返回基础模型]\n G --> I[unload: 返回纯基础模型]\n```\n\n### merge_and_unload 与 unload 区别\n\n| 方法 | 合并权重 | 卸载适配器 | 返回内容 |\n|------|----------|------------|----------|\n| `merge_and_unload()` | ✅ | ✅ | 合并后的模型 |\n| `unload()` | ❌ | ✅ | 原始基础模型 |\n\n```python\ndef merge_and_unload(self, progressbar: bool = False, safe_merge: bool = False, adapter_names: List = None):\n return self._unload_and_optionally_merge(\n progressbar=progressbar, safe_merge=safe_merge, adapter_names=adapter_names\n )\n\ndef unload(self) -> torch.nn.Module:\n return self._unload_and_optionally_merge(merge=False)\n```\n\n资料来源：[src/peft/tuners/tuners_utils.py:60-90]()\n\n## 总结\n\nPEFT库的核心架构采用分层设计模式：\n\n1. **PeftModel基类** 提供统一的适配器管理接口\n2. **任务专用模型类** 针对不同NLP任务进行接口适配\n3. **BaseTuner与TunersUtils** 实现适配器注入的核心逻辑\n4. **各类TunerModel** 实现不同的高效微调算法（LoRA、SHiRA、GrALoRA、xLoRA、MiSS、OFT、Adamss等）\n5. **helpers工具模块** 提供运行时签名更新、模型检测等辅助功能\n\n这种架构设计使得PEFT能够以统一的方式支持多种参数高效微调算法，同时保持良好的可扩展性以接入新的微调方法。\n\n---\n\n\n\n## 配置系统\n\n### 相关页面\n\n相关主题：[核心模块与架构](#core-modules), [LoRA及其变体实现](#lora-tuners)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/peft/config.py](https://github.com/huggingface/peft/blob/main/src/peft/config.py)\n- [src/peft/utils/peft_types.py](https://github.com/huggingface/peft/blob/main/src/peft/utils/peft_types.py)\n- [src/peft/utils/constants.py](https://github.com/huggingface/peft/blob/main/src/peft/utils/constants.py)\n- [src/peft/peft_model.py](https://github.com/huggingface/peft/blob/main/src/peft/peft_model.py)\n- [src/peft/tuners/tuners_utils.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/tuners_utils.py)\n- [src/peft/mixed_model.py](https://github.com/huggingface/peft/blob/main/src/peft/mixed_model.py)\n \n\n# 配置系统\n\nPEFT（Parameter-Efficient Fine-Tuning）库的配置系统是整个框架的核心基础设施，负责定义、管理和序列化各种参数高效微调方法的配置参数。该系统通过统一的配置类层次结构，为不同的微调技术（如 LoRA、Prefix Tuning、AdaLoRA 等）提供了一致的配置接口，同时保持了各方法特有的参数定制能力。\n\n## 系统架构概述\n\nPEFT 配置系统采用分层设计模式，核心层定义了所有配置类的基类和枚举类型，方法层则实现了各种特定微调技术的配置类。这种设计确保了配置的通用性与扩展性的平衡。\n\n```mermaid\ngraph TB\n subgraph 核心层\n PeftConfig[PeftConfig 基类]\n PeftType[PeftType 枚举]\n TaskType[TaskType 枚举]\n end\n \n subgraph 配置映射层\n PEFT_TYPE_TO_CONFIG_MAPPING[PEFT_TYPE_TO_CONFIG_MAPPING]\n PEFT_TYPE_TO_MIXED_MODEL_MAPPING[PEFT_TYPE_TO_MIXED_MODEL_MAPPING]\n end\n \n subgraph 方法层\n LoraConfig[LoRA 配置]\n PrefixTuningConfig[Prefix Tuning 配置]\n PromptTuningConfig[Prompt Tuning 配置]\n AdaLoraConfig[AdaLoRA 配置]\n IA3Config[IA³ 配置]\n LoHaConfig[LoHa 配置]\n LokrConfig[LoKr 配置]\n VeraConfig[VeRA 配置]\n HieraConfig[HiRA 配置]\n end\n \n subgraph 应用层\n PeftModel[PeftModel]\n MixedModel[MixedModel]\n end\n \n PeftConfig --> PEFT_TYPE_TO_CONFIG_MAPPING\n PeftConfig --> 配置映射层\n 配置映射层 --> 方法层\n 方法层 --> 应用层\n```\n\n## 核心配置类\n\n### PeftConfig 基类\n\n`PeftConfig` 是所有 PEFT 配置类的基类，封装了微调配置的基本属性和序列化逻辑。该类继承自 `transformers.PretrainedConfig`，因此具备标准的模型配置保存和加载功能。\n\n#### 核心属性\n\n| 属性名 | 类型 | 说明 | 默认值 |\n|--------|------|------|--------|\n| `peft_type` | `PeftType` | PEFT 方法类型 | 必需 |\n| `task_type` | `TaskType` | 任务类型 | 可选 |\n| `inference_mode` | `bool` | 是否为推理模式 | `False` |\n| `r` | `int` | 秩（用于 LoRA 等方法） | `8` |\n| `target_modules` | `Optional[Union[List[str], str]]` | 目标模块名称 | `None` |\n| `modules_to_save` | `Optional[List[str]]` | 需保存参数的额外模块 | `None` |\n| `fan_in_fan_out` | `bool` | 是否转置权重 | `False` |\n\n资料来源：[src/peft/config.py](https://github.com/huggingface/peft/blob/main/src/peft/config.py)\n\n#### 关键方法\n\n`PeftConfig` 提供了以下核心方法用于配置管理：\n\n- `save_pretrained(save_directory)` - 将配置保存到指定目录\n- `from_pretrained(pretrained_model_name_or_path, **kwargs)` - 从预训练路径加载配置\n- `to_dict()` - 将配置转换为字典格式\n\n### PeftType 枚举\n\n`PeftType` 枚举定义了 PEFT 库支持的所有微调方法类型：\n\n| 枚举值 | 说明 | 对应配置类 |\n|--------|------|-----------|\n| `LORA` | Low-Rank Adaptation | `LoraConfig` |\n| `PREFIX_TUNING` | Prefix Tuning | `PrefixTuningConfig` |\n| `PROMPT_TUNING` | Prompt Tuning | `PromptTuningConfig` |\n| `ADALORA` | Adaptive LoRA | `AdaLoraConfig` |\n| `ADAPTION_PROMPT` | Adaption Prompt | `AdaptionPromptConfig` |\n| `IA3` | (IA)³ | `IA3Config` |\n| `LOHA` | LoHA | `LoHaConfig` |\n| `LOKR` | LoKr | `LokrConfig` |\n| `VERA` | VeRA | `VeraConfig` |\n| `HIRA` | HiRA | `HiraConfig` |\n| `OFT` | OFT | `OftConfig` |\n| `POLY` | Poly | `PolyConfig` |\n| `LINEAR` | Linear | `LinearConfig` |\n| `MANUAL` | Manual | `ManualConfig` |\n\n资料来源：[src/peft/utils/peft_types.py](https://github.com/huggingface/peft/blob/main/src/peft/utils/peft_types.py)\n\n### TaskType 枚举\n\n`TaskType` 枚举定义了支持的模型任务类型，用于配置与具体任务的适配：\n\n| 枚举值 | 说明 | 适用模型类 |\n|--------|------|-----------|\n| `SEQ_CLS` | 序列分类 | `PeftModelForSequenceClassification` |\n| `SEQ_2_SEQ_LM` | 序列到序列语言模型 | `PeftModelForSeq2SeqLM` |\n| `CAUSAL_LM` | 因果语言模型 | `PeftModelForCausalLM` |\n| `TOKEN_CLS` | Token 分类 | `PeftModelForTokenClassification` |\n| `QUESTION_ANS` | 问答任务 | `PeftModelForQuestionAnswering` |\n| `FEATURE_EXTRACTION` | 特征提取 | `PeftModelForFeatureExtraction` |\n\n资料来源：[src/peft/peft_model.py](https://github.com/huggingface/peft/blob/main/src/peft/peft_model.py)\n\n## 配置映射机制\n\nPEFT 使用两个关键的映射字典来管理配置类型与实际配置类之间的对应关系。\n\n### PEFT_TYPE_TO_CONFIG_MAPPING\n\n此映射字典建立了 `PeftType` 枚举值与具体配置类之间的关联：\n\n```python\nPEFT_TYPE_TO_CONFIG_MAPPING: dict[PeftType, type[PeftConfig]] = {\n PeftType.LORA: LoraConfig,\n PeftType.PROMPT_TUNING: PromptTuningConfig,\n PeftType.PREFIX_TUNING: PrefixTuningConfig,\n # ... 其他映射\n}\n```\n\n### PEFT_TYPE_TO_MIXED_MODEL_MAPPING\n\n此映射用于混合模型场景，关联 `PeftType` 与混合模型类：\n\n```python\nPEFT_TYPE_TO_MIXED_MODEL_MAPPING: dict[PeftType, type[PeftMixedModel]] = {\n PeftType.LORA: PeftMixedModel,\n # ... 其他映射\n}\n```\n\n资料来源：[src/peft/mixed_model.py](https://github.com/huggingface/peft/blob/main/src/peft/mixed_model.py)\n\n## 配置加载流程\n\n配置加载遵循统一的流程，支持从 Hugging Face Hub 或本地目录加载配置。\n\n```mermaid\nsequenceDiagram\n participant 用户\n participant PeftConfig\n participant HF Hub\n participant 本地文件系统\n \n 用户->>PeftConfig: from_pretrained(model_id)\n PeftConfig->>PeftConfig: 确定配置类型\n alt 模型在 Hub 上\n PeftConfig->>HF Hub: 下载配置文件\n HF Hub-->>PeftConfig: 返回配置数据\n else 本地模型\n PeftConfig->>本地文件系统: 读取配置文件\n 本地文件系统-->>PeftConfig: 返回配置数据\n end\n PeftConfig->>PeftConfig: 解析并实例化配置对象\n PeftConfig-->>用户: 返回 PeftConfig 实例\n```\n\n### 加载参数说明\n\n| 参数名 | 类型 | 说明 | 默认值 |\n|--------|------|------|--------|\n| `pretrained_model_name_or_path` | `str` | 模型标识或路径 | 必需 |\n| `subfolder` | `str` | 子文件夹路径 | `\"\"` |\n| `revision` | `str` | Git 修订版本 | `\"main\"` |\n| `cache_dir` | `Optional[str]` | 缓存目录 | `None` |\n| `force_download` | `bool` | 强制重新下载 | `False` |\n| `resume_download` | `bool` | 恢复下载 | `False` |\n| `proxies` | `Optional[dict]` | 代理设置 | `None` |\n| `token` | `Optional[Union[str, bool]]` | HuggingFace Hub Token | `None` |\n\n## 方法特定配置\n\n### LoRA 配置\n\n`LoraConfig` 是最常用的配置类，继承自 `PeftConfig` 并添加了 LoRA 方法特有的参数：\n\n```python\nclass LoraConfig(PeftConfig):\n def __init__(\n self,\n r: int = 8,\n lora_alpha: int = 8,\n lora_dropout: float = 0.0,\n target_modules: Optional[Union[List[str], str]] = None,\n bias: str = \"none\",\n inference_mode: bool = False,\n # ... 其他参数\n ):\n```\n\n| 参数名 | 类型 | 说明 | 默认值 |\n|--------|------|------|--------|\n| `r` | `int` | LoRA 秩（低秩矩阵维度） | `8` |\n| `lora_alpha` | `int` | LoRA 缩放因子 | `8` |\n| `lora_dropout` | `float` | LoRA 层 Dropout 率 | `0.0` |\n| `bias` | `str` | 偏置训练策略 | `\"none\"` |\n| `task_type` | `TaskType` | 任务类型 | 可选 |\n| `modules_to_save` | `Optional[List[str]]` | 需训练的其他模块 | `None` |\n\n### Prefix Tuning 配置\n\n`PrefixTuningConfig` 用于 Prefix Tuning 方法：\n\n```python\nclass PrefixTuningConfig(PeftConfig):\n def __init__(\n self,\n num_virtual_tokens: int = 20,\n token_dim: int = None,\n num_transformer_submodules: int = 1,\n num_attention_heads: int = 1,\n num_layers: int = 1,\n prefix_projection: bool = False,\n # ... 其他参数\n ):\n```\n\n| 参数名 | 类型 | 说明 | 默认值 |\n|--------|------|------|--------|\n| `num_virtual_tokens` | `int` | 虚拟 token 数量 | `20` |\n| `token_dim` | `int` | token 维度 | 自动 |\n| `num_transformer_submodules` | `int` | Transformer 子模块数 | `1` |\n| `num_attention_heads` | `int` | 注意力头数 | 自动 |\n| `prefix_projection` | `bool` | 是否投影前缀 | `False` |\n\n## 配置验证机制\n\n### 目标模块兼容性检查\n\n`tuners_utils.py` 中的 `_check_target_module_compatiblity` 方法负责验证目标模块的兼容性：\n\n```python\ndef _check_target_module_compatiblity(self, peft_config: PeftConfig, model: nn.Module, target_name: str):\n \"\"\"\n Prevent applying LoRA to incompatible modules in specific architectures (e.g., Mamba).\n \"\"\"\n _check_lora_target_modules_mamba(peft_config, model, target_name)\n```\n\n该方法防止在特定架构（如 Mamba）上应用不兼容的 LoRA 配置。\n\n资料来源：[src/peft/tuners/tuners_utils.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/tuners_utils.py)\n\n### 模块名称验证\n\n配置系统对以下模块名称进行特殊处理：\n\n- **分类任务**：`\"classifier\"`, `\"score\"`\n- **问答任务**：`\"qa_outputs\"`\n- **Token 分类**：`\"classifier\"`, `\"score\"`\n\n资料来源：[src/peft/peft_model.py](https://github.com/huggingface/peft/blob/main/src/peft/peft_model.py)\n\n## 配置的动态更新\n\nPEFT 支持在运行时动态更新配置参数，通过 `inject_adapter` 方法实现：\n\n```python\ndef inject_adapter(\n self,\n model: nn.Module,\n adapter_name: str,\n autocast_adapter_dtype: bool = True,\n low_cpu_mem_usage: bool = False,\n state_dict: Optional[dict[str, torch.Tensor]] = None,\n) -> None:\n```\n\n此方法创建适配器层并替换目标模块，允许在不重新初始化模型的情况下添加新的适配器配置。\n\n## 热插拔配置\n\n`hotswap.py` 模块支持配置的动态热切换：\n\n```python\ndef hotswap_adapter(\n model: \"PeftModel\",\n model_name_or_path: str,\n adapter_name: str = \"default\",\n torch_device: Optional[str] = None,\n **kwargs,\n) -> None:\n```\n\n该功能允许在推理过程中替换适配器配置，无需重新加载整个模型。\n\n资料来源：[src/peft/utils/hotswap.py](https://github.com/huggingface/peft/blob/main/src/peft/utils/hotswap.py)\n\n## 配置序列化\n\n配置系统支持将配置保存为标准格式，便于分享和复用：\n\n### 保存流程\n\n1. 调用 `save_pretrained(save_directory)` 方法\n2. 创建目标目录（如不存在）\n3. 将配置转换为 JSON 格式\n4. 保存为 `config.json` 文件\n5. 返回保存的文件路径\n\n### 加载流程\n\n1. 调用 `from_pretrained(pretrained_model_name_or_path)`\n2. 自动检测 PEFT 配置类型\n3. 实例化对应的配置类\n4. 返回配置对象\n\n## 目标模块映射\n\n每种微调方法都定义了默认的目标模块映射，确保在未知模型架构时也能正常工作：\n\n| 方法 | 映射变量 | 典型目标模块 |\n|------|----------|--------------|\n| LoRA | `TRANSFORMERS_MODELS_TO_LORA_TARGET_MODULES_MAPPING` | `q_proj`, `v_proj`, `k_proj`, `o_proj` |\n| IA³ | `TRANSFORMERS_MODELS_TO_IA3_TARGET_MODULES_MAPPING` | 针对特定层的向量 |\n| Prefix Tuning | `TRANSFORMERS_MODELS_TO_PREFIX_TUNING_TARGET_MODULES_MAPPING` | 全模型层级 |\n\n## 适配器管理\n\n配置系统与适配器管理系统紧密集成，支持多适配器配置：\n\n### 适配器注册\n\n```python\nclass PeftModel:\n def __init__(self, model, peft_config, adapter_name: str = \"default\", **kwargs):\n # 默认适配器名为 \"default\"\n```\n\n### 适配器切换\n\n通过 `active_peft_config` 属性访问当前激活的适配器配置：\n\n```python\npeft_config = self.active_peft_config\nif not peft_config.is_prompt_learning:\n if peft_config.peft_type == PeftType.LORA:\n # LoRA 特定处理\n```\n\n## 总结\n\nPEFT 配置系统通过以下设计原则实现了灵活且可扩展的配置管理：\n\n1. **分层架构**：基类提供通用接口，派生类实现特定方法配置\n2. **类型安全**：通过枚举类型确保配置值的有效性\n3. **映射驱动**：使用字典映射实现配置类型与实现类的解耦\n4. **序列化支持**：与 Hugging Face 生态系统无缝集成\n5. **运行时动态性**：支持适配器的热插拔和动态更新\n\n这套配置系统使得用户能够以统一的方式使用不同的参数高效微调方法，同时为高级用户提供了充分的定制能力。\n\n---\n\n\n\n## LoRA及其变体实现\n\n### 相关页面\n\n相关主题：[其他PEFT方法](#other-tuners), [量化支持与加速优化](#quantization)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/peft/tuners/lora/__init__.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/lora/__init__.py)\n- [src/peft/tuners/lora/config.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/lora/config.py)\n- [src/peft/tuners/lora/layer.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/lora/layer.py)\n- [src/peft/tuners/lora/model.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/lora/model.py)\n- [src/peft/tuners/lora/dora.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/lora/dora.py)\n- [src/peft/tuners/adalora/__init__.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/adalora/__init__.py)\n- [src/peft/tuners/vera/__init__.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/vera/__init__.py)\n \n\n# LoRA及其变体实现\n\n## 概述\n\nLoRA（Low-Rank Adaptation）是一种高效的参数微调技术，通过在预训练模型的权重矩阵旁边添加低秩分解矩阵来实现参数高效微调。PEFT库实现了LoRA及其多种变体，包括DoRA、AdaLoRA和VeRA，每种变体在参数效率和适应性方面有不同的优化策略。\n\n## LoRA核心架构\n\n### 核心技术原理\n\nLoRA的核心思想是将预训练权重矩阵 $W_0 \\in \\mathbb{R}^{d \\times k}$ 的更新表示为低秩分解形式：\n\n$$W' = W_0 + \\Delta W = W_0 + BA$$\n\n其中 $B \\in \\mathbb{R}^{d \\times r}$，$A \\in \\mathbb{R}^{r \\times k}$，$r \\ll \\min(d, k)$。\n\n### 模块结构\n\n```\ngraph TD\n A[预训练模型 Linear层] --> B[LoRA包装]\n B --> C[LoraLayer]\n C --> D[Lora_A: 降维矩阵]\n C --> E[Lora_B: 升维矩阵]\n C --> F[scaling缩放因子]\n D --> G[前向传播: Wx + BAx]\n```\n\n## LoraConfig配置详解\n\nLoraConfig是LoRA微调的核心配置类，主要参数如下：\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| r | int | 8 | 低秩矩阵的秩 |\n| lora_alpha | int | 16 | 缩放因子，通常设为r的两倍 |\n| lora_dropout | float | 0.0 | LoRA层的dropout率 |\n| target_modules | Optional[List[str]] | None | 需要应用LoRA的模块名称 |\n| bias | str | \"none\" | bias处理方式: none/lora_only/all |\n| fan_in_fan_out | bool | False | 是否转置权重 |\n| init_weights | bool | True | 是否初始化LoRA权重 |\n\n## LoraLayer实现\n\nLoraLayer是LoRA的核心计算层，主要包含以下组件：\n\n```python\n# 资料来源：src/peft/tuners/lora/layer.py\nclass LoraLayer:\n prefix: str = \"lora_\"\n # 核心低秩矩阵\n lora_A: nn.Parameter # 降维矩阵\n lora_B: nn.Parameter # 升维矩阵\n scaling: float # 缩放因子\n```\n\n### 前向传播逻辑\n\n```\ngraph LR\n A[输入x] --> B[原始输出: Wx]\n A --> C[LoRA输出: BAx * scaling]\n B --> D[合并输出: Wx + BAx * scaling]\n```\n\n## LoRAModel类结构\n\nLoRAModel继承自PeftModel，负责将LoRA适配器应用到基础模型：\n\n```python\n# 资料来源：src/peft/tuners/lora/model.py\nclass LoRAModel(PeftModel):\n prefix: str = \"lora_\"\n tuner_layer_cls = LoraLayer\n target_module_mapping = TRANSFORMERS_MODELS_TO_LORA_TARGET_MODULES_MAPPING\n```\n\n### _create_and_replace方法\n\n该方法负责在基础模型中创建或替换LoRA层：\n\n```python\n# 资料来源：src/peft/tuners/lora/model.py:77-95\ndef _create_and_replace(\n self,\n lora_config,\n adapter_name,\n target,\n target_name,\n parent,\n current_key,\n *,\n parameter_name: Optional[str] = None,\n) -> None:\n if current_key is None:\n raise ValueError(\"Current Key shouldn't be `None`\")\n```\n\n## DoRA实现\n\nDoRA（Weight-Decomposed LoRA）将LoRA的更新分解为幅度和方向两个分量：\n\n$$W' = m \\cdot \\frac{W_0 + \\Delta W}{\\|W_0 + \\Delta W\\|} = m \\cdot \\hat{W}$$\n\n其中 $m$ 是可学习的幅度向量，$\\hat{W}$ 是归一化的权重矩阵。\n\n### DoRA层结构\n\n```\ngraph TD\n A[原始权重 W₀] --> B[LoRA更新 ΔW]\n B --> C[权重合并 W₀ + ΔW]\n C --> D[幅度向量 m]\n C --> E[方向归一化]\n D --> F[乘积: m × direction]\n E --> F\n```\n\n## AdaLoRA实现\n\nAdaLoRA（Adaptive LoRA）是一种自适应的LoRA变体，根据参数重要性动态分配秩：\n\n### 核心特性\n\n| 特性 | 描述 |\n|------|------|\n| 重要性评估 | 基于奇异值分解评估参数重要性 |\n| 动态秩分配 | 重要参数获得更高秩 |\n| 渐进式调整 | 训练过程中逐步调整秩分配 |\n\n## VeRA实现\n\nVeRA（Vector-based Random Matrix LoRA）使用随机投影向量替代可训练矩阵以减少参数量：\n\n### 参数效率对比\n\n| 方法 | 可训练参数 | 存储需求 |\n|------|-----------|----------|\n| LoRA | 2 × d × r | O(dr + kr) |\n| VeRA | d + k + 2r | O(d + k + r) |\n\n## 使用示例\n\n### 标准LoRA配置\n\n```python\n# 资料来源：src/peft/tuners/lora/model.py\nfrom peft import LoraConfig, get_peft_model\nfrom transformers import AutoModelForCausalLM\n\nconfig = LoraConfig(\n r=8,\n lora_alpha=32,\n target_modules=[\"q_proj\", \"v_proj\"],\n lora_dropout=0.1,\n bias=\"none\",\n task_type=\"CAUSAL_LM\"\n)\n\nmodel = AutoModelForCausalLM.from_pretrained(\"base-model\")\npeft_model = get_peft_model(model, config)\npeft_model.print_trainable_parameters()\n```\n\n### DoRA配置\n\n```python\nfrom peft import DoRAConfig, get_peft_model\n\nconfig = DoRAConfig(\n r=8,\n lora_alpha=16,\n target_modules=[\"q_proj\", \"v_proj\"],\n dora_dropout=0.1\n)\n```\n\n## 目标模块映射\n\nTRANSFORMERS_MODELS_TO_LORA_TARGET_MODULES_MAPPING定义了不同模型架构的默认目标模块：\n\n```python\n# 常见目标模块映射\n{\n \"bert\": [\"query\", \"value\"],\n \"gpt2\": [\"c_attn\", \"c_proj\"],\n \"llama\": [\"q_proj\", \"v_proj\"],\n \"t5\": [\"q\", \"v\"]\n}\n```\n\n## 多适配器支持\n\nPEFT支持同时加载多个LoRA适配器：\n\n```python\n# 加载多个适配器\nmodel.load_adapter(\"path/to/adapter_1\", \"adapter_1\")\nmodel.load_adapter(\"path/to/adapter_2\", \"adapter_2\")\n\n# 激活特定适配器\nmodel.set_adapter(\"adapter_1\")\n\n# 合并所有适配器到基础模型\nmodel.merge_and_unload()\n```\n\n## 状态切换与合并\n\n```\ngraph TD\n A[基础模型] --> B[添加LoRA层]\n B --> C{是否合并?}\n C -->|是| D[merge_and_unload]\n C -->|否| E[保持LoRA权重独立]\n D --> F[融合后模型]\n E --> G[可切换适配器]\n```\n\n## 导出与部署\n\nLoRA权重可以导出为独立文件：\n\n```python\n# 保存LoRA权重\nmodel.save_pretrained(\"output_path\")\n\n# 加载已保存的LoRA模型\nfrom peft import PeftModel\npeft_model = PeftModel.from_pretrained(base_model, \"output_path\")\n```\n\n## 与其他技术的兼容性\n\n### BitsAndBytes量化支持\n\n```python\n# 资料来源：src/peft/tuners/lora/model.py\nfrom peft import get_peft_model, prepare_model_for_kbit_training\nfrom transformers import BitsAndBytesConfig\n\nquantization_config = BitsAndBytesConfig(load_in_8bit=True)\nmodel = AutoModelForCausalLM.from_pretrained(\n \"model_name\",\n quantization_config=quantization_config\n)\nmodel = prepare_model_for_kbit_training(model)\npeft_model = get_peft_model(model, lora_config)\n```\n\n### 梯度检查点\n\nLoRA层支持与梯度检查点技术结合使用，适用于超大模型的微调场景。\n\n## 总结\n\nPEFT库中的LoRA及其变体实现提供了灵活的参数高效微调方案。标准LoRA通过低秩分解减少可训练参数，DoRA通过分解幅度和方向提升表达能力，AdaLoRA通过自适应秩分配优化参数效率，VeRA通过随机投影进一步降低存储开销。\n\n---\n\n\n\n## 其他PEFT方法\n\n### 相关页面\n\n相关主题：[LoRA及其变体实现](#lora-tuners), [高级调谐器与实验性方法](#advanced-tuners)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/peft/tuners/ia3/__init__.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/ia3/__init__.py)\n- [src/peft/tuners/prompt_tuning/__init__.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/prompt_tuning/__init__.py)\n- [src/peft/tuners/prefix_tuning/__init__.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/prefix_tuning/__init__.py)\n- [src/peft/tuners/p_tuning/__init__.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/p_tuning/__init__.py)\n- [src/peft/tuners/oft/__init__.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/oft/__init__.py)\n- [src/peft/tuners/multitask_prompt_tuning/__init__.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/multitask_prompt_tuning/__init__.py)\n \n\n# 其他PEFT方法\n\nPEFT（Parameter-Efficient Fine-Tuning）库不仅支持主流的 LoRA 方法，还实现了多种参数高效微调技术。本页面详细介绍 IA³、OFT、Prompt Tuning、Prefix Tuning、P-Tuning 和 Multitask Prompt Tuning 等方法的设计原理、配置参数和使用方式。\n\n---\n\n## 概述\n\nPEFT 库中的\"其他 PEFT 方法\"涵盖了多种轻量级微调范式，这些方法各有特点，适用于不同的场景和模型架构。这些方法的核心目标是**在保持模型性能的同时，大幅减少可训练参数的数量**。\n\n### 方法分类\n\n| 类别 | 方法 | 简介 |\n|------|------|------|\n| 适配器类 | IA³ | 通过学习可缩放向量来调整模型激活 |\n| 正交变换类 | OFT | 在正交约束下学习权重更新 |\n| 提示类 | Prompt Tuning | 在输入序列前添加可学习的软提示 |\n| 提示类 | Prefix Tuning | 在每一层注意力头前添加可学习前缀 |\n| 提示类 | P-Tuning | 使用可学习的嵌入配合提示编码器 |\n| 多任务类 | Multitask Prompt Tuning | 跨任务共享和特定任务提示的组合 |\n\n---\n\n## IA³ (Intra-block Agressive Adapter)\n\n### 方法原理\n\nIA³ 是一种极其参数高效的微调方法，其核心思想是通过**学习可缩放向量**来调整模型的激活值。与 LoRA 等方法不同，IA³ 不添加新的权重矩阵，而是通过**逐元素乘法**对关键位置的激活进行缩放。\n\n资料来源：[src/peft/tuners/ia3/model.py:1-50]()\n\n### 架构图\n\n```mermaid\ngraph TD\n A[原始输入] --> B[Linear层]\n B --> C{IA³ 激活缩放}\n C --> D[激活值 × lora_A]\n D --> E[后续层处理]\n E --> F[激活值 × lora_B]\n F --> G[输出]\n \n H[可训练向量] -->|缩放因子| C\n H -->|缩放因子| D\n H -->|缩放因子| F\n```\n\n### 核心参数配置\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `r` | int | 8 | 秩参数 |\n| `target_modules` | List[str] | None | 目标模块名称 |\n| `fan_in_fan_out` | bool | False | 是否转置权重 |\n| `bias` | str | \"none\" | 偏置处理方式 |\n\n### 使用示例\n\n```python\nfrom transformers import AutoModelForSeq2SeqLM\nfrom peft import IA3Config, get_peft_model\n\nconfig = IA3Config(\n peft_type=\"IA3\",\n task_type=\"SEQ_2_SEQ_LM\",\n target_modules=[\"q\", \"v\", \"k\", \"wi\"],\n feedforward_modules=[\"wi\"],\n)\nmodel = AutoModelForSeq2SeqLM.from_pretrained(\"t5-base\")\nia3_model = get_peft_model(model, config)\nia3_model.print_trainable_parameters()\n```\n\n资料来源：[src/peft/tuners/ia3/__init__.py]()\n\n---\n\n## OFT (Orthogonal Fine-Tuning)\n\n### 方法原理\n\nOFT 是一种基于**正交约束**的参数高效微调方法。该方法在 SD（Stable Diffusion）等扩散模型中应用广泛，通过学习一个正交矩阵来约束权重更新，从而避免微调过程中对预训练知识的破坏。\n\n资料来源：[src/peft/tuners/oft/model.py:1-60]()\n\n### 核心特性\n\n- **正交约束**：权重更新必须满足正交条件\n- **分组机制**：支持将权重分组处理\n- **模块丢弃**：可选的丢弃机制防止过拟合\n\n### 架构图\n\n```mermaid\ngraph TD\n A[预训练权重 W₀] --> B{OFT 层}\n B --> C[计算 ΔW = W - W₀]\n C --> D[正交约束处理]\n D --> E[分组旋转]\n E --> F[更新权重 W]\n \n G[可训练参数 θ] -->|生成旋转| E\n F --> H[推理/训练输出]\n```\n\n### 核心参数配置\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `r` | int | 4 | 秩参数 |\n| `target_modules` | List[str] | None | 目标模块 |\n| `module_dropout` | float | 0.0 | 模块丢弃率 |\n| `fan_in_fan_out` | bool | False | 是否转置 |\n| `init_weights` | bool | True | 是否初始化权重 |\n\n资料来源：[src/peft/tuners/oft/__init__.py]()\n\n---\n\n## Prompt Tuning\n\n### 方法原理\n\nPrompt Tuning 是一种纯提示式微调方法，其核心思想是**在输入序列前添加可学习的软提示（soft prompts）**。这些软提示是连续的嵌入向量，不对应任何真实的词表 token，通过反向传播进行优化。\n\n资料来源：[src/peft/tuners/prompt_tuning/__init__.py]()\n\n### 工作流程\n\n```mermaid\ngraph LR\n A[可学习提示
P] --> B[拼接
[P; x]]\n B --> C[Transformer Encoder]\n C --> D[预测输出 ŷ]\n```\n\n### 核心参数配置\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `num_virtual_tokens` | int | 100 | 虚拟 token 数量 |\n| `num_layers` | int | None | 提示层数 |\n| `num_attention_heads` | int | None | 注意力头数 |\n| `token_dim` | int | None | token 维度 |\n\n### 使用示例\n\n```python\nfrom transformers import AutoModelForSequenceClassification\nfrom peft import PromptTuningConfig, get_peft_model\n\nconfig = PromptTuningConfig(\n task_type=\"SEQ_CLS\",\n num_virtual_tokens=20,\n prompt_tuning_init=\"TEXT\",\n prompt_tuning_init_text=\"情感分类: \",\n)\nmodel = AutoModelForSequenceClassification.from_pretrained(\"bert-base-cased\")\npt_model = get_peft_model(model, config)\n```\n\n---\n\n## Prefix Tuning\n\n### 方法原理\n\nPrefix Tuning 与 Prompt Tuning 的主要区别在于**前缀被添加到每一层注意力头的键（K）和值（V）矩阵之前**，而不是仅在输入层。这种设计允许模型在更深的层次上学习任务相关的表示。\n\n资料来源：[src/peft/tuners/prefix_tuning/__init__.py]()\n\n### 架构对比\n\n```mermaid\ngraph TD\n subgraph Prompt Tuning\n P1[软提示] -->|拼接| I1[输入Embedding]\n I1 --> L1[Layer 1]\n L1 --> L2[Layer 2]\n L2 --> LN[Layer N]\n end\n \n subgraph Prefix Tuning\n PK1[前缀 K] -->|添加| A1[Attention]\n PV1[前缀 V] -->|添加| A1\n PK2[前缀 K] -->|添加| A2[Attention]\n PV2[前缀 V] -->|添加| A2\n I2[输入] --> A1\n A1 --> A2\n end\n```\n\n### 核心参数配置\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `num_virtual_tokens` | int | 30 | 虚拟 token 数量 |\n| `num_transformer_submodules` | int | 1 | 变换器子模块数量 |\n| `encoder_hidden_size` | int | None | 编码器隐藏层大小 |\n| `prefix_projection` | bool | False | 是否投影前缀 |\n\n---\n\n## P-Tuning\n\n### 方法原理\n\nP-Tuning 使用**可学习的提示编码器（Prompt Encoder）**来生成软提示。该方法结合了离散提示和连续嵌入的优点，通过一个小型 LSTM/MLP 网络将可学习的标记映射到模型 embedding 空间。\n\n资料来源：[src/peft/tuners/p_tuning/__init__.py]()\n\n### 架构图\n\n```mermaid\ngraph TD\n A[可学习标记
[P₁, P₂, ..., Pₙ]] --> B[提示编码器
LSTM/MLP]\n B --> C[软提示嵌入]\n C --> D[与输入拼接]\n D --> E[预训练模型]\n E --> F[输出]\n \n G[输入文本] -->|Embedding| D\n```\n\n### 核心参数配置\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `num_virtual_tokens` | int | 20 | 虚拟 token 数量 |\n| `encoder_hidden_size` | int | None | 编码器隐藏层大小 |\n| `encoder_num_layers` | int | 2 | 编码器层数 |\n| `encoder_dropout` | float | 0.0 | 编码器 dropout |\n\n---\n\n## Multitask Prompt Tuning (MPT)\n\n### 方法原理\n\nMultitask Prompt Tuning 是一种**跨任务共享提示**的方法。它通过学习一组共享的基座提示（base prompts）和任务特定的提示组合，实现知识的高效迁移和复用。\n\n资料来源：[src/peft/tuners/multitask_prompt_tuning/__init__.py]()\n\n### 设计理念\n\n```mermaid\ngraph TD\n subgraph 共享基座提示\n B[Base Prompt
跨任务共享]\n end\n \n subgraph 任务特定提示\n T1[Task Prompt ₁]\n T2[Task Prompt ₂]\n T3[Task Prompt ₙ]\n end\n \n subgraph 组合\n C1[Base + Task₁]\n C2[Base + Task₂]\n C3[Base + Taskₙ]\n end\n \n B --> C1\n B --> C2\n B --> C3\n T1 --> C1\n T2 --> C2\n T3 --> C3\n```\n\n### 核心参数配置\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `num_subtasks` | int | None | 子任务数量 |\n| `num_virtual_tokens` | int | 20 | 虚拟 token 数量 |\n| `prompt_tuning_init` | str | \"RANDOM\" | 提示初始化方式 |\n| `task_embedding_dim` | int | None | 任务嵌入维度 |\n\n---\n\n## 方法对比与选择指南\n\n### 参数量对比\n\n| 方法 | 典型可训练参数 | 适用场景 |\n|------|----------------|----------|\n| IA³ | ~0.1% | 序列到序列任务、文本生成 |\n| OFT | ~0.5-2% | 图像生成、扩散模型 |\n| Prompt Tuning | ~0.01-0.1% | 分类任务、简短任务描述 |\n| Prefix Tuning | ~0.1-0.5% | 生成任务、复杂推理 |\n| P-Tuning | ~0.1-0.3% | NER、关系抽取等结构化任务 |\n| MPT | ~0.1-0.5% | 多任务学习、跨域迁移 |\n\n### 选择建议\n\n```mermaid\ngraph TD\n A[任务类型] --> B{是否多任务?}\n B -->|是| C[考虑 MPT]\n B -->|否| D{数据量?}\n D -->|极少| E[Prompt Tuning]\n D -->|充足| F{任务类型?}\n F -->|扩散模型| G[OFT]\n F -->|序列到序列| H[IA³]\n F -->|生成任务| I[Prefix Tuning]\n F -->|结构化预测| J[P-Tuning]\n```\n\n---\n\n## 通用配置接口\n\n所有 PEFT 方法都遵循统一的配置模式，通过 `PeftConfig` 基类进行管理：\n\n```python\nfrom peft import PeftConfig, LoraConfig, IA3Config\n\n# 统一的配置结构\nconfig = {\n \"peft_type\": \"LORA\", # 或 IA3, PROMPT_TUNING, etc.\n \"task_type\": \"CAUSAL_LM\", # 或 SEQ_CLS, SEQ_2_SEQ_LM, etc.\n \"inference_mode\": False,\n \"r\": 8,\n \"target_modules\": [\"q_proj\", \"v_proj\"],\n}\n```\n\n### 通用参数说明\n\n| 参数名 | 类型 | 说明 |\n|--------|------|------|\n| `peft_type` | PeftType | PEFT 方法类型枚举 |\n| `task_type` | TaskType | 任务类型 |\n| `inference_mode` | bool | 是否为推理模式 |\n| `r` | int | 秩参数（适用于相关方法） |\n| `target_modules` | List[str] | 目标模块名称列表 |\n\n---\n\n## 与主模型集成\n\n### 基础模型类继承结构\n\n所有 PEFT 方法的模型类都继承自 `PeftModel`，提供统一的接口：\n\n资料来源：[src/peft/peft_model.py]()\n\n```python\nclass PeftModelForSequenceClassification(PeftModel):\n def __init__(\n self, \n model: torch.nn.Module, \n peft_config: PeftConfig, \n adapter_name: str = \"default\"\n ):\n super().__init__(model, peft_config, adapter_name)\n # 特定任务的初始化逻辑\n```\n\n### 适配器管理\n\n```python\n# 添加多个适配器\nmodel.add_adapter(adapter_name=\"lora_v1\", adapter_config=lora_config)\nmodel.add_adapter(adapter_name=\"lora_v2\", adapter_config=lora_config_2)\n\n# 切换活动适配器\nmodel.set_adapter(adapter_name=\"lora_v1\")\n\n# 合并适配器权重\nmodel.merge_and_unload()\n```\n\n---\n\n## 总结\n\nPEFT 库提供的\"其他 PEFT 方法\"涵盖了从轻量级提示调优到结构化适配器的多种技术。这些方法各有优势：\n\n- **IA³** 适合需要快速推理且对参数效率要求极高的场景\n- **OFT** 是扩散模型微调的首选方案\n- **Prompt Tuning** 适合超大规模模型的小样本学习\n- **Prefix Tuning** 在保持提示灵活性的同时提供更强的表达能力\n- **P-Tuning** 适合需要精细控制提示表示的任务\n- **Multitask Prompt Tuning** 是多任务学习的理想选择\n\n开发者应根据具体任务需求、模型架构和计算资源选择合适的微调方法。\n\n---\n\n\n\n## 高级调谐器与实验性方法\n\n### 相关页面\n\n相关主题：[其他PEFT方法](#other-tuners), [模型合并与融合工具](#merge-utils)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/peft/tuners/boft/__init__.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/boft/__init__.py)\n- [src/peft/tuners/fourierft/__init__.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/fourierft/__init__.py)\n- [src/peft/tuners/waveft/__init__.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/waveft/__init__.py)\n- [src/peft/tuners/loha/__init__.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/loha/__init__.py)\n- [src/peft/tuners/lokr/__init__.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/lokr/__init__.py)\n- [src/peft/tuners/hra/__init__.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/hra/__init__.py)\n- [src/peft/tuners/poly/__init__.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/poly/__init__.py)\n \n\n# 高级调谐器与实验性方法\n\n## 概述\n\nPEFT（Parameter-Efficient Fine-Tuning）库提供了多种高级调谐器（Advanced Tuners）和实验性方法，这些方法超越了传统的 LoRA 线性低秩分解范式，引入频域变换、Hadamard 积、Kronecker 积等更复杂的参数化策略。这些高级调谐器在保持参数效率的同时，提供了更丰富的表达能力，适用于对模型性能有更高要求的复杂微调任务。\n\n高级调谐器的核心设计目标包括：\n\n- **提高表达能力**：通过非线性结构或频域表示增强适配器的建模能力\n- **保持参数效率**：仍通过冻结原模型参数，仅训练少量附加参数来实现\n- **支持多样化架构**：覆盖卷积层、自注意力层、全连接层等多种网络结构\n\n## 高级调谐器架构总览\n\n```mermaid\ngraph TD\n A[PEFT 高级调谐器] --> B[频域变换类]\n A --> C[低秩分解类]\n A --> D[结构化参数类]\n \n B --> B1[BOFT]\n B --> B2[FourierFT]\n B --> B3[WaveFT]\n \n C --> C1[LoHA]\n C --> C2[LoKR]\n \n D --> D1[HRA]\n D --> D2[Poly]\n \n style A fill:#e1f5fe\n style B fill:#fff3e0\n style C fill:#e8f5e9\n style D fill:#f3e5f5\n```\n\n## 频域变换类调谐器\n\n频域变换类调谐器通过将参数矩阵变换到频域进行操作，利用频域中的特殊性质（如正交性、稀疏性）来实现高效且富有表达力的参数适配。\n\n### BOFT（Block-wise Orthogonal Fourier Transform）\n\nBOFT 是一种基于块状正交傅里叶变换的高级调谐器，它在频域中使用块状正交矩阵来实现参数适配。\n\n#### 核心原理\n\nBOFT 的核心思想是将权重更新表示为块状正交矩阵的线性组合：\n\n```\nΔW = Σᵢ αᵢ · Bᵢ · F\n```\n\n其中 Bᵢ 表示块状正交矩阵，F 表示傅里叶变换矩阵，αᵢ 是可训练的标量系数。\n\n#### 关键特性\n\n| 特性 | 描述 |\n|------|------|\n| 正交约束 | 块状正交矩阵确保更新方向的稳定性 |\n| 频域稀疏性 | 仅需少量频域分量即可达到良好效果 |\n| 计算效率 | 通过 FFT 实现快速矩阵运算 |\n| 表达能力 | 相比纯低秩方法具有更强表达能力 |\n\n资料来源：[src/peft/tuners/boft/__init__.py:1-50]()\n\n### FourierFT（傅里叶变换调谐器）\n\nFourierFT 是直接在傅里叶域进行参数化的调谐器，利用傅里叶变换的正交基函数来表示权重变化。\n\n#### 架构设计\n\n```mermaid\ngraph LR\n A[原始权重 W] --> B[傅里叶变换]\n B --> C[频域系数 C]\n C --> D[可训练缩放]\n D --> E[逆傅里叶变换]\n E --> F[更新权重 W']\n \n style D fill:#ffcdd2\n```\n\n#### 适用场景\n\n- 需要捕获周期性模式的NLP任务\n- 图像处理中的频域特征学习\n- 需要处理具有固有周期性的序列数据\n\n资料来源：[src/peft/tuners/fourierft/__init__.py:1-50]()\n\n### WaveFT（小波变换调谐器）\n\nWaveFT 利用小波变换的多尺度特性，在不同分辨率下进行参数适配，特别适合处理具有层次结构的数据。\n\n#### 多尺度分解\n\n| 尺度 | 特性 | 应用 |\n|------|------|------|\n| 低频分量 | 全局趋势 | 基础语义理解 |\n| 中频分量 | 局部特征 | 语法结构学习 |\n| 高频分量 | 细节变化 | 细粒度任务适配 |\n\n资料来源：[src/peft/tuners/waveft/__init__.py:1-50]()\n\n## 低秩分解类调谐器\n\n低秩分解类调谐器在传统 LoRA 的基础上引入更复杂的矩阵分解结构，以在保持参数效率的同时增强表达能力。\n\n### LoHA（Low-Rank Hadamard Product）\n\nLoHA 使用 Hadamard 积（元素级乘法）结合低秩分解来构建适配器，这种结构能够更有效地捕获参数间的非线性交互。\n\n#### 数学形式\n\n给定原始权重矩阵 W ∈ ℝᵈˣᵏ，LoHA 的更新形式为：\n\n```\nΔW = (A ⊙ B) · H\n```\n\n其中：\n- A ∈ ℝᵈˣʳ, B ∈ ℝᵈˣʳ 为低秩矩阵\n- H ∈ ℝʳˣᵏ 为 Hadamard 基础矩阵\n- ⊙ 表示 Hadamard 积（元素级乘法）\n\n#### 优势\n\n| 维度 | LoRA | LoHA |\n|------|------|------|\n| 参数数量 | 2dr | 2dr + rk |\n| 表达能力 | 线性组合 | 元素级交互 |\n| 计算复杂度 | O(dr + kr) | O(dr + kr) |\n| 适用场景 | 基础任务 | 复杂交互任务 |\n\n资料来源：[src/peft/tuners/loha/__init__.py:1-50]()\n\n### LoKR（Low-Rank Kronecker Product）\n\nLoKR 利用 Kronecker 积的结构化低秩分解，在保持参数效率的同时提供更强的表达能力。\n\n#### 数学形式\n\nLoKR 将权重更新表示为 Kronecker 积的形式：\n\n```\nΔW = Σᵢ αᵢ · (Aᵢ ⊗ Bᵢ)\n```\n\n其中 ⊗ 表示 Kronecker 积，Aᵢ 和 Bᵢ 分别为低秩矩阵。\n\n#### 参数效率分析\n\n| 分解方式 | 原始参数 | 分解后参数 | 压缩比 |\n|----------|----------|------------|--------|\n| 标准低秩 | d × k | r(d + k) | r(d+k)/dk |\n| Kronecker | d × k | r(d₁+k₁) | r(d₁+k₁)/dk |\n\n当 d = d₁d₂, k = k₁k₂ 时，Kronecker 分解可实现显著参数压缩。\n\n资料来源：[src/peft/tuners/lokr/__init__.py:1-50]()\n\n## 结构化参数类调谐器\n\n### HRA（High-Rank Adaptation）\n\nHRA 是一种高秩适配方法，设计用于在保持参数效率的同时允许更高秩的参数更新。\n\n#### 设计理念\n\n传统 LoRA 等方法强制使用低秩更新，这在某些复杂任务中可能限制表达能力。HRA 通过结构化的高秩分解来突破这一限制：\n\n```mermaid\ngraph TD\n A[高秩目标] --> B{分解策略选择}\n B --> C[块对角结构]\n B --> D[带状结构]\n B --> E[分层结构]\n \n C --> F[块内高秩
块间独立]\n D --> G[带内交互
带间解耦]\n E --> H[层级递进
渐进表达]\n \n style A fill:#ffcdd2\n```\n\n#### 与其他方法的对比\n\n| 方法 | 秩约束 | 参数效率 | 表达能力 |\n|------|--------|----------|----------|\n| LoRA | 固定低秩 | 极高 | 中等 |\n| DoRA | 固定低秩 | 极高 | 较高 |\n| HRA | 可调结构化 | 高 | 高 |\n| Full FT | 无约束 | 低 | 最高 |\n\n资料来源：[src/peft/tuners/hra/__init__.py:1-50]()\n\n### Poly（多项式调谐器）\n\nPoly 使用多项式参数化来实现权重更新，通过多项式基函数的线性组合来捕获更复杂的变换模式。\n\n#### 多项式基\n\n对于 d 阶多项式，权重更新可表示为：\n\n```\nΔW = Σₚ cₚ · Pₚ(W)\n```\n\n其中 Pₚ 是多项式基函数，cₚ 是可训练系数。\n\n#### 特性\n\n- **非线性建模**：通过多项式基引入非线性表达能力\n- **可调复杂度**：通过多项式阶数控制表达能力\n- **梯度平滑**：相比 ReLU 等激活函数具有更平滑的梯度流\n\n资料来源：[src/peft/tuners/poly/__init__.py:1-50]()\n\n## 统一配置接口\n\n### 配置参数对照表\n\n| 参数名 | 类型 | 说明 | 适用调谐器 |\n|--------|------|------|------------|\n| `r` | int | 低秩维度 | LoHA, LoKR, HRA |\n| `modules_to_save` | List[str] | 额外训练的模块 | 全部 |\n| `fan_in_fan_out` | bool | 权重初始化方式 | LoHA, LoKR |\n| `init_weights` | bool | 是否初始化权重 | 全部 |\n| `layers_to_transform` | List[int] | 指定变换层 | 全部 |\n\n### 使用示例\n\n```python\nfrom peft import get_peft_model, LoraConfig\n\n# LoHA 配置示例\nloha_config = LoraConfig(\n r=16,\n lora_alpha=32,\n target_modules=[\"q_proj\", \"v_proj\"],\n lora_dropout=0.05,\n bias=\"none\",\n task_type=\"CAUSAL_LM\"\n)\n\n# FourierFT 配置示例\nfourier_config = LoraConfig(\n r=8,\n lora_alpha=16,\n target_modules=[\"q_proj\", \"k_proj\", \"v_proj\", \"o_proj\"],\n task_type=\"CAUSAL_LM\"\n)\n```\n\n## 技术选型指南\n\n```mermaid\ngraph TD\n A[任务类型?] --> B{参数效率优先?}\n B -->|是| C{交互复杂度?}\n B -->|否| D[使用 HRA 或 Poly]\n \n C -->|简单线性| E[使用 LoRA]\n C -->|中等| F[使用 LoHA]\n C -->|复杂| G[使用 LoKR]\n \n A --> H{频域特征重要?}\n H -->|是| I{多尺度需求?}\n I -->|是| J[使用 WaveFT]\n I -->|否| K[使用 FourierFT]\n \n style E fill:#c8e6c9\n style F fill:#fff9c4\n style G fill:#ffccbc\n style J fill:#bbdefb\n style K fill:#e1bee7\n```\n\n### 场景推荐\n\n| 场景 | 推荐方法 | 理由 |\n|------|----------|------|\n| 通用文本微调 | LoRA | 成熟稳定，资源消耗低 |\n| 复杂语义任务 | LoHA | 元素级交互增强表达 |\n| 大模型高效微调 | LoKR | Kronecker 结构节省参数 |\n| 周期模式识别 | FourierFT | 频域表示天然捕获周期 |\n| 多粒度任务 | WaveFT | 小波多尺度分析 |\n| 高表达需求 | HRA | 结构化高秩保持效率 |\n\n## 底层实现架构\n\n### 调谐器类层次结构\n\n```mermaid\nclassDiagram\n class BaseTuner {\n <>\n +merge_weights()\n +unmerge_weights()\n +set_adapter()\n }\n \n class BaseLayer {\n +forward()\n +extra_capabilities()\n }\n \n class BOFT {\n +_create_boft_modules()\n +forward()\n }\n \n class FourierFT {\n +_create_fourier_modules()\n +forward()\n }\n \n class WaveFT {\n +_create_wavelet_modules()\n +forward()\n }\n \n class LoHA {\n +_create_hadamard_modules()\n +forward()\n }\n \n class LoKR {\n +_create_kronecker_modules()\n +forward()\n }\n \n class HRA {\n +_create_hra_modules()\n +forward()\n }\n \n class Poly {\n +_create_poly_modules()\n +forward()\n }\n \n BaseTuner <|-- BOFT\n BaseTuner <|-- FourierFT\n BaseTuner <|-- WaveFT\n BaseTuner <|-- LoHA\n BaseTuner <|-- LoKR\n BaseTuner <|-- HRA\n BaseTuner <|-- Poly\n \n BaseLayer <|-- BOFT\n BaseLayer <|-- FourierFT\n BaseLayer <|-- WaveFT\n BaseLayer <|-- LoHA\n BaseLayer <|-- LoKR\n BaseLayer <|-- HRA\n BaseLayer <|-- Poly\n```\n\n## 性能与效率对比\n\n### 参数量对比（以 d=1024, k=1024, r=16 为例）\n\n| 方法 | 可训练参数量 | 理论压缩比 |\n|------|-------------|-----------|\n| Full Fine-tune | 2,097,152 | 1× |\n| LoRA | 65,536 | 32× |\n| LoHA | 65,536 + α | ~32× |\n| LoKR | ~32,768 | ~64× |\n| BOFT | ~65,536 | ~32× |\n| FourierFT | ~32,768 | ~64× |\n\n### 计算开销\n\n| 方法 | 前向计算开销 | 反向梯度开销 |\n|------|-------------|-------------|\n| LoRA | O(dr + kr) | O(dr + kr) |\n| LoHA | O(dr + kr) | O(dr + kr) |\n| LoKR | O(d₁r + d₂r + k₁r + k₂r) | O(d₁r + d₂r + k₁r + k₂r) |\n| FourierFT | O(dk log d) | O(dk log d) |\n| WaveFT | O(dk log d) | O(dk log d) |\n\n## 最佳实践\n\n### 配置建议\n\n1. **秩的选择**：从 r=8 或 r=16 开始，根据任务复杂度逐步增加\n2. **目标模块**：优先选择注意力层的 q_proj 和 v_proj\n3. **学习率**：高级调谐器通常需要比 LoRA 稍低的学习率\n4. **初始化**：建议使用 PEFT 默认初始化策略\n\n### 常见问题排查\n\n| 问题 | 可能原因 | 解决方案 |\n|------|----------|----------|\n| 收敛慢 | 学习率过高 | 降低学习率 2-5 倍 |\n| 性能下降 | 秩过低 | 适当增加 r 值 |\n| 显存溢出 | batch size 过大 | 减小 batch size |\n| 效果不稳定 | 初始化不当 | 使用预定义初始化 |\n\n## 总结\n\nPEFT 库的高级调谐器为参数高效微调提供了丰富的选择，涵盖了频域变换、低秩分解、结构化参数等多种技术路线。这些方法在保持参数效率的同时，通过各自独特的参数化策略增强了模型的表达能力。\n\n开发者和研究人员可以根据具体任务需求、计算资源和性能要求，在这些高级调谐器中选择最合适的方案。随着研究的深入，这些实验性方法有望在未来得到进一步优化和广泛应用。\n\n---\n\n\n\n## 模型合并与融合工具\n\n### 相关页面\n\n相关主题：[量化支持与加速优化](#quantization), [示例与用例概览](#examples-overview)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/peft/utils/merge_utils.py](https://github.com/huggingface/peft/blob/main/src/peft/utils/merge_utils.py)\n- [src/peft/utils/save_and_load.py](https://github.com/huggingface/peft/blob/main/src/peft/utils/save_and_load.py)\n- [src/peft/mixed_model.py](https://github.com/huggingface/peft/blob/main/src/peft/mixed_model.py)\n- [src/peft/tuners/tuners_utils.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/tuners_utils.py)\n- [src/peft/peft_model.py](https://github.com/huggingface/peft/blob/main/src/peft/peft_model.py)\n- [src/peft/utils/hotswap.py](https://github.com/huggingface/peft/blob/main/src/peft/utils/hotswap.py)\n \n\n# 模型合并与融合工具\n\n## 概述\n\nPEFT（Parameter-Efficient Fine-Tuning）库提供了强大的模型合并与融合工具，使用户能够将适配器（Adapter）的权重与基础模型合并，生成一个独立的、合并后的模型。这些工具的核心功能包括：\n\n- **合并与卸载（Merge and Unload）**：将适配器权重合并回基础模型，生成标准Transformer模型\n- **卸载（Unload）**：移除所有PEFT模块，恢复基础模型\n- **混合适配器合并（Mixed Adapter Merging）**：支持在多适配器场景下选择性合并特定适配器\n\n合并后的模型不再依赖PEFT框架，可以像标准模型一样加载和使用，同时保留了适配器训练带来的能力增强。\n\n资料来源：[src/peft/tuners/tuners_utils.py:1-100]()\n\n## 核心架构\n\n### 合并机制流程\n\n```mermaid\ngraph TD\n A[PEFT模型] --> B{合并方式选择}\n B --> C[merge_and_unload
合并并卸载适配器]\n B --> D[unload
仅卸载适配器]\n C --> E[合并权重到基础层]\n D --> F[移除PEFT模块]\n E --> G[返回合并后的基础模型]\n F --> G\n G --> H[标准Transformer模型]\n```\n\n### 多适配器合并架构\n\n```mermaid\ngraph TD\n A[基础模型] --> B[Adapter 1
LoRA权重]\n A --> C[Adapter 2
LoRA权重]\n A --> D[Adapter N
LoRA权重]\n B --> E{选择性合并}\n C --> E\n D --> E\n E --> F[合并指定适配器]\n E --> G[合并全部适配器]\n F --> H[合并后的模型]\n G --> H\n```\n\n## 主要接口\n\n### PeftModel 基类方法\n\n所有PEFT模型继承自 `PeftModel` 基类，提供以下合并相关方法：\n\n| 方法名 | 参数 | 返回值 | 功能描述 |\n|--------|------|--------|----------|\n| `merge_and_unload` | `progressbar`, `safe_merge`, `adapter_names` | `torch.nn.Module` | 合并并卸载适配器，返回合并后的模型 |\n| `unload` | 无 | `torch.nn.Module` | 仅卸载适配器，返回基础模型 |\n| `_unload_and_optionally_merge` | `merge`, `progressbar`, `safe_merge`, `adapter_names` | `torch.nn.Module` | 内部实现，根据参数决定是否合并 |\n\n资料来源：[src/peft/tuners/tuners_utils.py:150-180]()\n\n### 方法详细说明\n\n#### merge_and_unload 方法\n\n```python\ndef merge_and_unload(\n self,\n progressbar: bool = False,\n safe_merge: bool = False,\n adapter_names: Optional[list[str]] = None,\n) -> torch.nn.Module:\n```\n\n**参数说明**：\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `progressbar` | `bool` | `False` | 是否显示合并进度条 |\n| `safe_merge` | `bool` | `False` | 是否使用安全合并模式（避免数值溢出） |\n| `adapter_names` | `Optional[list[str]]` | `None` | 指定要合并的适配器名称列表，None表示全部 |\n\n**使用示例**：\n\n```python\n>>> from peft import PeftModel\n>>> base_model = AutoModelForCausalLM.from_pretrained(\"base_model_path\")\n>>> peft_model = PeftModel.from_pretrained(base_model, \"adapter_path\")\n>>> merged_model = peft_model.merge_and_unload()\n```\n\n资料来源：[src/peft/tuners/tuners_utils.py:120-145]()\n\n#### unload 方法\n\n```python\ndef unload(self) -> torch.nn.Module:\n```\n\n该方法将所有PEFT模块从模型中移除，返回原始的基础模型。\n\n> **重要提示**：必须将返回的模型赋值给一个变量并使用它，这不是原地操作。\n\n资料来源：[src/peft/tuners/tuners_utils.py:155-165]()\n\n## 合并策略\n\n### 基础模型合并\n\n基础模型合并是最常见的场景，将单个适配器与基础模型合并：\n\n```mermaid\ngraph LR\n A[Base Model] -->|加载| B[PeftModel]\n B -->|添加适配器| C[LoRA Layers]\n C -->|merge_and_unload| D[合并后的模型]\n```\n\n### 多适配器选择性合并\n\n在多适配器场景下，可以选择性合并特定的适配器：\n\n```python\n# 合并指定适配器\nmerged_model = peft_model.merge_and_unload(\n adapter_names=[\"adapter_1\", \"adapter_2\"]\n)\n\n# 安全合并避免数值问题\nmerged_model = peft_model.merge_and_unload(\n safe_merge=True\n)\n```\n\n### 合并过程中的兼容性检查\n\nPEFT库实现了目标模块兼容性检查机制，防止在特定架构（如Mamba）上应用不兼容的LoRA模块：\n\n```python\ndef _check_target_module_compatiblity(\n self, \n peft_config: PeftConfig, \n model: nn.Module, \n target_name: str\n):\n \"\"\"防止在不兼容的模块上应用LoRA\"\"\"\n _check_lora_target_modules_mamba(peft_config, model, target_name)\n```\n\n资料来源：[src/peft/tuners/tuners_utils.py:170-175]()\n\n## 适配器热切换\n\n### hotswap_adapter 功能\n\nPEFT还提供了热切换适配器的功能，允许在不重新加载模型的情况下替换适配器：\n\n```python\nfrom peft.utils.hotswap import hotswap_adapter\n\n# 替换默认适配器\nhotswap_adapter(\n model, \n \"path-to-new-adapter\", \n adapter_name=\"default\",\n torch_device=\"cuda\"\n)\n```\n\n**参数说明**：\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `model` | `PeftModel` | 包含已加载适配器的PEFT模型 |\n| `model_name_or_path` | `str` | 新适配器的路径 |\n| `adapter_name` | `str` | 要替换的适配器名称 |\n| `torch_device` | `str` | 加载新适配器的设备 |\n\n资料来源：[src/peft/utils/hotswap.py:1-50]()\n\n### 热切换工作流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant M as PeftModel\n participant A1 as 原适配器\n participant A2 as 新适配器\n \n U->>M: 调用hotswap_adapter\n M->>M: 加载新适配器配置\n M->>M: 验证适配器兼容性\n M->>A1: 卸载原适配器权重\n M->>A2: 加载新适配器权重\n M->>U: 返回热切换后的模型\n```\n\n## Mixed PeftModel\n\n对于需要同时使用多个适配器的场景，PEFT提供了 `MixedPeftModel` 类，支持更灵活的多适配器管理。\n\n### 主要特性\n\n| 特性 | 说明 |\n|------|------|\n| 多适配器加载 | 同时加载多个适配器 |\n| 动态切换 | 在不同适配器间动态切换 |\n| 选择性合并 | 合并指定的适配器组合 |\n| 权重融合 | 支持不同合并策略的权重融合 |\n\n资料来源：[src/peft/mixed_model.py:1-100]()\n\n## 保存与加载\n\n### 模型保存\n\nPEFT提供了 `save_peft_model` 函数用于保存PEFT模型：\n\n```python\n>>> from peft import save_peft_model\n>>> peft_model.save_peft_model(save_path)\n```\n\n### 模型加载\n\n使用 `from_pretrained` 方法加载已保存的PEFT模型：\n\n```python\n>>> from peft import PeftModel\n>>> base_model = AutoModelForCausalLM.from_pretrained(\"base_model\")\n>>> peft_model = PeftModel.from_pretrained(base_model, \"peft_model_path\")\n```\n\n资料来源：[src/peft/utils/save_and_load.py:1-100]()\n\n## 使用场景\n\n### 场景一：训练后合并\n\n在完成适配器训练后，将适配器权重合并到基础模型：\n\n```python\nfrom peft import PeftModel, AutoModelForCausalLM\n\n# 1. 加载基础模型\nbase_model = AutoModelForCausalLM.from_pretrained(\"meta-llama/Llama-2-7b\")\n\n# 2. 加载训练好的PEFT适配器\npeft_model = PeftModel.from_pretrained(base_model, \"./lora_checkpoint\")\n\n# 3. 合并并卸载\nmerged_model = peft_model.merge_and_unload()\n\n# 4. 保存合并后的模型\nmerged_model.save_pretrained(\"./merged_model\")\n```\n\n### 场景二：多适配器选择性合并\n\n在多适配器训练后，选择性地合并部分适配器：\n\n```python\n# 假设有多个适配器\npeft_model.add_adapter(\"adapter_style_a\", config_a)\npeft_model.add_adapter(\"adapter_style_b\", config_b)\n\n# 只合并特定适配器\nmerged_model = peft_model.merge_and_unload(\n adapter_names=[\"adapter_style_a\"]\n)\n```\n\n### 场景三：推理时热切换\n\n在推理过程中动态切换不同适配器：\n\n```python\nfrom peft.utils.hotswap import hotswap_adapter\n\n# 使用适配器A推理\noutput_a = model(inputs)\n\n# 热切换到适配器B\nhotswap_adapter(model, \"path-to-adapter-b\", adapter_name=\"default\")\n\n# 使用适配器B推理\noutput_b = model(inputs)\n```\n\n## 注意事项\n\n### 内存需求\n\n合并操作需要额外的内存来存储中间结果，合并过程中内存使用量可能达到原模型大小的2-3倍。\n\n### 安全合并\n\n启用 `safe_merge=True` 可以避免合并过程中的数值溢出问题：\n\n```python\nmerged_model = peft_model.merge_and_unload(safe_merge=True)\n```\n\n### 不兼容模块\n\n某些特定架构（如Mamba）可能不支持标准的LoRA合并操作，系统会进行兼容性检查并抛出相应错误。\n\n## 相关文件索引\n\n| 文件路径 | 功能描述 |\n|----------|----------|\n| `src/peft/utils/merge_utils.py` | 核心合并工具函数 |\n| `src/peft/utils/save_and_load.py` | 模型保存与加载工具 |\n| `src/peft/mixed_model.py` | 混合适配器模型实现 |\n| `src/peft/tuners/tuners_utils.py` | tuner基类，包含merge_and_unload实现 |\n| `src/peft/peft_model.py` | PEFT模型主类定义 |\n| `src/peft/utils/hotswap.py` | 适配器热切换工具 |\n\n## 总结\n\nPEFT库的模型合并与融合工具提供了完整的工作流程，从适配器训练后的模型合并、多适配器选择性合并，到推理过程中的适配器热切换。这些工具使得用户可以灵活地管理和部署高效的参数微调模型，同时保持部署模型的简洁性和兼容性。\n\n---\n\n\n\n## 量化支持与加速优化\n\n### 相关页面\n\n相关主题：[模型合并与融合工具](#merge-utils), [核心模块与架构](#core-modules)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/peft/tuners/lora/bnb.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/lora/bnb.py)\n- [src/peft/tuners/lora/gptq.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/lora/gptq.py)\n- [src/peft/tuners/lora/awq.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/lora/awq.py)\n- [src/peft/tuners/lora/aqlm.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/lora/aqlm.py)\n- [src/peft/tuners/lora/hqq.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/lora/hqq.py)\n- [src/peft/optimizers/__init__.py](https://github.com/huggingface/peft/blob/main/src/peft/optimizers/__init__.py)\n \n\n# 量化支持与加速优化\n\n## 概述\n\nPEFT 库提供了全面的量化支持与加速优化功能，旨在降低大语言模型的显存占用和计算成本，同时保持模型性能。通过集成多种业界领先的量化方法，PEFT 使用户能够在量化模型上无缝应用 LoRA 等参数高效微调技术。量化支持覆盖了从 4-bit 量化到极致压缩的多种方案，包括 BitsAndBytes (bnb)、GPTQ、AWQ、AQLM 和 HQQ 等主流量化框架。\n\n## 架构总览\n\nPEFT 的量化系统采用模块化设计，每种量化方法都有独立的实现模块，与 LoRA 微调层深度集成。这种设计允许用户在量化模型上直接添加和训练适配器，而无需对原始量化架构进行大幅修改。\n\n```mermaid\ngraph TD\n A[用户配置] --> B[PEFT 量化模块]\n B --> C[bnb.py
BitsAndBytes 4-bit]\n B --> D[gptq.py
GPTQ 量化]\n B --> E[awq.py
AWQ 量化]\n B --> F[aqlm.py
AQLM 量化]\n B --> G[hqq.py
HQQ 量化]\n C --> H[LoRA 适配器层]\n D --> H\n E --> H\n F --> H\n G --> H\n H --> I[量化模型推理/训练]\n```\n\n## 量化方法详解\n\n### BitsAndBytes 量化 (bnb)\n\nBitsAndBytes 是由 Meta 开发的 4-bit 量化方案，采用 NormalFloat (NF4) 数据类型实现高效的权重量化。该方法在量化过程中使用双重量化技术，进一步减少显存占用。\n\n#### 核心参数配置\n\n| 参数 | 类型 | 说明 | 默认值 |\n|------|------|------|--------|\n| `load_in_4bit` | bool | 启用 4-bit 量化加载 | False |\n| `load_in_8bit` | bool | 启用 8-bit 量化加载 | False |\n| `bnb_4bit_quant_type` | str | 量化类型，可选 `nf4` 或 `fp4` | `nf4` |\n| `bnb_4bit_compute_dtype` | dtype | 计算数据类型 | float16 |\n| `bnb_4bit_use_double_quant` | bool | 启用双重量化 | False |\n\n#### 工作原理\n\nBitsAndBytes 在模型加载时自动替换原有的 Linear 层为自定义的 BNB Linear 层。该实现支持在量化模型上直接添加 LoRA 适配器，适配器参数保持原始精度以确保训练稳定性。\n\n资料来源：[src/peft/tuners/lora/bnb.py:1-200](https://github.com/huggingface/peft/blob/main/src/peft/tuners/lora/bnb.py)\n\n### GPTQ 量化\n\nGPTQ 是一种后训练量化 (PTQ) 方法，通过逐层优化实现 4-bit 权重量化。该方法在保持模型性能的同时实现显著的压缩率。\n\n#### 关键特性\n\n- 支持 4-bit 和 8-bit 量化精度\n- 与现有 PEFT 方法完全兼容\n- 支持量化感知训练\n\n#### 量化配置\n\n| 参数 | 说明 | 可选值 |\n|------|------|--------|\n| `bits` | 量化位数 | 2, 3, 4, 8 |\n| `tokenizer` | 分词器实例 | - |\n| `dataset` | 校准数据集 | 字符串或列表 |\n| `samples` | 校准样本数量 | 整数 |\n\n资料来源：[src/peft/tuners/lora/gptq.py:1-180](https://github.com/huggingface/peft/blob/main/src/peft/tuners/lora/gptq.py)\n\n### AWQ 量化\n\nAWQ (Activation-Aware Weight Quantization) 是一种硬件感知的权重量化方法，通过分析激活值分布来优化量化策略。该方法特别适合在特定硬件平台上部署。\n\n#### 核心优势\n\n- 针对硬件优化的高效推理\n- 保留重要权重为全精度\n- 与多种部署框架兼容\n\n资料来源：[src/peft/tuners/lora/awq.py:1-150](https://github.com/huggingface/peft/blob/main/src/peft/tuners/lora/awq.py)\n\n### AQLM 量化\n\nAQLM (Additive Quantization Language Models) 是一种基于加数量化的高级压缩方法，通过将权重矩阵分解为多个码本的组合实现极致压缩。\n\n#### 技术特点\n\n- 支持多码本量化架构\n- 高压缩率下的性能保持\n- 适合大规模模型的极致优化\n\n资料来源：[src/peft/tuners/lora/aqlm.py:1-160](https://github.com/huggingface/peft/blob/main/src/peft/tuners/lora/aqlm.py)\n\n### HQQ 量化\n\nHQQ (Hessian Quantization) 是一种基于 Hessian 矩阵的量化方法，通过考虑参数重要性进行自适应量化。该方法在量化过程中利用二阶信息来保护关键权重。\n\n#### 核心机制\n\n- 基于 Hessian 的敏感性分析\n- 自适应位宽分配\n- 训练后量化支持\n\n资料来源：[src/peft/tuners/lora/hqq.py:1-170](https://github.com/huggingface/peft/blob/main/src/peft/tuners/lora/hqq.py)\n\n## 优化器集成\n\nPEFT 的优化器模块提供了与量化系统深度集成的优化算法，专门针对量化环境下的训练进行了优化。\n\n```mermaid\ngraph LR\n A[量化模型] --> B[优化器选择]\n B --> C[标准优化器]\n B --> D[PEFT 优化器]\n C --> E[SGD/AdamW]\n D --> F[8bit AdamW]\n D --> G[32bit AdamW]\n F --> H[梯度更新]\n G --> H\n```\n\n### 8-bit AdamW 优化器\n\n针对量化环境优化的 8-bit AdamW 实现，通过分块量化技术保持训练稳定性。该优化器使用专利的分块方案处理梯度统计量，显著降低显存占用。\n\n### 优化器配置\n\n| 优化器类型 | 适用场景 | 显存节省 |\n|-----------|----------|----------|\n| 8-bit AdamW | 量化模型训练 | ~60% |\n| 32-bit AdamW | 精度敏感场景 | ~40% |\n| PyTorch SGD | 简单任务 | ~20% |\n\n资料来源：[src/peft/optimizers/__init__.py:1-100](https://github.com/huggingface/peft/blob/main/src/peft/optimizers/__init__.py)\n\n## 量化与 LoRA 的结合\n\n### 工作流程\n\n```mermaid\ngraph TD\n A[加载基础模型] --> B{选择量化方法}\n B --> C[BitsAndBytes]\n B --> D[GPTQ]\n B --> E[AWQ]\n B --> F[AQLM]\n B --> G[HQQ]\n C --> H[量化模型转换]\n D --> H\n E --> H\n F --> H\n G --> H\n H --> I[注入 LoRA 适配器]\n I --> J[PEFT 配置]\n J --> K[训练/推理]\n```\n\n### 兼容性矩阵\n\n| 量化方法 | LoRA | AdaLoRA | QLoRA | Prefix Tuning |\n|---------|------|---------|-------|---------------|\n| BitsAndBytes | ✓ | ✓ | ✓ | ✓ |\n| GPTQ | ✓ | ✓ | ✓ | ✓ |\n| AWQ | ✓ | ✓ | ✓ | ✓ |\n| AQLM | ✓ | ✓ | ✓ | ✓ |\n| HQQ | ✓ | ✓ | ✓ | ✓ |\n\n## 使用示例\n\n### BitsAndBytes 量化配置\n\n```python\nfrom peft import get_peft_model, LoraConfig, BitsAndBytesConfig\n\n# 配置量化参数\nbnb_config = BitsAndBytesConfig(\n load_in_4bit=True,\n bnb_4bit_compute_dtype=\"float16\",\n bnb_4bit_use_double_quant=True,\n bnb_4bit_quant_type=\"nf4\"\n)\n\n# 加载量化模型并应用 LoRA\nmodel = AutoModelForCausalLM.from_pretrained(\n \"model_name\",\n quantization_config=bnb_config\n)\n\nlora_config = LoraConfig(\n r=16,\n lora_alpha=32,\n target_modules=[\"q_proj\", \"v_proj\"],\n lora_dropout=0.05,\n task_type=\"CAUSAL_LM\"\n)\n\nmodel = get_peft_model(model, lora_config)\n```\n\n### QLoRA 训练流程\n\nQLoRA 结合了量化与 LoRA 的优势，实现极低显存占用的高效训练。该方案在 4-bit 量化的模型上训练 LoRA 适配器，同时保持优化器状态为全精度。\n\n## 性能与精度权衡\n\n### 量化精度对比\n\n| 量化方法 | 精度损失 | 压缩比 | 推理速度提升 |\n|---------|----------|--------|-------------|\n| FP16 (基线) | 0% | 1x | 1x |\n| INT8 | <1% | 2x | 1.3x |\n| NF4 (bnb) | <2% | 4x | 2x |\n| GPTQ-4bit | <3% | 4x | 2.5x |\n| AQLM | <4% | 8x | 3x |\n\n### 显存占用分析\n\n```\n模型规模: 7B 参数\n\nFP16 完整微调: ~28GB 显存\nQLoRA (4bit): ~6GB 显存\nLoRA (FP16): ~14GB 显存\n```\n\n## 技术实现要点\n\n### 量化感知训练\n\nPEFT 支持在量化模型上进行量化感知训练 (QAT)，通过以下机制实现：\n\n1. **直通的梯度流动**：LoRA 适配器层保持原始精度计算\n2. **动态量化更新**：权重更新采用舍入机制\n3. **兼容性检查**：自动验证量化配置与 PEFT 配置的兼容性\n\n### 混合精度策略\n\n量化配置中可指定不同的计算精度层级：\n\n```python\ncompute_dtype = torch.float16 # 计算使用 FP16\nquantization_config = {\n \"weight_bit_width\": 4, # 权重 4-bit\n \"calib_bit_width\": 8 # 校准使用 8-bit\n}\n```\n\n## 最佳实践\n\n### 量化方法选择指南\n\n| 应用场景 | 推荐量化方法 | 理由 |\n|---------|-------------|------|\n| 消费级 GPU 训练 | BitsAndBytes NF4 | 成熟稳定，生态完善 |\n| 服务器端部署 | GPTQ-4bit | 推理效率高 |\n| 移动端部署 | AWQ | 硬件适配性好 |\n| 极致压缩 | AQLM | 最高压缩率 |\n\n### 常见陷阱与规避\n\n1. **精度回退**：确保优化器状态使用足够精度\n2. **校准数据质量**：使用代表性数据避免分布偏移\n3. **目标模块选择**：优先量化 attention 和 FFN 层\n4. **梯度检查**：启用梯度监控以检测数值问题\n\n## 总结\n\nPEFT 的量化支持与加速优化模块为用户提供了完整的模型压缩解决方案。通过集成多种主流量化框架并保持与 LoRA 系列的深度兼容，PEFT 使得在资源受限环境下训练和部署大语言模型成为可能。开发者应根据具体应用场景、硬件条件和性能要求选择合适的量化策略，在模型效果和资源效率之间取得最佳平衡。\n\n---\n\n\n\n## 示例与用例概览\n\n### 相关页面\n\n相关主题：[PEFT概述与快速入门](#overview), [开发者指南与贡献](#developer-guides)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/peft/peft_model.py](https://github.com/huggingface/peft/blob/main/src/peft/peft_model.py)\n- [src/peft/tuners/lora/model.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/lora/model.py)\n- [src/peft/tuners/ia3/model.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/ia3/model.py)\n- [src/peft/tuners/prompt_tuning/model.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/prompt_tuning/model.py)\n- [src/peft/tuners/xlora/model.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/xlora/model.py)\n- [src/peft/helpers.py](https://github.com/huggingface/peft/blob/main/src/peft/helpers.py)\n- [src/peft/tuners/tuners_utils.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/tuners_utils.py)\n \n\n# 示例与用例概览\n\n## 概述\n\nPEFT（Parameter-Efficient Fine-Tuning）库提供了丰富的示例和用例，涵盖了从语言建模到图像分类的多种任务类型。这些示例展示了如何使用不同的适配器方法（如 LoRA、IA³、Prefix Tuning、Prompt Tuning 等）来高效地微调预训练模型。示例代码位于 `examples/` 目录下，涵盖了因果语言建模、条件生成、序列分类、图像分类、监督微调（SFT）以及 INT8 训练等多种场景。\n\nPEFT 的示例设计遵循统一的设计模式，通过 `get_peft_model()` 函数将 PEFT 配置应用到基础模型上，然后使用标准的 Transformers API 进行训练和推理。这种设计使得用户可以轻松地在不同的适配器方法之间切换，同时保持代码的一致性。\n\n## 核心任务类型\n\nPEFT 库针对不同的下游任务提供了专门的任务类型（Task Type），每种任务类型对应特定的模型类和应用场景。\n\n### 任务类型与模型类映射\n\n| 任务类型 | 枚举值 | 对应模型类 | 主要应用场景 |\n|---------|--------|-----------|-------------|\n| 因果语言建模 | `CAUSAL_LM` | `PeftModelForCausalLM` | GPT 系列模型的自回归生成 |\n| 条件生成 | `SEQ_2_SEQ_LM` | `PeftModelForSeq2SeqLM` | T5、BART 等编码器-解码器模型 |\n| 序列分类 | `SEQ_CLS` | `PeftModelForSequenceClassification` | 文本分类任务 |\n| Token 分类 | `TOKEN_CLS` | `PeftModelForTokenClassification` | 命名实体识别、词性标注 |\n| 问答任务 | `QUESTION_ANS` | `PeftModelForQuestionAnswering` | 阅读理解问答 |\n| 特征提取 | `FEATURE_EXTRACTION` | `PeftModelForFeatureExtraction` | 嵌入向量提取 |\n\n资料来源：[src/peft/peft_model.py:1-100]()\n\n### 因果语言建模（Causal Language Modeling）\n\n因果语言建模是 GPT 系列模型的核心任务，模型需要根据前面的 token 预测下一个 token。PEFT 提供了 `PeftModelForCausalLM` 类来处理这类任务。\n\n```python\nfrom transformers import AutoModelForCausalLM\nfrom peft import get_peft_model, LoraConfig, TaskType\n\nmodel = AutoModelForCausalLM.from_pretrained(\"gpt2\")\npeft_config = LoraConfig(\n task_type=TaskType.CAUSAL_LM,\n r=16,\n lora_alpha=32,\n lora_dropout=0.05,\n target_modules=[\"q_proj\", \"v_proj\"]\n)\npeft_model = get_peft_model(model, peft_config)\npeft_model.print_trainable_parameters()\n```\n\n在因果语言建模中，LoRA 适配器通常应用于注意力机制的查询（Query）和值（Value）投影层，以实现高效的参数更新。模型的 `generate()` 方法保持了与原始模型相同的签名，可以通过 `update_generate_signature()` 函数来更新以包含完整的参数说明。\n\n资料来源：[src/peft/tuners/lora/model.py:1-50]()\n资料来源：[src/peft/helpers.py:1-60]()\n\n### 序列到序列生成（Sequence-to-Sequence Generation）\n\n序列到序列任务适用于 T5、BART 等编码器-解码器架构的模型。`PeftModelForSeq2SeqLM` 类专门处理这类任务，支持条件生成、翻译、摘要等应用。\n\n```python\nfrom transformers import AutoModelForSeq2SeqLM\nfrom peft import PeftModelForSeq2SeqLM, get_peft_config\n\nconfig = {\n \"peft_type\": \"LORA\",\n \"task_type\": \"SEQ_2_SEQ_LM\",\n \"inference_mode\": False,\n \"r\": 8,\n \"lora_alpha\": 32,\n \"lora_dropout\": 0.1,\n \"target_modules\": [\"q\", \"v\"]\n}\n\npeft_config = get_peft_config(config)\nmodel = AutoModelForSeq2SeqLM.from_pretrained(\"t5-base\")\npeft_model = PeftModelForSeq2SeqLM(model, peft_config)\n```\n\n`PeftModelForSeq2SeqLM` 初始化时会保存基础模型的 `prepare_inputs_for_generation` 和 `_prepare_encoder_decoder_kwargs_for_generation` 方法引用，以确保生成过程中的兼容性。\n\n资料来源：[src/peft/peft_model.py:100-150]()\n\n### 序列分类（Sequence Classification）\n\n序列分类任务将整个序列映射到单个标签，常用于情感分析、主题分类等场景。`PeftModelForSequenceClassification` 专门处理此类任务。\n\n```python\nfrom transformers import AutoModelForSequenceClassification\nfrom peft import PeftModelForSequenceClassification, get_peft_config\n\nconfig = {\n \"peft_type\": \"PREFIX_TUNING\",\n \"task_type\": \"SEQ_CLS\",\n \"num_virtual_tokens\": 20,\n \"token_dim\": 768,\n \"num_transformer_submodules\": 1,\n \"num_attention_heads\": 12,\n \"num_layers\": 12\n}\n\npeft_config = get_peft_config(config)\nmodel = AutoModelForSequenceClassification.from_pretrained(\"bert-base-cased\")\npeft_model = PeftModelForSequenceClassification(model, peft_config)\n```\n\n在序列分类中，PEFT 默认识别 `classifier` 和 `score` 作为分类层名称，可以通过配置中的 `modules_to_save` 参数指定其他需要训练的分类层。\n\n资料来源：[src/peft/peft_model.py:50-100]()\n\n### Token 分类（Token Classification）\n\nToken 分类任务为输入序列中的每个 token 预测一个标签，适用于命名实体识别（NER）、词性标注等任务。\n\n```python\nfrom transformers import AutoModelForTokenClassification\nfrom peft import PeftModelForTokenClassification, get_peft_config\n\npeft_config = get_peft_config({\n \"peft_type\": \"LORA\",\n \"task_type\": \"TOKEN_CLS\",\n \"r\": 16,\n \"target_modules\": [\"query\", \"value\"]\n})\n\nmodel = AutoModelForTokenClassification.from_pretrained(\"bert-base-cased\")\npeft_model = PeftModelForTokenClassification(model, peft_config)\n```\n\n与序列分类类似，Token 分类也使用 `modules_to_save` 参数来控制哪些层需要被训练和保存。\n\n资料来源：[src/peft/peft_model.py:100-150]()\n\n### 问答任务（Question Answering）\n\n问答任务要求模型根据给定的上下文回答问题。`PeftModelForQuestionAnswering` 类专门处理抽取式问答场景。\n\n```python\nfrom transformers import AutoModelForQuestionAnswering\nfrom peft import PeftModelForQuestionAnswering, get_peft_config\n\npeft_config = get_peft_config({\n \"peft_type\": \"LORA\",\n \"task_type\": \"QUESTION_ANS\",\n \"r\": 16,\n \"target_modules\": [\"query\", \"value\"]\n})\n\nmodel = AutoModelForQuestionAnswering.from_pretrained(\"bert-base-cased\")\npeft_model = PeftModelForQuestionAnswering(model, peft_config)\n```\n\n默认情况下，问答任务的分类层名称为 `qa_outputs`，可以通过配置参数进行自定义。\n\n资料来源：[src/peft/peft_model.py:1-50]()\n\n### 特征提取（Feature Extraction）\n\n特征提取任务用于获取输入序列的嵌入表示，可用于下游任务的特征输入或相似度计算等场景。\n\n```python\nfrom transformers import AutoModel\nfrom peft import PeftModelForFeatureExtraction, get_peft_config\n\npeft_config = get_peft_config({\n \"peft_type\": \"LORA\",\n \"task_type\": \"FEATURE_EXTRACTION\",\n \"r\": 16\n})\n\nmodel = AutoModel.from_pretrained(\"bert-base-cased\")\npeft_model = PeftModelForFeatureExtraction(model, peft_config)\n```\n\n`PeftModelForFeatureExtraction` 的 `forward()` 方法支持丰富的参数，包括 `input_ids`、`attention_mask`、`inputs_embeds`、`output_attentions`、`output_hidden_states` 等，可根据具体需求灵活配置。\n\n资料来源：[src/peft/peft_model.py:50-100]()\n\n## 适配器方法与配置\n\nPEFT 支持多种参数高效微调方法，每种方法都有其独特的配置选项和应用场景。\n\n### LoRA（Low-Rank Adaptation）\n\nLoRA 是最广泛使用的 PEFT 方法之一，通过在预训练权重旁边添加低秩分解矩阵来实现高效微调。\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `r` | int | LoRA 矩阵的秩，值越大表示表达能力越强，但参数量也越大 |\n| `lora_alpha` | int | LoRA 的缩放因子，通常设置为 `r` 的两倍 |\n| `lora_dropout` | float | LoRA 层的 Dropout 概率 |\n| `target_modules` | List[str] | 需要应用 LoRA 的模块名称，如 `[\"q_proj\", \"v_proj\"]` |\n| `bias` | str | bias 的训练策略，可选 `\"none\"`、`\"all\"`、`\"lora_only\"` |\n| `fan_in_fan_out` | bool | 是否将权重转置 |\n\n资料来源：[src/peft/tuners/lora/model.py:1-80]()\n\n### IA³（Adapters by Inhibiting and Amplifying Inner Activations）\n\nIA³ 方法通过学习向量来缩放隐藏状态，实现对模型行为的精细调控。\n\n```python\nfrom peft import IA3Config, IA3Model\n\nconfig = IA3Config(\n task_type=TaskType.SEQ_2_SEQ_LM,\n target_modules=[\"q\", \"v\", \"k\", \"wo\", \"wi\"],\n feedforward_modules=[\"wi\"]\n)\n\nmodel = AutoModelForSeq2SeqLM.from_pretrained(\"t5-base\")\nia3_model = IA3Model(config, model)\n```\n\nIA³ 特别适合序列到序列任务，其 `target_modules` 和 `feedforward_modules` 参数用于指定缩放向量应用的位置。\n\n资料来源：[src/peft/tuners/ia3/model.py:1-60]()\n\n### Prefix Tuning（前缀微调）\n\nPrefix Tuning 通过在注意力层之前添加可学习的前缀 token 来引导模型生成。\n\n```python\nfrom peft import PrefixTuningConfig\n\nconfig = PrefixTuningConfig(\n task_type=TaskType.SEQ_CLS,\n num_virtual_tokens=20,\n token_dim=768,\n num_transformer_submodules=1,\n num_attention_heads=12,\n num_layers=12,\n prefix_projection=False\n)\n```\n\n关键参数包括 `num_virtual_tokens`（虚拟 token 数量）、`prefix_projection`（是否使用两层 MLP 投影）以及 `postprocess_past_key_value_function`（用于自定义 KV 缓存后处理的函数）。\n\n资料来源：[src/peft/peft_model.py:50-100]()\n\n### Prompt Tuning\n\nPrompt Tuning 是一种简洁的提示学习方法，仅通过学习嵌入层来实现任务适应。\n\n```python\nfrom peft import PromptTuningConfig, PromptTuningInit\n\nconfig = PromptTuningConfig(\n task_type=TaskType.SEQ_2_SEQ_LM,\n num_virtual_tokens=20,\n prompt_tuning_init=\"TEXT\",\n prompt_tuning_init_text=\"Predict if sentiment of this review is positive, negative or neutral\",\n tokenizer_name_or_path=\"t5-base\"\n)\n```\n\n`PromptTuningInit` 支持多种初始化方式：`RANDOM`、`TEXT`、`AVERAGE_EMBEDDINGS` 和 `SAMPLE_VOCAB`。当使用 `SAMPLE_VOCAB` 时，嵌入会根据词汇表进行随机采样初始化。\n\n资料来源：[src/peft/tuners/prompt_tuning/model.py:1-80]()\n\n### X-LoRA\n\nX-LoRA 是一种支持多适配器动态组合的方法，允许在推理时动态加载和组合多个 LoRA 适配器。\n\n```python\nfrom peft import XLoraConfig, get_xlora_config\n\nconfig = XLoraConfig(\n base_model_config=None,\n adapters={\n \"adapter_1\": \"./path/to/checkpoint1/\",\n \"adapter_2\": \"./path/to/checkpoint2/\"\n }\n)\n\nxlora_model = get_peft_model(model, config)\n```\n\nX-LoRA 支持量化模型（INT8/INT4），可通过 BitsAndBytesConfig 配置，支持 `flash_attention_2` 加速推理。\n\n资料来源：[src/peft/tuners/xlora/model.py:1-100]()\n\n## 工作流程与架构\n\n### 典型 PEFT 工作流程\n\n```mermaid\ngraph TD\n A[加载预训练模型] --> B[创建 PEFT 配置]\n B --> C[应用 PEFT 配置]\n C --> D{适配器类型}\n D -->|LoRA| E[替换目标层为 LoRA 层]\n D -->|IA³| F[添加缩放向量]\n D -->|Prefix| G[添加可学习前缀]\n D -->|Prompt| H[替换嵌入层]\n E --> I[训练 PEFT 模型]\n F --> I\n G --> I\n H --> I\n I --> J[保存适配器]\n J --> K[加载并合并]\n```\n\n### 适配器注入机制\n\nPEFT 的核心机制是通过 `inject_adapter()` 方法将适配器层注入到基础模型中。这个过程涉及目标模块的识别、替换和配置。\n\n```python\ndef inject_adapter(\n model: nn.Module,\n adapter_name: str,\n autocast_adapter_dtype: bool = True,\n low_cpu_mem_usage: bool = False,\n state_dict: Optional[dict[str, torch.Tensor]] = None,\n) -> None:\n```\n\n注入过程会遍历模型的子模块，根据配置中的 `target_modules` 映射找到需要替换的目标层，然后创建对应的适配器层进行替换。系统会检查目标模块的兼容性，防止在不支持的架构（如 Mamba）上应用不兼容的适配器。\n\n资料来源：[src/peft/tuners/tuners_utils.py:1-50]()\n\n### 模型合并与卸载\n\n训练完成后，PEFT 支持将适配器权重合并回基础模型，或完全卸载适配器恢复原始模型。\n\n```python\n# 合并并卸载\nmerged_model = peft_model.merge_and_unload()\n\n# 仅卸载（恢复基础模型）\nbase_model = peft_model.unload()\n```\n\n`merge_and_unload()` 方法使用 `safe_merge` 参数控制在合并前是否进行数值稳定性检查。`unload()` 方法则完全移除所有 PEFT 层，返回原始的基础模型。\n\n资料来源：[src/peft/tuners/tuners_utils.py:1-50]()\n\n## 高级功能\n\n### 签名更新工具\n\nPEFT 提供了 `update_forward_signature()` 和 `update_generate_signature()` 工具函数，用于更新封装后的模型方法签名，使 IDE 和帮助系统能够正确显示参数信息。\n\n```python\nfrom peft import update_forward_signature, update_generate_signature\n\npeft_model = get_peft_model(model, peft_config)\nupdate_forward_signature(peft_model) # 更新 forward 方法签名\nupdate_generate_signature(peft_model) # 更新 generate 方法签名\n```\n\n这些函数会检查当前签名的参数数量和名称，仅当签名只包含 `*args` 和 `**kwargs` 时才进行更新，确保不会意外覆盖有意义的方法签名。\n\n资料来源：[src/peft/helpers.py:1-100]()\n\n### 适配器缩放上下文管理器\n\n`rescale_adapter_scale()` 上下文管理器允许临时调整适配器的缩放因子，这在某些特殊的推理场景下非常有用。\n\n```python\nfrom peft import rescale_adapter_scale\n\nwith rescale_adapter_scale(peft_model, multiplier=2.0):\n outputs = peft_model(inputs)\n```\n\n该管理器会在进入上下文时修改缩放值，在退出时自动恢复原始值，确保不改变模型状态的持久性。\n\n资料来源：[src/peft/helpers.py:100-150]()\n\n### 多适配器管理\n\nPEFT 支持在同一模型上同时管理多个适配器，通过 `add_adapter()` 方法添加新适配器，通过 `set_adapter()` 方法切换当前活动的适配器。\n\n```python\n# 添加新适配器\npeft_model.add_adapter(new_adapter_name, new_peft_config)\n\n# 切换适配器\npeft_model.set_adapter(adapter_name)\n```\n\n添加适配器时，新层默认设置为 `requires_grad_(False)`（不可训练），需要显式调用才能激活训练。\n\n资料来源：[src/peft/tuners/tuners_utils.py:1-50]()\n\n### 量化训练支持\n\nPEFT 与 bitsandbytes 库深度集成，支持 INT8 和 INT4 量化训练。\n\n```python\nimport torch\nimport transformers\nfrom peft import get_peft_model, LoraConfig, prepare_model_for_kbit_training\n\nquantization_config = transformers.BitsAndBytesConfig(load_in_8bit=True)\nmodel = AutoModelForCausalLM.from_pretrained(\n \"mistralai/Mistral-7B-Instruct-v0.1\",\n quantization_config=quantization_config,\n device_map=\"auto\"\n)\nmodel = prepare_model_for_kbit_training(model)\npeft_model = get_peft_model(model, peft_config)\n```\n\n`prepare_model_for_kbit_training()` 函数负责准备量化模型以进行梯度计算，包括正确配置嵌入层和 lm_head 层的梯度设置。\n\n资料来源：[src/peft/tuners/lora/model.py:1-50]()\n\n## 配置参数速查表\n\n### LoRA 配置参数\n\n| 参数名 | 必需 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `r` | 是 | - | LoRA 矩阵秩 |\n| `lora_alpha` | 否 | `r` | 缩放因子 |\n| `lora_dropout` | 否 | `0.0` | Dropout 概率 |\n| `target_modules` | 否 | `None` | 目标模块列表 |\n| `bias` | 否 | `\"none\"` | bias 训练策略 |\n| `fan_in_fan_out` | 否 | `False` | 权重转置 |\n| `modules_to_save` | 否 | `None` | 额外保存的模块 |\n\n### Prefix Tuning 配置参数\n\n| 参数名 | 必需 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `num_virtual_tokens` | 是 | - | 虚拟 token 数量 |\n| `token_dim` | 是 | - | token 维度 |\n| `num_transformer_submodules` | 否 | `1` | transformer 子模块数 |\n| `num_attention_heads` | 是 | - | 注意力头数 |\n| `num_layers` | 是 | - | 层数 |\n| `prefix_projection` | 否 | `False` | 是否投影 |\n\n### Prompt Tuning 配置参数\n\n| 参数名 | 必需 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `num_virtual_tokens` | 是 | - | 虚拟 token 数量 |\n| `prompt_tuning_init` | 否 | `RANDOM` | 初始化方式 |\n| `prompt_tuning_init_text` | 条件 | - | 文本初始化内容 |\n| `tokenizer_name_or_path` | 条件 | - | 分词器路径 |\n\n## 最佳实践\n\n### 目标模块选择建议\n\n不同的模型架构适合不同的目标模块配置：\n\n- **Transformer 注意力层**：优先选择 `q_proj`、`v_proj`，其次考虑 `k_proj`、`o_proj`\n- **Feed-Forward 层**：对于 MoE 或大型 FFN 层，可考虑 `gate_proj`、`up_proj`、`down_proj`\n- **嵌入层**：对于特定任务，可添加 `embed_tokens` 或 `word_embeddings`\n\n### 秩（Rank）选择指南\n\n| 任务复杂度 | 推荐秩值 | 参数量级 |\n|-----------|---------|---------|\n| 简单分类 | 4-8 | ~100K |\n| 标准生成 | 8-16 | ~500K |\n| 复杂推理 | 16-64 | ~2M |\n| 大规模微调 | 64-128 | ~10M+ |\n\n### 训练技巧\n\n1. **学习率调整**：PEFT 模型通常需要比全量微调更高的学习率，建议 1e-3 到 5e-4\n2. **Epoch 数量**：由于参数较少，PEFT 通常需要更多 epoch 才能收敛\n3. **权重衰减**：建议对 LoRA 层使用较小的权重衰减（0.01 或 0.0）\n4. **Gradient Clipping**：标准设置 max_norm=1.0 适用于大多数场景\n\n## 相关资源\n\n- 因果语言建模示例：`examples/causal_language_modeling`\n- 条件生成示例：`examples/conditional_generation`\n- 序列分类示例：`examples/sequence_classification`\n- 图像分类示例：`examples/image_classification`\n- SFT 微调示例：`examples/sft`\n- INT8 训练示例：`examples/int8_training`\n- LoRA Dreambooth 示例：`examples/lora_dreambooth`\n\n---\n\n\n\n## 开发者指南与贡献\n\n### 相关页面\n\n相关主题：[PEFT概述与快速入门](#overview), [核心模块与架构](#core-modules)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [CONTRIBUTING.md](https://github.com/huggingface/peft/blob/main/CONTRIBUTING.md)\n- [src/peft/peft_model.py](https://github.com/huggingface/peft/blob/main/src/peft/peft_model.py)\n- [src/peft/helpers.py](https://github.com/huggingface/peft/blob/main/src/peft/helpers.py)\n- [src/peft/tuners/tuners_utils.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/tuners_utils.py)\n- [src/peft/tuners/lora/model.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/lora/model.py)\n- [src/peft/tuners/ia3/model.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/ia3/model.py)\n- [src/peft/tuners/oft/model.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/oft/model.py)\n- [src/peft/tuners/hra/model.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/hra/model.py)\n \n\n# 开发者指南与贡献\n\n## 概述\n\nPEFT（Parameter-Efficient Fine-Tuning）是一个专注于参数高效微调方法的开源库，集成了 Transformers、Diffusers 和 Accelerate 等主流深度学习框架。该项目旨在帮助开发者以最小的计算和存储成本，将大规模预训练模型高效适配到各类下游应用场景。资料来源：[README.md](https://github.com/huggingface/peft/blob/main/README.md)\n\n本页面面向希望深度参与 PEFT 项目开发的贡献者，涵盖自定义 Tuner 实现、模型集成、低级 API 使用、问题排查以及贡献流程等核心主题。\n\n## 架构设计概览\n\nPEFT 采用模块化的 Tuner 架构，每种微调方法（如 LoRA、IA³、OFT 等）都有独立的实现模块。资料来源：[src/peft/tuners/tuners_utils.py:1-50](https://github.com/huggingface/peft/blob/main/src/peft/tuners/tuners_utils.py)\n\n```mermaid\ngraph TD\n A[PeftModel 基类] --> B[TunerMixin]\n B --> C[各 Tuner 实现]\n C --> D[LoRA]\n C --> E[IA³]\n C --> F[OFT]\n C --> G[HRA]\n C --> H[其他 Tuner]\n \n I[BaseTunerLayer] --> J[各 Tuner Layer]\n J --> K[LoRALayer]\n J --> L[IA³Layer]\n J --> M[OFTLayer]\n \n N[PeftConfig] --> O[各配置类]\n O --> P[LoraConfig]\n O --> Q[IA³Config]\n O --> R[OFTConfig]\n```\n\n## 自定义 Tuner 开发\n\n### 核心组件结构\n\n每个 Tuner 实现需要包含以下核心组件：资料来源：[src/peft/tuners/lora/model.py:1-60](https://github.com/huggingface/peft/blob/main/src/peft/tuners/lora/model.py)\n\n| 组件 | 说明 | 必需性 |\n|------|------|--------|\n| Config 类 | 存储 Tuner 特定配置参数 | 必须 |\n| Layer 类 | 封装原始层并添加适配逻辑 | 必须 |\n| Model 类 | 实现模块替换和适配器注入 | 必须 |\n| target_module_mapping | 目标模块名称映射 | 推荐 |\n\n### Model 类实现规范\n\nTuner 的 Model 类必须继承自适当的基类，并实现以下关键方法：资料来源：[src/peft/tuners/oft/model.py:1-80](https://github.com/huggingface/peft/blob/main/src/peft/tuners/oft/model.py)\n\n```python\nclass MyTunerModel(BaseTunerModel):\n # 类级别属性\n prefix: str = \"my_tuner_\"\n tuner_layer_cls = MyTunerLayer\n target_module_mapping = TRANSFORMERS_MODELS_TO_MY_TUNER_TARGET_MODULES_MAPPING\n \n def _create_and_replace(\n self,\n my_tuner_config,\n adapter_name,\n target,\n target_name,\n parent,\n current_key,\n **optional_kwargs,\n ):\n # 核心替换逻辑\n if isinstance(target, Linear):\n # 创建或更新适配层\n```\n\n### Layer 类实现\n\nLayer 类负责在基础层之上添加适配参数：资料来源：[src/peft/tuners/ia3/model.py:1-100](https://github.com/huggingface/peft/blob/main/src/peft/tuners/ia3/model.py)\n\n| 方法 | 功能 |\n|------|------|\n| `__init__` | 初始化适配层参数 |\n| `update_layer` | 更新已存在适配层的配置 |\n| `merge` | 合并适配权重到基础层 |\n| `unmerge` | 从基础层分离适配权重 |\n\n### _create_and_replace 方法详解\n\n此方法是 Tuner 替换逻辑的核心，负责将原始模块替换为适配层：资料来源：[src/peft/tuners/hra/model.py:80-120](https://github.com/huggingface/peft/blob/main/src/peft/tuners/hra/model.py)\n\n```python\ndef _create_and_replace(\n self,\n hra_config,\n adapter_name,\n target,\n target_name,\n parent,\n current_key,\n **optional_kwargs,\n):\n if current_key is None:\n raise ValueError(\"Current Key shouldn't be `None`\")\n\n # 如果不是 HRALayer，创建新模块；否则更新现有层\n if not isinstance(target, HRALayer):\n new_module = self._create_new_module(hra_config, adapter_name, target, r=hra_config.r)\n if adapter_name not in self.active_adapters:\n new_module.requires_grad_(False)\n self._replace_module(parent, target_name, new_module, target)\n else:\n target.update_layer(\n adapter_name,\n r=hra_config.r,\n config=hra_config,\n )\n```\n\n## 低级 API 使用\n\n### inject_adapter 方法\n\n`inject_adapter` 方法允许开发者手动将适配器注入到模型中，而不依赖 `get_peft_model` 封装：资料来源：[src/peft/tuners/tuners_utils.py:1-50](https://github.com/huggingface/peft/blob/main/src/peft/tuners/tuners_utils.py)\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| model | nn.Module | 要注入适配器的模型 |\n| adapter_name | str | 适配器名称，默认 \"default\" |\n| autocast_adapter_dtype | bool | 是否自动转换适配器数据类型 |\n| low_cpu_mem_usage | bool | 是否在 meta 设备上创建空权重以加速加载 |\n| state_dict | dict | 可选的预加载权重字典 |\n\n### merge_and_unload 操作\n\n合并操作将适配器权重与基础模型融合：资料来源：[src/peft/tuners/tuners_utils.py:1-30](https://github.com/huggingface/peft/blob/main/src/peft/tuners/tuners_utils.py)\n\n```python\n# 合并并卸载适配器\nmerged_model = peft_model.merge_and_unload(progressbar=True, safe_merge=False)\n\n# 仅卸载而不合并\nbase_model = peft_model.unload()\n```\n\n### Helper 函数\n\n`helpers.py` 模块提供了多个实用函数用于签名更新和模型检查：资料来源：[src/peft/helpers.py:1-100](https://github.com/huggingface/peft/blob/main/src/peft/helpers.py)\n\n| 函数 | 功能 |\n|------|------|\n| `update_forward_signature` | 更新 PeftModel 的 forward 签名以包含父类参数 |\n| `update_generate_signature` | 更新 PeftModel 的 generate 签名 |\n| `check_if_peft_model` | 检查模型是否为 PEFT 模型 |\n| `rescale_adapter_scale` | 临时调整适配器缩放因子的上下文管理器 |\n\n## 适配器生命周期管理\n\n```mermaid\ngraph LR\n A[加载基础模型] --> B[创建 PeftConfig]\n B --> C[get_peft_model 或 inject_adapter]\n C --> D[创建适配层]\n D --> E[训练适配器]\n E --> F[merge_and_unload 或保存]\n F --> G[卸载适配器]\n```\n\n## 贡献流程\n\n### 提交 Pull Request 规范\n\n1. Fork 仓库并创建功能分支\n2. 确保代码通过所有现有测试\n3. 为新功能添加测试用例\n4. 更新相关文档\n5. 提交 PR 并描述变更内容\n\n### 代码风格要求\n\n- 遵循 PEP 8 代码规范\n- 为公共 API 添加完整的类型注解\n- 为复杂逻辑编写文档字符串\n- 确保提交信息清晰描述变更内容\n\n### 新 Tuner 贡献检查清单\n\n添加新的 Tuner 实现时，需确保完成以下内容：资料来源：[CONTRIBUTING.md](https://github.com/huggingface/peft/blob/main/CONTRIBUTING.md)\n\n| 检查项 | 说明 |\n|--------|------|\n| Config 类 | 实现完整的配置验证逻辑 |\n| Layer 类 | 实现权重初始化、更新和合并方法 |\n| Model 类 | 实现模块替换逻辑 |\n| 测试用例 | 覆盖核心功能和边界情况 |\n| 文档示例 | 提供完整的使用示例代码 |\n| 目标模块映射 | 定义支持的模型架构和层名称 |\n\n## 常见问题排查\n\n### 模块兼容性检查\n\n某些特定架构（如 Mamba）存在不兼容的模块，PEFT 提供了专门的检查机制：资料来源：[src/peft/tuners/tuners_utils.py:1-50](https://github.com/huggingface/peft/blob/main/src/peft/tuners/tuners_utils.py)\n\n```python\ndef _check_target_module_compatiblity(self, peft_config, model, target_name):\n \"\"\"防止将 LoRA 应用于不兼容的模块\"\"\"\n _check_lora_target_modules_mamba(peft_config, model, target_name)\n```\n\n### 适配器状态管理\n\n| 问题 | 解决方案 |\n|------|----------|\n| 适配器未激活 | 使用 `set_adapter` 方法切换活动适配器 |\n| 权重未更新 | 检查 `active_peft_config` 配置 |\n| 合并失败 | 确认基础模型支持合并操作 |\n\n### 内存优化建议\n\n| 策略 | 适用场景 |\n|------|----------|\n| `low_cpu_mem_usage=True` | 大模型加载阶段 |\n| 4-bit/8-bit 量化 | 显存受限环境 |\n| 梯度检查点 | 长序列训练 |\n\n## 集成最佳实践\n\n### 与 Transformers 集成\n\nPEFT 与 Transformers 库深度集成，支持直接使用 `AutoModelForX` 系列接口：资料来源：[src/peft/peft_model.py:1-100](https://github.com/huggingface/peft/blob/main/src/peft/peft_model.py)\n\n```python\nfrom transformers import AutoModelForSequenceClassification\nfrom peft import PeftModelForSequenceClassification, get_peft_config\n\nmodel = AutoModelForSequenceClassification.from_pretrained(\"bert-base-cased\")\npeft_model = PeftModelForSequenceClassification(model, peft_config)\npeft_model.print_trainable_parameters()\n```\n\n### 与 Diffusers 集成\n\n对于 Stable Diffusion 等扩散模型，PEFT 提供专门的适配接口：资料来源：[src/peft/tuners/oft/model.py:1-60](https://github.com/huggingface/peft/blob/main/src/peft/tuners/oft/model.py)\n\n```python\nfrom diffusers import StableDiffusionPipeline\nfrom peft import OFTModel\n\nmodel = StableDiffusionPipeline.from_pretrained(\"runwayml/stable-diffusion-v1-5\")\nmodel.text_encoder = OFTModel(model.text_encoder, config_te, \"default\")\nmodel.unet = OFTModel(model.unet, config_unet, \"default\")\n```\n\n## 扩展阅读\n\n- [PEFT 官方文档](https://huggingface.co/docs/peft)\n- [PEFT 模型集合](https://huggingface.co/PEFT)\n- [Transformers 集成指南](https://huggingface.co/docs/transformers/main/en/perf_train_gpu_one)\n- [Diffusers 适配器管理](https://huggingface.co/docs/diffusers/en/using-diffusers/loading)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：huggingface/peft\n\n摘要：发现 18 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：配置坑 - 来源证据：[BUG] peft 0.19 target_modules (str) use `set`。\n\n## 1. 配置坑 · 来源证据：[BUG] peft 0.19 target_modules (str) use `set`\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[BUG] peft 0.19 target_modules (str) use `set`\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_bd098228d56f4251949a351ac90335fc | https://github.com/huggingface/peft/issues/3229 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 安全/权限坑 · 来源证据：Comparison of Different Fine-Tuning Techniques for Conversational AI\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Comparison of Different Fine-Tuning Techniques for Conversational AI\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_408252d26b4a4d87b9ca9362c3b4b37b | https://github.com/huggingface/peft/issues/2310 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 安装坑 · 来源证据：Feature Request: Improve offline support for custom architectures in get_peft_model_state_dict\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Feature Request: Improve offline support for custom architectures in get_peft_model_state_dict\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_32e0990aa35b430bac525df543e75cac | https://github.com/huggingface/peft/issues/3211 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. 配置坑 · 来源证据：0.17.0: SHiRA, MiSS, LoRA for MoE, and more\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：0.17.0: SHiRA, MiSS, LoRA for MoE, and more\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a7ec4779d09a4fcebe0901d73f869bf0 | https://github.com/huggingface/peft/releases/tag/v0.17.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 5. 配置坑 · 来源证据：Applying Dora to o_proj of Meta-Llama-3.1-8B results in NaN\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Applying Dora to o_proj of Meta-Llama-3.1-8B results in NaN\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ce144c340d9f40929a6551e9dbca770d | https://github.com/huggingface/peft/issues/2049 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 6. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:570384908 | https://github.com/huggingface/peft | README/documentation is current enough for a first validation pass.\n\n## 7. 运行坑 · 来源证据：0.17.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：0.17.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_cd675dc497c44319af556a2e7059dd95 | https://github.com/huggingface/peft/releases/tag/v0.17.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 8. 运行坑 · 来源证据：v0.15.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.15.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_66bfe8be731a44de971b991569f61e57 | https://github.com/huggingface/peft/releases/tag/v0.15.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 9. 运行坑 · 来源证据：v0.15.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.15.2\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3d5933ee300d4f68bfab2f0440fae679 | https://github.com/huggingface/peft/releases/tag/v0.15.2 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 10. 维护坑 · 来源证据：0.16.0: LoRA-FA, RandLoRA, C³A, and much more\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：0.16.0: LoRA-FA, RandLoRA, C³A, and much more\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5ef66863f7c64b3e9e3ba6a72eaab639 | https://github.com/huggingface/peft/releases/tag/v0.16.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 11. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:570384908 | https://github.com/huggingface/peft | last_activity_observed missing\n\n## 12. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:570384908 | https://github.com/huggingface/peft | no_demo; severity=medium\n\n## 13. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:570384908 | https://github.com/huggingface/peft | no_demo; severity=medium\n\n## 14. 安全/权限坑 · 来源证据：0.18.0: RoAd, ALoRA, Arrow, WaveFT, DeLoRA, OSF, and more\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：0.18.0: RoAd, ALoRA, Arrow, WaveFT, DeLoRA, OSF, and more\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b28315fbb2d44b748ca46f87fafd3d33 | https://github.com/huggingface/peft/releases/tag/v0.18.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 15. 安全/权限坑 · 来源证据：v0.15.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.15.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1a3ce413d14349658dc005c25754bb1f | https://github.com/huggingface/peft/releases/tag/v0.15.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 16. 安全/权限坑 · 来源证据：v0.19.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.19.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_abcf15a2812744f0a37ad5c5d75643cf | https://github.com/huggingface/peft/releases/tag/v0.19.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 17. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:570384908 | https://github.com/huggingface/peft | issue_or_pr_quality=unknown\n\n## 18. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:570384908 | https://github.com/huggingface/peft | release_recency=unknown\n\n\n",
"markdown_key": "peft",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:570384908",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/huggingface/peft"
},
{
"evidence_id": "art_00af04d1514347d2a8b62735d079f976",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/huggingface/peft#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "peft 说明书",
"toc": [
"https://github.com/huggingface/peft 项目说明书",
"目录",
"PEFT概述与快速入门",
"什么是PEFT",
"PEFT架构概览",
"支持的PEFT方法",
"安装指南",
"快速入门",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "758cdac51922abbb24b6e772844c0a88bbe1cd7d",
"repo_inspection_error": null,
"repo_inspection_files": [
"pyproject.toml",
"README.md",
"requirements.txt",
"docs/README.md",
"docs/source/index.md",
"docs/source/_config.py",
"docs/source/install.md",
"docs/source/quicktour.md",
"docs/source/_toctree.yml",
"docs/source/developer_guides/model_merging.md",
"docs/source/developer_guides/torch_compile.md",
"docs/source/developer_guides/contributing.md",
"docs/source/developer_guides/mixed_models.md",
"docs/source/developer_guides/troubleshooting.md",
"docs/source/developer_guides/lora.md",
"docs/source/developer_guides/checkpoint.md",
"docs/source/developer_guides/custom_models.md",
"docs/source/developer_guides/low_level_api.md",
"docs/source/developer_guides/quantization.md",
"docs/source/package_reference/fourierft.md",
"docs/source/package_reference/cartridges.md",
"docs/source/package_reference/psoft.md",
"docs/source/package_reference/hira.md",
"docs/source/package_reference/tinylora.md",
"docs/source/package_reference/layernorm_tuning.md",
"docs/source/package_reference/adalora.md",
"docs/source/package_reference/peft_types.md",
"docs/source/package_reference/miss.md",
"docs/source/package_reference/osf.md",
"docs/source/package_reference/lora.md",
"docs/source/package_reference/xlora.md",
"docs/source/package_reference/lora_conversion.md",
"docs/source/package_reference/tuners.md",
"docs/source/package_reference/beft.md",
"docs/source/package_reference/peft_model.md",
"docs/source/package_reference/c3a.md",
"docs/source/package_reference/lokr.md",
"docs/source/package_reference/auto_class.md",
"docs/source/package_reference/helpers.md",
"docs/source/package_reference/loha.md"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# peft - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 peft 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **想在安装前理解开源项目价值和边界的用户**：当前证据主要来自项目文档。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md`, `docs/source/install.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `pip install peft` 证据：`README.md` Claim：`clm_0003` supported 0.86\n- `pip install git+https://github.com/huggingface/peft` 证据：`docs/source/install.md` Claim：`clm_0004` supported 0.86\n- `git clone https://github.com/huggingface/peft` 证据：`docs/source/install.md` Claim：`clm_0005` supported 0.86\n- `pip install -e .[test]` 证据：`docs/source/install.md` Claim：`clm_0006` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：先做角色匹配试用\n- **为什么**：这个项目更像角色库，核心风险是选错角色或把角色文案当执行能力；先用 Prompt Preview 试角色匹配，再决定是否沙盒导入。\n\n### 30 秒判断\n\n- **现在怎么做**：先做角色匹配试用\n- **最小安全下一步**：先用 Prompt Preview 试角色匹配；满意后再隔离导入\n- **先别相信**：角色质量和任务匹配不能直接相信。\n- **继续会触碰**：角色选择偏差、命令执行、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：想在安装前理解开源项目价值和边界的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md`, `docs/source/install.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n### 现在还不能相信\n\n- **角色质量和任务匹配不能直接相信。**（unverified）：角色库证明有很多角色，不证明每个角色都适合你的具体任务，也不证明角色能产生高质量结果。\n- **不能把角色文案当成真实执行能力。**（unverified）：安装前只能判断角色描述和任务画像是否匹配，不能证明它能在宿主 AI 里完成任务。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n\n### 继续会触碰什么\n\n- **角色选择偏差**：用户对任务应该由哪个专家角色处理的判断。 原因：选错角色会让 AI 从错误专业视角回答，浪费时间或误导决策。\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`, `docs/source/install.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`, `docs/source/install.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：先用交互式试用验证任务画像和角色匹配，不要先导入整套角色库。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **保留原始角色选择记录**：如果输出偏题，可以回到任务画像阶段重新选择角色，而不是继续沿着错误角色推进。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0007` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md`, `docs/source/install.md` Claim：`clm_0008` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md`, `docs/source/install.md` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：768\n- 重要文件覆盖：40/768\n- 证据索引条目：80\n- 角色 / Skill 条目：79\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 peft 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 peft 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 peft 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 79 个角色 / Skill / 项目文档条目。\n\n- **Generating the documentation**（project_doc）： B[任务特定模型]\n A --> C[Tuner层]\n A --> D[配置管理]\n \n B --> B1[PeftModelForCausalLM]\n B --> B2[PeftModelForSeq2SeqLM]\n B --> B3[PeftModelForSequenceClassification]\n B --> B4[PeftModelForTokenClassification]\n B --> B5[PeftModelForQuestionAnswering]\n B --> B6[PeftModelForFeatureExtraction]\n \n C --> C1[LoraModel]\n C --> C2[ShiraModel]\n C --> C3[GraloraModel]\n C --> C4[XloraModel]\n C --> C5[MissModel]\n C --> C6[OFTModel]\n \n D --> D1[PeftConfig]\n D --> D2[get_peft_config]\n D --> D3[from_pretrained]\n```\n\n资料来源：[src/peft/peft_model.py:1-50]()\n\n## 支持的PEFT方法\n\nPEFT库支持多种参数高效微调方法，每种方法适用于不同的场景和模型架构。\n\n| 方法 | 简称 | 描述 | 适用场景 |\n|------|------|------|----------|\n| LoRA | Low-Rank Adaptation | 通过低秩矩阵分解近似权重更新 | 通用场景，支持大多数模型 |\n| QLoRA | Quantized LoRA | 结合量化技术的LoRA变体 | 大模型int4/int8量化训练 |\n| Prefix Tuning | 前缀微调 | 在输入前添加可学习前缀 | 生成任务 |\n| Prompt Tuning | 提示微调 | 仅学习软提示向量 | 极端参数高效场景 |\n| P-Tuning | P-tuning | 使用LSTM/MLP编码提示 | NLU任务 |\n| IA³ | Infused Adapter by Inhibiting Amplify | 注入式适配器 | 任务迁移 |\n| AdaLoRA | Adaptive LoRA | 自适应秩分配 | 资源受限场景 |\n| LoHa | LoRA with Hadamard Product | 使用Hadamard积 | 低参数场景 |\n| LoKR | LoRA with Kronecker Product | 使用Kronecker积 | 高效参数利用 |\n| OFT | Orthogonal Finetuning | 正交微调 | 扩散模型 |\n| SHiRA | 层级正则化适配器 | 分层正则化策略 | 多任务场景 |\n| GraLoRA | Gradient-aware LoRA | 梯度感知LoRA | 复杂任务 |\n| xLoRA | 专家混合LoRA | 多专家LoRA组合 | 大模型高效适配 |\n| MiSS | 模型分片共享 | 分片权重共享结构 | 资源受限训练 |\n\n资料来源：[src/peft/tuners/lora/model.py:1-30]()、[src/peft/tuners/shira/model.py:1-20]()、[src/peft/tuners/gralora/model.py:1-20]()\n\n## 安装指南\n\n### 基础安装\n\n```bash\npip install peft\n```\n\n### 完整安装（包含所有依赖）\n\n```bash\npip install peft[dev,models,diffusers,qualcomm]\n```\n\n### 从源码安装\n\n```bash\ngit clone https://github.com/huggingface/peft.git\ncd peft\npip install -e .\n```\n\n### GPU特定版本\n\n对于需要GPU支持的环境：\n\n```bash\npip install peft --extra-index-url https://download.pytorch.org/whl/cu118\n```\n\n## 快速入门\n\n### 基本使用流程\n\n使用PEFT进行模型微调的标准流程如下：\n\n```mermaid\ngraph LR\n A[加载基础模型] --> B[创建PeftConfig]\n B --> C[初始化PeftModel]\n C --> D[训练PeftModel]\n D --> E[保存Adapter]\n E --> F[加载Inference]\n```\n\n### LoRA快速示例\n\n以下示例展示如何使用LoRA方法对因果语言模型进行微调：\n\n```python\nfrom transformers import AutoModelForCausalLM, AutoTokenizer\nfrom peft import LoraConfig, get_peft_model, TaskType\n\n# 1. 加载基础模型\nbase_model = AutoModelForCausalLM.from_pretrained(\"facebook/opt-125m\")\n\n# 2. 配置LoRA参数\nlora_config = LoraConfig(\n task_type=TaskType.CAUSAL_LM, # 任务类型\n r=16, # LoRA秩\n lora_alpha=32, # LoRA alpha参数\n lora_dropout=0.05, # Dropout率\n target_modules=[\"q_proj\", \"v_proj\"], # 目标模块\n bias=\"none\",\n)\n\n# 3. 创建PeftModel\npeft_model = get_peft_model(base_model, lora_config)\n\n# 4. 查看可训练参数\npeft_model.print_trainable_parameters()\n# 输出: trainable params: 8388608 || all params: 125018880 || trainable%: 6.710\n\n# 5. 训练模型\n# ... 训练代码 ...\n\n# 6. 保存Adapter\npeft_model.save_pretrained(\"lora_adapter\")\n\n# 7. 推理时加载\nfrom peft import PeftModel\nmodel = AutoModelForCausalLM.from_pretrained(\"facebook/opt-125m\")\npeft_model = PeftModel.from_pretrained(model, \"lora_adapter\")\n```\n\n资料来源：[src/peft/helpers.py:1-50]()\n\n### 不同任务的模型适配\n\nPEFT为不同任务类型提供了专门的模型类：\n\n| 任务类型 | 模型类 | 典型应用 |\n|----------|--------|----------|\n| 因果语言模型 | `PeftModelForCausalLM` | 文本生成 |\n| Seq2Seq | `PeftModelForSeq2SeqLM` | 翻译、摘要 |\n| 序列分类 | `PeftModelForSequenceClassification` | 情感分析、文本分类 |\n| Token分类 | `PeftModelForTokenClassification` | NER、词性标注 |\n| 问答 | `PeftModelForQuestionAnswering` | 问答系统 |\n| 特征提取 | `PeftModelForFeatureExtraction` | 嵌入向量生成 |\n\n资料来源：[src/peft/peft_model.py:50-150]()\n\n### PeftModel.from_pretrained方法\n\n从预训练加载PEFT模型的核心参数：\n\n```python\nPeftModel.from_pretrained(\n model, # 基础模型 (torch.nn.Module)\n model_id, # 模型ID或本地路径 (str)\n adapter_name=\"default\", # Adapter名称 (str)\n is_trainable=False, # 是否可训练 (bool)\n config=None, # 配置对象 (PeftConfig, optional)\n autocast_adapter_dtype=True # 是否自动转换dtype (bool)\n)\n```\n\n资料来源：[src/peft/peft_model.py:150-200]()\n\n### QLoRA配置示例\n\n对于大模型，推荐使用QLoRA进行高效训练：\n\n```python\nfrom transformers import AutoModelForCausalLM, BitsAndBytesConfig\nfrom peft import prepare_model_for_kbit_training, LoraConfig, get_peft_model\n\n# 量化配置\nquantization_config = BitsAndBytesConfig(\n load_in_8bit=True,\n llm_int8_threshold=6.0,\n llm_int8_has_fp16_weight=False\n)\n\n# 加载量化模型\nmodel = AutoModelForCausalLM.from_pretrained(\n \"mistralai/Mistral-7B-Instruct-v0.1\",\n quantization_config=quantization_config,\n device_map=\"auto\"\n)\n\n# 准备kbit训练\nmodel = prepare_model_for_kbit_training(model)\n\n# 配置LoRA\nlora_config = LoraConfig(\n r=64,\n lora_alpha=16,\n target_modules=[\"q_proj\", \"v_proj\", \"k_proj\", \"o_proj\"],\n lora_dropout=0.05,\n bias=\"none\",\n task_type=TaskType.CAUSAL_LM\n)\n\n# 创建PeftModel\npeft_model = get_peft_model(model, lora_config)\n```\n\n## 配置详解\n\n### LoraConfig主要参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `r` | int | 8 | LoRA秩，决定低秩矩阵的维度 |\n| `lora_alpha` | int | 16 | 缩放因子，通常设为2倍r |\n| `lora_dropout` | float | 0.0 | LoRA层的Dropout率 |\n| `target_modules` | List[str] | None | 要应用LoRA的模块名 |\n| `bias` | str | \"none\" | 偏置更新策略: none/all/lora_only |\n| `fan_in_fan_out` | bool | False | 是否转置权重矩阵 |\n| `modules_to_save` | List[str] | None | 需要保存的额外模块 |\n| `init_lora_weights` | bool | True | 是否初始化LoRA权重 |\n\n资料来源：[src/peft/tuners/lora/model.py:30-80]()\n\n### 任务类型枚举\n\n```python\nclass TaskType:\n CAUSAL_LM = \"CAUSAL_LM\" # 因果语言模型\n SEQ_CLS = \"SEQ_CLS\" # 序列分类\n TOKEN_CLS = \"TOKEN_CLS\" # Token分类\n QUESTION_ANS = \"QUESTION_ANS\" # 问答\n FEATURE_EXTRACTION = \"FEATURE_EXTRACTION\" # 特征提取\n SEQ_2_SEQ_LM = \"SEQ_2_SEQ_LM\" # 序列到序列\n```\n\n## 高级功能\n\n### 模型合并与卸载\n\nPEFT支持将adapter与基础模型合并，或完全卸载adapter：\n\n```python\n# 合并并卸载（生成独立模型）\nmerged_model = peft_model.merge_and_unload()\n\n# 仅卸载adapter（返回原始基础模型）\nbase_model = peft_model.unload()\n```\n\n资料来源：[src/peft/tuners/tuners_utils.py:50-80]()\n\n### Adapter热切换\n\n使用hotswap功能在不重新加载模型的情况下切换adapter：\n\n```python\nfrom peft import hotswap_adapter\n\n# 热切换adapter\nhotswap_adapter(model, \"path-to-new-adapter\", adapter_name=\"default\")\n```\n\n### 多Adapter管理\n\nPEFT支持同时加载和使用多个adapter：\n\n```python\n# 加载多个adapter\nmodel.add_adapter(\"adapter_1\", config_1)\nmodel.add_adapter(\"adapter_2\", config_2)\n\n# 设置活动adapter\nmodel.set_adapter(\"adapter_1\")\n\n# 使用特定adapter推理\nmodel.eval()\n```\n\n### 辅助函数\n\nPEFT提供了多个辅助函数用于签名更新和模型检查：\n\n```python\nfrom peft.helpers import update_signature, check_if_peft_model\n\n# 更新forward/generate签名\nupdate_signature(peft_model, method=\"forward\")\nupdate_signature(peft_model, method=\"generate\")\nupdate_signature(peft_model, method=\"all\")\n\n# 检查是否为PEFT模型\nis_peft = check_if_peft_model(\"path-to-model\")\n```\n\n资料来源：[src/peft/helpers.py:1-100]()\n\n## 模型适配器注入机制\n\nPEFT通过`inject_adapter`方法将adapter注入到基础模型：\n\n```python\ndef inject_adapter(\n model, # 目标模型\n adapter_name, # Adapter名称\n autocast_adapter_dtype=True, # 自动转换dtype\n low_cpu_mem_usage=False, # 低内存使用\n state_dict=None # 可选的状态字典\n)\n```\n\n该过程会遍历模型模块，将目标层替换为对应的tuner层：\n\n```mermaid\ngraph TD\n A[inject_adapter调用] --> B[遍历模型模块]\n B --> C{检查模块类型}\n C -->|Linear层| D[创建TunerLayer]\n C -->|其他层| E[跳过]\n D --> F[替换原模块]\n F --> G[注册adapter]\n```\n\n资料来源：[src/peft/tuners/tuners_utils.py:80-120]()\n\n## 与主流框架的集成\n\n### Transformers集成\n\nPEFT与Hugging Face Transformers库深度集成，支持直接使用`AutoModel`系列加载预训练模型并应用PEFT：\n\n```python\nfrom transformers import AutoModelForCausalLM\nfrom peft import get_peft_model, LoraConfig\n\nmodel = AutoModelForCausalLM.from_pretrained(\"meta-llama/Llama-2-7b\")\npeft_model = get_peft_model(model, lora_config)\n```\n\n### Diffusers集成\n\n对于扩散模型，PEFT提供了专门的适配器：\n\n```python\nfrom diffusers import StableDiffusionPipeline\nfrom peft import OFTModel, OFTConfig\n\nconfig = OFTConfig(\n r=8,\n target_modules=[\"k_proj\", \"q_proj\", \"v_proj\"]\n)\nmodel.unet = OFTModel(model.unet, config, \"default\")\n```\n\n资料来源：[src/peft/tuners/miss/model.py:1-30]()、[src/peft/tuners/oft/model.py:1-30]()\n\n### Accelerate集成\n\n对于分布式训练和超大规模模型，PEFT支持与Accelerate配合使用：\n\n```python\nfrom accelerate import Accelerator\nfrom peft import get_peft_model\n\naccelerator = Accelerator()\nmodel = get_peft_model(model, config)\nmodel = accelerator.prepare_model(model)\n```\n\n## 性能基准\n\nPEFT方法在保持参数效率的同时，能够达到与全量微调相当甚至更好的性能：\n\n| 方法 | 可训练参数量 | 性能对比 |\n|------|-------------|----------|\n| 全量微调 | 100% | 基准 |\n| LoRA (r=8) | ~0.1-1% | 相当 |\n| QLoRA | ~0.1-1% | 略低于全量 |\n| Prefix Tuning | ~0.1% | 因任务而异 |\n| Prompt Tuning | ~0.01% | 需更多数据 |\n\n## 下一步\n\n- 深入阅读[PEFT支持的PEFT方法文档](https://huggingface.co/docs/peft)\n- 查看[示例代码库](https://github.com/huggingface/peft/tree/main/examples)\n- 了解[自定义Tuner开发指南](https://huggingface.co/docs/peft/developer_guides/custom_models)\n- 尝试使用[多模态模型微调](https://huggingface.co/docs/peft/multimodal)\n\n---\n\n\n\n## 核心模块与架构\n\n### 相关页面\n\n相关主题：[配置系统](#config-system), [LoRA及其变体实现](#lora-tuners)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/peft/peft_model.py](https://github.com/huggingface/peft/blob/main/src/peft/peft_model.py)\n- [src/peft/mixed_model.py](https://github.com/huggingface/peft/blob/main/src/peft/mixed_model.py)\n- [src/peft/helpers.py](https://github.com/huggingface/peft/blob/main/src/peft/helpers.py)\n- [src/peft/tuners/tuners_utils.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/tuners_utils.py)\n- [src/peft/tuners/shira/model.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/shira/model.py)\n- [src/peft/tuners/gralora/model.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/gralora/model.py)\n- [src/peft/tuners/xlora/model.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/xlora/model.py)\n- [src/peft/tuners/miss/model.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/miss/model.py)\n- [src/peft/tuners/oft/model.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/oft/model.py)\n- [src/peft/tuners/adamss/model.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/adamss/model.py)\n \n\n# 核心模块与架构\n\n## 概述\n\nPEFT（Parameter-Efficient Fine-Tuning）库的核心架构围绕适配器模式设计，通过在不修改原始预训练模型参数的情况下添加少量可训练参数来实现高效的模型微调。该架构采用模块化设计，核心组件包括PeftModel基类、各类任务专用模型类、通用适配器注入机制以及丰富的工具函数。资料来源：[src/peft/peft_model.py:1-200]()\n\n## 核心模块架构图\n\n```mermaid\ngraph TD\n A[PeftModel 基类] --> B[PeftModelForSequenceClassification]\n A --> C[PeftModelForQuestionAnswering]\n A --> D[PeftModelForTokenClassification]\n A --> E[PeftModelForSeq2SeqLM]\n A --> F[PeftModelForFeatureExtraction]\n G[BaseTuner] --> A\n H[TunersUtils] --> G\n I[各Tuner模型类] --> H\n J[ShiraModel] --> I\n K[GraloraModel] --> I\n L[XloraModel] --> I\n M[MissModel] --> I\n N[OFTModel] --> I\n O[AdamssModel] --> I\n```\n\n## PeftModel 基类\n\n### 类职责与定位\n\nPeftModel是整个库的核心基类，负责管理适配器的加载、切换、合并与卸载。它封装了底层的基础模型，并提供了统一的接口供各任务类型模型继承使用。资料来源：[src/peft/peft_model.py:100-150]()\n\n### 主要方法\n\n| 方法名 | 功能描述 | 返回类型 |\n|--------|----------|----------|\n| `from_pretrained()` | 从预训练路径加载PEFT模型和适配器 | `PeftModel` |\n| `merge_and_unload()` | 合并适配器权重到基础模型并卸载适配器 | `torch.nn.Module` |\n| `unload()` | 返回基础模型，移除所有PEFT模块 | `torch.nn.Module` |\n| `inject_adapter()` | 注入适配器层并替换目标模块 | `None` |\n\n### from_pretrained 方法参数\n\n```python\n@classmethod\ndef from_pretrained(\n cls,\n model: torch.nn.Module,\n model_id: str or os.PathLike,\n adapter_name: str = \"default\",\n is_trainable: bool = False,\n config: PeftConfig = None,\n autocast_adapter_dtype: bool = True,\n **kwargs\n) -> PeftModel\n```\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `model` | `torch.nn.Module` | 必需 | 被适配的基础模型 |\n| `model_id` | `str` 或 `os.PathLike` | 必需 | PEFT配置的模型ID或本地路径 |\n| `adapter_name` | `str` | `\"default\"` | 适配器名称，支持加载多个适配器 |\n| `is_trainable` | `bool` | `False` | 是否训练模式，False时适配器被冻结 |\n| `config` | `PeftConfig` | `None` | 预定义的配置对象，与model_id互斥 |\n| `autocast_adapter_dtype` | `bool` | `True` | 是否自动转换适配器数据类型 |\n\n资料来源：[src/peft/peft_model.py:150-200]()\n\n## 任务专用模型类\n\nPEFT针对不同任务类型提供了专用的模型封装类，每个类针对特定任务进行了输入输出接口的适配。\n\n### 模型类列表与继承关系\n\n```mermaid\ngraph LR\n A[PeftModel] --> B[PeftModelForSequenceClassification]\n A --> C[PeftModelForQuestionAnswering]\n A --> D[PeftModelForTokenClassification]\n A --> E[PeftModelForSeq2SeqLM]\n A --> F[PeftModelForFeatureExtraction]\n```\n\n### PeftModelForSequenceClassification\n\n用于序列分类任务（如情感分析），自动配置分类层。构造函数中定义了默认的分类器模块名称列表：\n\n```python\nclassifier_module_names = [\"classifier\", \"score\"]\n```\n\n资料来源：[src/peft/peft_model.py:50-80]()\n\n### PeftModelForQuestionAnswering\n\n用于问答任务，配置问答输出层名称：\n\n```python\nqa_module_names = [\"qa_outputs\"]\n```\n\n资料来源：[src/peft/peft_model.py:30-50]()\n\n### PeftModelForTokenClassification\n\n用于令牌级分类任务（如命名实体识别），使用与序列分类相同的分类器模块名称：\n\n```python\nclassifier_module_names = [\"classifier\", \"score\"]\n```\n\n资料来源：[src/peft/peft_model.py:180-210]()\n\n### PeftModelForSeq2SeqLM\n\n用于序列到序列生成任务（如翻译、摘要），继承基类并额外保存生成相关方法引用：\n\n```python\nself.base_model_prepare_inputs_for_generation = self.base_model.prepare_inputs_for_generation\nself.base_model_prepare_encoder_decoder_kwargs_for_generation = (\n self.base_model._prepare_encoder_decoder_kwargs_for_generation\n)\n```\n\n资料来源：[src/peft/peft_model.py:230-260]()\n\n### PeftModelForFeatureExtraction\n\n用于特征提取任务，支持标准forward接口并提供灵活的输入处理能力。\n\n资料来源：[src/peft/peft_model.py:80-110]()\n\n## BaseTuner 与适配器注入机制\n\n### inject_adapter 方法\n\n`inject_adapter` 是将适配器层注入到目标模型的核心方法，负责创建适配器层并替换原模型中的目标模块。\n\n```python\ndef inject_adapter(\n self,\n model: nn.Module,\n adapter_name: str,\n autocast_adapter_dtype: bool = True,\n low_cpu_mem_usage: bool = False,\n state_dict: Optional[dict[str, torch.Tensor]] = None,\n) -> None:\n```\n\n| 参数名 | 类型 | 说明 |\n|--------|------|------|\n| `model` | `nn.Module` | 需要注入适配器的模型 |\n| `adapter_name` | `str` | 适配器名称 |\n| `autocast_adapter_dtype` | `bool` | 是否自动转换适配器数据类型 |\n| `low_cpu_mem_usage` | `bool` | 是否在元设备上创建空适配器权重以加速加载 |\n| `state_dict` | `Optional[dict]` | 可选的预定义状态字典 |\n\n资料来源：[src/peft/tuners/tuners_utils.py:100-150]()\n\n### _check_target_module_compatibility 方法\n\n该方法防止将LoRA等适配器应用于不兼容的模块（如Mamba架构）：\n\n```python\ndef _check_target_module_compatiblity(\n self, peft_config: PeftConfig, model: nn.Module, target_name: str\n):\n _check_lora_target_modules_mamba(peft_config, model, target_name)\n```\n\n资料来源：[src/peft/tuners/tuners_utils.py:90-95]()\n\n## 各类型Tuner模型\n\n### Tuner模型通用架构\n\n每种Tuner模型（如SHiRA、GrALoRA、xLoRA、MiSS、OFT、Adamss）都遵循统一的架构模式：\n\n```mermaid\ngraph TD\n A[BaseTuner] --> B[各TunerModel类]\n B --> C{_create_and_replace}\n C -->|Linear层| D[update_layer]\n C -->|非Linear层| E[_create_new_module]\n D --> F[替换原模块]\n E --> F\n```\n\n### SHiRA 模型\n\nSHiRA（Structured HieraRchy Adapter）模型具有以下特征：\n\n| 属性 | 值 |\n|------|-----|\n| `prefix` | `\"shira_\"` |\n| `tuner_layer_cls` | `ShiraLayer` |\n| `mask_type` | 支持 `\"random\"` 类型 |\n\n创建新模块时，支持通过 `random_seed` 参数控制随机性：\n\n```python\nkwargs[\"random_seed\"] = shira_config.random_seed\n```\n\n资料来源：[src/peft/tuners/shira/model.py:30-80]()\n\n### Gralora 模型\n\nGradoRA模型专注于梯度相关的高效微调：\n\n| 属性 | 值 |\n|------|-----|\n| `prefix` | `\"gralora_\"` |\n| `tuner_layer_cls` | `GraloraLayer` |\n\n对于Linear层，直接调用 `update_layer` 方法进行参数更新：\n\n```python\nif isinstance(target, Linear):\n target.update_layer(\n adapter_name,\n current_key,\n r=r,\n config=gralora_config,\n )\n```\n\n资料来源：[src/peft/tuners/gralora/model.py:40-70]()\n\n### xLoRA 模型\n\nxLoRA是一种支持混合适配器配置的模型类型：\n\n```python\ndef __init__(\n self,\n model: nn.Module,\n config: Union[dict[str, XLoraConfig], XLoraConfig],\n adapter_name: str,\n torch_device: Optional[str] = None,\n ephemeral_gpu_offload: bool = False,\n autocast_adapter_dtype: bool = True,\n **kwargs,\n) -> None:\n```\n\n| 参数名 | 类型 | 说明 |\n|--------|------|------|\n| `config` | `XLoraConfig` 或 `dict` | 支持单个或多个适配器配置 |\n| `torch_device` | `str` | 加载适配器的目标设备 |\n| `ephemeral_gpu_offload` | `bool` | 是否启用临时GPU卸载 |\n\n资料来源：[src/peft/tuners/xlora/model.py:40-80]()\n\n### MiSS 模型\n\nMiSS（Multi-Adapter Integration for Stable Diffusion）专为扩散模型设计：\n\n| 属性 | 值 |\n|------|-----|\n| `prefix` | `\"miss_\"` |\n| `tuner_layer_cls` | `MissLayer` |\n| `target_module_mapping` | `TRANSFORMERS_MODELS_TO_MISS_TARGET_MODULES_MAPPING` |\n\n创建新模块时的处理逻辑区分普通层和MissLayer：\n\n```python\nif not isinstance(target, MissLayer):\n new_module = self._create_new_module(miss_config, adapter_name, target, **kwargs)\n # 新适配器默认不训练\n new_module.requires_grad_(False)\n self._replace_module(parent, target_name, new_module, target)\nelse:\n target.update_layer(adapter_name, config=miss_config, **kwargs)\n```\n\n资料来源：[src/peft/tuners/miss/model.py:40-90]()\n\n### OFT 模型\n\nOFT（Orthogonal Fine-Tuning）模型保持参数的正交性约束：\n\n| 属性 | 值 |\n|------|-----|\n| `prefix` | `\"oft_\"` |\n| `tuner_layer_cls` | `OFTLayer` |\n| `loaded_in_8bit` | 支持8位量化加载 |\n\n```python\nkwargs = {\n \"r\": oft_config.r,\n \"fan_in_fan_out\": oft_config.fan_in_fan_out,\n \"loaded_in_8bit\": getattr(self.model, \"is_loaded_in_8bit\", False)\n}\n```\n\n资料来源：[src/peft/tuners/oft/model.py:40-80]()\n\n### Adamss 模型\n\nAdamss模型采用多子空间注意力机制：\n\n| 属性 | 值 |\n|------|-----|\n| `prefix` | `\"adamss_\"` |\n| `tuner_layer_cls` | `(AdamssLayer,)` |\n| `_asa_total_subspaces` | ASA子空间跟踪字典 |\n\n初始化时在BaseTuner注入适配器之前创建ASA跟踪属性：\n\n```python\ndef __init__(\n self, model, config, adapter_name, low_cpu_mem_usage: bool = False, state_dict: Optional[dict] = None\n) -> None:\n self._asa_total_subspaces = {}\n super().__init__(model, config, adapter_name, low_cpu_mem_usage, state_dict)\n```\n\n资料来源：[src/peft/tuners/adamss/model.py:50-70]()\n\n## 工具函数模块\n\n### helpers.py 核心功能\n\n#### check_if_peft_model\n\n检测指定路径的模型是否为PEFT模型：\n\n```python\ndef check_if_peft_model(model_name_or_path: str) -> bool:\n is_peft_model = True\n try:\n PeftConfig.from_pretrained(model_name_or_path)\n except Exception:\n is_peft_model = False\n return is_peft_model\n```\n\n资料来源：[src/peft/helpers.py:40-60]()\n\n#### update_signature\n\n更新PeftModel的接口签名以包含父类方法的参数：\n\n```python\ndef update_signature(model: PeftModel, method: str = \"all\") -> None:\n if method == \"forward\":\n update_forward_signature(model)\n elif method == \"generate\":\n update_generate_signature(model)\n elif method == \"all\":\n update_forward_signature(model)\n update_generate_signature(model)\n```\n\n| method参数值 | 效果 |\n|-------------|------|\n| `\"forward\"` | 仅更新forward方法签名 |\n| `\"generate\"` | 仅更新generate方法签名 |\n| `\"all\"` | 同时更新两者 |\n\n资料来源：[src/peft/helpers.py:1-30]()\n\n#### rescale_adapter_scale\n\n上下文管理器，用于临时调整适配器缩放因子：\n\n```python\n@contextmanager\ndef rescale_adapter_scale(model, multiplier):\n # 临时修改缩放值\n yield\n # 恢复原始值\n```\n\n资料来源：[src/peft/helpers.py:60-90]()\n\n#### update_forward_signature\n\n当forward签名仅包含 `*args` 和 `**kwargs` 时，用基类的完整签名替换：\n\n```python\ncurrent_signature = inspect.signature(model.forward)\nif (\n len(current_signature.parameters) == 2\n and \"args\" in current_signature.parameters\n and \"kwargs\" in current_signature.parameters\n):\n forward = deepcopy(model.forward.__func__)\n update_wrapper(forward, type(model.get_base_model()).forward, ...)\n```\n\n资料来源：[src/peft/helpers.py:90-130]()\n\n#### update_generate_signature\n\n类似地更新generate方法签名，支持处理单参数（仅kwargs）情况：\n\n```python\nif (\n len(current_signature.parameters) == 2\n and \"args\" in current_signature.parameters\n and \"kwargs\" in current_signature.parameters\n) or (len(current_signature.parameters) == 1 and \"kwargs\" in current_signature.parameters):\n generate = deepcopy(model.generate.__func__)\n update_wrapper(generate, type(model.get_base_model()).generate, ...)\n```\n\n资料来源：[src/peft/helpers.py:130-170]()\n\n## MixedModel 混合适配器模型\n\nMixedModel支持同时使用多个不同类型的PEFT适配器。其 `from_pretrained` 方法架构如下：\n\n```mermaid\ngraph LR\n A[from_pretrained] --> B[load config]\n B --> C[PEFT_TYPE_TO_MIXED_MODEL_MAPPING]\n C --> D[创建MixedModel实例]\n```\n\n```python\n@classmethod\ndef from_pretrained(\n cls,\n model: nn.Module,\n model_id: str or os.PathLike,\n adapter_name: str = \"default\",\n is_trainable: bool = False,\n config: PeftConfig = None,\n low_cpu_mem_usage: bool = False,\n **kwargs,\n) -> PeftModel:\n```\n\n资料来源：[src/peft/mixed_model.py:100-150]()\n\n## 适配器生命周期管理\n\n```mermaid\ngraph TD\n A[from_pretrained] --> B[inject_adapter]\n B --> C[创建新模块或更新现有层]\n C --> D[active_adapters管理]\n D --> E{merge_and_unload?}\n E -->|是| F[合并权重并卸载]\n E -->|否| G[继续训练/推理]\n F --> H[返回基础模型]\n G --> I[unload: 返回纯基础模型]\n```\n\n### merge_and_unload 与 unload 区别\n\n| 方法 | 合并权重 | 卸载适配器 | 返回内容 |\n|------|----------|------------|----------|\n| `merge_and_unload()` | ✅ | ✅ | 合并后的模型 |\n| `unload()` | ❌ | ✅ | 原始基础模型 |\n\n```python\ndef merge_and_unload(self, progressbar: bool = False, safe_merge: bool = False, adapter_names: List = None):\n return self._unload_and_optionally_merge(\n progressbar=progressbar, safe_merge=safe_merge, adapter_names=adapter_names\n )\n\ndef unload(self) -> torch.nn.Module:\n return self._unload_and_optionally_merge(merge=False)\n```\n\n资料来源：[src/peft/tuners/tuners_utils.py:60-90]()\n\n## 总结\n\nPEFT库的核心架构采用分层设计模式：\n\n1. **PeftModel基类** 提供统一的适配器管理接口\n2. **任务专用模型类** 针对不同NLP任务进行接口适配\n3. **BaseTuner与TunersUtils** 实现适配器注入的核心逻辑\n4. **各类TunerModel** 实现不同的高效微调算法（LoRA、SHiRA、GrALoRA、xLoRA、MiSS、OFT、Adamss等）\n5. **helpers工具模块** 提供运行时签名更新、模型检测等辅助功能\n\n这种架构设计使得PEFT能够以统一的方式支持多种参数高效微调算法，同时保持良好的可扩展性以接入新的微调方法。\n\n---\n\n\n\n## 配置系统\n\n### 相关页面\n\n相关主题：[核心模块与架构](#core-modules), [LoRA及其变体实现](#lora-tuners)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/peft/config.py](https://github.com/huggingface/peft/blob/main/src/peft/config.py)\n- [src/peft/utils/peft_types.py](https://github.com/huggingface/peft/blob/main/src/peft/utils/peft_types.py)\n- [src/peft/utils/constants.py](https://github.com/huggingface/peft/blob/main/src/peft/utils/constants.py)\n- [src/peft/peft_model.py](https://github.com/huggingface/peft/blob/main/src/peft/peft_model.py)\n- [src/peft/tuners/tuners_utils.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/tuners_utils.py)\n- [src/peft/mixed_model.py](https://github.com/huggingface/peft/blob/main/src/peft/mixed_model.py)\n \n\n# 配置系统\n\nPEFT（Parameter-Efficient Fine-Tuning）库的配置系统是整个框架的核心基础设施，负责定义、管理和序列化各种参数高效微调方法的配置参数。该系统通过统一的配置类层次结构，为不同的微调技术（如 LoRA、Prefix Tuning、AdaLoRA 等）提供了一致的配置接口，同时保持了各方法特有的参数定制能力。\n\n## 系统架构概述\n\nPEFT 配置系统采用分层设计模式，核心层定义了所有配置类的基类和枚举类型，方法层则实现了各种特定微调技术的配置类。这种设计确保了配置的通用性与扩展性的平衡。\n\n```mermaid\ngraph TB\n subgraph 核心层\n PeftConfig[PeftConfig 基类]\n PeftType[PeftType 枚举]\n TaskType[TaskType 枚举]\n end\n \n subgraph 配置映射层\n PEFT_TYPE_TO_CONFIG_MAPPING[PEFT_TYPE_TO_CONFIG_MAPPING]\n PEFT_TYPE_TO_MIXED_MODEL_MAPPING[PEFT_TYPE_TO_MIXED_MODEL_MAPPING]\n end\n \n subgraph 方法层\n LoraConfig[LoRA 配置]\n PrefixTuningConfig[Prefix Tuning 配置]\n PromptTuningConfig[Prompt Tuning 配置]\n AdaLoraConfig[AdaLoRA 配置]\n IA3Config[IA³ 配置]\n LoHaConfig[LoHa 配置]\n LokrConfig[LoKr 配置]\n VeraConfig[VeRA 配置]\n HieraConfig[HiRA 配置]\n end\n \n subgraph 应用层\n PeftModel[PeftModel]\n MixedModel[MixedModel]\n end\n \n PeftConfig --> PEFT_TYPE_TO_CONFIG_MAPPING\n PeftConfig --> 配置映射层\n 配置映射层 --> 方法层\n 方法层 --> 应用层\n```\n\n## 核心配置类\n\n### PeftConfig 基类\n\n`PeftConfig` 是所有 PEFT 配置类的基类，封装了微调配置的基本属性和序列化逻辑。该类继承自 `transformers.PretrainedConfig`，因此具备标准的模型配置保存和加载功能。\n\n#### 核心属性\n\n| 属性名 | 类型 | 说明 | 默认值 |\n|--------|------|------|--------|\n| `peft_type` | `PeftType` | PEFT 方法类型 | 必需 |\n| `task_type` | `TaskType` | 任务类型 | 可选 |\n| `inference_mode` | `bool` | 是否为推理模式 | `False` |\n| `r` | `int` | 秩（用于 LoRA 等方法） | `8` |\n| `target_modules` | `Optional[Union[List[str], str]]` | 目标模块名称 | `None` |\n| `modules_to_save` | `Optional[List[str]]` | 需保存参数的额外模块 | `None` |\n| `fan_in_fan_out` | `bool` | 是否转置权重 | `False` |\n\n资料来源：[src/peft/config.py](https://github.com/huggingface/peft/blob/main/src/peft/config.py)\n\n#### 关键方法\n\n`PeftConfig` 提供了以下核心方法用于配置管理：\n\n- `save_pretrained(save_directory)` - 将配置保存到指定目录\n- `from_pretrained(pretrained_model_name_or_path, **kwargs)` - 从预训练路径加载配置\n- `to_dict()` - 将配置转换为字典格式\n\n### PeftType 枚举\n\n`PeftType` 枚举定义了 PEFT 库支持的所有微调方法类型：\n\n| 枚举值 | 说明 | 对应配置类 |\n|--------|------|-----------|\n| `LORA` | Low-Rank Adaptation | `LoraConfig` |\n| `PREFIX_TUNING` | Prefix Tuning | `PrefixTuningConfig` |\n| `PROMPT_TUNING` | Prompt Tuning | `PromptTuningConfig` |\n| `ADALORA` | Adaptive LoRA | `AdaLoraConfig` |\n| `ADAPTION_PROMPT` | Adaption Prompt | `AdaptionPromptConfig` |\n| `IA3` | (IA)³ | `IA3Config` |\n| `LOHA` | LoHA | `LoHaConfig` |\n| `LOKR` | LoKr | `LokrConfig` |\n| `VERA` | VeRA | `VeraConfig` |\n| `HIRA` | HiRA | `HiraConfig` |\n| `OFT` | OFT | `OftConfig` |\n| `POLY` | Poly | `PolyConfig` |\n| `LINEAR` | Linear | `LinearConfig` |\n| `MANUAL` | Manual | `ManualConfig` |\n\n资料来源：[src/peft/utils/peft_types.py](https://github.com/huggingface/peft/blob/main/src/peft/utils/peft_types.py)\n\n### TaskType 枚举\n\n`TaskType` 枚举定义了支持的模型任务类型，用于配置与具体任务的适配：\n\n| 枚举值 | 说明 | 适用模型类 |\n|--------|------|-----------|\n| `SEQ_CLS` | 序列分类 | `PeftModelForSequenceClassification` |\n| `SEQ_2_SEQ_LM` | 序列到序列语言模型 | `PeftModelForSeq2SeqLM` |\n| `CAUSAL_LM` | 因果语言模型 | `PeftModelForCausalLM` |\n| `TOKEN_CLS` | Token 分类 | `PeftModelForTokenClassification` |\n| `QUESTION_ANS` | 问答任务 | `PeftModelForQuestionAnswering` |\n| `FEATURE_EXTRACTION` | 特征提取 | `PeftModelForFeatureExtraction` |\n\n资料来源：[src/peft/peft_model.py](https://github.com/huggingface/peft/blob/main/src/peft/peft_model.py)\n\n## 配置映射机制\n\nPEFT 使用两个关键的映射字典来管理配置类型与实际配置类之间的对应关系。\n\n### PEFT_TYPE_TO_CONFIG_MAPPING\n\n此映射字典建立了 `PeftType` 枚举值与具体配置类之间的关联：\n\n```python\nPEFT_TYPE_TO_CONFIG_MAPPING: dict[PeftType, type[PeftConfig]] = {\n PeftType.LORA: LoraConfig,\n PeftType.PROMPT_TUNING: PromptTuningConfig,\n PeftType.PREFIX_TUNING: PrefixTuningConfig,\n # ... 其他映射\n}\n```\n\n### PEFT_TYPE_TO_MIXED_MODEL_MAPPING\n\n此映射用于混合模型场景，关联 `PeftType` 与混合模型类：\n\n```python\nPEFT_TYPE_TO_MIXED_MODEL_MAPPING: dict[PeftType, type[PeftMixedModel]] = {\n PeftType.LORA: PeftMixedModel,\n # ... 其他映射\n}\n```\n\n资料来源：[src/peft/mixed_model.py](https://github.com/huggingface/peft/blob/main/src/peft/mixed_model.py)\n\n## 配置加载流程\n\n配置加载遵循统一的流程，支持从 Hugging Face Hub 或本地目录加载配置。\n\n```mermaid\nsequenceDiagram\n participant 用户\n participant PeftConfig\n participant HF Hub\n participant 本地文件系统\n \n 用户->>PeftConfig: from_pretrained(model_id)\n PeftConfig->>PeftConfig: 确定配置类型\n alt 模型在 Hub 上\n PeftConfig->>HF Hub: 下载配置文件\n HF Hub-->>PeftConfig: 返回配置数据\n else 本地模型\n PeftConfig->>本地文件系统: 读取配置文件\n 本地文件系统-->>PeftConfig: 返回配置数据\n end\n PeftConfig->>PeftConfig: 解析并实例化配置对象\n PeftConfig-->>用户: 返回 PeftConfig 实例\n```\n\n### 加载参数说明\n\n| 参数名 | 类型 | 说明 | 默认值 |\n|--------|------|------|--------|\n| `pretrained_model_name_or_path` | `str` | 模型标识或路径 | 必需 |\n| `subfolder` | `str` | 子文件夹路径 | `\"\"` |\n| `revision` | `str` | Git 修订版本 | `\"main\"` |\n| `cache_dir` | `Optional[str]` | 缓存目录 | `None` |\n| `force_download` | `bool` | 强制重新下载 | `False` |\n| `resume_download` | `bool` | 恢复下载 | `False` |\n| `proxies` | `Optional[dict]` | 代理设置 | `None` |\n| `token` | `Optional[Union[str, bool]]` | HuggingFace Hub Token | `None` |\n\n## 方法特定配置\n\n### LoRA 配置\n\n`LoraConfig` 是最常用的配置类，继承自 `PeftConfig` 并添加了 LoRA 方法特有的参数：\n\n```python\nclass LoraConfig(PeftConfig):\n def __init__(\n self,\n r: int = 8,\n lora_alpha: int = 8,\n lora_dropout: float = 0.0,\n target_modules: Optional[Union[List[str], str]] = None,\n bias: str = \"none\",\n inference_mode: bool = False,\n # ... 其他参数\n ):\n```\n\n| 参数名 | 类型 | 说明 | 默认值 |\n|--------|------|------|--------|\n| `r` | `int` | LoRA 秩（低秩矩阵维度） | `8` |\n| `lora_alpha` | `int` | LoRA 缩放因子 | `8` |\n| `lora_dropout` | `float` | LoRA 层 Dropout 率 | `0.0` |\n| `bias` | `str` | 偏置训练策略 | `\"none\"` |\n| `task_type` | `TaskType` | 任务类型 | 可选 |\n| `modules_to_save` | `Optional[List[str]]` | 需训练的其他模块 | `None` |\n\n### Prefix Tuning 配置\n\n`PrefixTuningConfig` 用于 Prefix Tuning 方法：\n\n```python\nclass PrefixTuningConfig(PeftConfig):\n def __init__(\n self,\n num_virtual_tokens: int = 20,\n token_dim: int = None,\n num_transformer_submodules: int = 1,\n num_attention_heads: int = 1,\n num_layers: int = 1,\n prefix_projection: bool = False,\n # ... 其他参数\n ):\n```\n\n| 参数名 | 类型 | 说明 | 默认值 |\n|--------|------|------|--------|\n| `num_virtual_tokens` | `int` | 虚拟 token 数量 | `20` |\n| `token_dim` | `int` | token 维度 | 自动 |\n| `num_transformer_submodules` | `int` | Transformer 子模块数 | `1` |\n| `num_attention_heads` | `int` | 注意力头数 | 自动 |\n| `prefix_projection` | `bool` | 是否投影前缀 | `False` |\n\n## 配置验证机制\n\n### 目标模块兼容性检查\n\n`tuners_utils.py` 中的 `_check_target_module_compatiblity` 方法负责验证目标模块的兼容性：\n\n```python\ndef _check_target_module_compatiblity(self, peft_config: PeftConfig, model: nn.Module, target_name: str):\n \"\"\"\n Prevent applying LoRA to incompatible modules in specific architectures (e.g., Mamba).\n \"\"\"\n _check_lora_target_modules_mamba(peft_config, model, target_name)\n```\n\n该方法防止在特定架构（如 Mamba）上应用不兼容的 LoRA 配置。\n\n资料来源：[src/peft/tuners/tuners_utils.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/tuners_utils.py)\n\n### 模块名称验证\n\n配置系统对以下模块名称进行特殊处理：\n\n- **分类任务**：`\"classifier\"`, `\"score\"`\n- **问答任务**：`\"qa_outputs\"`\n- **Token 分类**：`\"classifier\"`, `\"score\"`\n\n资料来源：[src/peft/peft_model.py](https://github.com/huggingface/peft/blob/main/src/peft/peft_model.py)\n\n## 配置的动态更新\n\nPEFT 支持在运行时动态更新配置参数，通过 `inject_adapter` 方法实现：\n\n```python\ndef inject_adapter(\n self,\n model: nn.Module,\n adapter_name: str,\n autocast_adapter_dtype: bool = True,\n low_cpu_mem_usage: bool = False,\n state_dict: Optional[dict[str, torch.Tensor]] = None,\n) -> None:\n```\n\n此方法创建适配器层并替换目标模块，允许在不重新初始化模型的情况下添加新的适配器配置。\n\n## 热插拔配置\n\n`hotswap.py` 模块支持配置的动态热切换：\n\n```python\ndef hotswap_adapter(\n model: \"PeftModel\",\n model_name_or_path: str,\n adapter_name: str = \"default\",\n torch_device: Optional[str] = None,\n **kwargs,\n) -> None:\n```\n\n该功能允许在推理过程中替换适配器配置，无需重新加载整个模型。\n\n资料来源：[src/peft/utils/hotswap.py](https://github.com/huggingface/peft/blob/main/src/peft/utils/hotswap.py)\n\n## 配置序列化\n\n配置系统支持将配置保存为标准格式，便于分享和复用：\n\n### 保存流程\n\n1. 调用 `save_pretrained(save_directory)` 方法\n2. 创建目标目录（如不存在）\n3. 将配置转换为 JSON 格式\n4. 保存为 `config.json` 文件\n5. 返回保存的文件路径\n\n### 加载流程\n\n1. 调用 `from_pretrained(pretrained_model_name_or_path)`\n2. 自动检测 PEFT 配置类型\n3. 实例化对应的配置类\n4. 返回配置对象\n\n## 目标模块映射\n\n每种微调方法都定义了默认的目标模块映射，确保在未知模型架构时也能正常工作：\n\n| 方法 | 映射变量 | 典型目标模块 |\n|------|----------|--------------|\n| LoRA | `TRANSFORMERS_MODELS_TO_LORA_TARGET_MODULES_MAPPING` | `q_proj`, `v_proj`, `k_proj`, `o_proj` |\n| IA³ | `TRANSFORMERS_MODELS_TO_IA3_TARGET_MODULES_MAPPING` | 针对特定层的向量 |\n| Prefix Tuning | `TRANSFORMERS_MODELS_TO_PREFIX_TUNING_TARGET_MODULES_MAPPING` | 全模型层级 |\n\n## 适配器管理\n\n配置系统与适配器管理系统紧密集成，支持多适配器配置：\n\n### 适配器注册\n\n```python\nclass PeftModel:\n def __init__(self, model, peft_config, adapter_name: str = \"default\", **kwargs):\n # 默认适配器名为 \"default\"\n```\n\n### 适配器切换\n\n通过 `active_peft_config` 属性访问当前激活的适配器配置：\n\n```python\npeft_config = self.active_peft_config\nif not peft_config.is_prompt_learning:\n if peft_config.peft_type == PeftType.LORA:\n # LoRA 特定处理\n```\n\n## 总结\n\nPEFT 配置系统通过以下设计原则实现了灵活且可扩展的配置管理：\n\n1. **分层架构**：基类提供通用接口，派生类实现特定方法配置\n2. **类型安全**：通过枚举类型确保配置值的有效性\n3. **映射驱动**：使用字典映射实现配置类型与实现类的解耦\n4. **序列化支持**：与 Hugging Face 生态系统无缝集成\n5. **运行时动态性**：支持适配器的热插拔和动态更新\n\n这套配置系统使得用户能够以统一的方式使用不同的参数高效微调方法，同时为高级用户提供了充分的定制能力。\n\n---\n\n\n\n## LoRA及其变体实现\n\n### 相关页面\n\n相关主题：[其他PEFT方法](#other-tuners), [量化支持与加速优化](#quantization)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/peft/tuners/lora/__init__.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/lora/__init__.py)\n- [src/peft/tuners/lora/config.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/lora/config.py)\n- [src/peft/tuners/lora/layer.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/lora/layer.py)\n- [src/peft/tuners/lora/model.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/lora/model.py)\n- [src/peft/tuners/lora/dora.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/lora/dora.py)\n- [src/peft/tuners/adalora/__init__.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/adalora/__init__.py)\n- [src/peft/tuners/vera/__init__.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/vera/__init__.py)\n \n\n# LoRA及其变体实现\n\n## 概述\n\nLoRA（Low-Rank Adaptation）是一种高效的参数微调技术，通过在预训练模型的权重矩阵旁边添加低秩分解矩阵来实现参数高效微调。PEFT库实现了LoRA及其多种变体，包括DoRA、AdaLoRA和VeRA，每种变体在参数效率和适应性方面有不同的优化策略。\n\n## LoRA核心架构\n\n### 核心技术原理\n\nLoRA的核心思想是将预训练权重矩阵 $W_0 \\in \\mathbb{R}^{d \\times k}$ 的更新表示为低秩分解形式：\n\n$$W' = W_0 + \\Delta W = W_0 + BA$$\n\n其中 $B \\in \\mathbb{R}^{d \\times r}$，$A \\in \\mathbb{R}^{r \\times k}$，$r \\ll \\min(d, k)$。\n\n### 模块结构\n\n```\ngraph TD\n A[预训练模型 Linear层] --> B[LoRA包装]\n B --> C[LoraLayer]\n C --> D[Lora_A: 降维矩阵]\n C --> E[Lora_B: 升维矩阵]\n C --> F[scaling缩放因子]\n D --> G[前向传播: Wx + BAx]\n```\n\n## LoraConfig配置详解\n\nLoraConfig是LoRA微调的核心配置类，主要参数如下：\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| r | int | 8 | 低秩矩阵的秩 |\n| lora_alpha | int | 16 | 缩放因子，通常设为r的两倍 |\n| lora_dropout | float | 0.0 | LoRA层的dropout率 |\n| target_modules | Optional[List[str]] | None | 需要应用LoRA的模块名称 |\n| bias | str | \"none\" | bias处理方式: none/lora_only/all |\n| fan_in_fan_out | bool | False | 是否转置权重 |\n| init_weights | bool | True | 是否初始化LoRA权重 |\n\n## LoraLayer实现\n\nLoraLayer是LoRA的核心计算层，主要包含以下组件：\n\n```python\n# 资料来源：src/peft/tuners/lora/layer.py\nclass LoraLayer:\n prefix: str = \"lora_\"\n # 核心低秩矩阵\n lora_A: nn.Parameter # 降维矩阵\n lora_B: nn.Parameter # 升维矩阵\n scaling: float # 缩放因子\n```\n\n### 前向传播逻辑\n\n```\ngraph LR\n A[输入x] --> B[原始输出: Wx]\n A --> C[LoRA输出: BAx * scaling]\n B --> D[合并输出: Wx + BAx * scaling]\n```\n\n## LoRAModel类结构\n\nLoRAModel继承自PeftModel，负责将LoRA适配器应用到基础模型：\n\n```python\n# 资料来源：src/peft/tuners/lora/model.py\nclass LoRAModel(PeftModel):\n prefix: str = \"lora_\"\n tuner_layer_cls = LoraLayer\n target_module_mapping = TRANSFORMERS_MODELS_TO_LORA_TARGET_MODULES_MAPPING\n```\n\n### _create_and_replace方法\n\n该方法负责在基础模型中创建或替换LoRA层：\n\n```python\n# 资料来源：src/peft/tuners/lora/model.py:77-95\ndef _create_and_replace(\n self,\n lora_config,\n adapter_name,\n target,\n target_name,\n parent,\n current_key,\n *,\n parameter_name: Optional[str] = None,\n) -> None:\n if current_key is None:\n raise ValueError(\"Current Key shouldn't be `None`\")\n```\n\n## DoRA实现\n\nDoRA（Weight-Decomposed LoRA）将LoRA的更新分解为幅度和方向两个分量：\n\n$$W' = m \\cdot \\frac{W_0 + \\Delta W}{\\|W_0 + \\Delta W\\|} = m \\cdot \\hat{W}$$\n\n其中 $m$ 是可学习的幅度向量，$\\hat{W}$ 是归一化的权重矩阵。\n\n### DoRA层结构\n\n```\ngraph TD\n A[原始权重 W₀] --> B[LoRA更新 ΔW]\n B --> C[权重合并 W₀ + ΔW]\n C --> D[幅度向量 m]\n C --> E[方向归一化]\n D --> F[乘积: m × direction]\n E --> F\n```\n\n## AdaLoRA实现\n\nAdaLoRA（Adaptive LoRA）是一种自适应的LoRA变体，根据参数重要性动态分配秩：\n\n### 核心特性\n\n| 特性 | 描述 |\n|------|------|\n| 重要性评估 | 基于奇异值分解评估参数重要性 |\n| 动态秩分配 | 重要参数获得更高秩 |\n| 渐进式调整 | 训练过程中逐步调整秩分配 |\n\n## VeRA实现\n\nVeRA（Vector-based Random Matrix LoRA）使用随机投影向量替代可训练矩阵以减少参数量：\n\n### 参数效率对比\n\n| 方法 | 可训练参数 | 存储需求 |\n|------|-----------|----------|\n| LoRA | 2 × d × r | O(dr + kr) |\n| VeRA | d + k + 2r | O(d + k + r) |\n\n## 使用示例\n\n### 标准LoRA配置\n\n```python\n# 资料来源：src/peft/tuners/lora/model.py\nfrom peft import LoraConfig, get_peft_model\nfrom transformers import AutoModelForCausalLM\n\nconfig = LoraConfig(\n r=8,\n lora_alpha=32,\n target_modules=[\"q_proj\", \"v_proj\"],\n lora_dropout=0.1,\n bias=\"none\",\n task_type=\"CAUSAL_LM\"\n)\n\nmodel = AutoModelForCausalLM.from_pretrained(\"base-model\")\npeft_model = get_peft_model(model, config)\npeft_model.print_trainable_parameters()\n```\n\n### DoRA配置\n\n```python\nfrom peft import DoRAConfig, get_peft_model\n\nconfig = DoRAConfig(\n r=8,\n lora_alpha=16,\n target_modules=[\"q_proj\", \"v_proj\"],\n dora_dropout=0.1\n)\n```\n\n## 目标模块映射\n\nTRANSFORMERS_MODELS_TO_LORA_TARGET_MODULES_MAPPING定义了不同模型架构的默认目标模块：\n\n```python\n# 常见目标模块映射\n{\n \"bert\": [\"query\", \"value\"],\n \"gpt2\": [\"c_attn\", \"c_proj\"],\n \"llama\": [\"q_proj\", \"v_proj\"],\n \"t5\": [\"q\", \"v\"]\n}\n```\n\n## 多适配器支持\n\nPEFT支持同时加载多个LoRA适配器：\n\n```python\n# 加载多个适配器\nmodel.load_adapter(\"path/to/adapter_1\", \"adapter_1\")\nmodel.load_adapter(\"path/to/adapter_2\", \"adapter_2\")\n\n# 激活特定适配器\nmodel.set_adapter(\"adapter_1\")\n\n# 合并所有适配器到基础模型\nmodel.merge_and_unload()\n```\n\n## 状态切换与合并\n\n```\ngraph TD\n A[基础模型] --> B[添加LoRA层]\n B --> C{是否合并?}\n C -->|是| D[merge_and_unload]\n C -->|否| E[保持LoRA权重独立]\n D --> F[融合后模型]\n E --> G[可切换适配器]\n```\n\n## 导出与部署\n\nLoRA权重可以导出为独立文件：\n\n```python\n# 保存LoRA权重\nmodel.save_pretrained(\"output_path\")\n\n# 加载已保存的LoRA模型\nfrom peft import PeftModel\npeft_model = PeftModel.from_pretrained(base_model, \"output_path\")\n```\n\n## 与其他技术的兼容性\n\n### BitsAndBytes量化支持\n\n```python\n# 资料来源：src/peft/tuners/lora/model.py\nfrom peft import get_peft_model, prepare_model_for_kbit_training\nfrom transformers import BitsAndBytesConfig\n\nquantization_config = BitsAndBytesConfig(load_in_8bit=True)\nmodel = AutoModelForCausalLM.from_pretrained(\n \"model_name\",\n quantization_config=quantization_config\n)\nmodel = prepare_model_for_kbit_training(model)\npeft_model = get_peft_model(model, lora_config)\n```\n\n### 梯度检查点\n\nLoRA层支持与梯度检查点技术结合使用，适用于超大模型的微调场景。\n\n## 总结\n\nPEFT库中的LoRA及其变体实现提供了灵活的参数高效微调方案。标准LoRA通过低秩分解减少可训练参数，DoRA通过分解幅度和方向提升表达能力，AdaLoRA通过自适应秩分配优化参数效率，VeRA通过随机投影进一步降低存储开销。\n\n---\n\n\n\n## 其他PEFT方法\n\n### 相关页面\n\n相关主题：[LoRA及其变体实现](#lora-tuners), [高级调谐器与实验性方法](#advanced-tuners)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/peft/tuners/ia3/__init__.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/ia3/__init__.py)\n- [src/peft/tuners/prompt_tuning/__init__.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/prompt_tuning/__init__.py)\n- [src/peft/tuners/prefix_tuning/__init__.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/prefix_tuning/__init__.py)\n- [src/peft/tuners/p_tuning/__init__.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/p_tuning/__init__.py)\n- [src/peft/tuners/oft/__init__.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/oft/__init__.py)\n- [src/peft/tuners/multitask_prompt_tuning/__init__.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/multitask_prompt_tuning/__init__.py)\n \n\n# 其他PEFT方法\n\nPEFT（Parameter-Efficient Fine-Tuning）库不仅支持主流的 LoRA 方法，还实现了多种参数高效微调技术。本页面详细介绍 IA³、OFT、Prompt Tuning、Prefix Tuning、P-Tuning 和 Multitask Prompt Tuning 等方法的设计原理、配置参数和使用方式。\n\n---\n\n## 概述\n\nPEFT 库中的\"其他 PEFT 方法\"涵盖了多种轻量级微调范式，这些方法各有特点，适用于不同的场景和模型架构。这些方法的核心目标是**在保持模型性能的同时，大幅减少可训练参数的数量**。\n\n### 方法分类\n\n| 类别 | 方法 | 简介 |\n|------|------|------|\n| 适配器类 | IA³ | 通过学习可缩放向量来调整模型激活 |\n| 正交变换类 | OFT | 在正交约束下学习权重更新 |\n| 提示类 | Prompt Tuning | 在输入序列前添加可学习的软提示 |\n| 提示类 | Prefix Tuning | 在每一层注意力头前添加可学习前缀 |\n| 提示类 | P-Tuning | 使用可学习的嵌入配合提示编码器 |\n| 多任务类 | Multitask Prompt Tuning | 跨任务共享和特定任务提示的组合 |\n\n---\n\n## IA³ (Intra-block Agressive Adapter)\n\n### 方法原理\n\nIA³ 是一种极其参数高效的微调方法，其核心思想是通过**学习可缩放向量**来调整模型的激活值。与 LoRA 等方法不同，IA³ 不添加新的权重矩阵，而是通过**逐元素乘法**对关键位置的激活进行缩放。\n\n资料来源：[src/peft/tuners/ia3/model.py:1-50]()\n\n### 架构图\n\n```mermaid\ngraph TD\n A[原始输入] --> B[Linear层]\n B --> C{IA³ 激活缩放}\n C --> D[激活值 × lora_A]\n D --> E[后续层处理]\n E --> F[激活值 × lora_B]\n F --> G[输出]\n \n H[可训练向量] -->|缩放因子| C\n H -->|缩放因子| D\n H -->|缩放因子| F\n```\n\n### 核心参数配置\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `r` | int | 8 | 秩参数 |\n| `target_modules` | List[str] | None | 目标模块名称 |\n| `fan_in_fan_out` | bool | False | 是否转置权重 |\n| `bias` | str | \"none\" | 偏置处理方式 |\n\n### 使用示例\n\n```python\nfrom transformers import AutoModelForSeq2SeqLM\nfrom peft import IA3Config, get_peft_model\n\nconfig = IA3Config(\n peft_type=\"IA3\",\n task_type=\"SEQ_2_SEQ_LM\",\n target_modules=[\"q\", \"v\", \"k\", \"wi\"],\n feedforward_modules=[\"wi\"],\n)\nmodel = AutoModelForSeq2SeqLM.from_pretrained(\"t5-base\")\nia3_model = get_peft_model(model, config)\nia3_model.print_trainable_parameters()\n```\n\n资料来源：[src/peft/tuners/ia3/__init__.py]()\n\n---\n\n## OFT (Orthogonal Fine-Tuning)\n\n### 方法原理\n\nOFT 是一种基于**正交约束**的参数高效微调方法。该方法在 SD（Stable Diffusion）等扩散模型中应用广泛，通过学习一个正交矩阵来约束权重更新，从而避免微调过程中对预训练知识的破坏。\n\n资料来源：[src/peft/tuners/oft/model.py:1-60]()\n\n### 核心特性\n\n- **正交约束**：权重更新必须满足正交条件\n- **分组机制**：支持将权重分组处理\n- **模块丢弃**：可选的丢弃机制防止过拟合\n\n### 架构图\n\n```mermaid\ngraph TD\n A[预训练权重 W₀] --> B{OFT 层}\n B --> C[计算 ΔW = W - W₀]\n C --> D[正交约束处理]\n D --> E[分组旋转]\n E --> F[更新权重 W]\n \n G[可训练参数 θ] -->|生成旋转| E\n F --> H[推理/训练输出]\n```\n\n### 核心参数配置\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `r` | int | 4 | 秩参数 |\n| `target_modules` | List[str] | None | 目标模块 |\n| `module_dropout` | float | 0.0 | 模块丢弃率 |\n| `fan_in_fan_out` | bool | False | 是否转置 |\n| `init_weights` | bool | True | 是否初始化权重 |\n\n资料来源：[src/peft/tuners/oft/__init__.py]()\n\n---\n\n## Prompt Tuning\n\n### 方法原理\n\nPrompt Tuning 是一种纯提示式微调方法，其核心思想是**在输入序列前添加可学习的软提示（soft prompts）**。这些软提示是连续的嵌入向量，不对应任何真实的词表 token，通过反向传播进行优化。\n\n资料来源：[src/peft/tuners/prompt_tuning/__init__.py]()\n\n### 工作流程\n\n```mermaid\ngraph LR\n A[可学习提示
P] --> B[拼接
[P; x]]\n B --> C[Transformer Encoder]\n C --> D[预测输出 ŷ]\n```\n\n### 核心参数配置\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `num_virtual_tokens` | int | 100 | 虚拟 token 数量 |\n| `num_layers` | int | None | 提示层数 |\n| `num_attention_heads` | int | None | 注意力头数 |\n| `token_dim` | int | None | token 维度 |\n\n### 使用示例\n\n```python\nfrom transformers import AutoModelForSequenceClassification\nfrom peft import PromptTuningConfig, get_peft_model\n\nconfig = PromptTuningConfig(\n task_type=\"SEQ_CLS\",\n num_virtual_tokens=20,\n prompt_tuning_init=\"TEXT\",\n prompt_tuning_init_text=\"情感分类: \",\n)\nmodel = AutoModelForSequenceClassification.from_pretrained(\"bert-base-cased\")\npt_model = get_peft_model(model, config)\n```\n\n---\n\n## Prefix Tuning\n\n### 方法原理\n\nPrefix Tuning 与 Prompt Tuning 的主要区别在于**前缀被添加到每一层注意力头的键（K）和值（V）矩阵之前**，而不是仅在输入层。这种设计允许模型在更深的层次上学习任务相关的表示。\n\n资料来源：[src/peft/tuners/prefix_tuning/__init__.py]()\n\n### 架构对比\n\n```mermaid\ngraph TD\n subgraph Prompt Tuning\n P1[软提示] -->|拼接| I1[输入Embedding]\n I1 --> L1[Layer 1]\n L1 --> L2[Layer 2]\n L2 --> LN[Layer N]\n end\n \n subgraph Prefix Tuning\n PK1[前缀 K] -->|添加| A1[Attention]\n PV1[前缀 V] -->|添加| A1\n PK2[前缀 K] -->|添加| A2[Attention]\n PV2[前缀 V] -->|添加| A2\n I2[输入] --> A1\n A1 --> A2\n end\n```\n\n### 核心参数配置\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `num_virtual_tokens` | int | 30 | 虚拟 token 数量 |\n| `num_transformer_submodules` | int | 1 | 变换器子模块数量 |\n| `encoder_hidden_size` | int | None | 编码器隐藏层大小 |\n| `prefix_projection` | bool | False | 是否投影前缀 |\n\n---\n\n## P-Tuning\n\n### 方法原理\n\nP-Tuning 使用**可学习的提示编码器（Prompt Encoder）**来生成软提示。该方法结合了离散提示和连续嵌入的优点，通过一个小型 LSTM/MLP 网络将可学习的标记映射到模型 embedding 空间。\n\n资料来源：[src/peft/tuners/p_tuning/__init__.py]()\n\n### 架构图\n\n```mermaid\ngraph TD\n A[可学习标记
[P₁, P₂, ..., Pₙ]] --> B[提示编码器
LSTM/MLP]\n B --> C[软提示嵌入]\n C --> D[与输入拼接]\n D --> E[预训练模型]\n E --> F[输出]\n \n G[输入文本] -->|Embedding| D\n```\n\n### 核心参数配置\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `num_virtual_tokens` | int | 20 | 虚拟 token 数量 |\n| `encoder_hidden_size` | int | None | 编码器隐藏层大小 |\n| `encoder_num_layers` | int | 2 | 编码器层数 |\n| `encoder_dropout` | float | 0.0 | 编码器 dropout |\n\n---\n\n## Multitask Prompt Tuning (MPT)\n\n### 方法原理\n\nMultitask Prompt Tuning 是一种**跨任务共享提示**的方法。它通过学习一组共享的基座提示（base prompts）和任务特定的提示组合，实现知识的高效迁移和复用。\n\n资料来源：[src/peft/tuners/multitask_prompt_tuning/__init__.py]()\n\n### 设计理念\n\n```mermaid\ngraph TD\n subgraph 共享基座提示\n B[Base Prompt
跨任务共享]\n end\n \n subgraph 任务特定提示\n T1[Task Prompt ₁]\n T2[Task Prompt ₂]\n T3[Task Prompt ₙ]\n end\n \n subgraph 组合\n C1[Base + Task₁]\n C2[Base + Task₂]\n C3[Base + Taskₙ]\n end\n \n B --> C1\n B --> C2\n B --> C3\n T1 --> C1\n T2 --> C2\n T3 --> C3\n```\n\n### 核心参数配置\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `num_subtasks` | int | None | 子任务数量 |\n| `num_virtual_tokens` | int | 20 | 虚拟 token 数量 |\n| `prompt_tuning_init` | str | \"RANDOM\" | 提示初始化方式 |\n| `task_embedding_dim` | int | None | 任务嵌入维度 |\n\n---\n\n## 方法对比与选择指南\n\n### 参数量对比\n\n| 方法 | 典型可训练参数 | 适用场景 |\n|------|----------------|----------|\n| IA³ | ~0.1% | 序列到序列任务、文本生成 |\n| OFT | ~0.5-2% | 图像生成、扩散模型 |\n| Prompt Tuning | ~0.01-0.1% | 分类任务、简短任务描述 |\n| Prefix Tuning | ~0.1-0.5% | 生成任务、复杂推理 |\n| P-Tuning | ~0.1-0.3% | NER、关系抽取等结构化任务 |\n| MPT | ~0.1-0.5% | 多任务学习、跨域迁移 |\n\n### 选择建议\n\n```mermaid\ngraph TD\n A[任务类型] --> B{是否多任务?}\n B -->|是| C[考虑 MPT]\n B -->|否| D{数据量?}\n D -->|极少| E[Prompt Tuning]\n D -->|充足| F{任务类型?}\n F -->|扩散模型| G[OFT]\n F -->|序列到序列| H[IA³]\n F -->|生成任务| I[Prefix Tuning]\n F -->|结构化预测| J[P-Tuning]\n```\n\n---\n\n## 通用配置接口\n\n所有 PEFT 方法都遵循统一的配置模式，通过 `PeftConfig` 基类进行管理：\n\n```python\nfrom peft import PeftConfig, LoraConfig, IA3Config\n\n# 统一的配置结构\nconfig = {\n \"peft_type\": \"LORA\", # 或 IA3, PROMPT_TUNING, etc.\n \"task_type\": \"CAUSAL_LM\", # 或 SEQ_CLS, SEQ_2_SEQ_LM, etc.\n \"inference_mode\": False,\n \"r\": 8,\n \"target_modules\": [\"q_proj\", \"v_proj\"],\n}\n```\n\n### 通用参数说明\n\n| 参数名 | 类型 | 说明 |\n|--------|------|------|\n| `peft_type` | PeftType | PEFT 方法类型枚举 |\n| `task_type` | TaskType | 任务类型 |\n| `inference_mode` | bool | 是否为推理模式 |\n| `r` | int | 秩参数（适用于相关方法） |\n| `target_modules` | List[str] | 目标模块名称列表 |\n\n---\n\n## 与主模型集成\n\n### 基础模型类继承结构\n\n所有 PEFT 方法的模型类都继承自 `PeftModel`，提供统一的接口：\n\n资料来源：[src/peft/peft_model.py]()\n\n```python\nclass PeftModelForSequenceClassification(PeftModel):\n def __init__(\n self, \n model: torch.nn.Module, \n peft_config: PeftConfig, \n adapter_name: str = \"default\"\n ):\n super().__init__(model, peft_config, adapter_name)\n # 特定任务的初始化逻辑\n```\n\n### 适配器管理\n\n```python\n# 添加多个适配器\nmodel.add_adapter(adapter_name=\"lora_v1\", adapter_config=lora_config)\nmodel.add_adapter(adapter_name=\"lora_v2\", adapter_config=lora_config_2)\n\n# 切换活动适配器\nmodel.set_adapter(adapter_name=\"lora_v1\")\n\n# 合并适配器权重\nmodel.merge_and_unload()\n```\n\n---\n\n## 总结\n\nPEFT 库提供的\"其他 PEFT 方法\"涵盖了从轻量级提示调优到结构化适配器的多种技术。这些方法各有优势：\n\n- **IA³** 适合需要快速推理且对参数效率要求极高的场景\n- **OFT** 是扩散模型微调的首选方案\n- **Prompt Tuning** 适合超大规模模型的小样本学习\n- **Prefix Tuning** 在保持提示灵活性的同时提供更强的表达能力\n- **P-Tuning** 适合需要精细控制提示表示的任务\n- **Multitask Prompt Tuning** 是多任务学习的理想选择\n\n开发者应根据具体任务需求、模型架构和计算资源选择合适的微调方法。\n\n---\n\n\n\n## 高级调谐器与实验性方法\n\n### 相关页面\n\n相关主题：[其他PEFT方法](#other-tuners), [模型合并与融合工具](#merge-utils)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/peft/tuners/boft/__init__.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/boft/__init__.py)\n- [src/peft/tuners/fourierft/__init__.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/fourierft/__init__.py)\n- [src/peft/tuners/waveft/__init__.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/waveft/__init__.py)\n- [src/peft/tuners/loha/__init__.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/loha/__init__.py)\n- [src/peft/tuners/lokr/__init__.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/lokr/__init__.py)\n- [src/peft/tuners/hra/__init__.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/hra/__init__.py)\n- [src/peft/tuners/poly/__init__.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/poly/__init__.py)\n \n\n# 高级调谐器与实验性方法\n\n## 概述\n\nPEFT（Parameter-Efficient Fine-Tuning）库提供了多种高级调谐器（Advanced Tuners）和实验性方法，这些方法超越了传统的 LoRA 线性低秩分解范式，引入频域变换、Hadamard 积、Kronecker 积等更复杂的参数化策略。这些高级调谐器在保持参数效率的同时，提供了更丰富的表达能力，适用于对模型性能有更高要求的复杂微调任务。\n\n高级调谐器的核心设计目标包括：\n\n- **提高表达能力**：通过非线性结构或频域表示增强适配器的建模能力\n- **保持参数效率**：仍通过冻结原模型参数，仅训练少量附加参数来实现\n- **支持多样化架构**：覆盖卷积层、自注意力层、全连接层等多种网络结构\n\n## 高级调谐器架构总览\n\n```mermaid\ngraph TD\n A[PEFT 高级调谐器] --> B[频域变换类]\n A --> C[低秩分解类]\n A --> D[结构化参数类]\n \n B --> B1[BOFT]\n B --> B2[FourierFT]\n B --> B3[WaveFT]\n \n C --> C1[LoHA]\n C --> C2[LoKR]\n \n D --> D1[HRA]\n D --> D2[Poly]\n \n style A fill:#e1f5fe\n style B fill:#fff3e0\n style C fill:#e8f5e9\n style D fill:#f3e5f5\n```\n\n## 频域变换类调谐器\n\n频域变换类调谐器通过将参数矩阵变换到频域进行操作，利用频域中的特殊性质（如正交性、稀疏性）来实现高效且富有表达力的参数适配。\n\n### BOFT（Block-wise Orthogonal Fourier Transform）\n\nBOFT 是一种基于块状正交傅里叶变换的高级调谐器，它在频域中使用块状正交矩阵来实现参数适配。\n\n#### 核心原理\n\nBOFT 的核心思想是将权重更新表示为块状正交矩阵的线性组合：\n\n```\nΔW = Σᵢ αᵢ · Bᵢ · F\n```\n\n其中 Bᵢ 表示块状正交矩阵，F 表示傅里叶变换矩阵，αᵢ 是可训练的标量系数。\n\n#### 关键特性\n\n| 特性 | 描述 |\n|------|------|\n| 正交约束 | 块状正交矩阵确保更新方向的稳定性 |\n| 频域稀疏性 | 仅需少量频域分量即可达到良好效果 |\n| 计算效率 | 通过 FFT 实现快速矩阵运算 |\n| 表达能力 | 相比纯低秩方法具有更强表达能力 |\n\n资料来源：[src/peft/tuners/boft/__init__.py:1-50]()\n\n### FourierFT（傅里叶变换调谐器）\n\nFourierFT 是直接在傅里叶域进行参数化的调谐器，利用傅里叶变换的正交基函数来表示权重变化。\n\n#### 架构设计\n\n```mermaid\ngraph LR\n A[原始权重 W] --> B[傅里叶变换]\n B --> C[频域系数 C]\n C --> D[可训练缩放]\n D --> E[逆傅里叶变换]\n E --> F[更新权重 W']\n \n style D fill:#ffcdd2\n```\n\n#### 适用场景\n\n- 需要捕获周期性模式的NLP任务\n- 图像处理中的频域特征学习\n- 需要处理具有固有周期性的序列数据\n\n资料来源：[src/peft/tuners/fourierft/__init__.py:1-50]()\n\n### WaveFT（小波变换调谐器）\n\nWaveFT 利用小波变换的多尺度特性，在不同分辨率下进行参数适配，特别适合处理具有层次结构的数据。\n\n#### 多尺度分解\n\n| 尺度 | 特性 | 应用 |\n|------|------|------|\n| 低频分量 | 全局趋势 | 基础语义理解 |\n| 中频分量 | 局部特征 | 语法结构学习 |\n| 高频分量 | 细节变化 | 细粒度任务适配 |\n\n资料来源：[src/peft/tuners/waveft/__init__.py:1-50]()\n\n## 低秩分解类调谐器\n\n低秩分解类调谐器在传统 LoRA 的基础上引入更复杂的矩阵分解结构，以在保持参数效率的同时增强表达能力。\n\n### LoHA（Low-Rank Hadamard Product）\n\nLoHA 使用 Hadamard 积（元素级乘法）结合低秩分解来构建适配器，这种结构能够更有效地捕获参数间的非线性交互。\n\n#### 数学形式\n\n给定原始权重矩阵 W ∈ ℝᵈˣᵏ，LoHA 的更新形式为：\n\n```\nΔW = (A ⊙ B) · H\n```\n\n其中：\n- A ∈ ℝᵈˣʳ, B ∈ ℝᵈˣʳ 为低秩矩阵\n- H ∈ ℝʳˣᵏ 为 Hadamard 基础矩阵\n- ⊙ 表示 Hadamard 积（元素级乘法）\n\n#### 优势\n\n| 维度 | LoRA | LoHA |\n|------|------|------|\n| 参数数量 | 2dr | 2dr + rk |\n| 表达能力 | 线性组合 | 元素级交互 |\n| 计算复杂度 | O(dr + kr) | O(dr + kr) |\n| 适用场景 | 基础任务 | 复杂交互任务 |\n\n资料来源：[src/peft/tuners/loha/__init__.py:1-50]()\n\n### LoKR（Low-Rank Kronecker Product）\n\nLoKR 利用 Kronecker 积的结构化低秩分解，在保持参数效率的同时提供更强的表达能力。\n\n#### 数学形式\n\nLoKR 将权重更新表示为 Kronecker 积的形式：\n\n```\nΔW = Σᵢ αᵢ · (Aᵢ ⊗ Bᵢ)\n```\n\n其中 ⊗ 表示 Kronecker 积，Aᵢ 和 Bᵢ 分别为低秩矩阵。\n\n#### 参数效率分析\n\n| 分解方式 | 原始参数 | 分解后参数 | 压缩比 |\n|----------|----------|------------|--------|\n| 标准低秩 | d × k | r(d + k) | r(d+k)/dk |\n| Kronecker | d × k | r(d₁+k₁) | r(d₁+k₁)/dk |\n\n当 d = d₁d₂, k = k₁k₂ 时，Kronecker 分解可实现显著参数压缩。\n\n资料来源：[src/peft/tuners/lokr/__init__.py:1-50]()\n\n## 结构化参数类调谐器\n\n### HRA（High-Rank Adaptation）\n\nHRA 是一种高秩适配方法，设计用于在保持参数效率的同时允许更高秩的参数更新。\n\n#### 设计理念\n\n传统 LoRA 等方法强制使用低秩更新，这在某些复杂任务中可能限制表达能力。HRA 通过结构化的高秩分解来突破这一限制：\n\n```mermaid\ngraph TD\n A[高秩目标] --> B{分解策略选择}\n B --> C[块对角结构]\n B --> D[带状结构]\n B --> E[分层结构]\n \n C --> F[块内高秩
块间独立]\n D --> G[带内交互
带间解耦]\n E --> H[层级递进
渐进表达]\n \n style A fill:#ffcdd2\n```\n\n#### 与其他方法的对比\n\n| 方法 | 秩约束 | 参数效率 | 表达能力 |\n|------|--------|----------|----------|\n| LoRA | 固定低秩 | 极高 | 中等 |\n| DoRA | 固定低秩 | 极高 | 较高 |\n| HRA | 可调结构化 | 高 | 高 |\n| Full FT | 无约束 | 低 | 最高 |\n\n资料来源：[src/peft/tuners/hra/__init__.py:1-50]()\n\n### Poly（多项式调谐器）\n\nPoly 使用多项式参数化来实现权重更新，通过多项式基函数的线性组合来捕获更复杂的变换模式。\n\n#### 多项式基\n\n对于 d 阶多项式，权重更新可表示为：\n\n```\nΔW = Σₚ cₚ · Pₚ(W)\n```\n\n其中 Pₚ 是多项式基函数，cₚ 是可训练系数。\n\n#### 特性\n\n- **非线性建模**：通过多项式基引入非线性表达能力\n- **可调复杂度**：通过多项式阶数控制表达能力\n- **梯度平滑**：相比 ReLU 等激活函数具有更平滑的梯度流\n\n资料来源：[src/peft/tuners/poly/__init__.py:1-50]()\n\n## 统一配置接口\n\n### 配置参数对照表\n\n| 参数名 | 类型 | 说明 | 适用调谐器 |\n|--------|------|------|------------|\n| `r` | int | 低秩维度 | LoHA, LoKR, HRA |\n| `modules_to_save` | List[str] | 额外训练的模块 | 全部 |\n| `fan_in_fan_out` | bool | 权重初始化方式 | LoHA, LoKR |\n| `init_weights` | bool | 是否初始化权重 | 全部 |\n| `layers_to_transform` | List[int] | 指定变换层 | 全部 |\n\n### 使用示例\n\n```python\nfrom peft import get_peft_model, LoraConfig\n\n# LoHA 配置示例\nloha_config = LoraConfig(\n r=16,\n lora_alpha=32,\n target_modules=[\"q_proj\", \"v_proj\"],\n lora_dropout=0.05,\n bias=\"none\",\n task_type=\"CAUSAL_LM\"\n)\n\n# FourierFT 配置示例\nfourier_config = LoraConfig(\n r=8,\n lora_alpha=16,\n target_modules=[\"q_proj\", \"k_proj\", \"v_proj\", \"o_proj\"],\n task_type=\"CAUSAL_LM\"\n)\n```\n\n## 技术选型指南\n\n```mermaid\ngraph TD\n A[任务类型?] --> B{参数效率优先?}\n B -->|是| C{交互复杂度?}\n B -->|否| D[使用 HRA 或 Poly]\n \n C -->|简单线性| E[使用 LoRA]\n C -->|中等| F[使用 LoHA]\n C -->|复杂| G[使用 LoKR]\n \n A --> H{频域特征重要?}\n H -->|是| I{多尺度需求?}\n I -->|是| J[使用 WaveFT]\n I -->|否| K[使用 FourierFT]\n \n style E fill:#c8e6c9\n style F fill:#fff9c4\n style G fill:#ffccbc\n style J fill:#bbdefb\n style K fill:#e1bee7\n```\n\n### 场景推荐\n\n| 场景 | 推荐方法 | 理由 |\n|------|----------|------|\n| 通用文本微调 | LoRA | 成熟稳定，资源消耗低 |\n| 复杂语义任务 | LoHA | 元素级交互增强表达 |\n| 大模型高效微调 | LoKR | Kronecker 结构节省参数 |\n| 周期模式识别 | FourierFT | 频域表示天然捕获周期 |\n| 多粒度任务 | WaveFT | 小波多尺度分析 |\n| 高表达需求 | HRA | 结构化高秩保持效率 |\n\n## 底层实现架构\n\n### 调谐器类层次结构\n\n```mermaid\nclassDiagram\n class BaseTuner {\n <>\n +merge_weights()\n +unmerge_weights()\n +set_adapter()\n }\n \n class BaseLayer {\n +forward()\n +extra_capabilities()\n }\n \n class BOFT {\n +_create_boft_modules()\n +forward()\n }\n \n class FourierFT {\n +_create_fourier_modules()\n +forward()\n }\n \n class WaveFT {\n +_create_wavelet_modules()\n +forward()\n }\n \n class LoHA {\n +_create_hadamard_modules()\n +forward()\n }\n \n class LoKR {\n +_create_kronecker_modules()\n +forward()\n }\n \n class HRA {\n +_create_hra_modules()\n +forward()\n }\n \n class Poly {\n +_create_poly_modules()\n +forward()\n }\n \n BaseTuner <|-- BOFT\n BaseTuner <|-- FourierFT\n BaseTuner <|-- WaveFT\n BaseTuner <|-- LoHA\n BaseTuner <|-- LoKR\n BaseTuner <|-- HRA\n BaseTuner <|-- Poly\n \n BaseLayer <|-- BOFT\n BaseLayer <|-- FourierFT\n BaseLayer <|-- WaveFT\n BaseLayer <|-- LoHA\n BaseLayer <|-- LoKR\n BaseLayer <|-- HRA\n BaseLayer <|-- Poly\n```\n\n## 性能与效率对比\n\n### 参数量对比（以 d=1024, k=1024, r=16 为例）\n\n| 方法 | 可训练参数量 | 理论压缩比 |\n|------|-------------|-----------|\n| Full Fine-tune | 2,097,152 | 1× |\n| LoRA | 65,536 | 32× |\n| LoHA | 65,536 + α | ~32× |\n| LoKR | ~32,768 | ~64× |\n| BOFT | ~65,536 | ~32× |\n| FourierFT | ~32,768 | ~64× |\n\n### 计算开销\n\n| 方法 | 前向计算开销 | 反向梯度开销 |\n|------|-------------|-------------|\n| LoRA | O(dr + kr) | O(dr + kr) |\n| LoHA | O(dr + kr) | O(dr + kr) |\n| LoKR | O(d₁r + d₂r + k₁r + k₂r) | O(d₁r + d₂r + k₁r + k₂r) |\n| FourierFT | O(dk log d) | O(dk log d) |\n| WaveFT | O(dk log d) | O(dk log d) |\n\n## 最佳实践\n\n### 配置建议\n\n1. **秩的选择**：从 r=8 或 r=16 开始，根据任务复杂度逐步增加\n2. **目标模块**：优先选择注意力层的 q_proj 和 v_proj\n3. **学习率**：高级调谐器通常需要比 LoRA 稍低的学习率\n4. **初始化**：建议使用 PEFT 默认初始化策略\n\n### 常见问题排查\n\n| 问题 | 可能原因 | 解决方案 |\n|------|----------|----------|\n| 收敛慢 | 学习率过高 | 降低学习率 2-5 倍 |\n| 性能下降 | 秩过低 | 适当增加 r 值 |\n| 显存溢出 | batch size 过大 | 减小 batch size |\n| 效果不稳定 | 初始化不当 | 使用预定义初始化 |\n\n## 总结\n\nPEFT 库的高级调谐器为参数高效微调提供了丰富的选择，涵盖了频域变换、低秩分解、结构化参数等多种技术路线。这些方法在保持参数效率的同时，通过各自独特的参数化策略增强了模型的表达能力。\n\n开发者和研究人员可以根据具体任务需求、计算资源和性能要求，在这些高级调谐器中选择最合适的方案。随着研究的深入，这些实验性方法有望在未来得到进一步优化和广泛应用。\n\n---\n\n\n\n## 模型合并与融合工具\n\n### 相关页面\n\n相关主题：[量化支持与加速优化](#quantization), [示例与用例概览](#examples-overview)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/peft/utils/merge_utils.py](https://github.com/huggingface/peft/blob/main/src/peft/utils/merge_utils.py)\n- [src/peft/utils/save_and_load.py](https://github.com/huggingface/peft/blob/main/src/peft/utils/save_and_load.py)\n- [src/peft/mixed_model.py](https://github.com/huggingface/peft/blob/main/src/peft/mixed_model.py)\n- [src/peft/tuners/tuners_utils.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/tuners_utils.py)\n- [src/peft/peft_model.py](https://github.com/huggingface/peft/blob/main/src/peft/peft_model.py)\n- [src/peft/utils/hotswap.py](https://github.com/huggingface/peft/blob/main/src/peft/utils/hotswap.py)\n \n\n# 模型合并与融合工具\n\n## 概述\n\nPEFT（Parameter-Efficient Fine-Tuning）库提供了强大的模型合并与融合工具，使用户能够将适配器（Adapter）的权重与基础模型合并，生成一个独立的、合并后的模型。这些工具的核心功能包括：\n\n- **合并与卸载（Merge and Unload）**：将适配器权重合并回基础模型，生成标准Transformer模型\n- **卸载（Unload）**：移除所有PEFT模块，恢复基础模型\n- **混合适配器合并（Mixed Adapter Merging）**：支持在多适配器场景下选择性合并特定适配器\n\n合并后的模型不再依赖PEFT框架，可以像标准模型一样加载和使用，同时保留了适配器训练带来的能力增强。\n\n资料来源：[src/peft/tuners/tuners_utils.py:1-100]()\n\n## 核心架构\n\n### 合并机制流程\n\n```mermaid\ngraph TD\n A[PEFT模型] --> B{合并方式选择}\n B --> C[merge_and_unload
合并并卸载适配器]\n B --> D[unload
仅卸载适配器]\n C --> E[合并权重到基础层]\n D --> F[移除PEFT模块]\n E --> G[返回合并后的基础模型]\n F --> G\n G --> H[标准Transformer模型]\n```\n\n### 多适配器合并架构\n\n```mermaid\ngraph TD\n A[基础模型] --> B[Adapter 1
LoRA权重]\n A --> C[Adapter 2
LoRA权重]\n A --> D[Adapter N
LoRA权重]\n B --> E{选择性合并}\n C --> E\n D --> E\n E --> F[合并指定适配器]\n E --> G[合并全部适配器]\n F --> H[合并后的模型]\n G --> H\n```\n\n## 主要接口\n\n### PeftModel 基类方法\n\n所有PEFT模型继承自 `PeftModel` 基类，提供以下合并相关方法：\n\n| 方法名 | 参数 | 返回值 | 功能描述 |\n|--------|------|--------|----------|\n| `merge_and_unload` | `progressbar`, `safe_merge`, `adapter_names` | `torch.nn.Module` | 合并并卸载适配器，返回合并后的模型 |\n| `unload` | 无 | `torch.nn.Module` | 仅卸载适配器，返回基础模型 |\n| `_unload_and_optionally_merge` | `merge`, `progressbar`, `safe_merge`, `adapter_names` | `torch.nn.Module` | 内部实现，根据参数决定是否合并 |\n\n资料来源：[src/peft/tuners/tuners_utils.py:150-180]()\n\n### 方法详细说明\n\n#### merge_and_unload 方法\n\n```python\ndef merge_and_unload(\n self,\n progressbar: bool = False,\n safe_merge: bool = False,\n adapter_names: Optional[list[str]] = None,\n) -> torch.nn.Module:\n```\n\n**参数说明**：\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `progressbar` | `bool` | `False` | 是否显示合并进度条 |\n| `safe_merge` | `bool` | `False` | 是否使用安全合并模式（避免数值溢出） |\n| `adapter_names` | `Optional[list[str]]` | `None` | 指定要合并的适配器名称列表，None表示全部 |\n\n**使用示例**：\n\n```python\n>>> from peft import PeftModel\n>>> base_model = AutoModelForCausalLM.from_pretrained(\"base_model_path\")\n>>> peft_model = PeftModel.from_pretrained(base_model, \"adapter_path\")\n>>> merged_model = peft_model.merge_and_unload()\n```\n\n资料来源：[src/peft/tuners/tuners_utils.py:120-145]()\n\n#### unload 方法\n\n```python\ndef unload(self) -> torch.nn.Module:\n```\n\n该方法将所有PEFT模块从模型中移除，返回原始的基础模型。\n\n> **重要提示**：必须将返回的模型赋值给一个变量并使用它，这不是原地操作。\n\n资料来源：[src/peft/tuners/tuners_utils.py:155-165]()\n\n## 合并策略\n\n### 基础模型合并\n\n基础模型合并是最常见的场景，将单个适配器与基础模型合并：\n\n```mermaid\ngraph LR\n A[Base Model] -->|加载| B[PeftModel]\n B -->|添加适配器| C[LoRA Layers]\n C -->|merge_and_unload| D[合并后的模型]\n```\n\n### 多适配器选择性合并\n\n在多适配器场景下，可以选择性合并特定的适配器：\n\n```python\n# 合并指定适配器\nmerged_model = peft_model.merge_and_unload(\n adapter_names=[\"adapter_1\", \"adapter_2\"]\n)\n\n# 安全合并避免数值问题\nmerged_model = peft_model.merge_and_unload(\n safe_merge=True\n)\n```\n\n### 合并过程中的兼容性检查\n\nPEFT库实现了目标模块兼容性检查机制，防止在特定架构（如Mamba）上应用不兼容的LoRA模块：\n\n```python\ndef _check_target_module_compatiblity(\n self, \n peft_config: PeftConfig, \n model: nn.Module, \n target_name: str\n):\n \"\"\"防止在不兼容的模块上应用LoRA\"\"\"\n _check_lora_target_modules_mamba(peft_config, model, target_name)\n```\n\n资料来源：[src/peft/tuners/tuners_utils.py:170-175]()\n\n## 适配器热切换\n\n### hotswap_adapter 功能\n\nPEFT还提供了热切换适配器的功能，允许在不重新加载模型的情况下替换适配器：\n\n```python\nfrom peft.utils.hotswap import hotswap_adapter\n\n# 替换默认适配器\nhotswap_adapter(\n model, \n \"path-to-new-adapter\", \n adapter_name=\"default\",\n torch_device=\"cuda\"\n)\n```\n\n**参数说明**：\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `model` | `PeftModel` | 包含已加载适配器的PEFT模型 |\n| `model_name_or_path` | `str` | 新适配器的路径 |\n| `adapter_name` | `str` | 要替换的适配器名称 |\n| `torch_device` | `str` | 加载新适配器的设备 |\n\n资料来源：[src/peft/utils/hotswap.py:1-50]()\n\n### 热切换工作流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant M as PeftModel\n participant A1 as 原适配器\n participant A2 as 新适配器\n \n U->>M: 调用hotswap_adapter\n M->>M: 加载新适配器配置\n M->>M: 验证适配器兼容性\n M->>A1: 卸载原适配器权重\n M->>A2: 加载新适配器权重\n M->>U: 返回热切换后的模型\n```\n\n## Mixed PeftModel\n\n对于需要同时使用多个适配器的场景，PEFT提供了 `MixedPeftModel` 类，支持更灵活的多适配器管理。\n\n### 主要特性\n\n| 特性 | 说明 |\n|------|------|\n| 多适配器加载 | 同时加载多个适配器 |\n| 动态切换 | 在不同适配器间动态切换 |\n| 选择性合并 | 合并指定的适配器组合 |\n| 权重融合 | 支持不同合并策略的权重融合 |\n\n资料来源：[src/peft/mixed_model.py:1-100]()\n\n## 保存与加载\n\n### 模型保存\n\nPEFT提供了 `save_peft_model` 函数用于保存PEFT模型：\n\n```python\n>>> from peft import save_peft_model\n>>> peft_model.save_peft_model(save_path)\n```\n\n### 模型加载\n\n使用 `from_pretrained` 方法加载已保存的PEFT模型：\n\n```python\n>>> from peft import PeftModel\n>>> base_model = AutoModelForCausalLM.from_pretrained(\"base_model\")\n>>> peft_model = PeftModel.from_pretrained(base_model, \"peft_model_path\")\n```\n\n资料来源：[src/peft/utils/save_and_load.py:1-100]()\n\n## 使用场景\n\n### 场景一：训练后合并\n\n在完成适配器训练后，将适配器权重合并到基础模型：\n\n```python\nfrom peft import PeftModel, AutoModelForCausalLM\n\n# 1. 加载基础模型\nbase_model = AutoModelForCausalLM.from_pretrained(\"meta-llama/Llama-2-7b\")\n\n# 2. 加载训练好的PEFT适配器\npeft_model = PeftModel.from_pretrained(base_model, \"./lora_checkpoint\")\n\n# 3. 合并并卸载\nmerged_model = peft_model.merge_and_unload()\n\n# 4. 保存合并后的模型\nmerged_model.save_pretrained(\"./merged_model\")\n```\n\n### 场景二：多适配器选择性合并\n\n在多适配器训练后，选择性地合并部分适配器：\n\n```python\n# 假设有多个适配器\npeft_model.add_adapter(\"adapter_style_a\", config_a)\npeft_model.add_adapter(\"adapter_style_b\", config_b)\n\n# 只合并特定适配器\nmerged_model = peft_model.merge_and_unload(\n adapter_names=[\"adapter_style_a\"]\n)\n```\n\n### 场景三：推理时热切换\n\n在推理过程中动态切换不同适配器：\n\n```python\nfrom peft.utils.hotswap import hotswap_adapter\n\n# 使用适配器A推理\noutput_a = model(inputs)\n\n# 热切换到适配器B\nhotswap_adapter(model, \"path-to-adapter-b\", adapter_name=\"default\")\n\n# 使用适配器B推理\noutput_b = model(inputs)\n```\n\n## 注意事项\n\n### 内存需求\n\n合并操作需要额外的内存来存储中间结果，合并过程中内存使用量可能达到原模型大小的2-3倍。\n\n### 安全合并\n\n启用 `safe_merge=True` 可以避免合并过程中的数值溢出问题：\n\n```python\nmerged_model = peft_model.merge_and_unload(safe_merge=True)\n```\n\n### 不兼容模块\n\n某些特定架构（如Mamba）可能不支持标准的LoRA合并操作，系统会进行兼容性检查并抛出相应错误。\n\n## 相关文件索引\n\n| 文件路径 | 功能描述 |\n|----------|----------|\n| `src/peft/utils/merge_utils.py` | 核心合并工具函数 |\n| `src/peft/utils/save_and_load.py` | 模型保存与加载工具 |\n| `src/peft/mixed_model.py` | 混合适配器模型实现 |\n| `src/peft/tuners/tuners_utils.py` | tuner基类，包含merge_and_unload实现 |\n| `src/peft/peft_model.py` | PEFT模型主类定义 |\n| `src/peft/utils/hotswap.py` | 适配器热切换工具 |\n\n## 总结\n\nPEFT库的模型合并与融合工具提供了完整的工作流程，从适配器训练后的模型合并、多适配器选择性合并，到推理过程中的适配器热切换。这些工具使得用户可以灵活地管理和部署高效的参数微调模型，同时保持部署模型的简洁性和兼容性。\n\n---\n\n\n\n## 量化支持与加速优化\n\n### 相关页面\n\n相关主题：[模型合并与融合工具](#merge-utils), [核心模块与架构](#core-modules)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/peft/tuners/lora/bnb.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/lora/bnb.py)\n- [src/peft/tuners/lora/gptq.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/lora/gptq.py)\n- [src/peft/tuners/lora/awq.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/lora/awq.py)\n- [src/peft/tuners/lora/aqlm.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/lora/aqlm.py)\n- [src/peft/tuners/lora/hqq.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/lora/hqq.py)\n- [src/peft/optimizers/__init__.py](https://github.com/huggingface/peft/blob/main/src/peft/optimizers/__init__.py)\n \n\n# 量化支持与加速优化\n\n## 概述\n\nPEFT 库提供了全面的量化支持与加速优化功能，旨在降低大语言模型的显存占用和计算成本，同时保持模型性能。通过集成多种业界领先的量化方法，PEFT 使用户能够在量化模型上无缝应用 LoRA 等参数高效微调技术。量化支持覆盖了从 4-bit 量化到极致压缩的多种方案，包括 BitsAndBytes (bnb)、GPTQ、AWQ、AQLM 和 HQQ 等主流量化框架。\n\n## 架构总览\n\nPEFT 的量化系统采用模块化设计，每种量化方法都有独立的实现模块，与 LoRA 微调层深度集成。这种设计允许用户在量化模型上直接添加和训练适配器，而无需对原始量化架构进行大幅修改。\n\n```mermaid\ngraph TD\n A[用户配置] --> B[PEFT 量化模块]\n B --> C[bnb.py
BitsAndBytes 4-bit]\n B --> D[gptq.py
GPTQ 量化]\n B --> E[awq.py
AWQ 量化]\n B --> F[aqlm.py
AQLM 量化]\n B --> G[hqq.py
HQQ 量化]\n C --> H[LoRA 适配器层]\n D --> H\n E --> H\n F --> H\n G --> H\n H --> I[量化模型推理/训练]\n```\n\n## 量化方法详解\n\n### BitsAndBytes 量化 (bnb)\n\nBitsAndBytes 是由 Meta 开发的 4-bit 量化方案，采用 NormalFloat (NF4) 数据类型实现高效的权重量化。该方法在量化过程中使用双重量化技术，进一步减少显存占用。\n\n#### 核心参数配置\n\n| 参数 | 类型 | 说明 | 默认值 |\n|------|------|------|--------|\n| `load_in_4bit` | bool | 启用 4-bit 量化加载 | False |\n| `load_in_8bit` | bool | 启用 8-bit 量化加载 | False |\n| `bnb_4bit_quant_type` | str | 量化类型，可选 `nf4` 或 `fp4` | `nf4` |\n| `bnb_4bit_compute_dtype` | dtype | 计算数据类型 | float16 |\n| `bnb_4bit_use_double_quant` | bool | 启用双重量化 | False |\n\n#### 工作原理\n\nBitsAndBytes 在模型加载时自动替换原有的 Linear 层为自定义的 BNB Linear 层。该实现支持在量化模型上直接添加 LoRA 适配器，适配器参数保持原始精度以确保训练稳定性。\n\n资料来源：[src/peft/tuners/lora/bnb.py:1-200](https://github.com/huggingface/peft/blob/main/src/peft/tuners/lora/bnb.py)\n\n### GPTQ 量化\n\nGPTQ 是一种后训练量化 (PTQ) 方法，通过逐层优化实现 4-bit 权重量化。该方法在保持模型性能的同时实现显著的压缩率。\n\n#### 关键特性\n\n- 支持 4-bit 和 8-bit 量化精度\n- 与现有 PEFT 方法完全兼容\n- 支持量化感知训练\n\n#### 量化配置\n\n| 参数 | 说明 | 可选值 |\n|------|------|--------|\n| `bits` | 量化位数 | 2, 3, 4, 8 |\n| `tokenizer` | 分词器实例 | - |\n| `dataset` | 校准数据集 | 字符串或列表 |\n| `samples` | 校准样本数量 | 整数 |\n\n资料来源：[src/peft/tuners/lora/gptq.py:1-180](https://github.com/huggingface/peft/blob/main/src/peft/tuners/lora/gptq.py)\n\n### AWQ 量化\n\nAWQ (Activation-Aware Weight Quantization) 是一种硬件感知的权重量化方法，通过分析激活值分布来优化量化策略。该方法特别适合在特定硬件平台上部署。\n\n#### 核心优势\n\n- 针对硬件优化的高效推理\n- 保留重要权重为全精度\n- 与多种部署框架兼容\n\n资料来源：[src/peft/tuners/lora/awq.py:1-150](https://github.com/huggingface/peft/blob/main/src/peft/tuners/lora/awq.py)\n\n### AQLM 量化\n\nAQLM (Additive Quantization Language Models) 是一种基于加数量化的高级压缩方法，通过将权重矩阵分解为多个码本的组合实现极致压缩。\n\n#### 技术特点\n\n- 支持多码本量化架构\n- 高压缩率下的性能保持\n- 适合大规模模型的极致优化\n\n资料来源：[src/peft/tuners/lora/aqlm.py:1-160](https://github.com/huggingface/peft/blob/main/src/peft/tuners/lora/aqlm.py)\n\n### HQQ 量化\n\nHQQ (Hessian Quantization) 是一种基于 Hessian 矩阵的量化方法，通过考虑参数重要性进行自适应量化。该方法在量化过程中利用二阶信息来保护关键权重。\n\n#### 核心机制\n\n- 基于 Hessian 的敏感性分析\n- 自适应位宽分配\n- 训练后量化支持\n\n资料来源：[src/peft/tuners/lora/hqq.py:1-170](https://github.com/huggingface/peft/blob/main/src/peft/tuners/lora/hqq.py)\n\n## 优化器集成\n\nPEFT 的优化器模块提供了与量化系统深度集成的优化算法，专门针对量化环境下的训练进行了优化。\n\n```mermaid\ngraph LR\n A[量化模型] --> B[优化器选择]\n B --> C[标准优化器]\n B --> D[PEFT 优化器]\n C --> E[SGD/AdamW]\n D --> F[8bit AdamW]\n D --> G[32bit AdamW]\n F --> H[梯度更新]\n G --> H\n```\n\n### 8-bit AdamW 优化器\n\n针对量化环境优化的 8-bit AdamW 实现，通过分块量化技术保持训练稳定性。该优化器使用专利的分块方案处理梯度统计量，显著降低显存占用。\n\n### 优化器配置\n\n| 优化器类型 | 适用场景 | 显存节省 |\n|-----------|----------|----------|\n| 8-bit AdamW | 量化模型训练 | ~60% |\n| 32-bit AdamW | 精度敏感场景 | ~40% |\n| PyTorch SGD | 简单任务 | ~20% |\n\n资料来源：[src/peft/optimizers/__init__.py:1-100](https://github.com/huggingface/peft/blob/main/src/peft/optimizers/__init__.py)\n\n## 量化与 LoRA 的结合\n\n### 工作流程\n\n```mermaid\ngraph TD\n A[加载基础模型] --> B{选择量化方法}\n B --> C[BitsAndBytes]\n B --> D[GPTQ]\n B --> E[AWQ]\n B --> F[AQLM]\n B --> G[HQQ]\n C --> H[量化模型转换]\n D --> H\n E --> H\n F --> H\n G --> H\n H --> I[注入 LoRA 适配器]\n I --> J[PEFT 配置]\n J --> K[训练/推理]\n```\n\n### 兼容性矩阵\n\n| 量化方法 | LoRA | AdaLoRA | QLoRA | Prefix Tuning |\n|---------|------|---------|-------|---------------|\n| BitsAndBytes | ✓ | ✓ | ✓ | ✓ |\n| GPTQ | ✓ | ✓ | ✓ | ✓ |\n| AWQ | ✓ | ✓ | ✓ | ✓ |\n| AQLM | ✓ | ✓ | ✓ | ✓ |\n| HQQ | ✓ | ✓ | ✓ | ✓ |\n\n## 使用示例\n\n### BitsAndBytes 量化配置\n\n```python\nfrom peft import get_peft_model, LoraConfig, BitsAndBytesConfig\n\n# 配置量化参数\nbnb_config = BitsAndBytesConfig(\n load_in_4bit=True,\n bnb_4bit_compute_dtype=\"float16\",\n bnb_4bit_use_double_quant=True,\n bnb_4bit_quant_type=\"nf4\"\n)\n\n# 加载量化模型并应用 LoRA\nmodel = AutoModelForCausalLM.from_pretrained(\n \"model_name\",\n quantization_config=bnb_config\n)\n\nlora_config = LoraConfig(\n r=16,\n lora_alpha=32,\n target_modules=[\"q_proj\", \"v_proj\"],\n lora_dropout=0.05,\n task_type=\"CAUSAL_LM\"\n)\n\nmodel = get_peft_model(model, lora_config)\n```\n\n### QLoRA 训练流程\n\nQLoRA 结合了量化与 LoRA 的优势，实现极低显存占用的高效训练。该方案在 4-bit 量化的模型上训练 LoRA 适配器，同时保持优化器状态为全精度。\n\n## 性能与精度权衡\n\n### 量化精度对比\n\n| 量化方法 | 精度损失 | 压缩比 | 推理速度提升 |\n|---------|----------|--------|-------------|\n| FP16 (基线) | 0% | 1x | 1x |\n| INT8 | <1% | 2x | 1.3x |\n| NF4 (bnb) | <2% | 4x | 2x |\n| GPTQ-4bit | <3% | 4x | 2.5x |\n| AQLM | <4% | 8x | 3x |\n\n### 显存占用分析\n\n```\n模型规模: 7B 参数\n\nFP16 完整微调: ~28GB 显存\nQLoRA (4bit): ~6GB 显存\nLoRA (FP16): ~14GB 显存\n```\n\n## 技术实现要点\n\n### 量化感知训练\n\nPEFT 支持在量化模型上进行量化感知训练 (QAT)，通过以下机制实现：\n\n1. **直通的梯度流动**：LoRA 适配器层保持原始精度计算\n2. **动态量化更新**：权重更新采用舍入机制\n3. **兼容性检查**：自动验证量化配置与 PEFT 配置的兼容性\n\n### 混合精度策略\n\n量化配置中可指定不同的计算精度层级：\n\n```python\ncompute_dtype = torch.float16 # 计算使用 FP16\nquantization_config = {\n \"weight_bit_width\": 4, # 权重 4-bit\n \"calib_bit_width\": 8 # 校准使用 8-bit\n}\n```\n\n## 最佳实践\n\n### 量化方法选择指南\n\n| 应用场景 | 推荐量化方法 | 理由 |\n|---------|-------------|------|\n| 消费级 GPU 训练 | BitsAndBytes NF4 | 成熟稳定，生态完善 |\n| 服务器端部署 | GPTQ-4bit | 推理效率高 |\n| 移动端部署 | AWQ | 硬件适配性好 |\n| 极致压缩 | AQLM | 最高压缩率 |\n\n### 常见陷阱与规避\n\n1. **精度回退**：确保优化器状态使用足够精度\n2. **校准数据质量**：使用代表性数据避免分布偏移\n3. **目标模块选择**：优先量化 attention 和 FFN 层\n4. **梯度检查**：启用梯度监控以检测数值问题\n\n## 总结\n\nPEFT 的量化支持与加速优化模块为用户提供了完整的模型压缩解决方案。通过集成多种主流量化框架并保持与 LoRA 系列的深度兼容，PEFT 使得在资源受限环境下训练和部署大语言模型成为可能。开发者应根据具体应用场景、硬件条件和性能要求选择合适的量化策略，在模型效果和资源效率之间取得最佳平衡。\n\n---\n\n\n\n## 示例与用例概览\n\n### 相关页面\n\n相关主题：[PEFT概述与快速入门](#overview), [开发者指南与贡献](#developer-guides)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/peft/peft_model.py](https://github.com/huggingface/peft/blob/main/src/peft/peft_model.py)\n- [src/peft/tuners/lora/model.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/lora/model.py)\n- [src/peft/tuners/ia3/model.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/ia3/model.py)\n- [src/peft/tuners/prompt_tuning/model.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/prompt_tuning/model.py)\n- [src/peft/tuners/xlora/model.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/xlora/model.py)\n- [src/peft/helpers.py](https://github.com/huggingface/peft/blob/main/src/peft/helpers.py)\n- [src/peft/tuners/tuners_utils.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/tuners_utils.py)\n \n\n# 示例与用例概览\n\n## 概述\n\nPEFT（Parameter-Efficient Fine-Tuning）库提供了丰富的示例和用例，涵盖了从语言建模到图像分类的多种任务类型。这些示例展示了如何使用不同的适配器方法（如 LoRA、IA³、Prefix Tuning、Prompt Tuning 等）来高效地微调预训练模型。示例代码位于 `examples/` 目录下，涵盖了因果语言建模、条件生成、序列分类、图像分类、监督微调（SFT）以及 INT8 训练等多种场景。\n\nPEFT 的示例设计遵循统一的设计模式，通过 `get_peft_model()` 函数将 PEFT 配置应用到基础模型上，然后使用标准的 Transformers API 进行训练和推理。这种设计使得用户可以轻松地在不同的适配器方法之间切换，同时保持代码的一致性。\n\n## 核心任务类型\n\nPEFT 库针对不同的下游任务提供了专门的任务类型（Task Type），每种任务类型对应特定的模型类和应用场景。\n\n### 任务类型与模型类映射\n\n| 任务类型 | 枚举值 | 对应模型类 | 主要应用场景 |\n|---------|--------|-----------|-------------|\n| 因果语言建模 | `CAUSAL_LM` | `PeftModelForCausalLM` | GPT 系列模型的自回归生成 |\n| 条件生成 | `SEQ_2_SEQ_LM` | `PeftModelForSeq2SeqLM` | T5、BART 等编码器-解码器模型 |\n| 序列分类 | `SEQ_CLS` | `PeftModelForSequenceClassification` | 文本分类任务 |\n| Token 分类 | `TOKEN_CLS` | `PeftModelForTokenClassification` | 命名实体识别、词性标注 |\n| 问答任务 | `QUESTION_ANS` | `PeftModelForQuestionAnswering` | 阅读理解问答 |\n| 特征提取 | `FEATURE_EXTRACTION` | `PeftModelForFeatureExtraction` | 嵌入向量提取 |\n\n资料来源：[src/peft/peft_model.py:1-100]()\n\n### 因果语言建模（Causal Language Modeling）\n\n因果语言建模是 GPT 系列模型的核心任务，模型需要根据前面的 token 预测下一个 token。PEFT 提供了 `PeftModelForCausalLM` 类来处理这类任务。\n\n```python\nfrom transformers import AutoModelForCausalLM\nfrom peft import get_peft_model, LoraConfig, TaskType\n\nmodel = AutoModelForCausalLM.from_pretrained(\"gpt2\")\npeft_config = LoraConfig(\n task_type=TaskType.CAUSAL_LM,\n r=16,\n lora_alpha=32,\n lora_dropout=0.05,\n target_modules=[\"q_proj\", \"v_proj\"]\n)\npeft_model = get_peft_model(model, peft_config)\npeft_model.print_trainable_parameters()\n```\n\n在因果语言建模中，LoRA 适配器通常应用于注意力机制的查询（Query）和值（Value）投影层，以实现高效的参数更新。模型的 `generate()` 方法保持了与原始模型相同的签名，可以通过 `update_generate_signature()` 函数来更新以包含完整的参数说明。\n\n资料来源：[src/peft/tuners/lora/model.py:1-50]()\n资料来源：[src/peft/helpers.py:1-60]()\n\n### 序列到序列生成（Sequence-to-Sequence Generation）\n\n序列到序列任务适用于 T5、BART 等编码器-解码器架构的模型。`PeftModelForSeq2SeqLM` 类专门处理这类任务，支持条件生成、翻译、摘要等应用。\n\n```python\nfrom transformers import AutoModelForSeq2SeqLM\nfrom peft import PeftModelForSeq2SeqLM, get_peft_config\n\nconfig = {\n \"peft_type\": \"LORA\",\n \"task_type\": \"SEQ_2_SEQ_LM\",\n \"inference_mode\": False,\n \"r\": 8,\n \"lora_alpha\": 32,\n \"lora_dropout\": 0.1,\n \"target_modules\": [\"q\", \"v\"]\n}\n\npeft_config = get_peft_config(config)\nmodel = AutoModelForSeq2SeqLM.from_pretrained(\"t5-base\")\npeft_model = PeftModelForSeq2SeqLM(model, peft_config)\n```\n\n`PeftModelForSeq2SeqLM` 初始化时会保存基础模型的 `prepare_inputs_for_generation` 和 `_prepare_encoder_decoder_kwargs_for_generation` 方法引用，以确保生成过程中的兼容性。\n\n资料来源：[src/peft/peft_model.py:100-150]()\n\n### 序列分类（Sequence Classification）\n\n序列分类任务将整个序列映射到单个标签，常用于情感分析、主题分类等场景。`PeftModelForSequenceClassification` 专门处理此类任务。\n\n```python\nfrom transformers import AutoModelForSequenceClassification\nfrom peft import PeftModelForSequenceClassification, get_peft_config\n\nconfig = {\n \"peft_type\": \"PREFIX_TUNING\",\n \"task_type\": \"SEQ_CLS\",\n \"num_virtual_tokens\": 20,\n \"token_dim\": 768,\n \"num_transformer_submodules\": 1,\n \"num_attention_heads\": 12,\n \"num_layers\": 12\n}\n\npeft_config = get_peft_config(config)\nmodel = AutoModelForSequenceClassification.from_pretrained(\"bert-base-cased\")\npeft_model = PeftModelForSequenceClassification(model, peft_config)\n```\n\n在序列分类中，PEFT 默认识别 `classifier` 和 `score` 作为分类层名称，可以通过配置中的 `modules_to_save` 参数指定其他需要训练的分类层。\n\n资料来源：[src/peft/peft_model.py:50-100]()\n\n### Token 分类（Token Classification）\n\nToken 分类任务为输入序列中的每个 token 预测一个标签，适用于命名实体识别（NER）、词性标注等任务。\n\n```python\nfrom transformers import AutoModelForTokenClassification\nfrom peft import PeftModelForTokenClassification, get_peft_config\n\npeft_config = get_peft_config({\n \"peft_type\": \"LORA\",\n \"task_type\": \"TOKEN_CLS\",\n \"r\": 16,\n \"target_modules\": [\"query\", \"value\"]\n})\n\nmodel = AutoModelForTokenClassification.from_pretrained(\"bert-base-cased\")\npeft_model = PeftModelForTokenClassification(model, peft_config)\n```\n\n与序列分类类似，Token 分类也使用 `modules_to_save` 参数来控制哪些层需要被训练和保存。\n\n资料来源：[src/peft/peft_model.py:100-150]()\n\n### 问答任务（Question Answering）\n\n问答任务要求模型根据给定的上下文回答问题。`PeftModelForQuestionAnswering` 类专门处理抽取式问答场景。\n\n```python\nfrom transformers import AutoModelForQuestionAnswering\nfrom peft import PeftModelForQuestionAnswering, get_peft_config\n\npeft_config = get_peft_config({\n \"peft_type\": \"LORA\",\n \"task_type\": \"QUESTION_ANS\",\n \"r\": 16,\n \"target_modules\": [\"query\", \"value\"]\n})\n\nmodel = AutoModelForQuestionAnswering.from_pretrained(\"bert-base-cased\")\npeft_model = PeftModelForQuestionAnswering(model, peft_config)\n```\n\n默认情况下，问答任务的分类层名称为 `qa_outputs`，可以通过配置参数进行自定义。\n\n资料来源：[src/peft/peft_model.py:1-50]()\n\n### 特征提取（Feature Extraction）\n\n特征提取任务用于获取输入序列的嵌入表示，可用于下游任务的特征输入或相似度计算等场景。\n\n```python\nfrom transformers import AutoModel\nfrom peft import PeftModelForFeatureExtraction, get_peft_config\n\npeft_config = get_peft_config({\n \"peft_type\": \"LORA\",\n \"task_type\": \"FEATURE_EXTRACTION\",\n \"r\": 16\n})\n\nmodel = AutoModel.from_pretrained(\"bert-base-cased\")\npeft_model = PeftModelForFeatureExtraction(model, peft_config)\n```\n\n`PeftModelForFeatureExtraction` 的 `forward()` 方法支持丰富的参数，包括 `input_ids`、`attention_mask`、`inputs_embeds`、`output_attentions`、`output_hidden_states` 等，可根据具体需求灵活配置。\n\n资料来源：[src/peft/peft_model.py:50-100]()\n\n## 适配器方法与配置\n\nPEFT 支持多种参数高效微调方法，每种方法都有其独特的配置选项和应用场景。\n\n### LoRA（Low-Rank Adaptation）\n\nLoRA 是最广泛使用的 PEFT 方法之一，通过在预训练权重旁边添加低秩分解矩阵来实现高效微调。\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `r` | int | LoRA 矩阵的秩，值越大表示表达能力越强，但参数量也越大 |\n| `lora_alpha` | int | LoRA 的缩放因子，通常设置为 `r` 的两倍 |\n| `lora_dropout` | float | LoRA 层的 Dropout 概率 |\n| `target_modules` | List[str] | 需要应用 LoRA 的模块名称，如 `[\"q_proj\", \"v_proj\"]` |\n| `bias` | str | bias 的训练策略，可选 `\"none\"`、`\"all\"`、`\"lora_only\"` |\n| `fan_in_fan_out` | bool | 是否将权重转置 |\n\n资料来源：[src/peft/tuners/lora/model.py:1-80]()\n\n### IA³（Adapters by Inhibiting and Amplifying Inner Activations）\n\nIA³ 方法通过学习向量来缩放隐藏状态，实现对模型行为的精细调控。\n\n```python\nfrom peft import IA3Config, IA3Model\n\nconfig = IA3Config(\n task_type=TaskType.SEQ_2_SEQ_LM,\n target_modules=[\"q\", \"v\", \"k\", \"wo\", \"wi\"],\n feedforward_modules=[\"wi\"]\n)\n\nmodel = AutoModelForSeq2SeqLM.from_pretrained(\"t5-base\")\nia3_model = IA3Model(config, model)\n```\n\nIA³ 特别适合序列到序列任务，其 `target_modules` 和 `feedforward_modules` 参数用于指定缩放向量应用的位置。\n\n资料来源：[src/peft/tuners/ia3/model.py:1-60]()\n\n### Prefix Tuning（前缀微调）\n\nPrefix Tuning 通过在注意力层之前添加可学习的前缀 token 来引导模型生成。\n\n```python\nfrom peft import PrefixTuningConfig\n\nconfig = PrefixTuningConfig(\n task_type=TaskType.SEQ_CLS,\n num_virtual_tokens=20,\n token_dim=768,\n num_transformer_submodules=1,\n num_attention_heads=12,\n num_layers=12,\n prefix_projection=False\n)\n```\n\n关键参数包括 `num_virtual_tokens`（虚拟 token 数量）、`prefix_projection`（是否使用两层 MLP 投影）以及 `postprocess_past_key_value_function`（用于自定义 KV 缓存后处理的函数）。\n\n资料来源：[src/peft/peft_model.py:50-100]()\n\n### Prompt Tuning\n\nPrompt Tuning 是一种简洁的提示学习方法，仅通过学习嵌入层来实现任务适应。\n\n```python\nfrom peft import PromptTuningConfig, PromptTuningInit\n\nconfig = PromptTuningConfig(\n task_type=TaskType.SEQ_2_SEQ_LM,\n num_virtual_tokens=20,\n prompt_tuning_init=\"TEXT\",\n prompt_tuning_init_text=\"Predict if sentiment of this review is positive, negative or neutral\",\n tokenizer_name_or_path=\"t5-base\"\n)\n```\n\n`PromptTuningInit` 支持多种初始化方式：`RANDOM`、`TEXT`、`AVERAGE_EMBEDDINGS` 和 `SAMPLE_VOCAB`。当使用 `SAMPLE_VOCAB` 时，嵌入会根据词汇表进行随机采样初始化。\n\n资料来源：[src/peft/tuners/prompt_tuning/model.py:1-80]()\n\n### X-LoRA\n\nX-LoRA 是一种支持多适配器动态组合的方法，允许在推理时动态加载和组合多个 LoRA 适配器。\n\n```python\nfrom peft import XLoraConfig, get_xlora_config\n\nconfig = XLoraConfig(\n base_model_config=None,\n adapters={\n \"adapter_1\": \"./path/to/checkpoint1/\",\n \"adapter_2\": \"./path/to/checkpoint2/\"\n }\n)\n\nxlora_model = get_peft_model(model, config)\n```\n\nX-LoRA 支持量化模型（INT8/INT4），可通过 BitsAndBytesConfig 配置，支持 `flash_attention_2` 加速推理。\n\n资料来源：[src/peft/tuners/xlora/model.py:1-100]()\n\n## 工作流程与架构\n\n### 典型 PEFT 工作流程\n\n```mermaid\ngraph TD\n A[加载预训练模型] --> B[创建 PEFT 配置]\n B --> C[应用 PEFT 配置]\n C --> D{适配器类型}\n D -->|LoRA| E[替换目标层为 LoRA 层]\n D -->|IA³| F[添加缩放向量]\n D -->|Prefix| G[添加可学习前缀]\n D -->|Prompt| H[替换嵌入层]\n E --> I[训练 PEFT 模型]\n F --> I\n G --> I\n H --> I\n I --> J[保存适配器]\n J --> K[加载并合并]\n```\n\n### 适配器注入机制\n\nPEFT 的核心机制是通过 `inject_adapter()` 方法将适配器层注入到基础模型中。这个过程涉及目标模块的识别、替换和配置。\n\n```python\ndef inject_adapter(\n model: nn.Module,\n adapter_name: str,\n autocast_adapter_dtype: bool = True,\n low_cpu_mem_usage: bool = False,\n state_dict: Optional[dict[str, torch.Tensor]] = None,\n) -> None:\n```\n\n注入过程会遍历模型的子模块，根据配置中的 `target_modules` 映射找到需要替换的目标层，然后创建对应的适配器层进行替换。系统会检查目标模块的兼容性，防止在不支持的架构（如 Mamba）上应用不兼容的适配器。\n\n资料来源：[src/peft/tuners/tuners_utils.py:1-50]()\n\n### 模型合并与卸载\n\n训练完成后，PEFT 支持将适配器权重合并回基础模型，或完全卸载适配器恢复原始模型。\n\n```python\n# 合并并卸载\nmerged_model = peft_model.merge_and_unload()\n\n# 仅卸载（恢复基础模型）\nbase_model = peft_model.unload()\n```\n\n`merge_and_unload()` 方法使用 `safe_merge` 参数控制在合并前是否进行数值稳定性检查。`unload()` 方法则完全移除所有 PEFT 层，返回原始的基础模型。\n\n资料来源：[src/peft/tuners/tuners_utils.py:1-50]()\n\n## 高级功能\n\n### 签名更新工具\n\nPEFT 提供了 `update_forward_signature()` 和 `update_generate_signature()` 工具函数，用于更新封装后的模型方法签名，使 IDE 和帮助系统能够正确显示参数信息。\n\n```python\nfrom peft import update_forward_signature, update_generate_signature\n\npeft_model = get_peft_model(model, peft_config)\nupdate_forward_signature(peft_model) # 更新 forward 方法签名\nupdate_generate_signature(peft_model) # 更新 generate 方法签名\n```\n\n这些函数会检查当前签名的参数数量和名称，仅当签名只包含 `*args` 和 `**kwargs` 时才进行更新，确保不会意外覆盖有意义的方法签名。\n\n资料来源：[src/peft/helpers.py:1-100]()\n\n### 适配器缩放上下文管理器\n\n`rescale_adapter_scale()` 上下文管理器允许临时调整适配器的缩放因子，这在某些特殊的推理场景下非常有用。\n\n```python\nfrom peft import rescale_adapter_scale\n\nwith rescale_adapter_scale(peft_model, multiplier=2.0):\n outputs = peft_model(inputs)\n```\n\n该管理器会在进入上下文时修改缩放值，在退出时自动恢复原始值，确保不改变模型状态的持久性。\n\n资料来源：[src/peft/helpers.py:100-150]()\n\n### 多适配器管理\n\nPEFT 支持在同一模型上同时管理多个适配器，通过 `add_adapter()` 方法添加新适配器，通过 `set_adapter()` 方法切换当前活动的适配器。\n\n```python\n# 添加新适配器\npeft_model.add_adapter(new_adapter_name, new_peft_config)\n\n# 切换适配器\npeft_model.set_adapter(adapter_name)\n```\n\n添加适配器时，新层默认设置为 `requires_grad_(False)`（不可训练），需要显式调用才能激活训练。\n\n资料来源：[src/peft/tuners/tuners_utils.py:1-50]()\n\n### 量化训练支持\n\nPEFT 与 bitsandbytes 库深度集成，支持 INT8 和 INT4 量化训练。\n\n```python\nimport torch\nimport transformers\nfrom peft import get_peft_model, LoraConfig, prepare_model_for_kbit_training\n\nquantization_config = transformers.BitsAndBytesConfig(load_in_8bit=True)\nmodel = AutoModelForCausalLM.from_pretrained(\n \"mistralai/Mistral-7B-Instruct-v0.1\",\n quantization_config=quantization_config,\n device_map=\"auto\"\n)\nmodel = prepare_model_for_kbit_training(model)\npeft_model = get_peft_model(model, peft_config)\n```\n\n`prepare_model_for_kbit_training()` 函数负责准备量化模型以进行梯度计算，包括正确配置嵌入层和 lm_head 层的梯度设置。\n\n资料来源：[src/peft/tuners/lora/model.py:1-50]()\n\n## 配置参数速查表\n\n### LoRA 配置参数\n\n| 参数名 | 必需 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `r` | 是 | - | LoRA 矩阵秩 |\n| `lora_alpha` | 否 | `r` | 缩放因子 |\n| `lora_dropout` | 否 | `0.0` | Dropout 概率 |\n| `target_modules` | 否 | `None` | 目标模块列表 |\n| `bias` | 否 | `\"none\"` | bias 训练策略 |\n| `fan_in_fan_out` | 否 | `False` | 权重转置 |\n| `modules_to_save` | 否 | `None` | 额外保存的模块 |\n\n### Prefix Tuning 配置参数\n\n| 参数名 | 必需 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `num_virtual_tokens` | 是 | - | 虚拟 token 数量 |\n| `token_dim` | 是 | - | token 维度 |\n| `num_transformer_submodules` | 否 | `1` | transformer 子模块数 |\n| `num_attention_heads` | 是 | - | 注意力头数 |\n| `num_layers` | 是 | - | 层数 |\n| `prefix_projection` | 否 | `False` | 是否投影 |\n\n### Prompt Tuning 配置参数\n\n| 参数名 | 必需 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `num_virtual_tokens` | 是 | - | 虚拟 token 数量 |\n| `prompt_tuning_init` | 否 | `RANDOM` | 初始化方式 |\n| `prompt_tuning_init_text` | 条件 | - | 文本初始化内容 |\n| `tokenizer_name_or_path` | 条件 | - | 分词器路径 |\n\n## 最佳实践\n\n### 目标模块选择建议\n\n不同的模型架构适合不同的目标模块配置：\n\n- **Transformer 注意力层**：优先选择 `q_proj`、`v_proj`，其次考虑 `k_proj`、`o_proj`\n- **Feed-Forward 层**：对于 MoE 或大型 FFN 层，可考虑 `gate_proj`、`up_proj`、`down_proj`\n- **嵌入层**：对于特定任务，可添加 `embed_tokens` 或 `word_embeddings`\n\n### 秩（Rank）选择指南\n\n| 任务复杂度 | 推荐秩值 | 参数量级 |\n|-----------|---------|---------|\n| 简单分类 | 4-8 | ~100K |\n| 标准生成 | 8-16 | ~500K |\n| 复杂推理 | 16-64 | ~2M |\n| 大规模微调 | 64-128 | ~10M+ |\n\n### 训练技巧\n\n1. **学习率调整**：PEFT 模型通常需要比全量微调更高的学习率，建议 1e-3 到 5e-4\n2. **Epoch 数量**：由于参数较少，PEFT 通常需要更多 epoch 才能收敛\n3. **权重衰减**：建议对 LoRA 层使用较小的权重衰减（0.01 或 0.0）\n4. **Gradient Clipping**：标准设置 max_norm=1.0 适用于大多数场景\n\n## 相关资源\n\n- 因果语言建模示例：`examples/causal_language_modeling`\n- 条件生成示例：`examples/conditional_generation`\n- 序列分类示例：`examples/sequence_classification`\n- 图像分类示例：`examples/image_classification`\n- SFT 微调示例：`examples/sft`\n- INT8 训练示例：`examples/int8_training`\n- LoRA Dreambooth 示例：`examples/lora_dreambooth`\n\n---\n\n\n\n## 开发者指南与贡献\n\n### 相关页面\n\n相关主题：[PEFT概述与快速入门](#overview), [核心模块与架构](#core-modules)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [CONTRIBUTING.md](https://github.com/huggingface/peft/blob/main/CONTRIBUTING.md)\n- [src/peft/peft_model.py](https://github.com/huggingface/peft/blob/main/src/peft/peft_model.py)\n- [src/peft/helpers.py](https://github.com/huggingface/peft/blob/main/src/peft/helpers.py)\n- [src/peft/tuners/tuners_utils.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/tuners_utils.py)\n- [src/peft/tuners/lora/model.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/lora/model.py)\n- [src/peft/tuners/ia3/model.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/ia3/model.py)\n- [src/peft/tuners/oft/model.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/oft/model.py)\n- [src/peft/tuners/hra/model.py](https://github.com/huggingface/peft/blob/main/src/peft/tuners/hra/model.py)\n \n\n# 开发者指南与贡献\n\n## 概述\n\nPEFT（Parameter-Efficient Fine-Tuning）是一个专注于参数高效微调方法的开源库，集成了 Transformers、Diffusers 和 Accelerate 等主流深度学习框架。该项目旨在帮助开发者以最小的计算和存储成本，将大规模预训练模型高效适配到各类下游应用场景。资料来源：[README.md](https://github.com/huggingface/peft/blob/main/README.md)\n\n本页面面向希望深度参与 PEFT 项目开发的贡献者，涵盖自定义 Tuner 实现、模型集成、低级 API 使用、问题排查以及贡献流程等核心主题。\n\n## 架构设计概览\n\nPEFT 采用模块化的 Tuner 架构，每种微调方法（如 LoRA、IA³、OFT 等）都有独立的实现模块。资料来源：[src/peft/tuners/tuners_utils.py:1-50](https://github.com/huggingface/peft/blob/main/src/peft/tuners/tuners_utils.py)\n\n```mermaid\ngraph TD\n A[PeftModel 基类] --> B[TunerMixin]\n B --> C[各 Tuner 实现]\n C --> D[LoRA]\n C --> E[IA³]\n C --> F[OFT]\n C --> G[HRA]\n C --> H[其他 Tuner]\n \n I[BaseTunerLayer] --> J[各 Tuner Layer]\n J --> K[LoRALayer]\n J --> L[IA³Layer]\n J --> M[OFTLayer]\n \n N[PeftConfig] --> O[各配置类]\n O --> P[LoraConfig]\n O --> Q[IA³Config]\n O --> R[OFTConfig]\n```\n\n## 自定义 Tuner 开发\n\n### 核心组件结构\n\n每个 Tuner 实现需要包含以下核心组件：资料来源：[src/peft/tuners/lora/model.py:1-60](https://github.com/huggingface/peft/blob/main/src/peft/tuners/lora/model.py)\n\n| 组件 | 说明 | 必需性 |\n|------|------|--------|\n| Config 类 | 存储 Tuner 特定配置参数 | 必须 |\n| Layer 类 | 封装原始层并添加适配逻辑 | 必须 |\n| Model 类 | 实现模块替换和适配器注入 | 必须 |\n| target_module_mapping | 目标模块名称映射 | 推荐 |\n\n### Model 类实现规范\n\nTuner 的 Model 类必须继承自适当的基类，并实现以下关键方法：资料来源：[src/peft/tuners/oft/model.py:1-80](https://github.com/huggingface/peft/blob/main/src/peft/tuners/oft/model.py)\n\n```python\nclass MyTunerModel(BaseTunerModel):\n # 类级别属性\n prefix: str = \"my_tuner_\"\n tuner_layer_cls = MyTunerLayer\n target_module_mapping = TRANSFORMERS_MODELS_TO_MY_TUNER_TARGET_MODULES_MAPPING\n \n def _create_and_replace(\n self,\n my_tuner_config,\n adapter_name,\n target,\n target_name,\n parent,\n current_key,\n **optional_kwargs,\n ):\n # 核心替换逻辑\n if isinstance(target, Linear):\n # 创建或更新适配层\n```\n\n### Layer 类实现\n\nLayer 类负责在基础层之上添加适配参数：资料来源：[src/peft/tuners/ia3/model.py:1-100](https://github.com/huggingface/peft/blob/main/src/peft/tuners/ia3/model.py)\n\n| 方法 | 功能 |\n|------|------|\n| `__init__` | 初始化适配层参数 |\n| `update_layer` | 更新已存在适配层的配置 |\n| `merge` | 合并适配权重到基础层 |\n| `unmerge` | 从基础层分离适配权重 |\n\n### _create_and_replace 方法详解\n\n此方法是 Tuner 替换逻辑的核心，负责将原始模块替换为适配层：资料来源：[src/peft/tuners/hra/model.py:80-120](https://github.com/huggingface/peft/blob/main/src/peft/tuners/hra/model.py)\n\n```python\ndef _create_and_replace(\n self,\n hra_config,\n adapter_name,\n target,\n target_name,\n parent,\n current_key,\n **optional_kwargs,\n):\n if current_key is None:\n raise ValueError(\"Current Key shouldn't be `None`\")\n\n # 如果不是 HRALayer，创建新模块；否则更新现有层\n if not isinstance(target, HRALayer):\n new_module = self._create_new_module(hra_config, adapter_name, target, r=hra_config.r)\n if adapter_name not in self.active_adapters:\n new_module.requires_grad_(False)\n self._replace_module(parent, target_name, new_module, target)\n else:\n target.update_layer(\n adapter_name,\n r=hra_config.r,\n config=hra_config,\n )\n```\n\n## 低级 API 使用\n\n### inject_adapter 方法\n\n`inject_adapter` 方法允许开发者手动将适配器注入到模型中，而不依赖 `get_peft_model` 封装：资料来源：[src/peft/tuners/tuners_utils.py:1-50](https://github.com/huggingface/peft/blob/main/src/peft/tuners/tuners_utils.py)\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| model | nn.Module | 要注入适配器的模型 |\n| adapter_name | str | 适配器名称，默认 \"default\" |\n| autocast_adapter_dtype | bool | 是否自动转换适配器数据类型 |\n| low_cpu_mem_usage | bool | 是否在 meta 设备上创建空权重以加速加载 |\n| state_dict | dict | 可选的预加载权重字典 |\n\n### merge_and_unload 操作\n\n合并操作将适配器权重与基础模型融合：资料来源：[src/peft/tuners/tuners_utils.py:1-30](https://github.com/huggingface/peft/blob/main/src/peft/tuners/tuners_utils.py)\n\n```python\n# 合并并卸载适配器\nmerged_model = peft_model.merge_and_unload(progressbar=True, safe_merge=False)\n\n# 仅卸载而不合并\nbase_model = peft_model.unload()\n```\n\n### Helper 函数\n\n`helpers.py` 模块提供了多个实用函数用于签名更新和模型检查：资料来源：[src/peft/helpers.py:1-100](https://github.com/huggingface/peft/blob/main/src/peft/helpers.py)\n\n| 函数 | 功能 |\n|------|------|\n| `update_forward_signature` | 更新 PeftModel 的 forward 签名以包含父类参数 |\n| `update_generate_signature` | 更新 PeftModel 的 generate 签名 |\n| `check_if_peft_model` | 检查模型是否为 PEFT 模型 |\n| `rescale_adapter_scale` | 临时调整适配器缩放因子的上下文管理器 |\n\n## 适配器生命周期管理\n\n```mermaid\ngraph LR\n A[加载基础模型] --> B[创建 PeftConfig]\n B --> C[get_peft_model 或 inject_adapter]\n C --> D[创建适配层]\n D --> E[训练适配器]\n E --> F[merge_and_unload 或保存]\n F --> G[卸载适配器]\n```\n\n## 贡献流程\n\n### 提交 Pull Request 规范\n\n1. Fork 仓库并创建功能分支\n2. 确保代码通过所有现有测试\n3. 为新功能添加测试用例\n4. 更新相关文档\n5. 提交 PR 并描述变更内容\n\n### 代码风格要求\n\n- 遵循 PEP 8 代码规范\n- 为公共 API 添加完整的类型注解\n- 为复杂逻辑编写文档字符串\n- 确保提交信息清晰描述变更内容\n\n### 新 Tuner 贡献检查清单\n\n添加新的 Tuner 实现时，需确保完成以下内容：资料来源：[CONTRIBUTING.md](https://github.com/huggingface/peft/blob/main/CONTRIBUTING.md)\n\n| 检查项 | 说明 |\n|--------|------|\n| Config 类 | 实现完整的配置验证逻辑 |\n| Layer 类 | 实现权重初始化、更新和合并方法 |\n| Model 类 | 实现模块替换逻辑 |\n| 测试用例 | 覆盖核心功能和边界情况 |\n| 文档示例 | 提供完整的使用示例代码 |\n| 目标模块映射 | 定义支持的模型架构和层名称 |\n\n## 常见问题排查\n\n### 模块兼容性检查\n\n某些特定架构（如 Mamba）存在不兼容的模块，PEFT 提供了专门的检查机制：资料来源：[src/peft/tuners/tuners_utils.py:1-50](https://github.com/huggingface/peft/blob/main/src/peft/tuners/tuners_utils.py)\n\n```python\ndef _check_target_module_compatiblity(self, peft_config, model, target_name):\n \"\"\"防止将 LoRA 应用于不兼容的模块\"\"\"\n _check_lora_target_modules_mamba(peft_config, model, target_name)\n```\n\n### 适配器状态管理\n\n| 问题 | 解决方案 |\n|------|----------|\n| 适配器未激活 | 使用 `set_adapter` 方法切换活动适配器 |\n| 权重未更新 | 检查 `active_peft_config` 配置 |\n| 合并失败 | 确认基础模型支持合并操作 |\n\n### 内存优化建议\n\n| 策略 | 适用场景 |\n|------|----------|\n| `low_cpu_mem_usage=True` | 大模型加载阶段 |\n| 4-bit/8-bit 量化 | 显存受限环境 |\n| 梯度检查点 | 长序列训练 |\n\n## 集成最佳实践\n\n### 与 Transformers 集成\n\nPEFT 与 Transformers 库深度集成，支持直接使用 `AutoModelForX` 系列接口：资料来源：[src/peft/peft_model.py:1-100](https://github.com/huggingface/peft/blob/main/src/peft/peft_model.py)\n\n```python\nfrom transformers import AutoModelForSequenceClassification\nfrom peft import PeftModelForSequenceClassification, get_peft_config\n\nmodel = AutoModelForSequenceClassification.from_pretrained(\"bert-base-cased\")\npeft_model = PeftModelForSequenceClassification(model, peft_config)\npeft_model.print_trainable_parameters()\n```\n\n### 与 Diffusers 集成\n\n对于 Stable Diffusion 等扩散模型，PEFT 提供专门的适配接口：资料来源：[src/peft/tuners/oft/model.py:1-60](https://github.com/huggingface/peft/blob/main/src/peft/tuners/oft/model.py)\n\n```python\nfrom diffusers import StableDiffusionPipeline\nfrom peft import OFTModel\n\nmodel = StableDiffusionPipeline.from_pretrained(\"runwayml/stable-diffusion-v1-5\")\nmodel.text_encoder = OFTModel(model.text_encoder, config_te, \"default\")\nmodel.unet = OFTModel(model.unet, config_unet, \"default\")\n```\n\n## 扩展阅读\n\n- [PEFT 官方文档](https://huggingface.co/docs/peft)\n- [PEFT 模型集合](https://huggingface.co/PEFT)\n- [Transformers 集成指南](https://huggingface.co/docs/transformers/main/en/perf_train_gpu_one)\n- [Diffusers 适配器管理](https://huggingface.co/docs/diffusers/en/using-diffusers/loading)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：huggingface/peft\n\n摘要：发现 18 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：配置坑 - 来源证据：[BUG] peft 0.19 target_modules (str) use `set`。\n\n## 1. 配置坑 · 来源证据：[BUG] peft 0.19 target_modules (str) use `set`\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[BUG] peft 0.19 target_modules (str) use `set`\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_bd098228d56f4251949a351ac90335fc | https://github.com/huggingface/peft/issues/3229 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 安全/权限坑 · 来源证据：Comparison of Different Fine-Tuning Techniques for Conversational AI\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Comparison of Different Fine-Tuning Techniques for Conversational AI\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_408252d26b4a4d87b9ca9362c3b4b37b | https://github.com/huggingface/peft/issues/2310 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 安装坑 · 来源证据：Feature Request: Improve offline support for custom architectures in get_peft_model_state_dict\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Feature Request: Improve offline support for custom architectures in get_peft_model_state_dict\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_32e0990aa35b430bac525df543e75cac | https://github.com/huggingface/peft/issues/3211 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. 配置坑 · 来源证据：0.17.0: SHiRA, MiSS, LoRA for MoE, and more\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：0.17.0: SHiRA, MiSS, LoRA for MoE, and more\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a7ec4779d09a4fcebe0901d73f869bf0 | https://github.com/huggingface/peft/releases/tag/v0.17.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 5. 配置坑 · 来源证据：Applying Dora to o_proj of Meta-Llama-3.1-8B results in NaN\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Applying Dora to o_proj of Meta-Llama-3.1-8B results in NaN\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ce144c340d9f40929a6551e9dbca770d | https://github.com/huggingface/peft/issues/2049 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 6. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:570384908 | https://github.com/huggingface/peft | README/documentation is current enough for a first validation pass.\n\n## 7. 运行坑 · 来源证据：0.17.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：0.17.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_cd675dc497c44319af556a2e7059dd95 | https://github.com/huggingface/peft/releases/tag/v0.17.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 8. 运行坑 · 来源证据：v0.15.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.15.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_66bfe8be731a44de971b991569f61e57 | https://github.com/huggingface/peft/releases/tag/v0.15.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 9. 运行坑 · 来源证据：v0.15.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.15.2\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3d5933ee300d4f68bfab2f0440fae679 | https://github.com/huggingface/peft/releases/tag/v0.15.2 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 10. 维护坑 · 来源证据：0.16.0: LoRA-FA, RandLoRA, C³A, and much more\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：0.16.0: LoRA-FA, RandLoRA, C³A, and much more\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5ef66863f7c64b3e9e3ba6a72eaab639 | https://github.com/huggingface/peft/releases/tag/v0.16.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 11. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:570384908 | https://github.com/huggingface/peft | last_activity_observed missing\n\n## 12. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:570384908 | https://github.com/huggingface/peft | no_demo; severity=medium\n\n## 13. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:570384908 | https://github.com/huggingface/peft | no_demo; severity=medium\n\n## 14. 安全/权限坑 · 来源证据：0.18.0: RoAd, ALoRA, Arrow, WaveFT, DeLoRA, OSF, and more\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：0.18.0: RoAd, ALoRA, Arrow, WaveFT, DeLoRA, OSF, and more\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b28315fbb2d44b748ca46f87fafd3d33 | https://github.com/huggingface/peft/releases/tag/v0.18.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 15. 安全/权限坑 · 来源证据：v0.15.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.15.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1a3ce413d14349658dc005c25754bb1f | https://github.com/huggingface/peft/releases/tag/v0.15.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 16. 安全/权限坑 · 来源证据：v0.19.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.19.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_abcf15a2812744f0a37ad5c5d75643cf | https://github.com/huggingface/peft/releases/tag/v0.19.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 17. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:570384908 | https://github.com/huggingface/peft | issue_or_pr_quality=unknown\n\n## 18. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:570384908 | https://github.com/huggingface/peft | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：huggingface/peft\n\n摘要：发现 18 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：配置坑 - 来源证据：[BUG] peft 0.19 target_modules (str) use `set`。\n\n## 1. 配置坑 · 来源证据：[BUG] peft 0.19 target_modules (str) use `set`\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[BUG] peft 0.19 target_modules (str) use `set`\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_bd098228d56f4251949a351ac90335fc | https://github.com/huggingface/peft/issues/3229 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 安全/权限坑 · 来源证据：Comparison of Different Fine-Tuning Techniques for Conversational AI\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Comparison of Different Fine-Tuning Techniques for Conversational AI\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_408252d26b4a4d87b9ca9362c3b4b37b | https://github.com/huggingface/peft/issues/2310 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 安装坑 · 来源证据：Feature Request: Improve offline support for custom architectures in get_peft_model_state_dict\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Feature Request: Improve offline support for custom architectures in get_peft_model_state_dict\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_32e0990aa35b430bac525df543e75cac | https://github.com/huggingface/peft/issues/3211 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. 配置坑 · 来源证据：0.17.0: SHiRA, MiSS, LoRA for MoE, and more\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：0.17.0: SHiRA, MiSS, LoRA for MoE, and more\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a7ec4779d09a4fcebe0901d73f869bf0 | https://github.com/huggingface/peft/releases/tag/v0.17.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 5. 配置坑 · 来源证据：Applying Dora to o_proj of Meta-Llama-3.1-8B results in NaN\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Applying Dora to o_proj of Meta-Llama-3.1-8B results in NaN\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ce144c340d9f40929a6551e9dbca770d | https://github.com/huggingface/peft/issues/2049 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 6. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:570384908 | https://github.com/huggingface/peft | README/documentation is current enough for a first validation pass.\n\n## 7. 运行坑 · 来源证据：0.17.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：0.17.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_cd675dc497c44319af556a2e7059dd95 | https://github.com/huggingface/peft/releases/tag/v0.17.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 8. 运行坑 · 来源证据：v0.15.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.15.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_66bfe8be731a44de971b991569f61e57 | https://github.com/huggingface/peft/releases/tag/v0.15.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 9. 运行坑 · 来源证据：v0.15.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.15.2\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3d5933ee300d4f68bfab2f0440fae679 | https://github.com/huggingface/peft/releases/tag/v0.15.2 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 10. 维护坑 · 来源证据：0.16.0: LoRA-FA, RandLoRA, C³A, and much more\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：0.16.0: LoRA-FA, RandLoRA, C³A, and much more\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5ef66863f7c64b3e9e3ba6a72eaab639 | https://github.com/huggingface/peft/releases/tag/v0.16.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 11. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:570384908 | https://github.com/huggingface/peft | last_activity_observed missing\n\n## 12. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:570384908 | https://github.com/huggingface/peft | no_demo; severity=medium\n\n## 13. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:570384908 | https://github.com/huggingface/peft | no_demo; severity=medium\n\n## 14. 安全/权限坑 · 来源证据：0.18.0: RoAd, ALoRA, Arrow, WaveFT, DeLoRA, OSF, and more\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：0.18.0: RoAd, ALoRA, Arrow, WaveFT, DeLoRA, OSF, and more\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b28315fbb2d44b748ca46f87fafd3d33 | https://github.com/huggingface/peft/releases/tag/v0.18.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 15. 安全/权限坑 · 来源证据：v0.15.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.15.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1a3ce413d14349658dc005c25754bb1f | https://github.com/huggingface/peft/releases/tag/v0.15.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 16. 安全/权限坑 · 来源证据：v0.19.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.19.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_abcf15a2812744f0a37ad5c5d75643cf | https://github.com/huggingface/peft/releases/tag/v0.19.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 17. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:570384908 | https://github.com/huggingface/peft | issue_or_pr_quality=unknown\n\n## 18. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:570384908 | https://github.com/huggingface/peft | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# peft - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 peft 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: 🤗 PEFT: State-of-the-art Parameter-Efficient Fine-Tuning. 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. overview：PEFT概述与快速入门。围绕“PEFT概述与快速入门”模拟一次用户任务，不展示安装或运行结果。\n2. core-modules：核心模块与架构。围绕“核心模块与架构”模拟一次用户任务，不展示安装或运行结果。\n3. config-system：配置系统。围绕“配置系统”模拟一次用户任务，不展示安装或运行结果。\n4. lora-tuners：LoRA及其变体实现。围绕“LoRA及其变体实现”模拟一次用户任务，不展示安装或运行结果。\n5. examples-overview：示例与用例概览。围绕“示例与用例概览”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. overview\n输入：用户提供的“PEFT概述与快速入门”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. core-modules\n输入：用户提供的“核心模块与架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. config-system\n输入：用户提供的“配置系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. lora-tuners\n输入：用户提供的“LoRA及其变体实现”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. examples-overview\n输入：用户提供的“示例与用例概览”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / overview：Step 1 必须围绕“PEFT概述与快速入门”形成一个小中间产物，并等待用户确认。\n- Step 2 / core-modules：Step 2 必须围绕“核心模块与架构”形成一个小中间产物，并等待用户确认。\n- Step 3 / config-system：Step 3 必须围绕“配置系统”形成一个小中间产物，并等待用户确认。\n- Step 4 / lora-tuners：Step 4 必须围绕“LoRA及其变体实现”形成一个小中间产物，并等待用户确认。\n- Step 5 / examples-overview：Step 5 必须围绕“示例与用例概览”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/huggingface/peft\n- https://github.com/huggingface/peft#readme\n- README.md\n- docs/source/quicktour.md\n- docs/source/install.md\n- src/peft/__init__.py\n- src/peft/peft_model.py\n- src/peft/mapping.py\n- src/peft/helpers.py\n- src/peft/auto.py\n- src/peft/tuners/tuners_utils.py\n- src/peft/config.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 peft 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：huggingface/peft\n\n## 官方安装入口\n\n### Python / pip · 官方安装入口\n\n```bash\npip install peft\n```\n\n来源：https://github.com/huggingface/peft#readme\n\n## 来源\n\n- repo: https://github.com/huggingface/peft\n- docs: https://github.com/huggingface/peft#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_fcee8ef0f7c24b199e4017e7b27c247f"
}