HF 空间模型 dev-bravelo/dsh-hf-spaces

dsh-hf-spaces

在 Hugging Face 上用自己的 GPU 虚拟机（GPU Space）运行开放权重 LLM，然后在 DeepSeek Harness 里像用其他模型一样使用它们。你发消息时，插件启动机器；启动过程中显示进度；通过你自己的模型作答；你不再使用时，插件暂停机器。这样 GPU 只在被使用时计费。

状态：alpha，尚未发布。 插件本身计划内的功能都已就位，并于 2026-10-31 在真实私有 Space 上测试过（见兼容性）。尚未发布到 npm；见 CHANGELOG.md。设计文档在 docs/design.md。

负责任地使用。 模型由你选择和运行；插件不添加内容过滤。安装前请阅读负责任地使用。

目录

1. 功能
2. 端到端流程
3. 开放模型，你自己的权重
4. 你负责搭建什么，插件负责做什么
5. 负责任地使用
6. 要求
7. 安装
8. 凭据
9. 配置
10. 架构
11. 安全与隐私
12. 兼容性
13. FAQ
14. 路线图
15. 贡献
16. 许可证

功能

- 模型选择器： 每个配置好的 Space 显示为一个服务商，列出它的模型、上下文大小、输出上限和推理等级。
- 按需启动： 向已暂停的 Space 发消息会启动它。模型就绪后，对话自动恢复，回答等待中的那条消息。
- 自动停止： 空闲时间可配置；每次启动还有时间上限，到点前几分钟给出警告，并提供一键延长。
- 看清正在发生什么：
- 头部指示器：每个使用 Space 的对话里都有（当它是配置档的默认模型时也有）：一行简短文字显示状态；启动中显示百分比和剩余时间，服务中显示停止时间；还有一个按钮，Start 或 Stop。点击状态会打开侧边栏标签页；
- 侧边栏标签页「Hugging Face Spaces」：进度条、Hugging Face 今天和本月为该 Space 计费的金额、最近的启动记录（时长、费用、每次结束的原因）、最近一次启动的运行日志尾部，以及每个凭据的状态；
- 通知： 即将到达时间上限（带 +N 和 Stop）、启动失败、推理等级被拒绝、凭据缺失或被拒绝；
- 设置页：在 Plugins 面板里，列出每项检查（凭据、Space、清单、模型、推理等级）和每个生效值及其来源。
- 手动控制： /space status | on | off | +N 和按钮，这些操作绝不会向模型发送任何内容。
- 看不到账户余额： Hugging Face 只在登录后的账单页面显示余额，API 拿不到，所以插件不显示余额，改为显示已计费金额。

完整流程

Hugging Face Space 是 Hugging Face 为你运行的虚拟机。在 GPU 硬件上（例如 A100），启动和运行期间按分钟计费，暂停时不收费。你的 Space 运行一个 OpenAI 兼容服务器（例如 llama.cpp llama-server），加载你选择的模型权重。

DeepSeek Harness (your computer) Hugging Face (your account)
┌────────────────────────────────┐ ┌──────────────────────────────┐
│ model selector: "My LLM" │ │ GPU Space (virtual machine) │
│ you send a message ────────────┼── is it serving? ─►│ paused → started by the │
│ │ │ plugin (API) │
│ header: "starting 42% · ~2 min"│◄── progress ───────┤ booting → copies and loads │ │ │ │ your weights │ │ the answer streams back ◄──────┼── your model ──────┤ serving → OpenAI-compatible │ │ │ │ API (/v1) │ │ idle 30 min / limit 60 min ────┼── pause ──────────►│ paused → billing stops │ └────────────────────────────────┘ └──────────────────────────────┘

