MIT licensed research and engineering PoC for a performance-first, text-first Qwen3.8-27B inference path on a single RTX 3060 12GB. It is intentionally honest about its evidence boundary: the repository includes CPU-side numerical tests, CUDA source and an RTX 3060 validation gate, but does not claim a target-card benchmark unless that gate has actually been run.
Qwen3.8-27B 在单张 RTX 3060 12GB 上的 batch=1 性能优先推理架构研究、性能模型和关键模块 PoC。
最重要的结论是：普通 Q4 计算权重仍不能完整驻留，而把输入 embedding 与视觉塔移到主机、将语言计算权重做校准后的 W3/W4 整张量混合量化，可把默认 no-MTP 常驻权重压到 9.87 GiB，连同 8K hot INT4 KV、FP32 Gated DeltaNet 状态、workspace 和 CUDA Graph 预算后为 10.77 GiB。这使 decode 的关键路径从 CPU RAM/PCIe offload 转为 GDDR6 权重扫描。
本工作环境没有 CUDA GPU。results/rtx3060_projection.json 的 decode、prefill、TTFT 全是模型推算；results/local_microbench.json 仅是本地 CPU 数值/缩小规模实验。代码和报告不会把它们表述为 RTX 3060 实测。
- 完整技术报告：
REPORT.zh-CN.md - 目标机验证计划：
TARGET_BENCHMARK.md - 运行时审查记录：
RUNTIME_QA.zh-CN.md - 持续优化问题台账：
STATUS.zh-CN.md - 可执行 text-first runtime：
runtime/run_resident3.py（先--inspect验证 manifest） - 架构图：
diagrams/architecture.svg - Python PoC：
q3060/ - 可编译 CUDA PoC：
cuda/ - 官方 safetensors 转换器：
tools/convert_checkpoint.py - 结果与 CSV：
results/
PYTHONPATH=. python -m unittest discover -s tests -v
PYTHONPATH=. python bench/run_microbench.py
PYTHONPATH=. python bench/simulate_3060.py
MPLCONFIGDIR=/tmp/q3060-mpl PYTHONPATH=. python bench/export_artifacts.py重建中文版 PDF 需要 Pandoc、XeLaTeX 和可嵌入的 CJK 字体；脚本在字体缺失时会拒绝生成不可读文件：
python tools/build_report_pdf.py --font /absolute/path/NotoSansCJKsc-Regular.otf目标 RTX 3060 上先运行：
./scripts/target_validate.sh它会构建 SM86 CUDA PoC，测 pinned H2D、device copy、三个 Qwen 典型矩阵形状的 W3A16/W4A16 fused GEMV，逐次校验首行数值，并保存完整 GPU/驱动/时钟元数据。
转换完成后，可用 ./scripts/target_full_validate.sh 作为完整上线门禁：它依次运行 Python 数值测试、slab 检查、真实可用 VRAM/SM86 预检和 CUDA 微基准，并在任一步失败时停止。
完整 text-first runtime 的目标机路径：
python -m pip install -r runtime/requirements.txt
python tools/convert_checkpoint.py --index "$CHECKPOINT/model.safetensors.index.json" --checkpoint-dir "$CHECKPOINT" --output "$RESIDENT" --precision-plan calibrated-plan.json
PYTHONPATH=.:runtime python runtime/run_resident3.py --resident-dir "$RESIDENT" --checkpoint-dir "$CHECKPOINT" --inspect
PYTHONPATH=.:runtime python tools/runtime_preflight.py --resident-dir "$RESIDENT" --checkpoint-dir "$CHECKPOINT"
PYTHONPATH=.:runtime python runtime/run_resident3.py --resident-dir "$RESIDENT" --checkpoint-dir "$CHECKPOINT" --prompt "你好" --max-new-tokens 64 --fused-gemv --fused-gdn--fused-gemv --fused-gdn 首次运行会本地编译 SM86 扩展；不带它们时走准确但更慢的 PyTorch fallback，便于图与量化调试。tools/runtime_preflight.py 会在真实机器上逐层检查 manifest、官方模型图、CUDA 架构与当前空闲显存，避免模型上传到一半才失败。当前执行器是 text-first；图像/视频前缀仍由按需视觉塔路线处理，避免破坏 12GB decode 预算。完整操作说明在 runtime/README.zh-CN.md。
real_target_*：只有目标机脚本实际运行后才允许出现。local_cpu_microbenchmark_and_numerical_test：当前无 GPU 环境的局部实验。deterministic_timeline_model：双/三缓冲离散时间线。theoretical_projection：显式假设驱动的 RTX 3060 推算。community_reported_measurement：公开用户日志，只作外部交叉检查。