WorkBuddy接入Hy4 preview本地运行：从配置到实战-平芜编程栈

各位开发者朋友，大家好。

最近 AI 工具圈有一个很有意思的变化：很多原本依赖云端算力的大模型能力，开始逐渐向本地化、单机化、私有化方向演进。今天要聊的 Hy4 preview 登录 WorkBuddy，并支持本地运行，就是这样一个值得关注的信号。简单来说，WorkBuddy 作为一个面向个人工作台场景的 AI 工具，接入 Hy4 preview 之后，可以在不依赖云端 API 的情况下，在本地完成一部分 AI 对话、任务规划、文档处理甚至接口自动化等工作。

这篇文章会从“Hy4 是什么、WorkBuddy 是什么、为什么要本地运行”开始，逐步拆解 WorkBuddy 的安装与配置流程、Hy4 接入方式、核心功能实操、常见报错排查，以及我在实际使用中觉得比较好用的工程实践。无论你是刚听说 WorkBuddy 的新手，还是已经遇到过“上下文用量满了”“本地模型怎么接进来”这类问题的老用户，这篇文章应该都能提供一些可落地的参考。

1. 背景与核心概念

1.1 Hy4 preview 是什么

Hy4 是近期热度比较高的开源 AI 模型系列之一，preview 表示预览版本。它和常见的对话模型、编程模型类似，定位是通用能力与任务执行能力兼顾，既可以做问答、总结、写作，也可以根据自然语言指令拆解任务、生成代码片段、调用工具等。

很多开发者关心它，是因为它的“成本结构”比较友好：模型权重可以下载到本地，不需要每次都把数据传到云端。这意味着在断网环境、内网环境、以及数据敏感的业务场景里，Hy4 preview 都有很强的落地潜力。

需要说明的是，由于 Hy4 仍处于 preview 阶段，具体参数规模、量化版本、硬件要求会随着版本迭代而调整。本文不会去写死某一组数据，而是重点讲解“在 WorkBuddy 中如何接入并运行这类本地模型”的通用思路。

1.2 WorkBuddy 是什么

WorkBuddy 是一个基于“个人工作台”理念的 AI 客户端工具，可以把它理解为“一个把多种 AI 能力整合在一起的操作系统级入口”。它不只是简单的聊天窗口，而是支持：

多模型管理：可以接入云端模型，也可以配置本地模型。
技能（Skill）系统：通过技能块扩展 AI 的能力范围，比如写网页、做接口自动化、调用 ComfyUI 生图等。
上下文管理：集中管理对话上下文，避免每次新开对话都丢失前面的信息。
插件生态：支持 Obsidian、VSCode 等工具的联动。
本地文件系统访问：可以直接读取、整理、转换本地文件。

从同类产品对比来看，WorkBuddy 和 CodeBuddy、Trae 这类编程助手的区别在于：CodeBuddy 更聚焦代码生成与 IDE 场景，Trae 强调纯 AI IDE 体验，而 WorkBuddy 更像一个“通用型 AI 办公/开发工作台”，代码能力只是它的一个板块。

1.3 为什么“本地运行”值得关注

先来看传统云端 AI 的使用链路：

用户输入 → 客户端 → 云端 API → 大模型计算 → 返回结果 → 用户界面

这条链路的好处是模型能力强、部署简单，但问题也很明显：

数据要经过第三方服务器，敏感信息存在外泄风险。
每次调用都有 API 费用，高频使用时成本不小。
网络不稳定或断网时，功能直接不可用。
上下文长度、请求频率容易受服务方限制。

本地运行的链路则变成：

用户输入 → WorkBuddy → 本地模型推理（Hy4 preview） → 返回结果 → 用户界面

所有数据都在本机流转，不上传、不排队、不按次计费，而且可以完全离线使用。对于有隐私要求、预算有限、或者经常出差断网的开发者来说，这是非常实用的能力。

2. 环境准备与版本说明

在开始安装 WorkBuddy 并接入 Hy4 preview 之前，先梳理一下环境要求。

2.1 操作系统

WorkBuddy 官方目前主要支持 Windows 10/11、macOS 和主流 Linux 发行版。需要注意的是，网上有用户反馈 Windows 7 无法安装 WorkBuddy，原因是新版本客户端普遍依赖较新的 WebView2 运行时和系统 API，Windows 7 已经停止官方支持。如果你还在使用 Win7，建议先升级系统，或者使用旧版本客户端，但旧版本可能无法完整支持 Hy4 preview 的本地推理特性。

