使用 Unsloth 和 Pi 编程代理设置 Qwen3.6-27B

我一直想要一个可以在真实代码库中工作的本地编程代理，而不需要每月花费 100 美元。经过大量的反复试验，我最终确定了以下方案：

• Unsloth Studio 作为本地兼容 OpenAI 的 API 服务。
• Unsloth GGUF 版本的 Qwen3.6-27B 模型，用于笔记本电脑或工作站的推理。
• Pi Coding Agent 作为终端中的编程执行环境。

简而言之：下载 GGUF 模型，让 Unsloth Studio 指向该模型运行，然后将 Pi 指向 Studio 的端点。或者，你可以把这套配置交给一个代理自动完成。

如果你已经在使用 Claude Code、Codex 或其他编程代理，可以跳过本文其余部分。只需粘贴以下提示词，让它自动完成所有工作（涵盖下文所有内容及注意事项）：

顺便提一下，我的电脑是搭载 M4 Max 芯片且拥有 36GB 内存的 MacBook Pro。查看 @fiveoutofnine 制作的 https://www.whatcani.run/，看看你的设备是否支持运行该模型。

如果你更喜欢手动操作（或者想了解每一步的细节），请继续阅读。

为什么选择 Qwen3.6-27B？

Qwen3.6-27B 在编程代理领域占据了一个非常实用的中间位置。它既不是小型的代码自动补全模型，也不是只有依赖云端 API 才有意义的大规模模型。官方 Qwen 模型卡片将其描述为一款拥有视觉编码器、长上下文支持，并专注于代理式编程和仓库级推理的 27B 模型。对于本地编程代理来说，这比聊天基准测试的“氛围感”更为重要。代理需要读取文件、推理代码库、进行修改、从工具错误中恢复，并在长任务中保持连贯性。

对于消费级硬件，我建议从 Unsloth 的 GGUF 量化版本开始，而不是原始的 BF16 检查点。BF16 模型适合拥有多 GPU 的专业工作站。如果你希望在开发者机器上运行，GGUF 路线是更实际的选择。

你需要准备什么

在 macOS 上，最快的路径是：

# 安装 Unsloth Studio
brew install unsloth-studio

# 安装 Pi
brew install pi-dev/tap/pi

在 Linux 上，以相同方式安装 Pi。Unsloth 的安装脚本在 Linux 上同样有效。

确认两者都在 PATH 中：

which unsloth
which pi

下载模型

UD-Q4_K_XL 量化的 27B GGUF 模型大小约为 16 GB。将其一次性拉取到已知路径：

curl -L -C - https://huggingface.co/unsloth/Qwen3.6-27B-GGUF/resolve/main/Qwen3.6-27B-UD-Q4_K_XL.gguf -o ~/models/Qwen3.6-27B-UD-Q4_K_XL.gguf

-C - 参数可以从当前字节偏移量恢复下载，因此如果连接中断，你可以重新运行相同的命令，它会从断点处继续。不要同时运行两个此命令的副本，否则它们都会写入文件并导致文件损坏。

你也可以让 Studio 在首次运行时下载模型，但 CLI 可能会在 16 GB 的冷下载完成之前超时。自己拉取 GGUF 模型更可预测。

启动本地模型服务器

unsloth studio run --model ~/models/Qwen3.6-27B-UD-Q4_K_XL.gguf --max-seq-length 16384

在拥有 36 GB 内存的 Apple Silicon Mac 上，16384 是一个合理的默认值；如果你有更多内存，可以调高（见下文硬件注意事项）。

当服务器就绪时，你会看到类似以下内容：

API Key: sk-unsloth-xxxx...
Server running at http://127.0.0.1:8888

保存 API 密钥。Studio 仅存储哈希值；它不会再显示明文密钥。

验证端点是否正常：

curl http://127.0.0.1:8888/v1/models -H "Authorization: Bearer <YOUR_API_KEY>"

你应该会收到一个包含一个条目的 JSON 列表。id 是你加载的完整路径。请保留该字符串以备后用。

配置 Pi

创建或编辑 ~/.pi/agent/models.json。替换为你自己的 API 密钥和你使用的模型路径：

{
  "unsloth-studio": {
    "base_url": "http://127.0.0.1:8888/v1",
    "api_key": "<YOUR_API_KEY>",
    "models": [
      {
        "id": "~/models/Qwen3.6-27B-UD-Q4_K_XL.gguf",
        "compat": {
          "strip_reasoning": true,
          "force_system_role": true
        }
      }
    ]
  }
}

兼容标志（compat flags）很重要。本地兼容 OpenAI 的服务接近 OpenAI API，但并不完全相同，Studio 会拒绝像 developer 角色和 reasoning_effort 这样的字段。

你可以确认 Pi 是否能看到该模型：

pi models

让 Pi 默认使用 Qwen

