跑自己的模型不再难club-3090 BYO模型完整流程从Hugging Face仓库到验证服务【免费下载链接】club-3090Community recipes for serving LLMs on RTX 3090/4090/5090 CUDA gpus. Multi-engine (vLLM, llama.cpp, ik_llama) and model-agnostic. Currently shipping Qwen3.6-27B Qwen3.6 35B Gemma 4 26B Gemma 4 31B configs for 1× and 2× cards.项目地址: https://gitcode.com/gh_mirrors/cl/club-3090club-3090是一个面向 RTX 3090/4090/5090 显卡的社区项目提供多引擎vLLM、llama.cpp、ik_llama的本地大模型部署配方。它最大的特色之一是BYO 模型流程Bring Your Own Model自带模型无需修改官方目录就能把自己的 Hugging Face 仓库或 GGUF 权重跑起来、调优、验证甚至注册进本地目录——官方目录的整套质量门控脚本对你的模型同样适用。本文带你走一遍完整路径serve → tune → validate → catalog → share部署 → 调优 → 验证 → 编目 → 分享。核心文档见 docs/BRING_YOUR_OWN.md。 先搞懂BYO 流程和官方目录的关系一个关键认知BYO 模型住在官方注册表之外。因此launch.sh/switch.sh --list这类向导不会列出你的模型——它们只解析官方目录里的 slug。BYO 的正确姿势是用docker compose -f 你的compose up -d直接启动所有验证脚本通过端点驱动--url/MODEL/URL而不是注册表 slug。好消息是switch.sh --list依然有用——它帮你找出最接近的官方 compose 作为模板。 第 1 步把模型跑起来——三条路径按权重类型选路径 AHugging Face safetensors 仓库 →pull.sh一键评估这是最顺的路径。scripts/pull.sh 会在下载之前用本套件的 KV 数学评估你的模型能不能跑得下而且对结论的可信度非常诚实详见 docs/PULL.md# 只评估不下载、不启动 scripts/pull.sh org/Model --profile-like vllm/minimal --dry-run # 评估通过 → 下载权重 生成独立 compose scripts/pull.sh org/Model --profile-like vllm/minimal --out byo.yml --yes docker compose -f byo.yml up -d--profile-like是必选项用于借用官方配置的运行时形状引擎、KV 格式、张量并行度做容量评估单卡 vLLM 用vllm/minimalTP1双卡用vllm/dualTP2。⚠️ 两个注意点只支持 safetensorsGGUF 仓库会直接硬停——走路径 B首次评估Qwen2ForCausalLM等自定义代码架构的模型时会停在needs-trust-remote-code-ack门——检查仓库代码后加--trust-remote-code即可这是门控在工作不是故障。路径 B已有 GGUF 权重 → 复制最接近的 compose 模板先列出本机所有官方 compose 及其路径bash scripts/switch.sh --list挑一个与你的引擎 拓扑最接近的如 vLLM 双卡的vllm/dual、llama.cpp 双卡的llamacpp/tess-dual-mtp复制后指向你的文件即可env MODEL_DIR/path/to/your/models \ GGUF_FILErelative/path/to/your-model.gguf \ PORT8062 CTX_SIZE104000 CUDA_VISIBLE_DEVICES0 \ docker compose -f models/model/engine/compose/topology/quant/serving.yml up -d单卡/双卡编码在路径本身里single/或dual/不是参数——双卡版会自动把层切分到两张卡。路径 C微调 / abliterated 变体 → 直接复用官方 compose 换权重如果你的模型与某个官方模型架构相同比如 abliterated 的 Qwen3.6-27Bpull.sh会拒绝为它做通用派生——这是预期行为因为混合/MoE 架构需要官方手工调好的标志位mamba-cache-mode、MTP spec-config 等。此时不要派生复用官方 compose、只换权重注意三件事对齐对齐项说明权重格式 ↔ 引擎GGUF 只配 llama.cpp/ik-llama/beellamavLLM 只吃 safetensorsAutoRound/AWQ/GPTQ/fp8量化格式bf16 全权重塞不进 2×24 GB选与 compose--quantization匹配的预量化版本MTP 头双卡/max 配置用了内置 MTP 头需选-MTP变体或删掉--speculative-config这样你继承全部调好的参数——TP、KV dtype、chat template、工具解析器、MTP、上下文——只换权重路径。️ 第 2 步调优配置——用快速循环找真实上限第一次启动几乎不可能落在最优配置。用快速循环逐个变量调整把 2.5–3.5 小时的完整门控留到最后详见 docs/QUALITY_TEST.md脚本耗时回答的问题scripts/verify-full.sh~2 分钟能启动、能对话、工具调用、流式、思考模式都正常吗scripts/verify-stress.sh~5–10 分钟长上下文阶梯NIAH下会不会 OOM 卡死真实可填上限是多少scripts/bench.sh~3–5 分钟TPS 是多少3 次预热 5 次测量scripts/quality-test.sh--medium~25–30 分钟工具调用、指令遵循、结构化输出的行为质量过关吗MODELserved-name URLhttp://localhost:port bash scripts/verify-full.sh MODELserved-name URLhttp://localhost:port bash scripts/quality-test.sh --medium上下文别贪大。KV 缓存在启动时预分配CTX_SIZE设得太大高上下文请求会 OOM 卡死服务器——我们见过标称160K的配置在 ~125K 时死亡。verify-stress.sh的阶梯测试会报告真实可填上限和显存余量某个阶梯返回HTTP 0是 OOM 而非没记住该降CTX_SIZE重跑。单卡 24 GB 的显存预算长这样其他调优要点KV 量化llama.cpp 系可以 K/V 分别量化-ctk/-ctv非对称vLLM 是整块一个格式官方 INT8 KV 来自引擎补丁只随int8.yml提供。改完 KV 必须重跑 verify-stress quality--medium投机解码只在净墙钟 TPS提升时才值得开接受率 80% 不等于赢——始终和无投机基线对比A/B 纪律每个对照组用相同的 docker restart 固定等待至少 3 次运行功耗对齐——冷启动或低功耗的对照组会制造假回归。✅ 第 3 步完整验证——一条命令跑全部门控配置稳定后跑一次完整门控。它会串起 bench → verify-stress → 8 包质量测试思考关 思考开→ soak 长时稳定性测试bash scripts/rebench-full.sh \ --url http://localhost:port --model served-name \ --engine vllm|llama-cpp|sglang|other --tag your-tag这是2.5–3.5 小时的运行所以前面要用快速脚本调好再跑这一次--resume可跳过已完成步骤别忘了给每个脚本传MODELserved-name——它们默认是官方模型名传错会 404自己用调优循环就够了要贡献回上游完整rebench-full记录是必须的维护者会复现你的数字后才提升状态。跑完之后你的端点就有了可复现的性能基线效果大致如此 第 4 步注册进本地目录——让模型成为一等公民手动跑第 1 步能出服务但没有launch.sh发现、没有显存投影、没有守卫覆盖。scripts/catalog.sh 的LOCAL 层让你不碰任何一个被跟踪的文件就拥有全部能力bash scripts/catalog.sh register --compose ./my-compose.yml \ --engine my-llamacpp --engine-type llama.cpp \ --weights /path/to/model.gguf bash scripts/preflight-add-model.sh my-llamacpp/your-modelregister会机械读取你的 compose把能解析的都填上引擎、上下文、KV 格式、端口、权重路径……并且写盘前打印每个值标注(given)或(derived)——--dry-run可先看全计划。它有三个宁停勿猜的拒绝--engine镜像匹配不上任何官方引擎、--weightscompose 无法提供 hidden_size 等维度、--engine-type错误的值会静默失败。注册后本地 slug 与官方条目共享engine/name形状列表里带· local标记bash scripts/switch.sh --local # 只看你注册的模型 bash scripts/switch.sh --list --all # 全部条目你的会带 · local 标签本地层写在scripts/lib/profiles-local/整个目录被 gitignoregit pull永不冲突、官方目录不受影响、删掉文件即可完全回滚。两个必须知道的坑端口你的模型住在202xx 端口段官方目录占 8010–8199 且会增长挤进官方段会在后续更新里撞车⚠️一条命令毁掉整个本地层git clean -xdf——-x会连被忽略的文件一起删你注册的所有模型会静默消失且无法恢复。git clean -fd不带-x才是安全的。 第 5 步分享 / 贡献回上游本地层是贡献的暂存地不是死胡同。scripts/lib/profiles/export_pr.py 一条命令把你的本地模型导出成可直接提交 PR 的完整包模型 spec、转成核心布局的 compose、注册表条目python3 scripts/lib/profiles/export_pr.py --spec-file spec.json --check # 只校验 python3 scripts/lib/profiles/export_pr.py --spec-file spec.json --out ./bundle它只写--out目录、不碰仓库且会主动拒绝exit 3缺display_name/family、缺权重映射、缺 composeStatus:头这类会被维护者打回的问题——修好重跑即可。数字格式参考 docs/RESULTS_CARD.md贡献规范见 CONTRIBUTING.md一个模型或一个关注点一个 PR。 上手前的小贴士模型 ID 保持干净不带斜杠的 served-name如mymodel-q4能让沙箱质量包路由得更顺单卡长上下文慎入DeltaNet 类模型有 ~50–60K 的单提示 prefill 悬崖长上下文场景建议直接上双卡配置悬崖详解见 docs/CLIFFS.mdGGUF 用户pull.sh只认 safetensors 是设计边界不是 bug别在路径 A 上浪费排查时间想省事座舱c3 --contribute把这条流程包装成了 5 阶段漏斗Bring → Serve → Tune → Measure → Promote和手动脚本走的是同一套门控见 tools/serve-cockpit/README.md。 关键文档索引文档内容docs/BRING_YOUR_OWN.mdBYO 全流程权威指南本文依据docs/PULL.mdpull.sh 门控体系、置信度分层详解docs/ADDING_MODELS.md更重的路径把模型提升进官方目录docs/QUALITY_TEST.md8 包质量测试测什么、怎么读结果docs/CLIFFS.mdprefill / 累积上下文失效模式docs/SINGLE_CARD.md / docs/DUAL_CARD.md单卡 / 双卡工作负载选型scripts/verify-stress.shNIAH 阶梯、真实上下文上限探测scripts/rebench-full.sh完整验证门控入口从git clone https://gitcode.com/gh_mirrors/cl/club-3090到curl看到第一句回复再到你的模型带着完整质量报告进入目录——这条路上每一步都有脚本和文档托底。跑自己的模型真的不难。【免费下载链接】club-3090Community recipes for serving LLMs on RTX 3090/4090/5090 CUDA gpus. Multi-engine (vLLM, llama.cpp, ik_llama) and model-agnostic. Currently shipping Qwen3.6-27B Qwen3.6 35B Gemma 4 26B Gemma 4 31B configs for 1× and 2× cards.项目地址: https://gitcode.com/gh_mirrors/cl/club-3090创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考