Hy4 preview 本地部署 WorkBuddy：环境配置与调用实践

Hy4 preview 登陆 WorkBuddy，支持本地运行，意味着你在个人电脑或办公电脑上也能使用这个预览版模型，而不必把所有请求都送往远程服务。对很多关注模型落地的人来说，真正有价值的不是模型列表里多了一个名字，而是 WorkBuddy 把运行模式的选择权交还给了用户：既可以继续使用云端 API，也可以把模型权重放到本机，在断网、敏感数据或长期高频调用场景下继续工作。这篇文章会以实际配置为主线，先讲清楚 WorkBuddy 和 Hy4 preview 各自负责什么，再带领你完成环境检查、模型配置、调用验证和问题排查。

1. 先理解 WorkBuddy 和 Hy4 preview 的定位

1.1 WorkBuddy 是什么样的工作台

从现有功能和使用方式来看，可以把 WorkBuddy 理解成一个聚合型 AI 工作台，把对话、文档处理、网页生成、接口自动化、文本写作等任务集中到一个入口。它和单纯的编程助手不同：CodeBuddy 这类工具通常面向代码编辑场景，而 WorkBuddy 更偏向办公、内容整理和日常自动化。用户可以在 WorkBuddy 中使用多个模型，也可以为不同任务切换不同的技能或插件。

这个定位意味着模型选择对 WorkBuddy 来说不是一个附属功能，而是核心工作流的一部分。你在里面写的每一段提示词、整理的每一份文档、触发的每一个自动化任务，最终都会落到某个模型上。所以“支持哪个模型”“是否支持本地运行”并不是锦上添花，而是决定这个工作台能否进入生产环境的关键条件。

1.2 Hy4 preview 给 WorkBuddy 带来什么

Hy4 preview 是一个预览版模型。Preview 的含义是功能已经基本完整，但可能还会调整参数、接口或输出行为。把它放到 WorkBuddy 里使用，意味着你可以在一个已经封装好的工作台界面中直接试用新模型，不必单独搭建一套推理服务。

预览版模型的价值主要体现在三方面：一是快速评估模型的基础能力，包括写作、总结、代码生成和指令理解；二是验证模型是否适合某个具体工作流，比如提取文档、自动回复、格式化输出；三是和现有模型做对比，决定是否在正式项目中切换。由于它支持本地运行，评估过程不需要把内部文档发送到外部服务，对需要控制数据流向的团队来说尤其重要。

1.3 本地运行与云端调用的差异

本地运行和云端 API 最大的差异在于请求路径。云端调用会把消息发送到远程服务器，由服务方完成推理后返回结果；本地运行则是在你自己的机器上加载模型权重，整个推理链路不离开本地。这让它在隐私、成本、可用性上有不同表现。

本地运行并不是没有代价。模型文件通常会占用几个 GB 到几十 GB 的磁盘，推理时的显存或内存占用也很高；如果本机算力不足，生成速度会明显慢于云端。所以在动手配置之前，先做环境检查比直接下载模型更值得。

2. 环境与依赖：先确认条件，再下载模型

2.1 操作系统和基础环境检查

本地运行模型对操作系统有要求。当前主流工作台类应用通常支持 Windows 10/11、macOS 和主流 Linux 发行版。Windows 7 不在支持范围内的情况很常见，原因是模型推理依赖的新版运行库、GPU 驱动和文件系统能力在旧系统上没有完整适配。如果你还在使用 Windows 7，建议先不要尝试把 WorkBuddy 作为主力工具装上去，至少要把系统升级到 Windows 10 或更高版本。

启动前建议确认以下几项：

• 系统版本：Windows 10 22H2、macOS 12 以上或 Ubuntu 20.04/22.04。
• Python 版本：如果 WorkBuddy 通过 Python 环境运行，Python 3.10 或 3.11 通常是兼容性较稳妥的选择。
• 显卡驱动：NVIDIA 显卡用户需要更新到支持 CUDA 的近期驱动，并确认驱动版本和推理框架匹配。
• 磁盘空间：预留至少 20 GB 空闲空间，模型文件之外还要考虑缓存和日志。
• 网络条件：第一次下载模型需要能访问模型托管站点或镜像源，后续推理可以不联网。

建议在安装 WorkBuddy 前先把这些环境信息记录下来，写到环境检查清单里，方便出问题时对照。

2.2 硬件要求与量化选择

Hy4 preview 能在哪些硬件上跑取决于模型体积和量化方式。量化是把模型权重从高精度压缩到低精度的过程，可以显著降低显存和内存占用，但会带来轻微精度损失。