2.2 硬件要求

如果要流畅运行本地模型，硬件是关键。Hy4 preview 属于中等规模模型，不同量化等级对硬件的要求不同。以下是一个保守的参考：

硬件项	最低配置	推荐配置
CPU	8 核以上	16 核以上
内存	16 GB	32 GB 及以上
GPU	可选（纯 CPU 推理较慢）	NVIDIA 显卡，显存 8 GB 以上
硬盘	20 GB 可用空间	50 GB 以上（SSD 优先）

如果你只是体验功能，用 CPU 跑小量化版本也是可以的，但生成速度会明显变慢。建议有条件的话，优先使用带 NVIDIA GPU 的环境，并通过 Ollama 或 llama.cpp 这类推理框架加载模型。

2.3 软件依赖

在本地运行 Hy4 preview，推荐准备以下软件：

Ollama：目前最流行的本地模型管理工具，支持一键下载模型、启动本地 API。
Git：如果你需要从 Hugging Face 或 ModelScope 手动下载模型权重。
Python 3.10+：用于写一些脚本，比如批量调用本地 API 做接口自动化测试。
WorkBuddy 客户端：最新版本，确认支持自定义模型接入。

这里的版本不需要完全和文章一致，只要保证“WorkBuddy 客户端能访问本地推理服务的 API 地址”即可。如果后续 WorkBuddy 内置了更简便的模型管理方式，以官方文档为准。

2.4 总体架构图

为了方便理解，先画一个简化的架构示意图：

[ WorkBuddy 客户端 ] | | 配置本地模型 API 地址 v [ 本地推理服务: Ollama / llama.cpp ] | | 通过模型权重加载 Hy4 preview v [ 本地模型权重文件 ]

后面所有配置，都是围绕“让 WorkBuddy 能通过 HTTP 请求访问到本地推理服务”展开的。

3. WorkBuddy 安装与基础配置

3.1 下载与安装

WorkBuddy 的安装包可以从官网或官方公众号入口获取。目前网络上有各种“网盘分享版”，不建议使用，因为这些版本可能不是最新的，也可能存在安全风险。

安装过程中需要注意：

Windows 用户建议右键“以管理员身份运行”安装包。
安装目录尽量不要放在 C 盘系统盘，可以在安装时手动指定 D 盘或其他数据盘。网上有“WorkBuddy 怎么移到 D 盘”的问题，如果你的安装器不支持自定义路径，可以在安装完成后通过“设置 → 存储位置”迁移数据目录。
首次启动时需要登录账号，目前支持手机号或邮箱注册。
启动后先检查版本更新，Hy4 preview 的接入能力可能依赖较新的客户端版本。

3.2 熟悉 WorkBuddy 主界面

安装完成后，你会看到类似这样的布局：

左侧：会话列表和功能导航。
中间：对话工作区。
右侧：上下文面板、技能面板、插件面板。
底部：输入框和模型切换器。

在开始配置模型之前，先随便发一条消息试试默认的云端模型是否可用，这样可以确认客户端本身没有网络问题。

3.3 确认模型管理入口

WorkBuddy 的模型管理入口通常在左下角“设置”或“模型管理”中。你可以看到已接入的模型列表、默认模型选择、以及“添加自定义模型”的按钮。我们要做的，就是在“自定义模型”中填入本地推理服务的地址和模型名称。

4. 本地运行 Hy4 preview 的完整流程

这一节是全文的核心，我会按照“部署推理服务 → 准备模型 → 配置 WorkBuddy → 验证联通 → 实际使用”五个步骤来演示。

4.1 方式一：使用 Ollama 快速部署

Ollama 是目前最简单的方式，它把模型下载和 API 服务封装得很干净。

首先安装 Ollama。以 macOS 和 Linux 为例，终端执行：

curl -fsSL https://ollama.com/install.sh | sh

Windows 用户直接下载 OllamaSetup.exe 安装即可。

安装完成后，启动 Ollama 服务：

ollama serve

正常情况下，Ollama 会默认监听127.0.0.1:11434，提供一个 OpenAI 兼容的接口。

接下来，拉取 Hy4 对应的模型。如果你的模型名称是hy4:latest，执行：

ollama pull hy4:latest

拉取完成后，可以先用命令行验证模型能不能正常生成：

ollama run hy4:latest "你好，请介绍一下你自己"

如果能看到正常的回复，说明本地推理服务已经准备就绪。

