SemanticEcho-Engineering · 语义回响 V3 —— 全链路工程实现

不训练、不改权重、零参数的推理期情感增强引擎 + 生产级 API 服务 + 数据打标闭环。 回收模型生成时被 softmax 丢弃的 token 嵌入，作为「情感底色」持续注入输出； 让小模型在情感表达 / 人味维度上向大模型靠拢 —— 人味由引擎补，成本由小模型省。 任意 decoder-only 模型只要给出 hidden_dim，引擎自动匹配最优注入参数（λ / γ / τ）。

本仓库是「语义回响（Semantic Echo）」体系三仓之一：

仓库	定位
SemanticEcho-Papers	方法论：论文、专利、方案设计
SemanticEcho-Engineering（本仓）	工程实现：推理框架、回响引擎、API 服务、打标闭环、监控
EmoRole-Engineering	角色侧：角色挂载、情感注入、评测与部署

---

一、模块总览

SemanticEcho-Engineering/
├── 自适应匹配.py        # 全模型自动参数匹配：hidden_dim → (λ, γ, τ)
├── 推理框架.py          # 四层集成：动态策略 v2 + RAG + LoRA + 回响
├── 回响引擎.py          # λ 步数衰减：前 N 步固定 λ，之后线性衰减至 0.3λ
├── 全流程推理.py        # 端到端 CLI：加载 → 生成 → 指标表 → JSON 运行记录
├── 打标工具.py          # 生成回复 → 标注任务（JSON + CSV，给人工标注）
├── 打标_全流程批次.py    # 把最近一次全流程运行记录转成标注任务
├── 实验_动态策略.py      # 3B 上对照动态策略 A/B/C（熵、重复率、命中率）
├── 实验_长上下文.py      # 固定 λ vs λ 步数衰减（2048 tokens 四区间稳定性）
├── API服务/             # 生产级 FastAPI：自定义协议 + OpenAI 兼容 + 控制面板
│   ├── 主程序.py        #   应用入口：注册双协议路由、挂载静态面板、CORS
│   ├── 接口.py          #   /api/v1/*（中文 JSON 字段，非 OpenAI 风格）
│   ├── openai兼容.py    #   /v1/models、/v1/chat/completions、/v1/completions
│   ├── 模型管理.py      #   模型注册/解析/加载/卸载/生成/状态（单例）
│   ├── 下载器.py        #   直链下载 + HuggingFace snapshot_download（可换镜像）
│   ├── 参数.py          #   λ/γ/τ 前端可调（覆盖自动推荐值）
│   ├── 开关.py          #   API / RAG / LoRA / 记忆 运行时热开关
│   ├── 流程编排.py      #   七节点状态机：注册→解析→适配→加载→生成→测试→打标
│   ├── 测试引擎.py      #   配置匹配 / λ 调度 / 模型冒烟 三组自检
│   ├── 监控.py          #   日志环形缓冲 + 生成记录 + GPU 显存 + 系统内存
│   ├── 记忆.py          #   超长期记忆：写入 / 检索 / 注入（情感维度 + n-gram 加权）
│   ├── 打标服务.py      #   定制模型流程：批量生成 + 输出标注任务（后台线程）
│   ├── 复查.py          #   打标二次复查：改情感维度/质量分/状态并回写
│   ├── 证书工具.py      #   自签名 HTTPS 证书（SAN=localhost/127.0.0.1，3650 天）
│   ├── 启动服务.py      #   CLI 启动（--端口 / --host / --https）
│   ├── 启动服务_MI300X.py # AMD MI300X（ROCm）适配启动脚本
│   └── 静态/            #   index.html（简化版）/ pro.html（专业版）/ dashboard.html（大屏）
├── 商务附件_全链路能力与技术介绍.md
├── 商务附件_商业授权价目表.md
└── README.md

运行时会自动创建 数据/（运行记录、模型库、记忆库、日志），本仓库不包含任何运行时数据。

---

二、四个核心件怎么工作

1. 自适应匹配（自适应匹配.py）—— 任何模型即插即用

• 扫描表（实测最优，优先命中）：896 → (0.50, 0.05, 0.10)、1536 → (0.08, 0.07, 0.09)、 2048 → (0.10, 0.08, 0.06)、3584 → (0.06, 0.12, 0.05)；
• 公式兜底（未命中时，与扫描表偏差 < 30%）：λ = 0.5·(896/d)^1.5（d<2048）/ 0.28·(896/d)（d≥2048），γ = 0.05·(d/896)^0.5，τ = 0.10·(d/896)^-0.5；
• 参数含义：λ 注入强度（大→更有灵性但易重复坍缩）、γ 回响池衰减（大→历史消退快）、 τ 情感筛选阈值（大→只保留高情感词）。

2. 回响引擎（回响引擎.py）—— 长上下文不坍缩

前 衰减起始步（默认 256）步使用固定 λ，之后线性衰减到 λ × 0.3（生成结束时到达）。 相比固定 λ，2048 tokens 全程熵保持在稳定区间、重复率接近 0；固定 λ 方案在 1024 步后坍缩复读。