每次输入 --provider unsloth-studio --model /Users/you/... 很快就会让人厌烦。Pi 从 ~/.pi/agent/settings.json 读取默认值。添加这两个键（与任何现有内容合并。Pi 会在那里写入自己的键，如 lastChangelogVersion）：

{
  "defaultProvider": "unsloth-studio",
  "defaultModel": "~/models/Qwen3.6-27B-UD-Q4_K_XL.gguf"
}

之后，在任何目录中直接运行 pi 即可使用本地模型。当你想要与托管模型进行比较时，仍然可以通过 --provider / --model 在每次调用时覆盖默认设置。

在代码库中运行 Pi

先尝试一个只读的小任务：

阅读项目结构并解释应用程序是如何启动的。暂时不要编辑文件。

然后是一个受限的编辑任务：

在代码库中找到一个低风险 bug 或清理项，进行更改，并运行最相关的狭窄测试。

这就是设置变得有用的地方。Pi 是编程执行环境（harness）。Qwen 是本地推理引擎。Unsloth Studio 是它们之间的适配器。

硬件注意事项

--max-seq-length 是主要的调节旋钮。27B 模型加上大的 KV 缓存会迅速消耗内存。

我在 macOS 上的起始规则：

• 36 GB Apple Silicon：16384 是实际的甜蜜点，对于真实编程任务足够长，同时每 token 延迟保持在可承受范围内。32768 可以工作，但随着上下文填充，生成速度会明显变慢。
• 64 GB 或更多：尝试 32768 或 65536。只有在你有足够冗余内存时才使用 131072。
• 如果遇到内存不足（OOM），先降低序列长度，再改变量化级别。
• UD-Q4_K_XL 是一个良好的质量基线。如果需要更快的速度，可以使用 Q3_K_XL。

无论你选择哪个数字，都要在 models.json 中将 contextWindow 设置为匹配值，否则 Pi 会尝试发送服务器无法处理的更长提示。

Qwen3.6 默认输出推理过程，完成结果包括最终答案前的 <thinking> 块，这些块作为 Pi 输出的一部分流式传输。你可以跟随阅读，或者忽略它们并快速浏览到答案。在 Apple Silicon 上，27B Q4 级别的生成速度约为 8 tok/s，因此每次响应前会有短暂的停顿。

对于长时间的编程会话，我更关心稳定性而不是最大基准性能。一个能够可靠地读取、编辑和测试小更改的本地模型，比一个在任务中途崩溃的最大化配置更有用。

Unsloth Studio UI 的作用

unsloth studio run 是无头的，它只提供 API 服务。如果你想要一个 UI 来浏览模型、测试提示或与加载的模型聊天：

unsloth studio ui

然后打开 http://127.0.0.1:8888。UI 共享相同的后端，因此你加载的任何模型也可以通过 /v1 访问。这适用于在向 Pi 放开编辑工具之前测试提示。

故障排除

Studio 在首次运行时打印 TimeoutError。

CLI 调用其自身的服务器来加载模型，并在 16 GB 的冷下载完成之前放弃。服务器会继续下载。要么等待 ~/.cache/huggingface/.../*.gguf 完成缓存并重新运行，要么使用上面的 curl -C - 步骤预先下载（推荐）。

Pi 看不到模型。直接点击端点：

curl http://127.0.0.1:8888/v1/models -H "Authorization: Bearer $KEY"

如果失败，问题在于 Studio，而不是 Pi。

Pi 在请求字段上出错。

保持 models.json 中的 compat 块。本地兼容 OpenAI 的端点通常拒绝较新的字段，如 developer 角色或 reasoning_effort。

生成感觉很慢。

在 Apple Silicon 上，27B Q4 级别 8 tok/s 是正常的。如果你没有使用完整的窗口，降低 --max-seq-length，加载时间和每 token 延迟都会改善。

Studio 的 sk-unsloth- 密钥丢失了。

Studio 仅显示一次密钥。停止服务器，使用 --api-key-name something 再次运行，启动时会打印一个新的密钥。旧的哈希仍然在磁盘上；你可以从 Studio 设置 UI 中修剪它。

最终观点

这是我目前会开始使用的本地编程代理堆栈：

Qwen3.6-27B GGUF → Unsloth Studio (localhost) → Pi Coding Agent → 你的代码库

它不会取代每个托管的前沿模型工作流。但它足以让“本地优先”的编程代理感觉真实：私有代码库上下文、零每 token 成本，以及一个真正为代理式编程而不是随意聊天而构建的模型。

参考

Unsloth Studio 文档: https://unsloth.ai/docs/new/studio Unsloth Studio 安装: https://unsloth.ai/docs/new/studio/install Unsloth Studio API: https://unsloth.ai/docs/basics/api Qwen3.6-27B GGUF: https://huggingface.co/unsloth/Qwen3.6-27B-GGUF Qwen3.6-27B 模型卡片: https://huggingface.co/Qwen/Qwen3.6-27B Pi 文档: https://pi.dev/docs/latest Pi 自定义模型: https://pi.dev/docs/latest/models