[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-EricLBuehler--candle-vllm":3,"tool-EricLBuehler--candle-vllm":61},[4,18,26,36,44,53],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":17},4358,"openclaw","openclaw\u002Fopenclaw","OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。\n\n这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。\n\nOpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你",349277,3,"2026-04-06T06:32:30",[13,14,15,16],"Agent","开发框架","图像","数据工具","ready",{"id":19,"name":20,"github_repo":21,"description_zh":22,"stars":23,"difficulty_score":10,"last_commit_at":24,"category_tags":25,"status":17},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,"2026-04-05T11:01:52",[14,15,13],{"id":27,"name":28,"github_repo":29,"description_zh":30,"stars":31,"difficulty_score":32,"last_commit_at":33,"category_tags":34,"status":17},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",141543,2,"2026-04-06T11:32:54",[14,13,35],"语言模型",{"id":37,"name":38,"github_repo":39,"description_zh":40,"stars":41,"difficulty_score":32,"last_commit_at":42,"category_tags":43,"status":17},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",107888,"2026-04-06T11:32:50",[14,15,13],{"id":45,"name":46,"github_repo":47,"description_zh":48,"stars":49,"difficulty_score":32,"last_commit_at":50,"category_tags":51,"status":17},4721,"markitdown","microsoft\u002Fmarkitdown","MarkItDown 是一款由微软 AutoGen 团队打造的轻量级 Python 工具，专为将各类文件高效转换为 Markdown 格式而设计。它支持 PDF、Word、Excel、PPT、图片（含 OCR）、音频（含语音转录）、HTML 乃至 YouTube 链接等多种格式的解析，能够精准提取文档中的标题、列表、表格和链接等关键结构信息。\n\n在人工智能应用日益普及的今天，大语言模型（LLM）虽擅长处理文本，却难以直接读取复杂的二进制办公文档。MarkItDown 恰好解决了这一痛点，它将非结构化或半结构化的文件转化为模型“原生理解”且 Token 效率极高的 Markdown 格式，成为连接本地文件与 AI 分析 pipeline 的理想桥梁。此外，它还提供了 MCP（模型上下文协议）服务器，可无缝集成到 Claude Desktop 等 LLM 应用中。\n\n这款工具特别适合开发者、数据科学家及 AI 研究人员使用，尤其是那些需要构建文档检索增强生成（RAG）系统、进行批量文本分析或希望让 AI 助手直接“阅读”本地文件的用户。虽然生成的内容也具备一定可读性，但其核心优势在于为机器",93400,"2026-04-06T19:52:38",[52,14],"插件",{"id":54,"name":55,"github_repo":56,"description_zh":57,"stars":58,"difficulty_score":10,"last_commit_at":59,"category_tags":60,"status":17},4487,"LLMs-from-scratch","rasbt\u002FLLMs-from-scratch","LLMs-from-scratch 是一个基于 PyTorch 的开源教育项目，旨在引导用户从零开始一步步构建一个类似 ChatGPT 的大型语言模型（LLM）。它不仅是同名技术著作的官方代码库，更提供了一套完整的实践方案，涵盖模型开发、预训练及微调的全过程。\n\n该项目主要解决了大模型领域“黑盒化”的学习痛点。许多开发者虽能调用现成模型，却难以深入理解其内部架构与训练机制。通过亲手编写每一行核心代码，用户能够透彻掌握 Transformer 架构、注意力机制等关键原理，从而真正理解大模型是如何“思考”的。此外，项目还包含了加载大型预训练权重进行微调的代码，帮助用户将理论知识延伸至实际应用。\n\nLLMs-from-scratch 特别适合希望深入底层原理的 AI 开发者、研究人员以及计算机专业的学生。对于不满足于仅使用 API，而是渴望探究模型构建细节的技术人员而言，这是极佳的学习资源。其独特的技术亮点在于“循序渐进”的教学设计：将复杂的系统工程拆解为清晰的步骤，配合详细的图表与示例，让构建一个虽小但功能完备的大模型变得触手可及。无论你是想夯实理论基础，还是为未来研发更大规模的模型做准备",90106,"2026-04-06T11:19:32",[35,15,13,14],{"id":62,"github_repo":63,"name":64,"description_en":65,"description_zh":66,"ai_summary_zh":67,"readme_en":68,"readme_zh":69,"quickstart_zh":70,"use_case_zh":71,"hero_image_url":72,"owner_login":73,"owner_name":74,"owner_avatar_url":75,"owner_bio":76,"owner_company":77,"owner_location":77,"owner_email":77,"owner_twitter":77,"owner_website":77,"owner_url":78,"languages":79,"stars":96,"forks":97,"last_commit_at":98,"license":99,"difficulty_score":100,"env_os":101,"env_gpu":102,"env_ram":103,"env_deps":104,"category_tags":116,"github_topics":77,"view_count":32,"oss_zip_url":77,"oss_zip_packed_at":77,"status":17,"created_at":117,"updated_at":118,"faqs":119,"releases":149},4639,"EricLBuehler\u002Fcandle-vllm","candle-vllm","Efficent platform for inference and serving local LLMs including an OpenAI compatible API server.","candle-vllm 是一个专为本地大语言模型（LLM）打造的高效推理与服务平台。它旨在解决在消费级硬件或私有服务器上部署大模型时，常遇到的显存占用高、推理速度慢以及并发处理能力弱等痛点，让用户能轻松搭建兼容 OpenAI 接口的高性能本地服务。\n\n这款工具特别适合开发者、研究人员以及希望私有化部署 AI 能力的技术团队使用。其核心优势在于基于 Rust 语言构建，不仅运行稳定，更引入了多项前沿优化技术：通过 PagedAttention 机制高效管理显存，支持连续批处理（Continuous Batching）以提升多用户并发性能，并提供原位量化及 GPTQ\u002FMarlin 4-bit 量化支持，显著降低资源门槛。\n\n此外，candle-vllm 具备出色的跨平台兼容性，既支持 NVIDIA GPU 的多卡与多节点分布式推理，也能在 Apple Silicon（Mac）设备上流畅运行。它广泛适配 Llama、Qwen、Mistral、DeepSeek 等主流开源模型架构，并支持流式输出与工具调用协议。无论是进行模型算法研究，还是构建实际的生产级应用，candle-vllm 都能提供极","candle-vllm 是一个专为本地大语言模型（LLM）打造的高效推理与服务平台。它旨在解决在消费级硬件或私有服务器上部署大模型时，常遇到的显存占用高、推理速度慢以及并发处理能力弱等痛点，让用户能轻松搭建兼容 OpenAI 接口的高性能本地服务。\n\n这款工具特别适合开发者、研究人员以及希望私有化部署 AI 能力的技术团队使用。其核心优势在于基于 Rust 语言构建，不仅运行稳定，更引入了多项前沿优化技术：通过 PagedAttention 机制高效管理显存，支持连续批处理（Continuous Batching）以提升多用户并发性能，并提供原位量化及 GPTQ\u002FMarlin 4-bit 量化支持，显著降低资源门槛。\n\n此外，candle-vllm 具备出色的跨平台兼容性，既支持 NVIDIA GPU 的多卡与多节点分布式推理，也能在 Apple Silicon（Mac）设备上流畅运行。它广泛适配 Llama、Qwen、Mistral、DeepSeek 等主流开源模型架构，并支持流式输出与工具调用协议。无论是进行模型算法研究，还是构建实际的生产级应用，candle-vllm 都能提供极速且灵活的底层支撑。","\u003Cp align=\"center\">\n    \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FEricLBuehler_candle-vllm_readme_729cc7175365.png\" alt=\"candle vLLM\" width=55%\u002F>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\".\u002FREADME.md\">English\u003C\u002Fa> |\n  \u003Ca href=\".\u002FREADME-CN.md\">简体中文\u003C\u002Fa> |\n\u003C\u002Fp>\n\nEfficient, easy-to-use platform for inference and serving local LLMs including an OpenAI compatible API server.\n\n## Features\n- OpenAI compatible API server provided for serving LLMs.\n- Highly extensible trait-based system to allow rapid implementation of new module pipelines,\n- Streaming support in generation.\n- Efficient management of key-value cache with PagedAttention.\n- Continuous batching (batched decoding for incoming requests over time).\n- `In-situ` quantization (and `In-situ` marlin format conversion)\n- `GPTQ\u002FMarlin` format quantization (4-bit)\n- Support `Mac\u002FMetal` devices\n- Support `Multi-GPU` inference (both `multi-process` and  `multi-threaded` mode)\n- Support `Multi-node` inference with MPI runner\n- Support Chunked Prefilling (default chunk size 8K)\n- Support CUDA Graph\n- Support Model Context Protocol (MCP) and OpenAI-compatible tool calling\n- Support Prefix Caching\n- Support Block-wise FP8 Models (SM90+, Qwen3 Series)\n- Support Flashinfer Backend\n- Support manual YaRN RoPE scaling override from the command line via `--yarn-scaling-factor`\n\n## Supported Models\n- Currently, candle-vllm supports chat serving for the following model structures.\n  \u003Cdetails open>\n    \u003Csummary>Show supported model architectures\u003C\u002Fsummary>\n\n    | Model ID | Model Type | Decoding Speed \u002F Request (`BF16`, Hopper) | Quantized (`Q4K` or `Marlin`) |\n    |--|--|--|--|\n    | #1 | **LLAMA** |105 tks\u002Fs (8B) | 154 tks\u002Fs (8B, Q4k), 163 tks\u002Fs (8B, **Marlin**) |\n    | #2 | **Mistral** |112 tks\u002Fs (7B)| 171 tks\u002Fs (7B, Q4k), 175 tks\u002Fs (7B, **Marlin**) |\n    | #3 | **Phi3\u002FPhi4** |139 tks\u002Fs (3.8B)|180 tks\u002Fs (3.8B, Q4k)|\n    | #4 | **QWen2\u002FQwen3 Dense** |96 tks\u002Fs (8B)|135 tks\u002Fs **(8B, Q4k)**|\n    | #5 | **QWen3 MoE** |92 tks\u002Fs **(30B)**|114 tks\u002Fs **(30B, Q4K)** |\n    | #6 | **QWen3-Next MoE** |71 tks\u002Fs **(80B, BF16, tp=2)**|TBD|\n    | #7 | **QWen3.5 Dense** |30 tks\u002Fs **(27B, BF16)**|~42 tks\u002Fs **(27B, Q4K \u002F FP8)** |\n    | #8 | **QWen3.5 MoE** |82 tks\u002Fs **(35B)**|93 tks\u002Fs **(35B, Q4K)** |\n    | #9 | **Yi** |148 tks\u002Fs (6B)| 180 tks\u002Fs (6B, Q4k)|\n    | #10 | **StableLM** |223 tks\u002Fs (3B)|-|\n    | #11 | **Gemma-2\u002FGemma-3** |92 tks\u002Fs (9B)|115 tks\u002Fs (9B, **Marlin**)|\n    | #12 | **DeepSeek V2\u002FV3\u002FR1** |TBD|~20 tks **(AWQ 671B, tp=8, offloading)**|\n    | #13 | **QwQ-32B** |45 tks\u002Fs **(32B, tp=2)**|63 tks\u002Fs **(32B, Q4K)**|\n    | #14 | **GLM4** |89 tks\u002Fs **(9B)**|124 tks\u002Fs **(9B, Q4K)**|\n  \u003C\u002Fdetails>\n\n### Demo Video\n- Nvidia GPU and Apple Silicon\n\n  \u003Cdetails>\n    \u003Csummary>Show Demo Video\u003C\u002Fsummary>\n    Chat demo on **GPU** (A100, BF16, QWen3-8B Reasoning Model)\n    \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FEricLBuehler_candle-vllm_readme_4d71b67badfd.gif\" width=\"85%\" height=\"85%\" >\n\n    Chat demo on **Apple Silicon** (M4 with 16GB unified memory, Q2K, QWen3-8B)\n    \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FEricLBuehler_candle-vllm_readme_d836b1d4d7c1.gif\" width=\"85%\" height=\"85%\" >\n  \u003C\u002Fdetails>\n\n## General Usage\n### Install Candle-vLLM\n\n**Clone code**\n```shell\ngit clone git@github.com:EricLBuehler\u002Fcandle-vllm.git\ncd candle-vllm\n```\n\n**CUDA (CUDA 11+, 12+, 13.0)**\n > Option 1 (Install into docker)\n```bash\n# Host driver version must >= specified cuda version, `flashattn` and `flashinfer` take longer time to build\n# Change `sm_80` to your hardware spec, e.g., sm_75 (V100), sm_80 (Ampere, A100), sm_86\u002F89 (RTX30xx, RTX40xx), sm_90 (Hopper, H100\u002FH200), sm_100\u002Fsm_120 (Blackwell, RTX50xx). \n.\u002Fbuild_docker.sh \"cuda,nccl,graph,flashinfer,cutlass\" sm_90 13.0.0\n\n# Or switch to Flash attention backend, or use Rust crate China Mirror (used in Chinese Mainland)\n.\u002Fbuild_docker.sh \"cuda,nccl,graph,flashattn,cutlass\" sm_80 12.9.0 1\n```\n\n > Option 2 (Manual Installation)\n\nInstall dependencies\n```shell\nsudo apt update\n# Install CUDA toolkit (optional)\nsudo apt install git libssl-dev pkg-config curl -y\nsudo apt install -y cuda-toolkit-12-9 # must \u003C= host driver version\n# Install rust, 1.83.0+ required\ncurl --proto '=https' --tlsv1.2 -sSf https:\u002F\u002Fsh.rustup.rs | sh\n\n# Make sure the CUDA Toolkit can be found in the system PATH\nexport PATH=$PATH:\u002Fusr\u002Flocal\u002Fcuda\u002Fbin\u002F\n```\n\nInstall for single node inference\n```shell\n# Remove \"flashattn,flashinfer,cutlass\" for sm_75 and sm_70\n# Replace `flashinfer` with `flashattn` to use Flash attention backend\ncargo install --features cuda,nccl,graph,flashinfer,cutlass --path .\n```\n\nInstall for multinode inference\n```shell\n# Use MPI (multi-gpus on multiple machines)\nsudo apt install libopenmpi-dev openmpi-bin -y #install mpi\nsudo apt install clang libclang-dev\ncargo install --features cuda,nccl,graph,flashattn,cutlass,mpi --path .\n\n# FlashInfer backend\ncargo install --features cuda,nccl,graph,flashinfer,cutlass,mpi --path .\n```\n\n**Mac\u002FMetal (single-node only)**\n\nInstall [Xcode command line tools](https:\u002F\u002Fmac.install.guide\u002Fcommandlinetools\u002F)\n\nInstall with `metal` feature\n```shell\ncargo install --features metal --path .\n```\n\n### Run Directly (Without installation)\n\n- [`ENV_PARAM`] cargo run [`BUILD_PARAM`] -- [`PROGRAM_PARAM`] [`MODEL_ID\u002FMODEL_WEIGHT_PATH`] [`CACHE CONFIG`] [`WEB UI`]\n  \u003Cdetails open>\n    \u003Csummary>Show details\u003C\u002Fsummary>\n\n    **Example:**\n\n    ```shell\n    [RUST_LOG=warn] cargo run [--release --features cuda,nccl,flashinfer,cutlass,graph] -- [--log --dtype bf16 --p 2000 --d 0,1 --gpu-memory-fraction 0.7 --isq q4k --prefill-chunk-size 8192 --frequency-penalty 1.1 --presence-penalty 1.1 --enforce-parser qwen_coder --yarn-scaling-factor 4.0] [--m Qwen\u002FQwen3.5-27B-FP8] [--fp8-kvcache] [--ui-server]\n    ```\n\n    `ENV_PARAM`: RUST_LOG=warn\n\n    `BUILD_PARAM`: --release --features cuda,nccl,flashinfer,cutlass,graph\n\n    `PROGRAM_PARAM`：--log --dtype bf16 --p 2000 --d 0,1 --gpu-memory-fraction 0.7 --isq q4k --prefill-chunk-size 8192 --frequency-penalty 1.1 --presence-penalty 1.1 --enforce-parser qwen_coder --yarn-scaling-factor 4.0\n\n    `MODEL_ID\u002FMODEL_WEIGHT_PATH`: --m Qwen\u002FQwen3.5-27B-FP8 (or `--w` specify local model path)\n\n    `CACHE CONFIG`: --fp8-kvcache\n\n    `WEB UI`: --ui-server\n\n    where, `--p`: server port; `--d`: device ids; `--w`: weight path (safetensors folder); `--f`: weight file (for gguf); `--m`: huggingface model-id; `--isq q4k`: convert weights into `q4k` format during model loading; `--prefill-chunk-size` chunk the prefill into size defined in this flag (default 8K, `0` for disable); `--frequency-penalty` and `--presence-penalty` repetition penalty (value from -2.0 to 2.0); `--mem` (`kvcache-mem-gpu`) sets a fixed KV cache budget in MB; `--gpu-memory-fraction` auto-sizes KV cache after model load using `fraction * remaining_gpu_memory`; `--enforce-parser` forces a specific tool parser backend such as `qwen_coder`, `qwen`, `json`, or `mistral`; `--yarn-scaling-factor` manually injects a YaRN RoPE scaling factor such as `4.0` to extend the effective context window for supported models; `--fp8-kvcache` used to enable fp8 kvcache; `--prefix-cache` enable prefix cache reuse; `--prefix-cache-max-tokens` cap prefix cache size; `--ui-server` start with a built-in ChatGPT-like Web UI sever. Replace `flashinfer` in `BUILD_PARAM` with `flashattn` to use the Flash attention backend instead.\n  \u003C\u002Fdetails>\n\n## 📚 Docs\n- [Rust Crate Usage](docs\u002Frust_crate.md)\n- [Embedding Model Usage](docs\u002Fembedding.md)\n- [MCP & Tool Calling](docs\u002Fmcp_tool_calling.md)\n- [Tool Call Parsing](docs\u002Ftool_parsing.md)\n- [Prefix Cache](docs\u002Fprefix_cache.md)\n- [Multimodal Model Usage](docs\u002Fmultimodal.md)\n- [Work with OpenCode](docs\u002Fopencode.md)\n- [Work with Kilo Code](docs\u002Fkilocode.md)\n\n## How to serve models?\n\n- **Note:** for docker build, execute the following command to enter docker:\n\n```shell\ndocker run --rm -it --gpus all --network host -v \u002Fhome:\u002Fhome -v \u002Fdata:\u002Fdata candle-vllm:latest bash\n```\n\n- Run **Uncompressed** models \n  \u003Cdetails open>\n    \u003Csummary>Show command\u003C\u002Fsummary>\n\n    **Local Path (with port, device)**\n    ```shell\n    candle-vllm --p 8000 --d 0,1 --w \u002Fhome\u002FQwen3-30B-A3B-Instruct-2507\u002F --prefix-cache\n    ```\n\n    **Local Path (ISQ, +UI Server)**\n    ```shell\n    candle-vllm --p 8000 --d 0,1 --w \u002Fhome\u002FQwen3.5-27B\u002F --isq q4k --ui-server --prefix-cache\n    ```\n\n    **Model-ID (download from Huggingface)**\n\n    ```shell\n    candle-vllm --m Qwen\u002FQwen3.5-35B-A3B --ui-server --prefix-cache\n    ```\n\n    **Manual YaRN scaling**\n    ```shell\n    candle-vllm --m Qwen\u002FQwen3.5-35B-A3B --yarn-scaling-factor 4.0 --ui-server --prefix-cache\n    ```\n\n    **FP8 Model** (block-wise quant, build with `cutlass` feature)\n    ```shell\n    candle-vllm --m Qwen\u002FQwen3.5-27B-FP8 --ui-server --prefix-cache\n    ```\n\n    ```shell\n     # MacOS\u002FMetal (Dense)\n    candle-vllm --m Qwen\u002FQwen3-4B-Instruct-2507-FP8 --ui-server --prefix-cache\n    ```\n  \u003C\u002Fdetails>\n\n- Run **GGUF** models \n  \u003Cdetails open>\n    \u003Csummary>Show command\u003C\u002Fsummary>\n\n    **Local Path**\n\n    ```shell\n    candle-vllm --f \u002Fhome\u002Fdata\u002FQwen3-30B-A3B-Instruct-2507-Q4_K_M.gguf --ui-server\n    ```\n\n    **Model-ID (download from Huggingface)**\n\n    ```shell\n    candle-vllm --m unsloth\u002FQwen3-30B-A3B-Instruct-2507-GGUF --f Qwen3-30B-A3B-Instruct-2507-Q4_K_M.gguf --ui-server\n    ```\n\n  \u003C\u002Fdetails>\n\n- Run **GGUF** models on **Apple Silicon**\n  \u003Cdetails>\n    \u003Csummary>Show command\u003C\u002Fsummary>\n\n    **Local Path (assume model downloaded in \u002Fhome)**\n\n    ```shell\n    candle-vllm --f \u002Fhome\u002Fqwq-32b-q4_k_m.gguf --ui-server\n    ```\n\n    **Model-ID (download from Huggingface)**\n\n    ```shell\n    candle-vllm --m Qwen\u002FQwQ-32B-GGUF --f qwq-32b-q4_k_m.gguf --ui-server\n    ```\n\n  \u003C\u002Fdetails>\n\n- Run **Any uncompressed models as quantized with in-situ quantization**\n  \u003Cdetails>\n    \u003Csummary>Show command\u003C\u002Fsummary>\n\n    **Simply add `isq` parameter when running unquantized models**\n\n    ```shell\n    candle-vllm --p 2000 --m Qwen\u002FQwen3.5-27B --isq q4k\n    ```\n\n    Options for in-site `isq` parameters: [\"q4_0\", \"q4_1\", \"q5_0\", \"q5_1\", \"q8_0\", \"q2k\", \"q3k\",\"q4k\",\"q5k\",\"q6k\"]\n\n  \u003C\u002Fdetails>\n\n- Run **Marlin-compatible GPTQ models** models (4-bit GPTQ, 128-group, desc_act=False)\n  \u003Cdetails>\n    \u003Csummary>Show command\u003C\u002Fsummary>\n\n    **Local Path**\n\n    ```shell\n    candle-vllm --w \u002Fhome\u002FDeepSeek-R1-Distill-Qwen-14B-GPTQ_4bit-128g\n    ```\n\n    **Model-ID (download from Huggingface)**\n\n    ```shell\n    candle-vllm --m thesven\u002FLlama-3-8B-GPTQ-4bit\n    ```\n\n    **Convert Any uncompressed model to marlin-compatible format**\n    ```shell\n    python3 examples\u002Fconvert_marlin.py --src \u002Fhome\u002FDeepSeek-R1-Distill-Qwen-14B\u002F --dst \u002Fhome\u002FDeepSeek-R1-Distill-Qwen-14B-GPTQ_4bit-128g\n    candle-vllm --w \u002Fhome\u002FDeepSeek-R1-Distill-Qwen-14B-GPTQ_4bit-128g\n    ```\n\n  \u003C\u002Fdetails>\n\n- Run **Marlin-compatible AWQ models** models\n  \u003Cdetails>\n    \u003Csummary>Show command\u003C\u002Fsummary>\n\n    **Convert AWQ model to Marlin-compatible format**\n    ```shell\n    python3 examples\u002Fconvert_awq_marlin.py --src \u002Fhome\u002FMeta-Llama-3.1-8B-Instruct-AWQ-INT4\u002F --dst \u002Fhome\u002FMeta-Llama-3.1-8B-Instruct-AWQ-INT4-Marlin\u002F --bits 4 --method awq --group 128 --nk False\n    ```\n\n    **Run the converted AWQ model**\n    ```shell\n    candle-vllm --d 0 --w \u002Fhome\u002FMeta-Llama-3.1-8B-Instruct-AWQ-INT4-Marlin\u002F\n    ```\n\n  \u003C\u002Fdetails>\n\n- Run **Marlin-format** models\n  \u003Cdetails>\n    \u003Csummary>Show command\u003C\u002Fsummary>\n\n    ```shell\n    candle-vllm --w \u002Fhome\u002FDeepSeek-R1-Distill-Qwen-14B-GPTQ-Marlin\u002F\n    ```\n\n  \u003C\u002Fdetails>\n\n\n- Run **Large models using multi-process mode (Multi-GPU)**\n  \u003Cdetails>\n    \u003Csummary>Show command\u003C\u002Fsummary>\n\n    **QwQ-32B BF16 model on two GPUs**\n    ```shell\n    candle-vllm --d 0,1 --w \u002Fhome\u002FQwQ-32B\u002F\n    ```\n\n    **QwQ-32B 4-bit AWQ model on two GPUs**\n\n    1) Convert AWQ model to Marlin-compatible format\n    ```shell\n    python3 examples\u002Fconvert_awq_marlin.py --src \u002Fhome\u002FQwQ-32B-AWQ\u002F --dst \u002Fhome\u002FQwQ-32B-AWQ-Marlin\u002F --bits 4 --method awq --group 128 --nk False\n    ```\n\n    2) Run the converted AWQ model\n    ```shell\n    candle-vllm --d 0,1 --w \u002Fhome\u002FQwQ-32B-AWQ-Marlin\u002F\n    ```\n\n    **Note:** number of GPUs (`--d`) used must be aligned to 2^n (e.g., 2, 4, or 8).\n  \u003C\u002Fdetails>\n\n- Run **Large models using multi-threaded mode (Multi-GPU, for debug purpose)**\n  \u003Cdetails>\n    \u003Csummary>Show command\u003C\u002Fsummary>\n\n    Simply add the `--multithread` parameter\n\n    **QwQ-32B BF16 model on two GPUs**\n    ```shell\n    candle-vllm --multithread --d 0,1 --w \u002Fhome\u002FQwQ-32B\u002F\n    ```\n\n    If you encountered problems under Multi-threaded Multi-GPU mode, you may:\n    ```shell\n    export NCCL_P2P_DISABLE=1 # disable p2p cause this feature can cause illegal memory access in certain environments\n    ```\n\n  \u003C\u002Fdetails>\n\n- Run **DeepSeek-R1 (671B\u002F685B) on Lower GPU Memories (CPU offloading)**\n  \u003Cdetails>\n    \u003Csummary>Show command\u003C\u002Fsummary>\n\n    **1. Convert DeepSeek-R1-AWQ model to Marlin-compatible format**\n    ```shell\n    python3 examples\u002Fconvert_awq_marlin.py --src \u002Fdata\u002FDeepSeek-R1-AWQ\u002F --dst \u002Fdata\u002FDeepSeek-R1-AWQ-Marlin\u002F \n    ```\n\n    **2. Run DeepSeek-R1 model on 8 x A100(40GB)**\n    ```shell\n    candle-vllm --log --d 0,1,2,3,4,5,6,7 --w \u002Fdata\u002FDeepSeek-R1-AWQ-Marlin\u002F--num-experts-offload-per-rank 15\n    ```\n\n    **Note:** This setup offloads 15 experts per rank (a total of 120 out of 256 experts) to the CPU (around 150GB additional host memory required). During inference, these offloaded experts are swapped back into GPU memory as needed. If you have even less GPU memory, consider increasing the `--num-experts-offload-per-rank` parameter (up to a maximum of 32 experts per rank in this case).\n\n  \u003C\u002Fdetails>\n\n- Run **DeepSeek-R1 (671B\u002F685B) on Multi-node**\n  \u003Cdetails>\n    \u003Csummary>Show command\u003C\u002Fsummary>\n\n    **1. Install MPI and build with MPI feature**\n    ```shell\n    sudo apt update\n    sudo apt install libopenmpi-dev openmpi-bin -y #install mpi\n    sudo apt install clang libclang-dev\n    #clone the repo on the same directory of the two node and build\n    cargo install --features cuda,nccl,mpi #build with mpi feature\n    ```\n\n    **2. Convert AWQ deepseek to Marlin-compatible format**\n    ```shell\n    python3 examples\u002Fconvert_awq_marlin.py --src \u002Fdata\u002FDeepSeek-R1-AWQ\u002F --dst \u002Fdata\u002FDeepSeek-R1-AWQ-Marlin\u002F \n    ```\n\n    **3. Config Multi-node Environment**\n\n    MPI Runner requires `identical` hardware and software configurations for all nodes, please ensure weights and candle-vllm binaries located in the identical folders in difference nodes. The the nodes need to be ssh (port 22 in this case) passwordless for each other (root user if `--allow-run-as-root`). `%NET_INTERFACE%` is the active network interface obtained through command 'ifconfig -a'. You may disable InfiniBand if it's not available in the nodes by insert env \"-x NCCL_IB_DISABLE=1\". Where, `hostfile` can be defined as:\n\n    Example (two nodes, each with 8 GPUs)\n    ```\n    192.168.1.100 slots=8\n    192.168.1.101 slots=8\n    ```\n\n    **4. Run the model on two nodes with MPI runner**\n    ```shell\n    sudo mpirun -np 16 -x RUST_LOG=info -hostfile .\u002Fhostfile --allow-run-as-root -bind-to none -map-by slot --mca plm_rsh_args \"-p 22\" --mca btl_tcp_if_include %NET_INTERFACE% candle-vllm --log --d 0,1,2,3,4,5,6,7 --w \u002Fdata\u002FDeepSeek-R1-AWQ-Marlin\u002F\n    ```\n  \u003C\u002Fdetails>\n\n- Run with **NUMA binding**\n  \u003Cdetails>\n    \u003Csummary>Show command\u003C\u002Fsummary>\n\n    **Prerequisite**\n    Ensure your machine has more than one NUMA node (i.e., more than one physical CPU), and install numactl:\n    ```shell\n    sudo apt-get install numactl\n    ```\n\n    Suppose your machine has 8 GPUs and 2 NUMA nodes, with each set of 4 GPUs bound to a different NUMA node.\n    To achieve optimal performance during inference using all GPUs, use the following NUMA binding:\n\n    ```shell\n    MAP_NUMA_NODE=0,0,0,0,1,1,1,1 numactl --cpunodebind=0 --membind=0 candle-vllm --d 0,1,2,3,4,5,6,7 --w \u002Fhome\u002Fdata\u002FDeepSeek-V2-Chat-AWQ-Marlin\n    ```\n\n    To use only 4 GPUs, you can apply this NUMA binding:\n    \n    ```shell\n    MAP_NUMA_NODE=0,0,0,0 numactl --cpunodebind=0 --membind=0 candle-vllm --d 0,1,2,3 --w \u002Fhome\u002Fdata\u002FDeepSeek-V2-Chat-AWQ-Marlin\n    ```\n    *where* `numactl --cpunodebind=0 --membind=0` above indicates NUMA binding for the master rank (master process) which should be matched to `MAP_NUMA_NODE`.\n\n    Note: The exact NUMA binding sequence may vary depending on your hardware configuration.\n  \u003C\u002Fdetails>\n\n## How to send request(s) to the backend?\n\n**Run chat frontend after starting the backend service**\n\nChat frontend (any frontend compatible with openai API, simple options available below):\n\n- **Option 1: Chat with Chat.py (for simple tests)**\n  \u003Cdetails>\n    \u003Csummary>Show Option 1\u003C\u002Fsummary>\n    \n    Install API and chatbot dependencies (openai package is only used for local chat with candle-vllm)\n\n    ```shell\n    python3 -m pip install openai rich click\n    ```\n\n    Chat with the mini chatbot (plain text)\n    ```shell\n    python3 examples\u002Fchat.py\n    ```\n\n    Pass generation parameters (to reasoning models with `--thinking True`)\n    ```shell\n    python3 examples\u002Fchat.py --temperature 0.7 --top_k 64 --top_p 0.9 --thinking True --system_prompt \"Thinking big!\"\n    ```\n\n    Chat with the mini chatbot (live update with Markdown, may cause flick)\n    ```shell\n    python3 examples\u002Fchat.py --live\n    ```\n  \u003Cdetails>\n\n- **Option 2: Chat with naive ChatUI (or popular dify frontend)**\n  \u003Cdetails>\n    \u003Csummary>Show Option 2\u003C\u002Fsummary>\n\n    Install naive ChatUI and its dependencies:\n\n    ```\n    git clone git@github.com:guoqingbao\u002Fcandle-vllm-demo.git\n    cd candle-vllm-demo\n    apt install npm #install npm if needed\n    npm install n -g #update node js if needed\n    n stable #update node js if needed\n    npm i -g pnpm #install pnpm manager\n    pnpm install #install ChatUI dependencies\n    ```\n\n    Launching the ChatUI:\n    ```\n    pnpm run dev # run the ChatUI\n    ```\n\n    **Trouble shooting for Nodejs error**\n    `ENOSPC: System limit for number of file watchers reached`\n    ```\n    echo fs.inotify.max_user_watches=524288 | sudo tee -a \u002Fetc\u002Fsysctl.conf && sudo sysctl -p\n    ```\n  \u003C\u002Fdetails>\n\n- **Option 3: Chat completion request with HTTP post**\n  \u003Cdetails>\n    \u003Csummary>Show Option 3\u003C\u002Fsummary>\n\n    ``` shell\n    curl -X POST \"http:\u002F\u002F127.0.0.1:2000\u002Fv1\u002Fchat\u002Fcompletions\" \\\n        -H \"Content-Type: application\u002Fjson\" \\\n        -H \"Authorization: Bearer YOUR_API_KEY\" \\\n        -d '{\n            \"model\": \"llama7b\",\n            \"messages\": [\n                {\"role\": \"user\", \"content\": \"Explain how to best learn Rust.\"}\n            ],\n            \"temperature\": 0.7,\n            \"max_tokens\": 128,\n            \"stop\": {\"Single\":\"\u003C\u002Fs>\"}\n        }'\n    ```\n    Sample response:\n\n    ```\n    {\"id\":\"cmpl-53092967-c9cf-40e0-ae26-d7ac786d59e8\",\"choices\":[{\"message\":{\"content\":\" Learning any programming language requires a combination of theory, practice, and dedication. Here are some steps and resources to help you learn Rust effectively:\\n\\n1. Start with the basics:\\n\\t* Understand the syntax and basic structure of Rust programs.\\n\\t* Learn about variables, data types, loops, and control structures.\\n\\t* Familiarize yourself with Rust's ownership system and borrowing mechanism.\\n2. Read the Rust book:\\n\\t* The Rust book is an official resource that provides a comprehensive introduction to the language.\\n\\t* It covers topics such\",\"role\":\"[INST]\"},\"finish_reason\":\"length\",\"index\":0,\"logprobs\":null}],\"created\":1718784498,\"model\":\"llama7b\",\"object\":\"chat.completion\",\"usage\":{\"completion_tokens\":129,\"prompt_tokens\":29,\"total_tokens\":158}}\n    ```\n  \u003C\u002Fdetails>\n\n- **Option 4: Chat completion with with openai package**\n  \u003Cdetails>\n    \u003Csummary>Show Option 4\u003C\u002Fsummary>\n\n    In your terminal, install the `openai` Python package by running `pip install openai`. I use version `1.3.5`.\n\n    Then, create a new Python file and write the following code:\n    ```python\n    import openai\n\n    openai.api_key = \"EMPTY\"\n\n    openai.base_url = \"http:\u002F\u002Flocalhost:2000\u002Fv1\u002F\"\n\n    completion = openai.chat.completions.create(\n        model=\"llama\",\n        messages=[\n            {\n                \"role\": \"user\",\n                \"content\": \"Explain how to best learn Rust.\",\n            },\n        ],\n        max_tokens = 64,\n    )\n    print(completion.choices[0].message.content)\n    ```\n    After the `candle-vllm` service is running, run the Python script and enjoy efficient inference with an OpenAI compatible API server!\n\n\n    **Batched requests**\n\n    Install openai API first\n    ```\n    python3 -m pip install openai\n    ```\n\n    Run the benchmark test\n    ``` shell\n    python3 examples\u002Fbenchmark.py --batch 16 --max_tokens 1024\n    ```\n    Refer to `examples\u002Fbenchmark.py`\n\n    ``` python\n    async def benchmark():\n        model = \"mistral7b\"\n        max_tokens = 1024\n        # 16 requests\n        prompts = [\"Explain how to best learn Rust.\", \n                \"Please talk about deep learning in 100 words.\", \n                \"Do you know the capital city of China? Talk the details of you known.\", \n                \"Who is the best female actor in the world? Explain why.\",\n                \"How to dealing with depression?\",\n                \"How to make money in short time?\",\n                \"What is the future trend of large language model?\",\n                \"The famous tech companies in the world.\",\n                \"Explain how to best learn Rust.\", \n                \"Please talk about deep learning in 100 words.\", \n                \"Do you know the capital city of China? Talk the details of you known.\", \n                \"Who is the best female actor in the world? Explain why.\",\n                \"How to dealing with depression?\",\n                \"How to make money in short time?\",\n                \"What is the future trend of large language model?\",\n                \"The famous tech companies in the world.\"]\n        \n        # send 16 chat requests at the same time\n        tasks: List[asyncio.Task] = []\n        for i in range(len(prompts)):\n            tasks.append(\n                asyncio.create_task(\n                    chat_completion(model, max_tokens, prompts[i]))\n            )\n\n        # obtain the corresponding stream object for each request\n        outputs: List[Stream[ChatCompletionChunk]] = await asyncio.gather(*tasks)\n\n        # tasks for streaming chat responses\n        tasks_stream: List[asyncio.Task] = []\n        for i in range(len(outputs)):\n            tasks_stream.append(\n                asyncio.create_task(\n                    stream_response(i, outputs[i]))\n            )\n\n        # gathering the response texts\n        outputs: List[(int, str)] = await asyncio.gather(*tasks_stream)\n\n        # print the results, you may find chat completion statistics in the backend server (i.e., candle-vllm)\n        for idx, output in outputs:\n            print(\"\\n\\n Response {}: \\n\\n {}\".format(idx, output))\n\n    asyncio.run(benchmark())\n    ```\n  \u003C\u002Fdetails>\n\n## In-situ quantization\n- **Loading unquantized models as gguf quantized or marlin format**\n  \u003Cdetails>\n    \u003Csummary>Show quantization config\u003C\u002Fsummary>\n\n    Candle-vllm supports in-situ quantization, allowing the transformation of default weights (F32\u002FF16\u002FBF16) into any GGML\u002FGGUF format, or `4-bit GPTQ\u002FAWQ` weights into `marlin format` during model loading. This feature helps conserve GPU memory and speedup inference performance, making it more efficient for consumer-grade GPUs (e.g., RTX 4090). To use this feature, simply supply the `isq` parameter when running candle-vllm.\n\n    **For unquantized models:**\n\n    ```\n    candle-vllm --p 2000 --w \u002Fhome\u002FMeta-Llama-3.1-8B-Instruct\u002F --isq q4k\n    ```\n\n    Options for `isq` parameters: [\"q4_0\", \"q4_1\", \"q5_0\", \"q5_1\", \"q8_0\", \"q2k\", \"q3k\",\"q4k\",\"q5k\",\"q6k\"]\n\n    **For quantized 4-bit GPTQ model:**\n\n    ```\n    candle-vllm --p 2000 --w \u002Fhome\u002Fmistral_7b-int4\u002F\n    ```\n\n    **Please note for marlin**:\n\n    1) It may takes few minutes to load F32\u002FF16\u002FBF16 models into quantized;\n\n    2) Marlin format in-situ conversion only support 4-bit GPTQ (with `sym=True`, `groupsize=128` or -1, `desc_act=False`) and 4-bit AWQ (after conversion using the given script, refer to `Other Usage`);\n\n    3) Marlin format only supported in CUDA platform.\n  \u003C\u002Fdetails>\n\n## Other Usage\n- KV Cache config, sampling parameter, etc.\n  \u003Cdetails>\n    \u003Csummary>Show details\u003C\u002Fsummary>\n    The `--mem` (`kvcache-mem-gpu`) parameter sets a fixed KV cache budget in MB. By default this is `4096` MB.\n\n    The `--gpu-memory-fraction` parameter is a lighter-weight auto mode. When omitted, it defaults to `0.7`. After the model finishes loading, candle-vllm probes each loaded CUDA or Metal device and computes the KV cache budget as:\n\n    ```\n    gpu_memory_fraction * remaining_gpu_memory_after_model_load\n    ```\n\n    This means the fraction directly controls how much of the free GPU memory left after model load can be used for the combined GPU cache budget. The minimum detected budget across ranks is used as the KV cache budget per rank. For example:\n\n    ```\n    candle-vllm --w \u002Fhome\u002FQwen3-Coder-30B-A3B-Instruct-FP8 --d 0,1 --gpu-memory-fraction 0.7\n    ```\n\n    Use `--mem` when you want an explicit fixed budget. Use `--gpu-memory-fraction` when you want the server to adapt to the currently available GPU memory after model load.\n\n    The `--enforce-parser` parameter forces a specific tool-calling parser backend instead of the model-based default selection. This is useful when a model is compatible with a parser but does not get auto-detected correctly. Common values are `qwen_coder`, `qwen`, `json`, and `mistral`. For example:\n\n    ```\n    candle-vllm --w \u002Fhome\u002FQwen3-Coder-30B-A3B-Instruct-FP8 --enforce-parser qwen_coder\n    ```\n\n    Invalid parser names are rejected at startup.\n\n    For chat history settings, set `record_conversation` to `true` to let candle-vllm remember chat history. By `default`, candle-vllm `does not` record chat history; instead, the client sends both the messages and the contextual history to candle-vllm. If record_conversation is set to `true`, the client sends only new chat messages to candle-vllm, and candle-vllm is responsible for recording the previous chat messages. However, this approach requires per-session chat recording, which is not yet implemented, so the default approach `record_conversation=false` is recommended.\n\n    For chat streaming, the `stream` flag in chat request need to be set to `True`.\n\n    ```\n    candle-vllm --p 2000 --w \u002Fhome\u002Fmistral_7b\u002F\n    ```\n\n    `--max-gen-tokens` parameter is used to control the maximum output tokens per chat response. The value will be set to 1\u002F5 of max_sequence_len by default.\n\n    For `consumer GPUs`, it is suggested to run the models under GGML formats (or Marlin format), e.g.,\n\n    ```\n    candle-vllm --p 2000 --w \u002Fhome\u002FMeta-Llama-3.1-8B-Instruct\u002F --isq q4k\n    ```\n\n    where `isq` is one of [\"q4_0\", \"q4_1\", \"q5_0\", \"q5_1\", \"q8_0\", \"q2k\", \"q3k\",\"q4k\",\"q5k\",\"q6k\", \"awq\", \"gptq\", \"marlin\", \"gguf\", \"ggml\"].\n  \u003C\u002Fdetails>\n\n- **Use Marlin kernel to speedup GPTQ\u002FAWQ models**\n  \u003Cdetails>\n    \u003Csummary>Show details\u003C\u002Fsummary>\n\n    Candle-vllm now supports GPTQ\u002FAWQ Marlin kernel, you can run these models directly, such as:\n\n    ```shell\n    candle-vllm --dtype f16 --w \u002Fhome\u002FMeta-Llama-3.1-8B-Instruct-GPTQ-INT4-Marlin\u002F\n    ```\n\n    or, convert existing AWQ 4bit model to marlin compatible format\n\n    ```shell\n    python3 examples\u002Fconvert_awq_marlin.py --src \u002Fhome\u002FMeta-Llama-3.1-8B-Instruct-AWQ-INT4\u002F --dst \u002Fhome\u002FMeta-Llama-3.1-8B-Instruct-AWQ-INT4-Marlin\u002F --bits 4 --method awq --group 128 --nk False\n    candle-vllm --dtype f16 --d 0 --w \u002Fhome\u002FMeta-Llama-3.1-8B-Instruct-AWQ-INT4-Marlin\u002F\n    ```\n\n    You may also use `GPTQModel` to transform a model to marlin-compatible format using the given script `examples\u002Fconvert_marlin.py`. \n\n    **Note:** for using Marlin fast kernel, only 4-bit GPTQ quantization supported at the moment. \n  \u003C\u002Fdetails>\n\n## Report issue\nInstalling `candle-vllm` is as simple as the following steps. If you have any problems, please create an\n[issue](https:\u002F\u002Fgithub.com\u002FEricLBuehler\u002Fcandle-vllm\u002Fissues).\n\n\n## Contributing\nThe following features are planned to be implemented, but contributions are especially welcome:\n- Sampling methods:\n  - Beam search ([huggingface\u002Fcandle#1319](https:\u002F\u002Fgithub.com\u002Fhuggingface\u002Fcandle\u002Fissues\u002F1319))\n- More pipelines (from `candle-transformers`)\n\n## Resources\n- Python implementation: [`vllm-project`](https:\u002F\u002Fgithub.com\u002Fvllm-project\u002Fvllm)\n- [`vllm` paper](https:\u002F\u002Farxiv.org\u002Fabs\u002F2309.06180)\n","\u003Cp align=\"center\">\n    \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FEricLBuehler_candle-vllm_readme_729cc7175365.png\" alt=\"candle vLLM\" width=55%\u002F>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\".\u002FREADME.md\">English\u003C\u002Fa> |\n  \u003Ca href=\".\u002FREADME-CN.md\">简体中文\u003C\u002Fa> |\n\u003C\u002Fp>\n\n高效、易用的本地大模型推理与服务化平台，内置兼容 OpenAI 的 API 服务器。\n\n## 特性\n- 提供兼容 OpenAI 的 API 服务器，用于部署和调用大模型。\n- 基于 trait 的高度可扩展系统，支持快速实现新的模块化流水线。\n- 生成过程中的流式输出支持。\n- 使用 PagedAttention 高效管理键值缓存。\n- 持续批处理（随时间到达的请求会自动分批解码）。\n- `In-situ` 量化（以及 `In-situ` Marlin 格式转换）。\n- 支持 `GPTQ\u002FMarlin` 格式的 4-bit 量化。\n- 支持 `Mac\u002FMetal` 设备。\n- 支持 `多 GPU` 推理（包括 `多进程` 和 `多线程` 模式）。\n- 支持使用 MPI 运行器进行 `多节点` 推理。\n- 支持分块预填充（默认分块大小为 8K）。\n- 支持 CUDA Graph。\n- 支持模型上下文协议（MCP）及兼容 OpenAI 的工具调用功能。\n- 支持前缀缓存。\n- 支持块级 FP8 模型（SM90+，通义千问 3 系列）。\n- 支持 Flashinfer 后端。\n- 支持通过命令行参数 `--yarn-scaling-factor` 手动覆盖 YaRN RoPE 缩放因子。\n\n## 支持的模型\n- 目前，candle-vllm 支持以下模型架构的对话服务。\n  \u003Cdetails open>\n    \u003Csummary>查看支持的模型架构\u003C\u002Fsummary>\n\n    | 模型 ID | 模型类型 | 解码速度 \u002F 请求 (`BF16`, Hopper) | 量化版本 (`Q4K` 或 `Marlin`) |\n    |--|--|--|--|\n    | #1 | **LLAMA** |105 tks\u002Fs (8B) | 154 tks\u002Fs (8B, Q4k), 163 tks\u002Fs (8B, **Marlin**) |\n    | #2 | **Mistral** |112 tks\u002Fs (7B)| 171 tks\u002Fs (7B, Q4k), 175 tks\u002Fs (7B, **Marlin**) |\n    | #3 | **Phi3\u002FPhi4** |139 tks\u002Fs (3.8B)|180 tks\u002Fs (3.8B, Q4k)|\n    | #4 | **QWen2\u002FQwen3 Dense** |96 tks\u002Fs (8B)|135 tks\u002Fs **(8B, Q4k)**|\n    | #5 | **QWen3 MoE** |92 tks\u002Fs **(30B)**|114 tks\u002Fs **(30B, Q4K)** |\n    | #6 | **QWen3-Next MoE** |71 tks\u002Fs **(80B, BF16, tp=2)**|待定|\n    | #7 | **QWen3.5 Dense** |30 tks\u002Fs **(27B, BF16)**|~42 tks\u002Fs **(27B, Q4K \u002F FP8)** |\n    | #8 | **QWen3.5 MoE** |82 tks\u002Fs **(35B)**|93 tks\u002Fs **(35B, Q4K)** |\n    | #9 | **Yi** |148 tks\u002Fs (6B)| 180 tks\u002Fs (6B, Q4k)|\n    | #10 | **StableLM** |223 tks\u002Fs (3B)|-|\n    | #11 | **Gemma-2\u002FGemma-3** |92 tks\u002Fs (9B)|115 tks\u002Fs (9B, **Marlin**)|\n    | #12 | **DeepSeek V2\u002FV3\u002FR1** |待定|~20 tks **(AWQ 671B, tp=8, offloading)**|\n    | #13 | **QwQ-32B** |45 tks\u002Fs **(32B, tp=2)**|63 tks\u002Fs **(32B, Q4K)**|\n    | #14 | **GLM4** |89 tks\u002Fs **(9B)**|124 tks\u002Fs **(9B, Q4K)**|\n  \u003C\u002Fdetails>\n\n### 演示视频\n- Nvidia GPU 和 Apple Silicon\n\n  \u003Cdetails>\n    \u003Csummary>查看演示视频\u003C\u002Fsummary>\n    GPU 上的对话演示（A100, BF16, QWen3-8B 理性模型）\n    \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FEricLBuehler_candle-vllm_readme_4d71b67badfd.gif\" width=\"85%\" height=\"85%\" >\n\n    Apple Silicon 上的对话演示（M4，16GB 统一内存，Q2K，QWen3-8B）\n    \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FEricLBuehler_candle-vllm_readme_d836b1d4d7c1.gif\" width=\"85%\" height=\"85%\" >\n  \u003C\u002Fdetails>\n\n## 通用使用方法\n### 安装 Candle-vLLM\n\n**克隆代码**\n```shell\ngit clone git@github.com:EricLBuehler\u002Fcandle-vllm.git\ncd candle-vllm\n```\n\n**CUDA（CUDA 11+、12+、13.0）**\n > 选项 1（安装到 Docker 容器中）\n```bash\n# 主机驱动版本必须大于或等于指定的 CUDA 版本，`flashattn` 和 `flashinfer` 构建时间较长。\n# 将 `sm_80` 替换为您的硬件规格，例如 sm_75（V100）、sm_80（Ampere，A100）、sm_86\u002F89（RTX30xx、RTX40xx）、sm_90（Hopper，H100\u002FH200）、sm_100\u002Fsm_120（Blackwell，RTX50xx）。\n.\u002Fbuild_docker.sh \"cuda,nccl,graph,flashinfer,cutlass\" sm_90 13.0.0\n\n# 或切换到 Flash attention 后端，或使用 Rust crate 中国镜像（在中国大陆使用）\n.\u002Fbuild_docker.sh \"cuda,nccl,graph,flashattn,cutlass\" sm_80 12.9.0 1\n```\n\n > 选项 2（手动安装）\n\n安装依赖项\n```shell\nsudo apt update\n# 安装 CUDA 工具包（可选）\nsudo apt install git libssl-dev pkg-config curl -y\nsudo apt install -y cuda-toolkit-12-9 # 必须小于或等于主机驱动版本\n# 安装 Rust，要求 1.83.0 及以上版本\ncurl --proto '=https' --tlsv1.2 -sSf https:\u002F\u002Fsh.rustup.rs | sh\n\n# 确保系统 PATH 中能找到 CUDA 工具包\nexport PATH=$PATH:\u002Fusr\u002Flocal\u002Fcuda\u002Fbin\u002F\n```\n\n单节点推理安装\n```shell\n# 对于 sm_75 和 sm_70，请移除 “flashattn,flashinfer,cutlass”\n# 将 “flashinfer” 替换为 “flashattn” 以使用 Flash attention 后端\ncargo install --features cuda,nccl,graph,flashinfer,cutlass --path .\n```\n\n多节点推理安装\n```shell\n# 使用 MPI（多台机器上的多 GPU）\nsudo apt install libopenmpi-dev openmpi-bin -y # 安装 MPI\nsudo apt install clang libclang-dev\ncargo install --features cuda,nccl,graph,flashattn,cutlass,mpi --path .\n\n# FlashInfer 后端\ncargo install --features cuda,nccl,graph,flashinfer,cutlass,mpi --path .\n```\n\n**Mac\u002FMetal（仅限单节点）**\n\n安装 [Xcode 命令行工具](https:\u002F\u002Fmac.install.guide\u002Fcommandlinetools\u002F)\n\n使用 `metal` 特性安装\n```shell\ncargo install --features metal --path .\n```\n\n### 直接运行（无需安装）\n\n- [`ENV_PARAM`] cargo run [`BUILD_PARAM`] -- [`PROGRAM_PARAM`] [`MODEL_ID\u002FMODEL_WEIGHT_PATH`] [`CACHE CONFIG`] [`WEB UI`]\n  \u003Cdetails open>\n    \u003Csummary>显示详情\u003C\u002Fsummary>\n\n    **示例：**\n\n    ```shell\n    [RUST_LOG=warn] cargo run [--release --features cuda,nccl,flashinfer,cutlass,graph] -- [--log --dtype bf16 --p 2000 --d 0,1 --gpu-memory-fraction 0.7 --isq q4k --prefill-chunk-size 8192 --frequency-penalty 1.1 --presence-penalty 1.1 --enforce-parser qwen_coder --yarn-scaling-factor 4.0] [--m Qwen\u002FQwen3.5-27B-FP8] [--fp8-kvcache] [--ui-server]\n    ```\n\n    `ENV_PARAM`: RUST_LOG=warn\n\n    `BUILD_PARAM`: --release --features cuda,nccl,flashinfer,cutlass,graph\n\n    `PROGRAM_PARAM`：--log --dtype bf16 --p 2000 --d 0,1 --gpu-memory-fraction 0.7 --isq q4k --prefill-chunk-size 8192 --frequency-penalty 1.1 --presence-penalty 1.1 --enforce-parser qwen_coder --yarn-scaling-factor 4.0\n\n    `MODEL_ID\u002FMODEL_WEIGHT_PATH`: --m Qwen\u002FQwen3.5-27B-FP8 (或 `--w` 指定本地模型路径)\n\n    `CACHE CONFIG`: --fp8-kvcache\n\n    `WEB UI`: --ui-server\n\n    其中，`--p`：服务器端口；`--d`：设备 ID；`--w`：权重路径（safetensors 文件夹）；`--f`：权重文件（用于 gguf）；`--m`：Hugging Face 模型 ID；`--isq q4k`：在加载模型时将权重转换为 `q4k` 格式；`--prefill-chunk-size` 将预填充分块为该选项定义的大小（默认 8K，`0` 表示禁用）；`--frequency-penalty` 和 `--presence-penalty` 是重复惩罚参数（取值范围为 -2.0 至 2.0）；`--mem`（`kvcache-mem-gpu`）以 MB 为单位设置固定的 KV 缓存预算；`--gpu-memory-fraction` 使用 `fraction * remaining_gpu_memory` 在模型加载后自动调整 KV 缓存大小；`--enforce-parser` 强制使用特定的工具解析器后端，如 `qwen_coder`、`qwen`、`json` 或 `mistral`；`--yarn-scaling-factor` 手动注入 YaRN RoPE 缩放因子，例如 `4.0`，以扩展支持模型的有效上下文窗口；`--fp8-kvcache` 用于启用 fp8 KV 缓存；`--prefix-cache` 启用前缀缓存复用；`--prefix-cache-max-tokens` 限制前缀缓存大小；`--ui-server` 则启动内置的类似 ChatGPT 的 Web UI 服务器。若要使用 Flash attention 后端，可将 `BUILD_PARAM` 中的 `flashinfer` 替换为 `flashattn`。\n  \u003C\u002Fdetails>\n\n## 📚 文档\n- [Rust Crate 使用](docs\u002Frust_crate.md)\n- [嵌入模型使用](docs\u002Fembedding.md)\n- [MCP 与工具调用](docs\u002Fmcp_tool_calling.md)\n- [工具调用解析](docs\u002Ftool_parsing.md)\n- [前缀缓存](docs\u002Fprefix_cache.md)\n- [多模态模型使用](docs\u002Fmultimodal.md)\n- [与 OpenCode 合作](docs\u002Fopencode.md)\n- [与 Kilo Code 合作](docs\u002Fkilocode.md)\n\n## 如何部署模型？\n\n- **注意：** 对于 Docker 构建，执行以下命令进入容器：\n\n```shell\ndocker run --rm -it --gpus all --network host -v \u002Fhome:\u002Fhome -v \u002Fdata:\u002Fdata candle-vllm:latest bash\n```\n\n- 运行 **未压缩** 模型\n  \u003Cdetails open>\n    \u003Csummary>显示命令\u003C\u002Fsummary>\n\n    **本地路径（含端口、设备）**\n    ```shell\n    candle-vllm --p 8000 --d 0,1 --w \u002Fhome\u002FQwen3-30B-A3B-Instruct-2507\u002F --prefix-cache\n    ```\n\n    **本地路径（ISQ，+UI 服务器）**\n    ```shell\n    candle-vllm --p 8000 --d 0,1 --w \u002Fhome\u002FQwen3.5-27B\u002F --isq q4k --ui-server --prefix-cache\n    ```\n\n    **模型 ID（从 Hugging Face 下载）**\n\n    ```shell\n    candle-vllm --m Qwen\u002FQwen3.5-35B-A3B --ui-server --prefix-cache\n    ```\n\n    **手动 YaRN 缩放**\n    ```shell\n    candle-vllm --m Qwen\u002FQwen3.5-35B-A3B --yarn-scaling-factor 4.0 --ui-server --prefix-cache\n    ```\n\n    **FP8 模型**（分块量化，使用 `cutlass` 特性构建）\n    ```shell\n    candle-vllm --m Qwen\u002FQwen3.5-27B-FP8 --ui-server --prefix-cache\n    ```\n\n    ```shell\n     # MacOS\u002FMetal（密集型）\n    candle-vllm --m Qwen\u002FQwen3-4B-Instruct-2507-FP8 --ui-server --prefix-cache\n    ```\n  \u003C\u002Fdetails>\n\n- 运行 **GGUF** 模型\n  \u003Cdetails open>\n    \u003Csummary>显示命令\u003C\u002Fsummary>\n\n    **本地路径**\n\n    ```shell\n    candle-vllm --f \u002Fhome\u002Fdata\u002FQwen3-30B-A3B-Instruct-2507-Q4_K_M.gguf --ui-server\n    ```\n\n    **模型 ID（从 Hugging Face 下载）**\n\n    ```shell\n    candle-vllm --m unsloth\u002FQwen3-30B-A3B-Instruct-2507-GGUF --f Qwen3-30B-A3B-Instruct-2507-Q4_K_M.gguf --ui-server\n    ```\n\n  \u003C\u002Fdetails>\n\n- 运行 **GGUF** 模型于 **Apple Silicon** 上\n  \u003Cdetails>\n    \u003Csummary>显示命令\u003C\u002Fsummary>\n\n    **本地路径（假设模型已下载至 \u002Fhome）**\n\n    ```shell\n    candle-vllm --f \u002Fhome\u002Fqwq-32b-q4_k_m.gguf --ui-server\n    ```\n\n    **模型 ID（从 Hugging Face 下载）**\n\n    ```shell\n    candle-vllm --m Qwen\u002FQwQ-32B-GGUF --f qwq-32b-q4_k_m.gguf --ui-server\n    ```\n\n  \u003C\u002Fdetails>\n\n- 运行 **任何未压缩模型，通过原位量化将其量化**\n  \u003Cdetails>\n    \u003Csummary>显示命令\u003C\u002Fsummary>\n\n    **只需在运行未量化模型时添加 `isq` 参数**\n\n    ```shell\n    candle-vllm --p 2000 --m Qwen\u002FQwen3.5-27B --isq q4k\n    ```\n\n    原位 `isq` 参数的可选值有：[\"q4_0\", \"q4_1\", \"q5_0\", \"q5_1\", \"q8_0\", \"q2k\", \"q3k\",\"q4k\",\"q5k\",\"q6k\"]\n\n  \u003C\u002Fdetails>\n\n- 运行 **与 Marlin 兼容的 GPTQ 模型**（4-bit GPTQ，128 组，desc_act=False）\n  \u003Cdetails>\n    \u003Csummary>显示命令\u003C\u002Fsummary>\n\n    **本地路径**\n\n    ```shell\n    candle-vllm --w \u002Fhome\u002FDeepSeek-R1-Distill-Qwen-14B-GPTQ_4bit-128g\n    ```\n\n    **模型 ID（从 Hugging Face 下载）**\n\n    ```shell\n    candle-vllm --m thesven\u002FLlama-3-8B-GPTQ-4bit\n    ```\n\n    **将任何未量化模型转换为 Marlin 兼容格式**\n    ```shell\n    python3 examples\u002Fconvert_marlin.py --src \u002Fhome\u002FDeepSeek-R1-Distill-Qwen-14B\u002F --dst \u002Fhome\u002FDeepSeek-R1-Distill-Qwen-14B-GPTQ_4bit-128g\n    candle-vllm --w \u002Fhome\u002FDeepSeek-R1-Distill-Qwen-14B-GPTQ_4bit-128g\n    ```\n\n  \u003C\u002Fdetails>\n\n- 运行 **与 Marlin 兼容的 AWQ 模型**\n  \u003Cdetails>\n    \u003Csummary>显示命令\u003C\u002Fsummary>\n\n    **将 AWQ 模型转换为 Marlin 兼容格式**\n    ```shell\n    python3 examples\u002Fconvert_awq_marlin.py --src \u002Fhome\u002FMeta-Llama-3.1-8B-Instruct-AWQ-INT4\u002F --dst \u002Fhome\u002FMeta-Llama-3.1-8B-Instruct-AWQ-INT4-Marlin\u002F --bits 4 --method awq --group 128 --nk False\n    ```\n\n    **运行转换后的 AWQ 模型**\n    ```shell\n    candle-vllm --d 0 --w \u002Fhome\u002FMeta-Llama-3.1-8B-Instruct-AWQ-INT4-Marlin\u002F\n    ```\n\n  \u003C\u002Fdetails>\n\n- 运行 **Marlin 格式的模型**\n  \u003Cdetails>\n    \u003Csummary>显示命令\u003C\u002Fsummary>\n\n    ```shell\n    candle-vllm --w \u002Fhome\u002FDeepSeek-R1-Distill-Qwen-14B-GPTQ-Marlin\u002F\n    ```\n\n  \u003C\u002Fdetails>\n\n\n- 运行 **大型模型，采用多进程模式（多 GPU）**\n  \u003Cdetails>\n    \u003Csummary>显示命令\u003C\u002Fsummary>\n\n    **QwQ-32B BF16 模型在两块 GPU 上**\n    ```shell\n    candle-vllm --d 0,1 --w \u002Fhome\u002FQwQ-32B\u002F\n    ```\n\n    **QwQ-32B 4-bit AWQ 模型在两块 GPU 上**\n\n    1) 将 AWQ 模型转换为 Marlin 兼容格式\n    ```shell\n    python3 examples\u002Fconvert_awq_marlin.py --src \u002Fhome\u002FQwQ-32B-AWQ\u002F --dst \u002Fhome\u002FQwQ-32B-AWQ-Marlin\u002F --bits 4 --method awq --group 128 --nk False\n    ```\n\n    2) 运行转换后的 AWQ 模型\n    ```shell\n    candle-vllm --d 0,1 --w \u002Fhome\u002FQwQ-32B-AWQ-Marlin\u002F\n    ```\n\n**注意：** 所使用的 GPU 数量（`--d`）必须是 2 的幂次方（例如，2、4 或 8）。\n  \u003C\u002Fdetails>\n\n- 使用多线程模式运行大型模型（多 GPU，用于调试）\n  \u003Cdetails>\n    \u003Csummary>显示命令\u003C\u002Fsummary>\n\n    只需添加 `--multithread` 参数即可。\n\n    **在两块 GPU 上运行 QwQ-32B BF16 模型**\n    ```shell\n    candle-vllm --multithread --d 0,1 --w \u002Fhome\u002FQwQ-32B\u002F\n    ```\n\n    如果在多线程多 GPU 模式下遇到问题，可以尝试：\n    ```shell\n    export NCCL_P2P_DISABLE=1 # 禁用 p2p，因为在某些环境中此功能可能导致非法内存访问\n    ```\n\n  \u003C\u002Fdetails>\n\n- 在较低 GPU 显存条件下运行 DeepSeek-R1（671B\u002F685B）（CPU offloading）\n  \u003Cdetails>\n    \u003Csummary>显示命令\u003C\u002Fsummary>\n\n    **1. 将 DeepSeek-R1-AWQ 模型转换为与 Marlin 兼容的格式**\n    ```shell\n    python3 examples\u002Fconvert_awq_marlin.py --src \u002Fdata\u002FDeepSeek-R1-AWQ\u002F --dst \u002Fdata\u002FDeepSeek-R1-AWQ-Marlin\u002F \n    ```\n\n    **2. 在 8 块 A100（40GB）上运行 DeepSeek-R1 模型**\n    ```shell\n    candle-vllm --log --d 0,1,2,3,4,5,6,7 --w \u002Fdata\u002FDeepSeek-R1-AWQ-Marlin\u002F--num-experts-offload-per-rank 15\n    ```\n\n    **注意：** 此设置会将每个 Rank 上的 15 个专家（总共 256 个中的 120 个）卸载到 CPU（大约需要额外 150GB 的主机内存）。在推理过程中，这些被卸载的专家会根据需要交换回 GPU 内存。如果您可用的 GPU 显存更少，请考虑增加 `--num-experts-offload-per-rank` 参数值（在此情况下，每个 Rank 最多可卸载 32 个专家）。\n\n  \u003C\u002Fdetails>\n\n- 在多节点上运行 DeepSeek-R1（671B\u002F685B）\n  \u003Cdetails>\n    \u003Csummary>显示命令\u003C\u002Fsummary>\n\n    **1. 安装 MPI 并启用 MPI 功能进行构建**\n    ```shell\n    sudo apt update\n    sudo apt install libopenmpi-dev openmpi-bin -y # 安装 MPI\n    sudo apt install clang libclang-dev\n    # 在两台节点的同一目录下克隆仓库并构建\n    cargo install --features cuda,nccl,mpi # 启用 MPI 功能进行构建\n    ```\n\n    **2. 将 AWQ DeepSeek 转换为 Marlin 兼容格式**\n    ```shell\n    python3 examples\u002Fconvert_awq_marlin.py --src \u002Fdata\u002FDeepSeek-R1-AWQ\u002F --dst \u002Fdata\u002FDeepSeek-R1-AWQ-Marlin\u002F \n    ```\n\n    **3. 配置多节点环境**\n\n    MPI 运行器要求所有节点具有“完全相同”的硬件和软件配置，请确保权重文件和 candle-vllm 二进制文件在不同节点上的路径完全一致。此外，节点之间需要免密 SSH 登录（使用 root 用户时需启用 `--allow-run-as-root`）。`%NET_INTERFACE%` 是通过 `ifconfig -a` 命令获取的活动网络接口。如果节点上没有 InfiniBand 网络，可以通过设置环境变量 `-x NCCL_IB_DISABLE=1` 来禁用它。`hostfile` 文件的示例如下：\n\n    示例（两台节点，每台有 8 个 GPU）\n    ```\n    192.168.1.100 slots=8\n    192.168.1.101 slots=8\n    ```\n\n    **4. 使用 MPI 运行器在两台节点上运行模型**\n    ```shell\n    sudo mpirun -np 16 -x RUST_LOG=info -hostfile .\u002Fhostfile --allow-run-as-root -bind-to none -map-by slot --mca plm_rsh_args \"-p 22\" --mca btl_tcp_if_include %NET_INTERFACE% candle-vllm --log --d 0,1,2,3,4,5,6,7 --w \u002Fdata\u002FDeepSeek-R1-AWQ-Marlin\u002F\n    ```\n  \u003C\u002Fdetails>\n\n- 使用 NUMA 绑定运行\n  \u003Cdetails>\n    \u003Csummary>显示命令\u003C\u002Fsummary>\n\n    **先决条件**\n    确保您的机器拥有多个 NUMA 节点（即多于一个物理 CPU），并安装 numactl：\n    ```shell\n    sudo apt-get install numactl\n    ```\n\n    假设您的机器有 8 个 GPU 和 2 个 NUMA 节点，每组 4 个 GPU 分别绑定到不同的 NUMA 节点。为了在使用全部 GPU 进行推理时获得最佳性能，可以采用以下 NUMA 绑定：\n\n    ```shell\n    MAP_NUMA_NODE=0,0,0,0,1,1,1,1 numactl --cpunodebind=0 --membind=0 candle-vllm --d 0,1,2,3,4,5,6,7 --w \u002Fhome\u002Fdata\u002FDeepSeek-V2-Chat-AWQ-Marlin\n    ```\n\n    如果仅使用 4 个 GPU，可以应用如下 NUMA 绑定：\n    \n    ```shell\n    MAP_NUMA_NODE=0,0,0,0 numactl --cpunodebind=0 --membind=0 candle-vllm --d 0,1,2,3 --w \u002Fhome\u002Fdata\u002FDeepSeek-V2-Chat-AWQ-Marlin\n    ```\n    *其中* 上述 `numactl --cpunodebind=0 --membind=0` 表示主 Rank（主进程）的 NUMA 绑定，应与 `MAP_NUMA_NODE` 设置相匹配。\n\n    注意：具体的 NUMA 绑定顺序可能因您的硬件配置而异。\n  \u003C\u002Fdetails>\n\n## 如何向后端发送请求？\n\n**在启动后端服务后运行聊天前端**\n\n聊天前端（任何兼容 OpenAI API 的前端，以下提供简单选项）：\n\n- **选项 1：使用 Chat.py 进行聊天（适用于简单测试）**\n  \u003Cdetails>\n    \u003Csummary>显示选项 1\u003C\u002Fsummary>\n    \n    安装 API 和聊天机器人依赖项（openai 包仅用于本地与 candle-vllm 的聊天）\n\n    ```shell\n    python3 -m pip install openai rich click\n    ```\n\n    使用迷你聊天机器人进行纯文本聊天：\n    ```shell\n    python3 examples\u002Fchat.py\n    ```\n\n    传递生成参数（对带有 `--thinking True` 的推理模型）：\n    ```shell\n    python3 examples\u002Fchat.py --temperature 0.7 --top_k 64 --top_p 0.9 --thinking True --system_prompt \"Thinking big!\"\n    ```\n\n    使用迷你聊天机器人进行 Markdown 实时更新的聊天（可能会出现闪烁）：\n    ```shell\n    python3 examples\u002Fchat.py --live\n    ```\n  \u003C\u002Fdetails>\n\n- **选项 2：使用 naive ChatUI（或流行的 dify 前端）进行聊天**\n  \u003Cdetails>\n    \u003Csummary>显示选项 2\u003C\u002Fsummary>\n\n    安装 naive ChatUI 及其依赖项：\n\n    ```\n    git clone git@github.com:guoqingbao\u002Fcandle-vllm-demo.git\n    cd candle-vllm-demo\n    apt install npm # 如果需要，安装 npm\n    npm install n -g # 如果需要，更新 Node.js\n    n stable # 如果需要，更新 Node.js\n    npm i -g pnpm # 安装 pnpm 包管理器\n    pnpm install # 安装 ChatUI 的依赖项\n    ```\n\n    启动 ChatUI：\n    ```\n    pnpm run dev # 运行 ChatUI\n    ```\n\n    **Node.js 错误排查**\n    `ENOSPC: 系统文件监视器数量限制已达到`\n    ```\n    echo fs.inotify.max_user_watches=524288 | sudo tee -a \u002Fetc\u002Fsysctl.conf && sudo sysctl -p\n    ```\n  \u003C\u002Fdetails>\n\n- **选项 3：使用 HTTP POST 发送聊天完成请求**\n  \u003Cdetails>\n    \u003Csummary>显示选项 3\u003C\u002Fsummary>\n\n    ``` shell\n    curl -X POST \"http:\u002F\u002F127.0.0.1:2000\u002Fv1\u002Fchat\u002Fcompletions\" \\\n        -H \"Content-Type: application\u002Fjson\" \\\n        -H \"Authorization: Bearer YOUR_API_KEY\" \\\n        -d '{\n            \"model\": \"llama7b\",\n            \"messages\": [\n                {\"role\": \"user\", \"content\": \"解释如何最好地学习 Rust。\"}\n            ],\n            \"temperature\": 0.7,\n            \"max_tokens\": 128,\n            \"stop\": {\"Single\":\"\u003C\u002Fs>\"}\n        }'\n    ```\n    示例响应：\n\n    ```\n    {\"id\":\"cmpl-53092967-c9cf-40e0-ae26-d7ac786d59e8\",\"choices\":[{\"message\":{\"content\":\" 学习任何编程语言都需要理论、实践和专注相结合。以下是帮助你有效学习 Rust 的一些步骤和资源：\\n\\n1. 从基础开始：\\n\\t* 理解 Rust 程序的语法和基本结构。\\n\\t* 学习变量、数据类型、循环和控制结构。\\n\\t* 熟悉 Rust 的所有权系统和借用机制。\\n2. 阅读 Rust 官方书籍：\\n\\t* Rust 官方书籍是全面介绍该语言的权威资源。\\n\\t* 它涵盖了诸如\",\"role\":\"[INST]\"},\"finish_reason\":\"length\",\"index\":0,\"logprobs\":null}],\"created\":1718784498,\"model\":\"llama7b\",\"object\":\"chat.completion\",\"usage\":{\"completion_tokens\":129,\"prompt_tokens\":29,\"total_tokens\":158}}\n    ```\n  \u003C\u002Fdetails>\n\n- **选项 4：使用 openai 包进行聊天完成**\n  \u003Cdetails>\n    \u003Csummary>显示选项 4\u003C\u002Fsummary>\n\n    在终端中运行 `pip install openai` 来安装 `openai` Python 包。我使用的是版本 `1.3.5`。\n\n    然后，创建一个新的 Python 文件并编写以下代码：\n    ```python\n    import openai\n\n    openai.api_key = \"EMPTY\"\n\n    openai.base_url = \"http:\u002F\u002Flocalhost:2000\u002Fv1\u002F\"\n\n    completion = openai.chat.completions.create(\n        model=\"llama\",\n        messages=[\n            {\n                \"role\": \"user\",\n                \"content\": \"解释如何最好地学习 Rust。\",\n            },\n        ],\n        max_tokens = 64,\n    )\n    print(completion.choices[0].message.content)\n    ```\n    在 `candle-vllm` 服务运行后，运行该 Python 脚本，即可享受与 OpenAI 兼容的 API 服务器带来的高效推理！\n\n\n    **批量请求**\n\n    首先安装 openai API：\n    ```\n    python3 -m pip install openai\n    ```\n\n    运行基准测试：\n    ``` shell\n    python3 examples\u002Fbenchmark.py --batch 16 --max_tokens 1024\n    ```\n    参考 `examples\u002Fbenchmark.py`\n\n    ``` python\n    async def benchmark():\n        model = \"mistral7b\"\n        max_tokens = 1024\n        # 16 个请求\n        prompts = [\"解释如何最好地学习 Rust。\", \n                \"请用 100 字谈谈深度学习。\", \n                \"你知道中国的首都吗？详细说说你所知道的。\", \n                \"世界上最好的女演员是谁？为什么？\",\n                \"如何应对抑郁症？\",\n                \"如何在短时间内赚钱？\",\n                \"大型语言模型的未来趋势是什么？\",\n                \"世界上著名的科技公司有哪些。\",\n                \"解释如何最好地学习 Rust。\", \n                \"请用 100 字谈谈深度学习。\", \n                \"你知道中国的首都吗？详细说说你所知道的。\", \n                \"世界上最好的女演员是谁？为什么？\",\n                \"如何应对抑郁症？\",\n                \"如何在短时间内赚钱？\",\n                \"大型语言模型的未来趋势是什么？\",\n                \"世界上著名的科技公司有哪些。\"]\n        \n        # 同时发送 16 个聊天请求\n        tasks: List[asyncio.Task] = []\n        for i in range(len(prompts)):\n            tasks.append(\n                asyncio.create_task(\n                    chat_completion(model, max_tokens, prompts[i]))\n            )\n\n        # 获取每个请求对应的流对象\n        outputs: List[Stream[ChatCompletionChunk]] = await asyncio.gather(*tasks)\n\n        # 处理聊天响应的流任务\n        tasks_stream: List[asyncio.Task] = []\n        for i in range(len(outputs)):\n            tasks_stream.append(\n                asyncio.create_task(\n                    stream_response(i, outputs[i]))\n            )\n\n        # 汇总响应文本\n        outputs: List[(int, str)] = await asyncio.gather(*tasks_stream)\n\n        # 打印结果，你可以在后端服务器（即 candle-vllm）中找到聊天完成的统计信息\n        for idx, output in outputs:\n            print(\"\\n\\n 回复 {}: \\n\\n {}\".format(idx, output))\n\n    asyncio.run(benchmark())\n    ```\n  \u003C\u002Fdetails>\n\n## 原位量化\n- **以 GGUF 量化或 Marlin 格式加载未量化模型**\n  \u003Cdetails>\n    \u003Csummary>显示量化配置\u003C\u002Fsummary>\n\n    Candle-vllm 支持原位量化，允许在加载模型时将默认权重（F32\u002FF16\u002FBF16）转换为任意 GGML\u002FGGUF 格式，或将 `4-bit GPTQ\u002FAWQ` 权重转换为 `marlin 格式`。此功能有助于节省 GPU 内存并加速推理性能，使其对消费级 GPU（例如 RTX 4090）更加高效。要使用此功能，只需在运行 candle-vllm 时提供 `isq` 参数。\n\n    **对于未量化模型：**\n\n    ```\n    candle-vllm --p 2000 --w \u002Fhome\u002FMeta-Llama-3.1-8B-Instruct\u002F --isq q4k\n    ```\n\n    `isq` 参数的选项有：[\"q4_0\", \"q4_1\", \"q5_0\", \"q5_1\", \"q8_0\", \"q2k\", \"q3k\",\"q4k\",\"q5k\",\"q6k\"]\n\n    **对于已量化 4-bit GPTQ 模型：**\n\n    ```\n    candle-vllm --p 2000 --w \u002Fhome\u002Fmistral_7b-int4\u002F\n    ```\n\n    **请注意关于 marlin 的几点：**\n\n    1) 将 F32\u002FF16\u002FBF16 模型加载为量化格式可能需要几分钟时间；\n\n    2) Marlin 格式的原位转换仅支持 4-bit GPTQ（`sym=True`、`groupsize=128` 或 -1、`desc_act=False`）以及 4-bit AWQ（需使用提供的脚本进行转换，参见“其他用法”）；\n\n    3) Marlin 格式仅在 CUDA 平台上受支持。\n  \u003C\u002Fdetails>\n\n## 其他用法\n- KV 缓存配置、采样参数等\n  \u003Cdetails>\n    \u003Csummary>显示详情\u003C\u002Fsummary>\n    `--mem`（`kvcache-mem-gpu`）参数用于设置固定的 KV 缓存预算，单位为 MB。默认值为 `4096` MB。\n\n    `--gpu-memory-fraction` 参数是一种更轻量级的自动模式。若省略，则默认值为 `0.7`。模型加载完成后，candle-vllm 会探测每个已加载的 CUDA 或 Metal 设备，并按以下公式计算 KV 缓存预算：\n\n    ```\n    gpu_memory_fraction * 模型加载后剩余的 GPU 内存\n    ```\n\n    这意味着该分数直接控制了模型加载后剩余的空闲 GPU 内存中可用于组合 GPU 缓存预算的比例。各进程检测到的最低预算将被用作每个进程的 KV 缓存预算。例如：\n\n    ```\n    candle-vllm --w \u002Fhome\u002FQwen3-Coder-30B-A3B-Instruct-FP8 --d 0,1 --gpu-memory-fraction 0.7\n    ```\n\n    当您希望设定明确的固定预算时，请使用 `--mem`；当您希望服务器根据模型加载后的当前可用 GPU 内存自动调整时，则使用 `--gpu-memory-fraction`。\n\n    `--enforce-parser` 参数可强制指定特定的工具调用解析器后端，而非由模型自动选择的默认解析器。这在模型与某个解析器兼容但未能正确自动检测到时非常有用。常见值包括 `qwen_coder`、`qwen`、`json` 和 `mistral`。例如：\n\n    ```\n    candle-vllm --w \u002Fhome\u002FQwen3-Coder-30B-A3B-Instruct-FP8 --enforce-parser qwen_coder\n    ```\n\n    无效的解析器名称将在启动时被拒绝。\n\n    对于聊天历史设置，将 `record_conversation` 设置为 `true` 可让 candle-vllm 记录聊天历史。默认情况下，candle-vllm 不会记录聊天历史；相反，客户端会同时发送消息和上下文历史给 candle-vllm。如果将 `record_conversation` 设置为 `true`，则客户端仅向 candle-vllm 发送新的聊天消息，而 candle-vllm 负责记录之前的聊天消息。然而，这种方法需要按会话记录聊天，目前尚未实现，因此建议采用默认方式 `record_conversation=false`。\n\n    在聊天流式传输中，聊天请求中的 `stream` 标志需设置为 `True`。\n\n    ```\n    candle-vllm --p 2000 --w \u002Fhome\u002Fmistral_7b\u002F\n    ```\n\n    `--max-gen-tokens` 参数用于控制每次聊天回复的最大输出 token 数。默认值为 `max_sequence_len` 的 1\u002F5。\n\n    对于 `消费级 GPU`，建议以 GGML 格式（或 Marlin 格式）运行模型，例如：\n\n    ```\n    candle-vllm --p 2000 --w \u002Fhome\u002FMeta-Llama-3.1-8B-Instruct\u002F --isq q4k\n    ```\n\n    其中 `isq` 是 [\"q4_0\", \"q4_1\", \"q5_0\", \"q5_1\", \"q8_0\", \"q2k\", \"q3k\",\"q4k\",\"q5k\",\"q6k\", \"awq\", \"gptq\", \"marlin\", \"gguf\", \"ggml\"] 中的一个。\n  \u003C\u002Fdetails>\n\n- **使用 Marlin 内核加速 GPTQ\u002FAWQ 模型**\n  \u003Cdetails>\n    \u003Csummary>显示详情\u003C\u002Fsummary>\n\n    Candle-vllm 现在支持 GPTQ\u002FAWQ 的 Marlin 内核，您可以直接运行这些模型，例如：\n\n    ```shell\n    candle-vllm --dtype f16 --w \u002Fhome\u002FMeta-Llama-3.1-8B-Instruct-GPTQ-INT4-Marlin\u002F\n    ```\n\n    或者，将现有的 AWQ 4bit 模型转换为 marlin 兼容格式：\n\n    ```shell\n    python3 examples\u002Fconvert_awq_marlin.py --src \u002Fhome\u002FMeta-Llama-3.1-8B-Instruct-AWQ-INT4\u002F --dst \u002Fhome\u002FMeta-Llama-3.1-8B-Instruct-AWQ-INT4-Marlin\u002F --bits 4 --method awq --group 128 --nk False\n    candle-vllm --dtype f16 --d 0 --w \u002Fhome\u002FMeta-Llama-3.1-8B-Instruct-AWQ-INT4-Marlin\u002F\n    ```\n\n    您也可以使用 `GPTQModel` 通过提供的脚本 `examples\u002Fconvert_marlin.py` 将模型转换为 marlin 兼容格式。\n\n    **注意：** 目前，只有 4-bit GPTQ 量化支持使用 Marlin 快速内核。\n  \u003C\u002Fdetails>\n\n## 报告问题\n安装 `candle-vllm` 非常简单，只需按照以下步骤操作即可。如果您遇到任何问题，请创建一个\n[issue](https:\u002F\u002Fgithub.com\u002FEricLBuehler\u002Fcandle-vllm\u002Fissues)。\n\n\n## 贡献\n计划实现以下功能，但我们特别欢迎贡献：\n- 采样方法：\n  - 束搜索（[huggingface\u002Fcandle#1319](https:\u002F\u002Fgithub.com\u002Fhuggingface\u002Fcandle\u002Fissues\u002F1319)）\n- 更多流水线（来自 `candle-transformers`）\n\n## 资源\n- Python 实现：[`vllm-project`](https:\u002F\u002Fgithub.com\u002Fvllm-project\u002Fvllm)\n- [`vllm` 论文](https:\u002F\u002Farxiv.org\u002Fabs\u002F2309.06180)","# Candle-vLLM 快速上手指南\n\nCandle-vLLM 是一个基于 Rust 构建的高效本地大语言模型（LLM）推理与服务平台，提供兼容 OpenAI 的 API 服务器。它支持多 GPU、多节点推理，并在 NVIDIA GPU 和 Apple Silicon (Mac) 上均有出色表现。\n\n## 1. 环境准备\n\n### 系统要求\n- **操作系统**: Linux (推荐), macOS (Apple Silicon)\n- **GPU**: NVIDIA GPU (CUDA 11+\u002F12+\u002F13.0) 或 Apple M 系列芯片\n- **内存**: 根据模型大小而定，建议 16GB+\n\n### 前置依赖\n\n#### Linux (CUDA)\n```bash\n# 更新包管理器\nsudo apt update\n\n# 安装基础工具\nsudo apt install git libssl-dev pkg-config curl -y\n\n# 安装 CUDA Toolkit (版本需 \u003C= 宿主驱动版本，例如 12.9)\nsudo apt install -y cuda-toolkit-12-9\n\n# 安装 Rust (要求 1.83.0+)\ncurl --proto '=https' --tlsv1.2 -sSf https:\u002F\u002Fsh.rustup.rs | sh\n\n# 配置环境变量，确保系统能找到 CUDA\nexport PATH=$PATH:\u002Fusr\u002Flocal\u002Fcuda\u002Fbin\u002F\n```\n\n#### macOS (Metal)\n- 安装 [Xcode Command Line Tools](https:\u002F\u002Fmac.install.guide\u002Fcommandlinetools\u002F)\n- 确保已安装 Rust (`curl --proto '=https' --tlsv1.2 -sSf https:\u002F\u002Fsh.rustup.rs | sh`)\n\n> **国内加速提示**: 在安装 Rust 或下载模型时，如遇网络问题，可配置国内镜像源或使用代理。部分构建脚本支持通过参数启用 Rust crate 中国镜像。\n\n## 2. 安装步骤\n\n你可以选择手动安装或使用 Docker。\n\n### 方案 A：手动安装 (推荐)\n\n**单节点推理 (Single Node)**\n```bash\n# 进入项目目录后执行\n# 注意：根据显卡架构调整 sm_XX (如 sm_80 对应 A100\u002F30xx\u002F40xx, sm_90 对应 H100)\n# 若使用 FlashAttention 后端，将 flashinfer 替换为 flashattn\ncargo install --features cuda,nccl,graph,flashinfer,cutlass --path .\n```\n\n**多节点\u002F多机推理 (Multi-Node with MPI)**\n```bash\n# 安装 MPI 依赖\nsudo apt install libopenmpi-dev openmpi-bin clang libclang-dev -y\n\n# 安装带 MPI 支持的版本\ncargo install --features cuda,nccl,graph,flashinfer,cutlass,mpi --path .\n```\n\n**macOS (Metal)**\n```bash\ncargo install --features metal --path .\n```\n\n### 方案 B：Docker 构建 (隔离环境)\n\n```bash\n# 构建镜像 (示例：sm_90 架构，CUDA 13.0，包含 flashinfer)\n# 国内用户可在命令末尾添加 '1' 以启用 Rust crate 中国镜像\n.\u002Fbuild_docker.sh \"cuda,nccl,graph,flashinfer,cutlass\" sm_90 13.0.0\n\n# 运行容器\ndocker run --rm -it --gpus all --network host -v \u002Fhome:\u002Fhome -v \u002Fdata:\u002Fdata candle-vllm:latest bash\n```\n\n## 3. 基本使用\n\n### 启动服务 (最简单示例)\n\n以下命令将从 Hugging Face 下载模型并启动一个带有 Web UI 的服务。\n\n**启动 Qwen3.5 模型 (自动下载 + Web UI)**\n```bash\ncandle-vllm --m Qwen\u002FQwen3.5-35B-A3B --ui-server --prefix-cache\n```\n\n**启动本地模型路径 (指定端口和设备)**\n```bash\n# --w: 本地权重文件夹路径\n# --d: 使用的 GPU ID (0,1 表示双卡)\n# --p: 服务端口\ncandle-vllm --p 8000 --d 0,1 --w \u002Fhome\u002FQwen3-30B-A3B-Instruct-2507\u002F --prefix-cache\n```\n\n**启动 GGUF 格式模型 (适用于量化模型或 Mac)**\n```bash\n# --f: 指定具体的 GGUF 文件\ncandle-vllm --f \u002Fhome\u002Fdata\u002FQwen3-30B-A3B-Instruct-2507-Q4_K_M.gguf --ui-server\n```\n\n**原位量化启动 (无需预先转换，加载时自动转为 Q4K)**\n```bash\n# --isq q4k: 加载未量化模型时即时转换为 Q4K 格式\ncandle-vllm --p 2000 --m Qwen\u002FQwen3.5-27B --isq q4k\n```\n\n### 常用参数说明\n\n| 参数 | 说明 |\n| :--- | :--- |\n| `--m` | Hugging Face Model ID (自动下载) |\n| `--w` | 本地模型权重文件夹路径 (safetensors) |\n| `--f` | 本地 GGUF 模型文件路径 |\n| `--p` | API 服务器端口 (默认通常不需指定，除非冲突) |\n| `--d` | 使用的 GPU 设备 ID (例如 `0,1` 或 `0`) |\n| `--ui-server` | 启动内置的类 ChatGPT Web 界面 |\n| `--isq` | 启用原位量化 (选项：`q4k`, `q8_0` 等) |\n| `--prefix-cache` | 启用前缀缓存以提升重复提示词的效率 |\n| `--yarn-scaling-factor` | 手动设置 YaRN RoPE 缩放因子以扩展上下文窗口 |\n\n### 访问服务\n启动成功后，打开浏览器访问 `http:\u002F\u002Flocalhost:\u003CPORT>` (若使用了 `--ui-server`)，或通过 OpenAI 兼容接口调用：\n- API 地址：`http:\u002F\u002Flocalhost:\u003CPORT>\u002Fv1\u002Fchat\u002Fcompletions`","某初创团队需要在本地 Mac 集群和混合 GPU 服务器上部署私有化客服大模型，以处理高并发的实时用户咨询，同时严格保障数据不出域。\n\n### 没有 candle-vllm 时\n- **硬件利用率低**：团队拥有的 Apple Silicon (M4) 设备无法高效运行大模型，只能闲置，被迫额外采购昂贵的 NVIDIA 显卡。\n- **响应延迟高**：在高峰期，传统推理框架缺乏连续批处理（Continuous Batching）能力，导致用户等待时间过长，体验卡顿。\n- **显存开销巨大**：未采用 PagedAttention 技术管理键值缓存，长对话场景下显存迅速爆满，频繁触发服务崩溃。\n- **集成成本高**：缺乏原生的 OpenAI 兼容接口，开发人员需编写大量胶水代码才能将本地模型接入现有的业务系统。\n- **量化部署复杂**：想要通过 4-bit 量化提升速度，往往需要复杂的格式转换流程，且难以在推理时动态完成。\n\n### 使用 candle-vllm 后\n- **全平台高效赋能**：直接利用 Mac\u002FMetal 设备进行推理，完美激活闲置算力，同时支持多卡和多节点扩展，硬件成本降低 40%。\n- **毫秒级流畅响应**：借助连续批处理和流式输出特性，即使在高并发下，首字生成时间和整体吞吐量也显著提升。\n- **显存管理智能化**：内置 PagedAttention 机制高效管理上下文缓存，稳定支持长轮次对话，服务稳定性大幅增强。\n- **无缝系统对接**：开箱即用的 OpenAI 兼容 API 服务器，让现有业务代码无需修改即可切换至本地大模型后端。\n- **即时量化加速**：支持原位（In-situ）GPTQ\u002FMarlin 量化，一键启动 4-bit 高精度推理，在保持模型效果的同时速度提升近 50%。\n\ncandle-vllm 通过极致的跨平台性能优化和开箱即用的企业级特性，让团队以最低成本实现了私有大模型的高效、稳定落地。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FEricLBuehler_candle-vllm_5d34191d.png","EricLBuehler","Eric Buehler","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002FEricLBuehler_f582cced.jpg","@huggingface ",null,"https:\u002F\u002Fgithub.com\u002FEricLBuehler",[80,84,88,92],{"name":81,"color":82,"percentage":83},"Rust","#dea584",99.1,{"name":85,"color":86,"percentage":87},"Python","#3572A5",0.5,{"name":89,"color":90,"percentage":91},"Shell","#89e051",0.3,{"name":93,"color":94,"percentage":95},"Dockerfile","#384d54",0.1,632,75,"2026-04-04T06:29:10","MIT",4,"Linux, macOS","NVIDIA GPU (必需，支持 CUDA 11+\u002F12+\u002F13.0，需指定 compute capability 如 sm_75\u002F80\u002F86\u002F89\u002F90\u002F100\u002F120) 或 Apple Silicon (M 系列芯片，支持 Metal)。多卡支持多进程或多线程模式，多节点支持 MPI。","未说明 (取决于模型大小，Apple Silicon 示例中提及 16GB 统一内存)",{"notes":105,"python":106,"dependencies":107},"该项目主要基于 Rust 开发而非 Python。安装时需根据显卡架构（如 Ampere, Hopper, Blackwell）编译对应的 CUDA 内核（sm_xx）。支持多种量化格式（GPTQ\u002FMarlin\u002FAWQ\u002FFP8\u002FISQ）及 FlashInfer\u002FFlashAttention 后端。多卡推理时设备数量需为 2 的幂次（如 2, 4, 8）。Mac 端仅支持单节点推理。","未说明 (核心为 Rust 项目，仅部分转换脚本需要 Python3)",[108,109,110,111,112,113,114,115],"Rust >= 1.83.0","CUDA Toolkit (11.x - 13.0)","libssl-dev","pkg-config","curl","libopenmpi-dev (多节点可选)","clang","Xcode command line tools (macOS)",[35,14],"2026-03-27T02:49:30.150509","2026-04-07T06:25:14.118712",[120,125,130,135,140,145],{"id":121,"question_zh":122,"answer_zh":123,"source_url":124},21091,"Qwen2 和 Qwen3 模型在使用新的注意力机制实现后性能显著下降，如何解决？","这是一个已知问题，新的注意力实现可能导致精度损失。维护者建议尝试最新的提交或特定的 Pull Request（如 #321）来恢复精度。该修复旨在将准确性恢复到引入新注意力机制之前的水平。如果问题依然存在，可能需要等待后续的长上下文测试更新或回退到旧版本。","https:\u002F\u002Fgithub.com\u002FEricLBuehler\u002Fcandle-vllm\u002Fissues\u002F303",{"id":126,"question_zh":127,"answer_zh":128,"source_url":129},21092,"Qwen3 MoE 模型在使用工具调用（Tool Usage）时频繁失败或返回意外结果怎么办？","这通常与提示词（prompt）过多或上下文管理有关。可以通过调整工作目录下的 `forge.yaml` 配置文件来解决。具体配置示例如下：\n```yaml\ncompact:\n  retention_window: 6\n  eviction_window: 0.2\n  max_tokens: 131072\n  token_threshold: 65536\n  message_threshold: 20\n  prompt: '{{> forge-system-prompt-context-summarizer.hbs }}'\n  model: DavidAU\u002FQwen3-Coder-42B-A3B-Instruct-TOTAL-RECALL-MASTER-CODER-M-512k-ctx\n  on_turn_end: false\n```\n此外，请确保参考最新的代码提交（如 #359），其中可能包含针对工具模板的修复。","https:\u002F\u002Fgithub.com\u002FEricLBuehler\u002Fcandle-vllm\u002Fissues\u002F262",{"id":131,"question_zh":132,"answer_zh":133,"source_url":134},21093,"在 Red Hat 系列发行版上构建时遇到 `candle-flash-attn` 链接错误如何处理？","该问题源于底层依赖库 `Candle` 的构建过程，而非本项目直接控制。`candle-vllm` 不直接构建 flash attention 内核。建议采取以下措施：\n1. 该项目已停止维护，官方推荐使用其继任项目 [mistral.rs](https:\u002F\u002Fgithub.com\u002FEricLBuehler\u002Fmistral.rs)，它更好地支持 flash attention 和 GGUF 格式。\n2. 如果必须使用本项目，需向 `Candle` 仓库提交 Issue 反馈此链接错误，因为构建步骤发生在 `Candle` 的 `build.rs` 中。","https:\u002F\u002Fgithub.com\u002FEricLBuehler\u002Fcandle-vllm\u002Fissues\u002F25",{"id":136,"question_zh":137,"answer_zh":138,"source_url":139},21094,"如何在不使用 `--hf-token` 参数的情况下运行程序，而是自动使用缓存中的 Token？","程序现已支持自动读取 Hugging Face 缓存目录下的 Token 文件。只需确保您的系统中存在有效的 `~\u002F.cache\u002Fhuggingface\u002Ftoken` 文件（通常由 Python 的 `huggingface_hub` 库登录生成）。配置好后，直接运行命令而无需添加 `--hf-token` 参数，程序会自动加载该文件中的凭证。","https:\u002F\u002Fgithub.com\u002FEricLBuehler\u002Fcandle-vllm\u002Fissues\u002F31",{"id":141,"question_zh":142,"answer_zh":143,"source_url":144},21095,"Qwen3 MoE 模型运行时出现 `CUDA_ERROR_INVALID_VALUE` 错误是什么原因？","该错误通常是由显存溢出（OOM）引起的，特别是在处理计算图时。当显存使用量达到极限时，CUDA 操作会失败并报此错误。建议检查显卡显存使用情况，尝试减小批次大小（batch size）或上下文长度，或者使用显存优化版本的模型量化格式。","https:\u002F\u002Fgithub.com\u002FEricLBuehler\u002Fcandle-vllm\u002Fissues\u002F237",{"id":146,"question_zh":147,"answer_zh":148,"source_url":134},21096,"candle-vllm 项目是否还在维护？是否有推荐的替代方案？","candle-vllm 项目目前已不再积极维护。维护者明确建议用户迁移至其继任项目 [mistral.rs](https:\u002F\u002Fgithub.com\u002FEricLBuehler\u002Fmistral.rs)。新项目提供了更好的功能支持，包括 Flash Attention、GGUF 格式支持以及更稳定的推理性能。",[]]