brontoguana/krasis · 上手攻略
- 仓库：brontoguana/krasis
- 链接：https://github.com/brontoguana/krasis
- 分类：LLM 推理引擎 · MoE 消费级 GPU 运行时
- 作者：Jay
- 更新：2026-08-20
这是什么
Krasis 是一个混合 LLM 推理运行时，专注于在消费级显存受限的 NVIDIA GPU 上高效运行数百亿参数级别的 MoE（Mixture of Experts）大模型。它的核心设计目标是：让一张或两张普通游戏显卡（如 RTX 5090 32 GB、RTX PRO 6000 96 GB）就能跑得动原本需要 H100/A100 才能加载的千亿参数模型。
v1.0.x 是当前主线，从早期 Python 热路径原型全面迁移到 Rust/CUDA 服务路径，Python 仅用于启动、配置和模型加载，所有性能关键路径（HCS 专家驻留管理、解码编排、CUDA kernel 调用、VRAM 预算分配）均由 Rust/CUDA 处理。
解决什么问题
运行超大 MoE 模型的核心矛盾在于：参数量远超单卡 VRAM。以 DeepSeek-V4-Flash-0731 为例，其 checkpoint 实际有 304.2B 参数，即使量化到 INT4，权重本身仍需要数百 GB 存储，远远超出消费级显卡的显存容量。
传统方案要么降太多精度（严重影响输出质量），要么必须多卡并行（增加硬件成本和工程复杂度）。
Krasis 的解决方案是 HCS（Hot/Cold Expert Residency Management）专家驻留管理：将 MoE 中被频繁激活的"热专家"保留在 GPU VRAM，将不活跃的"冷专家"卸载到 CPU RAM，并在推理过程中根据访问模式动态迁移。这使得单卡 32 GB VRAM 也能运行数百 B 参数的 MoE 模型，同时保持合理的推理速度。
快速安装
Linux / WSL2（推荐）
curl -sSf https://raw.githubusercontent.com/brontoguana/krasis/main/install.sh | bash -s -- prerelease
⚠️ 安装脚本默认创建
~/.krasis/venv虚拟环境，将可执行文件 symlink 到~/.local/bin，并自动更新当前 shell 的 PATH。无需 sudo。
⚠️prerelease安装最新测试版（含 v1.0.x 新特性）；如需稳定版，去掉该参数。
Windows（原生）
从 GitHub Releases 下载：
KrasisSetup-1.0.16-win64.exe
安装程序会以当前用户身份安装到 %LOCALAPPDATA%\Programs\Krasis，自带一个私有 Python 运行时（不依赖系统已有 Python），并自动添加开始菜单快捷方式。首次安装会下载 pinned CUDA/PyTorch wheel，时间较长（约数分钟）。
安装后验证
krasis --version # 显示版本信息
krasis-setup # 补充安装运行时代码依赖（通常只需一次）
核心用法
交互式启动（最常用）
krasis
启动器会逐步引导选择： 1. 本地已有模型 或 从 Hugging Face 下载（交互式 curated 下载流程） 2. GPU 选择（多卡机器可指定 GPU 索引） 3. 量化级别、KV cache 格式、HCS 策略、VRAM 安全边界 4. 是否开启 reverse SSH tunnel（将本地服务暴露给远程机器）
所有配置保存在 ~/.krasis/config，下次可非交互式加载：
# 加载上次保存的配置
krasis --non-interactive
# 指定配置文件
krasis --non-interactive --config /path/to/config.conf
# 命令行覆盖特定参数
krasis --non-interactive --model-path ~/.krasis/models/Qwen3-Coder-Next --selected-gpus 0,2 --benchmark
手动下载模型（Hugging Face CLI）
huggingface-cli download Qwen/Qwen3-Coder-Next \
--local-dir ~/.krasis/models/Qwen3-Coder-Next
核心配置参数
| 参数 | 可选值 | 说明 |
|---|---|---|
--attention-quant |
hqq4 / hqq6 / hqq8 |
HQQ 注意力量化级别，越高越精确、越耗 VRAM |
--kv-dtype |
k6v6（默认，质量优先） / k4v4（超紧凑） / bf16 |
KV cache 精度，k6v6 是质量/体积平衡起点 |
--gpu-expert-bits |
4（默认） / 8 |
MoE 专家权重量化位数 |
--vram-safety-margin |
整数（默认单位 MB） | VRAM 安全边界，偏低可能 OOM |
--dynamic-hcs |
开启（默认） / 关闭 | 是否动态调整 HCS 热/冷专家分布 |
--prefix-cache |
开启（默认） / 关闭 | 前缀缓存，聊天等多轮场景提速明显 |
⚠️ 关于
--vram-safety-margin：默认保守值约 600 MB（未验证，请以--help输出为准）。如遇 CUDA OOM，可适当增大该值；如果 VRAM 利用率低，可降低以提升 cache 容量。
OpenAI 兼容 API
Krasis 启动后暴露标准 OpenAI 接口，可直接用各类 OpenAI 兼容客户端调用：
http://localhost:8012/v1/chat/completions
健康检查：
curl http://localhost:8012/health
查看可用模型列表：
curl http://localhost:8012/v1/models
聊天客户端
# 启动交互式聊天
krasis chat
# 指定端口（默认 8012）
krasis chat --port 8013
# 直接传 prompt
krasis chat --prompt "Explain HCS in one paragraph"
# 读取文件内容作为 prompt
krasis chat --file prompts.txt
# 作为客户端调用远程 Krasis 服务
krasis chat --url http://host:8012
工具调用（Tool Use）
Krasis 支持将各模型原生工具调用语法翻译为 OpenAI 兼容的 tool_calls 结构化输出（streaming 和多轮均支持）。支持的模板家族：
- DeepSeek-V4（DSML 格式）
- Qwen（JSON / function XML 格式）：Qwen3-Coder-Next、Qwen3.5/3.6、Ornith、Step-3.7
- GLM（XML 参数格式）
- Gemma 4、MiniMax
⚠️ 已知限制：DeepSeek-V2/V2-Lite/VL2 官方模板未包含工具语法，不支持工具调用。Nemotron-3-Super INT4/HQQ4 运行时在 llama-witness 序列上有明显 autoregressive 退化，工具调用不可靠。
基准测试
# 固定入口：Qwen3-Coder-Next 速度回归测试
./dev speed-test
# 标准基准测试
./dev benchmark tests/qcn-k4v4-hqq8-int4-benchmark.conf
# 安装版命令
krasis --config tests/qcn-k4v4-hqq8-int4-benchmark.conf --benchmark
典型性能参考
⚠️ 以下数据来源于 GitHub README 原文，为 Krasis 官方自测结果，未独立第三方验证；实际性能受 CUDA 版本、PyTorch 版本、batch size 等因素影响。
| GPU | 模型 | 参数量 | 量化格式 | Prefill (tok/s) | Decode (tok/s) |
|---|---|---|---|---|---|
| RTX PRO 6000 96 GB | DeepSeek-V4-Flash-0731 | 304.2B | INT4/HQQ8/BF16 cache | 1,301.1 | 29.86（100 tokens） |
| RTX PRO 6000 96 GB | Qwen3-Coder-Next | 80B | INT4/HQQ4/k4v4 | 11,211.1 | 161.82（HTTP RT） |
| RTX 5090 32 GB | Nemotron-3-Super-120B | 123.6B | INT4/HQQ4/k4v4 | 1,852.2 | 50.76（HTTP RT） |
| RTX 5090 32 GB | Qwen3.5-397B-A17B | 397B | INT4/HQQ4/k4v4 | 973.8 | 18.71（HTTP RT） |
典型适用场景
- 本地跑超大 MoE 模型：不想用 API 付费，又需要跑 DeepSeek-V4-Flash、Qwen3.5-397B、Ornith 等千亿参数模型的个人开发者或研究者。
- 多模型对比评测：
dsh-dual-model-eval类型的评测场景，Krasis 支持同一硬件上快速切换模型配置做横向比较。 - 工具调用应用：需要 Function Calling / Tool Use 但又不想把数据发送到第三方 API 的场景，Krasis 对 Qwen3/DeepSeek-V4 的 tool call 翻译已有支持。
- 长上下文应用：k6v6 KV cache 格式（默认）兼顾质量和容量，适合需要较大上下文窗口的个人知识库或代码库分析。
坑与注意
- 首次运行慢：Krasis 首次运行时会构建本地优化缓存（
~/.krasis目录），后续运行复用缓存，速度明显提升。初次冷启动请耐心等待。 - WSL2 默认内存限制：WSL2 默认分配的内存可能只有 8 GB，这对大 MoE 模型远远不够。需要在 Windows 宿主的
C:\Users\<用户名>\.wslconfig中手动设置memory=120GB（或其他适当值）并重启 WSL。 - BF16 模式是调试模式：README 明确说明 BF16-heavy 模式是"validation/debug modes, not normal deployment targets"——生产环境应使用 INT4/INT8 专家缓存 + HQQ 注意力。
- AWQ 和 Polar4 已废弃：README v1.0.x 说明已废弃 AWQ 和 Polar4，新的生产路径使用 HQQ attention + k6v6/k4v4/BF16 KV。旧版教程可能仍引用 AWQ，请注意版本。
- 磁盘空间需求：模型文件 + Krasis 缓存（
~/.krasis）的总磁盘占用可能达到数百 GB；系统 RAM 也要足够容纳选定的量化 cache 和 HCS 冷专家数据。 - 工具调用能力不等于输出可靠性：DeepSeek-V2/V2-Lite/VL2 明确不支持 tool call；Nemotron-3-Super 在特定量化格式下不可靠；建议先查阅 ADVANCED.md 工具支持表 再决定在生产场景使用。
与同类对比
| 对比项 | Krasis | Ollama | vLLM | LM Studio |
|---|---|---|---|---|
| MoE 专家卸载 | ✅ HCS 架构 | ❌ 需完整加载 | ❌ PagedAttention 不处理 MoE卸载 | ❌ |
| 消费级单卡 | ✅ 32 GB 即可跑 397B | 部分支持（量化后） | 需要更多 VRAM | 部分支持 |
| 工具调用翻译 | ✅ 多家族原生翻译 | ❌ | ❌ | 有限 |
| Rust/CUDA 热路径 | ✅ | ❌（Go） | ✅（PagedAttention CUDA） | ❌ |
| Windows 原生 | ✅（exe 安装包） | ❌ | ❌ | ✅ |
| HQQ 注意力 | ✅ | ❌ | ❌ | 有限 |
| 开源 | ✅ MIT | ✅ AGPL | ✅ Apache 2.0 | ❌（闭源） |
⚠️ 表格对比基于公开文档，版本信息可能随更新变化；建议以各项目最新 Release 说明为准。
一句话推荐结论
如果你在消费级显卡上跑超大 MoE 模型，Krasis 的 HCS 专家卸载 + HQQ 注意力组合是当前最成熟的开源方案——一张 RTX 5090 就能跑 Qwen3.5-397B，且工具调用翻译开箱即用；但它专精 MoE，对 dense 模型（比如 Llama 3）优化有限，更适合明确需要 DeepSeek-V4 / Qwen3 / Ornith 这类 MoE 架构的用户。
来源：GitHub README（brontoguana/krasis）+ ADVANCED.md（工具调用支持表链接）+ STATS-BENCHMARKS.md（性能数据链接）