ollama v0.30.7 正式发布：Hermes 桌面端落地，接口、文档、底层依赖全方位优化

在这里插入图片描述

在这里插入图片描述

Ollama 于2026年6月9日推送了最新稳定版本 v0.30.7，本次版本迭代累计包含6次代码提交、20个文件变更，覆盖桌面交互能力、OpenAI 兼容接口、项目文档、底层依赖管理、代码逻辑适配、单元测试等多个维度。本次更新核心亮点为正式推出 Hermes Desktop 原生桌面界面，同时完成了接口数据对齐、llama.cpp 升级流程文档补充、结构化输出语法优化、全文档示例模型版本迭代，以及 Windows 平台路径逻辑重构等一系列实用优化，下面将结合发布说明、代码差异、文档修改、单元测试等内容，对 Ollama v0.30.7 所有变更进行完整、细致的拆解。

一、版本核心功能更新：Hermes Desktop 原生桌面界面正式上线

Ollama v0.30.7 最核心的新增能力，是为 Hermes 智能代理配套推出了 Hermes Desktop 原生桌面交互界面。在此前版本中，用户使用 Hermes 代理仅能通过命令行方式进行操作，缺乏可视化管理入口，而本次更新彻底补齐了这一短板。

新版本中，Ollama Launch 命令原生支持 Hermes Desktop，这是专门面向 Hermes 代理打造的原生桌面客户端。用户可以将该桌面程序与 Hermes 代理协同运行，借助可视化界面完成对话管理、第三方集成配置、消息应用对接等一系列操作，大幅降低了 Hermes 代理的使用门槛，尤其适合非专业命令行用户快速上手。

想要启动 Hermes 桌面端，仅需在终端执行一条极简命令即可：

ollama launch hermes-desktop

该命令为全局通用指令，适配本次优化后的全平台逻辑，其中 Windows 平台完成了原生配置路径适配，解决了旧版本中 Windows 系统下 Hermes 配置文件路径识别异常、目录读取不规范等问题，让桌面端在 Windows 环境下运行更加稳定。

二、全局变更总览：提交记录与文件改动概况

本次 v0.30.7 版本共计6次代码提交，涉及20个文件修改，从提交时间线来看，代码提交集中在2026年6月6日至6月8日期间，所有变更分为代码逻辑优化、文档内容更新、新增项目配置文件三大类，每一项变更都对应具体的功能优化与问题修复，整体变更清单如下：

1. 1. 优化 Zod 结构化输出示例，替换为原生 toJSONSchema 工具方法；
2. 2. 重构 Windows 平台下 Hermes 程序的原生配置路径逻辑；
3. 3. 对齐 OpenAI 兼容接口的模型列表与本地模型标签数据；
4. 4. 新增文档，详细描述 llama.cpp 依赖库的升级完整流程；
5. 5. 在项目根目录新增 AGENTS.md 与 CLAUDE.md 两份规范文件；
6. 6. 全量文档示例，将原有 Gemma 3 模型统一替换为 Gemma 4 模型。

除以上功能性变更外，本次更新还配套新增了大量单元测试代码，对 Hermes 路径逻辑、OpenAI 接口模型列表、标签接口数据一致性等能力进行校验，保障新版本功能的稳定性与兼容性。整体代码改动共计445行新增代码、111行删除代码，代码增减集中在业务逻辑、单元测试、文档文本三个板块。

三、项目根目录新增文件解读：AGENTS.md 与 CLAUDE.md

Ollama v0.30.7 在项目根目录新增了两份纯文本规范文件：AGENTS.md 和 CLAUDE.md，两份文件均为全新创建，无原有历史内容，主要用于统一项目开发规范、构建流程说明。

3.1 AGENTS.md 文件内容详解

AGENTS.md 主要用于说明 Ollama 项目的编译、运行与快速迭代流程，分为完整源码编译、Go 代码快速迭代两大使用场景，同时标注了配套参考文档。 文件中明确了从项目根目录进行完整编译的命令流程，基于 cmake 编译工具链实现全量构建，具体命令如下：