注意，“显存够不够”不能只看模型权重大小。推理时的 KV Cache、临时激活值、上下文长度都会占用额外显存。即使模型权重压缩到 4 GB，上下文设置过长也可能把显存顶满。

2.3 软件依赖与版本匹配

WorkBuddy 自身的版本、模型文件格式和推理引擎三者需要匹配。如果 WorkBuddy 从界面配置模型，通常会自动检测文件格式；如果通过配置文件手动指定，就要注意路径和格式。

推荐在安装完成后执行一次自检。如果 WorkBuddy 提供类似workbuddy doctor的运维命令，可以用它检查环境；如果不提供，就在模型管理页面查看是否有“环境检测”或“诊断”按钮。下面是一个示例命令：

workbuddy doctor

预期输出会包含系统版本、GPU 是否可用、CUDA 版本、推理框架加载状态等信息。如果出现GPU not found或cuda unavailable，不要继续配置模型，先解决驱动或运行时依赖问题。

注意：不要只看模型能不能下载成功，还要关注推理引擎能否识别你的硬件。下载成功只代表文件齐全，不代表模型能跑起来。

3. 把 Hy4 preview 配置到 WorkBuddy 的完整流程

3.1 准备模型文件

本地运行的前提是获得模型权重文件。Hy4 preview 可能通过两种途径进入 WorkBuddy：一种是 WorkBuddy 内置的模型管理仓库中直接拉取，另一种是你手动下载后指定路径。无论哪一种，最终都要让 WorkBuddy 知道你使用的模型标识和文件位置。

如果你使用模型管理页面，操作路径一般是：打开 WorkBuddy，进入模型管理，找到 Hy4 preview，点击下载。下载完成后，界面上通常会显示已就绪状态。如果你使用手动方式，则需要记住权重文件的根目录。一个典型的目录结构可能如下：

hy4-preview/ ├── config.json ├── tokenizer.json ├── model.safetensors └── generation_config.json

不要手动改名，也不要只拷贝model.safetensors而忽略config.json和tokenizer.json。模型文件和配置文件必须放在同一个目录，推理引擎才能正确加载。

3.2 修改 WorkBuddy 配置文件

安装并首次启动后，WorkBuddy 通常会在用户目录下生成配置文件夹，例如~/.workbuddy/。该目录下可能存在config.yaml或models.json等文件。下面给出一个通用 YAML 示例，字段名以你安装的实际版本为准：

model: name: hy4-preview path: D:/models/hy4-preview device: cuda quantization: int4 context_length: 8192 temperature: 0.7 max_output_tokens: 2048

各字段的含义如下：

• name：模型标识，在 WorkBuddy 中显示的名称。
• path：模型权重所在目录，一定要使用绝对路径。
• device：cuda表示用 NVIDIA 显卡，cpu表示纯 CPU，mps表示使用 Apple Silicon 的图形处理器。
• quantization：量化级别，常见值为fp16、int8、int4。
• context_length：上下文窗口长度，即模型能参考的 Token 数上限。
• temperature：采样温度，值越大输出越随机，值越小输出越确定。
• max_output_tokens：单次生成的最大 Token 数。

保存配置文件后，回到 WorkBuddy 主界面，重启应用或重新加载模型配置。配置不生效的第一反应不应该是“重启电脑”，而是检查配置文件保存的位置和文件名是否正确。

3.3 验证模型是否被发现

配置完成后，可以先用命令行入口确认 WorkBuddy 是否识别到模型。下面的命令用于说明思路，实际命令名称以你安装的 WorkBuddy 版本为准：

workbuddy models list

如果返回结果中有hy4-preview且状态为ready，说明模型已被发现。如果状态显示not found，则说明路径配置错误。此时回到.workbuddy目录，检查模型路径是否准确、文件名是否完整。

如果 WorkBuddy 没有命令行入口，也可以在界面里的模型选择器下拉框中查找 Hy4 preview。能看到模型名称只是第一步，真正可靠的验证是发起一次对话请求，这在下一节说明。

4. 本地调用的入口与上下文管理

4.1 在对话界面中使用 Hy4 preview

WorkBuddy 的模型选择器通常位于会话窗口顶部。把模型切换到 Hy4 preview 后，发送一条简单的测试消息，例如“请用三句话说明本地推理的优点”。如果模型在正常时间内返回内容，说明基本通路已打通。

在对话界面使用时，要注意一个容易被忽略的问题：同一会话会累积历史记录。WorkBuddy 每次发送给模型的并不只是你最新输入的内容，而是会把过往消息一起发给模型，从而保证多轮对话连贯。这也意味着上下文用量会随对话增长。

