# Qwen3.8-27B-SSMFIX-UD-Q3_K_XL-GGUF

> [English model card](README.md)

> 实验性社区转换版本，不是 Qwen 官方发布物。

本仓库包含一个 GGUF 文本推理模型：

`Qwen3.8-27B-BF16-SSMFIX-UD-Q3_K_XL.gguf`

它根据 [redashes/Qwen3.8-27B-BF16-SSMFIX](https://huggingface.co/redashes/Qwen3.8-27B-BF16-SSMFIX) 量化而来，而该模型又源自官方 [Qwen/Qwen3.8-27B](https://huggingface.co/Qwen/Qwen3.8-27B)。

## 模型概览

| 属性 | 内容 |
|---|---|
| 模型系列 | Qwen3.8 |
| 参数量 | 27B dense 模型 |
| 文件格式 | GGUF V3 |
| 量化标识 | UD-Q3_K_XL |
| 量化方式 | 使用 importance matrix 的自定义混合量化 |
| 文件大小 | 12,807.91 MiB，约 12.52 GiB |
| 报告 BPW | 3.93 |
| 上游上下文长度 | 262,144 tokens；实际容量取决于运行时和硬件 |
| 主要运行环境 | llama.cpp 及兼容 GGUF 的运行时 |
| 本文件用途 | 文本推理 |

`UD-Q3_K_XL` 是量化档位名称，并不表示每一个张量都使用纯 `Q3_K`。具体混合量化配方见 [quantization_recipe.txt](quantization_recipe.txt)。

## 模型来源与归属

```text
Qwen/Qwen3.8-27B
        |
        v
redashes/Qwen3.8-27B-BF16-SSMFIX
        |
        v
Luis23333/Qwen3.8-27B-SSMFIX-UD-Q3_K_XL-GGUF
```

- 上游模型：[Qwen/Qwen3.8-27B](https://huggingface.co/Qwen/Qwen3.8-27B)
- 直接 BF16 来源：[redashes/Qwen3.8-27B-BF16-SSMFIX](https://huggingface.co/redashes/Qwen3.8-27B-BF16-SSMFIX)
- 背景讨论：[Qwen3.8-27B discussion #76](https://huggingface.co/Qwen/Qwen3.8-27B/discussions/76)
- GGUF 发布者：Luis23333

直接来源模型将自身描述为对社区 SSM/conv1d 尺度问题研究的独立验证。本 GGUF 保留该修复版来源关系，然后按照下文的量化配方进行量化。它应被视为实验性社区模型，而不是 Qwen3.8 的官方修复版。

## SSMFIX 修复内容

BF16 来源模型对 8 个 `ssm_conv1d.weight` 张量进行逐层 alpha 缩放：

| 层 | 张量 | Alpha |
|---:|---|---:|
| 52 | `blk.52.ssm_conv1d.weight` | 0.59005 |
| 53 | `blk.53.ssm_conv1d.weight` | 0.55484 |
| 56 | `blk.56.ssm_conv1d.weight` | 0.54486 |
| 57 | `blk.57.ssm_conv1d.weight` | 0.53574 |
| 58 | `blk.58.ssm_conv1d.weight` | 0.60972 |
| 60 | `blk.60.ssm_conv1d.weight` | 0.48136 |
| 61 | `blk.61.ssm_conv1d.weight` | 0.65327 |
| 62 | `blk.62.ssm_conv1d.weight` | 0.61856 |

本地量化日志显示，`ssm_conv1d.weight` 在 GGUF 中仍保持 F32，因此该修复没有被本量化配方主动量化掉。

## 量化配方

模型从修复版 BF16 GGUF 转换而来，使用 llama.cpp build `9222 (9a532ae4b)` 和名为 `imatrix_unsloth.gguf_file` 的 importance matrix。

| 张量类别 | 类型 |
|---|---|
| 默认量化类型 | `IQ3_S` |
| Token embedding | `Q3_K` |
| 输出张量 | `Q5_K` |
| `attn_v` | `Q5_K` |
| 部分 attention、FFN、SSM、MTP 张量 | `IQ4_XS` |
| `ssm_conv1d.weight` | `F32` |

完整的张量覆盖规则记录在 [quantization_recipe.txt](quantization_recipe.txt) 中。因此，这个文件是自定义混合量化，不是纯单一类型的 Q3_K 文件。

## 多模态限制

上游 Qwen3.8 是视觉语言模型，但本仓库只包含上述转换得到的语言模型 GGUF，不包含 `mmproj`/视觉 projector。因此这个单文件版本只按文本推理模型进行介绍和测试。需要图像或视频输入时，请使用上游 Transformers 仓库或包含兼容 projector 的模型包。

## llama.cpp 使用方法

请使用支持 Qwen3.8/Qwen3.5 架构的较新 llama.cpp 版本。

### 交互式文本对话

```bash
llama-cli \
  -m Qwen3.8-27B-BF16-SSMFIX-UD-Q3_K_XL.gguf \
  --jinja \
  --reasoning on \
  -cnv
```

如果运行时支持，可以使用 `--reasoning off` 关闭思考模式。

### HTTP 服务

```bash
llama-server \
  -m Qwen3.8-27B-BF16-SSMFIX-UD-Q3_K_XL.gguf \
  --jinja \
  --reasoning auto \
  --ctx-size 16384 \
  --n-gpu-layers auto \
  --fit on \
  --flash-attn auto
```

262,144 tokens 是继承自上游的上下文元数据，并不意味着任意显卡都能实际分配这么大的上下文。16 GiB 显卡建议从 16,384 上下文开始，再根据显存逐步增加。

上游 Qwen 推荐参数大致为：

- 思考模式：`temperature=1.0`、`top_p=0.95`、`top_k=20`、`min_p=0.0`。
- 非思考模式：`temperature=0.7`、`top_p=0.80`、`top_k=20`、`min_p=0.0`、`presence_penalty=1.5`。

## 评测与本地 smoke test

### BF16 来源模型的参考结果

以下数据属于直接来源 BF16 模型，不属于本 GGUF 的质量评测，仅作为来源背景：

| 指标 | BF16 来源 v2 |
|---|---:|
| MT-Bench 平均 | 7.47 |
| IFEval prompt strict | 0.5194 |
| IFEval instruction strict | 0.6343 |
| GSM8K strict | 0.9644 |
| CMMLU | 0.6996 |
| TruthfulQA MC1 / MC2 | 0.3758 / 0.5513 |
| TruthfulQA generation ROUGE-1 / ROUGE-2 / ROUGE-L / BLEU | 0.345 / 0.246 / 0.345 / 0.256 |

### GGUF 运行 smoke test

本地测试使用 llama.cpp build `9222 (9a532ae4b)`、NVIDIA RTX 5070 Ti、16,384 上下文、6 个 prompt，每个运行 3 次，最多生成 256 tokens。

| 模式 | 成功请求 | 平均耗时 | 平均生成速度 |
|---|---:|---:|---:|
| Baseline | 18/18 | 6506.96 ms | 39.367 tokens/s |
| MTP2 | 18/18 | 23098.24 ms | 11.180 tokens/s |

这些是运行时 smoke test，不是模型能力分数。在当前本地环境中 MTP2 慢于 baseline，因此本仓库不宣称 MTP 对该文件一定能加速。

## 限制与免责声明

- 这是实验性社区转换版本，不是 Qwen 官方发布物。
- SSMFIX 假设及其收益不保证适用于所有任务。
- 本 GGUF 没有直接复现 BF16 来源模型的质量评测分数。
- 本仓库不包含视觉 projector，不将单文件版本宣传为多模态包。
- 长上下文表现取决于运行时、KV cache、显存/内存和 prompt 形状。
- 用于生产前请在自己的任务上验证。

## 许可证

模型遵循上游 Qwen 的 Apache-2.0 许可证，详见 [LICENSE](LICENSE)。重新分发时请保留上游和直接来源模型的归属信息。