Unsloth MCP Server

Unsloth MCP 服务

一个用于 Unsloth 的 MCP 服务。Unsloth 是一个可将大模型微调速度提升 2 倍、内存占用减少 80% 的库。

什么是 Unsloth？

Unsloth 是一个可大幅提升大模型微调效率的库：

• 速度：与标准方法相比，微调速度提升 2 倍
• 内存：VRAM 使用量减少 80%，让消费级 GPU 也能微调更大的模型
• 上下文长度：上下文长度最多可延长 13 倍（例如，在 80GB GPU 上，Llama 3.3 可支持 89K 个 token）
• 准确性：模型质量和性能均无损失

Unsloth 通过使用 OpenAI 的 Triton 语言编写的自定义 CUDA 内核、优化的反向传播和动态 4 位量化实现这些改进。

功能

• 优化 Llama、Mistral、Phi、Gemma 和其他模型的微调
• 通过 4 位量化实现高效训练
• 支持扩展上下文长度
• 提供用于模型加载、微调和推理的简单 API
• 可导出为多种格式（GGUF、Hugging Face 等）

安装

当前状态：请从源码安装（见下文）。此软件包已准备好发布到 npm （name、bin、server.json 注册表清单均已就绪），但尚未发布——下一节中基于 npx 的配置只有在 npm 发布后才能使用。

1. 在运行微调的机器上安装 Unsloth：pip install unsloth

2. 从源码构建服务：

   git clone https://github.com/OtotaO/unsloth-mcp-server.git
   cd unsloth-mcp-server
   npm install
   npm run build
   

3. 将 MCP 客户端（Claude Desktop、Claude Code、Cline、Cursor 等）指向构建后的入口文件：

   {
     "mcpServers": {
       "unsloth": {
         "command": "node",
         "args": ["/path/to/unsloth-mcp-server/build/index.js"],
         "env": { "HUGGINGFACE_TOKEN": "your_token_here" }
       }
     }
   }
   

   HUGGINGFACE_TOKEN 是可选项（仅门控/私有模型需要）。如果不使用该令牌，请省略 env 块。

npm 发布后（计划中）

发布到 npm，包名为 unsloth-mcp-server 后，相同的客户端即可通过 npx 使用 stdio 运行，无需克隆或构建：

{
  "mcpServers": {
    "unsloth": {
      "command": "npx",
      "args": ["-y", "unsloth-mcp-server"],
      "env": { "HUGGINGFACE_TOKEN": "your_token_here" }
    }
  }
}

对于 Claude Code：claude mcp add unsloth -- npx -y unsloth-mcp-server

可用工具

check_installation

验证系统上是否正确安装了 Unsloth。

参数：无

示例：

const result = await use_mcp_tool({
  server_name: "unsloth",
  tool_name: "check_installation",
  arguments: {}
});

list_supported_models

获取 Unsloth 支持的所有模型列表，包括 Llama、Mistral、Phi 和 Gemma 的变体。

参数：无

示例：

const result = await use_mcp_tool({
  server_name: "unsloth",
  tool_name: "list_supported_models",
  arguments: {}
});

load_model

加载经过 Unsloth 优化的预训练模型，以加快推理和微调速度。

参数：

• model_name（必需）：要加载的模型名称（例如："unsloth/Llama-3.2-1B"）
• max_seq_length（可选）：模型的最大序列长度（默认值：2048）
• load_in_4bit（可选）：是否以 4 位量化方式加载模型（默认值：true）
• use_gradient_checkpointing（可选）：是否使用梯度检查点以节省内存（默认值：true）

示例：

const result = await use_mcp_tool({
  server_name: "unsloth",
  tool_name: "load_model",
  arguments: {
    model_name: "unsloth/Llama-3.2-1B",
    max_seq_length: 4096,
    load_in_4bit: true
  }
});

finetune_model

使用 LoRA/QLoRA 技术和 Unsloth 优化来微调模型。

参数：

