noonghunna/club-3090

解決的問題

club-3090 提供一組經過驗證的「食譜」（Docker Compose 設定）與工具，協助使用者在 NVIDIA RTX 3090 GPU 上本地部署大型語言模型（LLM）。透過為不同 GPU 數量（單卡或雙卡 3090）與各種推論引擎提供驗證過的設定，消除硬體感知模型部署中的摸索過程，確保使用者能在不因 VRAM 限制而當機的情況下，最大化吞吐量或上下文視窗大小。

如何運作

本專案使用與模型無關的腳本與 Docker Compose 檔案框架來部署 LLM。支援多種推論引擎，包括 vLLM、llama.cpp 與 ik_llama。

• 部署流程：使用者可使用 CLI 導師（launch.sh）或終端機 UI 駕駛艙（c3）選擇模型與設定變體（例如高吞吐量的雙卡設定或穩健的單卡設定）。
• 硬體感知：工具會預估 VRAM 預算，並根據使用者可用的 GPU 數量過濾可執行的變體。
• 驗證：包含一組基準測試（bench.sh）與品質測試（quality-test.sh），用以驗證模型是否正確運行，並在不同提示與上下文長度下維持性能。
• 通用拉取：pull 工具會評估 HuggingFace safetensors 倉儲，判斷模型是否適合目前可用的硬體。

適用對象

• 擁有一或兩張 RTX 3090（或 4090/5090）的家用實驗室愛好者與開發者，希望在本地運行現代 LLM。
• 追求穩定性的使用者，希望避免「預填塞崖」（長提示時的 OOM 當機），並需要經過驗證、相容 OpenAI 的 API 端點。

主要亮點

• 多引擎支援：vLLM（最大吞吐量）、llama.cpp（最大穩健性/上下文）、ik_llama（最佳化的 GGUF 量化）的驗證食譜。
• Llama 風格 TUI：基於鍵盤的終端機 UI（c3），用於發現、部署與監控模型。
• 詳細基準測試：內建工具用於吞吐量（TPS）與行為品質測試。
• 硬體專用食譜：針對單卡（最高 200K 上下文）與雙卡（最高 262K 上下文）設定的特定配置。
• 跨設備診斷：報告工具（report.sh）可產生脫敏、可複製的硬體與堆疊報告，用於故障排除。