ilovemugi/mugi-decision

作者本人要说的话： 一切优化针对本人的A卡，原始未优化版本也保留，如果想玩玩看建议善用AI来适配。

Mugi Decision — 基于 Qwen backbone 的可变候选评分模型

本模型基于 Qwen/Qwen3.5-0.8B 的 text backbone 改造并微调。 保留 Qwen3.5 的混合文本解码器（DeltaNet + 全注意力），并接回原版视觉编码器及 merger，去掉词表输出投影， 改用所有候选共享的标量评分头。它接收“描述 + 若干候选”，给每个候选打分； 不生成聊天回答，也不是 Qwen 官方发布的模型。

Mugi Decision modifies and fine-tunes the Qwen3.5-0.8B text backbone. It replaces vocabulary prediction with a shared scalar decision head and supports variable-size candidate sets. This repository contains the merged BF16 text decision checkpoint, the original Qwen visual tower, tokenizer, text/image inference, text LoRA training, and optional Windows ROCm HIP kernels. It is an independent derivative, not an official Qwen release.

架构图

图示为文本决策骨干；视觉特征插在描述开头，选项分支与评分头保持相同结构。

模型与输入

文本部分约 752M 参数，24 层文本解码器；视觉部分 100,592,896 参数。输入直接序列化，不使用 Qwen 的 Jinja chat template：

公共前缀：
<|desc_begin|>问题描述<|desc_end|><|enum_begin|>["选项1", "选项2", ...]<|enum_end|>

每个分支后缀：
<|current_begin|>当前选项文本<|current_end|>

六个标记均为 tokenizer 中的独立 special token。每个分支最后一个有效 token 的隐藏状态经过共享 线性层产生标量；在当前候选集合内 softmax。候选数量不是固定分类头维度，至少需要两个候选。

推理时前缀只算一次，分支复制完整的 attention K/V、DeltaNet FP32 循环状态和卷积历史， 然后分批并行评分。训练使用完整序列，保留梯度，不使用分离梯度的前缀缓存。

改变选项列表会改变公共前缀，必须重新计算前缀。 仅同一道题、同一公共前缀下的候选后缀可以共享缓存。

快速开始

下载整个仓库（包括推理代码）：

hf download ilovemugi/mugi-decision --local-dir mugi-decision
cd mugi-decision

Windows / RX 7900 XTX / ROCm

仓库包含已验证的 uv 配置及锁文件；要求兼容的 AMD 驱动，Python 3.13：

uv sync --frozen
uv run --frozen python scripts/vision_webui.py

打开 http://127.0.0.1:7861 上传图片并输入问题、选项。纯文字交互可运行 uv run --frozen python scripts/try_model.py。

模型只加载一次，可以连续输入问题和选项。输入问题后空行结束，再每行输入一个选项，空行开始评分。 含空行的长段落先输入 /paste，粘贴后用单独一行 /end 结束。/quit 退出。

文件推理（先按下方示例创建 decision.json）：

uv run --frozen python scripts/infer.py --model . --input decision.json

Windows gfx1100 + BF16 自动启用已验证的 HIP 快速路径；加 --optimization none 回到参考实现。 --optimization hip 保留分离的运算路径并启用 HIP 核；本仓库权重已经合并 LoRA， 与开发期间“未合并 LoRA”的基准不同。--optimization fast 使用 HIP 和打包投影。

Linux / NVIDIA CUDA

以下以兼容 CUDA 13.0 的驱动为例；其他显卡请选用匹配的官方 PyTorch wheel：

uv sync --frozen
CUDA_VISIBLE_DEVICES=0 MUGI_BACKEND=cuda uv run --frozen python scripts/vision_webui.py
CUDA_VISIBLE_DEVICES=0 MUGI_BACKEND=cuda uv run --frozen python scripts/infer.py --model . --input decision.json

推理脚本支持 CUDA；仓库内 HIP 核只针对 Windows ROCm。CUDA 未安装 FLA/causal-conv1d 时会使用较慢的参考算子，不能将该路径速度当作优化过的 H100 性能。 当前 CLI 要求暴露一张支持 BF16 的 GPU，不自动回退到 CPU。

自定义输入

{
  "description": "磁盘使用率达到 95%，希望释放空间并保留近期排障信息，应怎样处理？",
  "options": [
    {"id": "rotate", "text": "检查保留要求，轮转并压缩旧日志，验证释放空间。"},
    {"id": "delete", "text": "直接删除整个系统目录。"},
    {"id": "ignore", "text": "等待磁盘写满。"}
  ]
}

保存为 JSON，传给 --input；也支持逐行 JSONL。 输出包括 selected_id、各候选 score/probability 和推理模式。 softmax 百分比仅表示当前候选间的相对分数，不是校准后的正确概率。

Transformers 加载

自定义架构代码已随权重提供，审阅代码后可使用 trust_remote_code=True：