• model_name（必需）：要微调的模型名称
• dataset_name（必需）：用于微调的数据集名称
• output_dir（必需）：保存微调后模型的目录
• max_seq_length（可选）：训练的最大序列长度（默认值：2048）
• lora_rank（可选）：LoRA 微调的秩（默认值：16）
• lora_alpha（可选）：LoRA 微调的 Alpha 值（默认值：16）
• batch_size（可选）：训练的批次大小（默认值：2）
• gradient_accumulation_steps（可选）：梯度累积步数（默认值：4）
• learning_rate（可选）：训练的学习率（默认值：2e-4）
• max_steps（可选）：最大训练步数（默认值：100）
• dataset_text_field（可选）：数据集中包含文本的字段（默认值：'text'）
• load_in_4bit（可选）：是否使用 4 位量化（默认值：true）

示例：

const result = await use_mcp_tool({
  server_name: "unsloth",
  tool_name: "finetune_model",
  arguments: {
    model_name: "unsloth/Llama-3.2-1B",
    dataset_name: "tatsu-lab/alpaca",
    output_dir: "./fine-tuned-model",
    max_steps: 100,
    batch_size: 2,
    learning_rate: 2e-4
  }
});

generate_text

使用经过微调的 Unsloth 模型生成文本。

参数：

• model_path（必需）：经过微调的模型路径
• prompt（必需）：用于生成文本的提示词
• max_new_tokens（可选）：要生成的最大 token 数量（默认：256）
• temperature（可选）：文本生成温度（默认：0.7）
• top_p（可选）：文本生成的 top-p 值（默认：0.9）

示例：

const result = await use_mcp_tool({
  server_name: "unsloth",
  tool_name: "generate_text",
  arguments: {
    model_path: "./fine-tuned-model",
    prompt: "Write a short story about a robot learning to paint:",
    max_new_tokens: 512,
    temperature: 0.8
  }
});

export_model

将经过微调的 Unsloth 模型导出为多种格式，以便部署。

参数：

• model_path（必需）：经过微调的模型路径
• export_format（必需）：要导出的格式（gguf、ollama、vllm、huggingface）
• output_path（必需）：保存导出模型的路径
• quantization_bits（可选）：量化位数（用于 GGUF 导出）（默认：4）

示例：

const result = await use_mcp_tool({
  server_name: "unsloth",
  tool_name: "export_model",
  arguments: {
    model_path: "./fine-tuned-model",
    export_format: "gguf",
    output_path: "./exported-model.gguf",
    quantization_bits: 4
  }
});

高级用法

自定义数据集

你可以正确设置自定义数据集的格式，并将其托管在 Hugging Face 上，或提供本地路径：

const result = await use_mcp_tool({
  server_name: "unsloth",
  tool_name: "finetune_model",
  arguments: {
    model_name: "unsloth/Llama-3.2-1B",
    dataset_name: "json",
    data_files: {"train": "path/to/your/data.json"},
    output_dir: "./fine-tuned-model"
  }
});

内存优化

对于硬件资源有限的大型模型：

• 减小批量大小并增加梯度累积步数
• 使用 4 位量化
• 启用梯度检查点
• 尽可能缩短序列长度

故障排除

常见问题

1. CUDA 内存不足：减小批量大小、使用 4 位量化，或尝试更小的模型
2. 导入错误：确保已安装正确版本的 torch、transformers 和 unsloth
3. 未找到模型：检查使用的模型名称是否受支持，或是否有权访问私有模型

版本兼容性

• Python：3.10、3.11 或 3.12（不支持 3.13）
• CUDA：建议使用 11.8 或 12.1 及以上版本
• PyTorch：建议使用 2.0 及以上版本

性能基准

模型	显存	Unsloth 速度	显存减少量	上下文长度
Llama 3.3（70B）	80GB	快 2 倍	>75%	长 13 倍
Llama 3.1（8B）	80GB	快 2 倍	>70%	长 12 倍
Mistral v0.3（7B）	80GB	快 2.2 倍	减少 75%	-

要求

• Python 3.10-3.12
• 支持 CUDA 的 NVIDIA GPU（推荐）
• Node.js 和 npm

许可证

Apache-2.0