1. 在 Harness 模型选择器里选中 Space 的模型，和其他模型一样。
2. 你发一条消息。 Space 正在服务，消息就直接发过去。Space 已暂停，插件先回一条简短提示，再通过 Hugging Face API 启动 Space，并在对话头部显示进度：GPU 和容器启动、权重拷贝、加载、预热。
3. 模型就绪后， 对话自动恢复，你的模型回答刚才等待的消息。27B 模型在 A100 上首次启动约需 3 分钟。
4. 你工作期间， 每个请求都从你的电脑发到你 Space 自己的地址（https://<subdomain>.hf.space），带上你的 token。不经过任何第三方推理服务。
5. 你用完以后， 插件暂停 Space：30 分钟无请求、每次启动达到 60 分钟上限（可延长），或你按下 Stop。计费随即停止。
6. Harness 关闭时， 插件无法暂停 Space，只能靠 Space 自己的休眠时间。请在 Space 设置里配一个。

私有 Space 让权重和 Space 只对你的账户可见：只有能访问该 Space 的 token 才能调用。机器仍由 Hugging Face 运行，所以那边跑的东西适用它的隐私政策。

开放模型，你的权重

- 模型由你提供。 插件不带模型，也不下载模型。你的 Space 提供无论你放入什么开放权重模型：基础模型、指令微调模型、量化版本（例如配合 llama.cpp 的 GGUF），还是自己微调的模型。
- 也包括内置拒绝行为较少的模型，通常叫「uncensored」或「abliterated」。托管助手会按策略拒绝很多请求；你自己运行的模型遵循权重和你给的系统提示词。
- 每个模型保留自己的许可证。 开放权重并不等于所有用途都免费：检查你运行的每个模型的许可证和可接受使用政策。
- 选择器只显示你声明的项： 模型名、上下文大小，以及你的服务器接受的推理强度档位。插件在首次启动时检查这些档位，并报告服务器拒绝的档位。

你搭建什么，插件做什么

插件驱动一个已经在运行你模型的 Space。它不创建 Space、不选硬件、不安装推理引擎、不上传权重：这些基础设施由你在 Hugging Face 上搭建和配置一次。

| 你在 Hugging Face 上搭建 | 插件在 DeepSeek Harness 中做什么 |
| Space（Docker Space），私有或公开 | 把其中的模型放进模型选择器 |
| 机器： Space 设置中的 GPU 硬件规格，例如 A100 或 L40S（或配置里的 hardware） | 通过 Hugging Face API 启动 Space，并暂停它 |
| 推理引擎： 运行模型并提供 OpenAI 兼容 API（见下文） | 等到引擎列出你的模型，然后发送对话 |
| 权重： 存放位置（挂载为卷的存储桶、Space 仓库，或启动时下载）以及引擎如何加载 | 显示启动进度，来源是 Space 状态和日志中可选的进度行 |
| 聊天模板及其接受的推理强度值 | 选择器中只提供你声明的强度档位，并在首次启动时检查 |
| Space 休眠时间： Harness 关闭时的安全网 | Harness 打开时应用自己的空闲和时间限制规则 |
| 引擎自身需要的 Space secrets | 写入你声明的启动变量（绝不写 secrets） |

推理引擎

任何在 Space 地址上提供 GET /v1/models 和 POST /v1/chat/completions 的引擎都应该能用：
- llama.cpp llama-server： 已测试（A100 上的 27B GGUF 模型，2026-10-31）。
- Ollama、vLLM、Hugging Face TGI 及类似服务器提供 OpenAI 兼容端点。只要它们提供上述两个端点就应该能用；尚未测试。欢迎反馈。

引擎侧需要：
- 监听 Space 暴露的端口（Docker Space 中是 Space README 里的 app_port，默认 7860），并在 Space 根路径的 /v1 下提供 API，或在配置里设置 baseURL；
- 在 GET /v1/models 中列出你的模型 id，与你在配置里写的完全一致；
- 接受 reasoning_effort，取值用你在 reasoning 里映射的那几个；模型不支持调节推理强度时，声明 reasoning: false；
- 模型能读图时，在引擎里加载它的视觉部分（llama.cpp 用 --mmproj projector），并在配置里或 Space 的 dsh-hf-spaces.json 清单里为该模型声明 input: [text, image]。不声明的话，Harness 会把模型当纯文本处理，拒绝给它图片。