4.2 方式二：使用 llama.cpp 手动部署

如果你使用的模型文件是 GGUF 格式，或者希望更精细地控制推理参数，可以使用 llama.cpp。

首先克隆仓库并编译：

git clone https://github.com/ggerganov/llama.cpp cd llama.cpp mkdir build cd build cmake .. cmake --build . --config Release

然后启动本地 API 服务：

./bin/llama-server -m /path/to/hy4-model.gguf \ --host 127.0.0.1 \ --port 8080 \ --ctx-size 4096

这里需要注意：

-m后面是模型文件的绝对路径。
--ctx-size表示上下文窗口大小，值越大占用显存越多。
如果显存不足，可以增加--n-gpu-layers的值来调整 GPU 卸载层数。

llama.cpp 启动后，也会提供一个 OpenAI 兼容的/v1/chat/completions接口，WorkBuddy 可以直接对接。

4.3 在 WorkBuddy 中配置自定义模型

回到 WorkBuddy 的“模型管理”页面，选择“添加自定义模型”，填入以下信息：

配置项	示例值	说明
模型名称	Hy4 preview	显示在模型列表里的名字
API 地址	`http://127.0.0.1:11434/v1`	Ollama 兼容接口地址
API Key	任意值，如`local`	本地服务通常不校验，但不能为空
模型 ID	`hy4:latest`	对应 Ollama 中的模型标签

配置完成后，在对话输入框上方的模型切换器里选择“Hy4 preview”，再发送一条消息。

预期结果：消息发送后，WorkBuddy 会调用本地 API，本地推理服务进日志中会出现请求记录，随后 AI 开始回复。

4.4 验证本地联通

如果你不确定配置是否正确，可以直接用 curl 测试 API 接口：

curl http://127.0.0.1:11434/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "hy4:latest", "messages": [ {"role": "user", "content": "用 Python 写一个快速排序"} ] }'

如果返回正常的 JSON 响应，说明接口连通无误，问题大概率出在 WorkBuddy 的配置项上。

4.5 结果说明

配置成功后，你可以在 WorkBuddy 中享受以下能力：

离线对话：关闭外网也能继续使用。
本地数据安全：对话内容不会上传到第三方服务器。
无按次计费：本地推理没有 API 费用。
长上下文可控：通过调整本地推理服务的参数，灵活控制上下文长度。

5. 核心功能实操与进阶用法

当你成功把 Hy4 preview 接入 WorkBuddy 后，接下来可以试试 WorkBuddy 的几个核心功能。下面挑选了几个网上讨论度高、实用性强的场景进行演示。

5.1 用自然语言写网页

WorkBuddy 支持通过“技能（Skill）”让 AI 生成完整网页。接入 Hy4 preview 后，在输入框中输入类似这样的指令：

请帮我生成一个带响应式布局的个人主页 HTML 文件，要求： - 包含导航栏、介绍区、项目展示区、联系表单。 - 使用 Tailwind CSS CDN 引入样式。 - 页面风格简洁，主色调用蓝色系。

Hy4 preview 会在当前上下文里生成完整的 HTML 代码，点击“写入文件”或“复制代码”即可保存到本地。用浏览器打开生成的 HTML 文件，就是一个可直接使用的静态页面。

这里有一个实际经验：本地模型生成的代码质量受上下文长度影响较大。如果你的指令比较复杂，建议把需求拆成“先搭框架 → 再细化模块 → 最后修样式”多个步骤，而不是一次性让 AI 输出一个完整的大型项目。

5.2 做接口自动化测试

WorkBuddy 的一个常见用途是“接口自动化”。你可以在 WorkBuddy 中新建一个任务，让 AI 根据接口文档生成 Python 自动化脚本。

比如，给 AI 粘贴一段接口说明：

POST /api/login 请求参数： username: string password: string 返回参数： code: int token: string

然后输入指令：

请基于上面接口，生成一个 Python requests 自动化测试脚本。 要求包含： - 登录接口的请求封装。 - 断言返回 code 为 200。 - 打印 token。

生成的脚本大致如下：

import requests def login(username: str, password: str) -> str: url = "http://127.0.0.1:8000/api/login" payload = { "username": username, "password": password } resp = requests.post(url, json=payload) assert resp.status_code == 200, f"HTTP Error: {resp.status_code}" data = resp.json() assert data.get("code") == 200, f"Business Error: {data}" return data["token"] if __name__ == "__main__": token = login("test_user", "123456") print("Token:", token)