import torch
from transformers import AutoModel, AutoTokenizer

repo = "ilovemugi/mugi-decision"
model = AutoModel.from_pretrained(
    repo, trust_remote_code=True,
    dtype=torch.bfloat16, attn_implementation="sdpa",
).to("cuda").eval()
tokenizer = AutoTokenizer.from_pretrained(repo)

此 AutoModel 示例加载文本评分器。图文评分使用下方 VisionDecisionEngine，自动组合本仓库的两份权重；无需另外下载 Qwen。 完整输入构造和缓存评分见 scripts/infer.py、mugi_decision/encoding.py 与 mugi_decision/vision.py。

仓库不包含 chat_template.jinja：推理直接编码六个自定义标记，不调用任何聊天模板。 模型架构代码仅保留根目录一份；命令行与 AutoModel 共用它。 不要调用 apply_chat_template 或 generate 来使用此评分模型。 ROCm 的 PyTorch 设备名同样是 "cuda"。

图文推理

本次发布的文本权重仍为 mixed400 最佳 epoch 2，接入 Qwen3.5-0.8B 原版视觉编码器与 merger。 没有新增图文训练；当前支持描述中一张图片、文字选项。 图像选项、视频输入尚未实现。 model.safetensors 保存合并后的文本骨干和评分头；vision.safetensors 只保存视觉模块，二者不重复保存骨干。

from PIL import Image
from mugi_decision.vision import VisionDecisionEngine

engine = VisionDecisionEngine(model_path=".")
result = engine.predict(
    "图片中的物体是什么？", ["猫", "狗", "自行车"],
    image=Image.open("image.jpg"), image_size=512, max_length=4096,
)
print(result)

图像放在 <|desc_begin|> 后，使用原生视觉标记、图像特征和 M-RoPE；不使用 Jinja 聊天模板。 图像、问题、选项列表组成共享前缀，随后分支评分。verify_cache=True 可比较缓存与完整前向结果。 图像大小是像素预算（保留比例），可选 256/512/768/1024；长度上限包含展开后的图像 token。 同一 engine 的请求应串行执行；随附 WebUI 已使用请求锁。

训练代码

随附的是实际使用的文本决策 LoRA/全参数训练代码。训练通过所有候选分数的交叉熵更新骨干适配器、 六个标记 embedding 和评分头；视觉编码器不参与该入口的训练。未包含训练数据、运行日志、优化器状态或私有服务器配置。

先安装训练依赖。Windows ROCm：uv sync --frozen --extra train。 Linux CUDA：可使用 uv sync --frozen --extra train --extra cuda-kernels，需要与 CUDA 13.0 匹配的 toolkit/C++ 编译环境； causal-conv1d 首次安装会编译。所有后续 CUDA 训练命令应保持这两个 extra，避免 uv 同步时移除加速依赖。

准备已按题目/共同材料分组排重的 train.jsonl、validation.jsonl，可另加 test.jsonl。每行格式：

{"id":"train-001","language":"zh","source":{"dataset":"my-data"},"description":"一加一等于几？","options":[{"id":"a","text":"二"},{"id":"b","text":"三"}],"target":{"type":"single_choice","selected_ids":["a"]}}

下面从已发布权重继续微调；两条命令的 --model 必须指向同一个模型/分词器目录：

uv run --frozen --extra train python scripts/prepare_training.py --model . --train train.jsonl --validation validation.jsonl --output data/ready
uv run --frozen --extra train python scripts/train.py --model . --data data/ready --output runs/my-lora --epochs 1 --batch-groups 1 --gradient-accumulation 16 --lr 5e-5 --rank 16 --dtype bf16

准备阶段固定选项顺序变体、检查标签和长度、拒绝重复描述，超长训练题在此阶段剔除并计数；验证题超长直接报错。 训练入口校验文件哈希，训练时不分词、不跳题。相同材料的不同问法及语义重复需要使用者在划分数据前处理。

若要从原始 Qwen 决策底模重新训练，而不是继续本仓库权重：

hf download Qwen/Qwen3.5-0.8B --local-dir Qwen3.5-0.8B
uv run --frozen --extra train python scripts/convert_model.py --source Qwen3.5-0.8B --output models/fresh-base

再将前面准备数据和训练命令的 --model . 均替换为 --model models/fresh-base。 原始底模不重复随本仓库分发。H100 已验证的优化开关为： --batch-groups 16 --gradient-accumulation 1 --checkpoint-linear-only --adaptive-checkpoint-tokens 12000 --fused-norms --autocast-lora --runtime-cumsum --cpu-threads 16。 实际显存由候选数量和分支长度决定；这些开关需要 CUDA 加速依赖。