可选，体验更好：在 Space 日志里输出进度行（SPACE_EVENT {...}）；提供 dsh-hf-spaces.json 清单，用户只需填 Space id；为每次启动都需要新值的 Space 提供启动变量。这三项都在 docs/design.md 里说明。参考 Space 模板可能后续提供。

负责任使用

这个插件是个工具，用来在你控制的机器上运行你选的模型。它不加内容过滤，拒绝更少的模型会回答托管助手拒绝的请求。这份自由伴随责任，责任在你。

使用本插件即表示你同意：
- 遵守适用于你、也适用于受你使用影响的人的法律；
- 遵守 Hugging Face 服务条款和内容政策，它们约束在其机器上运行的内容；
- 遵守你运行的每个模型的许可证和可接受使用政策。

不要用本插件或你用它运行的模型去做这些事：
- 在你居住地或影响所及之处做任何违法的事；
- 以任何形式创建、请求或分享涉及未成年人的性内容；
- 策划、宣扬或协助暴力、恐怖主义，或能造成大规模伤害的武器（生物、化学、核、放射性或爆炸物）；
- 编写恶意软件，或攻击、扫描、入侵你未获授权测试的系统；
- 骚扰、威胁、跟踪、诽谤或冒充他人，或泄露他人隐私数据；
- 进行欺诈、诈骗、垃圾信息，或把欺骗性内容伪装成真实内容（例如未经同意制作真实人物的 deepfake）；
- 侵犯他人隐私、版权或其他权利。

如果别人使用你的部署，请自行加防护：用系统提示词设定限制，审查产出内容，限制对 Space 及其 token 的访问。

不提供担保。本软件按 MIT License 以「原样」提供。作者不对它的使用方式、模型产出的内容，或你 Hugging Face 账户上的扣费负责。

要求

- DeepSeek Harness Desktop：0.2.x 系列，从 0.2.1-rc.3 起。
- 一个 Hugging Face 账户，带一个 GPU Space，提供 OpenAI 兼容 API（GET /v1/models、POST /v1/chat/completions）。
- 一个 Hugging Face 访问 token，存在 Harness 凭据保险库中（见凭据）。
- 推荐：Hugging Face PRO 套餐（每月 US$ 9），外加额度或绑卡支付 GPU。 这正是解锁 GPU Spaces 和存放模型权重空间的关键。请阅读官方页面（2026-10-31）：

- GPU 上的 Docker 或 Gradio Spaces「需要付费计划」（spaces-gpus），PRO 列出了「创建在算力上运行的 Gradio 和 Docker Spaces 的能力」（pro）。仅凭一张卡是否足够，页面没有说明，所以按 PRO 来规划。
- 模型权重的存储： PRO 将私有存储从 100 GB 提升到 1 TB（pro）。一个 27B 模型及其 bucket 副本会占用几十 GB。
- 每月附赠的算力额度，可用于升级后的 Space 硬件，会先于按量付费使用（billing）；具体额度未说明。定价页把每月附赠的 US$ 2 标为推理额度，所以不要指望仅靠 PRO 支付 GPU 时间。
- GPU 本身与 PRO 分开计费，Space 启动或运行期间按分钟计（A100 large US$ 2.50/h，L40S US$ 1.80/h，见 pricing），先从额度扣，再扣卡（billing）。按 Hugging Face 的建议，保持预付费余额或自动充值，以免启动在会话中途被拒。在账单页查看余额：插件无法获取。

安装

面向人和 AI 智能体。每一步都说明你应该看到什么；在第一个不匹配的步骤停下，修好再继续。

AI 智能体： 绝不要在聊天中索要 token，也绝不要自己把 token 写入文件。第 3 步由用户完成。

