供应 Token 指南

Provider Agent 是什么

token-provider-agent 是一个常驻运行的命令行程序，负责把你的机器接入平台、维持在线、接收任务并调用本地模型执行推理。

网页控制台负责创建 API Key、查看节点、活动记录和收入。而真正让你的机器成为 Provider 节点的，是这个 Agent。

准备工作

开始之前，确认以下条件已就绪：

• 一台能长期运行的机器
• 已安装并可访问的本地推理框架；默认使用 Unsloth Desktop，也支持 LM Studio / vLLM / oMLX / llama.cpp
• 默认 Unsloth Desktop 模式下，确认本地服务已在 http://127.0.0.1:8888 启动，已加载目标模型，并暴露 OpenAI-compatible /v1/models 和 /v1/chat/completions
• Unsloth Desktop 中的目标模型最低必须使用 Q4 量化版本（Q4 或更高精度）；本指南的 Qwen3.8 27B 示例推荐使用 UD-Q4_K_M
• 一个 Provider API Key（下一节介绍如何获取）
• 平台提供的 token-provider-agent 二进制文件

设备建议

选择模型时优先看 GPU 可用显存。以下是单卡常见配置建议；不同推理框架、量化精度、上下文长度和系统占用都会影响实际可加载规模，正式启动前仍以本地推理框架的加载结果和 Agent 预检为准。

软件下载

请前往 程序下载 下载天池 Token 相关程序。

普通 Provider 用户优先下载“天池 Token 桌面版”。桌面版提供图形化入口，支持 Provider 节点启动，更适合本地桌面和工作站日常运行。

只有在需要长期守护、脚本化部署、服务器部署或无桌面环境运行时，再下载“天池 Token 供应：命令行版”。如果选择命令行版，后续示例统一用 ./token-provider-agent 代替实际可执行文件。

本地推理框架也可以从下载页的“第三方程序”列表进入安装页面。默认推荐先使用已安装并已加载目标模型的 Unsloth Desktop；也可按机器和需求选择 LM Studio / vLLM / oMLX / llama.cpp。

第一步：获取 Provider API Key

登录网页控制台，进入 Provider 的「API 密钥」页面，创建一条新的 Provider API Key。

创建后页面会直接显示密钥内容（stp-...）。请立即保存，离开页面后无法再次查看。

建议每台机器使用独立的密钥，方便后续排查节点状态、活动记录和收入归属。

第二步：确认推理框架和模型可用

Provider Agent 启动时会检查指定模型是否在推理框架中可用。默认推理框架是 Unsloth Desktop，启动前确认四件事：

• 已从 Unsloth Desktop 下载页 安装 Unsloth Desktop
• 已下载并手动加载目标模型，且量化精度不低于 Q4；本指南的 Qwen3.8 27B 示例推荐使用 UD-Q4_K_M
• 本地 API 服务已启动，默认地址是 http://127.0.0.1:8888
• /v1/models 中的目标模型显示 loaded: true

--model 参数仍然使用平台侧模型代码，例如本指南统一采用的 qwen3.8:27b。控制台的 Token 供应示例会同时展示“模型名称”和“模型 ID”：模型名称通常用于搜索、下载或启动本地推理框架；模型 ID 是本地 OpenAI-compatible /v1/models 返回、Provider Agent 预检和真实请求使用的标识。

Unsloth Desktop 的安装、模型加载、Q4 量化门槛和验证方式见 Unsloth Desktop 本地模型准备。

如果你使用 LM Studio / vLLM / oMLX / llama.cpp 等 OpenAI-compatible 推理框架，同样确认服务已暴露 /v1/models 和 /v1/chat/completions，并准备好对应的推理框架地址和推理框架 API Key。Agent 会根据 --api-format 在启动预检时从平台 /platform/v1/models 的 runtime_model_options 选择默认模型 ID；如果你在控制台选择了另一个模型 ID，请通过 --runtime-model-id 或 PROVIDER_AGENT_RUNTIME_MODEL_ID 显式传入。使用 Unsloth Desktop 时，必须先在其界面中加载所选模型；天池 Token 桌面端、网页控制台和 Provider Agent 都不会加载、卸载或自动切换模型。使用 LM Studio 时也请先手动加载目标模型。

不同推理框架的安装、模型名准备、256K 上下文配置和可用性检查方式，见：

• Unsloth Desktop 本地模型准备
• LM Studio 本地模型准备
• vLLM 本地模型准备
• oMLX 本地模型准备
• llama.cpp 本地模型准备

LM Studio 的临时计费规则

LM Studio 的 /v1/chat/completions 协议因缓存统计不完善，非缓存输入暂时按照缓存输入价格计费。这是临时计费规则，不代表输入实际命中了缓存，也不适用于 /v1/responses 或 /v1/messages。

第三步：运行启动前检查

正式启动前，先跑一次预检：

