Shimmy 是一个纯 Rust 编写的、单二进制文件的 OpenAI

Shimmy 是一个纯 Rust 编写的、单二进制文件的 OpenAI 兼容型本地 LLM 推理服务器，主打轻量、快速和完全本地化。

本教程将覆盖从安装、模型配置到服务启动和客户端集成的完整过程。

📥 第一步：安装 Shimmy

Shimmy 提供了两种主要安装方式，推荐直接下载预编译二进制文件以获取完整的 GPU 支持。

方式一：下载预编译二进制文件（推荐）
这是最快的方式，二进制文件已包含 Airframe GPU 引擎，无需额外安装 CUDA 或 Vulkan SDK。从 GitHub Releases 页面下载对应系统文件：

Linux (x86_64): shimmy-linux-x86_64
macOS (Apple Silicon): shimmy-macos-arm64
Windows (x64): shimmy-windows-x86_64.exe

下载后，在终端中将其放在系统路径下，并赋予执行权限（Linux/macOS）：

1
2
3

# 以 Linux/macOS 为例
chmod +x shimmy
sudo mv shimmy /usr/local/bin/  # 或放置在任何 PATH 目录下

方式二：通过 Cargo 安装（开发者）
如果你已安装 Rust 工具链，也可以使用 Cargo 安装。但请注意，这样安装的可能是 HuggingFace 后端引擎。

1	cargo install shimmy

📂 第二步：准备模型文件

Shimmy 支持 GGUF 格式模型，并能自动在多个常见路径发现它们。

支持的路径：./models/（当前目录下）、~/.cache/huggingface/hub/（Hugging Face 缓存）、~/.ollama/models/（Ollama 模型目录）。
环境变量指定：通过 SHIMMY_BASE_GGUF 环境变量指定一个确定的模型文件路径。

下载示例模型（以 TinyLlama 为例）：

1
2
3

# 使用 huggingface-cli 下载
huggingface-cli download TheBloke/TinyLlama-1.1B-Chat-v1.0-GGUF \
  --include "tinyllama-1.1b-chat-v1.0.Q4_0.gguf" --local-dir ./models/

🚀 第三步：启动服务

一切准备就绪后，在终端中运行以下命令即可启动 Shimmy 服务器。

1	shimmy serve

默认地址：服务会运行在 http://localhost:11435，如果端口被占用会自动分配。
常用选项：
- 指定端口：shimmy serve --bind 127.0.0.1:8080。
- 指定模型：shimmy serve --model /path/to/model.gguf。

🔌 第四步：与你的 AI 工具集成

Shimmy 提供 OpenAI 兼容的 API 端点，因此你可以轻松地将它用作现有 AI 工具的后端。

使用 cURL 测试：

curl -X POST http://localhost:11435/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tinyllama-1.1b",
    "messages": [{"role": "user", "content": "Say hi in 5 words."}],
    "max_tokens": 32
  }'

集成到 IDE：

VSCode Copilot：在 settings.json 中添加：

1 2	{ "github.copilot.advanced": { "serverUrl": "http://localhost:11435" } } ```[citation:1][citation:4]

Continue.dev：在配置中添加：

"models": [{
  "title": "Local Shimmy",
  "provider": "openai",
  "model": "your-model-name",
  "apiBase": "http://localhost:11435/v1"
}]
```[citation:1][citation:4]

Cursor：直接在设置中将自定义端点指向 http://localhost:11435。

🐳 可选：使用 Docker 部署

对于喜欢容器化环境的用户，Shimmy 也提供了 Docker 支持。

准备模型目录：在本地创建一个目录（如 ./models）并放入 GGUF 模型文件。
启动容器：使用以下命令将模型目录挂载到容器内并启动服务。
1
docker run -v $(pwd)/models:/app/models -p 11435:11435 ghcr.io/michael-a-kuykendall/shimmy:latest
或使用项目提供的 docker-compose.yml 文件。

⚙️ 常用配置与环境变量

你可以通过环境变量对 Shimmy 进行精细化控制。

环境变量	描述	示例
`SHIMMY_BASE_GGUF`	指定默认加载的 GGUF 模型文件路径	`export SHIMMY_BASE_GGUF=/models/phi-3.gguf`
`SHIMMY_MAX_CTX`	覆盖模型的最大上下文窗口，支持 YaRN 扩展	`export SHIMMY_MAX_CTX=8192`
`SHIMMY_KV_QUANT`	KV 缓存量化类型，`int4` 可显著降低显存使用	`export SHIMMY_KV_QUANT=int4`
`SHIMMY_BIND_ADDRESS`	服务绑定的地址和端口	`export SHIMMY_BIND_ADDRESS=0.0.0.0:11435`