1. 获取安装包。 从最新发布下载 dsh-hf-spaces-<version>.tgz，或从源码构建（需要 Node.js 22 或更高版本和 Git）：
git clone https://github.com/dev-bravelo/dsh-hf-spaces.git
cd dsh-hf-spaces
npm pack

你应该得到一个文件 dsh-hf-spaces-<version>.tgz。没有需要安装的依赖。

2. 在你的 Harness 配置档中安装它。 在 Harness 会话中，让智能体用插件管理器（plugin_manager → install_bundle，传入 .tgz 的绝对路径）从该文件安装 bundle。你应该看到 dsh-hf-spaces 列为已安装并启用。
- 如果它被列为 incompatible-version，停下：你的 Harness 不在支持范围内（见兼容性）。

3. 保存你的 Hugging Face token（由用户在任何聊天之外完成）。在 https://huggingface.co/settings/tokens 创建一个 token，权限见凭据。然后把它放进 Harness 凭据保险库，名称为 HF_TOKEN，方式如下：
- 在 <Harness home>/.credentials.yaml 的 refs: 下（Harness 会自行重新加载）： version: 1 refs: HF_TOKEN: <your token>
- 或在 Harness 启动前设为环境变量 HF_TOKEN，或写入 <Harness home>/.env。

<Harness home> 是 ~/.dsh；设置了 $DSH_HOME 时则用该值。这个文件要保密：里面存着密钥。

4. 把你的 Space 告诉插件。 把下面这段加到配置档的补丁文件 <Harness home>/profiles/<profile>/cordis.patch.yml 里（该文件是 YAML 列表，把条目加进去）：
- id: hf-spaces
name: dsh-hf-spaces
config:
spaces:
- id: your-user/your-llm-space # your Space, owner/name
models:
- id: your-model-id # exactly as GET /v1/models lists it
name: My model 27B # the name shown in the model selector
reasoning: { "off": none, low: low, medium: medium, high: high }

其余字段都有默认值，全部列在 examples/config.example.yml。Space 发布了 dsh-hf-spaces.json 清单时，可以省略 models（设计文档第 6 节）。

5. 重启 Harness，打开 Plugins → dsh-hf-spaces。 每项检查都应显示 "ok"：凭据已接受、Space 已读取、模型已列出。"Models served" 和 "Effort levels" 在首次启动前显示 "later"。
- 如果某行显示 "fix"，就停下来：该行的消息会说明要改什么。

6. 开始使用。 在模型选择器里选好模型，发一条消息。插件会启动 Space，并在会话头部显示进度；模型就绪后就会给出回答。用完后，点头部的 Stop，或发送 /space off。

卸载： 从配置档补丁里删掉 hf-spaces 条目，再用插件管理器卸载这个包。
Space 本身保持原样：如果它还在运行，去 Hugging Face 上暂停它。

凭据

配置里永远不含 token。 它只指定 Harness 保险库中存放的凭据，默认名称是 HF_TOKEN。侧边栏标签页和设置页会显示每项凭据是否在保险库里、Hugging Face 是否接受它、它的账号和 token 角色，但从不显示它的值。

| 设置 | 是否必需 | 用途 | Hugging Face 上的 token 权限 |
| credentials.inference | 必需 | 向私有 Space 中的模型发送请求 | 对 Space 的读取权限 |
| credentials.control | 启动和停止时需要 | 启动、暂停和重启 Space | 对 Space 的写入权限 |
| credentials.billing | 否 | 每个 Space 今天和本月的 Hugging Face 计费 | 对计费的读取权限 |

- 一个带写入权限的经典 token 就能覆盖这三项。
- 要最小权限， 就分别创建细粒度 token，给每项设置指定各自的凭据名称。
- 创建 token 的地址： https://huggingface.co/settings/tokens。

配置

完整带注释的示例在 examples/config.example.yml。每个 Space 唯一必填的字段是

