Unsloth Desktop 本地模型准备

接入边界

Unsloth Desktop 提供 OpenAI-compatible 本地服务，默认地址是 http://127.0.0.1:8888。Provider Agent 通过 --api-format unsloth 接入。

使用前必须先在 Unsloth Desktop 中手动加载目标模型。天池 Token 桌面端、网页控制台和 Provider Agent 只检查并使用当前已经加载的模型，不会执行模型加载、卸载或自动切换。

目标模型必须是 GGUF 格式，且量化精度最低为 Q4。Q1、Q2、Q3 量化版本不支持；Q4（包含 Q4_K_S、UD-Q4_K_M、IQ4_* 等命名）及更高精度版本可以使用。本页的 Qwen3.8 27B 示例推荐选择 Unsloth 原生的 UD-Q4_K_M 版本。如果 Provider Agent 无法从模型名称或元数据识别量化版本，预检会阻止启动；请换用量化信息明确的模型后重试。

关闭 API Key 鉴权

如果只在本机或可信的私有局域网中使用 Unsloth Desktop，可以让 Provider Agent 免 API Key 访问推理接口：

1. 在 Unsloth Desktop 左侧导航中进入 API。
2. 找到 Keyless API access，开启 Chat and inference 开关。
3. 如果希望所有本地接口都免 API Key，再一并开启 Everything else 和 Allow tools；开关显示为绿色，表示对应类别已允许免密访问。

Provider Agent 只进行模型推理时，开启 Chat and inference 即可，此时本机和当前私有局域网中的 OpenAI-compatible、Anthropic-compatible 推理接口可以不带 API Key 访问。截图中的 Everything else 控制训练、文件和设置等其他接口，Allow tools 控制免密调用内置工具；这两个开关不是接入 Provider Agent 的必需项，请按实际需求决定是否开启。

免密访问只应在本机或可信局域网中使用，不要把未鉴权的 8888 端口直接暴露到公网。Unsloth Desktop 的公共 URL 和 Colab 场景仍会要求 API Key。如果希望保留鉴权，请不要开启 Chat and inference 的免密访问，并在 Provider Agent 中通过 --runtime-api-key 提供对应密钥。

设置模型上下文大小

先确认目标模型为 Q4 或更高精度的 GGUF 版本，再为它设置合适的上下文长度。在 Unsloth Desktop 的模型列表中找到目标模型，点击右侧的三点菜单，再选择 Settings。

在模型设置中找到 Context Length，按模型实际支持的上下文窗口填写或拖动到目标值。常见换算如下：

• 128K 上下文：131072
• 256K 上下文：262144

对于本页使用的 qwen3.8:27b，推荐设置为 262144（256K）；如果机器资源不足，最低应保持 131072（128K），低于此值将无法通过 Provider Agent 的启动预检。

勾选 Remember for this model，让 Unsloth Desktop 记住该模型的设置，然后点击 Reload model 重新加载模型，使新的上下文长度生效。

截图中的 131072 表示 Qwen3.8 27B 的最低可用 128K 上下文，仅用于展示设置位置；本页推荐值仍为 262144。上下文越大，内存或显存占用越高。如果页面提示当前可用内存不足，可以调低到 131072 后再重新加载。

注意，Context Length 是模型加载时的上下文窗口；OpenAI 请求体里的 max_tokens 只是单次请求最多生成多少 token，不能代替上下文窗口设置。

确认服务和模型

先在 Unsloth Desktop 中启动本地服务并加载目标模型，再查看模型列表：

curl http://127.0.0.1:8888/v1/models

从响应中找到目标项，确认其 loaded 为 true，并完整复制 id。这个值必须原样用作 --runtime-model-id；不要用平台侧的 --model 代码代替。

如果目标项的 loaded 为 false，请回到 Unsloth Desktop 手动加载后再继续。天池 Token 不会替你触发加载或切换。

运行预检

按上文开启 Chat and inference 免密访问后，不需要传 --runtime-api-key：

./token-provider-agent preflight start \  --model qwen3.8:27b \  --base-url http://127.0.0.1:8888 \  --api-format unsloth \  --runtime-model-id unsloth/Qwen3.8-27B-GGUF

将示例中的模型 ID 替换为 /v1/models 返回的精确 ID。预检只验证服务和已加载模型是否可用，不会加载、卸载或自动切换模型。

启动 Provider Agent

预检通过后，使用同一组运行时参数启动：

./token-provider-agent start \  --api-key stp-... \  --model qwen3.8:27b \  --base-url http://127.0.0.1:8888 \  --api-format unsloth \  --runtime-model-id unsloth/Qwen3.8-27B-GGUF

如果以后在 Unsloth Desktop 中改为另一个模型，请先停止 Provider Agent，在 Unsloth Desktop 中手动完成切换，再用新的精确模型 ID 重新预检和启动。

常见问题

• /v1/models 无法访问：确认 Unsloth Desktop 本地服务已启动，端口仍为 8888。
• 预检提示量化版本不支持：改用 Q4 或更高精度的 GGUF 模型，不要使用 Q1、Q2 或 Q3 版本。
• 预检无法识别量化版本：确认完整模型名称或元数据包含明确的量化标识，并改用可识别的模型。
• 预检提示模型不可用：确认模型项的 loaded 为 true，并核对 --runtime-model-id 的大小写和完整内容。
• 返回鉴权错误：确认 API → Keyless API access → Chat and inference 已开启；如果保留鉴权，则需通过 --runtime-api-key 提供对应密钥。
• 长对话提前截断或上下文不足：确认修改的是目标模型的 Context Length，已勾选 Remember for this model，并点击 Reload model 使设置生效。
• 启动后模型发生变化：停止 Provider Agent，手动恢复正确的已加载模型，再重新预检；Agent 不会自动切换模型。

参考链接

• Unsloth Qwen3.8-27B GGUF