训练输出 runs/my-lora/final 为适配器。继续图文推理： VisionDecisionEngine(model_path=".", adapter="runs/my-lora/final")，要求训练底模就是本仓库权重。 从 fresh-base 训练的适配器必须使用它对应的底模，不能直接套在已合并的发布权重上。 --resume runs/my-lora/checkpoint-N 可恢复训练；--epoch-snapshots 保留每个完整 epoch 的结果。 合并文本适配器可使用 scripts/merge_adapter.py --model <训练底模> --adapter <适配器> --output <新目录> --dtype bf16； 图文使用时还需将本仓库的 vision.safetensors、vision_config.json 和 preprocessor_config.json 放入该目录。

训练与权重选择

• 原始决策底模：Qwen3.5-0.8B text backbone + 初始化评分头和六个标记 embedding。
• 本次 mixed400 从原始决策底模开始，400,000 道去重训练题；中文 160,000、英文 240,000，65 个来源。
• LoRA rank 16、alpha 32、dropout 0.05；训练评分头、六个标记 embedding 及注意力/MLP 的 LoRA。
• BF16，3 epochs，总计 75,000 次更新；有效 batch 16，初始学习率 5e-5。
• 按固定验证集的中英文宏平均准确率选模，本次发布的是 epoch 2 / step 50,000。
• 不是第 3 轮末尾模型，也没有根据测试集挑选 epoch。
• 根目录 model.safetensors 已合并 LoRA，可独立加载，不需重新下载原始 Qwen 多模态权重。

评测

固定验证集 6,144 题：

Epoch	总准确率	中文	英文	验证 loss
1	75.54%	74.41%	76.29%	0.5802
2（选中）	76.63%	76.00%	77.05%	0.6327
3	76.37%	75.22%	77.13%	1.1754

固定独立测试集 2,048 题（中文 819、英文 1,229）：

模型	总准确率	中文	英文
第一轮 150k 最佳模型	61.38%	58.73%	63.14%
本次 mixed400 选中的 epoch 2	64.99%	62.64%	66.56%

本次答对 1,331/2,048 题。这些是本项目冻结子集的结果，不是完整官方榜单成绩。 测试包含 ARC、C3、MMLU-Pro、MMLU、C-Eval、SecQA-v2、SciQ、CMMLU、 LogiQA2-zh、PubMedQA labeled、AQuA，不覆盖全部后来新增任务。 测试与验证的任务配比不同，不能直接用两者总分差判断过拟合。 既有底模预训练数据不可完全审计，因此这里的排重不等于证明没有预训练污染。

上述主评测使用合并前的最佳 LoRA、BF16、固定离线选项顺序。 发布权重合并到 BF16，加上可选 HIP 算子会产生舍入差异，尚未将发布后所有运行模式逐一重跑完整测试集。 本机对 128 道覆盖 70 个验证来源的题目 + 1 道手工长题做过实现回归： 最快实现与原始 LoRA 的首选 127/129 一致；两处变动均是原版前两项仅差 0.015625 分的题目， 128 道有标签题的答对数均为 99。该小样本不构成“准确率完全不变”的保证。

本机 HIP 性能

RX 7900 XTX、Windows ROCm、Minecraft 长题，公共前缀 575 token、6 个候选：

实现	首次评分	预热中位数
原版 LoRA + 前缀缓存	8.36 s	144 ms
HIP + 内存合并 + 打包投影	0.47 s	52 ms

相同重复次数复测，约 2.76 倍预热提速；不含模型加载及 tokenizer。 首次 HIPRTC 编译另有一次性开销；后续使用本地缓存。 正式交互脚本计时还会包含输出转换等开销。底层 HIP 源码随仓库发布，不需要额外主机编译器。 此基准对应开发环境的内存合并路径；发布目录已独立试跑，示例评分与该路径一致。

局限与用途

适合研究多选决策、候选排序和轻量分类；无法保证事实正确或复杂长期规划能力。 模型会随候选措辞、排序、候选数量和上下文分布而改变分数。训练分支长度上限为 1024 token； 脚本允许更长输入不代表长上下文决策效果经过验证。 本项目未专门训练 Minecraft 行动策略，示例题只是手工功能测试。

文件与来源

• model.safetensors / config.json / tokenizer*.json：独立模型与分词器。
• configuration_mugi.py / modeling_mugi.py：Transformers 自定义架构加载代码。
• mugi_decision/ / scripts/：输入构造、模型推理、可选 HIP 优化及交互入口。
• vision.safetensors / vision_config.json / preprocessor_config.json：视觉权重及必要配置。
• scripts/train.py / scripts/prepare_training.py：训练与离线准备入口。
• webui/vision.html：本地图文测试页面。
• docs/figures/：SVG 架构图。

原始 backbone 及 tokenizer 来自 Qwen3.5-0.8B，Apache-2.0； 保留上游 LICENSE 和来源说明。项目推理代码按本仓库 Apache-2.0 发布。 各训练数据来源仍受其各自许可证和使用条件约束，不能把模型的许可证理解为对所有数据的再许可。