它的 id（owner/space-name）。
- 从 Space 推导： API 地址和硬件。
- 从 Hugging Face 读取： 每小时价格。
- 启动变量： 给每次启动都需要新值的 Space 用（会话 id、启动截止时间），以数据形式声明，带占位符。
- 插件的记录（最近的启动）保存在 <Harness home>/state/dsh-hf-spaces（stateDir 可以改）。

架构

按 DeepSeek Harness 的要求，插件分两半：

| 半边 | 运行在 | 职责 |
| Host | Harness 后端（Node.js） | 每个 Space 的模型路由；Space 监督器（状态、启动、停止、空闲与时限规则、费用）；一个小型 Hugging Face API 客户端；自己保存的最近启动记录；供界面用的本地 HTTP 路由，由 Harness 守护 |
| Client | Harness 窗口（Web UI） | 顶栏指示器、侧边栏标签页、通知和设置页；从 Host 路由读取状态；按钮调用 Host 动作 |

Space 一侧可以是任何提供 OpenAI 兼容 API 的 Space，例如 llama.cpp 的 llama-server。如果 Space 还输出设计里描述的可选进度事件，启动进度会更详细（复制百分比、加载、预热）。

安全与隐私

- Token 绝不写入配置、日志、记录或界面。把 token 粘贴到本该填凭据名或启动变量的地方会被拒绝，且不会回显。
- Token 只发往 Hugging Face（https://huggingface.co）和 Space 自己的 https://*.hf.space 地址。带 token 的请求绝不跟随重定向。
- 你的对话只发往你的 Space。 插件不上报遥测，也不使用其他服务。
- 本地 HTTP 路由用 Harness 自带的守护（connection.requestRejection）检查每个请求，只接受小请求体，只提供三个动作：启动、停止、延长。
- 测试从不调用真实服务： 用模拟的 Hugging Face API 和模拟的 Space，只在 127.0.0.1 上跑。
- 本仓库带一个密钥与个人数据扫描器，无依赖，由 pre-commit 和 commit-msg 钩子运行。见 AGENTS.md 第 4 节。

报告漏洞： 见 SECURITY.md。绝不要在 issue 里粘贴 token。

兼容性

| 插件 | DeepSeek Harness | 状态 |
| 0.1.0-alpha.9 | 0.2.1-rc.3 | alpha.8 加上每个模型的 input: [text, image]，这样 Space 提供的视觉模型能在 Harness 里读图。在已安装的 Harness 上做了离线与运行时测试，Windows，2026-11-01 |
| 0.1.0-alpha.8 | 0.2.1-rc.3 | 完整插件，界面在首次 Desktop 测试（alpha.7）后重新设计：选择器、启动与恢复、进度、/space、停止规则、标题栏指示、侧边栏标签页、通知、设置页、账单用量与启动记录。在已安装的 Harness 上做过离线与运行时测试，Windows，2026-10-31。首次真实启动（alpha.7，2026-10-31，私有 A100 Space）：3 分 11 秒就绪，进度实时可见，18 分钟后由 /space off 停止，预估费用 US$ 0.75。当天在 Desktop 上看到重新设计的标题栏正常工作，会话是从另一个模型切换过来的 |

每个版本都会写明它在哪些 Harness 版本上测试过、怎么测的。

更新 DeepSeek Harness 时：
- 在测试范围内（package.json 里的 engines.dsh，目前是 >=0.2.1-rc.3 <0.3.0-0），插件照常工作，不用改动。
- 超出范围，Harness 不会加载插件。插件管理器会把它显示为 incompatible-version，解决办法是等插件发布新版本，而不是找变通做法。
- 界面的每一部分都等它用到的 Harness 服务。 如果某个 Harness 版本去掉了某个服务（比如右侧边栏），只有那一部分会缺失，其余部分照常工作。

插件如何保持兼容是一条贡献者规则：AGENTS.md, section 7。

FAQ

插件会创建 Space 或安装推理引擎吗？