将脚本保存为test_login.py，在终端执行：

python test_login.py

这样，一个简单的接口自动化用例就完成了。如果你想让它自动生成更完整的测试报告，可以在指令中补充“生成 HTML 测试报告”或“使用 pytest 框架改写”等要求。

5.3 Skill 技能配置

WorkBuddy 的技能（Skill）系统，可以理解为“给 AI 预置一套行为模板”。比如，你可以创建一个名为“Python 代码评审”的技能，技能描述为：

你是一位资深 Python 架构师。当用户提交代码时，请按以下顺序审查： 1. 代码可读性与命名规范。 2. 是否存在异常处理缺失。 3. 是否存在性能瓶颈。 4. 是否考虑边界条件。 5. 给出改进建议与修改后的代码。

之后，只要在对话中切换到该技能，AI 就会按这个模板工作。

网上有很多关于“WorkBuddy skill”的教程，核心就一句话：技能块本质上是一段精心设计的系统提示词。你可以复制别人写好的技能，也可以自己写。使用本地模型时，技能描述尽量简洁明了，因为本地模型的指令遵循能力通常比云端大模型弱一些，过于复杂的技能模板可能导致输出偏差。

5.4 与 Obsidian 联动

WorkBuddy 支持与 Obsidian 联动的插件模式，可以在 Obsidian 中直接唤起 WorkBuddy，将选中文本发送到 AI 对话中。如果你使用本地模型，这个场景非常舒服：笔记内容不需要离开本地电脑，既保护隐私，又能获得 AI 的总结、润色和知识整理能力。

6. 常见问题与排查思路

在实际使用中，本地运行 Hy4 preview + WorkBuddy 最常遇到的问题，我整理成了一个排查表：

问题现象	常见原因	解决思路
安装后无法启动	系统版本过低（如 Win7）	升级到 Win10/11，更新 WebView2 运行时
WorkBuddy 无法连接本地模型	API 地址填写错误	检查本地推理服务是否启动，确认端口和路径
模型回复很慢	CPU 推理，无 GPU 加速	启用 GPU 加速，或使用更小的量化模型
上下文用量满了怎么办	单次对话轮次过多	点击“新对话”，或清理上下文缓存
模型总是重复说一句话	推理温度参数过高或过低	在本地推理服务端调整 temperature 参数
本地模型输出乱码	模型编码与 WorkBuddy 不匹配	检查模型文件是否为最新版，或更换量化版本
WorkBuddy 无法下载模型	模型源网络不稳定	配置镜像源，或先手动下载模型文件再导入
接入后生成的代码不可用	指令太长，模型遗漏细节	拆分成多个步骤，逐步确认后再往下走
部署后占用内存过高	上下文窗口设置过大	降低`--ctx-size`或`num_ctx`参数
无法使用 Skill 功能	客户端版本过旧	升级 WorkBuddy 到最新版本

6.1 上下文用量满了的解决方案

这是搜索热度很高的问题。WorkBuddy 的上下文管理逻辑是，每次对话都会携带历史消息，当累计长度超过模型上限时，会出现“上下文用量已满”的提示。

推荐做法如下：

新开对话：把当前工作总结成一段摘要，复制到新对话中继续使用。
删除历史消息：在会话设置中，清理早期轮次的对话记录。
调整本地模型的上下文窗口：在 Ollama 中通过num_ctx参数调大上下文窗口，例如：

ollama run hy4:latest --num-ctx 8192

这里要提醒一点：调大上下文窗口会显著增加显存和内存占用，如果硬件不够，反而会导致推理速度下降，甚至内存溢出。建议先确认硬件条件，再决定上下文大小。

6.2 排查清单

如果本地模型接入失败，可以按下面的顺序排查：

[ ] 本地推理服务是否还在运行？（浏览器访问http://127.0.0.1:11434看是否有响应）
[ ] 端口是否被其他程序占用？（netstat -ano | findstr 11434查看）
[ ] WorkBuddy 中的 API 地址是否以/v1结尾？
[ ] API Key 是否填写了非空字符串？
[ ] 模型 ID 是否与ollama list中显示的名称完全一致？
[ ] 是否有防火墙拦截了本地回环地址的访问？
[ ] 是否不小心关闭了终端窗口导致服务退出？

7. 最佳实践与工程建议

7.1 模型选择与量化

在本地运行 Hy4 preview 时，模型文件格式和量化方式会直接影响体验。常见的几种情况：