cmake -B build .
cmake --build build --parallel 8
./ollama serve

这套流程适用于完整编译 Ollama 所有底层依赖、原生程序与 Go 服务端代码，--parallel 8 代表开启8线程并行编译，提升编译效率，编译完成后通过 ./ollama serve 启动 Ollama 核心服务。

针对开发人员日常调试场景，文件提供了仅针对 Go 代码的快速迭代方案，无需编译底层原生依赖，直接编译并运行 Go 服务，命令如下：

go build .
go run . serve

该方案适用于已有完整原生编译产物、仅修改 Go 业务代码的场景，能够大幅缩短调试耗时。文件最后注明，环境依赖、平台适配说明、GPU 后端配置以及完整开发工作流，可参考项目内 docs/development.md 文档。

3.2 CLAUDE.md 文件内容详解

CLAUDE.md 内容极为简洁，全文仅3行内容，核心作用是指引文档查阅，文件内仅标注：可参考同目录下的 AGENTS.md 文件，获取本项目通用的代理相关规范与开发说明，两份文件形成联动，统一项目内智能代理相关的开发标准。

四、全量文档示例迭代：Gemma 3 统一替换为 Gemma 4

本次更新对项目内几乎所有使用模型示例的文档进行了批量修改，将文档、接口示例、命令行示例、结构化输出示例、视觉能力示例、上下文长度示例中的 gemma3 全部替换为 gemma4，覆盖项目首页、快速开始、CLI 命令参考、API 全系列文档、能力介绍文档等全部公开文档，下面按文档分类逐一说明变更细节。

4.1 首页与快速开始文档变更

项目首页文档中，原有介绍文本列举的模型包含 Gemma 3，本次直接修改为 Gemma 4，同步更新了主流模型展示列表。快速开始文档内的 API 调用示例，将 curl 请求体中的模型字段从 gemma3 修改为 gemma4，保证入门示例与新版本模型对齐。

4.2 命令行（CLI）参考文档变更

CLI 参考文档是用户使用命令行操作的核心参考，本次修改覆盖全部模型操作指令：

1. 1. 运行模型指令：ollama run gemma3 修改为 ollama run gemma4；
2. 2. 多模态模型调用指令：图文结合的运行指令同步替换模型名称；
3. 3. 模型下载指令：ollama pull gemma3 修改为 ollama pull gemma4；
4. 4. 模型删除指令：ollama rm gemma3 修改为 ollama rm gemma4；
5. 5. 自定义模型 Modelfile 模板：模板内 FROM gemma3 修改为 FROM gemma4；
6. 6. 停止运行模型指令：ollama stop gemma3 修改为 ollama stop gemma4。

所有 CLI 相关示例完成统一替换，保证命令行文档与当前主推模型版本一致。

4.3 API 系列文档全量变更

Ollama 原生 REST API 相关文档是对接二次开发、第三方集成的核心资料，本次对 API 介绍、流式响应、错误返回、使用指标、结构化输出、视觉能力六大类 API 文档完成模型示例替换。

1. 1. API 入门文档：基础 generate 接口的 curl 请求示例，模型字段替换为 gemma4；
2. 2. 流式响应文档：流式返回的 ndjson 格式示例数据，每一条返回体中的 model 字段全部修改为 gemma4，同时包含关闭流式返回后的非流式响应示例；
3. 3. 错误返回文档：接口运行报错场景下的流式返回示例，统一替换模型名称，保留原有报错格式与报错信息；
4. 4. 使用指标文档：包含 token 统计、运行指标的响应示例，更新模型字段；
5. 5. 视觉能力（多模态）文档：图片+文本对话的 curl 接口示例、Python SDK 示例、JavaScript SDK 示例，全部将调用模型改为 gemma4，覆盖文件路径传图、二进制传图等场景；
6. 6. 结构化输出文档：Python 结构化输出示例中的模型参数，同步替换为 gemma4。

