不训练、不改权重、可热插拔的「角色人格挂载 + 情感自然注入」工程实现。 把打标数据提炼成 ≤10MB 的角色包（情感特征谱），在解码期以零权重注入的方式把角色人格、 情感倾向与口癖表达接进本地大模型：人格基调（慢、稳）× 会话潮汐（中）× 情境反应（快）三层正交叠加， 目标是在 6/8/10/12GB 显存档位上都能跑、长对话不 OOC、切换角色不发呆。
本仓库是「语义回响（Semantic Echo）」体系三仓之一：
| 仓库 | 定位 |
|---|---|
| SemanticEcho-Papers | 方法论：论文、专利、方案设计 |
| SemanticEcho-Engineering | 引擎侧：推理框架、回响引擎、API 服务、打标闭环 |
| EmoRole-Engineering（本仓） | 角色侧：角色包构建、人格/情感注入、评测对照、TTS 外挂、部署归档 |
| 目录 | 内容 | 说明 |
|---|---|---|
01_综合技术方案/ |
本地角色挂载与情感注入综合技术方案、工程实践化方案 | 先读这里：资源盘点、方案选型、三硬指标与 6 条经验法则 |
02_角色参数与数据/ |
打标数据质量评估报告、标签奖励统计、汇总报告 | 仅保留评测结果；原始训练集 JSONL 不收录（见第五节） |
03_评测与对照/ |
（源工程中为空目录，未收录） | 评测代码与报告实际分布在 05_三档显存测试/ |
04_源码与原型/ |
backend/（FastAPI 服务 + 引擎 + CLI + 前端）、data/role_pack/ 角色包描述、scripts/eval_emoscore.py、部署验收报告 |
角色引擎主实现 |
05_三档显存测试/ |
显存/保真/去 AI 腔/调度器标定等 11 份实验报告 + 全部实验脚本与原始日志 | 评测与对照的证据链 |
06_Qwen3TTS外挂/ |
Qwen3-TTS LoRA 训练与 GGUF 推理脚本、一体化对话台、情感检测、韵律风格、音色校准 | TTS 外挂（不含权重与音频） |
07_最终归档/ |
里程碑最终归档、API 接口文档、归档版服务入口 | 交付快照 |
07_说唱合成Qwen3RapSynth/ |
说唱合成研究框架（韵律预测器、拍网格编排、A/B 消融） | 表达力扩展实验 |
console/ |
网页对话控制台（app.py + 静态前端） |
本地交互调试 |
app.py、启动CLI.py |
根级一键入口 | 见第三节 |
- 角色人格不是提示词模板，而是"情感特征谱"：从多维打标数据（人格/VAD/情感/声学）提取低维连续状态向量
v_角色+ 角色偏移量，落成标准化角色包（≤10MB，热切换 <1ms）。 - 载体选型：放弃回响池（P1）作为人格主载体（7B 下投影矩阵约 933MB，违背 ≤1GB 预算；且回响池是"情境情绪"不是"人格常量"），改用 P3 锚点行 + P5/P6 状态向量；推理引擎选 P6 情感导演 EDD（综合分 0.7046，家族最高），叠加 P1.5 自动适配总开关与 P3×P4 双通道。
- 分层控制避免标签化：人格基调（慢、稳定）× 会话潮汐（中）× 情境反应（快），三层正交叠加；每层都有独立强度预算与"边际增益门"，杜绝"叠了反而更差"。
- 资源：6/8/10/12GB 全部可跑；8GB 为优化基准，情感注入额外显存开销压到 <1GB（可选全部情感计算外置 CPU，仅
V×1引导张量上 GPU）。
前提：本仓库不含模型权重与原始数据，需自备基座模型（Qwen2.5 / Qwen3 系列，GGUF 或 safetensors）、 以及
04_源码与原型/data/role_pack/的二进制向量文件（.npy，本仓库同样未收录）。 角色包可由04_源码与原型/backend/build_role_pack.py从打标数据重新构建。
# 1) 角色引擎（后端服务 + 前端，一键启动，自动建虚拟环境装依赖）
cd 04_源码与原型/backend
python app.py
# 2) 归档版服务入口（对外 API）
cd 07_最终归档
python app.py --serve --port 8000
# 3) 命令行对话
python 启动CLI.py
# 4) 网页对话控制台
cd console
python app.py
# 5) 角色包构建 / 情感能力评测
python 04_源码与原型/backend/build_role_pack.py --help
python 04_源码与原型/scripts/eval_emoscore.py主要接口（详见 07_最终归档/接口文档.md）：
| 方法 | 路径 | 用途 |
|---|---|---|
| POST | /chat |
对话（返回回复 + 情感维度/命中率等指标） |
| GET | /health |
健康检查 |
服务默认地址 http://127.0.0.1:8000，引擎默认 llama.cpp CUDA + Qwen3-4B-Q4_K_M GGUF（可在配置中替换）。
| 指标 | 定义 | 状态 |
|---|---|---|
| 叠加正向性 | 每层算法过「边际增益门」，杜绝叠了更差 | 机制落地 |
| 情感能力提升 >70% | EmoScore 全栈 ≥ 1.7× 裸模型 | 管线就绪，待 LLM-Judge 盲评 |
| 长对话不 OOC | 30 轮：身份泄漏率 <2% / 漂移 ≤5 / 重复率 ≤0.12 | 实测全过 |
| 推理提速 ≥100% | 低设备高速推理 | +173%~238% |
关键单一结论（详见 05_三档显存测试/ 下各报告）：
P3 锚点注入主收益是防复读/防坍缩/输出细腻度（重复率 0.169→0.149）、强 β 反而劣化（7B 保真 87→79）、
P4 单通道有害而 P3×P4 双通道 win_rate 0.2667 全场最高、去 AI 腔只做 mild 双向抑制（71→74，strong 有害）。
- 原始训练数据与音视频未收录。具体来说：
02_角色参数与数据/微调数据/*.jsonl（微调训练集、情感打标训练集，单文件约 44MB）未收录 —— 体积大且含原始对话内容；06_Qwen3TTS外挂/data/*（TTS 训练代码数据、原始字幕/编码 JSONL，约 100MB）未收录；- 模型权重（
.safetensors/.pt/.gguf/.npy/.npz等）、生成的音频（.wav）、虚拟环境、运行时输出目录与聊天数据库均未收录。 - 因此本仓库是"工程与方法仓"：脚本、方案、实验报告、评测结果齐全，但无法开箱直接复跑（缺权重与数据）。
- 正文脱敏：角色代号统一为
EmoCompanion（原角色名）、RoleB、SpeakerA；绝对路径统一为<workspace>/、<home>/、<data-root>/；邮箱/凭据打码；主机名统一为HOST。 角色包文件名与代码内引用同步替换，若与你本地文件不一致，请按替换表自行映射。 - 未收录的其它文件：
02_角色参数与数据/汇总报告/文件复制校验报告.json（一次性拷贝校验日志，无技术信息）。
本仓库采用 CC BY-NC-SA 4.0 + 附加限制条款（署名-非商业性使用-相同方式共享 4.0），详见 LICENSE。
- ✅ 允许：学习与个人研究、学术引用、复现验证实验（须署名）
⚠️ 限定：可用代码但不可整段照抄；仅限非商业用途- ❌ 禁止：任何商业用途（含企业内部使用）、未署名的转载
- 相同方式共享：修改后再分发必须采用同一许可证
- 商业授权：商业使用 / 独家 / 买断授权请联系作者洽谈