如果你是新手，优先用 Ollama 自动下载的默认量化版本，省心稳定。
如果你显存有限，选择 Q4_K_M 或 Q5_K_M 这类中等量化版本，保留较好的生成质量同时降低资源占用。
如果你追求更高质量的生成结果，可以尝试 Q8 或 FP16 版本，但需要更大的显存。

记住一个原则：本地模型追求的是“在可接受速度下尽量好的质量”，不要一味追求最大参数版本。

7.2 配置管理

在实际项目中，建议把 WorkBuddy 的模型配置信息沉淀为团队文档。例如：

# workbuddy-local-model-config.yaml models: - name: Hy4 preview api_base: http://127.0.0.1:11434/v1 api_key: local model_id: hy4:latest description: 本地运行模型，用于日常问答和代码生成 context_size: 4096

这样做的好处是，换电脑或者团队成员接入时，只需要对照文档配置一次，不需要反复试错。

7.3 文件与数据管理

模型权重文件较大，建议单独放在一个数据盘目录，例如D:\AI\Models或/data/models。
定期清理 WorkBuddy 的缓存目录，避免日志和上下文文件占满磁盘。
对话中涉及机密数据时，务必确认当前使用的是本地模型，而不是云端模型。

7.4 配合外部脚本做自动化

WorkBuddy 本身是 GUI 工具，但它的能力可以通过脚本进一步放大。你可以写一个简单的 Python 脚本，调用本地 Ollama API，把 WorkBuddy 中生成的代码自动保存到项目目录。

示例脚本：

import requests def chat_with_local_model(prompt: str) -> str: resp = requests.post( "http://127.0.0.1:11434/v1/chat/completions", json={ "model": "hy4:latest", "messages": [{"role": "user", "content": prompt}], } ) resp.raise_for_status() return resp.json()["choices"][0]["message"]["content"] if __name__ == "__main__": code = chat_with_local_model("写一个 Python 装饰器，用于打印函数执行时间") print(code)

这种“GUI 操作 + API 脚本调用”的组合，在批量处理任务时非常高效。

7.5 关于安全边界

本地运行模型虽然解决了数据隐私问题，但也要注意新的安全边界：

本地模型的文件来源要可信，尽量从官方渠道或镜像源下载，防止模型权重被植入恶意指令。
不要因为“本地运行”就忽略权限管理，多用户电脑上建议为模型目录设置访问权限。
如果本地推理服务监听了非回环地址（例如0.0.0.0），局域网内的其他设备也能访问，注意控制网络暴露面。

安全上有一个原则可以记住：默认只监听本机回环地址，只有在明确需要局域网共享时才放开监听范围。

8. 总结与下一步学习建议

到这里，我们已经走完了从“了解 Hy4 preview 和 WorkBuddy”到“把模型配置到本地并实际使用”的全流程。

本文的几个核心知识点：

Hy4 preview 是一个适合本地部署的开源模型预览版，结合 WorkBuddy 可以在单机环境获得完整的 AI 工作台体验。
本地运行的核心是“通过 OpenAI 兼容 API 进行模型对接”，WorkBuddy 的自定义模型配置就是围绕这个标准接口展开的。
通过 Ollama 或 llama.cpp 可以快速启动本地推理服务，之后在 WorkBuddy 中填入 API 地址和模型 ID 即可。
上下文管理、技能配置、插件联动、接口自动化是 WorkBuddy 的几大高价值功能，配合本地模型使用时，要注意指令拆分与参数调整。
本地模型使用中最重要的实践原则是：安全、可控、可复现。

如果你接下来想继续深入，可以从这几个方向入手：

学习 Ollama 的更多参数，比如OLLAMA_NUM_PARALLEL、OLLAMA_MAX_LOADED_MODELS等，掌握本地服务的性能调优。
了解 GGUF 量化原理，搞清不同量化等级对显存、速度和生成质量的影响。
尝试给 WorkBuddy 编写自定义 Skill，把日常工作流沉淀成可复用的模板。
研究本地 RAG（检索增强生成）方案，让 Hy4 preview 能基于你自己的文档库来回答问题。

最后补充一句：本地 AI 工具链的变化非常快，本文的配置细节可能在后续版本中有所调整。如果你在操作过程中遇到与文章描述不一致的地方，优先以 WorkBuddy 官方文档和 Ollama 官方文档为准。动手把模型跑起来，比收藏二十篇教程都管用。希望这篇文章能帮你顺利跨过第一步。