不会。Space 由你在 Hugging Face 上搭建：GPU 硬件、推理引擎（例如 llama.cpp llama-server、Ollama 或 vLLM）、权重和休眠时间。插件随后从 DeepSeek Harness 启动、监视、使用和暂停这个 Space。见 What you set up, and what the plugin does。

如何在 DeepSeek Harness 里使用自己的开放权重 LLM？

在 GPU Hugging Face Space 上用兼容 OpenAI 的服务器（例如 llama.cpp llama-server）提供服务，安装本插件，再把 Space id 加到你的配置档（Installation）。模型随后会像其他模型一样出现在 Harness 模型选择器里。

这样能运行无审查或 abliterated 模型吗？

可以。Space 提供什么权重由你决定，包括内置拒答更少的微调模型，只要模型许可证和 Hugging Face 条款允许你这样使用。请先读 Responsible use。

如何停止为空闲的 Hugging Face GPU Space 付费？

插件在 30 分钟无请求后暂停 Space，每次启动上限 60 分钟（两者都可配置，上限可以延长），你按 Stop 或发送 /space off 时也会暂停。暂停的 Space 不计费。Harness 关闭时，只有 Space 自身的休眠时间能停止它。

费用是多少？

Space 启动和运行期间，Hugging Face 按已启动的分钟数对 GPU 计费：A100 large 为每小时 US$ 2.50（pricing，读取于 2026-10-31）。一次真实 27B 模型跑 18 分钟会话，花费约 0.75 美元。插件会显示每次启动的费用，以及 Space 今天和这个月扣了多少。

需要 Hugging Face PRO 套餐吗？

Hugging Face 要求付费套餐才能在 GPU 上运行 Docker 或 Gradio Space，PRO 还会提高权重文件的存储额度。见环境要求。

冷启动要多久？

27B 模型在 A100 上约 3 分钟：GPU 启动，权重从存储桶复制过来，加载，预热。进度显示在对话头部。Hugging Face 上的 GPU 排队还会额外增加时间。

我的提示词和模型是私密的吗？

私有 Space 只能用有读取权限的 token 调用。插件只把你的请求发到你的 Space 和 Hugging Face API，不带遥测。机器由 Hugging Face 运行，所以适用它的隐私政策。

哪些服务器和模型能用？

任何提供 OpenAI 兼容 API 的服务器（GET /v1/models、POST /v1/chat/completions）。已在 A100 上用 llama.cpp llama-server 提供 27B GGUF 模型测试过。

会显示我的 Hugging Face 余额吗？

不会。Hugging Face 不通过 API 暴露余额，请到账单页面查看。插件显示的是已扣费的金额。

能让 AI 智能体帮我安装吗？

可以。安装一节也面向智能体编写，写明了预期结果和停止条件。token 这一步始终由你完成：智能体绝不能要求在对话里提供 token。

DeepSeek Harness 更新会把它弄坏吗？

在支持的版本范围内，它能继续工作；超出范围时，Harness 会拒绝加载并给出说明，而不是在对话中途失败。见兼容性。

路线图

| 阶段 | 交付内容 | 状态 |
| 0. 契约 | 在已安装的 Harness 上验证客户端插件格式、插槽、本地路由和凭据 API，以及 Hugging Face Space 端点 | 已完成 |
| 1. 宿主 | 模型路由和 Space 守护进程，含离线测试 | 已完成 |
| 2. 客户端 | 头部指示器、侧边栏标签页、通知和设置页 | 已完成 |
| 3. 迁移 | 替换它由之发展而来的私有原型 | 已在真实配置档中完成，2026-10-31 |
| 4. 发布 1.0 | 公开仓库、npm 包、兼容性矩阵 | 下一步 |

参与贡献

先读 AGENTS.md。其中的规则对人和 AI 编程智能体同样适用。简而言之：
- 用英文写作；
- 绝不提交密钥或个人数据；
- 保持测试离线；
- 每次提交前运行 npm run check。

许可证

MIT。见负责任使用。