4.4 上下文长度文档变更

上下文长度文档中展示了运行中模型的状态列表，原有示例展示 gemma3 运行状态，本次修改为 gemma4，同时更新了模型占用大小、上下文窗口等配套示例数据，保持文档示例的完整性。

五、结构化输出优化：Zod 示例改用原生 toJSONSchema 方法

在 Ollama 结构化输出能力文档中，针对 JavaScript 场景的 Zod 数据校验框架使用示例完成语法优化，这也是本次重要的文档与使用规范更新。

旧版本示例中，需要额外引入第三方依赖 zod-to-json-schema，通过 zodToJsonSchema() 方法将 Zod 结构体转换为 JSON Schema，代码存在额外依赖、调用链路较长的问题。本次更新直接移除了第三方依赖引入语句，改用 Zod 框架原生提供的 toJSONSchema 工具方法，调用方式简化为 z.toJSONSchema(结构体)。

对应的代码示例同步修改：删除 import { zodToJsonSchema } from 'zod-to-json-schema' 引入代码，同时将接口请求体中 format 字段的取值，从 zodToJsonSchema(Country) 修改为 z.toJSONSchema(Country)。该优化简化了前端、Node.js 开发者的接入流程，减少了项目依赖，统一了结构化输出的标准用法。

六、新增 llama.cpp 升级流程文档：底层依赖维护规范

llama.cpp 是 Ollama 核心底层依赖，负责模型加载、推理调度、GPU 加速等核心能力，本次 v0.30.7 版本在 llama/ 目录下新增独立 README.md 文档，完整规范了 llama.cpp 依赖库的升级全流程、校验规则、风险点、补丁维护以及跨平台测试要求，填补了此前项目缺少底层依赖升级规范的空白。

6.1 升级核心说明

文档首先明确，Ollama 通过 LLAMA_CPP_VERSION 变量固定绑定特定版本的 llama.cpp，升级该依赖并非简单替换代码，会直接影响模型加载逻辑、GPU 设备探测、任务调度、运行日志、流式响应以及兼容性补丁，因此升级前后必须完成全链路校验，不能仅做代码替换。

6.2 标准升级工作流

文档定义了标准化的升级步骤：

1. 1. 记录当前基线分支中旧的 llama.cpp 提交哈希或标签，选定目标新版本的标签/提交哈希；
2. 2. 修改项目内 LLAMA_CPP_VERSION 变量，指向新版本；
3. 3. 执行 cmake 配置命令拉取指定版本源码，并自动应用项目内的兼容补丁，命令为 cmake -S llama/server --preset cpu；
4. 4. 校验源码目录，默认源码存放路径为 build/llama-server-cpu/_deps/llama_cpp-src，确认目录内代码为目标新版本，禁止使用旧的、未清理的缓存目录做校验。

该配置步骤仅用于源码拉取与补丁应用校验，不做运行时功能验证。完成源码拉取后，可通过 git 命令对比新旧版本差异，使用 git diff 旧版本哈希 新版本哈希 -- 文件路径、git show 新版本哈希:文件路径 查看具体代码变更，同时提醒开发者：不要将打过项目自定义补丁的代码当作上游原生源码进行对比。

6.3 升级重点审查内容

文档明确了升级 llama.cpp 后必须逐项审查的五大模块，覆盖编译、后端、服务、流式、模型全链路：

1. 1. 编译选项与依赖：检查 GGML、LLAMA 系列编译参数变化，新增依赖包、生成资源、着色器工具、后端依赖等，同步核对 CMake 配置文件、Docker 镜像、CI 持续集成脚本；
2. 2. 后端设备探测：校验 GGML 底层符号、设备属性接口、设备类型枚举、后端注册逻辑、设备排序、设备过滤规则，以及 CUDA、ROCm、Vulkan、Metal 各显卡后端的运行库行为；
3. 3. llama-server 服务契约：检查启动参数、默认配置、状态码、错误返回结构、内存日志、显存卸载日志、注意力机制日志、多 GPU 拆分运行等功能，确保 Ollama 上层 Go 代码与底层服务参数兼容；
4. 4. 流式响应能力：监测 SSE 数据流格式、心跳包、保活探测、结束标记、响应频率等变化，保证 Ollama 对流数据的解析逻辑正常；
5. 5. 模型与转换逻辑：适配新模型架构、张量命名、GGUF 元数据、分词器、推测解码、采样器默认参数等，涉及模型转换、模型管理、推理调度的代码均需校验，且不能仅完成模型加载测试，必须发起真实推理请求验证结果。