./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 与控制台展示不一致
• Unsloth Desktop 中的目标模型尚未加载
• 平台模型目录没有为当前 --model 和 --api-format 提供 runtime_model_options

其它 OpenAI-compatible 推理框架可以在预检时显式带上推理框架地址和框架类型：

./token-provider-agent preflight start --model qwen3.8:27b --base-url http://127.0.0.1:8000 --api-format omlx --runtime-model-id Qwen3.8-27B-4bit

如果上游服务需要鉴权，预检和启动时都要同时传入 --runtime-api-key，或设置 PROVIDER_AGENT_RUNTIME_API_KEY。

第四步：启动 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

主要参数：

启动成功后，进程会常驻运行，持续完成以下工作：

• 注册或恢复节点
• 上报模型和节点状态
• 发送心跳保持在线
• 接收并执行推理任务

所以它是一个常驻服务，不是一次性命令。

更多启动参数

如果需要自定义连接地址或调优参数，还可以使用：

这些启动参数也可以通过环境变量传入：

布尔参数支持 1、true、yes、on 表示开启，支持 0、false、no、off 表示关闭。完整命令列表可通过 --help 查看。

OpenAI-compatible 推理框架示例

当你的上游服务兼容 OpenAI Chat Completions API 时，选择对应的 --api-format 后启动即可。下面以默认推荐的 Unsloth Desktop 为例。其默认服务地址为 http://127.0.0.1:8888；开启 Chat and inference 免密访问后，启动命令不需要 --runtime-api-key：

./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

这里的 --runtime-model-id 必须替换成 Unsloth Desktop /v1/models 返回的已加载模型 ID。该命令只检查并使用模型，不会触发加载、卸载或自动切换。如果保留了 Unsloth Desktop 鉴权，请增加 --runtime-api-key。

第五步：确认节点正常工作

可以从三个方面确认。

Agent 进程状态

如果 start 运行后没有立刻退出，说明基础启动已通过。

网页控制台节点列表

进入 Provider 的「节点列表」页面，确认能看到：

• 你的节点名称
• 节点状态
• 最近心跳时间

如果心跳时间持续刷新，说明 Agent 在线运行正常。

活动记录和收入

当请求开始进入后，在「活动记录」和「收入」页面可以看到实际的请求处理情况。如果活动记录已出现请求且 Agent 稳定运行，主流程已接通。

常用命令

查看帮助

./token-provider-agent --help

查看节点状态

./token-provider-agent status --json

确认当前节点状态和生命周期快照。

查看本地模型

./token-provider-agent models --json

确认 Agent 当前能看到哪些本地模型。

导出诊断信息

./token-provider-agent diagnose --json

排查推理框架、连接或本地状态问题时最有用。

查看 P2P 状态

./token-provider-agent p2p status --json

排查直连或传输能力时使用。

停止

./token-provider-agent stop

如果 Agent 在前台运行，也可以直接 Ctrl+C 停止。

常见问题

启动时提示缺少 model code

启动命令缺少 --model 参数，补上后重新执行：

./token-provider-agent start --api-key stp-... --model qwen3.8:27b

预检失败，找不到模型

指定的模型在推理框架中不可用。依次检查：

1. 推理框架已启动
2. 模型 ID 拼写正确，且能在本地 /v1/models 中看到
3. Unsloth Desktop 的目标模型已加载且量化精度不低于 Q4；或其它 OpenAI-compatible /v1/models 能返回预检解析出的上游模型
4. 平台 /platform/v1/models 中当前平台模型的 runtime_model_options 包含所选 --api-format 和模型 ID

可以用 ./token-provider-agent models --json 查看 Agent 当前能识别的模型列表。

节点没出现在网页控制台

按顺序检查：

1. Agent 进程是否直接退出了
2. API Key 是否正确
3. 节点名是否成功传入
4. status 和 diagnose 输出中是否有明显错误

如果 Agent 启动成功但节点列表为空，通常是接入链路中某一步未完成。

Agent 在运行，但一直没有请求

不要立刻怀疑模型执行有问题，优先检查：

• 节点是否在线
• 心跳是否持续更新
• 模型是否已成功上报
• 当前是否有流量分配到你的节点

网页控制台的「节点列表」「活动记录」「收入」是最直接的三个观察入口。

API Key 泄露了怎么办

1. 在网页控制台删除旧的 Provider API Key
2. 创建一条新密钥
3. 用新密钥重新启动 Agent

不要继续使用已怀疑泄露的密钥。

最小上手流程

按以下顺序操作，即可完成最基础的接入：

1. 在网页控制台创建 Provider API Key
2. 准备好 token-provider-agent 二进制文件
3. 确认本地推理框架和目标模型可用
4. 运行 ./token-provider-agent preflight start --model qwen3.8:27b
5. 运行 ./token-provider-agent start --api-key stp-... --model qwen3.8:27b
6. 在网页控制台查看「节点列表」
7. 查看「活动记录」和「收入」