4.2 使用脚本调用本地模型

除了界面，WorkBuddy 也常被用于自动化流程，例如接口自动化、文档批量处理。此时需要通过脚本调用本地模型。如果 WorkBuddy 提供了 Python SDK，调用方式可能如下：

from workbuddy.sdk import WorkBuddyClient client = WorkBuddyClient.from_config("config.yaml") response = client.chat( model="hy4-preview", messages=[ {"role": "user", "content": "请把下面这段文字改成通知格式：项目本周五前提交测试报告。"} ], stream=False, ) print(response["text"])

这段代码的关键是WorkBuddyClient从同一个配置文件读取模型路径，所以脚本和 WorkBuddy 指向的是同一个模型实例。如果脚本报“模型未注册”，优先检查配置文件的name是否和实际一致。脚本调用更适合批量任务，例如生成多个文档草稿、批量改写、提取结构化字段。批量任务前先做一次小批量试运行，确认输出质量和响应时间，再放量。

4.3 上下文用量是什么，满了之后会发生什么

“上下文用量满了”是本地运行常见问题。上下文窗口由context_length参数控制。当对话累积的 Token 数超过设置上限，模型就无法再接受新的输入，表现为发送消息后没有正常响应、直接报错，或应用提示“上下文已满”。

不同应用的处理方式不同：有些会截断最旧的历史消息，有些会触发自动压缩摘要，有些则直接拒绝发送。WorkBuddy 中遇到上下文用量满，优先清理当前会话，把不必要的长文本从对话中移出，或另开一个会话。更稳妥的方式是在配置文件中调大context_length，但要注意显存占用会同步上升。

注意：调大上下文长度不是万能的。上下文翻倍，KV Cache 占用通常也接近翻倍，显存不足时模型可能加载失败或在推理中途报 OOM。

5. 验证运行结果：从日志到响应质量

5.1 检查模型加载日志

模型启动后，WorkBuddy 或推理引擎会输出加载日志。日志里的这些信息值得关注：

Loading model from D:/models/hy4-preview Quantization: int4 Device: cuda Context length: 8192 Model loaded successfully.

Model loaded successfully只代表推理引擎把权重读进了内存，不代表生成结果一定正确。下一步仍需要用任务验证输出质量。很多本地部署失败发生在“能加载但生成乱码”或“能加载但回答与问题无关”，这类问题不是路径错误，而是模型文件损坏、量化参数错误或推理引擎与模型格式不兼容。

5.2 用一组简单任务验证输出

验证本地模型时，不要只问“你是谁”。建议准备一组可重复的小任务，覆盖模型的基本能力：

• 指令遵循：让模型按指定格式输出。
• 文本总结：输入一段 500 字材料，要求输出 3 个要点。
• 结构化输出：让模型输出一段 JSON，再检查字段是否合法。
• 多轮一致性：连续追问两个相关问题，看模型是否记得前文。

每组任务都要记录输出、耗时和上下文用量。下面的表格记录一次验证过程：

如果结构化输出频繁解析失败，可以降低temperature，或在提示词中给出更严格的输出模板。

5.3 关键性能指标看哪些

本地推理的性能可以从三个维度观察：首 Token 延迟、生成速度和上下文扩展后的显存变化。

首 Token 延迟描述用户发消息后到收到第一个字的时间，主要受模型加载、预填充和硬件速度影响。生成速度通常用 Tokens/s 表示，即每秒生成多少个 Token。显存占用则决定你能同时打开多长的上下文。

建议在负载测试时用nvidia-smi之类的命令观察显卡状态：

nvidia-smi

关注显存使用量和 GPU 利用率。如果显存占用接近上限，说明当前模型和上下文配置已经很紧张；如果 GPU 利用率长期低于 50%，可能瓶颈在 CPU 或数据读取，而不是显卡。

6. 常见问题排查：从安装到运行

6.1 上下文用量满了怎么办

现象：会话窗口提示上下文已满，或发送消息后没有响应。

处理顺序：

1. 先看上下文设置，确认context_length是多少。
2. 清理当前会话中的长历史记录，或重新开一个会话。
3. 如果想在不丢失前文的情况下继续，使用摘要功能把前文压缩成简短内容。
4. 如果经常出现上下文满，考虑调大context_length，同时观察显存占用。
5. 如果调大后 OOM，则减少同时打开的会话数量，或使用更低的量化级别。

6.2 Windows 7 为什么用不了 WorkBuddy