6.4 兼容性补丁维护规则

Ollama 针对上游 llama.cpp 存在自定义兼容补丁，补丁文件统一存放在 llama/compat/ 目录下，配置阶段会自动应用。若新版本 llama.cpp 导致补丁插入位置偏移，禁止直接修改已打补丁的缓存代码，需要基于全新的上游源码重新生成补丁。

如果兼容代码、CMake 配置发生变更，需要单独编译 CPU 版本的 llama-server 进行验证，命令为 cmake --build build/llama-server-cpu --target llama-server --parallel 12。仅做配置校验无法发现源码缺失、模板实例化、链接报错等问题，必须执行编译验证。同时检查上游新版本是否已原生支持原有自定义补丁功能，若已原生支持，则需要删除本地冗余补丁或对补丁进行代码变基。

6.5 本地验证与端到端测试流程

完成代码与补丁校验后，执行全项目 Go 单元测试，命令为 go test ./...，确保上层业务逻辑无报错。单元测试通过后，编译对应平台的完整 Ollama 发行包。

运行时验证要求覆盖全主流平台与显卡后端：macOS arm64 架构下的 Metal 后端、Linux 与 Windows 平台下的 CUDA、ROCm、Vulkan 后端。编译完成后执行项目集成测试脚本，发起真实的 Ollama 推理请求，核查设备探测、显存卸载、内存统计、注意力机制、请求响应等全链路日志，要求 macOS、Windows、Linux 三大操作系统均完成验证，保证跨平台兼容性。

七、Hermes 模块代码重构：Windows 平台配置路径逻辑优化

本次更新对 cmd/launch/hermes.go 与配套单元测试文件 cmd/launch/hermes_test.go 进行了重点代码重构，核心优化 Windows 系统下 Hermes 程序的配置文件、环境变量文件路径识别逻辑，拆分路径获取函数，优化目录层级，同时保留环境变量自定义路径的能力。

7.1 核心函数拆分与逻辑重构

旧版本代码中，配置路径、环境文件路径直接关联用户主目录，Windows 平台路径识别逻辑混杂。新版本将单一的路径函数拆分为两层：新增 hermesHomePath() 函数用于获取 Hermes 根目录，hermesConfigPath() 函数基于根目录拼接配置文件路径，hermesEnvPath() 函数同样基于根目录拼接环境变量文件路径，代码层级更加清晰。

路径读取优先级规则保持不变：首先读取系统环境变量 HERMES_HOME，如果该变量存在且不为空，优先使用该自定义路径作为 Hermes 根目录；若未配置自定义环境变量，则区分操作系统进行默认路径匹配。

针对 Windows 平台，优先读取系统环境变量 LOCALAPPDATA，将 Hermes 根目录设置为 LOCALAPPDATA/hermes；若该环境变量读取失败，则自动定位到用户目录下的 AppData/Local/hermes 目录。非 Windows 平台，则默认使用用户主目录下的 .hermes 文件夹作为根目录。

在根目录确定后，配置文件固定为根目录下的 config.yaml，环境变量文件固定为根目录下的 .env，简化了目录结构，解决了旧版本 Windows 系统下配置文件散列、路径识别混乱的问题。

hermesBaseURL() 接口地址函数逻辑无变更，依旧是基于 Ollama 服务地址拼接 /v1 后缀，保证 Hermes 与 Ollama 接口通信正常。