3. 推理框架（推理框架.py）—— 四层编排

动态策略 v2（检测情感密度 > 0.15 时：A 不动 / B 降 τ 不升 λ / C 升 λ 且降 τ）

• RAG（FAISS top-k 检索拼 [参考信息] 前缀，向量库缺失自动回退纯回响）
• LoRA（peft 热挂载/卸载）+ 回响（长上下文启用时走步数衰减版）。

4. API 服务 + 打标闭环（API服务/）

• 双协议：/api/v1/*（中文 JSON 字段，内部/控制面板用）与 /v1/*（OpenAI 兼容，第三方客户端直接接）；
• 三套面板：简化版 /、专业版 /pro、监控大屏 /dashboard；
• 数据闭环：全流程运行记录 → 打标工具 出标注任务（JSON + CSV，带情感维度与 1–5 质量分） → 人工 复查 → 定制模型训练 → 再挂回引擎。

---

三、怎么跑

前置：Python 3.10+，NVIDIA GPU（或 AMD ROCm / 纯 CPU 慢速），torch、transformers、fastapi、uvicorn 等； 模型权重需自备（本仓库不含权重，建议 Qwen2.5 系列 GGUF / safetensors）。

# 0) 依赖（API 服务侧最小集）
pip install -r API服务/requirements.txt

# 1) 端到端跑一遍（一条命令）
python 全流程推理.py --模型 "<你的模型目录>/Qwen2.5-1.5B-Instruct" --量化 4bit --动态策略 B

# 2) 带 RAG / LoRA / 长上下文
python 全流程推理.py --模型 "<模型目录>" --量化 4bit --rag \
    --lora "<lora 目录>" --动态策略 C --长上下文 --提示 "你好" --提示 "再见"

# 3) 只要参数推荐（不加载模型）
python -c "from 自适应匹配 import 推荐参数; print(推荐参数(1536))"

# 4) 起 API 服务（自定义协议 + OpenAI 兼容 + 控制面板）
cd API服务
python 主程序.py                 # http://127.0.0.1:8000
python 启动服务.py --端口 8000 --host 0.0.0.0
python 启动服务_MI300X.py        # AMD MI300X / ROCm 环境

常用接口（启动后）：

方法	路径	用途
GET	/api/v1/健康	健康检查
POST	/api/v1/生成	标准生成（带 λ/γ/τ 与指标）
POST	/api/v1/打标	定制模型流程：批量生成 + 输出标注任务
GET	/api/v1/状态	模型/流程/监控状态
GET	/v1/models	OpenAI 风格模型列表
POST	/v1/chat/completions	OpenAI 风格对话补全

具体字段以 API服务/接口.py 与 API服务/openai兼容.py 顶部注释为准（每个模块头部都写了协议与参数）。 Windows 下如遇中文路径问题，先 chcp 65001 或直接把模型放在纯 ASCII 路径下。

---

四、原工程记录的设计指标（来自原工程 README，未在本仓库重跑）

1.5B 原版基座（Qwen2.5-1.5B-Instruct，未微调）挂载引擎后，同种子 42、唯一变量为是否挂载：

基准	裸 1.5B	挂载引擎
TuringBench 人似度	0.2333	0.4667
EmoCharacter 情感保真	0.8750	0.8863
HeartBench 中文人味	0.4055	0.4130
HEART-BENCH 人格推理	0.4884	0.5367
LLM-as-Judge 盲评	0.6900	0.6333

另有 3B 4bit、20 条提示词的全流程实机记录：成功率 100%、平均熵 2.06、平均重复率 0.07。 以上均为原工程自测口径，本仓库不复现该实验环境，请按第三节自行复跑后使用。

---

五、收录与脱敏说明

• 不含：模型权重（.pt/.pth/.safetensors/.gguf/.bin 等）、音视频、压缩包、虚拟环境、运行时 数据/ 目录、任何密钥与 token。
• 正文脱敏：角色代号统一为 EmoCompanion / RoleB / SpeakerA；绝对路径统一为 <workspace>/、<home>/、<data-root>/；邮箱与凭据打码。 因此代码中的默认路径（原为作者本机路径）会被替换为占位符，首次运行请用命令行参数显式指定模型与输出目录。
• 未收录的原始文件：一份对外未发出的商务合作邮件草稿（含第三方联系人与手机号，不属于工程内容）； 原工程根 README.md 由本规范 README 替代（原 README 的商业价目表内容见 商务附件_商业授权价目表.md，实测指标见第四节）。

---

六、许可证

本仓库采用 CC BY-NC-SA 4.0 + 附加限制条款（署名-非商业性使用-相同方式共享 4.0），详见 LICENSE。

• ✅ 允许：学习与个人研究、学术论文引用、复现验证实验（须署名）
• ⚠️ 限定：可用代码但不可整段照抄；仅限非商业用途
• ❌ 禁止：任何商业用途（含企业内部使用）、未署名的转载
• 相同方式共享：修改后再分发必须采用同一许可证
• 商业授权：商业使用 / 独家 / 买断授权请联系作者洽谈，价目参考 商务附件_商业授权价目表.md