(src) >> 4;\n return lookup[highbits];\n}\n```\n\n该函数通过查表方式快速判断 UTF-8 字符的字节长度，支持 1-4 字节的 UTF-8 编码。\n\n资料来源：[llama/llama.cpp/src/unicode.cpp:1-35]()\n\n## 推理工作流程\n\n```mermaid\nsequenceDiagram\n participant App as Go 应用\n participant CGO as CGO 桥接层\n participant Llama as llama.cpp 核心\n participant GGML as GGML 库\n participant Backend as GPU/CPU 后端\n\n App->>CGO: 加载模型 (llama_load_model_from_file)\n CGO->>Llama: 调用 C++ 接口\n Llama->>GGML: 初始化张量\n GGML->>Backend: 选择最优后端\n Backend-->>GGML: 后端就绪\n GGML-->>Llama: 张量初始化完成\n Llama-->>CGO: 模型句柄\n CGO-->>App: 返回 Model 对象\n\n App->>CGO: 执行推理 (llama_decode/llama_tokenize)\n CGO->>Llama: 前向传播\n Llama->>GGML: 层计算\n GGML->>Backend: 硬件加速计算\n Backend-->>GGML: 计算结果\n GGML-->>Llama: 输出张量\n Llama-->>CGO: token 结果\n CGO-->>App: 推理完成\n```\n\n## 错误处理机制\n\n系统定义了统一的错误处理流程，包括跨平台错误码转换：\n\n```cpp\n#if defined(_WIN32)\nstatic std::string llama_format_win_err(DWORD err) {\n LPSTR buf;\n size_t size = FormatMessageA(\n FORMAT_MESSAGE_ALLOCATE_BUFFER | FORMAT_MESSAGE_FROM_SYSTEM | FORMAT_MESSAGE_IGNORE_INSERTS,\n NULL, err, MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT), \n (LPSTR)&buf, 0, NULL);\n if (!size) {\n return \"FormatMessageA failed\";\n }\n std::string ret(buf, size);\n LocalFree(buf);\n return ret;\n}\n#endif\n```\n\n资料来源：[llama/llama.cpp/src/llama-mmap.cpp:40-55]()\n\n## 编译配置\n\n### 交叉编译支持\n\nllama.go 提供了 Windows 平台的特殊编译配置：\n\n```go\n// #cgo windows CPPFLAGS: -D_WIN32_WINNT=0x0602\n```\n\n这确保在 Windows Vista 及以上版本使用最新的 API 特性。\n\n### C++ 标准\n\n整个后端系统要求使用 C++17 标准编译，确保现代 C++ 特性的可用性：\n\n```go\n// #cgo CXXFLAGS: -std=c++17\n```\n\n## 总结\n\nOllama 的 LLM 后端系统是一个高度模块化、高性能的推理引擎架构。通过深度集成 llama.cpp 和 GGML，它实现了：\n\n- **多后端支持**：统一接口管理 CPU、CUDA、Metal、Vulkan 等多种计算后端\n- **高效内存管理**：通过内存映射和 KV 缓存技术优化资源利用\n- **跨平台兼容**：支持 Linux、Windows、macOS 等主流操作系统\n- **灵活的量化支持**：从 fp32 到 int2 多种精度选项\n\n该架构设计使得 Ollama 能够在不同硬件环境下提供一致的推理体验，同时最大化利用硬件性能。\n\n---\n\n\n\n## 命令行系统\n\n### 相关页面\n\n相关主题：[项目概述](#page-overview), [系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [cmd/cmd.go](https://github.com/ollama/ollama/blob/main/cmd/cmd.go)\n- [cmd/interactive.go](https://github.com/ollama/ollama/blob/main/cmd/interactive.go)\n- [cmd/config/config.go](https://github.com/ollama/ollama/blob/main/cmd/config/config.go)\n- [cmd/launch/launch.go](https://github.com/ollama/ollama/blob/main/cmd/launch/launch.go)\n- [cmd/tui/tui.go](https://github.com/ollama/ollama/blob/main/cmd/tui/tui.go)\n- [cmd/start.go](https://github.com/ollama/ollama/blob/main/cmd/start.go)\n \n\n# 命令行系统\n\n## 概述\n\nOllama 的命令行系统是用户与本地大语言模型交互的核心接口，提供模型管理、推理执行、配置管理等完整功能。该系统基于 Go 语言构建，采用模块化架构设计，通过 `cobra` 命令行框架实现层次化的命令结构。\n\n命令行系统的主要职责包括：接收用户输入的命令、解析参数、执行相应的业务逻辑、格式化输出结果。整个系统遵循单一入口原则，通过 `cmd/cmd.go` 中的根命令统一调度所有子命令。\n\n## 架构设计\n\n### 整体架构图\n\n```mermaid\ngraph TD\n A[命令行入口] --> B[根命令 RootCmd]\n B --> C[run 子命令]\n B --> D[serve 子命令]\n B --> E[pull 子命令]\n B --> F[push 子命令]\n B --> G[list 子命令]\n B --> H[show 子命令]\n B --> I[create 子命令]\n B --> J[ps 子命令]\n B --> K[stop 子命令]\n B --> L[rm 子命令]\n B --> M[copy 子命令]\n \n C --> N[启动推理服务]\n D --> O[后台服务模式]\n \n N --> P[TUI 交互界面]\n O --> Q[HTTP API 服务]\n \n P --> R[交互式输入处理]\n R --> S[流式响应渲染]\n S --> T[Unicode 文本处理]\n```\n\n### 核心模块说明\n\n| 模块路径 | 功能说明 | 依赖关系 |\n|---------|---------|---------|\n| `cmd/cmd.go` | 根命令定义与命令注册 | 依赖 cobra 框架 |\n| `cmd/start.go` | 应用启动入口与初始化 | 依赖 config、launch |\n| `cmd/interactive.go` | 交互式对话处理逻辑 | 依赖 tui 模块 |\n| `cmd/tui/tui.go` | 终端用户界面渲染 | 独立模块 |\n| `cmd/config/config.go` | 配置管理与持久化 | 依赖文件系统 |\n| `cmd/launch/launch.go` | 服务启动与进程管理 | 依赖系统调用 |\n\n## 命令结构\n\n### 根命令设计\n\nOllama 的命令行采用树形命令结构，所有子命令都注册在根命令 `RootCmd` 下。根命令负责全局参数解析和环境变量处理，确保所有命令共享相同的配置上下文。\n\n根命令定义了以下全局标志位：\n\n| 标志位 | 类型 | 默认值 | 说明 |\n|-------|------|-------|------|\n| `--verbose` | bool | false | 启用详细输出模式 |\n| `--host` | string | 空 | 指定服务地址 |\n| `--port` | int | 11434 | 指定服务端口 |\n| `--models` | string | 用户目录 | 模型存储路径 |\n| `--keepalive` | duration | 5m | 模型加载后保留时间 |\n\n资料来源：[cmd/cmd.go:1-100]()\n\n### 子命令详解\n\n#### run 命令\n\n`run` 命令用于启动模型推理并进入交互式对话模式。这是用户最常用的命令之一，支持直接传入模型名称即可开始对话。\n\n```mermaid\ngraph LR\n A[ollama run llama3] --> B[加载模型权重]\n B --> C[初始化推理引擎]\n C --> D[启动 TUI 界面]\n D --> E[等待用户输入]\n E --> F[流式推理处理]\n F --> G[渲染响应结果]\n G --> E\n```\n\n执行流程如下：\n\n1. 解析模型名称和可选参数\n2. 调用 `launch` 模块加载模型\n3. 初始化推理上下文和令牌生成器\n4. 启动交互式 TUI 界面\n5. 处理用户输入并生成流式响应\n\n资料来源：[cmd/interactive.go:1-150]()\n\n#### serve 命令\n\n`serve` 命令将 Ollama 作为后台守护进程运行，提供 HTTP API 服务供外部调用。该模式下系统监听指定端口，响应来自客户端的推理请求。\n\n启动参数说明：\n\n| 参数 | 说明 | 默认值 |\n|-----|------|-------|\n| `--host` | 绑定地址 | 127.0.0.1 |\n| `--port` | 监听端口 | 11434 |\n| `--log` | 日志级别 | info |\n| `--background` | 是否后台运行 | false |\n\n服务启动后会创建 HTTP 服务器，注册推理、嵌入、模型管理等多个路由处理器。\n\n资料来源：[cmd/launch/launch.go:1-100]()\n\n#### 模型管理命令\n\nOllama 提供完整的模型生命周期管理命令集：\n\n| 命令 | 功能 | 示例 |\n|-----|------|-----|\n| `pull` | 下载模型 | `ollama pull llama3` |\n| `push` | 上传模型 | `ollama push user/model` |\n| `list` | 列出本地模型 | `ollama list` |\n| `show` | 显示模型信息 | `ollama show llama3` |\n| `create` | 从 Modelfile 创建 | `ollama create custom --file Modelfile` |\n| `rm` | 删除模型 | `ollama rm llama3` |\n| `copy` | 复制模型 | `ollama copy src dest` |\n| `ps` | 查看运行中的模型 | `ollama ps` |\n| `stop` | 停止模型推理 | `ollama stop llama3` |\n\n资料来源：[cmd/cmd.go:100-300]()\n\n## 配置系统\n\n### 配置存储结构\n\nOllama 采用分层配置策略，支持环境变量、配置文件、命令行标志三种配置方式。配置按优先级从低到高排列为：默认配置 < 配置文件 < 环境变量 < 命令行参数。\n\n```mermaid\ngraph TD\n A[配置加载] --> B[读取默认配置]\n B --> C[加载配置文件]\n C --> D[应用环境变量]\n D --> E[解析命令行参数]\n E --> F[最终配置合并]\n```\n\n配置文件采用 TOML 格式存储在用户配置目录：\n\n| 平台 | 配置文件路径 |\n|-----|-------------|\n| Linux | `~/.config/ollama/config.toml` |\n| macOS | `~/Library/Application Support/ollama/config.toml` |\n| Windows | `%APPDATA%\\ollama\\config.toml` |\n\n配置项包括：模型默认路径、日志级别、API 超时设置、GPU 内存限制等。\n\n资料来源：[cmd/config/config.go:1-120]()\n\n### 环境变量配置\n\nOllama 支持通过环境变量覆盖默认配置，主要环境变量列表如下：\n\n| 环境变量 | 类型 | 说明 |\n|---------|------|-----|\n| `OLLAMA_HOST` | string | 服务绑定地址 |\n| `OLLAMA_PORT` | int | 服务监听端口 |\n| `OLLAMA_MODELS` | string | 模型存储目录 |\n| `OLLAMA_KEEPALIVE` | duration | 模型保活时间 |\n| `OLLAMA_DEBUG` | bool | 调试模式开关 |\n| `OLLAMA_NOHISTORY` | bool | 禁用命令历史记录 |\n\n资料来源：[cmd/config/config.go:200-280]()\n\n## 交互式界面\n\n### TUI 组件架构\n\n交互式对话界面（Terminal User Interface）由 `cmd/tui/tui.go` 模块实现，采用分层渲染架构。界面分为输入区、输出区、状态栏三个主要区域。\n\n```mermaid\ngraph TD\n A[TUI 渲染器] --> B[Header 组件]\n A --> C[Message 组件]\n A --> D[Input 组件]\n A --> E[StatusBar 组件]\n \n B --> F[模型信息显示]\n B --> G[对话状态指示]\n \n C --> H[用户消息样式]\n C --> I[助手消息样式]\n C --> J[工具调用显示]\n \n D --> K[多行输入支持]\n D --> L[历史命令导航]\n \n E --> M[Token 计数]\n E --> N[处理状态]\n```\n\n消息组件支持多种内容类型的渲染，包括纯文本、带格式文本、代码块、工具调用结果等。对于流式输出，系统采用增量渲染策略，边接收边显示。\n\n资料来源：[cmd/tui/tui.go:1-200]()\n\n### 输入处理流程\n\n交互模式下的输入处理涉及多轮对话上下文管理和流式响应渲染。系统维护一个消息历史列表，每次交互时将用户输入追加到历史并携带完整上下文发送给推理引擎。\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant I as Input Handler\n participant M as Message Manager\n participant E as Engine\n participant R as Renderer\n \n U->>I: 输入文本\n I->>M: 添加用户消息\n M->>E: 发送带上下文的请求\n E-->>R: 流式 Token\n R->>R: 增量渲染\n E-->>M: 完成响应\n M->>M: 添加助手消息\n M->>U: 显示完整对话\n```\n\nUnicode 文本处理模块负责正确的 UTF-8 编码解码和多语言字符渲染，确保中文、日文等非 ASCII 字符的正确显示。\n\n资料来源：[cmd/interactive.go:150-300]()\n\n## 启动流程\n\n### 应用初始化序列\n\nOllama 启动时经历一系列初始化步骤，从命令行解析到服务就绪的完整流程如下：\n\n```mermaid\nflowchart TD\n A[程序入口 main] --> B[初始化日志系统]\n B --> C[加载用户配置]\n C --> D[解析命令行参数]\n D --> E{命令类型判断}\n \n E -->|run 命令| F[加载指定模型]\n E -->|serve 命令| G[初始化 HTTP 服务器]\n E -->|其他命令| H[执行对应操作]\n \n F --> I[启动 TUI 交互]\n G --> J[注册路由处理器]\n J --> K[开始监听请求]\n \n H --> L[执行完成后退出]\n I --> M[处理交互循环]\n K --> M\n```\n\n`cmd/start.go` 负责协调整个启动过程，包括信号处理、优雅关闭、超时控制等关键逻辑。系统支持通过 `SIGINT` 和 `SIGTERM` 信号优雅退出，确保正在进行的推理任务能够正常完成或保存状态。\n\n资料来源：[cmd/start.go:1-150]()\n\n### 进程生命周期管理\n\n后台服务模式下的进程管理涉及端口占用检测、进程标识持久化、配置热更新等机制。启动时系统会在配置目录创建 PID 文件记录进程 ID，便于后续管理操作。\n\n| 状态 | 说明 | 触发条件 |\n|-----|------|---------|\n| Starting | 启动中 | 进程启动 |\n| Ready | 就绪 | 服务绑定端口成功 |\n| Running | 运行中 | 处理推理请求 |\n| Stopping | 停止中 | 收到终止信号 |\n| Stopped | 已停止 | 进程退出 |\n\n资料来源：[cmd/launch/launch.go:100-250]()\n\n## 错误处理与日志\n\n### 错误分类\n\n命令行系统对错误进行了分类处理，不同类型的错误对应不同的用户提示和恢复策略：\n\n| 错误类型 | 错误码前缀 | 处理方式 | 示例 |\n|---------|----------|---------|-----|\n| 模型加载错误 | `ERR_MODEL_LOAD` | 提示检查模型文件 | 模型文件损坏 |\n| 推理错误 | `ERR_INFERENCE` | 显示错误信息 | 内存不足 |\n| 网络错误 | `ERR_NETWORK` | 建议检查服务状态 | 端口被占用 |\n| 配置错误 | `ERR_CONFIG` | 提示修正配置 | 配置文件格式错误 |\n| 权限错误 | `ERR_PERMISSION` | 提示检查权限 | 无法写入模型目录 |\n\n日志系统采用分级输出策略，可通过 `--verbose` 标志启用调试级别的日志输出。生产环境下建议使用默认的 info 级别，仅在排查问题时启用详细日志。\n\n资料来源：[cmd/cmd.go:300-400]()\n\n### 用户友好的错误提示\n\n系统尽可能将内部错误转换为用户可理解的操作建议。例如，当模型加载失败时，不仅报告失败原因，还会建议可能的解决方案如重新下载模型、检查磁盘空间等。\n\n```go\n// 错误提示示例结构\ntype UserError struct {\n Message string // 面向用户的错误描述\n Detail string // 技术细节（可选）\n Suggestion []string // 修复建议列表\n DocsURL string // 相关文档链接\n}\n```\n\n资料来源：[cmd/interactive.go:300-380]()\n\n## 扩展性与插件\n\n### 命令扩展机制\n\nOllama 预留了命令扩展接口，允许通过外部插件注册新的子命令。插件通过实现特定接口将自己注册到命令树中，无需修改核心代码即可扩展功能。\n\n扩展命令的注册流程：\n\n1. 插件加载时调用注册函数\n2. 提供命令名称、处理器函数、参数模式\n3. 系统将命令添加到根命令的子命令列表\n4. 用户即可通过标准方式调用扩展命令\n\n### 配置扩展点\n\n配置系统支持自定义配置项和配置验证器，插件可以声明自己的配置项并在配置文件中使用。配置变更支持热重载，无需重启服务即可应用新配置。\n\n## 总结\n\nOllama 的命令行系统提供了完善的模型管理和推理交互能力，通过模块化设计实现了良好的可维护性和扩展性。系统采用分层架构，将命令行解析、配置管理、用户界面、模型服务等职责分离，便于独立演进和测试。\n\n核心设计特点包括：基于 cobra 框架的命令层次结构、分层配置系统带优先级覆盖、流式响应渲染的 TUI 交互、完整的模型生命周期管理命令集、以及友好的错误提示和日志系统。这些设计使得 Ollama 既适合作为命令行工具直接使用，也为作为后台服务提供了坚实基础。\n\n---\n\n\n\n## 桌面应用程序\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [命令行系统](#page-cli-system)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [app/server/server.go](https://github.com/ollama/ollama/blob/main/app/server/server.go)\n- [app/ui/app.go](https://github.com/ollama/ollama/blob/main/app/ui/app.go)\n- [app/ui/ui.go](https://github.com/ollama/ollama/blob/main/app/ui/ui.go)\n- [app/webview/webview.go](https://github.com/ollama/ollama/blob/main/app/webview/webview.go)\n- [app/updater/updater.go](https://github.com/ollama/ollama/blob/main/app/updater/updater.go)\n- [app/tools/tools.go](https://github.com/ollama/ollama/blob/main/app/tools/tools.go)\n- [app/store/store.go](https://github.com/ollama/ollama/blob/main/app/store/store.go)\n \n\n# 桌面应用程序\n\nOllama 桌面应用程序为 macOS 和 Windows 用户提供本地化的图形界面，使其能够在本地运行和管理大型语言模型。该应用程序集成了 WebView 渲染引擎、后端服务、模型管理功能以及自动更新机制，为用户提供了开箱即用的 AI 推理体验。\n\n## 架构概述\n\nOllama 桌面应用采用分层架构设计，将用户界面、后端服务和系统级功能解耦。这种设计使得各组件可以独立开发和测试，同时保持整体系统的协调一致。\n\n```mermaid\ngraph TD\n A[用户界面层
React + TypeScript] --> B[WebView 渲染层
系统原生浏览器引擎]\n B --> C[Go 后端服务层
app/server]\n C --> D[核心推理引擎
Ollama Core]\n C --> E[模型存储
app/store]\n C --> F[自动更新
app/updater]\n C --> G[系统工具
app/tools]\n \n H[macOS/Windows
原生操作系统] --> I[系统集成
文件选择/网络配置]\n```\n\n| 层次 | 技术栈 | 职责 |\n|------|--------|------|\n| 用户界面层 | React + TypeScript + TailwindCSS | 交互式 UI 组件、消息展示、设置面板 |\n| WebView 渲染层 | 系统原生 WebView | HTML/CSS/JS 渲染、JavaScript 桥接 |\n| 后端服务层 | Go | HTTP 服务器、API 处理、系统集成 |\n| 核心推理层 | Ollama Core | 模型加载、推理执行、张量计算 |\n\n## 核心组件\n\n### 服务器模块\n\n`app/server/server.go` 实现了嵌入式 HTTP 服务器，负责处理前端请求和系统级操作。该模块提供了模型管理、对话处理、嵌入生成等核心功能的 API 端点。\n\n服务器模块的关键职责包括：\n\n- 接收并处理来自 WebView 的 HTTP 请求\n- 管理模型的生命周期（加载、卸载、切换）\n- 处理聊天完成和文本生成请求\n- 提供嵌入向量计算接口\n- 管理模型的下载进度跟踪\n\n### 用户界面模块\n\n`app/ui/app.go` 和 `app/ui/ui.go` 共同构成了应用程序的前端核心。界面采用 React 组件化架构，主要包含以下功能模块：\n\n```mermaid\ngraph LR\n A[消息组件
Message.tsx] --> B[对话界面]\n C[模型选择器
ModelPicker.tsx] --> B\n D[设置面板
Settings.tsx] --> B\n E[下载进度
Downloading.tsx] --> B\n F[错误提示
ErrorMessage.tsx] --> B\n G[思考层级
ThinkButton.tsx] --> B\n```\n\n| 组件 | 文件位置 | 功能描述 |\n|------|----------|----------|\n| Message | app/ui/app/src/components/Message.tsx | 渲染对话消息，支持工具调用结果展示 |\n| ModelPicker | app/ui/app/src/components/ModelPicker.tsx | 模型列表展示与选择 |\n| Settings | app/ui/app/src/components/Settings.tsx | 应用配置、网络设置、用户账户管理 |\n| Downloading | app/ui/app/src/components/Downloading.tsx | 模型下载进度条展示 |\n| ErrorMessage | app/ui/app/src/components/ErrorMessage.tsx | 错误信息渲染与链接支持 |\n| ThinkButton | app/ui/app/src/components/ThinkButton.tsx | 思考层级下拉选择器 |\n\n消息组件支持多种内容类型，包括普通文本、工具调用结果、Web 搜索摘要和 Web 抓取结果。当模型返回工具调用时，界面会展示工具名称、查询参数和原始 JSON 结果。资料来源：[app/ui/app/src/components/Message.tsx:Message.tsx]()\n\n### WebView 集成\n\n`app/webview/webview.go` 负责与操作系统原生 WebView 进行交互。该模块桥接了 Go 后端和前端 JavaScript 环境，使两者能够进行双向通信。\n\nWebView 的核心功能包括：\n\n- 初始化原生浏览器引擎\n- 注册 JavaScript 桥接接口\n- 处理文件选择对话框（模型目录选择）\n- 管理应用窗口生命周期\n\n资料来源：[app/webview/webview.go:webview.go]()\n\n### 自动更新模块\n\n`app/updater/updater.go` 实现了应用程序的自动更新机制。该模块会定期检查 Ollama 服务器以获取最新版本信息，并在后台下载更新包。\n\n自动更新流程采用静默下载方式，不阻塞用户当前操作。用户可以在下次启动时选择安装更新，或者通过设置面板手动触发更新检查。\n\n资料来源：[app/updater/updater.go:updater.go]()\n\n### 工具系统\n\n`app/tools/tools.go` 定义了应用程序可调用的系统工具集。这些工具扩展了 AI 模型的能力范围，使其能够执行超出纯文本生成的任务。\n\n工具系统支持的典型功能包括：\n\n- **Web 搜索工具**：允许模型发起网络搜索请求并获取结果\n- **Web 抓取工具**：获取指定 URL 的页面内容供模型分析\n- **系统集成工具**：访问本地文件系统、触发系统通知等\n\n资料来源：[app/tools/tools.go:tools.go]()\n\n### 数据存储模块\n\n`app/store/store.go` 负责管理应用程序的持久化数据。这包括用户设置、模型缓存信息、对话历史以及会话状态。\n\n存储模块采用本地文件系统存储策略，所有数据默认保存在用户主目录下的 Ollama 应用数据文件夹中。模型文件单独存储在可配置的模型目录中。\n\n资料来源：[app/store/store.go:store.go]()\n\n## 设置面板功能\n\n设置面板是用户配置应用程序的主要入口，提供以下配置选项：\n\n| 设置项 | 功能描述 | 可配置性 |\n|--------|----------|----------|\n| Expose | 是否将 Ollama 服务暴露到网络 | 用户开关 |\n| Models | 模型存储目录位置 | 仅查看，通过系统对话框选择 |\n| Cloud | 云端模型和 Web 搜索功能开关 | 受 OLLAMA_NO_CLOUD 环境变量约束 |\n| Auto Update | 自动更新检查开关 | 用户开关 |\n| 用户账户 | 登录、升级、管理账户信息 | 需联网 |\n\n资料来源：[app/ui/app/src/components/Settings.tsx:Settings.tsx]()\n\n## 开发环境搭建\n\n### 环境准备\n\n开发桌面应用程序前需要安装以下工具：\n\n1. Go 1.21 或更高版本\n2. Node.js 18+ 和 npm\n3. TypeScript 代码生成工具：`go install github.com/tkrajina/typescriptify-golang-structs/tscriptify@latest`\n\n### UI 开发模式\n\nUI 开发支持热重载功能，可大幅提升开发效率：\n\n```bash\n# 终端 1：启动 React 开发服务器\ncd ui/app\nnpm install\nnpm run dev\n\n# 终端 2：运行应用（带开发标志）\ngo generate ./...\nOLLAMA_DEBUG=1 go run ./cmd/app -dev\n```\n\n`-dev` 标志启用以下开发特性：\n\n- 从 Vite 开发服务器（http://localhost:5173）加载 UI\n- 固定 API 请求端口至 http://127.0.0.1:3001\n- 启用 CORS 跨域请求头\n- 支持前端热重载\n\n资料来源：[app/README.md:Development]()\n\n### 生产构建\n\n**Windows 构建流程：**\n\n```powershell\n# 安装本地依赖\n.\\scripts\\deps_local.ps1\n\n# 或使用发布依赖\n.\\scripts\\deps_release.ps1 0.6.8\n\n# 执行构建\n.\\scripts\\build_windows.ps1\n```\n\n**macOS 构建流程：**\n\n```bash\n# 设置 Xcode 开发工具路径\nexport DEVELOPER_DIR=/Applications/Xcode_14.1.0.app/Contents/Developer\n\n# 安装本地依赖\n./scripts/deps_local.sh\n\n# 或使用发布依赖\n./scripts/deps_release.sh 0.6.8\n\n# 执行构建\n./scripts/build_darwin.sh\n```\n\n资料来源：[app/README.md:Build]()\n\n## 下载与发布\n\n### 下载地址\n\n| 平台 | 下载链接 |\n|------|----------|\n| macOS | https://github.com/ollama/app/releases/download/latest/Ollama.dmg |\n| Windows | https://github.com/ollama/app/releases/download/latest/OllamaSetup.exe |\n\n资料来源：[app/README.md:Download]()\n\n## 工作流程\n\n### 模型下载流程\n\n当用户选择尚未安装的模型时，应用程序触发下载流程：\n\n```mermaid\nsequenceDiagram\n participant U as 用户界面\n participant S as 服务器模块\n participant M as 模型存储\n participant C as 核心引擎\n\n U->>S: 请求下载模型\n S->>M: 创建下载会话\n M-->>U: 返回下载进度\n loop 下载中\n M-->>U: 更新下载百分比\n end\n M->>C: 加载模型文件\n C-->>U: 模型就绪通知\n```\n\n下载进度组件会实时显示已下载字节数和总字节数，并计算完成百分比。进度条采用动态宽度设计，百分比精确到个位。资料来源：[app/ui/app/src/components/Downloading.tsx:Downloading.tsx]()\n\n### 思考层级配置\n\n应用程序支持配置模型的思考层级（Thinking Level），这是一个实验性功能，允许用户控制模型在生成响应前的推理深度：\n\n```mermaid\ngraph TD\n A[用户点击思考按钮] --> B{下拉菜单展开}\n B --> C[选择层级]\n C --> D[更新当前配置]\n D --> E[下拉菜单关闭]\n E --> F[下次请求携带新层级]\n```\n\n资料来源：[app/ui/app/src/components/ThinkButton.tsx:ThinkButton.tsx]()\n\n## 技术实现要点\n\n### 组件优化\n\n部分高频渲染的组件使用了 `React.memo` 进行性能优化，通过自定义比较函数避免不必要的重渲染：\n\n```typescript\nexport default React.memo(Message, (prevProps, nextProps) => {\n return (\n prevProps.message === nextProps.message &&\n prevProps.onEditMessage === nextProps.onEditMessage &&\n prevProps.messageIndex === nextProps.messageIndex &&\n prevProps.isStreaming === nextProps.isStreaming &&\n prevProps.isFaded === nextProps.isFaded &&\n prevProps.browserToolResult === nextProps.browserToolResult\n );\n});\n```\n\n这种方法确保只有当消息内容或相关属性发生变化时才触发重新渲染，提升了对话界面的响应速度。\n\n### 深色模式支持\n\n所有 UI 组件均支持深色模式，通过 TailwindCSS 的 `dark:` 前缀实现主题适配。颜色变量如 `text-neutral-500` 和 `dark:text-neutral-400` 允许界面自动适应系统主题设置。\n\n### WebView 桥接协议\n\n前端与后端通过预定义的 JavaScript 接口进行通信。WebView 暴露的 `window.webview` 对象提供了以下能力：\n\n- `selectModelsDirectory()`：打开系统文件选择对话框\n- 其他系统级操作接口\n\n资料来源：[app/ui/app/src/components/Settings.tsx:Settings.tsx]()\n\n## 相关资源\n\nOllama 桌面应用程序是 Ollama 整体生态系统的前端入口，它与核心推理引擎、API 服务、命令行工具共同构成了完整的本地 AI 运行平台。通过提供图形化界面，应用程序降低了用户使用本地大语言模型的门槛，同时保持了高性能和隐私保护的特性。\n\n---\n\n\n\n## 高级功能\n\n### 相关页面\n\n相关主题：[API 参考](#page-api-reference), [LLM 后端系统](#page-llm-backend), [系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [docs/capabilities/streaming.mdx](https://github.com/ollama/ollama/blob/main/docs/capabilities/streaming.mdx)\n- [docs/capabilities/tool-calling.mdx](https://github.com/ollama/ollama/blob/main/docs/capabilities/tool-calling.mdx)\n- [docs/capabilities/vision.mdx](https://github.com/ollama/ollama/blob/main/docs/capabilities/vision.mdx)\n- [docs/capabilities/embeddings.mdx](https://github.com/ollama/ollama/blob/main/docs/capabilities/embeddings.mdx)\n- [docs/capabilities/thinking.mdx](https://github.com/ollama/ollama/blob/main/docs/capabilities/thinking.mdx)\n- [tools/tools.go](https://github.com/ollama/ollama/blob/main/tools/tools.go)\n- [x/tools/registry.go](https://github.com/ollama/ollama/blob/main/x/tools/registry.go)\n- [x/tools/websearch.go](https://github.com/ollama/ollama/blob/main/x/tools/websearch.go)\n- [model/renderers/json.go](https://github.com/ollama/ollama/blob/main/model/renderers/json.go)\n \n\n# 高级功能\n\nOllama 作为一款本地大语言模型运行框架，提供了丰富的**高级功能**，旨在增强 AI 模型的实用性、交互性和扩展性。这些功能包括流式输出、工具调用、多模态视觉支持、文本嵌入、思维推理模式等，使开发者能够在本地环境中构建复杂的 AI 应用，而无需依赖云端服务。\n\n本文档详细介绍 Ollama 的各项高级功能，包括其工作原理、API 使用方式、配置选项以及实际应用场景。\n\n---\n\n## 1. 流式输出（Streaming）\n\n### 1.1 功能概述\n\n流式输出是 Ollama 的一项核心功能，允许模型以流式方式逐步返回生成内容，而非等待完整响应生成完毕后再返回。这对于需要实时反馈的应用场景（如聊天机器人、实时写作辅助等）至关重要。\n\n流式输出采用 **Server-Sent Events (SSE)** 协议实现，客户端可以逐步接收模型生成的内容，并在每个 token 生成时立即展示，提升用户体验。\n\n### 1.2 工作原理\n\n```mermaid\ngraph TD\n A[客户端发送请求] --> B{启用 stream: true}\n B --> C[服务端开始生成]\n C --> D[生成单个 token]\n D --> E[通过 SSE 推送 token]\n E --> F[客户端接收并显示]\n F --> G{是否完成?}\n G -->|否| D\n G -->|是| H[发送完成事件]\n H --> I[关闭连接]\n```\n\n### 1.3 API 调用示例\n\n**生成端点流式请求：**\n\n```bash\ncurl -X POST http://localhost:11434/api/generate \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"model\": \"llama3\",\n \"prompt\": \"Write a story\",\n \"stream\": true\n }'\n```\n\n**流式响应格式：**\n\n```json\n{\"model\":\"llama3\",\"created_at\":\"2024-01-01T00:00:00Z\",\"response\":\"从前\",\"done\":false}\n{\"model\":\"llama3\",\"created_at\":\"2024-01-01T00:00:00Z\",\"response\":\"有一个\",\"done\":false}\n{\"model\":\"llama3\",\"created_at\":\"2024-01-01T00:00:00Z\",\"response\":\"小女孩\",\"done\":true}\n```\n\n资料来源：[docs/capabilities/streaming.mdx]()\n\n### 1.4 前端组件实现\n\nOllama 的前端界面通过 `StreamingMarkdownContent` 组件处理流式内容渲染，该组件接收 `content` 和 `isStreaming` 属性，实时更新显示区域。\n\n```tsx\n\n```\n\n资料来源：[app/ui/app/src/components/Message.tsx]()\n\n---\n\n## 2. 工具调用（Tool Calling）\n\n### 2.1 功能概述\n\n工具调用功能使大语言模型能够识别并调用外部工具来执行特定任务，突破了纯文本生成的能力限制。通过预定义工具注册机制，模型可以请求执行 Web 搜索、文件操作、计算任务等。\n\n### 2.2 架构设计\n\n```mermaid\ngraph TD\n A[用户请求] --> B[模型分析请求]\n B --> C{需要调用工具?}\n C -->|否| D[直接生成响应]\n C -->|是| E[返回工具调用请求]\n E --> F[工具注册表查找]\n F --> G[执行工具]\n G --> H[返回结果]\n H --> I[模型整合结果]\n I --> J[生成最终响应]\n```\n\n### 2.3 工具注册机制\n\nOllama 通过 `registry.go` 实现工具的注册与管理，支持多种类型的工具集成。\n\n```go\n// 工具注册表核心结构\ntype ToolRegistry struct {\n tools map[string]Tool\n}\n```\n\n资料来源：[x/tools/registry.go]()\n\n**注册流程：**\n\n1. 定义工具的结构和参数模式\n2. 将工具注册到全局注册表\n3. 模型通过 function calling 识别可调用工具\n4. 执行工具并返回结果\n\n### 2.4 Web 搜索工具\n\nWeb 搜索是 Ollama 集成的重要工具之一，允许模型实时获取互联网信息。\n\n```go\ntype WebSearchTool struct {\n Query string `json:\"query\"`\n}\n\ntype WebSearchResult struct {\n Query string `json:\"query\"`\n Results []Result `json:\"results\"`\n}\n```\n\n资料来源：[x/tools/websearch.go]()\n\n**搜索结果显示：**\n\n```tsx\n{toolName === \"web_search\" && (\n <>\n Search results for \n \n)}\n```\n\n资料来源：[app/ui/app/src/components/Message.tsx]()\n\n### 2.5 工具配置选项\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| Tools | boolean | false | 启用单轮工具模式 |\n| Agent | boolean | false | 启用代理模式 |\n| Tools Mode | enum | - | 工具使用级别控制 |\n\n资料来源：[app/ui/app/src/components/Settings.tsx]()\n\n### 2.6 工具调用界面\n\n前端界面提供直观的工具调用展示，包括工具名称、参数和执行结果：\n\n```tsx\n{message.tool_calls && message.tool_calls.length > 0 && (\n \n {message.tool_calls.map((toolCall: ToolCall, index: number) => (\n \n ))}\n
\n)}\n```\n\n资料来源：[app/ui/app/src/components/Message.tsx]()\n\n---\n\n## 3. 多模态视觉支持（Vision）\n\n### 3.1 功能概述\n\nOllama 支持多模态模型，能够处理图像输入并结合文本进行理解和分析。这使得用户可以上传图片并就图片内容进行问答、分析图表、描述场景等。\n\n### 3.2 支持的场景\n\n- **图像描述**：生成图片的文字描述\n- **视觉问答**：根据图片内容回答问题\n- **文档分析**：理解截图、图表、表格\n- **多图像处理**：同时分析多张图片\n\n### 3.3 API 调用示例\n\n**使用图片提示生成描述：**\n\n```bash\n./ollama-bench -model qwen3-vl -image photo.jpg -epochs 6 -max-tokens 100 -p \"Describe this image\"\n```\n\n资料来源：[cmd/bench/README.md]()\n\n**图像生成 API：**\n\n```bash\ncurl http://localhost:11434/v1/images/generations \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"model\": \"z-image\",\n \"prompt\": \"a white cat\",\n \"size\": \"1024x1024\"\n }'\n```\n\n资料来源：[x/imagegen/README.md]()\n\n### 3.4 图像生成参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| model | string | required | 模型名称 |\n| prompt | string | required | 生成提示词 |\n| size | string | 1024x1024 | 图像尺寸 |\n| steps | int | 9 | 去噪步数 |\n| seed | int | 42 | 随机种子 |\n\n资料来源：[x/imagegen/README.md]()\n\n---\n\n## 4. 文本嵌入（Embeddings）\n\n### 4.1 功能概述\n\n嵌入功能将文本转换为高维向量表示，使得语义相似的文本在向量空间中距离更近。这对于语义搜索、文本聚类、相似度匹配等应用至关重要。\n\n### 4.2 嵌入端点\n\n```bash\ncurl -X POST -H \"Content-Type: application/json\" \\\n -d '{\"prompt\": \"turn me into an embedding\"}' \\\n http://localhost:8080/embedding\n```\n\n资料来源：[runner/README.md]()\n\n### 4.3 应用场景\n\n- **语义搜索**：基于内容相似度而非关键词匹配\n- **文档聚类**：将相关文档分组\n- **推荐系统**：计算内容相似度\n- **文本分类**：作为下游分类器的特征输入\n\n资料来源：[docs/capabilities/embeddings.mdx]()\n\n---\n\n## 5. 思维推理模式（Thinking）\n\n### 5.1 功能概述\n\n思维推理模式允许模型在生成最终答案之前展示其推理过程，特别适合复杂问题解决和需要多步推理的任务。\n\n### 5.2 思维层级配置\n\nOllama 提供了多级思维模式配置，用户可以根据任务复杂度选择合适的推理深度：\n\n| 思维层级 | 描述 | 适用场景 |\n|----------|------|----------|\n| none | 无思维推理 | 简单问答 |\n| low | 基础推理 | 简单推理任务 |\n| medium | 中级推理 | 常规复杂问题 |\n| high | 深度推理 | 复杂多步推理 |\n\n资料来源：[app/ui/app/src/components/ThinkButton.tsx]()\n\n### 5.3 前端实现\n\n```tsx\n{Object.entries(THINKING_LEVELS).map(([, level]) => (\n {\n onLevelChange?.(level);\n setIsDropdownOpen(false);\n }}\n >\n {THINKING_LEVEL_LABELS[level]}\n \n))}\n```\n\n资料来源：[app/ui/app/src/components/ThinkButton.tsx]()\n\n### 5.4 工作流程\n\n```mermaid\ngraph TD\n A[用户输入] --> B[选择思维层级]\n B --> C[模型进行内部推理]\n C --> D{是否显示推理过程?}\n D -->|是| E[输出推理步骤]\n D -->|否| F[直接输出结论]\n E --> F\n F --> G[最终响应]\n```\n\n---\n\n## 6. JSON 渲染器\n\n### 6.1 功能概述\n\nOllama 包含专门的 JSON 渲染器组件，用于格式化和展示结构化 JSON 数据，确保模型输出的 JSON 内容正确显示。\n\n### 6.2 核心结构\n\n```go\ntype JSONRenderer struct {\n // 渲染配置\n indent int\n sortKeys bool\n}\n```\n\n资料来源：[model/renderers/json.go]()\n\n### 6.3 渲染特性\n\n- **语法高亮**：区分键、值、类型\n- **格式化输出**：美化 JSON 缩进\n- **错误检测**：识别无效 JSON\n\n---\n\n## 7. 模型下载与进度跟踪\n\n### 7.1 下载管理\n\nOllama 提供可视化的模型下载进度跟踪功能，用户可以实时查看下载状态。\n\n### 7.2 下载界面组件\n\n```tsx\n\n```\n\n资料来源：[app/ui/app/src/components/Downloading.tsx]()\n\n### 7.3 进度显示格式\n\n```\n${formatBytes(completed, unit)} / ${formatBytes(total, unit)} (${Math.floor(percentage)}%)\n```\n\n资料来源：[app/ui/app/src/components/Downloading.tsx]()\n\n---\n\n## 8. 云端与本地配置\n\n### 8.1 配置项\n\nOllama 支持灵活的云端与本地模型切换配置：\n\n| 配置项 | 说明 |\n|--------|------|\n| Expose | 允许网络暴露 |\n| Models | 模型存储位置 |\n| Cloud | 启用云端模型 |\n| Auto Update | 自动更新功能 |\n\n资料来源：[app/ui/app/src/components/Settings.tsx]()\n\n### 8.2 环境变量控制\n\n某些配置可被环境变量强制覆盖：\n\n```tsx\n{cloudOverriddenByEnv\n ? \"The OLLAMA_NO_CLOUD environment variable is currently forcing cloud off.\"\n : \"Enable cloud models and web search.\"}\n```\n\n资料来源：[app/ui/app/src/components/Settings.tsx]()\n\n---\n\n## 9. 总结\n\nOllama 的高级功能通过模块化设计，为本地 AI 应用开发提供了强大的能力支撑：\n\n| 功能模块 | 主要作用 | 技术实现 |\n|----------|----------|----------|\n| 流式输出 | 实时响应反馈 | SSE 协议 |\n| 工具调用 | 扩展模型能力 | 函数注册表 |\n| 视觉支持 | 多模态理解 | 图像处理管线 |\n| 文本嵌入 | 语义表示 | 向量编码 |\n| 思维推理 | 推理过程展示 | 分层思维模式 |\n\n这些功能的组合使用，使开发者能够在本地环境中构建功能丰富、性能优秀的 AI 应用，同时保持对数据和模型的完全控制。\n\n---\n\n\n\n## 部署与构建\n\n### 相关页面\n\n相关主题：[项目概述](#page-overview), [系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [llama/README.md](https://github.com/ollama/ollama/blob/main/llama/README.md)\n- [app/README.md](https://github.com/ollama/ollama/blob/main/app/README.md)\n- [api/examples/README.md](https://github.com/ollama/ollama/blob/main/api/examples/README.md)\n- [cmd/bench/README.md](https://github.com/ollama/ollama/blob/main/cmd/bench/README.md)\n- [runner/README.md](https://github.com/ollama/ollama/blob/main/runner/README.md)\n- [x/imagegen/cmd/engine/README.md](https://github.com/ollama/ollama/blob/main/x/imagegen/cmd/engine/README.md)\n- [llama/llama.cpp/src/llama.go](https://github.com/ollama/ollama/blob/main/llama/llama.cpp/src/llama.go)\n- [ml/backend/ggml/ggml/src/ggml-backend-reg.cpp](https://github.com/ollama/ollama/blob/main/ml/backend/ggml/ggml/src/ggml-backend-reg.cpp)\n \n\n# 部署与构建\n\nOllama 是一个本地大语言模型运行框架，支持跨平台部署与构建。本文详细介绍 Ollama 的构建系统、支持的平台、环境配置以及各平台的构建流程。\n\n## 系统概述\n\nOllama 采用模块化架构设计，支持多种后端计算框架和硬件加速。构建系统基于 Makefile 和 Go 语言工具链，可生成适用于不同操作系统的可执行文件和容器镜像。\n\n```mermaid\ngraph TD\n A[Ollama 源码] --> B[构建系统]\n B --> C[Linux 构建]\n B --> D[macOS 构建]\n B --> E[Windows 构建]\n B --> F[Docker 构建]\n C --> G[二进制文件]\n D --> G\n E --> G\n F --> H[Docker 镜像]\n G --> I[本地部署]\n H --> J[容器化部署]\n```\n\n资料来源：[llama/README.md:1-20]()\n\n## 环境准备\n\n### Go 语言环境\n\nOllama 主要使用 Go 语言开发，构建系统要求安装 Go 1.22 或更高版本。Go 环境变量配置如下：\n\n| 环境变量 | 说明 | 示例值 |\n|---------|------|--------|\n| `GOPATH` | Go 工作目录 | `$HOME/go` |\n| `GOROOT` | Go 安装路径 | `/usr/local/go` |\n| `CGO_ENABLED` | C 互操作启用 | `1` |\n\n资料来源：[llama/llama.cpp/src/llama.go:1-10]()\n\n### 系统依赖\n\n不同平台需要安装相应的编译工具链和依赖库。\n\n**Linux 平台依赖：**\n\n- GCC/G++ 编译器（支持 C++17）\n- CMake（用于 ggml 后端构建）\n- CUDA Toolkit（GPU 加速可选）\n- Vulkan SDK（GPU 加速可选）\n\n**macOS 平台依赖：**\n\n- Xcode 14.1 或更高版本\n- Xcode 命令行工具\n- Metal 框架（GPU 加速）\n\n**Windows 平台依赖：**\n\n- Visual Studio 2022 或更高版本\n- MinGW-w64（部分构建场景）\n- Windows SDK\n\n资料来源：[app/README.md:1-50]()\n\n## 多平台构建流程\n\n### Linux 构建\n\nLinux 平台是 Ollama 最主要的部署目标，支持完整的 GPU 加速功能。\n\n```bash\n# 安装系统依赖\nsudo apt-get update\nsudo apt-get install -y build-essential cmake\n\n# 克隆源码\ngit clone https://github.com/ollama/ollama.git\ncd ollama\n\n# 构建可执行文件\ngo build -o ollama .\n```\n\n资料来源：[llama/README.md:10-25]()\n\n### macOS 构建\n\nmacOS 平台支持 Metal GPU 加速，通过 Xcode 工具链进行构建。\n\n```bash\n# 设置 Xcode 开发环境\nexport DEVELOPER_DIR=/Applications/Xcode_14.1.0.app/Contents/Developer\nexport SDKROOT=/Applications/Xcode_14.1.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk\n\n# 设置编译优化参数\nexport CGO_CFLAGS=\"-O3 -mmacosx-version-min=12.0\"\nexport CGO_CXXFLAGS=\"-O3 -mmacosx-version-min=12.0\"\nexport CGO_LDFLAGS=\"-mmacosx-version-min=12.0\"\n\n# 安装本地依赖\n./scripts/deps_local.sh\n\n# 执行构建\n./scripts/build_darwin.sh\n```\n\n资料来源：[app/README.md:30-55]()\n\n### Windows 构建\n\nWindows 平台通过 PowerShell 脚本自动化构建流程。\n\n```powershell\n# 安装本地依赖\n.\\scripts\\deps_local.ps1\n\n# 或使用发布版本依赖\n.\\scripts\\deps_release.ps1 0.6.8\n\n# 执行构建\n.\\scripts\\build_windows.ps1\n```\n\n资料来源：[app/README.md:20-30]()\n\n## GPU 后端支持\n\nOllama 通过 ggml（GGML 库）支持多种 GPU 加速后端。\n\n```mermaid\ngraph LR\n A[Ollama Core] --> B[ggml-backend-reg]\n B --> C[CPU Backend]\n B --> D[CUDA Backend]\n B --> E[Metal Backend]\n B --> F[Vulkan Backend]\n B --> G[SYCL Backend]\n B --> H[WebGPU Backend]\n \n C --> I[ARM/x86]\n D --> J[NVIDIA GPU]\n E --> K[Apple Silicon]\n F --> L[AMD/Intel GPU]\n```\n\n资料来源：[ml/backend/ggml/ggml/src/ggml-backend-reg.cpp:1-60]()\n\n### 后端编译条件\n\n| 后端 | 编译宏 | 依赖 |\n|------|--------|------|\n| CPU | `GGML_USE_CPU` | 无 |\n| CUDA | `GGML_USE_CUDA` | CUDA Toolkit |\n| Metal | `GGML_USE_METAL` | Xcode/Metal SDK |\n| Vulkan | `GGML_USE_VULKAN` | Vulkan SDK |\n| SYCL | `GGML_USE_SYCL` | oneAPI |\n| WebGPU | `GGML_USE_WEBGPU` | Dawn |\n| CANN | `GGML_USE_CANN` | 华为昇腾 |\n| BLAS | `GGML_USE_BLAS` | OpenBLAS |\n\n资料来源：[ml/backend/ggml/ggml/src/ggml-backend-reg.cpp:25-55]()\n\n### Vulkan 后端构建\n\nVulkan 后端需要使用 GLSL 编译器将着色器代码编译为 SPIR-V 格式。\n\n```bash\n# 编译 Vulkan 着色器生成器\ng++ -std=c++17 -o vulkan-shaders-gen vulkan-shaders-gen.cpp\n\n# 生成着色器头文件\n./vulkan-shaders-gen --input ./shaders --output /tmp/vulkan_shaders.hpp\n```\n\n资料来源：[ml/backend/ggml/ggml/src/ggml-vulkan/vulkan-shaders/vulkan-shaders-gen.cpp:1-50]()\n\n## Docker 部署\n\nOllama 提供官方 Docker 镜像，支持容器化部署。\n\n### Docker 构建\n\n```bash\n# 构建 Docker 镜像\ndocker build -t ollama/ollama:latest .\n\n# 运行容器\ndocker run -d \\\n --gpus all \\\n -v ollama:/root/.ollama \\\n -p 11434:11434 \\\n ollama/ollama:latest\n```\n\n资料来源：[app/README.md:5-15]()\n\n### Docker 构建脚本\n\n构建系统提供自动化 Docker 构建脚本：\n\n```bash\n# 执行 Docker 构建\n./scripts/build_docker.sh\n\n# 指定镜像标签\ndocker build -t ollama/ollama:custom-tag .\n```\n\n## 轻量级 Runner\n\nOllama 提供一个精简的 `runner` 模块，用于在资源受限环境中加载模型并提供 HTTP 推理服务。\n\n```bash\n# 构建 runner\ngo build -o runner ./x/imagegen/cmd/engine\n\n# 启动 runner\n./runner -model \n```\n\n### Runner API 接口\n\n| 端点 | 方法 | 说明 |\n|------|------|------|\n| `/completion` | POST | 文本补全 |\n| `/embedding` | POST | 向量嵌入生成 |\n\n资料来源：[runner/README.md:1-25]()\n\n**完成请求示例：**\n\n```bash\ncurl -X POST \\\n -H \"Content-Type: application/json\" \\\n -d '{\"prompt\": \"hi\"}' \\\n http://localhost:8080/completion\n```\n\n**嵌入请求示例：**\n\n```bash\ncurl -X POST \\\n -H \"Content-Type: application/json\" \\\n -d '{\"prompt\": \"turn me into an embedding\"}' \\\n http://localhost:8080/embedding\n```\n\n## API 示例\n\nOllama 提供 Go 语言 API 示例，帮助开发者集成推理功能。\n\n### 可用示例\n\n| 示例 | 文件路径 | 说明 |\n|------|----------|------|\n| 聊天 | `api/examples/chat/main.go` | 与模型对话 |\n| 生成 | `api/examples/generate/main.go` | 文本生成 |\n| 流式生成 | `api/examples/generate-streaming/main.go` | 流式文本生成 |\n| 拉取进度 | `api/examples/pull-progress/main.go` | 模型拉取进度 |\n\n资料来源：[api/examples/README.md:1-20]()\n\n### 运行示例\n\n```bash\n# 运行聊天示例\ngo run api/examples/chat/main.go\n\n# 运行生成示例\ngo run api/examples/generate/main.go\n\n# 运行流式生成示例\ngo run api/examples/generate-streaming/main.go\n```\n\n## 交叉编译支持\n\nOllama 支持交叉编译，可在单一平台构建其他平台的二进制文件。\n\n### 编译目标配置\n\n| 目标平台 | GOOS | GOARCH | 额外配置 |\n|----------|------|--------|----------|\n| Linux AMD64 | `linux` | `amd64` | 无 |\n| Linux ARM64 | `linux` | `arm64` | 无 |\n| macOS AMD64 | `darwin` | `amd64` | Xcode SDK |\n| macOS ARM64 | `darwin` | `arm64` | Xcode SDK |\n| Windows AMD64 | `windows` | `amd64` | MinGW |\n\n### 交叉编译示例\n\n```bash\n# 编译 Linux ARM64 版本\nGOOS=linux GOARCH=arm64 CGO_ENABLED=1 go build -o ollama-linux-arm64 .\n\n# 编译 Windows 版本\nGOOS=windows GOARCH=amd64 CGO_ENABLED=1 go build -o ollama.exe .\n```\n\n## 性能基准测试\n\nOllama 提供 `ollama-bench` 工具用于性能评估。\n\n```bash\n# 基本用法\n./ollama-bench -model llama3 -epochs 6\n\n# 指定提示词\n./ollama-bench -model gemma3 -epochs 6 -p \"Write me a short story\"\n\n# 带图像提示词\n./ollama-bench -model qwen3-vl -image photo.jpg -epochs 6 -max-tokens 100 -p \"Describe this image\"\n\n# 控制提示词长度\n./ollama-bench -model gemma3 -epochs 6 -prompt-tokens 512\n\n# 高级配置\n./ollama-bench -model llama3 -epochs 10 -temperature 0.7 -max-tokens 500 -seed 42 -format csv -output results.csv\n```\n\n### 基准测试参数\n\n| 参数 | 说明 | 默认值 |\n|------|------|--------|\n| `-model` | 模型名称（必填） | - |\n| `-epochs` | 迭代次数 | 6 |\n| `-max-tokens` | 最大生成 token 数 | 200 |\n| `-temperature` | 采样温度 | 0.0 |\n| `-seed` | 随机种子 | 0（随机） |\n| `-timeout` | 超时时间（秒） | 300 |\n| `-format` | 输出格式 | - |\n\n资料来源：[cmd/bench/README.md:1-40]()\n\n## 图像生成引擎\n\nOllama 的图像生成功能基于独立的 MLX 引擎。\n\n### 构建图像生成引擎\n\n```bash\ngo build -o engine ./x/imagegen/cmd/engine\n```\n\n### 使用图像生成\n\n```bash\n./engine -zimage -model /path/to/z-image -prompt \"a cat\" -output cat.png\n```\n\n### 可选参数\n\n| 参数 | 说明 | 默认值 |\n|------|------|--------|\n| `-width` | 图像宽度 | 1024 |\n| `-height` | 图像高度 | 1024 |\n| `-steps` | 去噪步数 | 9 |\n| `-seed` | 随机种子 | 42 |\n\n资料来源：[x/imagegen/cmd/engine/README.md:1-30]()\n\n## 桌面应用构建\n\nOllama 提供跨平台桌面应用，支持 macOS 和 Windows。\n\n### 桌面应用依赖\n\n| 平台 | 构建脚本 | 说明 |\n|------|----------|------|\n| macOS | `scripts/build_darwin.sh` | 使用 Xcode 构建 |\n| Windows | `scripts/build_windows.ps1` | 使用 PowerShell 构建 |\n\n### 开发模式启动\n\n```bash\n# 生成代码并启动开发服务器\ngo generate ./...\ngo run ./cmd/app\n\n# 启用调试模式\nOLLAMA_DEBUG=1 go run ./cmd/app -dev\n```\n\n### UI 开发模式\n\n1. 启动 React 开发服务器：\n ```bash\n cd ui/app\n npm install\n npm run dev\n ```\n\n2. 启动 Ollama 应用（带 `-dev` 参数）：\n ```bash\n go generate ./...\n OLLAMA_DEBUG=1 go run ./cmd/app -dev\n ```\n\n开发模式下 `-dev` 参数启用以下功能：\n\n- 从 Vite 开发服务器加载 UI（http://localhost:5173）\n- 固定 API 请求端口（http://127.0.0.1:3001）\n- 启用 CORS 跨域请求支持\n- 支持热模块替换\n\n资料来源：[app/README.md:55-90]()\n\n## 版本与发布\n\nOllama 使用语义化版本号管理发布版本。发布构建需要：\n\n1. 更新版本号文件\n2. 生成变更日志\n3. 执行完整测试套件\n4. 构建所有平台版本\n5. 签名并发布工件\n\n## 常见问题排查\n\n| 问题 | 可能原因 | 解决方案 |\n|------|----------|----------|\n| CGO 编译失败 | 缺少 C/C++ 编译器 | 安装 GCC 或 Clang |\n| GPU 不可用 | 驱动未正确安装 | 更新 GPU 驱动程序 |\n| 内存不足 | 模型过大 | 选择更小的模型 |\n| 端口占用 | 11434 端口被占用 | 更换端口或释放端口 |\n\n## 总结\n\nOllama 的构建系统设计灵活，支持从源码编译到 Docker 容器化部署的完整流程。开发者可根据目标平台和硬件环境选择合适的构建方式，利用多后端支持实现最优的推理性能。\n\n---\n\n\n\n## 模型转换系统\n\n### 相关页面\n\n相关主题：[模型管理](#page-model-management), [LLM 后端系统](#page-llm-backend), [部署与构建](#page-deployment)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [convert/convert.go](https://github.com/ollama/ollama/blob/main/convert/convert.go)\n- [convert/convert_llama.go](https://github.com/ollama/ollama/blob/main/convert/convert_llama.go)\n- [convert/convert_qwen3.go](https://github.com/ollama/ollama/blob/main/convert/convert_qwen3.go)\n- [convert/convert_gemma3.go](https://github.com/ollama/ollama/blob/main/convert/convert_gemma3.go)\n- [convert/reader_safetensors.go](https://github.com/ollama/ollama/blob/main/convert/reader_safetensors.go)\n- [convert/reader_torch.go](https://github.com/ollama/ollama/blob/main/convert/reader_torch.go)\n- [tokenizer/tokenizer.go](https://github.com/ollama/ollama/blob/main/tokenizer/tokenizer.go)\n- [parser/parser.go](https://github.com/ollama/ollama/blob/main/parser/parser.go)\n \n\n# 模型转换系统\n\n## 概述\n\nOllama 的模型转换系统（Model Conversion System）是核心组件之一，负责将来自不同训练框架（如 PyTorch）和不同模型格式（如 SafeTensors）的预训练模型转换为 Ollama 专有的运行时格式。该系统支持多种模型架构，包括 Llama、Qwen3、Gemma3 等主流开源大语言模型。\n\n模型转换系统的主要职责包括：\n\n- 解析源模型文件的权重和配置\n- 处理不同量化级别的模型参数\n- 生成 Ollama 运行时所需的 GGUF/GGML 格式文件\n- 验证转换后模型的完整性和正确性\n\n## 系统架构\n\n### 整体架构图\n\n```mermaid\ngraph TD\n A[输入模型文件] --> B[解析层 Parser]\n B --> C[读取器 Readers]\n C --> D{模型类型检测}\n D -->|PyTorch| E[reader_torch.go]\n D -->|SafeTensors| F[reader_safetensors.go]\n E --> G[转换层 Converter]\n F --> G\n G --> H[模型特定转换器]\n H --> I[convert_llama.go]\n H --> J[convert_qwen3.go]\n H --> K[convert_gemma3.go]\n I --> L[分词器 Tokenizer]\n J --> L\n K --> L\n L --> M[GGUF/GGML 输出]\n```\n\n### 核心组件说明\n\n| 组件 | 文件路径 | 职责描述 |\n|------|----------|----------|\n| 解析器 | `parser/parser.go` | 解析输入配置和模型元数据 |\n| SafeTensors 读取器 | `convert/reader_safetensors.go` | 读取 SafeTensors 格式的模型权重 |\n| PyTorch 读取器 | `convert/reader_torch.go` | 读取 PyTorch 格式的模型权重 |\n| Llama 转换器 | `convert/convert_llama.go` | Llama 系列模型的专用转换逻辑 |\n| Qwen3 转换器 | `convert/convert_qwen3.go` | Qwen3 系列模型的专用转换逻辑 |\n| Gemma3 转换器 | `convert/convert_gemma3.go` | Gemma3 系列模型的专用转换逻辑 |\n| 分词器 | `tokenizer/tokenizer.go` | 处理模型关联的分词器资源 |\n\n## 转换流程\n\n### 标准转换工作流\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Parser as 解析器\n participant Reader as 读取器\n participant Converter as 转换器\n participant Tokenizer as 分词器\n participant Output as 输出文件\n\n User->>Parser: 提交原始模型路径\n Parser->>Parser: 读取模型配置和架构\n Parser->>Reader: 加载权重数据\n Reader-->>Parser: 返回权重映射\n Parser->>Converter: 调用架构专用转换\n Converter->>Converter: 应用量化参数\n Converter->>Tokenizer: 获取分词器配置\n Tokenizer-->>Converter: 返回分词器数据\n Converter->>Output: 生成 GGUF 文件\n Output-->>User: 转换完成\n```\n\n### 转换步骤详解\n\n#### 第一阶段：模型解析\n\n解析器负责读取输入模型的配置信息和元数据。这一阶段会：\n\n1. 检测模型文件格式（PyTorch checkpoint 或 SafeTensors）\n2. 读取模型架构配置（层数、隐藏维度、注意力头数等）\n3. 识别模型家族（Llama、Qwen、Gemma 等）\n\n资料来源：[parser/parser.go]()\n\n#### 第二阶段：权重读取\n\n根据检测到的模型格式，选择对应的读取器：\n\n- **SafeTensors 读取器**：高效读取 SafeTensors 格式文件，支持内存映射\n- **PyTorch 读取器**：处理传统的 PyTorch 模型检查点文件\n\n资料来源：[convert/reader_safetensors.go]()[convert/reader_torch.go]()\n\n#### 第三阶段：模型转换\n\n针对不同模型架构，应用特定的转换逻辑：\n\n| 模型系列 | 转换器文件 | 特殊处理 |\n|----------|------------|----------|\n| Llama | `convert_llama.go` | 标准 Transformer 结构 |\n| Qwen3 | `convert_qwen3.go` | Qwen 特有的 RoPE 和注意力机制 |\n| Gemma3 | `convert_gemma3.go` | Gemma 特有的规范化层 |\n\n资料来源：[convert/convert_llama.go]()[convert/convert_qwen3.go]()[convert/convert_gemma3.go]()\n\n#### 第四阶段：分词器处理\n\n转换过程的最后阶段涉及分词器资源的整合，确保转换后的模型能够正确地进行文本编码和解码。\n\n资料来源：[tokenizer/tokenizer.go]()\n\n## 核心转换接口\n\n### 主转换函数\n\n```go\n// convert/convert.go\nfunc Convert(modelPath string, outputPath string, options *ConvertOptions) error\n```\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| modelPath | string | 源模型文件的路径 |\n| outputPath | string | 输出 GGUF 文件的目标路径 |\n| options | ConvertOptions | 转换选项（量化级别、参数精度等） |\n\n### 转换选项结构\n\n| 选项 | 默认值 | 说明 |\n|------|--------|------|\n| Quantization | Q4_0 | 量化级别（Q4_0、Q5_1、Q8_0 等） |\n| BatchSize | 512 | 推理批次大小 |\n| Threads | 自动 | CPU 线程数 |\n\n## 量化支持\n\n模型转换系统支持多种量化级别，以平衡模型大小和推理质量：\n\n| 量化类型 | 压缩率 | 质量影响 | 适用场景 |\n|----------|--------|----------|----------|\n| F16 | 100% | 无 | 高精度需求 |\n| Q5_1 | ~60% | 极小 | 资源受限环境 |\n| Q4_0 | ~50% | 较小 | 推荐默认选项 |\n| Q3_K | ~35% | 中等 | 极致压缩 |\n| Q2_K | ~25% | 较明显 | 最低资源 |\n\n资料来源：[convert/convert.go]()\n\n## 输出格式\n\n转换系统输出的 GGUF（GGML Unified Format）文件包含以下组件：\n\n```\nGGUF 文件结构\n├── Header（文件头）\n├── Metadata KV（元数据键值对）\n├── Tensor Info（张量信息）\n├── Tensor Data（张量数据）\n└── Padding（对齐填充）\n```\n\nGGUF 格式设计用于支持：\n\n- 内存映射加载\n- 元数据内嵌\n- 张量信息自描述\n- 跨平台兼容性\n\n## 相关文件参考\n\n| 文件 | 功能 |\n|------|------|\n| `llama/llama.cpp/src/gguf.cpp` | GGUF 格式底层实现 |\n| `llama/llama.cpp/src/unicode.cpp` | Unicode 处理支持 |\n| `ml/backend/ggml/ggml/src/ggml-cpu/quants.c` | CPU 量化实现 |\n\n资料来源：[llama/llama.cpp/src/gguf.cpp]()[llama/llama.cpp/src/unicode.cpp]()[ml/backend/ggml/ggml/src/ggml-cpu/quants.c]()\n\n## 使用示例\n\n### 命令行转换\n\n```bash\nollama convert --input /path/to/model --output model.gguf --quantize q4_0\n```\n\n### API 调用\n\n```go\nerr := convert.Convert(\n \"/models/llama3-8b\",\n \"/output/llama3-8b-q4.gguf\",\n &convert.ConvertOptions{\n Quantization: \"q4_0\",\n },\n)\n```\n\n## 注意事项\n\n1. **模型兼容性**：仅支持已实现转换器的模型架构\n2. **资源需求**：大模型转换需要足够的磁盘空间和内存\n3. **量化损失**：量化会引入精度损失，请根据需求选择量化级别\n4. **版本兼容**：转换后的 GGUF 文件需与 Ollama 版本兼容\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：ollama/ollama\n\n摘要：发现 23 个潜在踩坑项，其中 7 个为 high/blocking；最高优先级：安装坑 - 来源证据：0.23.1 : mlx runner failed。\n\n## 1. 安装坑 · 来源证据：0.23.1 : mlx runner failed\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：0.23.1 : mlx runner failed\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_06acaa8b4f9d4923977e39f0de3349df | https://github.com/ollama/ollama/issues/16007 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：Ollama Cloud: Frequent 503 errors making cloud models unreliable\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Ollama Cloud: Frequent 503 errors making cloud models unreliable\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_568af28cdfb04c3eaf66b648ffff865f | https://github.com/ollama/ollama/issues/15419 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：Support `ppc64le` architecture\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Support `ppc64le` architecture\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_82122f2d4dfd4202a09101c78837de0e | https://github.com/ollama/ollama/issues/796 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 4. 配置坑 · 来源证据：Not compatible with Glaude code Cli when using local model\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Not compatible with Glaude code Cli when using local model\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_18239d63b211480fa37ec3c6dfb773ee | https://github.com/ollama/ollama/issues/16094 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 5. 配置坑 · 来源证据：Registering fine-tuned models\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Registering fine-tuned models\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3417faf9df79457e841e34e3df365558 | https://github.com/ollama/ollama/issues/16095 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 6. 运行坑 · 来源证据：[Bug] 0.23.2 Image generation succeeds but no image saved to disk or returned via API\"\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：[Bug] 0.23.2 Image generation succeeds but no image saved to disk or returned via API\"\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_294d6c7549c44529a06895132ef49777 | https://github.com/ollama/ollama/issues/16072 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 7. 安全/权限坑 · 来源证据：Feature Request: Expose account quota/usage details via Ollama Cloud API (headers and/or response body)\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Feature Request: Expose account quota/usage details via Ollama Cloud API (headers and/or response body)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_56cc99bad67b43a6b9a0ccff38aef5e2 | https://github.com/ollama/ollama/issues/15663 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 8. 安装坑 · 来源证据：VRAM Detection Issue on Radeon 780M (gfx1035) - Kernel Page Fault\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：VRAM Detection Issue on Radeon 780M (gfx1035) - Kernel Page Fault\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_26de977c783d40308b5962cd61c7a1df | https://github.com/ollama/ollama/issues/16040 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。\n\n## 9. 配置坑 · 来源证据：mistral-medium-3.5 - Produces nonsense outputs\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：mistral-medium-3.5 - Produces nonsense outputs\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5516e9097bb34de3a29210537c23e393 | https://github.com/ollama/ollama/issues/15975 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。\n\n## 10. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:658928958 | https://github.com/ollama/ollama | README/documentation is current enough for a first validation pass.\n\n## 11. 运行坑 · 来源证据：SIGSEGV in MLX VAE decode after diffusion steps complete on M4 Pro (macOS 26.4.1, Ollama 0.23.2)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：SIGSEGV in MLX VAE decode after diffusion steps complete on M4 Pro (macOS 26.4.1, Ollama 0.23.2)\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b8c07744d01f41b392c0ce87ebda37b4 | https://github.com/ollama/ollama/issues/16093 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 12. 运行坑 · 来源证据：ollama run 交互模式无法拖拽/粘贴图片\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：ollama run 交互模式无法拖拽/粘贴图片\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fc1e1d2e0e8e441d88c14ea3f7e6316e | https://github.com/ollama/ollama/issues/16091 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 13. 运行坑 · 来源证据：v0.23.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.23.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3c18127a820d4532885af7c07b2cf3c6 | https://github.com/ollama/ollama/releases/tag/v0.23.0 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 14. 维护坑 · 来源证据：Featured your project on osalt.dev — README badge available if you'd like to use it\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Featured your project on osalt.dev — README badge available if you'd like to use it\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d786a153134241388add2323ae688dfa | https://github.com/ollama/ollama/issues/16092 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 15. 维护坑 · 来源证据：Running qwen3.6:27b-bf16 on an AMD Ryzen AI Max leads to gibberish\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Running qwen3.6:27b-bf16 on an AMD Ryzen AI Max leads to gibberish\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ccd9e90075d24d39bf6fd43ae8b41221 | https://github.com/ollama/ollama/issues/15879 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 16. 维护坑 · 来源证据：Running qwen3.6:27b-q8_0 produces also gibberish on an AMD Ryzen AI Max+\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Running qwen3.6:27b-q8_0 produces also gibberish on an AMD Ryzen AI Max+\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4c22a5e593dd4d5b85e18cf0a5f790f4 | https://github.com/ollama/ollama/issues/15903 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 17. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:658928958 | https://github.com/ollama/ollama | last_activity_observed missing\n\n## 18. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:658928958 | https://github.com/ollama/ollama | no_demo; severity=medium\n\n## 19. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:658928958 | https://github.com/ollama/ollama | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 20. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:658928958 | https://github.com/ollama/ollama | no_demo; severity=medium\n\n## 21. 安全/权限坑 · 来源证据：v0.23.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.23.1\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a04a5f2703d24cc9aa072bdfcdc5552c | https://github.com/ollama/ollama/releases/tag/v0.23.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 22. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:658928958 | https://github.com/ollama/ollama | issue_or_pr_quality=unknown\n\n## 23. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:658928958 | https://github.com/ollama/ollama | release_recency=unknown\n\n\n",
"markdown_key": "ollama",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:658928958",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/ollama/ollama"
},
{
"evidence_id": "art_dfc0812014df427d8050c605baafddd7",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/ollama/ollama#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "ollama 说明书",
"toc": [
"https://github.com/ollama/ollama 项目说明书",
"目录",
"项目概述",
"核心定位",
"技术架构",
"核心组件",
"图像生成引擎",
"开发工作流",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "c2f2d90a679317e443b0c35aa6d6d747cdd6c57b",
"repo_inspection_error": null,
"repo_inspection_files": [
"Dockerfile",
"README.md",
"docs/import.mdx",
"docs/template.mdx",
"docs/macos.mdx",
"docs/cloud.mdx",
"docs/troubleshooting.mdx",
"docs/gpu.mdx",
"docs/docker.mdx",
"docs/api.md",
"docs/cli.mdx",
"docs/windows.mdx",
"docs/examples.md",
"docs/index.mdx",
"docs/README.md",
"docs/development.md",
"docs/docs.json",
"docs/quickstart.mdx",
"docs/openapi.yaml",
"docs/context-length.mdx",
"docs/modelfile.mdx",
"docs/linux.mdx",
"docs/faq.mdx",
"docs/api/openai-compatibility.mdx",
"docs/api/errors.mdx",
"docs/api/authentication.mdx",
"docs/api/anthropic-compatibility.mdx",
"docs/api/introduction.mdx",
"docs/api/usage.mdx",
"docs/api/streaming.mdx",
"docs/capabilities/structured-outputs.mdx",
"docs/capabilities/thinking.mdx",
"docs/capabilities/web-search.mdx",
"docs/capabilities/embeddings.mdx",
"docs/capabilities/tool-calling.mdx",
"docs/capabilities/vision.mdx",
"docs/capabilities/streaming.mdx",
"docs/integrations/opencode.mdx",
"docs/integrations/nemoclaw.mdx",
"docs/integrations/onyx.mdx"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# app - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 app 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `curl -fsSL https://ollama.com/install.sh | sh` 证据：`README.md` Claim：`clm_0003` supported 0.86\n- `curl http://localhost:11434/api/chat -d '{` 证据：`README.md` Claim：`clm_0004` supported 0.86\n- `pip install ollama` 证据：`README.md` Claim：`clm_0005` supported 0.86\n- `npm i ollama` 证据：`README.md` Claim：`clm_0006` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：先做角色匹配试用\n- **为什么**：这个项目更像角色库，核心风险是选错角色或把角色文案当执行能力；先用 Prompt Preview 试角色匹配，再决定是否沙盒导入。\n\n### 30 秒判断\n\n- **现在怎么做**：先做角色匹配试用\n- **最小安全下一步**：先用 Prompt Preview 试角色匹配；满意后再隔离导入\n- **先别相信**：角色质量和任务匹配不能直接相信。\n- **继续会触碰**：角色选择偏差、命令执行、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n### 现在还不能相信\n\n- **角色质量和任务匹配不能直接相信。**（unverified）：角色库证明有很多角色，不证明每个角色都适合你的具体任务，也不证明角色能产生高质量结果。\n- **不能把角色文案当成真实执行能力。**（unverified）：安装前只能判断角色描述和任务画像是否匹配，不能证明它能在宿主 AI 里完成任务。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n\n### 继续会触碰什么\n\n- **角色选择偏差**：用户对任务应该由哪个专家角色处理的判断。 原因：选错角色会让 AI 从错误专业视角回答，浪费时间或误导决策。\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：先用交互式试用验证任务画像和角色匹配，不要先导入整套角色库。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **保留原始角色选择记录**：如果输出偏题，可以回到任务画像阶段重新选择角色，而不是继续沿着错误角色推进。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0007` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0008` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：1932\n- 重要文件覆盖：40/1932\n- 证据索引条目：80\n- 角色 / Skill 条目：23\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 app 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 app 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 app 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 23 个角色 / Skill / 项目文档条目。\n\n- **Documentation**（project_doc）：Getting Started Quickstart https://docs.ollama.com/quickstart Examples ./examples.md Importing models https://docs.ollama.com/import MacOS Documentation https://docs.ollama.com/macos Linux Documentation https://docs.ollama.com/linux Windows Documentation https://docs.ollama.com/windows Docker Documentation https://docs.ollama.com/docker 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/README.md`\n- **extract-examples**（project_doc）：Extracts code examples from MDX files to a temp directory so you can run them. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/tools/extract-examples/README.md`\n- **Ollama**（project_doc）：or download manually https://ollama.com/download/Ollama.dmg 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **Ollama for macOS and Windows**（project_doc）：- macOS https://github.com/ollama/app/releases/download/latest/Ollama.dmg - Windows https://github.com/ollama/app/releases/download/latest/OllamaSetup.exe 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`app/README.md`\n- **Integration Tests**（project_doc）：This directory contains integration tests to exercise Ollama end-to-end to verify behavior 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`integration/README.md`\n- **llama**（project_doc）：This package provides Go bindings to llama.cpp https://github.com/ggerganov/llama.cpp . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama/README.md`\n- **runner**（project_doc）：A minimial runner for loading a model and running inference via a http web server. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`runner/README.md`\n- **Ollama API Examples**（project_doc）：Run the examples in this directory with: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`api/examples/README.md`\n- **Webview**（project_doc）：This is a vendored version of the webview go https://github.com/webview/webview go project 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`app/webview/README.md`\n- **Features**（project_doc）：Ollama Benchmark Tool --------------------- 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`cmd/bench/README.md`\n- **Image Generation in Ollama Experimental**（project_doc）：Image Generation in Ollama Experimental 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`x/imagegen/README.md`\n- **MLX Engine**（project_doc）：Experimental MLX backend for running models on Apple Silicon and CUDA. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`x/imagegen/cmd/engine/README.md`\n- **MLX Memory Management**（project_doc）：This package will get consolidated with x/ml/backend/mlx in the future. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`x/imagegen/mlx/README.md`\n- **Tokenizer**（project_doc）：Tokenizer for LLM inference supporting BPE, SentencePiece, and WordPiece algorithms. The goal of this package is to see if a pure Go tokenizer can be fast and correct. It primarily supports the imagegen models however it or parts of it could be considered to replace Ollama's tokenizer in the model package. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`x/imagegen/tokenizer/README.md`\n- **Vendored MLX-C Headers**（project_doc）：These header files are vendored from mlx-c https://github.com/ml-explore/mlx-c . The pinned version is in MLX C VERSION at the repo root. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`x/mlxrunner/mlx/include/mlx/c/README.md`\n- **Contributing to Ollama**（project_doc）：Thank you for your interest in contributing to Ollama! Here are a few guidelines to help get you started. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CONTRIBUTING.md`\n- **API**（project_doc）：Note: Ollama's API docs are moving to https://docs.ollama.com/api 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api.md`\n- **Development**（project_doc）：- Go https://go.dev/doc/install - C/C++ Compiler e.g. Clang on macOS, TDM-GCC https://github.com/jmeubank/tdm-gcc/releases/latest Windows amd64 or llvm-mingw https://github.com/mstorsjo/llvm-mingw Windows arm64 , GCC/Clang on Linux. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/development.md`\n- **Examples**（project_doc）：This directory contains different examples of using Ollama. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples.md`\n- **Tensor Blob Format**（project_doc）：Ollama stores model tensors as individual blobs in the safetensors format. Each blob contains a logical tensor or a combined quantized tensor with its scale/bias components , or a group of logical tensors e.g. shared experts for a given layer along with the scale/bias components for that tensor . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`x/imagegen/docs/blob-format.md`\n- **Security**（project_doc）：The Ollama maintainer team takes security seriously and will actively work to resolve security issues. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`SECURITY.md`\n- **Feature request**（project_doc）： 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.github/ISSUE_TEMPLATE/20_feature_request.md`\n- **Model request**（project_doc）： 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.github/ISSUE_TEMPLATE/30_model_request.md`\n\n## 证据索引\n\n- 共索引 80 条证据。\n\n- **Documentation**（documentation）：Getting Started Quickstart https://docs.ollama.com/quickstart Examples ./examples.md Importing models https://docs.ollama.com/import MacOS Documentation https://docs.ollama.com/macos Linux Documentation https://docs.ollama.com/linux Windows Documentation https://docs.ollama.com/windows Docker Documentation https://docs.ollama.com/docker 证据：`docs/README.md`\n- **extract-examples**（documentation）：Extracts code examples from MDX files to a temp directory so you can run them. 证据：`docs/tools/extract-examples/README.md`\n- **Ollama**（documentation）：or download manually https://ollama.com/download/Ollama.dmg 证据：`README.md`\n- **Ollama for macOS and Windows**（documentation）：- macOS https://github.com/ollama/app/releases/download/latest/Ollama.dmg - Windows https://github.com/ollama/app/releases/download/latest/OllamaSetup.exe 证据：`app/README.md`\n- **Integration Tests**（documentation）：This directory contains integration tests to exercise Ollama end-to-end to verify behavior 证据：`integration/README.md`\n- **llama**（documentation）：This package provides Go bindings to llama.cpp https://github.com/ggerganov/llama.cpp . 证据：`llama/README.md`\n- **runner**（documentation）：A minimial runner for loading a model and running inference via a http web server. 证据：`runner/README.md`\n- **Ollama API Examples**（documentation）：Run the examples in this directory with: 证据：`api/examples/README.md`\n- **Webview**（documentation）：This is a vendored version of the webview go https://github.com/webview/webview go project 证据：`app/webview/README.md`\n- **Features**（documentation）：Ollama Benchmark Tool --------------------- 证据：`cmd/bench/README.md`\n- **Image Generation in Ollama Experimental**（documentation）：Image Generation in Ollama Experimental 证据：`x/imagegen/README.md`\n- **MLX Engine**（documentation）：Experimental MLX backend for running models on Apple Silicon and CUDA. 证据：`x/imagegen/cmd/engine/README.md`\n- **MLX Memory Management**（documentation）：This package will get consolidated with x/ml/backend/mlx in the future. 证据：`x/imagegen/mlx/README.md`\n- **Tokenizer**（documentation）：Tokenizer for LLM inference supporting BPE, SentencePiece, and WordPiece algorithms. The goal of this package is to see if a pure Go tokenizer can be fast and correct. It primarily supports the imagegen models however it or parts of it could be considered to replace Ollama's tokenizer in the model package. 证据：`x/imagegen/tokenizer/README.md`\n- **Vendored MLX-C Headers**（documentation）：These header files are vendored from mlx-c https://github.com/ml-explore/mlx-c . The pinned version is in MLX C VERSION at the repo root. 证据：`x/mlxrunner/mlx/include/mlx/c/README.md`\n- **Contributing to Ollama**（documentation）：Thank you for your interest in contributing to Ollama! Here are a few guidelines to help get you started. 证据：`CONTRIBUTING.md`\n- **Package**（package_manifest）：{ \"name\": \"app\", \"private\": true, \"version\": \"0.0.0\", \"type\": \"module\", \"scripts\": { \"dev\": \"vite\", \"build\": \"tsc -b && vite build\", \"lint\": \"eslint .\", \"preview\": \"vite preview\", \"prettier\": \"prettier --write .\", \"prettier:check\": \"prettier --check .\", \"storybook\": \"storybook dev -p 6006\", \"build-storybook\": \"storybook build\", \"test\": \"vitest\", \"test:ui\": \"vitest --ui\", \"test:coverage\": \"vitest --coverage\" }, \"dependencies\": { \"@headlessui/react\": \"^2.2.4\", \"@heroicons/react\": \"^2.2.0\", \"@tanstack/react-query\": \"^5.80.7\", \"@tanstack/react-router\": \"^1.120.20\", \"@tanstack/react-router-devtools\": \"^1.120.20\", \"clsx\": \"^2.1.1\", \"framer-motion\": \"^12.17.0\", \"katex\": \"^0.16.22\", \"micromark-exte… 证据：`app/ui/app/package.json`\n- **License**（source_file）：Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files the \"Software\" , to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 证据：`LICENSE`\n- **License**（source_file）：Copyright c 2018, the dialog authors. 证据：`app/dialog/LICENSE`\n- **License**（source_file）：Copyright c 2023-2024 The ggml authors 证据：`llama/llama.cpp/LICENSE`\n- **License**（source_file）：Copyright c 2023-2024 The ggml authors 证据：`ml/backend/ggml/ggml/LICENSE`\n- **API**（documentation）：Note: Ollama's API docs are moving to https://docs.ollama.com/api 证据：`docs/api.md`\n- **Development**（documentation）：- Go https://go.dev/doc/install - C/C++ Compiler e.g. Clang on macOS, TDM-GCC https://github.com/jmeubank/tdm-gcc/releases/latest Windows amd64 or llvm-mingw https://github.com/mstorsjo/llvm-mingw Windows arm64 , GCC/Clang on Linux. 证据：`docs/development.md`\n- **Examples**（documentation）：This directory contains different examples of using Ollama. 证据：`docs/examples.md`\n- **Tensor Blob Format**（documentation）：Ollama stores model tensors as individual blobs in the safetensors format. Each blob contains a logical tensor or a combined quantized tensor with its scale/bias components , or a group of logical tensors e.g. shared experts for a given layer along with the scale/bias components for that tensor . 证据：`x/imagegen/docs/blob-format.md`\n- **Security**（documentation）：The Ollama maintainer team takes security seriously and will actively work to resolve security issues. 证据：`SECURITY.md`\n- **20 Feature Request**（documentation）：--- name: Feature request about: Request a new feature labels: feature request --- 证据：`.github/ISSUE_TEMPLATE/20_feature_request.md`\n- **30 Model Request**（documentation）：--- name: Model request about: Request support for a new model to be added to Ollama labels: model request --- 证据：`.github/ISSUE_TEMPLATE/30_model_request.md`\n- **Cmakepresets**（structured_config）：{ \"version\": 3, \"configurePresets\": { \"name\": \"Default\", \"binaryDir\": \"${sourceDir}/build\", \"installDir\": \"${sourceDir}/dist\", \"cacheVariables\": { \"CMAKE BUILD TYPE\": \"Release\", \"CMAKE MSVC RUNTIME LIBRARY\": \"MultiThreaded\" } }, { \"name\": \"CPU\", \"inherits\": \"Default\" }, { \"name\": \"CUDA\", \"inherits\": \"Default\" }, { \"name\": \"CUDA 11\", \"inherits\": \"CUDA\" , \"cacheVariables\": { \"CMAKE CUDA ARCHITECTURES\": \"50-virtual;60-virtual;61-virtual;70-virtual;75-virtual;80-virtual;86-virtual;87-virtual;89-virtual;90-virtual\", \"CMAKE CUDA FLAGS\": \"-Wno-deprecated-gpu-targets -t 2\", \"OLLAMA RUNNER DIR\": \"cuda v11\" } }, { \"name\": \"CUDA 12\", \"inherits\": \"CUDA\" , \"cacheVariables\": { \"CMAKE CUDA ARCHITECTURES\":… 证据：`CMakePresets.json`\n- **Docs**（structured_config）：{ \"$schema\": \"https://mintlify.com/docs.json\", \"name\": \"Ollama\", \"colors\": { \"primary\": \" 000\", \"light\": \" b5b5b5\", \"dark\": \" 000\" }, \"favicon\": \"/images/favicon.png\", \"logo\": { \"light\": \"/images/logo.png\", \"dark\": \"/images/logo-dark.png\", \"href\": \"https://ollama.com\" }, \"theme\": \"maple\", \"background\": { \"color\": { \"light\": \" ffffff\", \"dark\": \" 000000\" } }, \"fonts\": { \"family\": \"system-ui\", \"heading\": { \"family\": \"system-ui\" }, \"body\": { \"family\": \"system-ui\" } }, \"styling\": { \"codeblocks\": \"system\" }, \"contextual\": { \"options\": \"copy\" }, \"navbar\": { \"links\": { \"label\": \"Sign in\", \"href\": \"https://ollama.com/signin\" } , \"primary\": { \"type\": \"button\", \"label\": \"Download\", \"href\": \"https://ol… 证据：`docs/docs.json`\n- **Alfred**（structured_config）：{ \"stop\": \" \", \" \", \" \", \" \" } 证据：`template/alfred.json`\n- **Alpaca**（structured_config）：{ \"stop\": \" Instruction:\", \" Response\" } 证据：`template/alpaca.json`\n- **Chatml**（structured_config）：{ \"stop\": \" \", \" \" } 证据：`template/chatml.json`\n- **Chatqa**（structured_config）：{ \"stop\": \"System:\", \"User:\", \"Assistant:\", \" \" } 证据：`template/chatqa.json`\n- **Codellama 70B Instruct**（structured_config）：{ \"stop\": \"Source:\", \"Destination:\", \" \" } 证据：`template/codellama-70b-instruct.json`\n- **Command R**（structured_config）：{ \"stop\": \" \", \" \" } 证据：`template/command-r.json`\n- **Falcon Instruct**（structured_config）：{ \"stop\": \"User:\", \"Assistant:\" } 证据：`template/falcon-instruct.json`\n- **Gemma Instruct**（structured_config）：{ \"stop\": \" \", \" \" } 证据：`template/gemma-instruct.json`\n- **Gemma3 Instruct**（structured_config）：{ \"stop\": \" \" , \"temperature\": 0.1 } 证据：`template/gemma3-instruct.json`\n- **Granite Instruct**（structured_config）：{ \"stop\": \"System:\", \"Question:\", \"Answer:\" } 证据：`template/granite-instruct.json`\n- **Index**（structured_config）：{ \"template\": \"{% if messages 0 'role' == 'system' %}{% set system message = messages 0 'content' %}{% endif %}{% if system message is defined %}{{ system message }}{% endif %}{% for message in messages %}{% set content = message 'content' %}{% if message 'role' == 'user' %}{{ ' user\\\\n' + content + ' \\\\n assistant\\\\n' }}{% elif message 'role' == 'assistant' %}{{ content + ' ' + '\\\\n' }}{% endif %}{% endfor %}\", \"name\": \"chatml\" }, { \"template\": \"{% if not add generation prompt is defined %}{% set add generation prompt = false %}{% endif %}{% for message in messages %}{{' ' + message 'role' + '\\n' + message 'content' + ' ' + '\\n'}}{% endfor %}{% if add generation prompt %}{{ ' assistant\\n'… 证据：`template/index.json`\n- **Llama2 Chat**（structured_config）：{ \"stop\": \" INST \", \" /INST \", \" \", \" \" } 证据：`template/llama2-chat.json`\n- **Llama3 Instruct**（structured_config）：{ \"stop\": \" \", \" \", \" \" } 证据：`template/llama3-instruct.json`\n- **Magicoder**（structured_config）：{ \"stop\": \"@@ Instruction\", \"@@ Response\" } 证据：`template/magicoder.json`\n- **Mistral Instruct**（structured_config）：{ \"stop\": \" \", \" \" } 证据：`template/mistral-instruct.json`\n- **Openchat**（structured_config）：{ \"stop\": \" \" } 证据：`template/openchat.json`\n- **Phi 3**（structured_config）：{ \"stop\": \" \", \" \", \" \", \" \" } 证据：`template/phi-3.json`\n- **Solar Instruct**（structured_config）：{ \"stop\": \" System:\", \" User:\", \" Assistant\" } 证据：`template/solar-instruct.json`\n- **Starcoder2 Instruct**（structured_config）：{ \"stop\": \" Instruction\", \" Response\", \" \" } 证据：`template/starcoder2-instruct.json`\n- **Vicuna**（structured_config）：{ \"stop\": \"USER:\", \"ASSISTANT:\" } 证据：`template/vicuna.json`\n- **Zephyr**（structured_config）：{ \"stop\": \" \", \" \", \" \", \" \" } 证据：`template/zephyr.json`\n- **Tsconfig.App**（structured_config）：{ \"compilerOptions\": { \"baseUrl\": \".\", \"tsBuildInfoFile\": \"./node modules/.tmp/tsconfig.app.tsbuildinfo\", \"target\": \"ES2020\", \"useDefineForClassFields\": true, \"lib\": \"ES2020\", \"DOM\", \"DOM.Iterable\" , \"module\": \"ESNext\", \"skipLibCheck\": true, \"types\": , 证据：`app/ui/app/tsconfig.app.json`\n- **Tsconfig**（structured_config）：{ \"files\": , \"references\": { \"path\": \"./tsconfig.app.json\" }, { \"path\": \"./tsconfig.node.json\" }, { \"path\": \"./tsconfig.stories.json\" } } 证据：`app/ui/app/tsconfig.json`\n- **Tsconfig.Node**（structured_config）：{ \"compilerOptions\": { \"tsBuildInfoFile\": \"./node modules/.tmp/tsconfig.node.tsbuildinfo\", \"target\": \"ES2022\", \"lib\": \"ES2023\" , \"module\": \"ESNext\", \"skipLibCheck\": true, 证据：`app/ui/app/tsconfig.node.json`\n- **Tsconfig.Stories**（structured_config）：{ \"extends\": \"./tsconfig.app.json\", \"compilerOptions\": { \"types\": \"@storybook/react-vite\" }, \"include\": \"src/ / .stories. \" , \"exclude\": } 证据：`app/ui/app/tsconfig.stories.json`\n- **.dockerignore**（source_file）：.vscode ollama app macapp dist build .env .cache test data .git 证据：`.dockerignore`\n- **.gitattributes**（source_file）：llama/ / .cpp linguist-vendored llama/ / .hpp linguist-vendored llama/ / .h linguist-vendored llama/ / .c linguist-vendored llama/ / .cu linguist-vendored llama/ / .cuh linguist-vendored llama/ / .m linguist-vendored llama/ / .metal linguist-vendored 证据：`.gitattributes`\n- **.gitignore**（source_file）：.DS Store .vscode .env .venv .swp dist build .cache .gocache .exe .idea test data .crt debug bin llama/build llama/vendor /ollama integration/testdata/models/ 证据：`.gitignore`\n- **.Golangci**（source_file）：version: \"2\" linters: enable: - asasalint - bidichk - bodyclose - containedctx - gocheckcompilerdirectives - intrange - makezero - misspell - nilerr - nolintlint - nosprintfhostport - unconvert - usetesting - wastedassign - whitespace disable: - errcheck - usestdlibvars settings: govet: disable: - unusedresult staticcheck: checks: - all - -QF disable quick fix suggestions - -SA1019 - -ST1000 package comment format - -ST1003 underscores in package names - -ST1005 error strings should not be capitalized - -ST1012 error var naming ErrFoo - -ST1016 receiver name consistency - -ST1020 comment on exported function format - -ST1021 comment on exported type format - -ST1022 comment on exported var… 证据：`.golangci.yaml`\n- **Handle cross-compilation on macOS: when CMAKE OSX ARCHITECTURES is set to a**（source_file）：cmake minimum required VERSION 3.21 证据：`CMakeLists.txt`\n- 其余 20 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`docs/README.md`, `docs/tools/extract-examples/README.md`, `README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`docs/README.md`, `docs/tools/extract-examples/README.md`, `README.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **项目概述**：importance `high`\n - source_paths: README.md, llama/README.md, docs/index.mdx\n- **系统架构**：importance `high`\n - source_paths: llm/server.go, server/routes.go, server/sched.go, llama/llama.go, discover/gpu.go\n- **API 参考**：importance `high`\n - source_paths: api/types.go, api/client.go, server/routes.go, openai/openai.go, anthropic/anthropic.go\n- **模型管理**：importance `high`\n - source_paths: server/model.go, server/model_resolver.go, server/model_recommendations.go, server/model_caches.go, manifest/manifest.go\n- **LLM 后端系统**：importance `high`\n - source_paths: llama/llama.cpp/src/llama.cpp, llama/llama.go, llm/llm_darwin.go, llm/llm_linux.go, llm/llm_windows.go\n- **命令行系统**：importance `high`\n - source_paths: cmd/cmd.go, cmd/interactive.go, cmd/config/config.go, cmd/launch/launch.go, cmd/tui/tui.go\n- **桌面应用程序**：importance `medium`\n - source_paths: app/server/server.go, app/ui/app.go, app/ui/ui.go, app/webview/webview.go, app/updater/updater.go\n- **高级功能**：importance `high`\n - source_paths: docs/capabilities/streaming.mdx, docs/capabilities/tool-calling.mdx, docs/capabilities/vision.mdx, docs/capabilities/embeddings.mdx, docs/capabilities/thinking.mdx\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `c2f2d90a679317e443b0c35aa6d6d747cdd6c57b`\n- inspected_files: `Dockerfile`, `README.md`, `docs/import.mdx`, `docs/template.mdx`, `docs/macos.mdx`, `docs/cloud.mdx`, `docs/troubleshooting.mdx`, `docs/gpu.mdx`, `docs/docker.mdx`, `docs/api.md`, `docs/cli.mdx`, `docs/windows.mdx`, `docs/examples.md`, `docs/index.mdx`, `docs/README.md`, `docs/development.md`, `docs/docs.json`, `docs/quickstart.mdx`, `docs/openapi.yaml`, `docs/context-length.mdx`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：0.23.1 : mlx runner failed\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：0.23.1 : mlx runner failed\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_06acaa8b4f9d4923977e39f0de3349df | https://github.com/ollama/ollama/issues/16007 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：Ollama Cloud: Frequent 503 errors making cloud models unreliable\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Ollama Cloud: Frequent 503 errors making cloud models unreliable\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_568af28cdfb04c3eaf66b648ffff865f | https://github.com/ollama/ollama/issues/15419 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：Support `ppc64le` architecture\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Support `ppc64le` architecture\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_82122f2d4dfd4202a09101c78837de0e | https://github.com/ollama/ollama/issues/796 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：Not compatible with Glaude code Cli when using local model\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Not compatible with Glaude code Cli when using local model\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_18239d63b211480fa37ec3c6dfb773ee | https://github.com/ollama/ollama/issues/16094 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：Registering fine-tuned models\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Registering fine-tuned models\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_3417faf9df79457e841e34e3df365558 | https://github.com/ollama/ollama/issues/16095 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：[Bug] 0.23.2 Image generation succeeds but no image saved to disk or returned via API\"\n\n- Trigger: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：[Bug] 0.23.2 Image generation succeeds but no image saved to disk or returned via API\"\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_294d6c7549c44529a06895132ef49777 | https://github.com/ollama/ollama/issues/16072 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 来源证据：Feature Request: Expose account quota/usage details via Ollama Cloud API (headers and/or response body)\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Feature Request: Expose account quota/usage details via Ollama Cloud API (headers and/or response body)\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_56cc99bad67b43a6b9a0ccff38aef5e2 | https://github.com/ollama/ollama/issues/15663 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 来源证据：VRAM Detection Issue on Radeon 780M (gfx1035) - Kernel Page Fault\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：VRAM Detection Issue on Radeon 780M (gfx1035) - Kernel Page Fault\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_26de977c783d40308b5962cd61c7a1df | https://github.com/ollama/ollama/issues/16040 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 来源证据：mistral-medium-3.5 - Produces nonsense outputs\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：mistral-medium-3.5 - Produces nonsense outputs\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_5516e9097bb34de3a29210537c23e393 | https://github.com/ollama/ollama/issues/15975 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:658928958 | https://github.com/ollama/ollama | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：ollama/ollama\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：local_cli\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：0.23.1 : mlx runner failed（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Ollama Cloud: Frequent 503 errors making cloud models unreliable（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Support `ppc64le` architecture（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Not compatible with Glaude code Cli when using local model（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Registering fine-tuned models（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/ollama/ollama 项目说明书\n\n生成时间：2026-05-11 12:46:52 UTC\n\n## 目录\n\n- [项目概述](#page-overview)\n- [系统架构](#page-architecture)\n- [API 参考](#page-api-reference)\n- [模型管理](#page-model-management)\n- [LLM 后端系统](#page-llm-backend)\n- [命令行系统](#page-cli-system)\n- [桌面应用程序](#page-desktop-app)\n- [高级功能](#page-advanced-features)\n- [部署与构建](#page-deployment)\n- [模型转换系统](#page-model-conversion)\n\n\n\n## 项目概述\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [LLM 后端系统](#page-llm-backend), [部署与构建](#page-deployment)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/ollama/ollama/blob/main/README.md)\n- [llama/README.md](https://github.com/ollama/ollama/blob/main/llama/README.md)\n- [docs/index.mdx](https://github.com/ollama/ollama/blob/main/docs/index.mdx)\n- [app/README.md](https://github.com/ollama/ollama/blob/main/app/README.md)\n- [api/examples/README.md](https://github.com/ollama/ollama/blob/main/api/examples/README.md)\n- [cmd/bench/README.md](https://github.com/ollama/ollama/blob/main/cmd/bench/README.md)\n- [runner/README.md](https://github.com/ollama/ollama/blob/main/runner/README.md)\n- [x/imagegen/cmd/engine/README.md](https://github.com/ollama/ollama/blob/main/x/imagegen/cmd/engine/README.md)\n \n\n# 项目概述\n\nOllama 是一款开源的大语言模型（Large Language Model，LLM）运行框架，旨在为开发者提供简便的本地模型部署和推理能力。通过统一的命令行接口和 REST API，Ollama 支持在本地环境中运行各种开源模型，无需复杂的配置或云端依赖。\n\n## 核心定位\n\nOllama 的设计目标是降低大语言模型的使用门槛，让用户能够在个人电脑或服务器上直接运行、测试和部署 AI 模型。项目采用轻量化架构，将模型管理、推理引擎和 API 服务整合为一个统一的系统，同时保持高度的可扩展性和跨平台兼容性。\n\n该项目的主要特性包括：\n\n- **本地运行**：所有模型推理均在本地设备完成，数据不需要离开用户的计算机\n- **跨平台支持**：支持 macOS、Windows 和 Linux 操作系统\n- **模型管理**：提供命令行工具用于下载、运行和管理各类开源模型\n- **API 接口**：提供 RESTful API，方便应用程序集成和使用\n- **多种推理后端**：支持 CUDA、Metal、Vulkan、Sycl 等多种硬件加速后端\n\n## 技术架构\n\nOllama 的系统架构采用分层设计，从底层到顶层依次为推理引擎层、模型管理层、API 服务层和应用接口层。\n\n```mermaid\ngraph TD\n A[用户应用] --> B[REST API / CLI]\n B --> C[API 服务层]\n C --> D[模型管理层]\n D --> E[推理引擎层]\n E --> F{硬件加速后端}\n F --> G[CUDA]\n F --> H[Metal]\n F --> I[Vulkan]\n F --> J[CPU]\n```\n\n### 推理引擎层\n\n推理引擎层是 Ollama 的核心计算组件，基于 ggml（现更名为 llama.cpp）库实现。该层负责加载模型权重、执行张量运算和处理模型推理的各个阶段。\n\n```mermaid\ngraph LR\n A[模型文件] --> B[GGUF 格式解析]\n B --> C[张量加载]\n C --> D[推理计算]\n D --> E[结果输出]\n \n style A fill:#e1f5fe\n style E fill:#e8f5e8\n```\n\n**支持的推理后端**：\n\n| 后端 | 平台 | 描述 |\n|------|------|------|\n| CUDA | Linux/Windows | NVIDIA GPU 加速 |\n| Metal | macOS | Apple Silicon GPU 加速 |\n| Vulkan | 跨平台 | 通用 GPU 加速 |\n| SYCL | Linux | Intel GPU 加速 |\n| CPU | 跨平台 | 仅使用 CPU 计算 |\n\n资料来源：[ml/backend/ggml/ggml/src/ggml-backend-reg.cpp:1-56]()\n\n推理引擎支持多种量化格式，以在保持模型质量的同时减少内存占用：\n\n| 量化类型 | 描述 | 内存占用 |\n|----------|------|----------|\n| f32 | 全精度浮点 | 100% |\n| f16 | 半精度浮点 | 50% |\n| q4_0 | 4位量化 | 25% |\n| q4_1 | 4位量化（改进版） | 29% |\n| q5_0 | 5位量化 | 31% |\n| q5_1 | 5位量化（改进版） | 35% |\n| q8_0 | 8位量化 | 50% |\n| q2_k | 2位量化（知识蒸馏） | 30% |\n| q3_k | 3位量化（知识蒸馏） | 37% |\n| q4_k | 4位量化（知识蒸馏） | 46% |\n| q5_k | 5位量化（知识蒸馏） | 57% |\n| q6_k | 6位量化（知识蒸馏） | 67% |\n\n资料来源：[ml/backend/ggml/ggml/src/ggml-vulkan/vulkan-shaders/vulkan-shaders-gen.cpp:28-46]()\n\n### 模型管理层\n\n模型管理层负责处理模型的下载、存储、版本管理和运行时加载。该层维护本地模型仓库，支持从官方模型库或自定义来源获取模型。\n\n模型文件采用 GGUF（Generic Graph Unification Format）格式存储，该格式将模型的架构、权重和元数据整合在单一文件中，便于分发和加载。\n\n### API 服务层\n\nOllama 提供了完整的 REST API，支持与现有应用程序的集成。API 服务层封装了模型调用的所有逻辑，提供标准化的接口。\n\n**主要 API 端点**：\n\n| 端点 | 方法 | 功能 |\n|------|------|------|\n| /api/chat | POST | 对话式聊天交互 |\n| /api/generate | POST | 文本生成 |\n| /api/embeddings | POST | 生成文本嵌入向量 |\n| /api/pull | POST | 拉取模型 |\n| /api/create | POST | 创建新模型 |\n| /api/push | POST | 上传模型到仓库 |\n| /api/show | POST | 显示模型信息 |\n| /api/tags | GET | 列出本地模型 |\n\n资料来源：[api/examples/README.md:1-30]()\n\n### 应用接口层\n\n应用接口层提供两种主要的交互方式：命令行界面（CLI）和桌面应用程序。\n\n**命令行工具**：\n```bash\nollama run llama3 # 运行模型\nollama pull llama3 # 下载模型\nollama list # 列出本地模型\nollama ps # 显示运行中的模型\nollama rm llama3 # 删除模型\n```\n\n**桌面应用程序**：\nOllama 提供独立的桌面客户端，支持 macOS 和 Windows 平台。该应用基于 React 前端框架构建，提供图形化的模型管理和对话界面。\n\n资料来源：[app/README.md:1-50]()\n\n## 核心组件\n\n### 命令行客户端\n\n命令行客户端是用户与 Ollama 交互的主要工具之一。它提供了简洁的接口用于执行所有模型操作，包括运行推理、管理模型和配置系统参数。\n\n主要命令包括：\n\n| 命令 | 用途 |\n|------|------|\n| run | 启动模型交互会话 |\n| create | 从 Modelfile 创建模型 |\n| show | 显示模型信息 |\n| run | 运行模型（快捷方式） |\n| pull | 从模型库下载模型 |\n| push | 上传模型到仓库 |\n| list | 列出本地已安装的模型 |\n| ps | 显示当前运行的模型 |\n| cp | 复制模型 |\n| rm | 删除模型 |\n| help | 显示帮助信息 |\n\n### 桌面应用\n\nOllama 桌面应用程序为用户提供了图形化的操作界面，主要功能包括：\n\n- **模型选择器**：浏览和选择本地或云端模型\n- **聊天界面**：与模型进行对话交互\n- **设置管理**：配置系统参数，如网络暴露、模型存储路径等\n- **下载管理**：显示模型下载进度和状态\n- **错误显示**：展示运行过程中的错误信息和诊断数据\n\n```mermaid\ngraph TD\n A[桌面应用] --> B[模型选择器]\n A --> C[聊天界面]\n A --> D[设置面板]\n A --> E[下载管理]\n \n C --> F[消息组件]\n F --> G[工具调用]\n G --> H[网络搜索]\n G --> I[网页抓取]\n \n D --> J[网络配置]\n D --> K[存储配置]\n D --> L[云端设置]\n```\n\n资料来源：[app/ui/app/src/components/ModelPicker.tsx:1-30]()\n资料来源：[app/ui/app/src/components/Downloading.tsx:1-25]()\n资料来源：[app/ui/app/src/components/Settings.tsx:1-80]()\n资料来源：[app/ui/app/src/components/Message.tsx:1-50]()\n\n### 性能基准测试工具\n\nOllama 内置了性能基准测试工具 `ollama-bench`，用于评估模型在不同硬件配置下的推理性能。该工具支持多种测试场景和参数配置。\n\n**基本用法**：\n```bash\n./ollama-bench -model gemma3 -epochs 6 -max-tokens 100 -p \"Write me a short story\"\n```\n\n**带图像的测试**：\n```bash\n./ollama-bench -model qwen3-vl -image photo.jpg -epochs 6 -max-tokens 100 -p \"Describe this image\"\n```\n\n**测试参数**：\n\n| 参数 | 说明 | 默认值 |\n|------|------|--------|\n| -model | 待测试的模型列表（逗号分隔） | 必填 |\n| -epochs | 每个模型的迭代次数 | 6 |\n| -max-tokens | 模型响应的最大 token 数 | 200 |\n| -temperature | 采样温度参数 | 0.0 |\n| -seed | 随机种子 | 0（随机） |\n| -timeout | 超时时间（秒） | 300 |\n| -p | 提示文本 | 默认故事提示 |\n| -image | 包含在提示中的图像文件 | 空 |\n| -k | Keep-alive 持续时间（秒） | 0 |\n| -format | 输出格式（csv/json） | 默认格式 |\n\n资料来源：[cmd/bench/README.md:1-50]()\n\n## 图像生成引擎\n\n除了语言模型推理，Ollama 还包含一个实验性的图像生成引擎，采用 MLX（Machine Learning Acceleration）技术实现。该引擎支持在 Apple Silicon 和 CUDA 设备上运行图像生成任务。\n\n**构建和运行**：\n```bash\ngo build -o engine ./x/imagegen/cmd/engine\n./engine -zimage -model /path/to/z-image -prompt \"a cat\" -output cat.png\n```\n\n**可用参数**：\n\n| 参数 | 说明 | 默认值 |\n|------|------|--------|\n| -width | 图像宽度 | 1024 |\n| -height | 图像高度 | 1024 |\n| -steps | 去噪步数 | 9 |\n| -seed | 随机种子 | 42 |\n\n资料来源：[x/imagegen/cmd/engine/README.md:1-30]()\n\n## 开发工作流\n\n### 桌面应用开发\n\n桌面应用的开发采用前后端分离架构，前端使用 React + Vite 构建，后端使用 Go 语言。\n\n```mermaid\ngraph LR\n A[前端开发] --> B[npm run dev]\n B --> C[Vite Dev Server]\n C --> D[热重载]\n \n E[后端开发] --> F[go run ./cmd/app]\n F --> G[API 服务]\n \n C --> H[端口 5173]\n G --> I[端口 3001]\n```\n\n**环境准备**：\n```bash\ngo install github.com/tkrajina/typescriptify-golang-structs/tscriptify@latest\n```\n\n**开发模式启动**：\n```bash\ncd ui/app\nnpm install\nnpm run dev\n```\n\n```bash\ngo generate ./... && OLLAMA_DEBUG=1 go run ./cmd/app -dev\n```\n\n开发模式启用以下特性：\n- 从 Vite 开发服务器加载 UI（端口 5173）\n- API 请求固定到本地端口 3001\n- 支持跨域请求\n- UI 热重载支持\n\n资料来源：[app/README.md:20-40]()\n\n### Runner 组件\n\nRunner 是 Ollama 的轻量级推理组件，提供最小化的模型加载和推理 HTTP 服务。开发者可以使用 Runner 快速测试模型或构建自定义推理服务。\n\n**基本用法**：\n```bash\n./runner -model \n```\n\n**API 端点**：\n\n| 端点 | 方法 | 功能 |\n|------|------|------|\n| /completion | POST | 文本补全 |\n| /embedding | POST | 嵌入向量生成 |\n\n**示例请求**：\n```bash\ncurl -X POST -H \"Content-Type: application/json\" -d '{\"prompt\": \"hi\"}' http://localhost:8080/completion\n\ncurl -X POST -H \"Content-Type: application/json\" -d '{\"prompt\": \"turn me into an embedding\"}' http://localhost:8080/embedding\n```\n\n资料来源：[runner/README.md:1-30]()\n\n## 系统要求\n\n### 硬件要求\n\n| 组件 | 最低要求 | 推荐配置 |\n|------|----------|----------|\n| 内存 | 8GB | 16GB 及以上 |\n| 存储 | 10GB 可用空间 | 50GB 及以上 |\n| GPU（可选） | NVIDIA GPU with CUDA / Apple Silicon / 兼容 Vulkan | 高端独立显卡 |\n\n### 软件要求\n\n| 平台 | 要求 |\n|------|------|\n| macOS | macOS 10.15+ |\n| Windows | Windows 10/11 |\n| Linux | Ubuntu 18.04+ 或等效发行版 |\n\n## 下载和安装\n\n用户可以通过以下方式获取 Ollama：\n\n| 平台 | 下载地址 |\n|------|----------|\n| macOS | https://github.com/ollama/app/releases/download/latest/Ollama.dmg |\n| Windows | https://github.com/ollama/app/releases/download/latest/OllamaSetup.exe |\n| Linux | 使用安装脚本或包管理器 |\n\n资料来源：[app/README.md:1-10]()\n\n## 扩展功能\n\n### 工具调用\n\nOllama 支持工具调用功能，允许模型在对话中调用外部工具来完成特定任务。主要支持的工具类型包括：\n\n- **网络搜索**：通过 `web_search` 工具进行实时信息搜索\n- **网页抓取**：通过 `web_fetch` 工具获取网页内容\n\n```mermaid\ngraph TD\n A[用户请求] --> B{是否需要工具}\n B -->|是| C[选择工具]\n C --> D[web_search]\n C --> E[web_fetch]\n D --> F[显示搜索结果]\n E --> G[显示抓取内容]\n F --> H[模型整合回复]\n G --> H\n B -->|否| I[直接生成回复]\n I --> H\n```\n\n资料来源：[app/ui/app/src/components/Message.tsx:1-40]()\n\n### 思考模式\n\nOllama 支持可配置的思考模式（Think Mode），用户可以根据需求选择不同的思考深度级别。该功能通过 `ThinkButton` 组件实现，提供下拉式选择界面。\n\n| 思考级别 | 描述 |\n|----------|------|\n| 基础 | 快速响应，适用于简单问题 |\n| 标准 | 适度推理，平衡速度和深度 |\n| 深度 | 详细推理，适用于复杂问题 |\n\n资料来源：[app/ui/app/src/components/ThinkButton.tsx:1-40]()\n\n## 技术特点\n\n### Unicode 支持\n\nOllama 的推理引擎包含完整的 Unicode 处理能力，支持多种字符编码和国际化文本处理。核心的 Unicode 函数包括：\n\n| 函数 | 功能 |\n|------|------|\n| `unicode_len_utf8` | 计算 UTF-8 字符长度 |\n| `unicode_cpt_to_utf8` | 码点转 UTF-8 |\n| `unicode_cpt_from_utf8` | UTF-8 转码点 |\n\n资料来源：[llama/llama.cpp/src/unicode.cpp:1-30]()\n\n### 错误处理\n\n系统提供完善的错误处理和展示机制，通过 `ErrorMessage` 组件向用户呈现运行错误，同时支持错误信息的链接渲染和格式化显示。\n\n资料来源：[app/ui/app/src/components/ErrorMessage.tsx:1-30]()\n\n## 总结\n\nOllama 是一个功能完善的大语言模型运行框架，通过模块化的架构设计，为用户提供了从模型管理、推理计算到应用集成的完整解决方案。其跨平台特性、多后端支持和丰富的 API 接口，使其成为在本地环境中部署和使用大语言模型的理想选择。项目采用开源模式开发，持续获得社区贡献和更新。\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[项目概述](#page-overview), [API 参考](#page-api-reference), [LLM 后端系统](#page-llm-backend)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [llm/server.go](https://github.com/ollama/ollama/blob/main/llm/server.go)\n- [server/routes.go](https://github.com/ollama/ollama/blob/main/server/routes.go)\n- [server/sched.go](https://github.com/ollama/ollama/blob/main/server/sched.go)\n- [llama/llama.go](https://github.com/ollama/ollama/blob/main/llama/llama.go)\n- [discover/gpu.go](https://github.com/ollama/ollama/blob/main/discover/gpu.go)\n- [api/client.go](https://github.com/ollama/ollama/blob/main/api/client.go)\n \n\n# 系统架构\n\n## 概述\n\nOllama 是一个本地大语言模型运行框架，旨在为用户提供简便的方式来下载、运行和管理各种大语言模型。其核心设计理念是将复杂的模型加载、推理调度和硬件加速封装成简洁的 API 接口，使开发者能够通过 REST API、Python SDK 或 JavaScript SDK 与本地运行的模型进行交互。\n\nOllama 的系统架构采用分层设计，从上到下依次为：API 层、服务层、调度层、LLM 运行时层和后端加速层。这种分层架构确保了各模块之间的低耦合和高内聚，便于扩展新的后端支持和完善调度策略。\n\n## 整体架构\n\nOllama 的系统架构可以用以下层次结构表示：\n\n```mermaid\ngraph TB\n subgraph \"API 层\"\n REST_API[REST API]\n Python_SDK[Python SDK]\n JS_SDK[JavaScript SDK]\n end\n \n subgraph \"服务层\"\n Routes[HTTP Routes]\n Handlers[Request Handlers]\n end\n \n subgraph \"调度层\"\n Scheduler[调度器 Sched]\n Queue[请求队列]\n LoadBalancer[负载均衡]\n end\n \n subgraph \"LLM 运行时层\"\n LLMServer[LLM Server]\n Session[会话管理]\n Tokenizer[分词器]\n end\n \n subgraph \"后端加速层\"\n GGML[GGML Library]\n CUDA[CUDA Backend]\n Metal[Metal Backend]\n Vulkan[Vulkan Backend]\n SYCL[SYCL Backend]\n end\n \n subgraph \"硬件层\"\n GPU[GPU 设备]\n CPU[CPU 设备]\n end\n \n REST_API --> Routes\n Python_SDK --> Routes\n JS_SDK --> Routes\n Routes --> Handlers\n Handlers --> Scheduler\n Scheduler --> LLMServer\n LLMServer --> GGML\n GGML --> CUDA\n GGML --> Metal\n GGML --> Vulkan\n GGML --> SYCL\n CUDA --> GPU\n Metal --> GPU\n Vulkan --> GPU\n SYCL --> GPU\n GGML --> CPU\n```\n\n## 核心组件\n\n### API 层\n\nOllama 提供三层 API 接口供开发者使用：\n\n| 接口类型 | 端点 | 用途 |\n|---------|------|------|\n| REST API | `http://localhost:11434` | 直接 HTTP 调用 |\n| Python SDK | `pip install ollama` | Python 应用集成 |\n| JavaScript SDK | `npm i ollama` | Node.js 应用集成 |\n\nREST API 的核心端点包括：\n\n- `/api/chat` - 对话接口，支持流式输出\n- `/api/generate` - 文本生成接口\n- `/api/pull` - 模型下载接口，支持进度回调\n\n资料来源：[README.md](https://github.com/ollama/ollama/blob/main/README.md)\n\n### 服务层\n\n服务层负责处理 HTTP 请求并将请求路由到相应的处理器。\n\n#### 路由分发\n\nOllama 使用 Go 标准库的 HTTP 处理机制，通过 `server/routes.go` 文件定义路由规则。每个路由对应一个具体的业务处理函数，包括模型加载、推理执行、模型列表查询等功能。\n\n```go\n// 路由注册示意\nfunc setupRoutes(mux *http.ServeMux) {\n mux.HandleFunc(\"/api/chat\", handleChat)\n mux.HandleFunc(\"/api/generate\", handleGenerate)\n mux.HandleFunc(\"/api/pull\", handlePull)\n mux.HandleFunc(\"/api/models\", handleListModels)\n}\n```\n\n资料来源：[server/routes.go](https://github.com/ollama/ollama/blob/main/server/routes.go)\n\n### 调度层\n\n调度层是 Ollama 架构中的核心组件，负责管理模型的生命周期和请求的分发。\n\n#### 调度器 (Scheduler)\n\n调度器维护一个请求队列和已加载模型的映射关系。当请求到达时，调度器根据模型名称找到对应的运行实例，如果没有可用实例则创建新实例。\n\n```mermaid\ngraph LR\n A[请求] --> B{模型已加载?}\n B -->|是| C[分配到现有实例]\n B -->|否| D{资源足够?}\n D -->|是| E[创建新实例]\n D -->|否| F[等待资源释放]\n E --> G[分配请求]\n F --> B\n C --> H[执行推理]\n G --> H\n```\n\n调度器使用以下策略进行负载管理：\n\n- **模型隔离**：不同模型的请求分配到不同的运行实例\n- **资源感知**：根据可用 GPU 显存和系统内存动态决定是否加载新模型\n- **会话复用**：保持已加载模型实例活跃以减少加载延迟\n\n资料来源：[server/sched.go](https://github.com/ollama/ollama/blob/main/server/sched.go)\n\n### LLM 运行时层\n\nLLM 运行时层负责实际执行模型的加载和推理操作。\n\n#### LLM Server\n\n`llm/server.go` 实现了 LLM 服务的核心逻辑，包括：\n\n- 模型加载与初始化\n- 推理请求处理\n- 会话状态管理\n- 分词(Tokenization)处理\n\n```go\ntype LLMServer struct {\n model *llama.Model\n params *llama.InferenceParams\n session *Session\n}\n```\n\n资料来源：[llm/server.go](https://github.com/ollama/ollama/blob/main/llm/server.go)\n\n#### 分词器\n\nOllama 集成 llama.cpp 的分词器实现，支持 UTF-8 编码的文本处理。分词器将输入文本转换为 token 序列，供模型处理。\n\n```cpp\nuint32_t unicode_cpt_from_utf8(const std::string & utf8, size_t & offset) {\n // UTF-8 解码实现\n}\n```\n\n资料来源：[llama/llama.cpp/src/unicode.cpp](https://github.com/ollama/ollama/blob/main/llama/llama.cpp/src/unicode.cpp)\n\n### 后端加速层\n\nOllama 基于 GGML (General Graphical Model Library) 实现模型推理，支持多种硬件加速后端。\n\n#### GGML 后端支持\n\n| 后端 | 宏定义 | 适用场景 |\n|------|--------|----------|\n| CUDA | `GGML_USE_CUDA` | NVIDIA GPU |\n| Metal | `GGML_USE_METAL` | Apple Silicon |\n| Vulkan | `GGML_USE_VULKAN` | 跨平台 GPU |\n| SYCL | `GGML_USE_SYCL` | Intel GPU |\n| WebGPU | `GGML_USE_WEBGPU` | 浏览器环境 |\n| OpenCL | `GGML_USE_OPENCL` | 通用 GPU |\n| Hexagon | `GGML_USE_HEXAGON` | Qualcomm DSP |\n| BLAS | `GGML_USE_BLAS` | CPU 矩阵运算 |\n| CANN | `GGML_USE_CANN` | 华为昇腾 |\n\n```cpp\n#ifdef GGML_USE_CUDA\n#include \"ggml-cuda.h\"\n#endif\n\n#ifdef GGML_USE_METAL\n#include \"ggml-metal.h\"\n#endif\n\n#ifdef GGML_USE_VULKAN\n#include \"ggml-vulkan.h\"\n#endif\n```\n\n资料来源：[ml/backend/ggml/ggml/src/ggml-backend-reg.cpp](https://github.com/ollama/ollama/blob/main/ml/backend/ggml/ggml/src/ggml-backend-reg.cpp)\n\n#### 量化支持\n\nOllama 支持多种量化格式以降低显存占用：\n\n| 量化类型 | 标识 | 说明 |\n|---------|------|------|\n| Q4_0 | 4位量化 | 基础量化 |\n| Q4_1 | 4位量化 | 改进精度 |\n| Q5_0 | 5位量化 | 更高精度 |\n| Q5_1 | 5位量化 | 最佳5位 |\n| Q8_0 | 8位量化 | 接近FP16 |\n| Q2_K | 2位K量化 | 极致压缩 |\n| Q3_K | 3位K量化 | 高压缩 |\n| Q4_K | 4位K量化 | 推荐使用 |\n| Q5_K | 5位K量化 | 高精度压缩 |\n| Q6_K | 6位K量化 | 最高精度压缩 |\n\n资料来源：[ml/backend/ggml/ggml/src/ggml-vulkan/vulkan-shaders/vulkan-shaders-gen.cpp](https://github.com/ollama/ollama/blob/main/ml/backend/ggml/ggml/src/ggml-vulkan/vulkan-shaders/vulkan-shaders-gen.cpp)\n\n### GPU 发现层\n\nGPU 发现模块负责检测系统中的可用计算设备，为后端选择提供依据。\n\n#### 设备检测逻辑\n\n```go\nfunc DetectGPU() (GPUInfo, error) {\n // 检测 CUDA 设备\n if cudaAvailable := checkCUDA(); cudaAvailable {\n return GPUInfo{Type: \"cuda\", Count: getCUDACount()}, nil\n }\n // 检测 Metal 设备\n if metalAvailable := checkMetal(); metalAvailable {\n return GPUInfo{Type: \"metal\", Count: getMetalCount()}, nil\n }\n // 回退到 CPU\n return GPUInfo{Type: \"cpu\"}, nil\n}\n```\n\n资料来源：[discover/gpu.go](https://github.com/ollama/ollama/blob/main/discover/gpu.go)\n\n## 数据流\n\n### 推理请求处理流程\n\n```mermaid\nsequenceDiagram\n participant Client as 客户端\n participant API as API 层\n participant Route as 路由层\n participant Sched as 调度器\n participant LLM as LLM Server\n participant Backend as GGML 后端\n \n Client->>API: POST /api/chat\n API->>Route: 解析请求\n Route->>Sched: 调度请求\n Sched->>LLM: 获取/创建实例\n LLM->>Backend: 加载模型\n Backend->>Backend: 执行推理\n LLM->>LLM: 处理响应\n Sched-->>Route: 返回结果\n Route-->>API: 流式/完整响应\n API-->>Client: 返回结果\n```\n\n### 模型下载与注册流程\n\n```mermaid\ngraph LR\n A[请求下载模型] --> B[查询注册表]\n B --> C{Haven 模型?}\n C -->|是| D[直接下载]\n C -->|否| E[解析 Manifest]\n E --> F[下载 Manifest]\n F --> G[检查 Layer]\n G --> H[下载 Chunk]\n H --> I[验证校验和]\n I --> J{所有 Chunk 完成?}\n J -->|否| G\n J -->|是| K[组装模型文件]\n K --> L[注册到本地]\n```\n\n资料来源：[server/internal/client/ollama/registry.go](https://github.com/ollama/ollama/blob/main/server/internal/client/ollama/registry.go)\n\n## API 客户端集成\n\nOllama 提供多语言客户端 SDK，客户端层负责协议封装和请求发送。\n\n### Go 客户端\n\n```go\nimport \"github.com/ollama/ollama/api\"\n\nclient := api.Client{Endpoint: \"http://localhost:11434\"}\nresp, err := client.Chat(context.Background(), &api.ChatRequest{\n Model: \"gemma3\",\n Messages: []api.Message{{Role: \"user\", Content: \"你好\"}},\n})\n```\n\n资料来源：[api/client.go](https://github.com/ollama/ollama/blob/main/api/client.go)\n\n### Python 客户端\n\n```python\nfrom ollama import chat\n\nresponse = chat(model='gemma3', messages=[\n {'role': 'user', 'content': 'Why is the sky blue?'},\n])\nprint(response.message.content)\n```\n\n### JavaScript 客户端\n\n```javascript\nimport ollama from \"ollama\";\n\nconst response = await ollama.chat({\n model: \"gemma3\",\n messages: [{ role: \"user\", content: \"Why is the sky blue?\" }],\n});\n```\n\n## 内存映射\n\nOllama 使用内存映射 (Memory Mapping) 技术加载模型文件，以提高加载速度和内存利用效率。\n\n### 跨平台实现\n\n```cpp\n#if defined(_POSIX_MAPPED_FILES)\n#include \n#include \n#endif\n\n#if defined(_WIN32)\n#include \n#endif\n```\n\n资料来源：[llama/llama.cpp/src/llama-mmap.cpp](https://github.com/ollama/ollama/blob/main/llama/llama.cpp/src/llama-mmap.cpp)\n\n## 配置与部署\n\n### 模型存储位置\n\nOllama 默认将模型存储在配置目录中，可通过设置界面或环境变量修改：\n\n| 配置项 | 说明 | 默认值 |\n|-------|------|--------|\n| `OLLAMA_MODELS` | 模型存储目录 | `~/.ollama/models` |\n| `OLLAMA_HOST` | 服务监听地址 | `127.0.0.1:11434` |\n| `OLLAMA_KEEP_ALIVE` | 模型保持加载时间 | `5m` |\n\n### 开发模式\n\n桌面应用支持开发模式以便于调试：\n\n```bash\nOLLAMA_DEBUG=1 go run ./cmd/app -dev\n```\n\n开发模式特性：\n- 从 Vite 开发服务器加载 UI\n- 启用 CORS 跨域支持\n- 固定 API 端口 `127.0.0.1:3001`\n- 支持热重载\n\n资料来源：[app/README.md](https://github.com/ollama/ollama/blob/main/app/README.md)\n\n## 性能基准测试\n\nOllama 提供性能测试工具 `ollama-bench` 用于评估模型在不同配置下的表现。\n\n### 命令行选项\n\n| 选项 | 说明 | 默认值 |\n|------|------|--------|\n| `-model` | 测试的模型名称 | 必填 |\n| `-epochs` | 迭代次数 | 6 |\n| `-max-tokens` | 最大输出 token 数 | 200 |\n| `-temperature` | 采样温度 | 0.0 |\n| `-seed` | 随机种子 | 随机 |\n| `-format` | 输出格式 (csv/json) | text |\n\n### 使用示例\n\n```bash\n./ollama-bench -model gemma3 -epochs 10 -temperature 0.7 -seed 42\n```\n\n资料来源：[cmd/bench/README.md](https://github.com/ollama/ollama/blob/main/cmd/bench/README.md)\n\n---\n\n\n\n## API 参考\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [高级功能](#page-advanced-features)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [api/types.go](https://github.com/ollama/ollama/blob/main/api/types.go)\n- [api/client.go](https://github.com/ollama/ollama/blob/main/api/client.go)\n- [server/routes.go](https://github.com/ollama/ollama/blob/main/server/routes.go)\n- [server/images.go](https://github.com/ollama/ollama/blob/main/server/images.go)\n- [server/create.go](https://github.com/ollama/ollama/blob/main/server/create.go)\n- [openai/openai.go](https://github.com/ollama/ollama/blob/main/openai/openai.go)\n- [docs/api.md](https://github.com/ollama/ollama/blob/main/docs/api.md)\n \n\n# API 参考\n\nOllama 提供了一套完整的 REST API，用于运行和管理本地大语言模型。本文档详细描述所有 API 端点的使用方法、请求参数和响应格式。\n\n## 概述\n\nOllama API 服务默认运行在 `http://localhost:11434`，提供两种 API 兼容模式：\n\n- **原生 Ollama API**：Ollama 原生的聊天和生成接口\n- **OpenAI 兼容 API**：兼容 OpenAI Chat Completions 格式的接口\n- **Anthropic 兼容 API**：兼容 Anthropic Messages 格式的接口\n\n```mermaid\ngraph TB\n subgraph \"客户端\"\n A[curl / HTTP 客户端]\n B[Python SDK]\n C[JavaScript SDK]\n end\n \n subgraph \"API 层\"\n D[原生 API /api/*]\n E[OpenAI 兼容 /v1/*]\n F[Anthropic 兼容 /v1/*]\n end\n \n subgraph \"服务层\"\n G[Server Handler]\n H[ollama.Client]\n end\n \n subgraph \"后端\"\n I[LLM Runner]\n J[Model Registry]\n end\n \n A --> D\n B --> D\n C --> D\n A --> E\n C --> F\n D --> G\n E --> G\n F --> G\n G --> H\n H --> I\n H --> J\n```\n\n资料来源：[server/routes.go:1-50](https://github.com/ollama/ollama/blob/main/server/routes.go)\n\n## 基础配置\n\n### CORS 配置\n\nAPI 支持跨域请求，允许以下来源访问：\n\n| 配置项 | 说明 | 默认值 |\n|--------|------|--------|\n| `OLLAMA_ORIGINS` | 允许的来源列表 | `*` (允许所有) |\n\nCORS 配置支持通配符和浏览器扩展：\n\n```go\ncorsConfig := cors.DefaultConfig()\ncorsConfig.AllowWildcard = true\ncorsConfig.AllowBrowserExtensions = true\n```\n\n资料来源：[server/routes.go:150-180](https://github.com/ollama/ollama/blob/main/server/routes.go)\n\n### 请求头\n\n所有 API 请求支持以下通用请求头：\n\n| 请求头 | 说明 |\n|--------|------|\n| `Content-Type` | 内容类型，通常为 `application/json` |\n| `Authorization` | 认证令牌（如需要） |\n| `User-Agent` | 用户代理标识 |\n| `Accept` | 接受的响应格式 |\n\nOpenAI 兼容性请求头也被支持：\n\n```go\n\"OpenAI-Beta\",\n\"x-stainless-arch\",\n\"x-stainless-async\",\n\"x-stainless-runtime\",\n\"x-stainless-runtime-version\",\n```\n\n资料来源：[server/routes.go:160-175](https://github.com/ollama/ollama/blob/main/server/routes.go)\n\n## 核心 API 端点\n\n### 健康检查\n\n#### GET /\n\n检查 Ollama 服务状态。\n\n**响应示例：**\n\n```json\n{\n \"version\": \"0.5.0\"\n}\n```\n\n### 模型操作\n\n#### POST /api/create\n\n从 GGUF 文件创建模型。\n\n**请求体：**\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| `name` | string | 是 | 模型名称 |\n| `modelfile` | string | 否 | Modelfile 内容 |\n| `quantize` | string | 否 | 量化级别 |\n| `stream` | boolean | 否 | 是否流式响应 |\n\n**请求示例：**\n\n```json\n{\n \"name\": \"my-custom-model\",\n \"modelfile\": \"FROM ./model.bin\\nPARAMETER temperature 0.7\",\n \"stream\": true\n}\n```\n\n资料来源：[server/create.go:1-50](https://github.com/ollama/ollama/blob/main/server/create.go)\n\n#### DELETE /api/delete\n\n删除模型。\n\n**请求体：**\n\n```json\n{\n \"name\": \"llama3:latest\"\n}\n```\n\n#### POST /api/show\n\n显示模型详细信息。\n\n**请求体：**\n\n```json\n{\n \"name\": \"llama3:latest\"\n}\n```\n\n**响应示例：**\n\n```json\n{\n \"modelfile\": \"FROM llama3\\nPARAMETER temperature 0.8\",\n \"parameters\": \"temperature: 0.8\\nnum_keep: 0\",\n \"template\": \"{{ .Prompt }}\",\n \"details\": {\n \"parent_model\": \"\",\n \"format\": \"gguf\",\n \"family\": \"llama\",\n \"families\": [\"llama\"],\n \"parameter_size\": \"8B\",\n \"quantization_level\": \"Q4_0\"\n }\n}\n```\n\n### 模型列表\n\n#### GET /api/tags\n\n获取本地已安装的模型列表。\n\n**查询参数：**\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `name` | string | 过滤特定命名空间下的模型 |\n\n**响应示例：**\n\n```json\n{\n \"models\": [\n {\n \"name\": \"llama3:latest\",\n \"modified_at\": \"2025-01-15T10:30:00Z\",\n \"size\": 3826790912,\n \"digest\": \"sha256:8e710c2b...\"\n }\n ]\n}\n```\n\n资料来源：[server/images.go:1-100](https://github.com/ollama/ollama/blob/main/server/images.go)\n\n### 聊天接口\n\n#### POST /api/chat\n\n发送聊天消息并获取响应。\n\n**请求体：**\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| `model` | string | 是 | 模型名称 |\n| `messages` | array | 是 | 消息数组 |\n| `stream` | boolean | 否 | 流式响应，默认 true |\n| `format` | string | 否 | 响应格式 (json) |\n| `options` | object | 否 | 模型选项 |\n| `keep_alive` | duration | 否 | 模型保持加载时间 |\n\n**消息对象结构：**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `role` | string | 角色：`user`、`assistant`、`system`、`tool` |\n| `content` | string | 消息内容 |\n| `images` | array | 图片数据（用于多模态模型） |\n| `tool_calls` | array | 工具调用 |\n| `tool_call_id` | string | 工具调用 ID |\n| `name` | string | 发送者名称 |\n\n**请求示例：**\n\n```bash\ncurl http://localhost:11434/api/chat -d '{\n \"model\": \"gemma3\",\n \"messages\": [\n {\n \"role\": \"user\",\n \"content\": \"Why is the sky blue?\"\n }\n ],\n \"stream\": false\n}'\n```\n\n**响应示例：**\n\n```json\n{\n \"model\": \"gemma3\",\n \"created_at\": \"2025-01-15T10:30:00Z\",\n \"message\": {\n \"role\": \"assistant\",\n \"content\": \"The sky appears blue because...\"\n },\n \"done\": true,\n \"total_duration\": 5000000000,\n \"load_duration\": 1000000000,\n \"prompt_eval_count\": 10,\n \"eval_count\": 50\n}\n```\n\n**流式响应：**\n\n```json\n{\n \"model\": \"gemma3\",\n \"created_at\": \"2025-01-15T10:30:00Z\",\n \"message\": {\n \"role\": \"assistant\",\n \"content\": \"The\"\n },\n \"done\": false\n}\n```\n\n资料来源：[api/types.go:1-100](https://github.com/ollama/ollama/blob/main/api/types.go)\n\n### 生成接口\n\n#### POST /api/generate\n\n基于提示词生成文本。\n\n**请求体：**\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| `model` | string | 是 | 模型名称 |\n| `prompt` | string | 是 | 输入提示词 |\n| `system` | string | 否 | 系统提示词 |\n| `template` | string | 否 | 自定义模板 |\n| `context` | array | 否 | 上下文（对话历史） |\n| `stream` | boolean | 否 | 流式响应，默认 true |\n| `options` | object | 否 | 模型选项 |\n| `format` | string | 否 | 响应格式 |\n\n**模型选项 (options)：**\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `temperature` | float | 采样温度，0-2 之间 |\n| `seed` | int | 随机种子 |\n| `num_predict` | int | 最大生成 token 数 |\n| `top_k` | int | Top-K 采样 |\n| `top_p` | float | Top-P 采样 |\n| `num_ctx` | int | 上下文窗口大小 |\n| `repeat_last_n` | int | 重复惩罚 |\n| `repeat_penalty` | float | 重复惩罚因子 |\n\n**响应示例：**\n\n```json\n{\n \"model\": \"llama3\",\n \"response\": \"Generated text...\",\n \"done\": true,\n \"context\": [1, 2, 3, ...],\n \"total_duration\": 5000000000,\n \"load_duration\": 1000000000,\n \"prompt_eval_count\": 10,\n \"eval_count\": 50,\n \"eval_duration\": 4000000000\n}\n```\n\n资料来源：[api/types.go:100-200](https://github.com/ollama/ollama/blob/main/api/types.go)\n\n### 模型推送与拉取\n\n#### POST /api/pull\n\n从远程仓库拉取模型。\n\n**请求体：**\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| `name` | string | 是 | 模型名称 |\n| `insecure` | boolean | 否 | 允许不安全连接 |\n| `stream` | boolean | 否 | 流式进度 |\n\n**流式进度响应：**\n\n```json\n{\n \"status\": \"pulling manifest\",\n \"digest\": \"sha256:...\",\n \"total\": 3826790912\n}\n```\n\n```json\n{\n \"status\": \"downloading\",\n \"digest\": \"sha256:...\",\n \"total\": 3826790912,\n \"completed\": 1000000000\n}\n```\n\n#### POST /api/push\n\n推送模型到远程仓库。\n\n**请求体：**\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| `name` | string | 是 | 模型名称 |\n| `insecure` | boolean | 否 | 允许不安全连接 |\n| `stream` | boolean | 否 | 流式进度 |\n\n#### POST /api/copy\n\n复制模型。\n\n**请求体：**\n\n```json\n{\n \"source\": \"llama3:latest\",\n \"destination\": \"my-llama3\"\n}\n```\n\n### 运行状态\n\n#### GET /api/ps\n\n获取当前运行的模型状态。\n\n**响应示例：**\n\n```json\n{\n \"models\": [\n {\n \"name\": \"llama3:latest\",\n \"model\": \"llama3\",\n \"size\": 3826790912,\n \"digest\": \"sha256:8e710c2b...\",\n \"expires_at\": \"2025-01-15T11:00:00Z\",\n \"size_vram\": 3826790912\n }\n ]\n}\n```\n\n### 嵌入生成\n\n#### POST /api/embeddings\n\n生成文本嵌入向量。\n\n**请求体：**\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| `model` | string | 是 | 模型名称 |\n| `prompt` | string | 是 | 输入文本 |\n\n**响应示例：**\n\n```json\n{\n \"model\": \"llama3\",\n \"embeddings\": [[0.123, -0.456, 0.789, ...]]\n}\n```\n\n## OpenAI 兼容 API\n\nOllama 提供与 OpenAI API 兼容的端点，方便使用现有的 OpenAI SDK。\n\n### 聊天补全\n\n#### POST /v1/chat/completions\n\nOpenAI 兼容的聊天补全接口。\n\n**请求示例：**\n\n```bash\ncurl http://localhost:11434/v1/chat/completions \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"model\": \"gemma3\",\n \"messages\": [\n {\"role\": \"user\", \"content\": \"Hello!\"}\n ]\n }'\n```\n\n**请求参数：**\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `model` | string | 模型名称 |\n| `messages` | array | 消息数组 |\n| `temperature` | float | 采样温度 |\n| `max_tokens` | int | 最大 token 数 |\n| `stream` | boolean | 流式响应 |\n| `stop` | array/string | 停止词 |\n| `tools` | array | 可用工具 |\n| `tool_choice` | object | 工具选择策略 |\n\n**响应格式：**\n\n```json\n{\n \"id\": \"chatcmpl-xxx\",\n \"object\": \"chat.completion\",\n \"created\": 1705310400,\n \"model\": \"gemma3\",\n \"choices\": [\n {\n \"index\": 0,\n \"message\": {\n \"role\": \"assistant\",\n \"content\": \"Hello! How can I help you?\"\n },\n \"finish_reason\": \"stop\"\n }\n ],\n \"usage\": {\n \"prompt_tokens\": 10,\n \"completion_tokens\": 20,\n \"total_tokens\": 30\n }\n}\n```\n\n资料来源：[openai/openai.go:1-100](https://github.com/ollama/ollama/blob/main/openai/openai.go)\n\n### 模型列表\n\n#### GET /v1/models\n\n获取可用模型列表。\n\n**响应示例：**\n\n```json\n{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"llama3:latest\",\n \"object\": \"model\",\n \"created\": 1705310400,\n \"owned_by\": \"ollama\"\n }\n ]\n}\n```\n\n### 嵌入生成\n\n#### POST /v1/embeddings\n\nOpenAI 兼容的嵌入接口。\n\n**请求示例：**\n\n```bash\ncurl http://localhost:11434/v1/embeddings \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"model\": \"llama3\",\n \"input\": \"The quick brown fox\"\n }'\n```\n\n## Anthropic 兼容 API\n\nOllama 提供与 Anthropic Claude API 兼容的接口。\n\n### 消息接口\n\n#### POST /v1/messages\n\nAnthropic 兼容的消息接口。\n\n**请求示例：**\n\n```bash\ncurl http://localhost:11434/v1/messages \\\n -H \"Content-Type: application/json\" \\\n -H \"x-api-key: any-string\" \\\n -H \"anthropic-version: 2023-06-01\" \\\n -d '{\n \"model\": \"claude-3\",\n \"messages\": [\n {\"role\": \"user\", \"content\": \"Hello!\"}\n ],\n \"max_tokens\": 1024\n }'\n```\n\n**请求参数：**\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `model` | string | 模型名称 |\n| `messages` | array | 消息数组 |\n| `system` | string | 系统提示词 |\n| `max_tokens` | int | 最大生成 token 数 |\n| `temperature` | float | 采样温度 |\n| `stream` | boolean | 流式响应 |\n| `tools` | array | 工具定义 |\n\n资料来源：[docs/api.md:1-150](https://github.com/ollama/ollama/blob/main/docs/api.md)\n\n## 工具调用 (Function Calling)\n\n### 工具定义\n\n```json\n{\n \"tools\": [\n {\n \"type\": \"function\",\n \"function\": {\n \"name\": \"get_weather\",\n \"description\": \"获取指定城市的天气信息\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"city\": {\n \"type\": \"string\",\n \"description\": \"城市名称\"\n }\n },\n \"required\": [\"city\"]\n }\n }\n }\n ]\n}\n```\n\n### 工具调用响应\n\n```json\n{\n \"message\": {\n \"role\": \"assistant\",\n \"content\": \"\",\n \"tool_calls\": [\n {\n \"id\": \"call_123\",\n \"type\": \"function\",\n \"function\": {\n \"name\": \"get_weather\",\n \"arguments\": \"{\\\"city\\\": \\\"Beijing\\\"}\"\n }\n }\n ]\n }\n}\n```\n\n### 工具结果反馈\n\n```json\n{\n \"role\": \"tool\",\n \"content\": \"{\\\"temperature\\\": \\\"22°C\\\", \\\"condition\\\": \\\"Sunny\\\"}\",\n \"tool_call_id\": \"call_123\"\n}\n```\n\n## SDK 客户端\n\n### Python SDK\n\n```bash\npip install ollama\n```\n\n```python\nfrom ollama import chat\n\nresponse = chat(model='gemma3', messages=[\n {\n 'role': 'user',\n 'content': 'Why is the sky blue?',\n },\n])\nprint(response.message.content)\n```\n\n### JavaScript SDK\n\n```bash\nnpm i ollama\n```\n\n```javascript\nimport { ollama } from \"ollama\";\n\nconst response = await ollama.chat({\n model: \"gemma3\",\n messages: [{ role: \"user\", content: \"Why is the sky blue?\" }],\n});\nconsole.log(response.message.content);\n```\n\n### Go 客户端\n\n```go\nimport \"github.com/ollama/ollama/api\"\n\nclient, _ := api.ClientFromEnvironment()\nchat, _ := client.Chat(ctx, &api.ChatRequest{\n Model: \"llama3\",\n Messages: []api.Message{\n {Role: \"user\", Content: \"Why is the sky blue?\"},\n },\n})\nfmt.Println(chat.Message.Content)\n```\n\n## 错误处理\n\n### 错误响应格式\n\n所有错误返回标准 JSON 格式：\n\n```json\n{\n \"error\": {\n \"code\": \"invalid_request\",\n \"message\": \"详细错误信息\",\n \"param\": \"参数名称\"\n }\n}\n```\n\n### HTTP 状态码\n\n| 状态码 | 说明 |\n|--------|------|\n| 200 | 请求成功 |\n| 400 | 请求参数错误 |\n| 404 | 资源不存在 |\n| 500 | 服务器内部错误 |\n| 503 | 服务不可用（模型加载中） |\n\n## 配置参数\n\n### 环境变量\n\n| 变量 | 说明 | 默认值 |\n|------|------|--------|\n| `OLLAMA_HOST` | 服务监听地址 | `127.0.0.1:11434` |\n| `OLLAMA_MODELS` | 模型存储目录 | `~/.ollama/models` |\n| `OLLAMA_ORIGINS` | 允许的 CORS 来源 | `*` |\n| `OLLAMA_KEEP_ALIVE` | 模型保持时间 | `5m` |\n\n### 运行时配置\n\n模型运行时可以通过 `options` 参数配置：\n\n```json\n{\n \"model\": \"llama3\",\n \"options\": {\n \"temperature\": 0.7,\n \"top_p\": 0.9,\n \"num_ctx\": 4096,\n \"seed\": 42\n }\n}\n```\n\n## 请求/响应流程\n\n```mermaid\nsequenceDiagram\n participant Client\n participant API as API Server\n participant Registry as Model Registry\n participant Runner as LLM Runner\n \n Client->>API: POST /api/chat\n API->>Registry: 查找模型\n Registry-->>API: 模型路径\n API->>Runner: 加载模型\n Runner-->>API: 模型已加载\n \n loop 流式生成\n API->>Runner: 处理 token\n Runner-->>API: 生成 token\n API-->>Client: SSE 事件\n end\n \n Runner-->>API: 完成\n API-->>Client: 最终响应\n```\n\n## 性能指标\n\nAPI 响应包含以下性能指标：\n\n| 字段 | 说明 |\n|------|------|\n| `total_duration` | 总请求耗时（纳秒） |\n| `load_duration` | 模型加载耗时（纳秒） |\n| `prompt_eval_count` | 提示词 token 数 |\n| `prompt_eval_duration` | 提示词处理耗时（纳秒） |\n| `eval_count` | 生成 token 数 |\n| `eval_duration` | 生成耗时（纳秒） |\n\n## 最佳实践\n\n### 1. 流式响应\n\n对于交互式应用，使用流式响应可以提供更好的用户体验：\n\n```bash\ncurl -X POST http://localhost:11434/api/chat \\\n -d '{\"model\": \"llama3\", \"messages\": [{\"role\": \"user\", \"content\": \"Hello\"}], \"stream\": true}'\n```\n\n### 2. 连接复用\n\n使用 HTTP keep-alive 减少连接开销：\n\n```python\nimport ollama\n\nclient = ollama.Client()\n# 多个请求复用同一连接\nfor msg in conversation:\n response = client.chat(model='llama3', messages=conversation)\n```\n\n### 3. 模型预热\n\n首次请求会有模型加载延迟，可以预先触发：\n\n```bash\ncurl -X POST http://localhost:11434/api/generate \\\n -d '{\"model\": \"llama3\", \"prompt\": \"warmup\", \"stream\": false}'\n```\n\n### 4. 上下文管理\n\n合理管理上下文长度以优化性能：\n\n```json\n{\n \"model\": \"llama3\",\n \"options\": {\n \"num_ctx\": 2048\n }\n}\n```\n\n## 相关文档\n\n- [快速开始指南](https://docs.ollama.com/quickstart)\n- [API 完整文档](https://docs.ollama.com/api)\n- [OpenAPI 规范](./openapi.yaml)\n- [模型库](https://ollama.com/library)\n\n---\n\n\n\n## 模型管理\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [模型转换系统](#page-model-conversion), [LLM 后端系统](#page-llm-backend)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [server/images.go](https://github.com/ollama/ollama/blob/main/server/images.go)\n- [server/model.go](https://github.com/ollama/ollama/blob/main/server/model.go)\n- [server/model_resolver.go](https://github.com/ollama/ollama/blob/main/server/model_resolver.go)\n- [server/model_recommendations.go](https://github.com/ollama/ollama/blob/main/server/model_recommendations.go)\n- [server/model_caches.go](https://github.com/ollama/ollama/blob/main/server/model_caches.go)\n- [manifest/manifest.go](https://github.com/ollama/ollama/blob/main/manifest/manifest.go)\n \n\n# 模型管理\n\nOllama 的模型管理是核心系统之一，负责模型的发现、下载、缓存、加载、版本控制和运行时管理。本页面详细介绍 Ollama 如何管理系统模型的生命周期。\n\n## 概述\n\nOllama 采用分层架构管理模型文件，核心组件包括：\n\n- **模型清单（Manifest）**：描述模型元数据、层信息和依赖关系\n- **Blob 缓存**：存储模型的离散数据块，支持去重和复用\n- **模型解析器**：解析 GGUF 格式和模型配置\n- **模型加载器**：根据运行时后端加载模型进行推理\n\n```mermaid\ngraph TD\n A[用户请求] --> B{模型是否存在?}\n B -->|否| C[下载模型清单]\n C --> D[解析 Manifest]\n D --> E[检查 Blob 缓存]\n E --> F{缺失 Blob?}\n F -->|是| G[下载缺失层]\n F -->|否| H[加载模型]\n G --> H\n H --> I[初始化推理后端]\n I --> J[返回模型实例]\n```\n\n## 模型清单（Manifest）\n\n模型清单是描述模型结构的核心数据结构，包含模型的完整元信息。\n\n### Manifest 结构\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `Model` | string | 模型名称 |\n| `ModelURL` | string | 模型源 URL |\n| `Architectures` | []string | 支持的模型架构 |\n| `AdapterPath` | string | 适配器路径 |\n| `Capabilities` | []string | 模型能力列表 |\n| `Migrations` | map[string]string | 迁移映射 |\n\n资料来源：[manifest/manifest.go:1-50](https://github.com/ollama/ollama/blob/main/manifest/manifest.go)\n\n### Manifest 层结构\n\n每个模型由多个层（Layer）组成，层是最小下载和缓存单元：\n\n```go\ntype ManifestLayer struct {\n Digest string // SHA256 哈希\n Size int64 // 层大小\n From *string // 来源模型\n MediaType string // MIME 类型\n Zdigest string // 压缩后哈希\n Zsize int64 // 压缩后大小\n}\n```\n\n资料来源：[manifest/manifest.go:51-80](https://github.com/ollama/ollama/blob/main/manifest/manifest.go)\n\n## Blob 缓存系统\n\nOllama 使用基于内容寻址的 Blob 缓存系统，所有模型数据以 SHA256 哈希作为唯一标识存储。\n\n### Blob 缓存策略\n\n```go\n// Blobs newer than this may belong to another process that has not written its\n// manifest yet. They become eligible for the normal mark-and-sweep pass later.\nconst layerPruneGracePeriod = time.Hour\n```\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `layerPruneGracePeriod` | 1小时 | Blob 清理宽限期 |\n\n资料来源：[server/images.go:29-33](https://github.com/ollama/ollama/blob/main/server/images.go)\n\n### Blob 生命周期\n\n```mermaid\nstateDiagram-v2\n [*] --> Downloaded: 下载完成\n Downloaded --> Cached: 写入 Blob 目录\n Cached --> InUse: 模型加载\n InUse --> Cached: 模型卸载\n Cached --> Pruned: 超过宽限期且未被引用\n Pruned --> [*]: 删除文件\n```\n\n## 模型能力（Capabilities）\n\nOllama 支持检测和管理模型的多种能力，确保模型与请求功能匹配。\n\n### 能力类型定义\n\n| 能力标识 | 说明 | 错误类型 |\n|----------|------|----------|\n| `completion` | 文本补全 | `errCapabilityCompletion` |\n| `tools` | 工具调用 | `errCapabilityTools` |\n| `insert` | 上下文插入 | `errCapabilityInsert` |\n| `vision` | 视觉理解 | `errCapabilityVision` |\n| `audio` | 音频处理 | `errCapabilityAudio` |\n| `embedding` | 向量嵌入 | `errCapabilityEmbedding` |\n| `thinking` | 思考模式 | `errCapabilityThinking` |\n| `image` | 图像生成 | `errCapabilityImage` |\n\n资料来源：[server/images.go:35-48](https://github.com/ollama/ollama/blob/main/server/images.go)\n\n### 能力检查流程\n\n```mermaid\ngraph LR\n A[请求] --> B{需要能力 X?}\n B -->|是| C[检查模型 Manifest]\n C --> D{模型支持 X?}\n D -->|否| E[返回 errCapabilities]\n D -->|是| F[继续处理]\n B -->|否| F\n```\n\n## 模型下载与解析\n\n### 模型解析器\n\n模型解析器负责从 GGUF 文件中提取元数据和配置信息：\n\n```go\n// Model 解析关键步骤\n1. 读取 GGUF 头部\n2. 解析元数据键值对\n3. 提取张量信息\n4. 验证架构兼容性\n```\n\n资料来源：[server/model.go:1-100](https://github.com/ollama/ollama/blob/main/server/model.go)\n\n### 模型推荐系统\n\n当模型不可用或需要优化时，系统提供模型推荐：\n\n```go\ntype ModelRecommendation struct {\n Model string // 推荐模型名称\n Reason string // 推荐原因\n Alternatives []string // 备选方案\n}\n```\n\n资料来源：[server/model_recommendations.go:1-50](https://github.com/ollama/ollama/blob/main/server/model_recommendations.go)\n\n## 模型缓存管理\n\n### 缓存结构\n\n```go\ntype ModelCache struct {\n mu sync.RWMutex\n models map[string]*ModelInstance\n maxSize int64\n currentSize int64\n}\n```\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `models` | map | 已加载模型实例 |\n| `maxSize` | int64 | 最大缓存大小 |\n| `currentSize` | int64 | 当前缓存使用量 |\n\n资料来源：[server/model_caches.go:1-60](https://github.com/ollama/ollama/blob/main/server/model_caches.go)\n\n### 缓存淘汰策略\n\n当缓存达到上限时，系统采用 LRU（最近最少使用）策略淘汰模型：\n\n```mermaid\ngraph TD\n A[加载新模型] --> B{缓存已满?}\n B -->|否| C[直接加载]\n B -->|是| D[查找 LRU 模型]\n D --> E[检查是否可以卸载]\n E -->|是| F[卸载并释放资源]\n F --> C\n E -->|否| G[等待或返回错误]\n```\n\n## 模型解析流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant S as 服务器\n participant M as Manifest\n participant B as Blob Cache\n participant R as Runner\n\n U->>S: 请求模型 \"llama3\"\n S->>M: 解析 Manifest\n M->>B: 检查 Blob 完整性\n B-->>M: Blob 状态\n M-->>S: 验证结果\n S->>R: 初始化 Runner\n R->>B: 读取模型数据\n B-->>R: 返回数据流\n R-->>S: 模型就绪\n S-->>U: 返回模型句柄\n```\n\n## 模型元数据\n\n### 模型配置结构\n\n| 字段 | 说明 |\n|------|------|\n| `ModelFamily` | 模型家族（如 llama, gemma） |\n| `ModelType` | 模型类型（chat, completion, embedding） |\n| `Template` | 提示词模板 |\n| `Parameters` | 模型参数配置 |\n| `SystemPrompt` | 系统提示词 |\n\n资料来源：[server/model.go:100-200](https://github.com/ollama/ollama/blob/main/server/model.go)\n\n## 错误处理\n\n### 常见错误类型\n\n| 错误类型 | 说明 | 处理方式 |\n|----------|------|----------|\n| `errInsecureProtocol` | 不安全的协议 | 拒绝下载 |\n| `errCapabilities` | 能力不匹配 | 返回可用能力列表 |\n| `errManifestNotFound` | 清单不存在 | 尝试重新发现 |\n| `errBlobNotFound` | Blob 缺失 | 触发重新下载 |\n\n资料来源：[server/images.go:48-60](https://github.com/ollama/ollama/blob/main/server/images.go)\n\n## 相关命令\n\n### 模型管理 CLI\n\n| 命令 | 说明 |\n|------|------|\n| `ollama list` | 列出已下载模型 |\n| `ollama pull ` | 下载模型 |\n| `ollama rm ` | 删除模型 |\n| `ollama show ` | 显示模型信息 |\n| `ollama cp ` | 复制模型 |\n\n## 总结\n\nOllama 的模型管理系统通过以下核心机制实现高效的资源利用：\n\n1. **内容寻址存储**：基于 SHA256 的 Blob 缓存消除重复数据\n2. **分层清单**：Manifest 分层支持增量更新和部分下载\n3. **能力检测**：运行时验证模型能力，确保功能匹配\n4. **智能缓存**：LRU 策略平衡内存使用和模型切换性能\n5. **错误恢复**：完善的错误处理支持自动重试和回退\n\n---\n\n\n\n## LLM 后端系统\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [模型管理](#page-model-management), [高级功能](#page-advanced-features)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [llama/llama.cpp/src/llama.go](https://github.com/ollama/ollama/blob/main/llama/llama.go)\n- [llama/llama.cpp/src/llama-kv-cache.cpp](https://github.com/ollama/ollama/blob/main/llama/llama.cpp/src/llama-kv-cache.cpp)\n- [llama/llama.cpp/src/llama-mmap.cpp](https://github.com/ollama/ollama/blob/main/llama/llama.cpp/src/llama-mmap.cpp)\n- [ml/backend/ggml/ggml/src/ggml-backend-reg.cpp](https://github.com/ollama/ollama/blob/main/ml/backend/ggml/ggml/src/ggml-backend-reg.cpp)\n- [ml/backend/ggml/ggml/src/gguf.cpp](https://github.com/ollama/ollama/blob/main/ml/backend/ggml/ggml/src/gguf.cpp)\n- [ml/backend/ggml/ggml/src/ggml-vulkan/vulkan-shaders/vulkan-shaders-gen.cpp](https://github.com/ollama/ollama/blob/main/ml/backend/ggml/ggml/src/ggml-vulkan/vulkan-shaders/vulkan-shaders-gen.cpp)\n \n\n# LLM 后端系统\n\nOllama 的 LLM 后端系统是整个项目的核心推理引擎，负责加载大语言模型、执行前向推理、管理计算资源以及协调 GPU/CPU 计算。该系统深度集成了 llama.cpp 库和 GGML（Georgi Gerganov's Machine Learning）张量库，为多种硬件平台提供统一的推理接口。\n\n## 系统架构概览\n\nLLM 后端系统采用分层架构设计，从上到下依次为：Go 语言高级接口层、CGO 桥接层、C++ 核心计算层、以及硬件抽象后端层。这种分层设计使得上层 Go 应用能够透明地调用高性能 C++ 推理代码，同时支持多种硬件加速后端。\n\n```mermaid\ngraph TD\n A[Go 应用层] --> B[CGO 接口层]\n B --> C[llama.cpp 核心层]\n C --> D[GGML 张量库]\n D --> E[硬件后端层]\n \n E --> F[GGML-CPU]\n E --> G[GGML-CUDA]\n E --> H[GGML-Metal]\n E --> I[GGML-Vulkan]\n E --> J[GGML-SYCL]\n \n K[GGUF 模型格式] --> C\n L[KV Cache 管理] --> C\n```\n\n## 核心组件\n\n### llama.go 接口层\n\n`llama/llama.go` 文件是 Ollama 提供的 Go 语言绑定，通过 CGO 技术调用底层的 C++ 代码。该文件定义了模型加载、推理执行、上下文管理等核心接口，是 Go 应用与 C++ 推理引擎之间的桥梁。\n\n文件通过以下编译指令指定编译参数和头文件路径：\n\n```go\n// #cgo CXXFLAGS: -std=c++17\n// #cgo CPPFLAGS: -I${SRCDIR}/../include\n// #cgo CPPFLAGS: -I${SRCDIR}/../../../ml/backend/ggml/ggml/include\nimport \"C\"\n```\n\n资料来源：[llama/llama.go:1-10]()\n\n### GGML 张量库\n\nGGML 是 Ollama 后端系统的核心计算库，提供了张量运算、内存管理、以及多硬件后端支持。该库采用模块化设计，通过后端注册机制支持不同的硬件加速器。\n\n#### 后端注册机制\n\nGGML 通过后端注册表管理各种硬件加速后端，系统支持的后端类型包括：\n\n| 后端类型 | 宏定义 | 描述 |\n|---------|--------|------|\n| CPU | GGML_USE_CPU | x86/ARM CPU 计算 |\n| CUDA | GGML_USE_CUDA | NVIDIA GPU 加速 |\n| Metal | GGML_USE_METAL | Apple Silicon GPU |\n| Vulkan | GGML_USE_VULKAN | 跨平台 GPU API |\n| SYCL | GGML_USE_SYCL | Intel GPU/多平台 |\n| WebGPU | GGML_USE_WEBGPU | 浏览器/跨平台 |\n| ZDNN | GGML_USE_ZDNN | IBM zSeries |\n| OpenCL | GGML_USE_OPENCL | 通用 GPU |\n| Hexagon | GGML_USE_HEXAGON | Qualcomm DSP |\n| BLAS | GGML_USE_BLAS | CPU 矩阵运算 |\n| RPC | GGML_USE_RPC | 远程过程调用 |\n| CANN | GGML_USE_CANN | 华为昇腾 NPU |\n\n资料来源：[ml/backend/ggml/ggml/src/ggml-backend-reg.cpp:1-70]()\n\n#### GGUF 模型格式\n\nGGUF（Georgi Gerganov Universal Format）是 GGML 推荐的模型存储格式，定义了一套标准的数据类型映射机制。系统支持以下数据类型：\n\n| Go/C++ 类型 | GGUF 类型枚举 |\n|-------------|--------------|\n| uint8_t | GGUF_TYPE_UINT8 |\n| int8_t | GGUF_TYPE_INT8 |\n| uint16_t | GGUF_TYPE_UINT16 |\n| int16_t | GGUF_TYPE_INT16 |\n| uint32_t | GGUF_TYPE_UINT32 |\n| int32_t | GGUF_TYPE_INT32 |\n| float | GGUF_TYPE_FLOAT32 |\n| bool | GGUF_TYPE_BOOL |\n| std::string | GGUF_TYPE_STRING |\n\n资料来源：[ml/backend/ggml/ggml/src/gguf.cpp:1-60]()\n\n### Vulkan 计算后端\n\nVulkan 后端是 Ollama 支持的重要 GPU 加速方案，通过 SPIR-V 着色器实现张量运算。该后端的着色器代码由 `vulkan-shaders-gen.cpp` 动态生成，支持多种量化精度。\n\nVulkan 后端支持的量化类型包括：\n\n| 量化类型 | 描述 |\n|---------|------|\n| f32 | 32位浮点 |\n| f16 | 16位浮点 |\n| q4_0 | 4位量化版本0 |\n| q4_1 | 4位量化版本1 |\n| q5_0/q5_1 | 5位量化 |\n| q8_0 | 8位量化 |\n| q2_k/q3_k/q4_k/q5_k/q6_k | K-量化变体 |\n| iq1_s/iq1_m | 1位智能量化 |\n| iq2_xxs/iq2_xs/iq2_s | 2位智能量化 |\n\n资料来源：[ml/backend/ggml/ggml/src/ggml-vulkan/vulkan-shaders/vulkan-shaders-gen.cpp:1-50]()\n\n## KV 缓存管理\n\nKV Cache（键值缓存）是 LLM 推理中的关键优化机制，通过缓存已计算的注意力键值对，避免重复计算历史 token 的注意力表示。\n\n### llama_kv_cache 类结构\n\nOllama 的 KV 缓存实现定义在 `llama-kv-cache.cpp` 中，提供了完整的缓存管理功能：\n\n```cpp\nllama_kv_cache::llama_kv_cache(\n const llama_model & model, // 模型引用\n ggml_type type_k, // 键的类型\n ggml_type type_v, // 值的类型\n bool v_trans, // 值转置标志\n bool offload, // 是否卸载到 GPU\n bool unified, // 统一缓存模式\n uint32_t kv_size, // 缓存大小\n uint32_t n_seq_max, // 最大序列数\n uint32_t n_pad, // 填充参数\n uint32_t n_swa, // 滑动窗口大小\n llama_swa_type swa_type, // 滑动窗口类型\n const layer_filter_cb & filter, // 层过滤器\n const layer_reuse_cb & reuse // 层重用回调\n);\n```\n\n资料来源：[llama/llama.cpp/src/llama-kv-cache.cpp:1-50]()\n\n### 缓存参数说明\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| model | llama_model& | 关联的模型对象 |\n| type_k/type_v | ggml_type | 键值张量的数据类型 |\n| v_trans | bool | 是否对 V 张量转置 |\n| offload | bool | 是否将缓存卸载到 GPU |\n| unified | bool | 统一模式（多序列共享缓存） |\n| kv_size | uint32_t | KV 缓存的槽位数量 |\n| n_seq_max | uint32_t | 同时处理的最大序列数 |\n| n_pad | uint32_t | 内存对齐填充大小 |\n\n### 缓冲区管理\n\nKV 缓存通过 `ggml_backend_buft_comparator` 比较器管理不同的缓冲区类型，确保内存分配顺序的一致性和可靠性。缓存支持动态扩展和序列级隔离，适用于多用户并发推理场景。\n\n资料来源：[llama/llama.cpp/src/llama-kv-cache.cpp:30-45]()\n\n## 内存映射管理\n\nOllama 使用内存映射（Memory Mapping）技术高效加载大型模型文件，减少内存占用并提高加载速度。`llama-mmap.cpp` 实现了跨平台的内存映射接口。\n\n### 平台特定实现\n\n| 平台 | 头文件 | 功能 |\n|------|--------|------|\n| POSIX | unistd.h, sys/mman.h, sys/resource.h | POSIX 内存映射 |\n| Windows | windows.h | Win32 文件映射 |\n| macOS | TargetConditionals.h | Apple 平台适配 |\n\n资料来源：[llama/llama.cpp/src/llama-mmap.cpp:1-40]()\n\n### 内存锁定\n\n对于需要长时间驻留内存的模型数据，系统支持内存锁定功能：\n\n```cpp\n#if defined(_POSIX_MEMLOCK_RANGE)\n #include \n#endif\n```\n\n这确保关键推理数据不会被操作系统换页到磁盘，保证推理延迟的稳定性。\n\n资料来源：[llama/llama.cpp/src/llama-mmap.cpp:15-20]()\n\n## Unicode 与文本处理\n\n推理引擎内置了完整的 Unicode 文本处理能力，支持多语言输入和 tokenization。`unicode.cpp` 实现了 UTF-8 编码的解码和编码功能。\n\n### UTF-8 长度计算\n\n```cpp\nsize_t unicode_len_utf8(char src) {\n const size_t lookup[] = { 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 2, 2, 3, 4 };\n uint8_t highbits = static_cast(src) >> 4;\n return lookup[highbits];\n}\n```\n\n该函数通过查表方式快速判断 UTF-8 字符的字节长度，支持 1-4 字节的 UTF-8 编码。\n\n资料来源：[llama/llama.cpp/src/unicode.cpp:1-35]()\n\n## 推理工作流程\n\n```mermaid\nsequenceDiagram\n participant App as Go 应用\n participant CGO as CGO 桥接层\n participant Llama as llama.cpp 核心\n participant GGML as GGML 库\n participant Backend as GPU/CPU 后端\n\n App->>CGO: 加载模型 (llama_load_model_from_file)\n CGO->>Llama: 调用 C++ 接口\n Llama->>GGML: 初始化张量\n GGML->>Backend: 选择最优后端\n Backend-->>GGML: 后端就绪\n GGML-->>Llama: 张量初始化完成\n Llama-->>CGO: 模型句柄\n CGO-->>App: 返回 Model 对象\n\n App->>CGO: 执行推理 (llama_decode/llama_tokenize)\n CGO->>Llama: 前向传播\n Llama->>GGML: 层计算\n GGML->>Backend: 硬件加速计算\n Backend-->>GGML: 计算结果\n GGML-->>Llama: 输出张量\n Llama-->>CGO: token 结果\n CGO-->>App: 推理完成\n```\n\n## 错误处理机制\n\n系统定义了统一的错误处理流程，包括跨平台错误码转换：\n\n```cpp\n#if defined(_WIN32)\nstatic std::string llama_format_win_err(DWORD err) {\n LPSTR buf;\n size_t size = FormatMessageA(\n FORMAT_MESSAGE_ALLOCATE_BUFFER | FORMAT_MESSAGE_FROM_SYSTEM | FORMAT_MESSAGE_IGNORE_INSERTS,\n NULL, err, MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT), \n (LPSTR)&buf, 0, NULL);\n if (!size) {\n return \"FormatMessageA failed\";\n }\n std::string ret(buf, size);\n LocalFree(buf);\n return ret;\n}\n#endif\n```\n\n资料来源：[llama/llama.cpp/src/llama-mmap.cpp:40-55]()\n\n## 编译配置\n\n### 交叉编译支持\n\nllama.go 提供了 Windows 平台的特殊编译配置：\n\n```go\n// #cgo windows CPPFLAGS: -D_WIN32_WINNT=0x0602\n```\n\n这确保在 Windows Vista 及以上版本使用最新的 API 特性。\n\n### C++ 标准\n\n整个后端系统要求使用 C++17 标准编译，确保现代 C++ 特性的可用性：\n\n```go\n// #cgo CXXFLAGS: -std=c++17\n```\n\n## 总结\n\nOllama 的 LLM 后端系统是一个高度模块化、高性能的推理引擎架构。通过深度集成 llama.cpp 和 GGML，它实现了：\n\n- **多后端支持**：统一接口管理 CPU、CUDA、Metal、Vulkan 等多种计算后端\n- **高效内存管理**：通过内存映射和 KV 缓存技术优化资源利用\n- **跨平台兼容**：支持 Linux、Windows、macOS 等主流操作系统\n- **灵活的量化支持**：从 fp32 到 int2 多种精度选项\n\n该架构设计使得 Ollama 能够在不同硬件环境下提供一致的推理体验，同时最大化利用硬件性能。\n\n---\n\n\n\n## 命令行系统\n\n### 相关页面\n\n相关主题：[项目概述](#page-overview), [系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [cmd/cmd.go](https://github.com/ollama/ollama/blob/main/cmd/cmd.go)\n- [cmd/interactive.go](https://github.com/ollama/ollama/blob/main/cmd/interactive.go)\n- [cmd/config/config.go](https://github.com/ollama/ollama/blob/main/cmd/config/config.go)\n- [cmd/launch/launch.go](https://github.com/ollama/ollama/blob/main/cmd/launch/launch.go)\n- [cmd/tui/tui.go](https://github.com/ollama/ollama/blob/main/cmd/tui/tui.go)\n- [cmd/start.go](https://github.com/ollama/ollama/blob/main/cmd/start.go)\n \n\n# 命令行系统\n\n## 概述\n\nOllama 的命令行系统是用户与本地大语言模型交互的核心接口，提供模型管理、推理执行、配置管理等完整功能。该系统基于 Go 语言构建，采用模块化架构设计，通过 `cobra` 命令行框架实现层次化的命令结构。\n\n命令行系统的主要职责包括：接收用户输入的命令、解析参数、执行相应的业务逻辑、格式化输出结果。整个系统遵循单一入口原则，通过 `cmd/cmd.go` 中的根命令统一调度所有子命令。\n\n## 架构设计\n\n### 整体架构图\n\n```mermaid\ngraph TD\n A[命令行入口] --> B[根命令 RootCmd]\n B --> C[run 子命令]\n B --> D[serve 子命令]\n B --> E[pull 子命令]\n B --> F[push 子命令]\n B --> G[list 子命令]\n B --> H[show 子命令]\n B --> I[create 子命令]\n B --> J[ps 子命令]\n B --> K[stop 子命令]\n B --> L[rm 子命令]\n B --> M[copy 子命令]\n \n C --> N[启动推理服务]\n D --> O[后台服务模式]\n \n N --> P[TUI 交互界面]\n O --> Q[HTTP API 服务]\n \n P --> R[交互式输入处理]\n R --> S[流式响应渲染]\n S --> T[Unicode 文本处理]\n```\n\n### 核心模块说明\n\n| 模块路径 | 功能说明 | 依赖关系 |\n|---------|---------|---------|\n| `cmd/cmd.go` | 根命令定义与命令注册 | 依赖 cobra 框架 |\n| `cmd/start.go` | 应用启动入口与初始化 | 依赖 config、launch |\n| `cmd/interactive.go` | 交互式对话处理逻辑 | 依赖 tui 模块 |\n| `cmd/tui/tui.go` | 终端用户界面渲染 | 独立模块 |\n| `cmd/config/config.go` | 配置管理与持久化 | 依赖文件系统 |\n| `cmd/launch/launch.go` | 服务启动与进程管理 | 依赖系统调用 |\n\n## 命令结构\n\n### 根命令设计\n\nOllama 的命令行采用树形命令结构，所有子命令都注册在根命令 `RootCmd` 下。根命令负责全局参数解析和环境变量处理，确保所有命令共享相同的配置上下文。\n\n根命令定义了以下全局标志位：\n\n| 标志位 | 类型 | 默认值 | 说明 |\n|-------|------|-------|------|\n| `--verbose` | bool | false | 启用详细输出模式 |\n| `--host` | string | 空 | 指定服务地址 |\n| `--port` | int | 11434 | 指定服务端口 |\n| `--models` | string | 用户目录 | 模型存储路径 |\n| `--keepalive` | duration | 5m | 模型加载后保留时间 |\n\n资料来源：[cmd/cmd.go:1-100]()\n\n### 子命令详解\n\n#### run 命令\n\n`run` 命令用于启动模型推理并进入交互式对话模式。这是用户最常用的命令之一，支持直接传入模型名称即可开始对话。\n\n```mermaid\ngraph LR\n A[ollama run llama3] --> B[加载模型权重]\n B --> C[初始化推理引擎]\n C --> D[启动 TUI 界面]\n D --> E[等待用户输入]\n E --> F[流式推理处理]\n F --> G[渲染响应结果]\n G --> E\n```\n\n执行流程如下：\n\n1. 解析模型名称和可选参数\n2. 调用 `launch` 模块加载模型\n3. 初始化推理上下文和令牌生成器\n4. 启动交互式 TUI 界面\n5. 处理用户输入并生成流式响应\n\n资料来源：[cmd/interactive.go:1-150]()\n\n#### serve 命令\n\n`serve` 命令将 Ollama 作为后台守护进程运行，提供 HTTP API 服务供外部调用。该模式下系统监听指定端口，响应来自客户端的推理请求。\n\n启动参数说明：\n\n| 参数 | 说明 | 默认值 |\n|-----|------|-------|\n| `--host` | 绑定地址 | 127.0.0.1 |\n| `--port` | 监听端口 | 11434 |\n| `--log` | 日志级别 | info |\n| `--background` | 是否后台运行 | false |\n\n服务启动后会创建 HTTP 服务器，注册推理、嵌入、模型管理等多个路由处理器。\n\n资料来源：[cmd/launch/launch.go:1-100]()\n\n#### 模型管理命令\n\nOllama 提供完整的模型生命周期管理命令集：\n\n| 命令 | 功能 | 示例 |\n|-----|------|-----|\n| `pull` | 下载模型 | `ollama pull llama3` |\n| `push` | 上传模型 | `ollama push user/model` |\n| `list` | 列出本地模型 | `ollama list` |\n| `show` | 显示模型信息 | `ollama show llama3` |\n| `create` | 从 Modelfile 创建 | `ollama create custom --file Modelfile` |\n| `rm` | 删除模型 | `ollama rm llama3` |\n| `copy` | 复制模型 | `ollama copy src dest` |\n| `ps` | 查看运行中的模型 | `ollama ps` |\n| `stop` | 停止模型推理 | `ollama stop llama3` |\n\n资料来源：[cmd/cmd.go:100-300]()\n\n## 配置系统\n\n### 配置存储结构\n\nOllama 采用分层配置策略，支持环境变量、配置文件、命令行标志三种配置方式。配置按优先级从低到高排列为：默认配置 < 配置文件 < 环境变量 < 命令行参数。\n\n```mermaid\ngraph TD\n A[配置加载] --> B[读取默认配置]\n B --> C[加载配置文件]\n C --> D[应用环境变量]\n D --> E[解析命令行参数]\n E --> F[最终配置合并]\n```\n\n配置文件采用 TOML 格式存储在用户配置目录：\n\n| 平台 | 配置文件路径 |\n|-----|-------------|\n| Linux | `~/.config/ollama/config.toml` |\n| macOS | `~/Library/Application Support/ollama/config.toml` |\n| Windows | `%APPDATA%\\ollama\\config.toml` |\n\n配置项包括：模型默认路径、日志级别、API 超时设置、GPU 内存限制等。\n\n资料来源：[cmd/config/config.go:1-120]()\n\n### 环境变量配置\n\nOllama 支持通过环境变量覆盖默认配置，主要环境变量列表如下：\n\n| 环境变量 | 类型 | 说明 |\n|---------|------|-----|\n| `OLLAMA_HOST` | string | 服务绑定地址 |\n| `OLLAMA_PORT` | int | 服务监听端口 |\n| `OLLAMA_MODELS` | string | 模型存储目录 |\n| `OLLAMA_KEEPALIVE` | duration | 模型保活时间 |\n| `OLLAMA_DEBUG` | bool | 调试模式开关 |\n| `OLLAMA_NOHISTORY` | bool | 禁用命令历史记录 |\n\n资料来源：[cmd/config/config.go:200-280]()\n\n## 交互式界面\n\n### TUI 组件架构\n\n交互式对话界面（Terminal User Interface）由 `cmd/tui/tui.go` 模块实现，采用分层渲染架构。界面分为输入区、输出区、状态栏三个主要区域。\n\n```mermaid\ngraph TD\n A[TUI 渲染器] --> B[Header 组件]\n A --> C[Message 组件]\n A --> D[Input 组件]\n A --> E[StatusBar 组件]\n \n B --> F[模型信息显示]\n B --> G[对话状态指示]\n \n C --> H[用户消息样式]\n C --> I[助手消息样式]\n C --> J[工具调用显示]\n \n D --> K[多行输入支持]\n D --> L[历史命令导航]\n \n E --> M[Token 计数]\n E --> N[处理状态]\n```\n\n消息组件支持多种内容类型的渲染，包括纯文本、带格式文本、代码块、工具调用结果等。对于流式输出，系统采用增量渲染策略，边接收边显示。\n\n资料来源：[cmd/tui/tui.go:1-200]()\n\n### 输入处理流程\n\n交互模式下的输入处理涉及多轮对话上下文管理和流式响应渲染。系统维护一个消息历史列表，每次交互时将用户输入追加到历史并携带完整上下文发送给推理引擎。\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant I as Input Handler\n participant M as Message Manager\n participant E as Engine\n participant R as Renderer\n \n U->>I: 输入文本\n I->>M: 添加用户消息\n M->>E: 发送带上下文的请求\n E-->>R: 流式 Token\n R->>R: 增量渲染\n E-->>M: 完成响应\n M->>M: 添加助手消息\n M->>U: 显示完整对话\n```\n\nUnicode 文本处理模块负责正确的 UTF-8 编码解码和多语言字符渲染，确保中文、日文等非 ASCII 字符的正确显示。\n\n资料来源：[cmd/interactive.go:150-300]()\n\n## 启动流程\n\n### 应用初始化序列\n\nOllama 启动时经历一系列初始化步骤，从命令行解析到服务就绪的完整流程如下：\n\n```mermaid\nflowchart TD\n A[程序入口 main] --> B[初始化日志系统]\n B --> C[加载用户配置]\n C --> D[解析命令行参数]\n D --> E{命令类型判断}\n \n E -->|run 命令| F[加载指定模型]\n E -->|serve 命令| G[初始化 HTTP 服务器]\n E -->|其他命令| H[执行对应操作]\n \n F --> I[启动 TUI 交互]\n G --> J[注册路由处理器]\n J --> K[开始监听请求]\n \n H --> L[执行完成后退出]\n I --> M[处理交互循环]\n K --> M\n```\n\n`cmd/start.go` 负责协调整个启动过程，包括信号处理、优雅关闭、超时控制等关键逻辑。系统支持通过 `SIGINT` 和 `SIGTERM` 信号优雅退出，确保正在进行的推理任务能够正常完成或保存状态。\n\n资料来源：[cmd/start.go:1-150]()\n\n### 进程生命周期管理\n\n后台服务模式下的进程管理涉及端口占用检测、进程标识持久化、配置热更新等机制。启动时系统会在配置目录创建 PID 文件记录进程 ID，便于后续管理操作。\n\n| 状态 | 说明 | 触发条件 |\n|-----|------|---------|\n| Starting | 启动中 | 进程启动 |\n| Ready | 就绪 | 服务绑定端口成功 |\n| Running | 运行中 | 处理推理请求 |\n| Stopping | 停止中 | 收到终止信号 |\n| Stopped | 已停止 | 进程退出 |\n\n资料来源：[cmd/launch/launch.go:100-250]()\n\n## 错误处理与日志\n\n### 错误分类\n\n命令行系统对错误进行了分类处理，不同类型的错误对应不同的用户提示和恢复策略：\n\n| 错误类型 | 错误码前缀 | 处理方式 | 示例 |\n|---------|----------|---------|-----|\n| 模型加载错误 | `ERR_MODEL_LOAD` | 提示检查模型文件 | 模型文件损坏 |\n| 推理错误 | `ERR_INFERENCE` | 显示错误信息 | 内存不足 |\n| 网络错误 | `ERR_NETWORK` | 建议检查服务状态 | 端口被占用 |\n| 配置错误 | `ERR_CONFIG` | 提示修正配置 | 配置文件格式错误 |\n| 权限错误 | `ERR_PERMISSION` | 提示检查权限 | 无法写入模型目录 |\n\n日志系统采用分级输出策略，可通过 `--verbose` 标志启用调试级别的日志输出。生产环境下建议使用默认的 info 级别，仅在排查问题时启用详细日志。\n\n资料来源：[cmd/cmd.go:300-400]()\n\n### 用户友好的错误提示\n\n系统尽可能将内部错误转换为用户可理解的操作建议。例如，当模型加载失败时，不仅报告失败原因，还会建议可能的解决方案如重新下载模型、检查磁盘空间等。\n\n```go\n// 错误提示示例结构\ntype UserError struct {\n Message string // 面向用户的错误描述\n Detail string // 技术细节（可选）\n Suggestion []string // 修复建议列表\n DocsURL string // 相关文档链接\n}\n```\n\n资料来源：[cmd/interactive.go:300-380]()\n\n## 扩展性与插件\n\n### 命令扩展机制\n\nOllama 预留了命令扩展接口，允许通过外部插件注册新的子命令。插件通过实现特定接口将自己注册到命令树中，无需修改核心代码即可扩展功能。\n\n扩展命令的注册流程：\n\n1. 插件加载时调用注册函数\n2. 提供命令名称、处理器函数、参数模式\n3. 系统将命令添加到根命令的子命令列表\n4. 用户即可通过标准方式调用扩展命令\n\n### 配置扩展点\n\n配置系统支持自定义配置项和配置验证器，插件可以声明自己的配置项并在配置文件中使用。配置变更支持热重载，无需重启服务即可应用新配置。\n\n## 总结\n\nOllama 的命令行系统提供了完善的模型管理和推理交互能力，通过模块化设计实现了良好的可维护性和扩展性。系统采用分层架构，将命令行解析、配置管理、用户界面、模型服务等职责分离，便于独立演进和测试。\n\n核心设计特点包括：基于 cobra 框架的命令层次结构、分层配置系统带优先级覆盖、流式响应渲染的 TUI 交互、完整的模型生命周期管理命令集、以及友好的错误提示和日志系统。这些设计使得 Ollama 既适合作为命令行工具直接使用，也为作为后台服务提供了坚实基础。\n\n---\n\n\n\n## 桌面应用程序\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [命令行系统](#page-cli-system)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [app/server/server.go](https://github.com/ollama/ollama/blob/main/app/server/server.go)\n- [app/ui/app.go](https://github.com/ollama/ollama/blob/main/app/ui/app.go)\n- [app/ui/ui.go](https://github.com/ollama/ollama/blob/main/app/ui/ui.go)\n- [app/webview/webview.go](https://github.com/ollama/ollama/blob/main/app/webview/webview.go)\n- [app/updater/updater.go](https://github.com/ollama/ollama/blob/main/app/updater/updater.go)\n- [app/tools/tools.go](https://github.com/ollama/ollama/blob/main/app/tools/tools.go)\n- [app/store/store.go](https://github.com/ollama/ollama/blob/main/app/store/store.go)\n \n\n# 桌面应用程序\n\nOllama 桌面应用程序为 macOS 和 Windows 用户提供本地化的图形界面，使其能够在本地运行和管理大型语言模型。该应用程序集成了 WebView 渲染引擎、后端服务、模型管理功能以及自动更新机制，为用户提供了开箱即用的 AI 推理体验。\n\n## 架构概述\n\nOllama 桌面应用采用分层架构设计，将用户界面、后端服务和系统级功能解耦。这种设计使得各组件可以独立开发和测试，同时保持整体系统的协调一致。\n\n```mermaid\ngraph TD\n A[用户界面层
React + TypeScript] --> B[WebView 渲染层
系统原生浏览器引擎]\n B --> C[Go 后端服务层
app/server]\n C --> D[核心推理引擎
Ollama Core]\n C --> E[模型存储
app/store]\n C --> F[自动更新
app/updater]\n C --> G[系统工具
app/tools]\n \n H[macOS/Windows
原生操作系统] --> I[系统集成
文件选择/网络配置]\n```\n\n| 层次 | 技术栈 | 职责 |\n|------|--------|------|\n| 用户界面层 | React + TypeScript + TailwindCSS | 交互式 UI 组件、消息展示、设置面板 |\n| WebView 渲染层 | 系统原生 WebView | HTML/CSS/JS 渲染、JavaScript 桥接 |\n| 后端服务层 | Go | HTTP 服务器、API 处理、系统集成 |\n| 核心推理层 | Ollama Core | 模型加载、推理执行、张量计算 |\n\n## 核心组件\n\n### 服务器模块\n\n`app/server/server.go` 实现了嵌入式 HTTP 服务器，负责处理前端请求和系统级操作。该模块提供了模型管理、对话处理、嵌入生成等核心功能的 API 端点。\n\n服务器模块的关键职责包括：\n\n- 接收并处理来自 WebView 的 HTTP 请求\n- 管理模型的生命周期（加载、卸载、切换）\n- 处理聊天完成和文本生成请求\n- 提供嵌入向量计算接口\n- 管理模型的下载进度跟踪\n\n### 用户界面模块\n\n`app/ui/app.go` 和 `app/ui/ui.go` 共同构成了应用程序的前端核心。界面采用 React 组件化架构，主要包含以下功能模块：\n\n```mermaid\ngraph LR\n A[消息组件
Message.tsx] --> B[对话界面]\n C[模型选择器
ModelPicker.tsx] --> B\n D[设置面板
Settings.tsx] --> B\n E[下载进度
Downloading.tsx] --> B\n F[错误提示
ErrorMessage.tsx] --> B\n G[思考层级
ThinkButton.tsx] --> B\n```\n\n| 组件 | 文件位置 | 功能描述 |\n|------|----------|----------|\n| Message | app/ui/app/src/components/Message.tsx | 渲染对话消息，支持工具调用结果展示 |\n| ModelPicker | app/ui/app/src/components/ModelPicker.tsx | 模型列表展示与选择 |\n| Settings | app/ui/app/src/components/Settings.tsx | 应用配置、网络设置、用户账户管理 |\n| Downloading | app/ui/app/src/components/Downloading.tsx | 模型下载进度条展示 |\n| ErrorMessage | app/ui/app/src/components/ErrorMessage.tsx | 错误信息渲染与链接支持 |\n| ThinkButton | app/ui/app/src/components/ThinkButton.tsx | 思考层级下拉选择器 |\n\n消息组件支持多种内容类型，包括普通文本、工具调用结果、Web 搜索摘要和 Web 抓取结果。当模型返回工具调用时，界面会展示工具名称、查询参数和原始 JSON 结果。资料来源：[app/ui/app/src/components/Message.tsx:Message.tsx]()\n\n### WebView 集成\n\n`app/webview/webview.go` 负责与操作系统原生 WebView 进行交互。该模块桥接了 Go 后端和前端 JavaScript 环境，使两者能够进行双向通信。\n\nWebView 的核心功能包括：\n\n- 初始化原生浏览器引擎\n- 注册 JavaScript 桥接接口\n- 处理文件选择对话框（模型目录选择）\n- 管理应用窗口生命周期\n\n资料来源：[app/webview/webview.go:webview.go]()\n\n### 自动更新模块\n\n`app/updater/updater.go` 实现了应用程序的自动更新机制。该模块会定期检查 Ollama 服务器以获取最新版本信息，并在后台下载更新包。\n\n自动更新流程采用静默下载方式，不阻塞用户当前操作。用户可以在下次启动时选择安装更新，或者通过设置面板手动触发更新检查。\n\n资料来源：[app/updater/updater.go:updater.go]()\n\n### 工具系统\n\n`app/tools/tools.go` 定义了应用程序可调用的系统工具集。这些工具扩展了 AI 模型的能力范围，使其能够执行超出纯文本生成的任务。\n\n工具系统支持的典型功能包括：\n\n- **Web 搜索工具**：允许模型发起网络搜索请求并获取结果\n- **Web 抓取工具**：获取指定 URL 的页面内容供模型分析\n- **系统集成工具**：访问本地文件系统、触发系统通知等\n\n资料来源：[app/tools/tools.go:tools.go]()\n\n### 数据存储模块\n\n`app/store/store.go` 负责管理应用程序的持久化数据。这包括用户设置、模型缓存信息、对话历史以及会话状态。\n\n存储模块采用本地文件系统存储策略，所有数据默认保存在用户主目录下的 Ollama 应用数据文件夹中。模型文件单独存储在可配置的模型目录中。\n\n资料来源：[app/store/store.go:store.go]()\n\n## 设置面板功能\n\n设置面板是用户配置应用程序的主要入口，提供以下配置选项：\n\n| 设置项 | 功能描述 | 可配置性 |\n|--------|----------|----------|\n| Expose | 是否将 Ollama 服务暴露到网络 | 用户开关 |\n| Models | 模型存储目录位置 | 仅查看，通过系统对话框选择 |\n| Cloud | 云端模型和 Web 搜索功能开关 | 受 OLLAMA_NO_CLOUD 环境变量约束 |\n| Auto Update | 自动更新检查开关 | 用户开关 |\n| 用户账户 | 登录、升级、管理账户信息 | 需联网 |\n\n资料来源：[app/ui/app/src/components/Settings.tsx:Settings.tsx]()\n\n## 开发环境搭建\n\n### 环境准备\n\n开发桌面应用程序前需要安装以下工具：\n\n1. Go 1.21 或更高版本\n2. Node.js 18+ 和 npm\n3. TypeScript 代码生成工具：`go install github.com/tkrajina/typescriptify-golang-structs/tscriptify@latest`\n\n### UI 开发模式\n\nUI 开发支持热重载功能，可大幅提升开发效率：\n\n```bash\n# 终端 1：启动 React 开发服务器\ncd ui/app\nnpm install\nnpm run dev\n\n# 终端 2：运行应用（带开发标志）\ngo generate ./...\nOLLAMA_DEBUG=1 go run ./cmd/app -dev\n```\n\n`-dev` 标志启用以下开发特性：\n\n- 从 Vite 开发服务器（http://localhost:5173）加载 UI\n- 固定 API 请求端口至 http://127.0.0.1:3001\n- 启用 CORS 跨域请求头\n- 支持前端热重载\n\n资料来源：[app/README.md:Development]()\n\n### 生产构建\n\n**Windows 构建流程：**\n\n```powershell\n# 安装本地依赖\n.\\scripts\\deps_local.ps1\n\n# 或使用发布依赖\n.\\scripts\\deps_release.ps1 0.6.8\n\n# 执行构建\n.\\scripts\\build_windows.ps1\n```\n\n**macOS 构建流程：**\n\n```bash\n# 设置 Xcode 开发工具路径\nexport DEVELOPER_DIR=/Applications/Xcode_14.1.0.app/Contents/Developer\n\n# 安装本地依赖\n./scripts/deps_local.sh\n\n# 或使用发布依赖\n./scripts/deps_release.sh 0.6.8\n\n# 执行构建\n./scripts/build_darwin.sh\n```\n\n资料来源：[app/README.md:Build]()\n\n## 下载与发布\n\n### 下载地址\n\n| 平台 | 下载链接 |\n|------|----------|\n| macOS | https://github.com/ollama/app/releases/download/latest/Ollama.dmg |\n| Windows | https://github.com/ollama/app/releases/download/latest/OllamaSetup.exe |\n\n资料来源：[app/README.md:Download]()\n\n## 工作流程\n\n### 模型下载流程\n\n当用户选择尚未安装的模型时，应用程序触发下载流程：\n\n```mermaid\nsequenceDiagram\n participant U as 用户界面\n participant S as 服务器模块\n participant M as 模型存储\n participant C as 核心引擎\n\n U->>S: 请求下载模型\n S->>M: 创建下载会话\n M-->>U: 返回下载进度\n loop 下载中\n M-->>U: 更新下载百分比\n end\n M->>C: 加载模型文件\n C-->>U: 模型就绪通知\n```\n\n下载进度组件会实时显示已下载字节数和总字节数，并计算完成百分比。进度条采用动态宽度设计，百分比精确到个位。资料来源：[app/ui/app/src/components/Downloading.tsx:Downloading.tsx]()\n\n### 思考层级配置\n\n应用程序支持配置模型的思考层级（Thinking Level），这是一个实验性功能，允许用户控制模型在生成响应前的推理深度：\n\n```mermaid\ngraph TD\n A[用户点击思考按钮] --> B{下拉菜单展开}\n B --> C[选择层级]\n C --> D[更新当前配置]\n D --> E[下拉菜单关闭]\n E --> F[下次请求携带新层级]\n```\n\n资料来源：[app/ui/app/src/components/ThinkButton.tsx:ThinkButton.tsx]()\n\n## 技术实现要点\n\n### 组件优化\n\n部分高频渲染的组件使用了 `React.memo` 进行性能优化，通过自定义比较函数避免不必要的重渲染：\n\n```typescript\nexport default React.memo(Message, (prevProps, nextProps) => {\n return (\n prevProps.message === nextProps.message &&\n prevProps.onEditMessage === nextProps.onEditMessage &&\n prevProps.messageIndex === nextProps.messageIndex &&\n prevProps.isStreaming === nextProps.isStreaming &&\n prevProps.isFaded === nextProps.isFaded &&\n prevProps.browserToolResult === nextProps.browserToolResult\n );\n});\n```\n\n这种方法确保只有当消息内容或相关属性发生变化时才触发重新渲染，提升了对话界面的响应速度。\n\n### 深色模式支持\n\n所有 UI 组件均支持深色模式，通过 TailwindCSS 的 `dark:` 前缀实现主题适配。颜色变量如 `text-neutral-500` 和 `dark:text-neutral-400` 允许界面自动适应系统主题设置。\n\n### WebView 桥接协议\n\n前端与后端通过预定义的 JavaScript 接口进行通信。WebView 暴露的 `window.webview` 对象提供了以下能力：\n\n- `selectModelsDirectory()`：打开系统文件选择对话框\n- 其他系统级操作接口\n\n资料来源：[app/ui/app/src/components/Settings.tsx:Settings.tsx]()\n\n## 相关资源\n\nOllama 桌面应用程序是 Ollama 整体生态系统的前端入口，它与核心推理引擎、API 服务、命令行工具共同构成了完整的本地 AI 运行平台。通过提供图形化界面，应用程序降低了用户使用本地大语言模型的门槛，同时保持了高性能和隐私保护的特性。\n\n---\n\n\n\n## 高级功能\n\n### 相关页面\n\n相关主题：[API 参考](#page-api-reference), [LLM 后端系统](#page-llm-backend), [系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [docs/capabilities/streaming.mdx](https://github.com/ollama/ollama/blob/main/docs/capabilities/streaming.mdx)\n- [docs/capabilities/tool-calling.mdx](https://github.com/ollama/ollama/blob/main/docs/capabilities/tool-calling.mdx)\n- [docs/capabilities/vision.mdx](https://github.com/ollama/ollama/blob/main/docs/capabilities/vision.mdx)\n- [docs/capabilities/embeddings.mdx](https://github.com/ollama/ollama/blob/main/docs/capabilities/embeddings.mdx)\n- [docs/capabilities/thinking.mdx](https://github.com/ollama/ollama/blob/main/docs/capabilities/thinking.mdx)\n- [tools/tools.go](https://github.com/ollama/ollama/blob/main/tools/tools.go)\n- [x/tools/registry.go](https://github.com/ollama/ollama/blob/main/x/tools/registry.go)\n- [x/tools/websearch.go](https://github.com/ollama/ollama/blob/main/x/tools/websearch.go)\n- [model/renderers/json.go](https://github.com/ollama/ollama/blob/main/model/renderers/json.go)\n \n\n# 高级功能\n\nOllama 作为一款本地大语言模型运行框架，提供了丰富的**高级功能**，旨在增强 AI 模型的实用性、交互性和扩展性。这些功能包括流式输出、工具调用、多模态视觉支持、文本嵌入、思维推理模式等，使开发者能够在本地环境中构建复杂的 AI 应用，而无需依赖云端服务。\n\n本文档详细介绍 Ollama 的各项高级功能，包括其工作原理、API 使用方式、配置选项以及实际应用场景。\n\n---\n\n## 1. 流式输出（Streaming）\n\n### 1.1 功能概述\n\n流式输出是 Ollama 的一项核心功能，允许模型以流式方式逐步返回生成内容，而非等待完整响应生成完毕后再返回。这对于需要实时反馈的应用场景（如聊天机器人、实时写作辅助等）至关重要。\n\n流式输出采用 **Server-Sent Events (SSE)** 协议实现，客户端可以逐步接收模型生成的内容，并在每个 token 生成时立即展示，提升用户体验。\n\n### 1.2 工作原理\n\n```mermaid\ngraph TD\n A[客户端发送请求] --> B{启用 stream: true}\n B --> C[服务端开始生成]\n C --> D[生成单个 token]\n D --> E[通过 SSE 推送 token]\n E --> F[客户端接收并显示]\n F --> G{是否完成?}\n G -->|否| D\n G -->|是| H[发送完成事件]\n H --> I[关闭连接]\n```\n\n### 1.3 API 调用示例\n\n**生成端点流式请求：**\n\n```bash\ncurl -X POST http://localhost:11434/api/generate \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"model\": \"llama3\",\n \"prompt\": \"Write a story\",\n \"stream\": true\n }'\n```\n\n**流式响应格式：**\n\n```json\n{\"model\":\"llama3\",\"created_at\":\"2024-01-01T00:00:00Z\",\"response\":\"从前\",\"done\":false}\n{\"model\":\"llama3\",\"created_at\":\"2024-01-01T00:00:00Z\",\"response\":\"有一个\",\"done\":false}\n{\"model\":\"llama3\",\"created_at\":\"2024-01-01T00:00:00Z\",\"response\":\"小女孩\",\"done\":true}\n```\n\n资料来源：[docs/capabilities/streaming.mdx]()\n\n### 1.4 前端组件实现\n\nOllama 的前端界面通过 `StreamingMarkdownContent` 组件处理流式内容渲染，该组件接收 `content` 和 `isStreaming` 属性，实时更新显示区域。\n\n```tsx\n\n```\n\n资料来源：[app/ui/app/src/components/Message.tsx]()\n\n---\n\n## 2. 工具调用（Tool Calling）\n\n### 2.1 功能概述\n\n工具调用功能使大语言模型能够识别并调用外部工具来执行特定任务，突破了纯文本生成的能力限制。通过预定义工具注册机制，模型可以请求执行 Web 搜索、文件操作、计算任务等。\n\n### 2.2 架构设计\n\n```mermaid\ngraph TD\n A[用户请求] --> B[模型分析请求]\n B --> C{需要调用工具?}\n C -->|否| D[直接生成响应]\n C -->|是| E[返回工具调用请求]\n E --> F[工具注册表查找]\n F --> G[执行工具]\n G --> H[返回结果]\n H --> I[模型整合结果]\n I --> J[生成最终响应]\n```\n\n### 2.3 工具注册机制\n\nOllama 通过 `registry.go` 实现工具的注册与管理，支持多种类型的工具集成。\n\n```go\n// 工具注册表核心结构\ntype ToolRegistry struct {\n tools map[string]Tool\n}\n```\n\n资料来源：[x/tools/registry.go]()\n\n**注册流程：**\n\n1. 定义工具的结构和参数模式\n2. 将工具注册到全局注册表\n3. 模型通过 function calling 识别可调用工具\n4. 执行工具并返回结果\n\n### 2.4 Web 搜索工具\n\nWeb 搜索是 Ollama 集成的重要工具之一，允许模型实时获取互联网信息。\n\n```go\ntype WebSearchTool struct {\n Query string `json:\"query\"`\n}\n\ntype WebSearchResult struct {\n Query string `json:\"query\"`\n Results []Result `json:\"results\"`\n}\n```\n\n资料来源：[x/tools/websearch.go]()\n\n**搜索结果显示：**\n\n```tsx\n{toolName === \"web_search\" && (\n <>\n Search results for \n \n)}\n```\n\n资料来源：[app/ui/app/src/components/Message.tsx]()\n\n### 2.5 工具配置选项\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| Tools | boolean | false | 启用单轮工具模式 |\n| Agent | boolean | false | 启用代理模式 |\n| Tools Mode | enum | - | 工具使用级别控制 |\n\n资料来源：[app/ui/app/src/components/Settings.tsx]()\n\n### 2.6 工具调用界面\n\n前端界面提供直观的工具调用展示，包括工具名称、参数和执行结果：\n\n```tsx\n{message.tool_calls && message.tool_calls.length > 0 && (\n \n {message.tool_calls.map((toolCall: ToolCall, index: number) => (\n \n ))}\n
\n)}\n```\n\n资料来源：[app/ui/app/src/components/Message.tsx]()\n\n---\n\n## 3. 多模态视觉支持（Vision）\n\n### 3.1 功能概述\n\nOllama 支持多模态模型，能够处理图像输入并结合文本进行理解和分析。这使得用户可以上传图片并就图片内容进行问答、分析图表、描述场景等。\n\n### 3.2 支持的场景\n\n- **图像描述**：生成图片的文字描述\n- **视觉问答**：根据图片内容回答问题\n- **文档分析**：理解截图、图表、表格\n- **多图像处理**：同时分析多张图片\n\n### 3.3 API 调用示例\n\n**使用图片提示生成描述：**\n\n```bash\n./ollama-bench -model qwen3-vl -image photo.jpg -epochs 6 -max-tokens 100 -p \"Describe this image\"\n```\n\n资料来源：[cmd/bench/README.md]()\n\n**图像生成 API：**\n\n```bash\ncurl http://localhost:11434/v1/images/generations \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"model\": \"z-image\",\n \"prompt\": \"a white cat\",\n \"size\": \"1024x1024\"\n }'\n```\n\n资料来源：[x/imagegen/README.md]()\n\n### 3.4 图像生成参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| model | string | required | 模型名称 |\n| prompt | string | required | 生成提示词 |\n| size | string | 1024x1024 | 图像尺寸 |\n| steps | int | 9 | 去噪步数 |\n| seed | int | 42 | 随机种子 |\n\n资料来源：[x/imagegen/README.md]()\n\n---\n\n## 4. 文本嵌入（Embeddings）\n\n### 4.1 功能概述\n\n嵌入功能将文本转换为高维向量表示，使得语义相似的文本在向量空间中距离更近。这对于语义搜索、文本聚类、相似度匹配等应用至关重要。\n\n### 4.2 嵌入端点\n\n```bash\ncurl -X POST -H \"Content-Type: application/json\" \\\n -d '{\"prompt\": \"turn me into an embedding\"}' \\\n http://localhost:8080/embedding\n```\n\n资料来源：[runner/README.md]()\n\n### 4.3 应用场景\n\n- **语义搜索**：基于内容相似度而非关键词匹配\n- **文档聚类**：将相关文档分组\n- **推荐系统**：计算内容相似度\n- **文本分类**：作为下游分类器的特征输入\n\n资料来源：[docs/capabilities/embeddings.mdx]()\n\n---\n\n## 5. 思维推理模式（Thinking）\n\n### 5.1 功能概述\n\n思维推理模式允许模型在生成最终答案之前展示其推理过程，特别适合复杂问题解决和需要多步推理的任务。\n\n### 5.2 思维层级配置\n\nOllama 提供了多级思维模式配置，用户可以根据任务复杂度选择合适的推理深度：\n\n| 思维层级 | 描述 | 适用场景 |\n|----------|------|----------|\n| none | 无思维推理 | 简单问答 |\n| low | 基础推理 | 简单推理任务 |\n| medium | 中级推理 | 常规复杂问题 |\n| high | 深度推理 | 复杂多步推理 |\n\n资料来源：[app/ui/app/src/components/ThinkButton.tsx]()\n\n### 5.3 前端实现\n\n```tsx\n{Object.entries(THINKING_LEVELS).map(([, level]) => (\n {\n onLevelChange?.(level);\n setIsDropdownOpen(false);\n }}\n >\n {THINKING_LEVEL_LABELS[level]}\n \n))}\n```\n\n资料来源：[app/ui/app/src/components/ThinkButton.tsx]()\n\n### 5.4 工作流程\n\n```mermaid\ngraph TD\n A[用户输入] --> B[选择思维层级]\n B --> C[模型进行内部推理]\n C --> D{是否显示推理过程?}\n D -->|是| E[输出推理步骤]\n D -->|否| F[直接输出结论]\n E --> F\n F --> G[最终响应]\n```\n\n---\n\n## 6. JSON 渲染器\n\n### 6.1 功能概述\n\nOllama 包含专门的 JSON 渲染器组件，用于格式化和展示结构化 JSON 数据，确保模型输出的 JSON 内容正确显示。\n\n### 6.2 核心结构\n\n```go\ntype JSONRenderer struct {\n // 渲染配置\n indent int\n sortKeys bool\n}\n```\n\n资料来源：[model/renderers/json.go]()\n\n### 6.3 渲染特性\n\n- **语法高亮**：区分键、值、类型\n- **格式化输出**：美化 JSON 缩进\n- **错误检测**：识别无效 JSON\n\n---\n\n## 7. 模型下载与进度跟踪\n\n### 7.1 下载管理\n\nOllama 提供可视化的模型下载进度跟踪功能，用户可以实时查看下载状态。\n\n### 7.2 下载界面组件\n\n```tsx\n\n```\n\n资料来源：[app/ui/app/src/components/Downloading.tsx]()\n\n### 7.3 进度显示格式\n\n```\n${formatBytes(completed, unit)} / ${formatBytes(total, unit)} (${Math.floor(percentage)}%)\n```\n\n资料来源：[app/ui/app/src/components/Downloading.tsx]()\n\n---\n\n## 8. 云端与本地配置\n\n### 8.1 配置项\n\nOllama 支持灵活的云端与本地模型切换配置：\n\n| 配置项 | 说明 |\n|--------|------|\n| Expose | 允许网络暴露 |\n| Models | 模型存储位置 |\n| Cloud | 启用云端模型 |\n| Auto Update | 自动更新功能 |\n\n资料来源：[app/ui/app/src/components/Settings.tsx]()\n\n### 8.2 环境变量控制\n\n某些配置可被环境变量强制覆盖：\n\n```tsx\n{cloudOverriddenByEnv\n ? \"The OLLAMA_NO_CLOUD environment variable is currently forcing cloud off.\"\n : \"Enable cloud models and web search.\"}\n```\n\n资料来源：[app/ui/app/src/components/Settings.tsx]()\n\n---\n\n## 9. 总结\n\nOllama 的高级功能通过模块化设计，为本地 AI 应用开发提供了强大的能力支撑：\n\n| 功能模块 | 主要作用 | 技术实现 |\n|----------|----------|----------|\n| 流式输出 | 实时响应反馈 | SSE 协议 |\n| 工具调用 | 扩展模型能力 | 函数注册表 |\n| 视觉支持 | 多模态理解 | 图像处理管线 |\n| 文本嵌入 | 语义表示 | 向量编码 |\n| 思维推理 | 推理过程展示 | 分层思维模式 |\n\n这些功能的组合使用，使开发者能够在本地环境中构建功能丰富、性能优秀的 AI 应用，同时保持对数据和模型的完全控制。\n\n---\n\n\n\n## 部署与构建\n\n### 相关页面\n\n相关主题：[项目概述](#page-overview), [系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [llama/README.md](https://github.com/ollama/ollama/blob/main/llama/README.md)\n- [app/README.md](https://github.com/ollama/ollama/blob/main/app/README.md)\n- [api/examples/README.md](https://github.com/ollama/ollama/blob/main/api/examples/README.md)\n- [cmd/bench/README.md](https://github.com/ollama/ollama/blob/main/cmd/bench/README.md)\n- [runner/README.md](https://github.com/ollama/ollama/blob/main/runner/README.md)\n- [x/imagegen/cmd/engine/README.md](https://github.com/ollama/ollama/blob/main/x/imagegen/cmd/engine/README.md)\n- [llama/llama.cpp/src/llama.go](https://github.com/ollama/ollama/blob/main/llama/llama.cpp/src/llama.go)\n- [ml/backend/ggml/ggml/src/ggml-backend-reg.cpp](https://github.com/ollama/ollama/blob/main/ml/backend/ggml/ggml/src/ggml-backend-reg.cpp)\n \n\n# 部署与构建\n\nOllama 是一个本地大语言模型运行框架，支持跨平台部署与构建。本文详细介绍 Ollama 的构建系统、支持的平台、环境配置以及各平台的构建流程。\n\n## 系统概述\n\nOllama 采用模块化架构设计，支持多种后端计算框架和硬件加速。构建系统基于 Makefile 和 Go 语言工具链，可生成适用于不同操作系统的可执行文件和容器镜像。\n\n```mermaid\ngraph TD\n A[Ollama 源码] --> B[构建系统]\n B --> C[Linux 构建]\n B --> D[macOS 构建]\n B --> E[Windows 构建]\n B --> F[Docker 构建]\n C --> G[二进制文件]\n D --> G\n E --> G\n F --> H[Docker 镜像]\n G --> I[本地部署]\n H --> J[容器化部署]\n```\n\n资料来源：[llama/README.md:1-20]()\n\n## 环境准备\n\n### Go 语言环境\n\nOllama 主要使用 Go 语言开发，构建系统要求安装 Go 1.22 或更高版本。Go 环境变量配置如下：\n\n| 环境变量 | 说明 | 示例值 |\n|---------|------|--------|\n| `GOPATH` | Go 工作目录 | `$HOME/go` |\n| `GOROOT` | Go 安装路径 | `/usr/local/go` |\n| `CGO_ENABLED` | C 互操作启用 | `1` |\n\n资料来源：[llama/llama.cpp/src/llama.go:1-10]()\n\n### 系统依赖\n\n不同平台需要安装相应的编译工具链和依赖库。\n\n**Linux 平台依赖：**\n\n- GCC/G++ 编译器（支持 C++17）\n- CMake（用于 ggml 后端构建）\n- CUDA Toolkit（GPU 加速可选）\n- Vulkan SDK（GPU 加速可选）\n\n**macOS 平台依赖：**\n\n- Xcode 14.1 或更高版本\n- Xcode 命令行工具\n- Metal 框架（GPU 加速）\n\n**Windows 平台依赖：**\n\n- Visual Studio 2022 或更高版本\n- MinGW-w64（部分构建场景）\n- Windows SDK\n\n资料来源：[app/README.md:1-50]()\n\n## 多平台构建流程\n\n### Linux 构建\n\nLinux 平台是 Ollama 最主要的部署目标，支持完整的 GPU 加速功能。\n\n```bash\n# 安装系统依赖\nsudo apt-get update\nsudo apt-get install -y build-essential cmake\n\n# 克隆源码\ngit clone https://github.com/ollama/ollama.git\ncd ollama\n\n# 构建可执行文件\ngo build -o ollama .\n```\n\n资料来源：[llama/README.md:10-25]()\n\n### macOS 构建\n\nmacOS 平台支持 Metal GPU 加速，通过 Xcode 工具链进行构建。\n\n```bash\n# 设置 Xcode 开发环境\nexport DEVELOPER_DIR=/Applications/Xcode_14.1.0.app/Contents/Developer\nexport SDKROOT=/Applications/Xcode_14.1.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk\n\n# 设置编译优化参数\nexport CGO_CFLAGS=\"-O3 -mmacosx-version-min=12.0\"\nexport CGO_CXXFLAGS=\"-O3 -mmacosx-version-min=12.0\"\nexport CGO_LDFLAGS=\"-mmacosx-version-min=12.0\"\n\n# 安装本地依赖\n./scripts/deps_local.sh\n\n# 执行构建\n./scripts/build_darwin.sh\n```\n\n资料来源：[app/README.md:30-55]()\n\n### Windows 构建\n\nWindows 平台通过 PowerShell 脚本自动化构建流程。\n\n```powershell\n# 安装本地依赖\n.\\scripts\\deps_local.ps1\n\n# 或使用发布版本依赖\n.\\scripts\\deps_release.ps1 0.6.8\n\n# 执行构建\n.\\scripts\\build_windows.ps1\n```\n\n资料来源：[app/README.md:20-30]()\n\n## GPU 后端支持\n\nOllama 通过 ggml（GGML 库）支持多种 GPU 加速后端。\n\n```mermaid\ngraph LR\n A[Ollama Core] --> B[ggml-backend-reg]\n B --> C[CPU Backend]\n B --> D[CUDA Backend]\n B --> E[Metal Backend]\n B --> F[Vulkan Backend]\n B --> G[SYCL Backend]\n B --> H[WebGPU Backend]\n \n C --> I[ARM/x86]\n D --> J[NVIDIA GPU]\n E --> K[Apple Silicon]\n F --> L[AMD/Intel GPU]\n```\n\n资料来源：[ml/backend/ggml/ggml/src/ggml-backend-reg.cpp:1-60]()\n\n### 后端编译条件\n\n| 后端 | 编译宏 | 依赖 |\n|------|--------|------|\n| CPU | `GGML_USE_CPU` | 无 |\n| CUDA | `GGML_USE_CUDA` | CUDA Toolkit |\n| Metal | `GGML_USE_METAL` | Xcode/Metal SDK |\n| Vulkan | `GGML_USE_VULKAN` | Vulkan SDK |\n| SYCL | `GGML_USE_SYCL` | oneAPI |\n| WebGPU | `GGML_USE_WEBGPU` | Dawn |\n| CANN | `GGML_USE_CANN` | 华为昇腾 |\n| BLAS | `GGML_USE_BLAS` | OpenBLAS |\n\n资料来源：[ml/backend/ggml/ggml/src/ggml-backend-reg.cpp:25-55]()\n\n### Vulkan 后端构建\n\nVulkan 后端需要使用 GLSL 编译器将着色器代码编译为 SPIR-V 格式。\n\n```bash\n# 编译 Vulkan 着色器生成器\ng++ -std=c++17 -o vulkan-shaders-gen vulkan-shaders-gen.cpp\n\n# 生成着色器头文件\n./vulkan-shaders-gen --input ./shaders --output /tmp/vulkan_shaders.hpp\n```\n\n资料来源：[ml/backend/ggml/ggml/src/ggml-vulkan/vulkan-shaders/vulkan-shaders-gen.cpp:1-50]()\n\n## Docker 部署\n\nOllama 提供官方 Docker 镜像，支持容器化部署。\n\n### Docker 构建\n\n```bash\n# 构建 Docker 镜像\ndocker build -t ollama/ollama:latest .\n\n# 运行容器\ndocker run -d \\\n --gpus all \\\n -v ollama:/root/.ollama \\\n -p 11434:11434 \\\n ollama/ollama:latest\n```\n\n资料来源：[app/README.md:5-15]()\n\n### Docker 构建脚本\n\n构建系统提供自动化 Docker 构建脚本：\n\n```bash\n# 执行 Docker 构建\n./scripts/build_docker.sh\n\n# 指定镜像标签\ndocker build -t ollama/ollama:custom-tag .\n```\n\n## 轻量级 Runner\n\nOllama 提供一个精简的 `runner` 模块，用于在资源受限环境中加载模型并提供 HTTP 推理服务。\n\n```bash\n# 构建 runner\ngo build -o runner ./x/imagegen/cmd/engine\n\n# 启动 runner\n./runner -model \n```\n\n### Runner API 接口\n\n| 端点 | 方法 | 说明 |\n|------|------|------|\n| `/completion` | POST | 文本补全 |\n| `/embedding` | POST | 向量嵌入生成 |\n\n资料来源：[runner/README.md:1-25]()\n\n**完成请求示例：**\n\n```bash\ncurl -X POST \\\n -H \"Content-Type: application/json\" \\\n -d '{\"prompt\": \"hi\"}' \\\n http://localhost:8080/completion\n```\n\n**嵌入请求示例：**\n\n```bash\ncurl -X POST \\\n -H \"Content-Type: application/json\" \\\n -d '{\"prompt\": \"turn me into an embedding\"}' \\\n http://localhost:8080/embedding\n```\n\n## API 示例\n\nOllama 提供 Go 语言 API 示例，帮助开发者集成推理功能。\n\n### 可用示例\n\n| 示例 | 文件路径 | 说明 |\n|------|----------|------|\n| 聊天 | `api/examples/chat/main.go` | 与模型对话 |\n| 生成 | `api/examples/generate/main.go` | 文本生成 |\n| 流式生成 | `api/examples/generate-streaming/main.go` | 流式文本生成 |\n| 拉取进度 | `api/examples/pull-progress/main.go` | 模型拉取进度 |\n\n资料来源：[api/examples/README.md:1-20]()\n\n### 运行示例\n\n```bash\n# 运行聊天示例\ngo run api/examples/chat/main.go\n\n# 运行生成示例\ngo run api/examples/generate/main.go\n\n# 运行流式生成示例\ngo run api/examples/generate-streaming/main.go\n```\n\n## 交叉编译支持\n\nOllama 支持交叉编译，可在单一平台构建其他平台的二进制文件。\n\n### 编译目标配置\n\n| 目标平台 | GOOS | GOARCH | 额外配置 |\n|----------|------|--------|----------|\n| Linux AMD64 | `linux` | `amd64` | 无 |\n| Linux ARM64 | `linux` | `arm64` | 无 |\n| macOS AMD64 | `darwin` | `amd64` | Xcode SDK |\n| macOS ARM64 | `darwin` | `arm64` | Xcode SDK |\n| Windows AMD64 | `windows` | `amd64` | MinGW |\n\n### 交叉编译示例\n\n```bash\n# 编译 Linux ARM64 版本\nGOOS=linux GOARCH=arm64 CGO_ENABLED=1 go build -o ollama-linux-arm64 .\n\n# 编译 Windows 版本\nGOOS=windows GOARCH=amd64 CGO_ENABLED=1 go build -o ollama.exe .\n```\n\n## 性能基准测试\n\nOllama 提供 `ollama-bench` 工具用于性能评估。\n\n```bash\n# 基本用法\n./ollama-bench -model llama3 -epochs 6\n\n# 指定提示词\n./ollama-bench -model gemma3 -epochs 6 -p \"Write me a short story\"\n\n# 带图像提示词\n./ollama-bench -model qwen3-vl -image photo.jpg -epochs 6 -max-tokens 100 -p \"Describe this image\"\n\n# 控制提示词长度\n./ollama-bench -model gemma3 -epochs 6 -prompt-tokens 512\n\n# 高级配置\n./ollama-bench -model llama3 -epochs 10 -temperature 0.7 -max-tokens 500 -seed 42 -format csv -output results.csv\n```\n\n### 基准测试参数\n\n| 参数 | 说明 | 默认值 |\n|------|------|--------|\n| `-model` | 模型名称（必填） | - |\n| `-epochs` | 迭代次数 | 6 |\n| `-max-tokens` | 最大生成 token 数 | 200 |\n| `-temperature` | 采样温度 | 0.0 |\n| `-seed` | 随机种子 | 0（随机） |\n| `-timeout` | 超时时间（秒） | 300 |\n| `-format` | 输出格式 | - |\n\n资料来源：[cmd/bench/README.md:1-40]()\n\n## 图像生成引擎\n\nOllama 的图像生成功能基于独立的 MLX 引擎。\n\n### 构建图像生成引擎\n\n```bash\ngo build -o engine ./x/imagegen/cmd/engine\n```\n\n### 使用图像生成\n\n```bash\n./engine -zimage -model /path/to/z-image -prompt \"a cat\" -output cat.png\n```\n\n### 可选参数\n\n| 参数 | 说明 | 默认值 |\n|------|------|--------|\n| `-width` | 图像宽度 | 1024 |\n| `-height` | 图像高度 | 1024 |\n| `-steps` | 去噪步数 | 9 |\n| `-seed` | 随机种子 | 42 |\n\n资料来源：[x/imagegen/cmd/engine/README.md:1-30]()\n\n## 桌面应用构建\n\nOllama 提供跨平台桌面应用，支持 macOS 和 Windows。\n\n### 桌面应用依赖\n\n| 平台 | 构建脚本 | 说明 |\n|------|----------|------|\n| macOS | `scripts/build_darwin.sh` | 使用 Xcode 构建 |\n| Windows | `scripts/build_windows.ps1` | 使用 PowerShell 构建 |\n\n### 开发模式启动\n\n```bash\n# 生成代码并启动开发服务器\ngo generate ./...\ngo run ./cmd/app\n\n# 启用调试模式\nOLLAMA_DEBUG=1 go run ./cmd/app -dev\n```\n\n### UI 开发模式\n\n1. 启动 React 开发服务器：\n ```bash\n cd ui/app\n npm install\n npm run dev\n ```\n\n2. 启动 Ollama 应用（带 `-dev` 参数）：\n ```bash\n go generate ./...\n OLLAMA_DEBUG=1 go run ./cmd/app -dev\n ```\n\n开发模式下 `-dev` 参数启用以下功能：\n\n- 从 Vite 开发服务器加载 UI（http://localhost:5173）\n- 固定 API 请求端口（http://127.0.0.1:3001）\n- 启用 CORS 跨域请求支持\n- 支持热模块替换\n\n资料来源：[app/README.md:55-90]()\n\n## 版本与发布\n\nOllama 使用语义化版本号管理发布版本。发布构建需要：\n\n1. 更新版本号文件\n2. 生成变更日志\n3. 执行完整测试套件\n4. 构建所有平台版本\n5. 签名并发布工件\n\n## 常见问题排查\n\n| 问题 | 可能原因 | 解决方案 |\n|------|----------|----------|\n| CGO 编译失败 | 缺少 C/C++ 编译器 | 安装 GCC 或 Clang |\n| GPU 不可用 | 驱动未正确安装 | 更新 GPU 驱动程序 |\n| 内存不足 | 模型过大 | 选择更小的模型 |\n| 端口占用 | 11434 端口被占用 | 更换端口或释放端口 |\n\n## 总结\n\nOllama 的构建系统设计灵活，支持从源码编译到 Docker 容器化部署的完整流程。开发者可根据目标平台和硬件环境选择合适的构建方式，利用多后端支持实现最优的推理性能。\n\n---\n\n\n\n## 模型转换系统\n\n### 相关页面\n\n相关主题：[模型管理](#page-model-management), [LLM 后端系统](#page-llm-backend), [部署与构建](#page-deployment)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [convert/convert.go](https://github.com/ollama/ollama/blob/main/convert/convert.go)\n- [convert/convert_llama.go](https://github.com/ollama/ollama/blob/main/convert/convert_llama.go)\n- [convert/convert_qwen3.go](https://github.com/ollama/ollama/blob/main/convert/convert_qwen3.go)\n- [convert/convert_gemma3.go](https://github.com/ollama/ollama/blob/main/convert/convert_gemma3.go)\n- [convert/reader_safetensors.go](https://github.com/ollama/ollama/blob/main/convert/reader_safetensors.go)\n- [convert/reader_torch.go](https://github.com/ollama/ollama/blob/main/convert/reader_torch.go)\n- [tokenizer/tokenizer.go](https://github.com/ollama/ollama/blob/main/tokenizer/tokenizer.go)\n- [parser/parser.go](https://github.com/ollama/ollama/blob/main/parser/parser.go)\n \n\n# 模型转换系统\n\n## 概述\n\nOllama 的模型转换系统（Model Conversion System）是核心组件之一，负责将来自不同训练框架（如 PyTorch）和不同模型格式（如 SafeTensors）的预训练模型转换为 Ollama 专有的运行时格式。该系统支持多种模型架构，包括 Llama、Qwen3、Gemma3 等主流开源大语言模型。\n\n模型转换系统的主要职责包括：\n\n- 解析源模型文件的权重和配置\n- 处理不同量化级别的模型参数\n- 生成 Ollama 运行时所需的 GGUF/GGML 格式文件\n- 验证转换后模型的完整性和正确性\n\n## 系统架构\n\n### 整体架构图\n\n```mermaid\ngraph TD\n A[输入模型文件] --> B[解析层 Parser]\n B --> C[读取器 Readers]\n C --> D{模型类型检测}\n D -->|PyTorch| E[reader_torch.go]\n D -->|SafeTensors| F[reader_safetensors.go]\n E --> G[转换层 Converter]\n F --> G\n G --> H[模型特定转换器]\n H --> I[convert_llama.go]\n H --> J[convert_qwen3.go]\n H --> K[convert_gemma3.go]\n I --> L[分词器 Tokenizer]\n J --> L\n K --> L\n L --> M[GGUF/GGML 输出]\n```\n\n### 核心组件说明\n\n| 组件 | 文件路径 | 职责描述 |\n|------|----------|----------|\n| 解析器 | `parser/parser.go` | 解析输入配置和模型元数据 |\n| SafeTensors 读取器 | `convert/reader_safetensors.go` | 读取 SafeTensors 格式的模型权重 |\n| PyTorch 读取器 | `convert/reader_torch.go` | 读取 PyTorch 格式的模型权重 |\n| Llama 转换器 | `convert/convert_llama.go` | Llama 系列模型的专用转换逻辑 |\n| Qwen3 转换器 | `convert/convert_qwen3.go` | Qwen3 系列模型的专用转换逻辑 |\n| Gemma3 转换器 | `convert/convert_gemma3.go` | Gemma3 系列模型的专用转换逻辑 |\n| 分词器 | `tokenizer/tokenizer.go` | 处理模型关联的分词器资源 |\n\n## 转换流程\n\n### 标准转换工作流\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Parser as 解析器\n participant Reader as 读取器\n participant Converter as 转换器\n participant Tokenizer as 分词器\n participant Output as 输出文件\n\n User->>Parser: 提交原始模型路径\n Parser->>Parser: 读取模型配置和架构\n Parser->>Reader: 加载权重数据\n Reader-->>Parser: 返回权重映射\n Parser->>Converter: 调用架构专用转换\n Converter->>Converter: 应用量化参数\n Converter->>Tokenizer: 获取分词器配置\n Tokenizer-->>Converter: 返回分词器数据\n Converter->>Output: 生成 GGUF 文件\n Output-->>User: 转换完成\n```\n\n### 转换步骤详解\n\n#### 第一阶段：模型解析\n\n解析器负责读取输入模型的配置信息和元数据。这一阶段会：\n\n1. 检测模型文件格式（PyTorch checkpoint 或 SafeTensors）\n2. 读取模型架构配置（层数、隐藏维度、注意力头数等）\n3. 识别模型家族（Llama、Qwen、Gemma 等）\n\n资料来源：[parser/parser.go]()\n\n#### 第二阶段：权重读取\n\n根据检测到的模型格式，选择对应的读取器：\n\n- **SafeTensors 读取器**：高效读取 SafeTensors 格式文件，支持内存映射\n- **PyTorch 读取器**：处理传统的 PyTorch 模型检查点文件\n\n资料来源：[convert/reader_safetensors.go]()[convert/reader_torch.go]()\n\n#### 第三阶段：模型转换\n\n针对不同模型架构，应用特定的转换逻辑：\n\n| 模型系列 | 转换器文件 | 特殊处理 |\n|----------|------------|----------|\n| Llama | `convert_llama.go` | 标准 Transformer 结构 |\n| Qwen3 | `convert_qwen3.go` | Qwen 特有的 RoPE 和注意力机制 |\n| Gemma3 | `convert_gemma3.go` | Gemma 特有的规范化层 |\n\n资料来源：[convert/convert_llama.go]()[convert/convert_qwen3.go]()[convert/convert_gemma3.go]()\n\n#### 第四阶段：分词器处理\n\n转换过程的最后阶段涉及分词器资源的整合，确保转换后的模型能够正确地进行文本编码和解码。\n\n资料来源：[tokenizer/tokenizer.go]()\n\n## 核心转换接口\n\n### 主转换函数\n\n```go\n// convert/convert.go\nfunc Convert(modelPath string, outputPath string, options *ConvertOptions) error\n```\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| modelPath | string | 源模型文件的路径 |\n| outputPath | string | 输出 GGUF 文件的目标路径 |\n| options | ConvertOptions | 转换选项（量化级别、参数精度等） |\n\n### 转换选项结构\n\n| 选项 | 默认值 | 说明 |\n|------|--------|------|\n| Quantization | Q4_0 | 量化级别（Q4_0、Q5_1、Q8_0 等） |\n| BatchSize | 512 | 推理批次大小 |\n| Threads | 自动 | CPU 线程数 |\n\n## 量化支持\n\n模型转换系统支持多种量化级别，以平衡模型大小和推理质量：\n\n| 量化类型 | 压缩率 | 质量影响 | 适用场景 |\n|----------|--------|----------|----------|\n| F16 | 100% | 无 | 高精度需求 |\n| Q5_1 | ~60% | 极小 | 资源受限环境 |\n| Q4_0 | ~50% | 较小 | 推荐默认选项 |\n| Q3_K | ~35% | 中等 | 极致压缩 |\n| Q2_K | ~25% | 较明显 | 最低资源 |\n\n资料来源：[convert/convert.go]()\n\n## 输出格式\n\n转换系统输出的 GGUF（GGML Unified Format）文件包含以下组件：\n\n```\nGGUF 文件结构\n├── Header（文件头）\n├── Metadata KV（元数据键值对）\n├── Tensor Info（张量信息）\n├── Tensor Data（张量数据）\n└── Padding（对齐填充）\n```\n\nGGUF 格式设计用于支持：\n\n- 内存映射加载\n- 元数据内嵌\n- 张量信息自描述\n- 跨平台兼容性\n\n## 相关文件参考\n\n| 文件 | 功能 |\n|------|------|\n| `llama/llama.cpp/src/gguf.cpp` | GGUF 格式底层实现 |\n| `llama/llama.cpp/src/unicode.cpp` | Unicode 处理支持 |\n| `ml/backend/ggml/ggml/src/ggml-cpu/quants.c` | CPU 量化实现 |\n\n资料来源：[llama/llama.cpp/src/gguf.cpp]()[llama/llama.cpp/src/unicode.cpp]()[ml/backend/ggml/ggml/src/ggml-cpu/quants.c]()\n\n## 使用示例\n\n### 命令行转换\n\n```bash\nollama convert --input /path/to/model --output model.gguf --quantize q4_0\n```\n\n### API 调用\n\n```go\nerr := convert.Convert(\n \"/models/llama3-8b\",\n \"/output/llama3-8b-q4.gguf\",\n &convert.ConvertOptions{\n Quantization: \"q4_0\",\n },\n)\n```\n\n## 注意事项\n\n1. **模型兼容性**：仅支持已实现转换器的模型架构\n2. **资源需求**：大模型转换需要足够的磁盘空间和内存\n3. **量化损失**：量化会引入精度损失，请根据需求选择量化级别\n4. **版本兼容**：转换后的 GGUF 文件需与 Ollama 版本兼容\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：ollama/ollama\n\n摘要：发现 23 个潜在踩坑项，其中 7 个为 high/blocking；最高优先级：安装坑 - 来源证据：0.23.1 : mlx runner failed。\n\n## 1. 安装坑 · 来源证据：0.23.1 : mlx runner failed\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：0.23.1 : mlx runner failed\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_06acaa8b4f9d4923977e39f0de3349df | https://github.com/ollama/ollama/issues/16007 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：Ollama Cloud: Frequent 503 errors making cloud models unreliable\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Ollama Cloud: Frequent 503 errors making cloud models unreliable\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_568af28cdfb04c3eaf66b648ffff865f | https://github.com/ollama/ollama/issues/15419 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：Support `ppc64le` architecture\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Support `ppc64le` architecture\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_82122f2d4dfd4202a09101c78837de0e | https://github.com/ollama/ollama/issues/796 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 4. 配置坑 · 来源证据：Not compatible with Glaude code Cli when using local model\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Not compatible with Glaude code Cli when using local model\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_18239d63b211480fa37ec3c6dfb773ee | https://github.com/ollama/ollama/issues/16094 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 5. 配置坑 · 来源证据：Registering fine-tuned models\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Registering fine-tuned models\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3417faf9df79457e841e34e3df365558 | https://github.com/ollama/ollama/issues/16095 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 6. 运行坑 · 来源证据：[Bug] 0.23.2 Image generation succeeds but no image saved to disk or returned via API\"\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：[Bug] 0.23.2 Image generation succeeds but no image saved to disk or returned via API\"\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_294d6c7549c44529a06895132ef49777 | https://github.com/ollama/ollama/issues/16072 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 7. 安全/权限坑 · 来源证据：Feature Request: Expose account quota/usage details via Ollama Cloud API (headers and/or response body)\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Feature Request: Expose account quota/usage details via Ollama Cloud API (headers and/or response body)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_56cc99bad67b43a6b9a0ccff38aef5e2 | https://github.com/ollama/ollama/issues/15663 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 8. 安装坑 · 来源证据：VRAM Detection Issue on Radeon 780M (gfx1035) - Kernel Page Fault\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：VRAM Detection Issue on Radeon 780M (gfx1035) - Kernel Page Fault\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_26de977c783d40308b5962cd61c7a1df | https://github.com/ollama/ollama/issues/16040 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。\n\n## 9. 配置坑 · 来源证据：mistral-medium-3.5 - Produces nonsense outputs\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：mistral-medium-3.5 - Produces nonsense outputs\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5516e9097bb34de3a29210537c23e393 | https://github.com/ollama/ollama/issues/15975 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。\n\n## 10. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:658928958 | https://github.com/ollama/ollama | README/documentation is current enough for a first validation pass.\n\n## 11. 运行坑 · 来源证据：SIGSEGV in MLX VAE decode after diffusion steps complete on M4 Pro (macOS 26.4.1, Ollama 0.23.2)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：SIGSEGV in MLX VAE decode after diffusion steps complete on M4 Pro (macOS 26.4.1, Ollama 0.23.2)\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b8c07744d01f41b392c0ce87ebda37b4 | https://github.com/ollama/ollama/issues/16093 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 12. 运行坑 · 来源证据：ollama run 交互模式无法拖拽/粘贴图片\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：ollama run 交互模式无法拖拽/粘贴图片\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fc1e1d2e0e8e441d88c14ea3f7e6316e | https://github.com/ollama/ollama/issues/16091 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 13. 运行坑 · 来源证据：v0.23.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.23.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3c18127a820d4532885af7c07b2cf3c6 | https://github.com/ollama/ollama/releases/tag/v0.23.0 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 14. 维护坑 · 来源证据：Featured your project on osalt.dev — README badge available if you'd like to use it\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Featured your project on osalt.dev — README badge available if you'd like to use it\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d786a153134241388add2323ae688dfa | https://github.com/ollama/ollama/issues/16092 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 15. 维护坑 · 来源证据：Running qwen3.6:27b-bf16 on an AMD Ryzen AI Max leads to gibberish\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Running qwen3.6:27b-bf16 on an AMD Ryzen AI Max leads to gibberish\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ccd9e90075d24d39bf6fd43ae8b41221 | https://github.com/ollama/ollama/issues/15879 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 16. 维护坑 · 来源证据：Running qwen3.6:27b-q8_0 produces also gibberish on an AMD Ryzen AI Max+\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Running qwen3.6:27b-q8_0 produces also gibberish on an AMD Ryzen AI Max+\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4c22a5e593dd4d5b85e18cf0a5f790f4 | https://github.com/ollama/ollama/issues/15903 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 17. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:658928958 | https://github.com/ollama/ollama | last_activity_observed missing\n\n## 18. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:658928958 | https://github.com/ollama/ollama | no_demo; severity=medium\n\n## 19. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:658928958 | https://github.com/ollama/ollama | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 20. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:658928958 | https://github.com/ollama/ollama | no_demo; severity=medium\n\n## 21. 安全/权限坑 · 来源证据：v0.23.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.23.1\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a04a5f2703d24cc9aa072bdfcdc5552c | https://github.com/ollama/ollama/releases/tag/v0.23.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 22. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:658928958 | https://github.com/ollama/ollama | issue_or_pr_quality=unknown\n\n## 23. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:658928958 | https://github.com/ollama/ollama | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：ollama/ollama\n\n摘要：发现 23 个潜在踩坑项，其中 7 个为 high/blocking；最高优先级：安装坑 - 来源证据：0.23.1 : mlx runner failed。\n\n## 1. 安装坑 · 来源证据：0.23.1 : mlx runner failed\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：0.23.1 : mlx runner failed\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_06acaa8b4f9d4923977e39f0de3349df | https://github.com/ollama/ollama/issues/16007 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：Ollama Cloud: Frequent 503 errors making cloud models unreliable\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Ollama Cloud: Frequent 503 errors making cloud models unreliable\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_568af28cdfb04c3eaf66b648ffff865f | https://github.com/ollama/ollama/issues/15419 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：Support `ppc64le` architecture\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Support `ppc64le` architecture\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_82122f2d4dfd4202a09101c78837de0e | https://github.com/ollama/ollama/issues/796 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 4. 配置坑 · 来源证据：Not compatible with Glaude code Cli when using local model\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Not compatible with Glaude code Cli when using local model\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_18239d63b211480fa37ec3c6dfb773ee | https://github.com/ollama/ollama/issues/16094 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 5. 配置坑 · 来源证据：Registering fine-tuned models\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Registering fine-tuned models\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3417faf9df79457e841e34e3df365558 | https://github.com/ollama/ollama/issues/16095 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 6. 运行坑 · 来源证据：[Bug] 0.23.2 Image generation succeeds but no image saved to disk or returned via API\"\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：[Bug] 0.23.2 Image generation succeeds but no image saved to disk or returned via API\"\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_294d6c7549c44529a06895132ef49777 | https://github.com/ollama/ollama/issues/16072 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 7. 安全/权限坑 · 来源证据：Feature Request: Expose account quota/usage details via Ollama Cloud API (headers and/or response body)\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Feature Request: Expose account quota/usage details via Ollama Cloud API (headers and/or response body)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_56cc99bad67b43a6b9a0ccff38aef5e2 | https://github.com/ollama/ollama/issues/15663 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 8. 安装坑 · 来源证据：VRAM Detection Issue on Radeon 780M (gfx1035) - Kernel Page Fault\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：VRAM Detection Issue on Radeon 780M (gfx1035) - Kernel Page Fault\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_26de977c783d40308b5962cd61c7a1df | https://github.com/ollama/ollama/issues/16040 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。\n\n## 9. 配置坑 · 来源证据：mistral-medium-3.5 - Produces nonsense outputs\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：mistral-medium-3.5 - Produces nonsense outputs\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5516e9097bb34de3a29210537c23e393 | https://github.com/ollama/ollama/issues/15975 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。\n\n## 10. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:658928958 | https://github.com/ollama/ollama | README/documentation is current enough for a first validation pass.\n\n## 11. 运行坑 · 来源证据：SIGSEGV in MLX VAE decode after diffusion steps complete on M4 Pro (macOS 26.4.1, Ollama 0.23.2)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：SIGSEGV in MLX VAE decode after diffusion steps complete on M4 Pro (macOS 26.4.1, Ollama 0.23.2)\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b8c07744d01f41b392c0ce87ebda37b4 | https://github.com/ollama/ollama/issues/16093 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 12. 运行坑 · 来源证据：ollama run 交互模式无法拖拽/粘贴图片\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：ollama run 交互模式无法拖拽/粘贴图片\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fc1e1d2e0e8e441d88c14ea3f7e6316e | https://github.com/ollama/ollama/issues/16091 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 13. 运行坑 · 来源证据：v0.23.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.23.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3c18127a820d4532885af7c07b2cf3c6 | https://github.com/ollama/ollama/releases/tag/v0.23.0 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 14. 维护坑 · 来源证据：Featured your project on osalt.dev — README badge available if you'd like to use it\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Featured your project on osalt.dev — README badge available if you'd like to use it\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d786a153134241388add2323ae688dfa | https://github.com/ollama/ollama/issues/16092 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 15. 维护坑 · 来源证据：Running qwen3.6:27b-bf16 on an AMD Ryzen AI Max leads to gibberish\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Running qwen3.6:27b-bf16 on an AMD Ryzen AI Max leads to gibberish\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ccd9e90075d24d39bf6fd43ae8b41221 | https://github.com/ollama/ollama/issues/15879 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 16. 维护坑 · 来源证据：Running qwen3.6:27b-q8_0 produces also gibberish on an AMD Ryzen AI Max+\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Running qwen3.6:27b-q8_0 produces also gibberish on an AMD Ryzen AI Max+\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4c22a5e593dd4d5b85e18cf0a5f790f4 | https://github.com/ollama/ollama/issues/15903 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 17. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:658928958 | https://github.com/ollama/ollama | last_activity_observed missing\n\n## 18. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:658928958 | https://github.com/ollama/ollama | no_demo; severity=medium\n\n## 19. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:658928958 | https://github.com/ollama/ollama | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 20. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:658928958 | https://github.com/ollama/ollama | no_demo; severity=medium\n\n## 21. 安全/权限坑 · 来源证据：v0.23.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.23.1\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a04a5f2703d24cc9aa072bdfcdc5552c | https://github.com/ollama/ollama/releases/tag/v0.23.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 22. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:658928958 | https://github.com/ollama/ollama | issue_or_pr_quality=unknown\n\n## 23. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:658928958 | https://github.com/ollama/ollama | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# ollama - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 ollama 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Get up and running with Kimi-K2.5, GLM-5, MiniMax, DeepSeek, gpt-oss, Qwen, Gemma and other models. 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-overview：项目概述。围绕“项目概述”模拟一次用户任务，不展示安装或运行结果。\n2. page-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n3. page-api-reference：API 参考。围绕“API 参考”模拟一次用户任务，不展示安装或运行结果。\n4. page-model-management：模型管理。围绕“模型管理”模拟一次用户任务，不展示安装或运行结果。\n5. page-llm-backend：LLM 后端系统。围绕“LLM 后端系统”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-overview\n输入：用户提供的“项目概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-api-reference\n输入：用户提供的“API 参考”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-model-management\n输入：用户提供的“模型管理”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-llm-backend\n输入：用户提供的“LLM 后端系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-overview：Step 1 必须围绕“项目概述”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-architecture：Step 2 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-api-reference：Step 3 必须围绕“API 参考”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-model-management：Step 4 必须围绕“模型管理”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-llm-backend：Step 5 必须围绕“LLM 后端系统”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/ollama/ollama\n- https://github.com/ollama/ollama#readme\n- README.md\n- llama/README.md\n- docs/index.mdx\n- llm/server.go\n- server/routes.go\n- server/sched.go\n- llama/llama.go\n- discover/gpu.go\n- api/client.go\n- api/types.go\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 ollama 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：ollama/ollama\n\n## 官方安装入口\n\n### Python / pip · 官方安装入口\n\n```bash\npip install ollama\n```\n\n来源：https://github.com/ollama/ollama#readme\n\n## 来源\n\n- repo: https://github.com/ollama/ollama\n- docs: https://github.com/ollama/ollama#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_79f405cb6efb4ba58f5cb60a06b5c482"
}