7.2 单元测试配套更新

hermes_test.go 针对重构后的路径逻辑新增并修改了多组单元测试用例，覆盖两大核心场景：

1. 1. Windows 原生路径校验：模拟 Windows 环境、配置 LOCALAPPDATA 环境变量，校验程序是否正确读取该路径下的 hermes/config.yaml，替代旧版本用户目录下的隐藏目录路径；
2. 2. 自定义 HERMES_HOME 校验：模拟全平台环境下配置 HERMES_HOME 自定义目录，校验程序优先使用自定义目录，并在自定义目录下读取 config.yaml 配置文件。

所有测试用例模拟临时目录、系统环境变量、操作系统标识，严格校验路径拼接结果，保证重构后的路径逻辑在各种环境下稳定运行。

八、OpenAI 兼容接口优化：模型列表与标签数据对齐

Ollama 提供了与 OpenAI 接口格式兼容的 /v1/models 模型列表接口，本次 v0.30.7 版本修复了该接口数据不一致问题，实现 OpenAI 兼容接口的模型列表与 Ollama 原生 /api/tags 标签接口数据完全对齐，同时优化了模型 ID 取值逻辑，并补充大量单元测试保障一致性。

8.1 核心代码逻辑修改（openai/openai.go）

在 ToListCompletion 函数中，重构了模型 ID 的取值规则：遍历原生接口返回的模型数据时，优先读取数据内的 Model 字段作为接口返回的 Id；如果 Model 字段为空，则降级使用 Name 字段作为 Id。

对应的归属者 OwnedBy 字段，也同步基于最终确定的 Id 进行命名空间解析，而非旧版本固定使用 Name 字段解析，彻底解决了不同字段取值不一致导致的接口数据错乱问题。

8.2 单元测试补充（openai/openai_test.go、server/routes_list_test.go）

为验证接口逻辑，项目新增两组完整单元测试：

1. 1. 模型标识规则测试：构造两组测试数据，一组同时包含 Name 与 Model 字段，一组仅包含 Name 字段，校验接口优先使用 Model 字段作为 ID、降级使用 Name 字段，同时校验命名空间、创建时间等字段的解析结果；
2. 2. 双接口数据一致性测试：在服务路由测试文件中，创建多个本地模型，修改模型清单的修改时间，分别请求原生 /api/tags 接口与 OpenAI 兼容 /v1/models 接口，逐行对比模型 ID、创建时间、排序规则，确保两个接口返回的模型数量、模型标识、时间戳、排序顺序完全一致。

该优化解决了第三方基于 OpenAI 格式对接 Ollama 时，模型名称不匹配、列表排序错乱的问题，提升了接口兼容性。

九、其他配套文件变更

1. 1. openapi.yaml：OpenAPI 接口描述文件同步完成对应修改，共计154行代码增减，适配接口字段、示例模型的变更；
2. 2. 全链路示例联动：所有涉及模型调用、接口返回、命令行操作的文档、配置、测试用例全部完成联动修改，保证整个项目示例、代码、文档、测试用例版本统一。

总结

代码地址：github.com/ollama/ollama

Ollama v0.30.7 是一次兼顾功能新增、体验优化、底层规范、接口兼容、文档完善的综合性版本更新。从用户使用层面，Hermes Desktop 原生桌面界面上线，让智能代理告别纯命令行操作，可视化管理能力大幅提升，同时优化了 Windows 平台的目录适配，提升跨平台使用体验；从开发者层面，Zod 结构化输出语法简化、OpenAI 兼容接口数据对齐，降低了二次开发与第三方集成成本；从项目维护层面，新增 llama.cpp 升级规范、根目录开发规范文件，补齐了底层依赖维护流程，重构 Hermes 路径代码并补充大量单元测试，提升项目健壮性。

我们相信人工智能为普通人提供了一种“增强工具”，并致力于分享全方位的AI知识。在这里，您可以找到最新的AI科普文章、工具评测、提升效率的秘籍以及行业洞察。