现象：在 Windows 7 上安装失败或启动白屏。

原因：WorkBuddy 依赖的新版浏览器组件、图形接口、运行库和 GPU 驱动在 Windows 7 上缺少系统级支持。即使强行安装，模型推理也可能因为缺少新版 CUDA 或深度学习运行时而崩溃。

处理方式：

• 优先升级到 Windows 10/11。
• 如果硬件不支持升级，可以考虑在旧机器上用旧版 WorkBuddy，但不要期待新模型功能完整。
• 检查虚拟机或远程 Linux 环境，把本地模型放在其他机器运行，旧电脑只做远程客户端。

6.3 如何把 WorkBuddy 从 C 盘移到 D 盘

现象：C 盘空间紧张，想迁移安装目录和模型缓存。

处理建议：

• 如果 WorkBuddy 支持自定义安装路径，在安装时直接选择 D 盘。
• 已安装时，先把 WorkBuddy 的安装目录复制到 D 盘，再修改快捷方式的启动路径。
• 模型缓存目录通常在用户目录下，例如~/.cache/workbuddy或~/.workbuddy/models，可以把该目录移动到 D 盘，然后在配置文件中用绝对路径指向新位置。
• 不要直接剪切正在使用的目录，先退出 WorkBuddy，再移动，启动一次确认配置仍然生效。

6.4 能否通过 API 接入 WorkBuddy

不少用户希望把 WorkBuddy 接入自己的脚本或第三方工具，这是可行的。WorkBuddy 如果提供 API 服务，通常可以在设置页开启本地监听端口，然后通过 HTTP 请求调用。也可以反过来，为 WorkBuddy 配置一个外部 API 模型地址。

两种方向要分清楚：

• 把 WorkBuddy 当作服务端：其他程序通过 API 调用 WorkBuddy，底层使用 Hy4 preview 本地模型。
• 把 WorkBuddy 当作客户端：WorkBuddy 连接外部 API 模型，本地只负责界面和任务编排。

实际配置时先确认你要哪种方向。本地运行的核心优势是第一种：数据不出内网，其他工具仍然通过标准接口消费模型能力。

7. 最佳实践：把本地模型用成生产级服务

7.1 把配置和缓存管理干净

本地模型最容易失控的是“文件到处放”。推荐建立一个统一目录，例如D:/ai-models，按模型名分子目录，把权重、日志和缓存分开。WorkBuddy 的配置目录也单独备份，确保重装系统后可以快速恢复。

配置变更前先备份原配置文件。不要在生产环境直接修改正在运行的配置，改完要重新加载并验证一次，再切换到新的任务。

7.2 多模型切换和工具边界

WorkBuddy、CodeBuddy、Trae 这类工具容易混淆。实际项目中可以按任务类型划分：需要代码补全和重构时使用编程助手，需要文档、办公自动化、网页生成时使用 WorkBuddy。Hy4 preview 在 WorkBuddy 中更适合办公类任务，不要在它身上期待与专用代码模型完全一致的表现。

多模型并存时，给每个模型建立能力档案，记录适合的任务、上下文长度、温度和量化参数。下次切回时不需要重新试错。

7.3 调优路线与检查清单

把本地模型从“能跑”变成“稳定用”，建议按下面的检查清单逐步调整：

• 首次安装后先跑环境自检，确认 GPU 和驱动可用。
• 用一个标准测试集验证模型输出质量，不要在正式任务中临时试。
• 高频调用前先预热模型，避免首请求加载过慢。
• 为不同任务设置不同的context_length，不要全局拉满。
• 在配置中启用日志输出，保留最近一次异常现场。
• 升级 WorkBuddy 或模型前备份配置，并保留上一个可用版本。
• 如果模型输出随机性过高，先降低temperature，不要直接更换模型。
• 在正式使用前明确回退方案，保留一个行为稳定的备用模型。

本地模型不是配置完就一劳永逸。随着任务变多，上下文管理、显存调优和版本升级都会变成持续工作。把环境信息、模型路径、验证结果都记录下来，遇到问题排查会顺利很多。

Hy4 preview 登陆 WorkBuddy 并支持本地运行，对个人用户和小团队来说，关键价值是可以用较低门槛把模型纳入日常办公流程。最重要的不是模型列表多了一个名字，而是你拥有了选择运行位置的能力。建议从一个小任务开始，先跑通对话、确认日志、记录上下文用量，再逐步扩展到批量任务。这样即使遇到问题，也只需要对着配置和日志排查，不会因为一个模型把整个工作台拖进不可维护的状态。