Michael-A-Kuykendall/shimmy

## 本地 LLM 的直接替代 OpenAI API 方案 Shimmy 是一个**单一二进制文件**，为 GGUF 模型提供 **100% 兼容 OpenAI 的端点**。将您现有的 AI 工具指向 Shimmy，它们就能直接运行——本地、私密且免费。 **🎉 v1.9.0 新特性**：一次下载，包含所有 GPU 后端！无需编译，没有后端困惑——只需下载即可运行。 ## 开发者工具 无论您是派生 (Fork) Shimmy 还是将作为服务集成，我们都提供完整的文档和集成模板。 ### 30 秒内试用 ``` # 1) 下载预编译二进制文件（包含所有 GPU 后端） # Windows: curl -L https://github.com/Michael-A-Kuykendall/shimmy/releases/latest/download/shimmy-windows-x86_64.exe -o shimmy.exe ./shimmy.exe serve & # Linux: curl -L https://github.com/Michael-A-Kuykendall/shimmy/releases/latest/download/shimmy-linux-x86_64 -o shimmy && chmod +x shimmy ./shimmy serve & # macOS (Apple Silicon): curl -L https://github.com/Michael-A-Kuykendall/shimmy/releases/latest/download/shimmy-macos-arm64 -o shimmy && chmod +x shimmy ./shimmy serve & # 2) 查看模型并选择一个 ./shimmy list # 3) 对 OpenAI API 进行冒烟测试 curl -s http://127.0.0.1:11435/v1/chat/completions \ -H 'Content-Type: application/json' \ -d '{ "model":"REPLACE_WITH_MODEL_FROM_list", "messages":[{"role":"user","content":"Say hi in 5 words."}], "max_tokens":32 }' | jq -r '.choices[0].message.content' ``` ## 🚀 兼容 OpenAI SDK 和工具 **无需更改代码** - 只需更改 API 端点： - **任何 OpenAI 客户端**：Python、Node.js、curl 等。 - **开发应用程序**：兼容标准 SDK - **VSCode 扩展**：指向 `http://localhost:11435` - **Cursor 编辑器**：内置 OpenAI 兼容性 - **Continue.dev**：直接替代的模型提供者 ### 与 OpenAI SDK 配合使用 - Node.js (openai v4) ``` import OpenAI from "openai"; const openai = new OpenAI({ baseURL: "http://127.0.0.1:11435/v1", apiKey: "sk-local", // placeholder, Shimmy ignores it }); const resp = await openai.chat.completions.create({ model: "REPLACE_WITH_MODEL", messages: [{ role: "user", content: "Say hi in 5 words." }], max_tokens: 32, }); console.log(resp.choices[0].message?.content); ``` - Python (openai>=1.0.0) ``` from openai import OpenAI client = OpenAI(base_url="http://127.0.0.1:11435/v1", api_key="sk-local") resp = client.chat.completions.create( model="REPLACE_WITH_MODEL", messages=[{"role": "user", "content": "Say hi in 5 words."}], max_tokens=32, ) print(resp.choices[0].message.content) ``` ## ⚡ 无需配置 - **自动查找模型**，支持 Hugging Face 缓存、Ollama、本地目录 - **自动分配端口**以避免冲突 - **自动检测 LoRA 适配器**以适应专用模型 - **开箱即用** - 无需配置文件，无需设置向导 ## 🧠 高级 MOE (混合专家模型) 支持 **在消费级硬件上运行 70B+ 模型**，支持智能 CPU/GPU 混合处理： - **🔄 CPU MOE 卸载**：自动在 CPU 和 GPU 之间分配模型层 - **🧮 智能层放置**：优化各层的运行位置以实现最大性能 - **💾 内存效率**：通过策略性使用系统 RAM，在有限的 VRAM 中容纳更大的模型 - **⚡ 混合加速**：在最重要的地方获得 GPU 速度，在其他地方获得 CPU 的可靠性 - **🎛️ 可配置**：提供 `--cpu-moe` 和 `--n-cpu-moe` 标志以进行精细控制 ``` # 在安装期间启用 MOE CPU offloading cargo install shimmy --features moe # 使用 MOE 混合处理运行 shimmy serve --cpu-moe --n-cpu-moe 8 # 自动平衡：GPU layers（速度快）+ CPU layers（内存效率高） ``` **非常适合**：大型模型 (70B+)、VRAM 受限的系统、高性价比推理 ## 🎯 非常适合本地开发 - **隐私**：您的代码永远不会离开您的机器 - **成本**：无需 API 密钥，无按 token 计费 - **速度**：本地推理，亚秒级响应 - **可靠性**：无速率限制，无停机时间 ## 快速开始 (30 秒) ### 安装 **✨ v1.9.0 新特性**：下载包含所有 GPU 后端的预编译二进制文件！ #### **📥 预编译二进制文件 (推荐 - 零依赖)** 选择您的平台并下载 - 无需编译： ``` # Windows x64（包含 CUDA + Vulkan + OpenCL） curl -L https://github.com/Michael-A-Kuykendall/shimmy/releases/latest/download/shimmy-windows-x86_64.exe -o shimmy.exe # Linux x86_64（包含 CUDA + Vulkan + OpenCL） curl -L https://github.com/Michael-A-Kuykendall/shimmy/releases/latest/download/shimmy-linux-x86_64 -o shimmy && chmod +x shimmy # macOS ARM64（包含适用于 Apple Silicon 的 MLX） curl -L https://github.com/Michael-A-Kuykendall/shimmy/releases/latest/download/shimmy-macos-arm64 -o shimmy && chmod +x shimmy # macOS Intel（仅限 CPU） curl -L https://github.com/Michael-A-Kuykendall/shimmy/releases/latest/download/shimmy-macos-intel -o shimmy && chmod +x shimmy # Linux ARM64（仅限 CPU） curl -L https://github.com/Michael-A-Kuykendall/shimmy/releases/latest/download/shimmy-linux-aarch64 -o shimmy && chmod +x shimmy ``` **就是这样！** 您的 GPU 将在运行时被自动检测到。 #### **🛠️ 从源码构建 (高级)** 想要自定义或贡献代码？ ``` # 基本安装（仅限 CPU） cargo install shimmy --features huggingface # Kitchen Sink 构建（预编译二进制文件所使用的）： # Windows/Linux x64: cargo install shimmy --features huggingface,llama,llama-cuda,llama-vulkan,llama-opencl,vision # macOS ARM64: cargo install shimmy --features huggingface,llama,mlx,vision # 仅限 CPU（任何平台）： cargo install shimmy --features huggingface,llama,vision ``` ### GPU 加速 **✨ v1.9.0 的新功能**：每个平台一个二进制文件，并带有自动 GPU 检测！ #### **📥 下载预编译二进制文件 (推荐)** 无需编译！每个二进制文件都包含适用于您平台的所有 GPU 后端： | 平台 | 下载 | GPU 支持 | 自动检测 | |----------|----------|-------------|--------------| | **Windows x64** | [shimmy-windows-x86_64.exe](https://github.com/Michael-A-Kuykendall/shimmy/releases/latest/download/shimmy-windows-x86_64.exe) | CUDA + Vulkan + OpenCL | ✅ | | **Linux x86_64** | [shimmy-linux-x86_64](https://github.com/Michael-A-Kuykendall/shimmy/releases/latest/download/shimmy-linux-x86_64) | CUDA + Vulkan + OpenCL | ✅ | | **macOS ARM64** | [shimmy-macos-arm64](https://github.com/Michael-A-Kuykendall/shimmy/releases/latest/download/shimmy-macos-arm64) | MLX (Apple Silicon) | ✅ | | **macOS Intel** | [shimmy-macos-intel](https://github.com/Michael-A-Kuykendall/shimmy/releases/latest/download/shimmy-macos-intel) | 仅 CPU | 不适用 | | **Linux ARM64** | [shimmy-linux-aarch64](https://github.com/Michael-A-Kuykendall/shimmy/releases/latest/download/shimmy-linux-aarch64) | 仅 CPU | 不适用 | **工作原理**：下载一个文件并运行它。Shimmy 会自动检测并使用您的 GPU！ ``` # Windows 示例 curl -L https://github.com/Michael-A-Kuykendall/shimmy/releases/latest/download/shimmy-windows-x86_64.exe -o shimmy.exe ./shimmy.exe serve --gpu-backend auto # Auto-detects CUDA/Vulkan/OpenCL # Linux 示例 curl -L https://github.com/Michael-A-Kuykendall/shimmy/releases/latest/download/shimmy-linux-x86_64 -o shimmy chmod +x shimmy ./shimmy serve --gpu-backend auto # Auto-detects CUDA/Vulkan/OpenCL # macOS ARM64 示例 curl -L https://github.com/Michael-A-Kuykendall/shimmy/releases/latest/download/shimmy-macos-arm64 -o shimmy chmod +x shimmy ./shimmy serve # Auto-detects MLX on Apple Silicon ``` #### **🎯 GPU 自动检测** Shimmy 使用智能 GPU 检测，遵循以下优先级顺序： 1. **CUDA** (通过 nvidia-smi 检测 NVIDIA GPU) 2. **Vulkan** (通过 vulkaninfo 检测跨平台 GPU) 3. **OpenCL** (通过 clinfo 检测 AMD/Intel GPU) 4. **MLX** (通过系统检测 Apple Silicon) 5. **CPU** (未检测到 GPU 时的回退方案) **无需手动配置！** 只需使用 `--gpu-backend auto` 运行（默认）。 #### **🔧 手动后端覆盖** 想要强制指定特定的后端？使用 `--gpu-backend` 标志： ``` # 自动检测（默认 - 推荐） shimmy serve --gpu-backend auto # 强制 CPU（用于测试或兼容性） shimmy serve --gpu-backend cpu # 强制 CUDA（仅限 NVIDIA GPU） shimmy serve --gpu-backend cuda # 强制 Vulkan（AMD/Intel/跨平台） shimmy serve --gpu-backend vulkan # 强制 OpenCL（AMD/Intel 替代方案） shimmy serve --gpu-backend opencl ``` **🛡️ 错误处理与健壮性**：如果您强制指定了一个不可用的后端（例如，在 AMD GPU 上使用 `--gpu-backend cuda`），Shimmy 将会： 1. ✅ 显示清晰的错误消息解释问题 2. ✅ 自动回退到优先级顺序中的下一个可用后端 3. ✅ 记录实际使用的后端（使用 `--verbose` 检查） 4. ✅ 继续处理请求（优雅降级，不会崩溃） 5. ✅ 支持环境变量覆盖：`SHIMMY_GPU_BACKEND=cuda` **常见场景**： - 在非 NVIDIA 显卡上使用 `--gpu-backend cuda` → 回退到 Vulkan 或 OpenCL - 在未安装驱动的情况下使用 `--gpu-backend vulkan` → 回退到 OpenCL 或 CPU - 使用 `--gpu-backend invalid` → 清晰的错误提示 + 回退到自动检测 - 未检测到 GPU → 在 CPU 上运行并显示性能警告 **环境变量**：设置 `SHIMMY_GPU_BACKEND=cuda` 可在不使用 CLI 标志的情况下覆盖默认设置。 #### **🔍 检查 GPU 支持** ``` # 显示检测到的 GPU 后端 shimmy gpu-info # 检查正在使用的后端 shimmy serve --gpu-backend auto --verbose ``` #### **⚡ 二进制文件大小** - **启用 GPU 的二进制文件** (Windows/Linux x64, macOS ARM64)：约 40-50MB - **仅限 CPU 的二进制文件** (macOS Intel, Linux ARM64)：约 20-30MB 权衡：二进制文件稍大，但无需编译且能自动检测 GPU。 #### **🛠️ 从源码构建 (高级)** 想要自定义或贡献代码？从源码构建： - 可以编译进多个后端，并自动选择最佳的一个 - 使用 `--gpu-backend ` 强制指定后端 ### 获取模型 Shimmy 自动从以下位置发现模型： - **Hugging Face 缓存**：`~/.cache/huggingface/hub/` - **Ollama 模型**：`~/.ollama/models/` - **本地目录**：`./models/` - **环境变量**：`SHIMMY_BASE_GGUF=path/to/model.gguf` ``` # 下载开箱即用的模型 huggingface-cli download microsoft/Phi-3-mini-4k-instruct-gguf --local-dir ./models/ huggingface-cli download bartowski/Llama-3.2-1B-Instruct-GGUF --local-dir ./models/ ``` ### 启动服务器 ``` # 自动分配端口以避免冲突 shimmy serve # 或使用手动端口 shimmy serve --bind 127.0.0.1:11435 ``` 将您的开发工具指向显示的端口 —— VSCode Copilot、Cursor、Continue.dev 均可立即使用。 ## 📦 下载与安装 ### 包管理器 - **Rust**: [`cargo install shimmy --features moe`](https://crates.io/crates/shimmy) *(推荐)* - **Rust (基础版)**: [`cargo install shimmy`](https://crates.io/crates/shimmy) - **VS Code**: [Shimmy 扩展](https://marketplace.visualstudio.com/items?itemName=targetedwebresults.shimmy-vscode) - **Windows MSVC**：使用 `shimmy-llama-cpp-2` 包以获得更好的兼容性 - **npm**: `npm install -g shimmy-js` *(计划中)* - **Python**: `pip install shimmy` *(计划中)* ### 直接下载 - **GitHub Releases**: [最新二进制文件](https://github.com/Michael-A-Kuykendall/shimmy/releases/latest) - **Docker**: `docker pull shimmy/shimmy:latest` *(即将推出)* ### 🍎 macOS 支持 **已确认完全兼容！** Shimmy 在 macOS 上配合 Metal GPU 加速运行完美。 ``` # 安装依赖 brew install cmake rust # 安装 shimmy cargo install shimmy ``` **✅ 已验证可用：** - Intel 和 Apple Silicon Mac - Metal GPU 加速（自动） - 专为 Apple Silicon 提供的 MLX 原生加速 - Xcode 17+ 兼容性 - 所有 LoRA 适配器功能 ## 集成示例 ### VSCode Copilot ``` { "github.copilot.advanced": { "serverUrl": "http://localhost:11435" } } ``` ### Continue.dev ``` { "models": [{ "title": "Local Shimmy", "provider": "openai", "model": "your-model-name", "apiBase": "http://localhost:11435/v1" }] } ``` ### Cursor IDE 开箱即用 - 只需指向 `http://localhost:11435/v1` ## 为什么 Shimmy 将永远免费 我开发 Shimmy 是为了在 AI 开发中保持隐私优先的控制，并让一切保持本地化和轻量化。 **这是我的承诺**：Shimmy 将永远保持 MIT 许可。如果您想支持开发，请[赞助它](https://github.com/sponsors/Michael-A-Kuykendall)。如果不想，只需用它构建出酷炫的东西即可。 ## API 参考 ### 端点 - `GET /health` - 健康检查 - `POST /v1/chat/completions` - 兼容 OpenAI 的聊天 - `GET /v1/models` - 列出可用模型 - `POST /api/generate` - Shimmy 原生 API - `GET /ws/generate` - WebSocket 流式传输 ### CLI 命令 ``` shimmy serve # Start server (auto port allocation) shimmy serve --bind 127.0.0.1:8080 # Manual port binding shimmy serve --cpu-moe --n-cpu-moe 8 # Enable MOE CPU offloading shimmy list # Show available models (LLM-filtered) shimmy discover # Refresh model discovery shimmy generate --name X --prompt "Hi" # Test generation shimmy probe model-name # Verify model loads shimmy gpu-info # Show GPU backend status ``` ## 技术架构 - **Rust + Tokio**：内存安全，异步高性能 - **llama.cpp 后端**：行业标准的 GGUF 推理 - **OpenAI API 兼容性**：直接替代 - **动态端口管理**：零冲突，自动分配 - **零配置自动发现**：开箱即用™ ### 🚀 高级功能 - **🧠 MOE CPU 卸载**：针对大型模型 (70B+) 的 GPU/CPU 混合处理 - **🎯 智能模型过滤**：自动排除非语言模型 (Stable Diffusion, Whisper, CLIP) - **🛡️ 6重门控发布验证**：结构化质量限制确保可靠性 - **⚡ 智能模型预加载**：带有使用情况跟踪的后台加载，实现瞬间模型切换 - **💾 响应缓存**：LRU + TTL 缓存为重复查询带来 20-40% 的性能提升 - **🚀 集成模板**：针对 Docker, Kubernetes, Railway, Fly.io, FastAPI, Express 的一键部署 - **🔄 请求路由**：支持带有健康检查和负载均衡的多实例部署 - **📊 高级可观测性**：带有自我优化和 Prometheus 集成的实时指标 - **🔗 RustChain 集成**：带有工作流编排的通用工作流转译 ## 社区与支持 - **🐛 Bug 报告**: [GitHub Issues](https://github.com/Michael-A-Kuykendall/shimmy/issues) - **💬 讨论区**: [GitHub Discussions](https://github.com/Michael-A-Kuykendall/shimmy/discussions) - **📖 文档**: [docs/](docs/) • [工程方法论](docs/METHODOLOGY.md) • [OpenAI 兼容性矩阵](docs/OPENAI_COMPAT.md) • [基准测试 (可重现)](docs/BENCHMARKS.md) - **💝 赞助**: [GitHub Sponsors](https://github.com/sponsors/Michael-A-Kuykendall) ### Star 历史 [](https://www.star-history.com/#Michael-A-Kuykendall/shimmy&Timeline) ### 🚀 发展势头快照 📦 **小于 5MB 的单一二进制文件** (比 Ollama 小 142 倍) 🌟 ** 颗星且增长迅速** ⏱ **<1s 启动时间** 🦀 **100% Rust 编写无 Python** ### 📰 特色报道 🔥 [**Hacker News**](https://news.ycombinator.com/item?id=45130322) • [**再次登上首页**](https://news.ycombinator.com/item?id=45199898) • [**IPE 时事通讯**](https://ipenewsletter.substack.com/p/the-strange-new-side-hustles-of-openai) **企业用户**：需要发票？请发送邮件至 [michaelallenkuykendall@gmail.com](mailto:michaelallenkuykendall@gmail.com) ## ⚡ 性能对比 | 工具 | 二进制文件大小 | 启动时间 | 内存使用 | OpenAI API | |------|-------------|--------------|--------------|------------| | **Shimmy** | **4.8MB** | **<100ms** | **50MB** | **100%** | | Ollama | 680MB | 5-10s | 200MB+ | 部分 | | llama.cpp | 89MB | 1-2s | 100MB | 通过 llama-server | ## 质量与可靠性 Shimmy 通过全面的测试保持高代码质量： - **全面的测试套件**，结合基于属性的测试 - **带有质量门禁的自动化 CI/CD 流水线** - **针对关键操作的运行时不变量检查** - **跨平台兼容性测试** ### 开发测试 运行完整的测试套件： ``` # 使用 cargo alias cargo test-quick # Quick development tests # 使用 Makefile make test # Full test suite make test-quick # Quick development tests ``` 有关技术细节，请参阅我们的[测试方法](docs/ppt-invariant-testing.md)。 ## 许可证与理念 MIT 许可证 - 永远如此。 **理念**：基础设施应该是无形的。Shimmy 就是基础设施。 **测试理念**：通过全面的验证和基于属性的测试来保证可靠性。 **永久维护者**：Michael A. Kuykendall **承诺**：这永远不会成为付费产品 **使命**：让本地模型推理变得简单可靠

标签：API代理, GGUF, LangChain, LLM推理服务器, OpenAI API, Rust, SafeTensors, Vectored Exception Handling, Veh, 免费, 单文件部署, 可视化界面, 大模型部署, 实时告警, 开源, 无依赖, 服务枚举, 服务端, 本地AI, 本地大模型, 本地推理, 本地模型, 模型热更新, 深度学习, 私有化部署, 网络流量审计, 自动发现, 轻量级, 通知系统, 防御规避