# https://github.com/ollama/ollama 项目说明书 生成时间：2026-05-11 12:46:52 UTC ## 目录 - [项目概述](#page-overview) - [系统架构](#page-architecture) - [API 参考](#page-api-reference) - [模型管理](#page-model-management) - [LLM 后端系统](#page-llm-backend) - [命令行系统](#page-cli-system) - [桌面应用程序](#page-desktop-app) - [高级功能](#page-advanced-features) - [部署与构建](#page-deployment) - [模型转换系统](#page-model-conversion) ## 项目概述 ### 相关页面 相关主题：[系统架构](#page-architecture), [LLM 后端系统](#page-llm-backend), [部署与构建](#page-deployment)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/ollama/ollama/blob/main/README.md) - [llama/README.md](https://github.com/ollama/ollama/blob/main/llama/README.md) - [docs/index.mdx](https://github.com/ollama/ollama/blob/main/docs/index.mdx) - [app/README.md](https://github.com/ollama/ollama/blob/main/app/README.md) - [api/examples/README.md](https://github.com/ollama/ollama/blob/main/api/examples/README.md) - [cmd/bench/README.md](https://github.com/ollama/ollama/blob/main/cmd/bench/README.md) - [runner/README.md](https://github.com/ollama/ollama/blob/main/runner/README.md) - [x/imagegen/cmd/engine/README.md](https://github.com/ollama/ollama/blob/main/x/imagegen/cmd/engine/README.md)
# 项目概述 Ollama 是一款开源的大语言模型（Large Language Model，LLM）运行框架，旨在为开发者提供简便的本地模型部署和推理能力。通过统一的命令行接口和 REST API，Ollama 支持在本地环境中运行各种开源模型，无需复杂的配置或云端依赖。 ## 核心定位 Ollama 的设计目标是降低大语言模型的使用门槛，让用户能够在个人电脑或服务器上直接运行、测试和部署 AI 模型。项目采用轻量化架构，将模型管理、推理引擎和 API 服务整合为一个统一的系统，同时保持高度的可扩展性和跨平台兼容性。 该项目的主要特性包括： - **本地运行**：所有模型推理均在本地设备完成，数据不需要离开用户的计算机 - **跨平台支持**：支持 macOS、Windows 和 Linux 操作系统 - **模型管理**：提供命令行工具用于下载、运行和管理各类开源模型 - **API 接口**：提供 RESTful API，方便应用程序集成和使用 - **多种推理后端**：支持 CUDA、Metal、Vulkan、Sycl 等多种硬件加速后端 ## 技术架构 Ollama 的系统架构采用分层设计，从底层到顶层依次为推理引擎层、模型管理层、API 服务层和应用接口层。 ```mermaid graph TD A[用户应用] --> B[REST API / CLI] B --> C[API 服务层] C --> D[模型管理层] D --> E[推理引擎层] E --> F{硬件加速后端} F --> G[CUDA] F --> H[Metal] F --> I[Vulkan] F --> J[CPU] ``` ### 推理引擎层 推理引擎层是 Ollama 的核心计算组件，基于 ggml（现更名为 llama.cpp）库实现。该层负责加载模型权重、执行张量运算和处理模型推理的各个阶段。 ```mermaid graph LR A[模型文件] --> B[GGUF 格式解析] B --> C[张量加载] C --> D[推理计算] D --> E[结果输出] style A fill:#e1f5fe style E fill:#e8f5e8 ``` **支持的推理后端**： | 后端 | 平台 | 描述 | |------|------|------| | CUDA | Linux/Windows | NVIDIA GPU 加速 | | Metal | macOS | Apple Silicon GPU 加速 | | Vulkan | 跨平台 | 通用 GPU 加速 | | SYCL | Linux | Intel GPU 加速 | | CPU | 跨平台 | 仅使用 CPU 计算 | 资料来源：[ml/backend/ggml/ggml/src/ggml-backend-reg.cpp:1-56]() 推理引擎支持多种量化格式，以在保持模型质量的同时减少内存占用： | 量化类型 | 描述 | 内存占用 | |----------|------|----------| | f32 | 全精度浮点 | 100% | | f16 | 半精度浮点 | 50% | | q4_0 | 4位量化 | 25% | | q4_1 | 4位量化（改进版） | 29% | | q5_0 | 5位量化 | 31% | | q5_1 | 5位量化（改进版） | 35% | | q8_0 | 8位量化 | 50% | | q2_k | 2位量化（知识蒸馏） | 30% | | q3_k | 3位量化（知识蒸馏） | 37% | | q4_k | 4位量化（知识蒸馏） | 46% | | q5_k | 5位量化（知识蒸馏） | 57% | | q6_k | 6位量化（知识蒸馏） | 67% | 资料来源：[ml/backend/ggml/ggml/src/ggml-vulkan/vulkan-shaders/vulkan-shaders-gen.cpp:28-46]() ### 模型管理层 模型管理层负责处理模型的下载、存储、版本管理和运行时加载。该层维护本地模型仓库，支持从官方模型库或自定义来源获取模型。 模型文件采用 GGUF（Generic Graph Unification Format）格式存储，该格式将模型的架构、权重和元数据整合在单一文件中，便于分发和加载。 ### API 服务层 Ollama 提供了完整的 REST API，支持与现有应用程序的集成。API 服务层封装了模型调用的所有逻辑，提供标准化的接口。 **主要 API 端点**： | 端点 | 方法 | 功能 | |------|------|------| | /api/chat | POST | 对话式聊天交互 | | /api/generate | POST | 文本生成 | | /api/embeddings | POST | 生成文本嵌入向量 | | /api/pull | POST | 拉取模型 | | /api/create | POST | 创建新模型 | | /api/push | POST | 上传模型到仓库 | | /api/show | POST | 显示模型信息 | | /api/tags | GET | 列出本地模型 | 资料来源：[api/examples/README.md:1-30]() ### 应用接口层 应用接口层提供两种主要的交互方式：命令行界面（CLI）和桌面应用程序。 **命令行工具**： ```bash ollama run llama3 # 运行模型 ollama pull llama3 # 下载模型 ollama list # 列出本地模型 ollama ps # 显示运行中的模型 ollama rm llama3 # 删除模型 ``` **桌面应用程序**： Ollama 提供独立的桌面客户端，支持 macOS 和 Windows 平台。该应用基于 React 前端框架构建，提供图形化的模型管理和对话界面。 资料来源：[app/README.md:1-50]() ## 核心组件 ### 命令行客户端 命令行客户端是用户与 Ollama 交互的主要工具之一。它提供了简洁的接口用于执行所有模型操作，包括运行推理、管理模型和配置系统参数。 主要命令包括： | 命令 | 用途 | |------|------| | run | 启动模型交互会话 | | create | 从 Modelfile 创建模型 | | show | 显示模型信息 | | run | 运行模型（快捷方式） | | pull | 从模型库下载模型 | | push | 上传模型到仓库 | | list | 列出本地已安装的模型 | | ps | 显示当前运行的模型 | | cp | 复制模型 | | rm | 删除模型 | | help | 显示帮助信息 | ### 桌面应用 Ollama 桌面应用程序为用户提供了图形化的操作界面，主要功能包括： - **模型选择器**：浏览和选择本地或云端模型 - **聊天界面**：与模型进行对话交互 - **设置管理**：配置系统参数，如网络暴露、模型存储路径等 - **下载管理**：显示模型下载进度和状态 - **错误显示**：展示运行过程中的错误信息和诊断数据 ```mermaid graph TD A[桌面应用] --> B[模型选择器] A --> C[聊天界面] A --> D[设置面板] A --> E[下载管理] C --> F[消息组件] F --> G[工具调用] G --> H[网络搜索] G --> I[网页抓取] D --> J[网络配置] D --> K[存储配置] D --> L[云端设置] ``` 资料来源：[app/ui/app/src/components/ModelPicker.tsx:1-30]() 资料来源：[app/ui/app/src/components/Downloading.tsx:1-25]() 资料来源：[app/ui/app/src/components/Settings.tsx:1-80]() 资料来源：[app/ui/app/src/components/Message.tsx:1-50]() ### 性能基准测试工具 Ollama 内置了性能基准测试工具 `ollama-bench`，用于评估模型在不同硬件配置下的推理性能。该工具支持多种测试场景和参数配置。 **基本用法**： ```bash ./ollama-bench -model gemma3 -epochs 6 -max-tokens 100 -p "Write me a short story" ``` **带图像的测试**： ```bash ./ollama-bench -model qwen3-vl -image photo.jpg -epochs 6 -max-tokens 100 -p "Describe this image" ``` **测试参数**： | 参数 | 说明 | 默认值 | |------|------|--------| | -model | 待测试的模型列表（逗号分隔） | 必填 | | -epochs | 每个模型的迭代次数 | 6 | | -max-tokens | 模型响应的最大 token 数 | 200 | | -temperature | 采样温度参数 | 0.0 | | -seed | 随机种子 | 0（随机） | | -timeout | 超时时间（秒） | 300 | | -p | 提示文本 | 默认故事提示 | | -image | 包含在提示中的图像文件 | 空 | | -k | Keep-alive 持续时间（秒） | 0 | | -format | 输出格式（csv/json） | 默认格式 | 资料来源：[cmd/bench/README.md:1-50]() ## 图像生成引擎 除了语言模型推理，Ollama 还包含一个实验性的图像生成引擎，采用 MLX（Machine Learning Acceleration）技术实现。该引擎支持在 Apple Silicon 和 CUDA 设备上运行图像生成任务。 **构建和运行**： ```bash go build -o engine ./x/imagegen/cmd/engine ./engine -zimage -model /path/to/z-image -prompt "a cat" -output cat.png ``` **可用参数**： | 参数 | 说明 | 默认值 | |------|------|--------| | -width | 图像宽度 | 1024 | | -height | 图像高度 | 1024 | | -steps | 去噪步数 | 9 | | -seed | 随机种子 | 42 | 资料来源：[x/imagegen/cmd/engine/README.md:1-30]() ## 开发工作流 ### 桌面应用开发 桌面应用的开发采用前后端分离架构，前端使用 React + Vite 构建，后端使用 Go 语言。 ```mermaid graph LR A[前端开发] --> B[npm run dev] B --> C[Vite Dev Server] C --> D[热重载] E[后端开发] --> F[go run ./cmd/app] F --> G[API 服务] C --> H[端口 5173] G --> I[端口 3001] ``` **环境准备**： ```bash go install github.com/tkrajina/typescriptify-golang-structs/tscriptify@latest ``` **开发模式启动**： ```bash cd ui/app npm install npm run dev ``` ```bash go generate ./... && OLLAMA_DEBUG=1 go run ./cmd/app -dev ``` 开发模式启用以下特性： - 从 Vite 开发服务器加载 UI（端口 5173） - API 请求固定到本地端口 3001 - 支持跨域请求 - UI 热重载支持 资料来源：[app/README.md:20-40]() ### Runner 组件 Runner 是 Ollama 的轻量级推理组件，提供最小化的模型加载和推理 HTTP 服务。开发者可以使用 Runner 快速测试模型或构建自定义推理服务。 **基本用法**： ```bash ./runner -model ``` **API 端点**： | 端点 | 方法 | 功能 | |------|------|------| | /completion | POST | 文本补全 | | /embedding | POST | 嵌入向量生成 | **示例请求**： ```bash curl -X POST -H "Content-Type: application/json" -d '{"prompt": "hi"}' http://localhost:8080/completion curl -X POST -H "Content-Type: application/json" -d '{"prompt": "turn me into an embedding"}' http://localhost:8080/embedding ``` 资料来源：[runner/README.md:1-30]() ## 系统要求 ### 硬件要求 | 组件 | 最低要求 | 推荐配置 | |------|----------|----------| | 内存 | 8GB | 16GB 及以上 | | 存储 | 10GB 可用空间 | 50GB 及以上 | | GPU（可选） | NVIDIA GPU with CUDA / Apple Silicon / 兼容 Vulkan | 高端独立显卡 | ### 软件要求 | 平台 | 要求 | |------|------| | macOS | macOS 10.15+ | | Windows | Windows 10/11 | | Linux | Ubuntu 18.04+ 或等效发行版 | ## 下载和安装 用户可以通过以下方式获取 Ollama： | 平台 | 下载地址 | |------|----------| | macOS | https://github.com/ollama/app/releases/download/latest/Ollama.dmg | | Windows | https://github.com/ollama/app/releases/download/latest/OllamaSetup.exe | | Linux | 使用安装脚本或包管理器 | 资料来源：[app/README.md:1-10]() ## 扩展功能 ### 工具调用 Ollama 支持工具调用功能，允许模型在对话中调用外部工具来完成特定任务。主要支持的工具类型包括： - **网络搜索**：通过 `web_search` 工具进行实时信息搜索 - **网页抓取**：通过 `web_fetch` 工具获取网页内容 ```mermaid graph TD A[用户请求] --> B{是否需要工具} B -->|是| C[选择工具] C --> D[web_search] C --> E[web_fetch] D --> F[显示搜索结果] E --> G[显示抓取内容] F --> H[模型整合回复] G --> H B -->|否| I[直接生成回复] I --> H ``` 资料来源：[app/ui/app/src/components/Message.tsx:1-40]() ### 思考模式 Ollama 支持可配置的思考模式（Think Mode），用户可以根据需求选择不同的思考深度级别。该功能通过 `ThinkButton` 组件实现，提供下拉式选择界面。 | 思考级别 | 描述 | |----------|------| | 基础 | 快速响应，适用于简单问题 | | 标准 | 适度推理，平衡速度和深度 | | 深度 | 详细推理，适用于复杂问题 | 资料来源：[app/ui/app/src/components/ThinkButton.tsx:1-40]() ## 技术特点 ### Unicode 支持 Ollama 的推理引擎包含完整的 Unicode 处理能力，支持多种字符编码和国际化文本处理。核心的 Unicode 函数包括： | 函数 | 功能 | |------|------| | `unicode_len_utf8` | 计算 UTF-8 字符长度 | | `unicode_cpt_to_utf8` | 码点转 UTF-8 | | `unicode_cpt_from_utf8` | UTF-8 转码点 | 资料来源：[llama/llama.cpp/src/unicode.cpp:1-30]() ### 错误处理 系统提供完善的错误处理和展示机制，通过 `ErrorMessage` 组件向用户呈现运行错误，同时支持错误信息的链接渲染和格式化显示。 资料来源：[app/ui/app/src/components/ErrorMessage.tsx:1-30]() ## 总结 Ollama 是一个功能完善的大语言模型运行框架，通过模块化的架构设计，为用户提供了从模型管理、推理计算到应用集成的完整解决方案。其跨平台特性、多后端支持和丰富的 API 接口，使其成为在本地环境中部署和使用大语言模型的理想选择。项目采用开源模式开发，持续获得社区贡献和更新。 --- ## 系统架构 ### 相关页面 相关主题：[项目概述](#page-overview), [API 参考](#page-api-reference), [LLM 后端系统](#page-llm-backend)
相关源码文件 以下源码文件用于生成本页说明： - [llm/server.go](https://github.com/ollama/ollama/blob/main/llm/server.go) - [server/routes.go](https://github.com/ollama/ollama/blob/main/server/routes.go) - [server/sched.go](https://github.com/ollama/ollama/blob/main/server/sched.go) - [llama/llama.go](https://github.com/ollama/ollama/blob/main/llama/llama.go) - [discover/gpu.go](https://github.com/ollama/ollama/blob/main/discover/gpu.go) - [api/client.go](https://github.com/ollama/ollama/blob/main/api/client.go)
# 系统架构 ## 概述 Ollama 是一个本地大语言模型运行框架，旨在为用户提供简便的方式来下载、运行和管理各种大语言模型。其核心设计理念是将复杂的模型加载、推理调度和硬件加速封装成简洁的 API 接口，使开发者能够通过 REST API、Python SDK 或 JavaScript SDK 与本地运行的模型进行交互。 Ollama 的系统架构采用分层设计，从上到下依次为：API 层、服务层、调度层、LLM 运行时层和后端加速层。这种分层架构确保了各模块之间的低耦合和高内聚，便于扩展新的后端支持和完善调度策略。 ## 整体架构 Ollama 的系统架构可以用以下层次结构表示： ```mermaid graph TB subgraph "API 层" REST_API[REST API] Python_SDK[Python SDK] JS_SDK[JavaScript SDK] end subgraph "服务层" Routes[HTTP Routes] Handlers[Request Handlers] end subgraph "调度层" Scheduler[调度器 Sched] Queue[请求队列] LoadBalancer[负载均衡] end subgraph "LLM 运行时层" LLMServer[LLM Server] Session[会话管理] Tokenizer[分词器] end subgraph "后端加速层" GGML[GGML Library] CUDA[CUDA Backend] Metal[Metal Backend] Vulkan[Vulkan Backend] SYCL[SYCL Backend] end subgraph "硬件层" GPU[GPU 设备] CPU[CPU 设备] end REST_API --> Routes Python_SDK --> Routes JS_SDK --> Routes Routes --> Handlers Handlers --> Scheduler Scheduler --> LLMServer LLMServer --> GGML GGML --> CUDA GGML --> Metal GGML --> Vulkan GGML --> SYCL CUDA --> GPU Metal --> GPU Vulkan --> GPU SYCL --> GPU GGML --> CPU ``` ## 核心组件 ### API 层 Ollama 提供三层 API 接口供开发者使用： | 接口类型 | 端点 | 用途 | |---------|------|------| | REST API | `http://localhost:11434` | 直接 HTTP 调用 | | Python SDK | `pip install ollama` | Python 应用集成 | | JavaScript SDK | `npm i ollama` | Node.js 应用集成 | REST API 的核心端点包括： - `/api/chat` - 对话接口，支持流式输出 - `/api/generate` - 文本生成接口 - `/api/pull` - 模型下载接口，支持进度回调 资料来源：[README.md](https://github.com/ollama/ollama/blob/main/README.md) ### 服务层 服务层负责处理 HTTP 请求并将请求路由到相应的处理器。 #### 路由分发 Ollama 使用 Go 标准库的 HTTP 处理机制，通过 `server/routes.go` 文件定义路由规则。每个路由对应一个具体的业务处理函数，包括模型加载、推理执行、模型列表查询等功能。 ```go // 路由注册示意 func setupRoutes(mux *http.ServeMux) { mux.HandleFunc("/api/chat", handleChat) mux.HandleFunc("/api/generate", handleGenerate) mux.HandleFunc("/api/pull", handlePull) mux.HandleFunc("/api/models", handleListModels) } ``` 资料来源：[server/routes.go](https://github.com/ollama/ollama/blob/main/server/routes.go) ### 调度层 调度层是 Ollama 架构中的核心组件，负责管理模型的生命周期和请求的分发。 #### 调度器 (Scheduler) 调度器维护一个请求队列和已加载模型的映射关系。当请求到达时，调度器根据模型名称找到对应的运行实例，如果没有可用实例则创建新实例。 ```mermaid graph LR A[请求] --> B{模型已加载?} B -->|是| C[分配到现有实例] B -->|否| D{资源足够?} D -->|是| E[创建新实例] D -->|否| F[等待资源释放] E --> G[分配请求] F --> B C --> H[执行推理] G --> H ``` 调度器使用以下策略进行负载管理： - **模型隔离**：不同模型的请求分配到不同的运行实例 - **资源感知**：根据可用 GPU 显存和系统内存动态决定是否加载新模型 - **会话复用**：保持已加载模型实例活跃以减少加载延迟 资料来源：[server/sched.go](https://github.com/ollama/ollama/blob/main/server/sched.go) ### LLM 运行时层 LLM 运行时层负责实际执行模型的加载和推理操作。 #### LLM Server `llm/server.go` 实现了 LLM 服务的核心逻辑，包括： - 模型加载与初始化 - 推理请求处理 - 会话状态管理 - 分词(Tokenization)处理 ```go type LLMServer struct { model *llama.Model params *llama.InferenceParams session *Session } ``` 资料来源：[llm/server.go](https://github.com/ollama/ollama/blob/main/llm/server.go) #### 分词器 Ollama 集成 llama.cpp 的分词器实现，支持 UTF-8 编码的文本处理。分词器将输入文本转换为 token 序列，供模型处理。 ```cpp uint32_t unicode_cpt_from_utf8(const std::string & utf8, size_t & offset) { // UTF-8 解码实现 } ``` 资料来源：[llama/llama.cpp/src/unicode.cpp](https://github.com/ollama/ollama/blob/main/llama/llama.cpp/src/unicode.cpp) ### 后端加速层 Ollama 基于 GGML (General Graphical Model Library) 实现模型推理，支持多种硬件加速后端。 #### GGML 后端支持 | 后端 | 宏定义 | 适用场景 | |------|--------|----------| | CUDA | `GGML_USE_CUDA` | NVIDIA GPU | | Metal | `GGML_USE_METAL` | Apple Silicon | | Vulkan | `GGML_USE_VULKAN` | 跨平台 GPU | | SYCL | `GGML_USE_SYCL` | Intel GPU | | WebGPU | `GGML_USE_WEBGPU` | 浏览器环境 | | OpenCL | `GGML_USE_OPENCL` | 通用 GPU | | Hexagon | `GGML_USE_HEXAGON` | Qualcomm DSP | | BLAS | `GGML_USE_BLAS` | CPU 矩阵运算 | | CANN | `GGML_USE_CANN` | 华为昇腾 | ```cpp #ifdef GGML_USE_CUDA #include "ggml-cuda.h" #endif #ifdef GGML_USE_METAL #include "ggml-metal.h" #endif #ifdef GGML_USE_VULKAN #include "ggml-vulkan.h" #endif ``` 资料来源：[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) #### 量化支持 Ollama 支持多种量化格式以降低显存占用： | 量化类型 | 标识 | 说明 | |---------|------|------| | Q4_0 | 4位量化 | 基础量化 | | Q4_1 | 4位量化 | 改进精度 | | Q5_0 | 5位量化 | 更高精度 | | Q5_1 | 5位量化 | 最佳5位 | | Q8_0 | 8位量化 | 接近FP16 | | Q2_K | 2位K量化 | 极致压缩 | | Q3_K | 3位K量化 | 高压缩 | | Q4_K | 4位K量化 | 推荐使用 | | Q5_K | 5位K量化 | 高精度压缩 | | Q6_K | 6位K量化 | 最高精度压缩 | 资料来源：[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) ### GPU 发现层 GPU 发现模块负责检测系统中的可用计算设备，为后端选择提供依据。 #### 设备检测逻辑 ```go func DetectGPU() (GPUInfo, error) { // 检测 CUDA 设备 if cudaAvailable := checkCUDA(); cudaAvailable { return GPUInfo{Type: "cuda", Count: getCUDACount()}, nil } // 检测 Metal 设备 if metalAvailable := checkMetal(); metalAvailable { return GPUInfo{Type: "metal", Count: getMetalCount()}, nil } // 回退到 CPU return GPUInfo{Type: "cpu"}, nil } ``` 资料来源：[discover/gpu.go](https://github.com/ollama/ollama/blob/main/discover/gpu.go) ## 数据流 ### 推理请求处理流程 ```mermaid sequenceDiagram participant Client as 客户端 participant API as API 层 participant Route as 路由层 participant Sched as 调度器 participant LLM as LLM Server participant Backend as GGML 后端 Client->>API: POST /api/chat API->>Route: 解析请求 Route->>Sched: 调度请求 Sched->>LLM: 获取/创建实例 LLM->>Backend: 加载模型 Backend->>Backend: 执行推理 LLM->>LLM: 处理响应 Sched-->>Route: 返回结果 Route-->>API: 流式/完整响应 API-->>Client: 返回结果 ``` ### 模型下载与注册流程 ```mermaid graph LR A[请求下载模型] --> B[查询注册表] B --> C{Haven 模型?} C -->|是| D[直接下载] C -->|否| E[解析 Manifest] E --> F[下载 Manifest] F --> G[检查 Layer] G --> H[下载 Chunk] H --> I[验证校验和] I --> J{所有 Chunk 完成?} J -->|否| G J -->|是| K[组装模型文件] K --> L[注册到本地] ``` 资料来源：[server/internal/client/ollama/registry.go](https://github.com/ollama/ollama/blob/main/server/internal/client/ollama/registry.go) ## API 客户端集成 Ollama 提供多语言客户端 SDK，客户端层负责协议封装和请求发送。 ### Go 客户端 ```go import "github.com/ollama/ollama/api" client := api.Client{Endpoint: "http://localhost:11434"} resp, err := client.Chat(context.Background(), &api.ChatRequest{ Model: "gemma3", Messages: []api.Message{{Role: "user", Content: "你好"}}, }) ``` 资料来源：[api/client.go](https://github.com/ollama/ollama/blob/main/api/client.go) ### Python 客户端 ```python from ollama import chat response = chat(model='gemma3', messages=[ {'role': 'user', 'content': 'Why is the sky blue?'}, ]) print(response.message.content) ``` ### JavaScript 客户端 ```javascript import ollama from "ollama"; const response = await ollama.chat({ model: "gemma3", messages: [{ role: "user", content: "Why is the sky blue?" }], }); ``` ## 内存映射 Ollama 使用内存映射 (Memory Mapping) 技术加载模型文件，以提高加载速度和内存利用效率。 ### 跨平台实现 ```cpp #if defined(_POSIX_MAPPED_FILES) #include #include #endif #if defined(_WIN32) #include #endif ``` 资料来源：[llama/llama.cpp/src/llama-mmap.cpp](https://github.com/ollama/ollama/blob/main/llama/llama.cpp/src/llama-mmap.cpp) ## 配置与部署 ### 模型存储位置 Ollama 默认将模型存储在配置目录中，可通过设置界面或环境变量修改： | 配置项 | 说明 | 默认值 | |-------|------|--------| | `OLLAMA_MODELS` | 模型存储目录 | `~/.ollama/models` | | `OLLAMA_HOST` | 服务监听地址 | `127.0.0.1:11434` | | `OLLAMA_KEEP_ALIVE` | 模型保持加载时间 | `5m` | ### 开发模式 桌面应用支持开发模式以便于调试： ```bash OLLAMA_DEBUG=1 go run ./cmd/app -dev ``` 开发模式特性： - 从 Vite 开发服务器加载 UI - 启用 CORS 跨域支持 - 固定 API 端口 `127.0.0.1:3001` - 支持热重载 资料来源：[app/README.md](https://github.com/ollama/ollama/blob/main/app/README.md) ## 性能基准测试 Ollama 提供性能测试工具 `ollama-bench` 用于评估模型在不同配置下的表现。 ### 命令行选项 | 选项 | 说明 | 默认值 | |------|------|--------| | `-model` | 测试的模型名称 | 必填 | | `-epochs` | 迭代次数 | 6 | | `-max-tokens` | 最大输出 token 数 | 200 | | `-temperature` | 采样温度 | 0.0 | | `-seed` | 随机种子 | 随机 | | `-format` | 输出格式 (csv/json) | text | ### 使用示例 ```bash ./ollama-bench -model gemma3 -epochs 10 -temperature 0.7 -seed 42 ``` 资料来源：[cmd/bench/README.md](https://github.com/ollama/ollama/blob/main/cmd/bench/README.md) --- ## API 参考 ### 相关页面 相关主题：[系统架构](#page-architecture), [高级功能](#page-advanced-features)
相关源码文件 以下源码文件用于生成本页说明： - [api/types.go](https://github.com/ollama/ollama/blob/main/api/types.go) - [api/client.go](https://github.com/ollama/ollama/blob/main/api/client.go) - [server/routes.go](https://github.com/ollama/ollama/blob/main/server/routes.go) - [server/images.go](https://github.com/ollama/ollama/blob/main/server/images.go) - [server/create.go](https://github.com/ollama/ollama/blob/main/server/create.go) - [openai/openai.go](https://github.com/ollama/ollama/blob/main/openai/openai.go) - [docs/api.md](https://github.com/ollama/ollama/blob/main/docs/api.md)
# API 参考 Ollama 提供了一套完整的 REST API，用于运行和管理本地大语言模型。本文档详细描述所有 API 端点的使用方法、请求参数和响应格式。 ## 概述 Ollama API 服务默认运行在 `http://localhost:11434`，提供两种 API 兼容模式： - **原生 Ollama API**：Ollama 原生的聊天和生成接口 - **OpenAI 兼容 API**：兼容 OpenAI Chat Completions 格式的接口 - **Anthropic 兼容 API**：兼容 Anthropic Messages 格式的接口 ```mermaid graph TB subgraph "客户端" A[curl / HTTP 客户端] B[Python SDK] C[JavaScript SDK] end subgraph "API 层" D[原生 API /api/*] E[OpenAI 兼容 /v1/*] F[Anthropic 兼容 /v1/*] end subgraph "服务层" G[Server Handler] H[ollama.Client] end subgraph "后端" I[LLM Runner] J[Model Registry] end A --> D B --> D C --> D A --> E C --> F D --> G E --> G F --> G G --> H H --> I H --> J ``` 资料来源：[server/routes.go:1-50](https://github.com/ollama/ollama/blob/main/server/routes.go) ## 基础配置 ### CORS 配置 API 支持跨域请求，允许以下来源访问： | 配置项 | 说明 | 默认值 | |--------|------|--------| | `OLLAMA_ORIGINS` | 允许的来源列表 | `*` (允许所有) | CORS 配置支持通配符和浏览器扩展： ```go corsConfig := cors.DefaultConfig() corsConfig.AllowWildcard = true corsConfig.AllowBrowserExtensions = true ``` 资料来源：[server/routes.go:150-180](https://github.com/ollama/ollama/blob/main/server/routes.go) ### 请求头 所有 API 请求支持以下通用请求头： | 请求头 | 说明 | |--------|------| | `Content-Type` | 内容类型，通常为 `application/json` | | `Authorization` | 认证令牌（如需要） | | `User-Agent` | 用户代理标识 | | `Accept` | 接受的响应格式 | OpenAI 兼容性请求头也被支持： ```go "OpenAI-Beta", "x-stainless-arch", "x-stainless-async", "x-stainless-runtime", "x-stainless-runtime-version", ``` 资料来源：[server/routes.go:160-175](https://github.com/ollama/ollama/blob/main/server/routes.go) ## 核心 API 端点 ### 健康检查 #### GET / 检查 Ollama 服务状态。 **响应示例：** ```json { "version": "0.5.0" } ``` ### 模型操作 #### POST /api/create 从 GGUF 文件创建模型。 **请求体：** | 参数 | 类型 | 必需 | 说明 | |------|------|------|------| | `name` | string | 是 | 模型名称 | | `modelfile` | string | 否 | Modelfile 内容 | | `quantize` | string | 否 | 量化级别 | | `stream` | boolean | 否 | 是否流式响应 | **请求示例：** ```json { "name": "my-custom-model", "modelfile": "FROM ./model.bin\nPARAMETER temperature 0.7", "stream": true } ``` 资料来源：[server/create.go:1-50](https://github.com/ollama/ollama/blob/main/server/create.go) #### DELETE /api/delete 删除模型。 **请求体：** ```json { "name": "llama3:latest" } ``` #### POST /api/show 显示模型详细信息。 **请求体：** ```json { "name": "llama3:latest" } ``` **响应示例：** ```json { "modelfile": "FROM llama3\nPARAMETER temperature 0.8", "parameters": "temperature: 0.8\nnum_keep: 0", "template": "{{ .Prompt }}", "details": { "parent_model": "", "format": "gguf", "family": "llama", "families": ["llama"], "parameter_size": "8B", "quantization_level": "Q4_0" } } ``` ### 模型列表 #### GET /api/tags 获取本地已安装的模型列表。 **查询参数：** | 参数 | 类型 | 说明 | |------|------|------| | `name` | string | 过滤特定命名空间下的模型 | **响应示例：** ```json { "models": [ { "name": "llama3:latest", "modified_at": "2025-01-15T10:30:00Z", "size": 3826790912, "digest": "sha256:8e710c2b..." } ] } ``` 资料来源：[server/images.go:1-100](https://github.com/ollama/ollama/blob/main/server/images.go) ### 聊天接口 #### POST /api/chat 发送聊天消息并获取响应。 **请求体：** | 参数 | 类型 | 必需 | 说明 | |------|------|------|------| | `model` | string | 是 | 模型名称 | | `messages` | array | 是 | 消息数组 | | `stream` | boolean | 否 | 流式响应，默认 true | | `format` | string | 否 | 响应格式 (json) | | `options` | object | 否 | 模型选项 | | `keep_alive` | duration | 否 | 模型保持加载时间 | **消息对象结构：** | 字段 | 类型 | 说明 | |------|------|------| | `role` | string | 角色：`user`、`assistant`、`system`、`tool` | | `content` | string | 消息内容 | | `images` | array | 图片数据（用于多模态模型） | | `tool_calls` | array | 工具调用 | | `tool_call_id` | string | 工具调用 ID | | `name` | string | 发送者名称 | **请求示例：** ```bash curl http://localhost:11434/api/chat -d '{ "model": "gemma3", "messages": [ { "role": "user", "content": "Why is the sky blue?" } ], "stream": false }' ``` **响应示例：** ```json { "model": "gemma3", "created_at": "2025-01-15T10:30:00Z", "message": { "role": "assistant", "content": "The sky appears blue because..." }, "done": true, "total_duration": 5000000000, "load_duration": 1000000000, "prompt_eval_count": 10, "eval_count": 50 } ``` **流式响应：** ```json { "model": "gemma3", "created_at": "2025-01-15T10:30:00Z", "message": { "role": "assistant", "content": "The" }, "done": false } ``` 资料来源：[api/types.go:1-100](https://github.com/ollama/ollama/blob/main/api/types.go) ### 生成接口 #### POST /api/generate 基于提示词生成文本。 **请求体：** | 参数 | 类型 | 必需 | 说明 | |------|------|------|------| | `model` | string | 是 | 模型名称 | | `prompt` | string | 是 | 输入提示词 | | `system` | string | 否 | 系统提示词 | | `template` | string | 否 | 自定义模板 | | `context` | array | 否 | 上下文（对话历史） | | `stream` | boolean | 否 | 流式响应，默认 true | | `options` | object | 否 | 模型选项 | | `format` | string | 否 | 响应格式 | **模型选项 (options)：** | 参数 | 类型 | 说明 | |------|------|------| | `temperature` | float | 采样温度，0-2 之间 | | `seed` | int | 随机种子 | | `num_predict` | int | 最大生成 token 数 | | `top_k` | int | Top-K 采样 | | `top_p` | float | Top-P 采样 | | `num_ctx` | int | 上下文窗口大小 | | `repeat_last_n` | int | 重复惩罚 | | `repeat_penalty` | float | 重复惩罚因子 | **响应示例：** ```json { "model": "llama3", "response": "Generated text...", "done": true, "context": [1, 2, 3, ...], "total_duration": 5000000000, "load_duration": 1000000000, "prompt_eval_count": 10, "eval_count": 50, "eval_duration": 4000000000 } ``` 资料来源：[api/types.go:100-200](https://github.com/ollama/ollama/blob/main/api/types.go) ### 模型推送与拉取 #### POST /api/pull 从远程仓库拉取模型。 **请求体：** | 参数 | 类型 | 必需 | 说明 | |------|------|------|------| | `name` | string | 是 | 模型名称 | | `insecure` | boolean | 否 | 允许不安全连接 | | `stream` | boolean | 否 | 流式进度 | **流式进度响应：** ```json { "status": "pulling manifest", "digest": "sha256:...", "total": 3826790912 } ``` ```json { "status": "downloading", "digest": "sha256:...", "total": 3826790912, "completed": 1000000000 } ``` #### POST /api/push 推送模型到远程仓库。 **请求体：** | 参数 | 类型 | 必需 | 说明 | |------|------|------|------| | `name` | string | 是 | 模型名称 | | `insecure` | boolean | 否 | 允许不安全连接 | | `stream` | boolean | 否 | 流式进度 | #### POST /api/copy 复制模型。 **请求体：** ```json { "source": "llama3:latest", "destination": "my-llama3" } ``` ### 运行状态 #### GET /api/ps 获取当前运行的模型状态。 **响应示例：** ```json { "models": [ { "name": "llama3:latest", "model": "llama3", "size": 3826790912, "digest": "sha256:8e710c2b...", "expires_at": "2025-01-15T11:00:00Z", "size_vram": 3826790912 } ] } ``` ### 嵌入生成 #### POST /api/embeddings 生成文本嵌入向量。 **请求体：** | 参数 | 类型 | 必需 | 说明 | |------|------|------|------| | `model` | string | 是 | 模型名称 | | `prompt` | string | 是 | 输入文本 | **响应示例：** ```json { "model": "llama3", "embeddings": [[0.123, -0.456, 0.789, ...]] } ``` ## OpenAI 兼容 API Ollama 提供与 OpenAI API 兼容的端点，方便使用现有的 OpenAI SDK。 ### 聊天补全 #### POST /v1/chat/completions OpenAI 兼容的聊天补全接口。 **请求示例：** ```bash curl http://localhost:11434/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "gemma3", "messages": [ {"role": "user", "content": "Hello!"} ] }' ``` **请求参数：** | 参数 | 类型 | 说明 | |------|------|------| | `model` | string | 模型名称 | | `messages` | array | 消息数组 | | `temperature` | float | 采样温度 | | `max_tokens` | int | 最大 token 数 | | `stream` | boolean | 流式响应 | | `stop` | array/string | 停止词 | | `tools` | array | 可用工具 | | `tool_choice` | object | 工具选择策略 | **响应格式：** ```json { "id": "chatcmpl-xxx", "object": "chat.completion", "created": 1705310400, "model": "gemma3", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "Hello! How can I help you?" }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 10, "completion_tokens": 20, "total_tokens": 30 } } ``` 资料来源：[openai/openai.go:1-100](https://github.com/ollama/ollama/blob/main/openai/openai.go) ### 模型列表 #### GET /v1/models 获取可用模型列表。 **响应示例：** ```json { "object": "list", "data": [ { "id": "llama3:latest", "object": "model", "created": 1705310400, "owned_by": "ollama" } ] } ``` ### 嵌入生成 #### POST /v1/embeddings OpenAI 兼容的嵌入接口。 **请求示例：** ```bash curl http://localhost:11434/v1/embeddings \ -H "Content-Type: application/json" \ -d '{ "model": "llama3", "input": "The quick brown fox" }' ``` ## Anthropic 兼容 API Ollama 提供与 Anthropic Claude API 兼容的接口。 ### 消息接口 #### POST /v1/messages Anthropic 兼容的消息接口。 **请求示例：** ```bash curl http://localhost:11434/v1/messages \ -H "Content-Type: application/json" \ -H "x-api-key: any-string" \ -H "anthropic-version: 2023-06-01" \ -d '{ "model": "claude-3", "messages": [ {"role": "user", "content": "Hello!"} ], "max_tokens": 1024 }' ``` **请求参数：** | 参数 | 类型 | 说明 | |------|------|------| | `model` | string | 模型名称 | | `messages` | array | 消息数组 | | `system` | string | 系统提示词 | | `max_tokens` | int | 最大生成 token 数 | | `temperature` | float | 采样温度 | | `stream` | boolean | 流式响应 | | `tools` | array | 工具定义 | 资料来源：[docs/api.md:1-150](https://github.com/ollama/ollama/blob/main/docs/api.md) ## 工具调用 (Function Calling) ### 工具定义 ```json { "tools": [ { "type": "function", "function": { "name": "get_weather", "description": "获取指定城市的天气信息", "parameters": { "type": "object", "properties": { "city": { "type": "string", "description": "城市名称" } }, "required": ["city"] } } } ] } ``` ### 工具调用响应 ```json { "message": { "role": "assistant", "content": "", "tool_calls": [ { "id": "call_123", "type": "function", "function": { "name": "get_weather", "arguments": "{\"city\": \"Beijing\"}" } } ] } } ``` ### 工具结果反馈 ```json { "role": "tool", "content": "{\"temperature\": \"22°C\", \"condition\": \"Sunny\"}", "tool_call_id": "call_123" } ``` ## SDK 客户端 ### Python SDK ```bash pip install ollama ``` ```python from ollama import chat response = chat(model='gemma3', messages=[ { 'role': 'user', 'content': 'Why is the sky blue?', }, ]) print(response.message.content) ``` ### JavaScript SDK ```bash npm i ollama ``` ```javascript import { ollama } from "ollama"; const response = await ollama.chat({ model: "gemma3", messages: [{ role: "user", content: "Why is the sky blue?" }], }); console.log(response.message.content); ``` ### Go 客户端 ```go import "github.com/ollama/ollama/api" client, _ := api.ClientFromEnvironment() chat, _ := client.Chat(ctx, &api.ChatRequest{ Model: "llama3", Messages: []api.Message{ {Role: "user", Content: "Why is the sky blue?"}, }, }) fmt.Println(chat.Message.Content) ``` ## 错误处理 ### 错误响应格式 所有错误返回标准 JSON 格式： ```json { "error": { "code": "invalid_request", "message": "详细错误信息", "param": "参数名称" } } ``` ### HTTP 状态码 | 状态码 | 说明 | |--------|------| | 200 | 请求成功 | | 400 | 请求参数错误 | | 404 | 资源不存在 | | 500 | 服务器内部错误 | | 503 | 服务不可用（模型加载中） | ## 配置参数 ### 环境变量 | 变量 | 说明 | 默认值 | |------|------|--------| | `OLLAMA_HOST` | 服务监听地址 | `127.0.0.1:11434` | | `OLLAMA_MODELS` | 模型存储目录 | `~/.ollama/models` | | `OLLAMA_ORIGINS` | 允许的 CORS 来源 | `*` | | `OLLAMA_KEEP_ALIVE` | 模型保持时间 | `5m` | ### 运行时配置 模型运行时可以通过 `options` 参数配置： ```json { "model": "llama3", "options": { "temperature": 0.7, "top_p": 0.9, "num_ctx": 4096, "seed": 42 } } ``` ## 请求/响应流程 ```mermaid sequenceDiagram participant Client participant API as API Server participant Registry as Model Registry participant Runner as LLM Runner Client->>API: POST /api/chat API->>Registry: 查找模型 Registry-->>API: 模型路径 API->>Runner: 加载模型 Runner-->>API: 模型已加载 loop 流式生成 API->>Runner: 处理 token Runner-->>API: 生成 token API-->>Client: SSE 事件 end Runner-->>API: 完成 API-->>Client: 最终响应 ``` ## 性能指标 API 响应包含以下性能指标： | 字段 | 说明 | |------|------| | `total_duration` | 总请求耗时（纳秒） | | `load_duration` | 模型加载耗时（纳秒） | | `prompt_eval_count` | 提示词 token 数 | | `prompt_eval_duration` | 提示词处理耗时（纳秒） | | `eval_count` | 生成 token 数 | | `eval_duration` | 生成耗时（纳秒） | ## 最佳实践 ### 1. 流式响应 对于交互式应用，使用流式响应可以提供更好的用户体验： ```bash curl -X POST http://localhost:11434/api/chat \ -d '{"model": "llama3", "messages": [{"role": "user", "content": "Hello"}], "stream": true}' ``` ### 2. 连接复用 使用 HTTP keep-alive 减少连接开销： ```python import ollama client = ollama.Client() # 多个请求复用同一连接 for msg in conversation: response = client.chat(model='llama3', messages=conversation) ``` ### 3. 模型预热 首次请求会有模型加载延迟，可以预先触发： ```bash curl -X POST http://localhost:11434/api/generate \ -d '{"model": "llama3", "prompt": "warmup", "stream": false}' ``` ### 4. 上下文管理 合理管理上下文长度以优化性能： ```json { "model": "llama3", "options": { "num_ctx": 2048 } } ``` ## 相关文档 - [快速开始指南](https://docs.ollama.com/quickstart) - [API 完整文档](https://docs.ollama.com/api) - [OpenAPI 规范](./openapi.yaml) - [模型库](https://ollama.com/library) --- ## 模型管理 ### 相关页面 相关主题：[系统架构](#page-architecture), [模型转换系统](#page-model-conversion), [LLM 后端系统](#page-llm-backend)
相关源码文件 以下源码文件用于生成本页说明： - [server/images.go](https://github.com/ollama/ollama/blob/main/server/images.go) - [server/model.go](https://github.com/ollama/ollama/blob/main/server/model.go) - [server/model_resolver.go](https://github.com/ollama/ollama/blob/main/server/model_resolver.go) - [server/model_recommendations.go](https://github.com/ollama/ollama/blob/main/server/model_recommendations.go) - [server/model_caches.go](https://github.com/ollama/ollama/blob/main/server/model_caches.go) - [manifest/manifest.go](https://github.com/ollama/ollama/blob/main/manifest/manifest.go)
# 模型管理 Ollama 的模型管理是核心系统之一，负责模型的发现、下载、缓存、加载、版本控制和运行时管理。本页面详细介绍 Ollama 如何管理系统模型的生命周期。 ## 概述 Ollama 采用分层架构管理模型文件，核心组件包括： - **模型清单（Manifest）**：描述模型元数据、层信息和依赖关系 - **Blob 缓存**：存储模型的离散数据块，支持去重和复用 - **模型解析器**：解析 GGUF 格式和模型配置 - **模型加载器**：根据运行时后端加载模型进行推理 ```mermaid graph TD A[用户请求] --> B{模型是否存在?} B -->|否| C[下载模型清单] C --> D[解析 Manifest] D --> E[检查 Blob 缓存] E --> F{缺失 Blob?} F -->|是| G[下载缺失层] F -->|否| H[加载模型] G --> H H --> I[初始化推理后端] I --> J[返回模型实例] ``` ## 模型清单（Manifest） 模型清单是描述模型结构的核心数据结构，包含模型的完整元信息。 ### Manifest 结构 | 字段 | 类型 | 说明 | |------|------|------| | `Model` | string | 模型名称 | | `ModelURL` | string | 模型源 URL | | `Architectures` | []string | 支持的模型架构 | | `AdapterPath` | string | 适配器路径 | | `Capabilities` | []string | 模型能力列表 | | `Migrations` | map[string]string | 迁移映射 | 资料来源：[manifest/manifest.go:1-50](https://github.com/ollama/ollama/blob/main/manifest/manifest.go) ### Manifest 层结构 每个模型由多个层（Layer）组成，层是最小下载和缓存单元： ```go type ManifestLayer struct { Digest string // SHA256 哈希 Size int64 // 层大小 From *string // 来源模型 MediaType string // MIME 类型 Zdigest string // 压缩后哈希 Zsize int64 // 压缩后大小 } ``` 资料来源：[manifest/manifest.go:51-80](https://github.com/ollama/ollama/blob/main/manifest/manifest.go) ## Blob 缓存系统 Ollama 使用基于内容寻址的 Blob 缓存系统，所有模型数据以 SHA256 哈希作为唯一标识存储。 ### Blob 缓存策略 ```go // Blobs newer than this may belong to another process that has not written its // manifest yet. They become eligible for the normal mark-and-sweep pass later. const layerPruneGracePeriod = time.Hour ``` | 参数 | 默认值 | 说明 | |------|--------|------| | `layerPruneGracePeriod` | 1小时 | Blob 清理宽限期 | 资料来源：[server/images.go:29-33](https://github.com/ollama/ollama/blob/main/server/images.go) ### Blob 生命周期 ```mermaid stateDiagram-v2 [*] --> Downloaded: 下载完成 Downloaded --> Cached: 写入 Blob 目录 Cached --> InUse: 模型加载 InUse --> Cached: 模型卸载 Cached --> Pruned: 超过宽限期且未被引用 Pruned --> [*]: 删除文件 ``` ## 模型能力（Capabilities） Ollama 支持检测和管理模型的多种能力，确保模型与请求功能匹配。 ### 能力类型定义 | 能力标识 | 说明 | 错误类型 | |----------|------|----------| | `completion` | 文本补全 | `errCapabilityCompletion` | | `tools` | 工具调用 | `errCapabilityTools` | | `insert` | 上下文插入 | `errCapabilityInsert` | | `vision` | 视觉理解 | `errCapabilityVision` | | `audio` | 音频处理 | `errCapabilityAudio` | | `embedding` | 向量嵌入 | `errCapabilityEmbedding` | | `thinking` | 思考模式 | `errCapabilityThinking` | | `image` | 图像生成 | `errCapabilityImage` | 资料来源：[server/images.go:35-48](https://github.com/ollama/ollama/blob/main/server/images.go) ### 能力检查流程 ```mermaid graph LR A[请求] --> B{需要能力 X?} B -->|是| C[检查模型 Manifest] C --> D{模型支持 X?} D -->|否| E[返回 errCapabilities] D -->|是| F[继续处理] B -->|否| F ``` ## 模型下载与解析 ### 模型解析器 模型解析器负责从 GGUF 文件中提取元数据和配置信息： ```go // Model 解析关键步骤 1. 读取 GGUF 头部 2. 解析元数据键值对 3. 提取张量信息 4. 验证架构兼容性 ``` 资料来源：[server/model.go:1-100](https://github.com/ollama/ollama/blob/main/server/model.go) ### 模型推荐系统 当模型不可用或需要优化时，系统提供模型推荐： ```go type ModelRecommendation struct { Model string // 推荐模型名称 Reason string // 推荐原因 Alternatives []string // 备选方案 } ``` 资料来源：[server/model_recommendations.go:1-50](https://github.com/ollama/ollama/blob/main/server/model_recommendations.go) ## 模型缓存管理 ### 缓存结构 ```go type ModelCache struct { mu sync.RWMutex models map[string]*ModelInstance maxSize int64 currentSize int64 } ``` | 字段 | 类型 | 说明 | |------|------|------| | `models` | map | 已加载模型实例 | | `maxSize` | int64 | 最大缓存大小 | | `currentSize` | int64 | 当前缓存使用量 | 资料来源：[server/model_caches.go:1-60](https://github.com/ollama/ollama/blob/main/server/model_caches.go) ### 缓存淘汰策略 当缓存达到上限时，系统采用 LRU（最近最少使用）策略淘汰模型： ```mermaid graph TD A[加载新模型] --> B{缓存已满?} B -->|否| C[直接加载] B -->|是| D[查找 LRU 模型] D --> E[检查是否可以卸载] E -->|是| F[卸载并释放资源] F --> C E -->|否| G[等待或返回错误] ``` ## 模型解析流程 ```mermaid sequenceDiagram participant U as 用户 participant S as 服务器 participant M as Manifest participant B as Blob Cache participant R as Runner U->>S: 请求模型 "llama3" S->>M: 解析 Manifest M->>B: 检查 Blob 完整性 B-->>M: Blob 状态 M-->>S: 验证结果 S->>R: 初始化 Runner R->>B: 读取模型数据 B-->>R: 返回数据流 R-->>S: 模型就绪 S-->>U: 返回模型句柄 ``` ## 模型元数据 ### 模型配置结构 | 字段 | 说明 | |------|------| | `ModelFamily` | 模型家族（如 llama, gemma） | | `ModelType` | 模型类型（chat, completion, embedding） | | `Template` | 提示词模板 | | `Parameters` | 模型参数配置 | | `SystemPrompt` | 系统提示词 | 资料来源：[server/model.go:100-200](https://github.com/ollama/ollama/blob/main/server/model.go) ## 错误处理 ### 常见错误类型 | 错误类型 | 说明 | 处理方式 | |----------|------|----------| | `errInsecureProtocol` | 不安全的协议 | 拒绝下载 | | `errCapabilities` | 能力不匹配 | 返回可用能力列表 | | `errManifestNotFound` | 清单不存在 | 尝试重新发现 | | `errBlobNotFound` | Blob 缺失 | 触发重新下载 | 资料来源：[server/images.go:48-60](https://github.com/ollama/ollama/blob/main/server/images.go) ## 相关命令 ### 模型管理 CLI | 命令 | 说明 | |------|------| | `ollama list` | 列出已下载模型 | | `ollama pull ` | 下载模型 | | `ollama rm ` | 删除模型 | | `ollama show ` | 显示模型信息 | | `ollama cp ` | 复制模型 | ## 总结 Ollama 的模型管理系统通过以下核心机制实现高效的资源利用： 1. **内容寻址存储**：基于 SHA256 的 Blob 缓存消除重复数据 2. **分层清单**：Manifest 分层支持增量更新和部分下载 3. **能力检测**：运行时验证模型能力，确保功能匹配 4. **智能缓存**：LRU 策略平衡内存使用和模型切换性能 5. **错误恢复**：完善的错误处理支持自动重试和回退 --- ## LLM 后端系统 ### 相关页面 相关主题：[系统架构](#page-architecture), [模型管理](#page-model-management), [高级功能](#page-advanced-features)
相关源码文件 以下源码文件用于生成本页说明： - [llama/llama.cpp/src/llama.go](https://github.com/ollama/ollama/blob/main/llama/llama.go) - [llama/llama.cpp/src/llama-kv-cache.cpp](https://github.com/ollama/ollama/blob/main/llama/llama.cpp/src/llama-kv-cache.cpp) - [llama/llama.cpp/src/llama-mmap.cpp](https://github.com/ollama/ollama/blob/main/llama/llama.cpp/src/llama-mmap.cpp) - [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) - [ml/backend/ggml/ggml/src/gguf.cpp](https://github.com/ollama/ollama/blob/main/ml/backend/ggml/ggml/src/gguf.cpp) - [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)
# LLM 后端系统 Ollama 的 LLM 后端系统是整个项目的核心推理引擎，负责加载大语言模型、执行前向推理、管理计算资源以及协调 GPU/CPU 计算。该系统深度集成了 llama.cpp 库和 GGML（Georgi Gerganov's Machine Learning）张量库，为多种硬件平台提供统一的推理接口。 ## 系统架构概览 LLM 后端系统采用分层架构设计，从上到下依次为：Go 语言高级接口层、CGO 桥接层、C++ 核心计算层、以及硬件抽象后端层。这种分层设计使得上层 Go 应用能够透明地调用高性能 C++ 推理代码，同时支持多种硬件加速后端。 ```mermaid graph TD A[Go 应用层] --> B[CGO 接口层] B --> C[llama.cpp 核心层] C --> D[GGML 张量库] D --> E[硬件后端层] E --> F[GGML-CPU] E --> G[GGML-CUDA] E --> H[GGML-Metal] E --> I[GGML-Vulkan] E --> J[GGML-SYCL] K[GGUF 模型格式] --> C L[KV Cache 管理] --> C ``` ## 核心组件 ### llama.go 接口层 `llama/llama.go` 文件是 Ollama 提供的 Go 语言绑定，通过 CGO 技术调用底层的 C++ 代码。该文件定义了模型加载、推理执行、上下文管理等核心接口，是 Go 应用与 C++ 推理引擎之间的桥梁。 文件通过以下编译指令指定编译参数和头文件路径： ```go // #cgo CXXFLAGS: -std=c++17 // #cgo CPPFLAGS: -I${SRCDIR}/../include // #cgo CPPFLAGS: -I${SRCDIR}/../../../ml/backend/ggml/ggml/include import "C" ``` 资料来源：[llama/llama.go:1-10]() ### GGML 张量库 GGML 是 Ollama 后端系统的核心计算库，提供了张量运算、内存管理、以及多硬件后端支持。该库采用模块化设计，通过后端注册机制支持不同的硬件加速器。 #### 后端注册机制 GGML 通过后端注册表管理各种硬件加速后端，系统支持的后端类型包括： | 后端类型 | 宏定义 | 描述 | |---------|--------|------| | CPU | GGML_USE_CPU | x86/ARM CPU 计算 | | CUDA | GGML_USE_CUDA | NVIDIA GPU 加速 | | Metal | GGML_USE_METAL | Apple Silicon GPU | | Vulkan | GGML_USE_VULKAN | 跨平台 GPU API | | SYCL | GGML_USE_SYCL | Intel GPU/多平台 | | WebGPU | GGML_USE_WEBGPU | 浏览器/跨平台 | | ZDNN | GGML_USE_ZDNN | IBM zSeries | | OpenCL | GGML_USE_OPENCL | 通用 GPU | | Hexagon | GGML_USE_HEXAGON | Qualcomm DSP | | BLAS | GGML_USE_BLAS | CPU 矩阵运算 | | RPC | GGML_USE_RPC | 远程过程调用 | | CANN | GGML_USE_CANN | 华为昇腾 NPU | 资料来源：[ml/backend/ggml/ggml/src/ggml-backend-reg.cpp:1-70]() #### GGUF 模型格式 GGUF（Georgi Gerganov Universal Format）是 GGML 推荐的模型存储格式，定义了一套标准的数据类型映射机制。系统支持以下数据类型： | Go/C++ 类型 | GGUF 类型枚举 | |-------------|--------------| | uint8_t | GGUF_TYPE_UINT8 | | int8_t | GGUF_TYPE_INT8 | | uint16_t | GGUF_TYPE_UINT16 | | int16_t | GGUF_TYPE_INT16 | | uint32_t | GGUF_TYPE_UINT32 | | int32_t | GGUF_TYPE_INT32 | | float | GGUF_TYPE_FLOAT32 | | bool | GGUF_TYPE_BOOL | | std::string | GGUF_TYPE_STRING | 资料来源：[ml/backend/ggml/ggml/src/gguf.cpp:1-60]() ### Vulkan 计算后端 Vulkan 后端是 Ollama 支持的重要 GPU 加速方案，通过 SPIR-V 着色器实现张量运算。该后端的着色器代码由 `vulkan-shaders-gen.cpp` 动态生成，支持多种量化精度。 Vulkan 后端支持的量化类型包括： | 量化类型 | 描述 | |---------|------| | f32 | 32位浮点 | | f16 | 16位浮点 | | q4_0 | 4位量化版本0 | | q4_1 | 4位量化版本1 | | q5_0/q5_1 | 5位量化 | | q8_0 | 8位量化 | | q2_k/q3_k/q4_k/q5_k/q6_k | K-量化变体 | | iq1_s/iq1_m | 1位智能量化 | | iq2_xxs/iq2_xs/iq2_s | 2位智能量化 | 资料来源：[ml/backend/ggml/ggml/src/ggml-vulkan/vulkan-shaders/vulkan-shaders-gen.cpp:1-50]() ## KV 缓存管理 KV Cache（键值缓存）是 LLM 推理中的关键优化机制，通过缓存已计算的注意力键值对，避免重复计算历史 token 的注意力表示。 ### llama_kv_cache 类结构 Ollama 的 KV 缓存实现定义在 `llama-kv-cache.cpp` 中，提供了完整的缓存管理功能： ```cpp llama_kv_cache::llama_kv_cache( const llama_model & model, // 模型引用 ggml_type type_k, // 键的类型 ggml_type type_v, // 值的类型 bool v_trans, // 值转置标志 bool offload, // 是否卸载到 GPU bool unified, // 统一缓存模式 uint32_t kv_size, // 缓存大小 uint32_t n_seq_max, // 最大序列数 uint32_t n_pad, // 填充参数 uint32_t n_swa, // 滑动窗口大小 llama_swa_type swa_type, // 滑动窗口类型 const layer_filter_cb & filter, // 层过滤器 const layer_reuse_cb & reuse // 层重用回调 ); ``` 资料来源：[llama/llama.cpp/src/llama-kv-cache.cpp:1-50]() ### 缓存参数说明 | 参数 | 类型 | 说明 | |------|------|------| | model | llama_model& | 关联的模型对象 | | type_k/type_v | ggml_type | 键值张量的数据类型 | | v_trans | bool | 是否对 V 张量转置 | | offload | bool | 是否将缓存卸载到 GPU | | unified | bool | 统一模式（多序列共享缓存） | | kv_size | uint32_t | KV 缓存的槽位数量 | | n_seq_max | uint32_t | 同时处理的最大序列数 | | n_pad | uint32_t | 内存对齐填充大小 | ### 缓冲区管理 KV 缓存通过 `ggml_backend_buft_comparator` 比较器管理不同的缓冲区类型，确保内存分配顺序的一致性和可靠性。缓存支持动态扩展和序列级隔离，适用于多用户并发推理场景。 资料来源：[llama/llama.cpp/src/llama-kv-cache.cpp:30-45]() ## 内存映射管理 Ollama 使用内存映射（Memory Mapping）技术高效加载大型模型文件，减少内存占用并提高加载速度。`llama-mmap.cpp` 实现了跨平台的内存映射接口。 ### 平台特定实现 | 平台 | 头文件 | 功能 | |------|--------|------| | POSIX | unistd.h, sys/mman.h, sys/resource.h | POSIX 内存映射 | | Windows | windows.h | Win32 文件映射 | | macOS | TargetConditionals.h | Apple 平台适配 | 资料来源：[llama/llama.cpp/src/llama-mmap.cpp:1-40]() ### 内存锁定 对于需要长时间驻留内存的模型数据，系统支持内存锁定功能： ```cpp #if defined(_POSIX_MEMLOCK_RANGE) #include #endif ``` 这确保关键推理数据不会被操作系统换页到磁盘，保证推理延迟的稳定性。 资料来源：[llama/llama.cpp/src/llama-mmap.cpp:15-20]() ## Unicode 与文本处理 推理引擎内置了完整的 Unicode 文本处理能力，支持多语言输入和 tokenization。`unicode.cpp` 实现了 UTF-8 编码的解码和编码功能。 ### UTF-8 长度计算 ```cpp size_t unicode_len_utf8(char src) { const size_t lookup[] = { 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 2, 2, 3, 4 }; uint8_t highbits = static_cast(src) >> 4; return lookup[highbits]; } ``` 该函数通过查表方式快速判断 UTF-8 字符的字节长度，支持 1-4 字节的 UTF-8 编码。 资料来源：[llama/llama.cpp/src/unicode.cpp:1-35]() ## 推理工作流程 ```mermaid sequenceDiagram participant App as Go 应用 participant CGO as CGO 桥接层 participant Llama as llama.cpp 核心 participant GGML as GGML 库 participant Backend as GPU/CPU 后端 App->>CGO: 加载模型 (llama_load_model_from_file) CGO->>Llama: 调用 C++ 接口 Llama->>GGML: 初始化张量 GGML->>Backend: 选择最优后端 Backend-->>GGML: 后端就绪 GGML-->>Llama: 张量初始化完成 Llama-->>CGO: 模型句柄 CGO-->>App: 返回 Model 对象 App->>CGO: 执行推理 (llama_decode/llama_tokenize) CGO->>Llama: 前向传播 Llama->>GGML: 层计算 GGML->>Backend: 硬件加速计算 Backend-->>GGML: 计算结果 GGML-->>Llama: 输出张量 Llama-->>CGO: token 结果 CGO-->>App: 推理完成 ``` ## 错误处理机制 系统定义了统一的错误处理流程，包括跨平台错误码转换： ```cpp #if defined(_WIN32) static std::string llama_format_win_err(DWORD err) { LPSTR buf; size_t size = FormatMessageA( FORMAT_MESSAGE_ALLOCATE_BUFFER | FORMAT_MESSAGE_FROM_SYSTEM | FORMAT_MESSAGE_IGNORE_INSERTS, NULL, err, MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT), (LPSTR)&buf, 0, NULL); if (!size) { return "FormatMessageA failed"; } std::string ret(buf, size); LocalFree(buf); return ret; } #endif ``` 资料来源：[llama/llama.cpp/src/llama-mmap.cpp:40-55]() ## 编译配置 ### 交叉编译支持 llama.go 提供了 Windows 平台的特殊编译配置： ```go // #cgo windows CPPFLAGS: -D_WIN32_WINNT=0x0602 ``` 这确保在 Windows Vista 及以上版本使用最新的 API 特性。 ### C++ 标准 整个后端系统要求使用 C++17 标准编译，确保现代 C++ 特性的可用性： ```go // #cgo CXXFLAGS: -std=c++17 ``` ## 总结 Ollama 的 LLM 后端系统是一个高度模块化、高性能的推理引擎架构。通过深度集成 llama.cpp 和 GGML，它实现了： - **多后端支持**：统一接口管理 CPU、CUDA、Metal、Vulkan 等多种计算后端 - **高效内存管理**：通过内存映射和 KV 缓存技术优化资源利用 - **跨平台兼容**：支持 Linux、Windows、macOS 等主流操作系统 - **灵活的量化支持**：从 fp32 到 int2 多种精度选项 该架构设计使得 Ollama 能够在不同硬件环境下提供一致的推理体验，同时最大化利用硬件性能。 --- ## 命令行系统 ### 相关页面 相关主题：[项目概述](#page-overview), [系统架构](#page-architecture)
相关源码文件 以下源码文件用于生成本页说明： - [cmd/cmd.go](https://github.com/ollama/ollama/blob/main/cmd/cmd.go) - [cmd/interactive.go](https://github.com/ollama/ollama/blob/main/cmd/interactive.go) - [cmd/config/config.go](https://github.com/ollama/ollama/blob/main/cmd/config/config.go) - [cmd/launch/launch.go](https://github.com/ollama/ollama/blob/main/cmd/launch/launch.go) - [cmd/tui/tui.go](https://github.com/ollama/ollama/blob/main/cmd/tui/tui.go) - [cmd/start.go](https://github.com/ollama/ollama/blob/main/cmd/start.go)
# 命令行系统 ## 概述 Ollama 的命令行系统是用户与本地大语言模型交互的核心接口，提供模型管理、推理执行、配置管理等完整功能。该系统基于 Go 语言构建，采用模块化架构设计，通过 `cobra` 命令行框架实现层次化的命令结构。 命令行系统的主要职责包括：接收用户输入的命令、解析参数、执行相应的业务逻辑、格式化输出结果。整个系统遵循单一入口原则，通过 `cmd/cmd.go` 中的根命令统一调度所有子命令。 ## 架构设计 ### 整体架构图 ```mermaid graph TD A[命令行入口] --> B[根命令 RootCmd] B --> C[run 子命令] B --> D[serve 子命令] B --> E[pull 子命令] B --> F[push 子命令] B --> G[list 子命令] B --> H[show 子命令] B --> I[create 子命令] B --> J[ps 子命令] B --> K[stop 子命令] B --> L[rm 子命令] B --> M[copy 子命令] C --> N[启动推理服务] D --> O[后台服务模式] N --> P[TUI 交互界面] O --> Q[HTTP API 服务] P --> R[交互式输入处理] R --> S[流式响应渲染] S --> T[Unicode 文本处理] ``` ### 核心模块说明 | 模块路径 | 功能说明 | 依赖关系 | |---------|---------|---------| | `cmd/cmd.go` | 根命令定义与命令注册 | 依赖 cobra 框架 | | `cmd/start.go` | 应用启动入口与初始化 | 依赖 config、launch | | `cmd/interactive.go` | 交互式对话处理逻辑 | 依赖 tui 模块 | | `cmd/tui/tui.go` | 终端用户界面渲染 | 独立模块 | | `cmd/config/config.go` | 配置管理与持久化 | 依赖文件系统 | | `cmd/launch/launch.go` | 服务启动与进程管理 | 依赖系统调用 | ## 命令结构 ### 根命令设计 Ollama 的命令行采用树形命令结构，所有子命令都注册在根命令 `RootCmd` 下。根命令负责全局参数解析和环境变量处理，确保所有命令共享相同的配置上下文。 根命令定义了以下全局标志位： | 标志位 | 类型 | 默认值 | 说明 | |-------|------|-------|------| | `--verbose` | bool | false | 启用详细输出模式 | | `--host` | string | 空 | 指定服务地址 | | `--port` | int | 11434 | 指定服务端口 | | `--models` | string | 用户目录 | 模型存储路径 | | `--keepalive` | duration | 5m | 模型加载后保留时间 | 资料来源：[cmd/cmd.go:1-100]() ### 子命令详解 #### run 命令 `run` 命令用于启动模型推理并进入交互式对话模式。这是用户最常用的命令之一，支持直接传入模型名称即可开始对话。 ```mermaid graph LR A[ollama run llama3] --> B[加载模型权重] B --> C[初始化推理引擎] C --> D[启动 TUI 界面] D --> E[等待用户输入] E --> F[流式推理处理] F --> G[渲染响应结果] G --> E ``` 执行流程如下： 1. 解析模型名称和可选参数 2. 调用 `launch` 模块加载模型 3. 初始化推理上下文和令牌生成器 4. 启动交互式 TUI 界面 5. 处理用户输入并生成流式响应 资料来源：[cmd/interactive.go:1-150]() #### serve 命令 `serve` 命令将 Ollama 作为后台守护进程运行，提供 HTTP API 服务供外部调用。该模式下系统监听指定端口，响应来自客户端的推理请求。 启动参数说明： | 参数 | 说明 | 默认值 | |-----|------|-------| | `--host` | 绑定地址 | 127.0.0.1 | | `--port` | 监听端口 | 11434 | | `--log` | 日志级别 | info | | `--background` | 是否后台运行 | false | 服务启动后会创建 HTTP 服务器，注册推理、嵌入、模型管理等多个路由处理器。 资料来源：[cmd/launch/launch.go:1-100]() #### 模型管理命令 Ollama 提供完整的模型生命周期管理命令集： | 命令 | 功能 | 示例 | |-----|------|-----| | `pull` | 下载模型 | `ollama pull llama3` | | `push` | 上传模型 | `ollama push user/model` | | `list` | 列出本地模型 | `ollama list` | | `show` | 显示模型信息 | `ollama show llama3` | | `create` | 从 Modelfile 创建 | `ollama create custom --file Modelfile` | | `rm` | 删除模型 | `ollama rm llama3` | | `copy` | 复制模型 | `ollama copy src dest` | | `ps` | 查看运行中的模型 | `ollama ps` | | `stop` | 停止模型推理 | `ollama stop llama3` | 资料来源：[cmd/cmd.go:100-300]() ## 配置系统 ### 配置存储结构 Ollama 采用分层配置策略，支持环境变量、配置文件、命令行标志三种配置方式。配置按优先级从低到高排列为：默认配置 < 配置文件 < 环境变量 < 命令行参数。 ```mermaid graph TD A[配置加载] --> B[读取默认配置] B --> C[加载配置文件] C --> D[应用环境变量] D --> E[解析命令行参数] E --> F[最终配置合并] ``` 配置文件采用 TOML 格式存储在用户配置目录： | 平台 | 配置文件路径 | |-----|-------------| | Linux | `~/.config/ollama/config.toml` | | macOS | `~/Library/Application Support/ollama/config.toml` | | Windows | `%APPDATA%\ollama\config.toml` | 配置项包括：模型默认路径、日志级别、API 超时设置、GPU 内存限制等。 资料来源：[cmd/config/config.go:1-120]() ### 环境变量配置 Ollama 支持通过环境变量覆盖默认配置，主要环境变量列表如下： | 环境变量 | 类型 | 说明 | |---------|------|-----| | `OLLAMA_HOST` | string | 服务绑定地址 | | `OLLAMA_PORT` | int | 服务监听端口 | | `OLLAMA_MODELS` | string | 模型存储目录 | | `OLLAMA_KEEPALIVE` | duration | 模型保活时间 | | `OLLAMA_DEBUG` | bool | 调试模式开关 | | `OLLAMA_NOHISTORY` | bool | 禁用命令历史记录 | 资料来源：[cmd/config/config.go:200-280]() ## 交互式界面 ### TUI 组件架构 交互式对话界面（Terminal User Interface）由 `cmd/tui/tui.go` 模块实现，采用分层渲染架构。界面分为输入区、输出区、状态栏三个主要区域。 ```mermaid graph TD A[TUI 渲染器] --> B[Header 组件] A --> C[Message 组件] A --> D[Input 组件] A --> E[StatusBar 组件] B --> F[模型信息显示] B --> G[对话状态指示] C --> H[用户消息样式] C --> I[助手消息样式] C --> J[工具调用显示] D --> K[多行输入支持] D --> L[历史命令导航] E --> M[Token 计数] E --> N[处理状态] ``` 消息组件支持多种内容类型的渲染，包括纯文本、带格式文本、代码块、工具调用结果等。对于流式输出，系统采用增量渲染策略，边接收边显示。 资料来源：[cmd/tui/tui.go:1-200]() ### 输入处理流程 交互模式下的输入处理涉及多轮对话上下文管理和流式响应渲染。系统维护一个消息历史列表，每次交互时将用户输入追加到历史并携带完整上下文发送给推理引擎。 ```mermaid sequenceDiagram participant U as 用户 participant I as Input Handler participant M as Message Manager participant E as Engine participant R as Renderer U->>I: 输入文本 I->>M: 添加用户消息 M->>E: 发送带上下文的请求 E-->>R: 流式 Token R->>R: 增量渲染 E-->>M: 完成响应 M->>M: 添加助手消息 M->>U: 显示完整对话 ``` Unicode 文本处理模块负责正确的 UTF-8 编码解码和多语言字符渲染，确保中文、日文等非 ASCII 字符的正确显示。 资料来源：[cmd/interactive.go:150-300]() ## 启动流程 ### 应用初始化序列 Ollama 启动时经历一系列初始化步骤，从命令行解析到服务就绪的完整流程如下： ```mermaid flowchart TD A[程序入口 main] --> B[初始化日志系统] B --> C[加载用户配置] C --> D[解析命令行参数] D --> E{命令类型判断} E -->|run 命令| F[加载指定模型] E -->|serve 命令| G[初始化 HTTP 服务器] E -->|其他命令| H[执行对应操作] F --> I[启动 TUI 交互] G --> J[注册路由处理器] J --> K[开始监听请求] H --> L[执行完成后退出] I --> M[处理交互循环] K --> M ``` `cmd/start.go` 负责协调整个启动过程，包括信号处理、优雅关闭、超时控制等关键逻辑。系统支持通过 `SIGINT` 和 `SIGTERM` 信号优雅退出，确保正在进行的推理任务能够正常完成或保存状态。 资料来源：[cmd/start.go:1-150]() ### 进程生命周期管理 后台服务模式下的进程管理涉及端口占用检测、进程标识持久化、配置热更新等机制。启动时系统会在配置目录创建 PID 文件记录进程 ID，便于后续管理操作。 | 状态 | 说明 | 触发条件 | |-----|------|---------| | Starting | 启动中 | 进程启动 | | Ready | 就绪 | 服务绑定端口成功 | | Running | 运行中 | 处理推理请求 | | Stopping | 停止中 | 收到终止信号 | | Stopped | 已停止 | 进程退出 | 资料来源：[cmd/launch/launch.go:100-250]() ## 错误处理与日志 ### 错误分类 命令行系统对错误进行了分类处理，不同类型的错误对应不同的用户提示和恢复策略： | 错误类型 | 错误码前缀 | 处理方式 | 示例 | |---------|----------|---------|-----| | 模型加载错误 | `ERR_MODEL_LOAD` | 提示检查模型文件 | 模型文件损坏 | | 推理错误 | `ERR_INFERENCE` | 显示错误信息 | 内存不足 | | 网络错误 | `ERR_NETWORK` | 建议检查服务状态 | 端口被占用 | | 配置错误 | `ERR_CONFIG` | 提示修正配置 | 配置文件格式错误 | | 权限错误 | `ERR_PERMISSION` | 提示检查权限 | 无法写入模型目录 | 日志系统采用分级输出策略，可通过 `--verbose` 标志启用调试级别的日志输出。生产环境下建议使用默认的 info 级别，仅在排查问题时启用详细日志。 资料来源：[cmd/cmd.go:300-400]() ### 用户友好的错误提示 系统尽可能将内部错误转换为用户可理解的操作建议。例如，当模型加载失败时，不仅报告失败原因，还会建议可能的解决方案如重新下载模型、检查磁盘空间等。 ```go // 错误提示示例结构 type UserError struct { Message string // 面向用户的错误描述 Detail string // 技术细节（可选） Suggestion []string // 修复建议列表 DocsURL string // 相关文档链接 } ``` 资料来源：[cmd/interactive.go:300-380]() ## 扩展性与插件 ### 命令扩展机制 Ollama 预留了命令扩展接口，允许通过外部插件注册新的子命令。插件通过实现特定接口将自己注册到命令树中，无需修改核心代码即可扩展功能。 扩展命令的注册流程： 1. 插件加载时调用注册函数 2. 提供命令名称、处理器函数、参数模式 3. 系统将命令添加到根命令的子命令列表 4. 用户即可通过标准方式调用扩展命令 ### 配置扩展点 配置系统支持自定义配置项和配置验证器，插件可以声明自己的配置项并在配置文件中使用。配置变更支持热重载，无需重启服务即可应用新配置。 ## 总结 Ollama 的命令行系统提供了完善的模型管理和推理交互能力，通过模块化设计实现了良好的可维护性和扩展性。系统采用分层架构，将命令行解析、配置管理、用户界面、模型服务等职责分离，便于独立演进和测试。 核心设计特点包括：基于 cobra 框架的命令层次结构、分层配置系统带优先级覆盖、流式响应渲染的 TUI 交互、完整的模型生命周期管理命令集、以及友好的错误提示和日志系统。这些设计使得 Ollama 既适合作为命令行工具直接使用，也为作为后台服务提供了坚实基础。 --- ## 桌面应用程序 ### 相关页面 相关主题：[系统架构](#page-architecture), [命令行系统](#page-cli-system)
相关源码文件 以下源码文件用于生成本页说明： - [app/server/server.go](https://github.com/ollama/ollama/blob/main/app/server/server.go) - [app/ui/app.go](https://github.com/ollama/ollama/blob/main/app/ui/app.go) - [app/ui/ui.go](https://github.com/ollama/ollama/blob/main/app/ui/ui.go) - [app/webview/webview.go](https://github.com/ollama/ollama/blob/main/app/webview/webview.go) - [app/updater/updater.go](https://github.com/ollama/ollama/blob/main/app/updater/updater.go) - [app/tools/tools.go](https://github.com/ollama/ollama/blob/main/app/tools/tools.go) - [app/store/store.go](https://github.com/ollama/ollama/blob/main/app/store/store.go)
# 桌面应用程序 Ollama 桌面应用程序为 macOS 和 Windows 用户提供本地化的图形界面，使其能够在本地运行和管理大型语言模型。该应用程序集成了 WebView 渲染引擎、后端服务、模型管理功能以及自动更新机制，为用户提供了开箱即用的 AI 推理体验。 ## 架构概述 Ollama 桌面应用采用分层架构设计，将用户界面、后端服务和系统级功能解耦。这种设计使得各组件可以独立开发和测试，同时保持整体系统的协调一致。 ```mermaid graph TD A[用户界面层
React + TypeScript] --> B[WebView 渲染层
系统原生浏览器引擎] B --> C[Go 后端服务层
app/server] C --> D[核心推理引擎
Ollama Core] C --> E[模型存储
app/store] C --> F[自动更新
app/updater] C --> G[系统工具
app/tools] H[macOS/Windows
原生操作系统] --> I[系统集成
文件选择/网络配置] ``` | 层次 | 技术栈 | 职责 | |------|--------|------| | 用户界面层 | React + TypeScript + TailwindCSS | 交互式 UI 组件、消息展示、设置面板 | | WebView 渲染层 | 系统原生 WebView | HTML/CSS/JS 渲染、JavaScript 桥接 | | 后端服务层 | Go | HTTP 服务器、API 处理、系统集成 | | 核心推理层 | Ollama Core | 模型加载、推理执行、张量计算 | ## 核心组件 ### 服务器模块 `app/server/server.go` 实现了嵌入式 HTTP 服务器，负责处理前端请求和系统级操作。该模块提供了模型管理、对话处理、嵌入生成等核心功能的 API 端点。 服务器模块的关键职责包括： - 接收并处理来自 WebView 的 HTTP 请求 - 管理模型的生命周期（加载、卸载、切换） - 处理聊天完成和文本生成请求 - 提供嵌入向量计算接口 - 管理模型的下载进度跟踪 ### 用户界面模块 `app/ui/app.go` 和 `app/ui/ui.go` 共同构成了应用程序的前端核心。界面采用 React 组件化架构，主要包含以下功能模块： ```mermaid graph LR A[消息组件
Message.tsx] --> B[对话界面] C[模型选择器
ModelPicker.tsx] --> B D[设置面板
Settings.tsx] --> B E[下载进度
Downloading.tsx] --> B F[错误提示
ErrorMessage.tsx] --> B G[思考层级
ThinkButton.tsx] --> B ``` | 组件 | 文件位置 | 功能描述 | |------|----------|----------| | Message | app/ui/app/src/components/Message.tsx | 渲染对话消息，支持工具调用结果展示 | | ModelPicker | app/ui/app/src/components/ModelPicker.tsx | 模型列表展示与选择 | | Settings | app/ui/app/src/components/Settings.tsx | 应用配置、网络设置、用户账户管理 | | Downloading | app/ui/app/src/components/Downloading.tsx | 模型下载进度条展示 | | ErrorMessage | app/ui/app/src/components/ErrorMessage.tsx | 错误信息渲染与链接支持 | | ThinkButton | app/ui/app/src/components/ThinkButton.tsx | 思考层级下拉选择器 | 消息组件支持多种内容类型，包括普通文本、工具调用结果、Web 搜索摘要和 Web 抓取结果。当模型返回工具调用时，界面会展示工具名称、查询参数和原始 JSON 结果。资料来源：[app/ui/app/src/components/Message.tsx:Message.tsx]() ### WebView 集成 `app/webview/webview.go` 负责与操作系统原生 WebView 进行交互。该模块桥接了 Go 后端和前端 JavaScript 环境，使两者能够进行双向通信。 WebView 的核心功能包括： - 初始化原生浏览器引擎 - 注册 JavaScript 桥接接口 - 处理文件选择对话框（模型目录选择） - 管理应用窗口生命周期 资料来源：[app/webview/webview.go:webview.go]() ### 自动更新模块 `app/updater/updater.go` 实现了应用程序的自动更新机制。该模块会定期检查 Ollama 服务器以获取最新版本信息，并在后台下载更新包。 自动更新流程采用静默下载方式，不阻塞用户当前操作。用户可以在下次启动时选择安装更新，或者通过设置面板手动触发更新检查。 资料来源：[app/updater/updater.go:updater.go]() ### 工具系统 `app/tools/tools.go` 定义了应用程序可调用的系统工具集。这些工具扩展了 AI 模型的能力范围，使其能够执行超出纯文本生成的任务。 工具系统支持的典型功能包括： - **Web 搜索工具**：允许模型发起网络搜索请求并获取结果 - **Web 抓取工具**：获取指定 URL 的页面内容供模型分析 - **系统集成工具**：访问本地文件系统、触发系统通知等 资料来源：[app/tools/tools.go:tools.go]() ### 数据存储模块 `app/store/store.go` 负责管理应用程序的持久化数据。这包括用户设置、模型缓存信息、对话历史以及会话状态。 存储模块采用本地文件系统存储策略，所有数据默认保存在用户主目录下的 Ollama 应用数据文件夹中。模型文件单独存储在可配置的模型目录中。 资料来源：[app/store/store.go:store.go]() ## 设置面板功能 设置面板是用户配置应用程序的主要入口，提供以下配置选项： | 设置项 | 功能描述 | 可配置性 | |--------|----------|----------| | Expose | 是否将 Ollama 服务暴露到网络 | 用户开关 | | Models | 模型存储目录位置 | 仅查看，通过系统对话框选择 | | Cloud | 云端模型和 Web 搜索功能开关 | 受 OLLAMA_NO_CLOUD 环境变量约束 | | Auto Update | 自动更新检查开关 | 用户开关 | | 用户账户 | 登录、升级、管理账户信息 | 需联网 | 资料来源：[app/ui/app/src/components/Settings.tsx:Settings.tsx]() ## 开发环境搭建 ### 环境准备 开发桌面应用程序前需要安装以下工具： 1. Go 1.21 或更高版本 2. Node.js 18+ 和 npm 3. TypeScript 代码生成工具：`go install github.com/tkrajina/typescriptify-golang-structs/tscriptify@latest` ### UI 开发模式 UI 开发支持热重载功能，可大幅提升开发效率： ```bash # 终端 1：启动 React 开发服务器 cd ui/app npm install npm run dev # 终端 2：运行应用（带开发标志） go generate ./... OLLAMA_DEBUG=1 go run ./cmd/app -dev ``` `-dev` 标志启用以下开发特性： - 从 Vite 开发服务器（http://localhost:5173）加载 UI - 固定 API 请求端口至 http://127.0.0.1:3001 - 启用 CORS 跨域请求头 - 支持前端热重载 资料来源：[app/README.md:Development]() ### 生产构建 **Windows 构建流程：** ```powershell # 安装本地依赖 .\scripts\deps_local.ps1 # 或使用发布依赖 .\scripts\deps_release.ps1 0.6.8 # 执行构建 .\scripts\build_windows.ps1 ``` **macOS 构建流程：** ```bash # 设置 Xcode 开发工具路径 export DEVELOPER_DIR=/Applications/Xcode_14.1.0.app/Contents/Developer # 安装本地依赖 ./scripts/deps_local.sh # 或使用发布依赖 ./scripts/deps_release.sh 0.6.8 # 执行构建 ./scripts/build_darwin.sh ``` 资料来源：[app/README.md:Build]() ## 下载与发布 ### 下载地址 | 平台 | 下载链接 | |------|----------| | 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:Download]() ## 工作流程 ### 模型下载流程 当用户选择尚未安装的模型时，应用程序触发下载流程： ```mermaid sequenceDiagram participant U as 用户界面 participant S as 服务器模块 participant M as 模型存储 participant C as 核心引擎 U->>S: 请求下载模型 S->>M: 创建下载会话 M-->>U: 返回下载进度 loop 下载中 M-->>U: 更新下载百分比 end M->>C: 加载模型文件 C-->>U: 模型就绪通知 ``` 下载进度组件会实时显示已下载字节数和总字节数，并计算完成百分比。进度条采用动态宽度设计，百分比精确到个位。资料来源：[app/ui/app/src/components/Downloading.tsx:Downloading.tsx]() ### 思考层级配置 应用程序支持配置模型的思考层级（Thinking Level），这是一个实验性功能，允许用户控制模型在生成响应前的推理深度： ```mermaid graph TD A[用户点击思考按钮] --> B{下拉菜单展开} B --> C[选择层级] C --> D[更新当前配置] D --> E[下拉菜单关闭] E --> F[下次请求携带新层级] ``` 资料来源：[app/ui/app/src/components/ThinkButton.tsx:ThinkButton.tsx]() ## 技术实现要点 ### 组件优化 部分高频渲染的组件使用了 `React.memo` 进行性能优化，通过自定义比较函数避免不必要的重渲染： ```typescript export default React.memo(Message, (prevProps, nextProps) => { return ( prevProps.message === nextProps.message && prevProps.onEditMessage === nextProps.onEditMessage && prevProps.messageIndex === nextProps.messageIndex && prevProps.isStreaming === nextProps.isStreaming && prevProps.isFaded === nextProps.isFaded && prevProps.browserToolResult === nextProps.browserToolResult ); }); ``` 这种方法确保只有当消息内容或相关属性发生变化时才触发重新渲染，提升了对话界面的响应速度。 ### 深色模式支持 所有 UI 组件均支持深色模式，通过 TailwindCSS 的 `dark:` 前缀实现主题适配。颜色变量如 `text-neutral-500` 和 `dark:text-neutral-400` 允许界面自动适应系统主题设置。 ### WebView 桥接协议 前端与后端通过预定义的 JavaScript 接口进行通信。WebView 暴露的 `window.webview` 对象提供了以下能力： - `selectModelsDirectory()`：打开系统文件选择对话框 - 其他系统级操作接口 资料来源：[app/ui/app/src/components/Settings.tsx:Settings.tsx]() ## 相关资源 Ollama 桌面应用程序是 Ollama 整体生态系统的前端入口，它与核心推理引擎、API 服务、命令行工具共同构成了完整的本地 AI 运行平台。通过提供图形化界面，应用程序降低了用户使用本地大语言模型的门槛，同时保持了高性能和隐私保护的特性。 --- ## 高级功能 ### 相关页面 相关主题：[API 参考](#page-api-reference), [LLM 后端系统](#page-llm-backend), [系统架构](#page-architecture)
相关源码文件 以下源码文件用于生成本页说明： - [docs/capabilities/streaming.mdx](https://github.com/ollama/ollama/blob/main/docs/capabilities/streaming.mdx) - [docs/capabilities/tool-calling.mdx](https://github.com/ollama/ollama/blob/main/docs/capabilities/tool-calling.mdx) - [docs/capabilities/vision.mdx](https://github.com/ollama/ollama/blob/main/docs/capabilities/vision.mdx) - [docs/capabilities/embeddings.mdx](https://github.com/ollama/ollama/blob/main/docs/capabilities/embeddings.mdx) - [docs/capabilities/thinking.mdx](https://github.com/ollama/ollama/blob/main/docs/capabilities/thinking.mdx) - [tools/tools.go](https://github.com/ollama/ollama/blob/main/tools/tools.go) - [x/tools/registry.go](https://github.com/ollama/ollama/blob/main/x/tools/registry.go) - [x/tools/websearch.go](https://github.com/ollama/ollama/blob/main/x/tools/websearch.go) - [model/renderers/json.go](https://github.com/ollama/ollama/blob/main/model/renderers/json.go)
# 高级功能 Ollama 作为一款本地大语言模型运行框架，提供了丰富的**高级功能**，旨在增强 AI 模型的实用性、交互性和扩展性。这些功能包括流式输出、工具调用、多模态视觉支持、文本嵌入、思维推理模式等，使开发者能够在本地环境中构建复杂的 AI 应用，而无需依赖云端服务。 本文档详细介绍 Ollama 的各项高级功能，包括其工作原理、API 使用方式、配置选项以及实际应用场景。 --- ## 1. 流式输出（Streaming） ### 1.1 功能概述 流式输出是 Ollama 的一项核心功能，允许模型以流式方式逐步返回生成内容，而非等待完整响应生成完毕后再返回。这对于需要实时反馈的应用场景（如聊天机器人、实时写作辅助等）至关重要。 流式输出采用 **Server-Sent Events (SSE)** 协议实现，客户端可以逐步接收模型生成的内容，并在每个 token 生成时立即展示，提升用户体验。 ### 1.2 工作原理 ```mermaid graph TD A[客户端发送请求] --> B{启用 stream: true} B --> C[服务端开始生成] C --> D[生成单个 token] D --> E[通过 SSE 推送 token] E --> F[客户端接收并显示] F --> G{是否完成?} G -->|否| D G -->|是| H[发送完成事件] H --> I[关闭连接] ``` ### 1.3 API 调用示例 **生成端点流式请求：** ```bash curl -X POST http://localhost:11434/api/generate \ -H "Content-Type: application/json" \ -d '{ "model": "llama3", "prompt": "Write a story", "stream": true }' ``` **流式响应格式：** ```json {"model":"llama3","created_at":"2024-01-01T00:00:00Z","response":"从前","done":false} {"model":"llama3","created_at":"2024-01-01T00:00:00Z","response":"有一个","done":false} {"model":"llama3","created_at":"2024-01-01T00:00:00Z","response":"小女孩","done":true} ``` 资料来源：[docs/capabilities/streaming.mdx]() ### 1.4 前端组件实现 Ollama 的前端界面通过 `StreamingMarkdownContent` 组件处理流式内容渲染，该组件接收 `content` 和 `isStreaming` 属性，实时更新显示区域。 ```tsx ``` 资料来源：[app/ui/app/src/components/Message.tsx]() --- ## 2. 工具调用（Tool Calling） ### 2.1 功能概述 工具调用功能使大语言模型能够识别并调用外部工具来执行特定任务，突破了纯文本生成的能力限制。通过预定义工具注册机制，模型可以请求执行 Web 搜索、文件操作、计算任务等。 ### 2.2 架构设计 ```mermaid graph TD A[用户请求] --> B[模型分析请求] B --> C{需要调用工具?} C -->|否| D[直接生成响应] C -->|是| E[返回工具调用请求] E --> F[工具注册表查找] F --> G[执行工具] G --> H[返回结果] H --> I[模型整合结果] I --> J[生成最终响应] ``` ### 2.3 工具注册机制 Ollama 通过 `registry.go` 实现工具的注册与管理，支持多种类型的工具集成。 ```go // 工具注册表核心结构 type ToolRegistry struct { tools map[string]Tool } ``` 资料来源：[x/tools/registry.go]() **注册流程：** 1. 定义工具的结构和参数模式 2. 将工具注册到全局注册表 3. 模型通过 function calling 识别可调用工具 4. 执行工具并返回结果 ### 2.4 Web 搜索工具 Web 搜索是 Ollama 集成的重要工具之一，允许模型实时获取互联网信息。 ```go type WebSearchTool struct { Query string `json:"query"` } type WebSearchResult struct { Query string `json:"query"` Results []Result `json:"results"` } ``` 资料来源：[x/tools/websearch.go]() **搜索结果显示：** ```tsx {toolName === "web_search" && ( <> Search results for )} ``` 资料来源：[app/ui/app/src/components/Message.tsx]() ### 2.5 工具配置选项 | 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | Tools | boolean | false | 启用单轮工具模式 | | Agent | boolean | false | 启用代理模式 | | Tools Mode | enum | - | 工具使用级别控制 | 资料来源：[app/ui/app/src/components/Settings.tsx]() ### 2.6 工具调用界面 前端界面提供直观的工具调用展示，包括工具名称、参数和执行结果： ```tsx {message.tool_calls && message.tool_calls.length > 0 && (
{message.tool_calls.map((toolCall: ToolCall, index: number) => ( ))}
)} ``` 资料来源：[app/ui/app/src/components/Message.tsx]() --- ## 3. 多模态视觉支持（Vision） ### 3.1 功能概述 Ollama 支持多模态模型，能够处理图像输入并结合文本进行理解和分析。这使得用户可以上传图片并就图片内容进行问答、分析图表、描述场景等。 ### 3.2 支持的场景 - **图像描述**：生成图片的文字描述 - **视觉问答**：根据图片内容回答问题 - **文档分析**：理解截图、图表、表格 - **多图像处理**：同时分析多张图片 ### 3.3 API 调用示例 **使用图片提示生成描述：** ```bash ./ollama-bench -model qwen3-vl -image photo.jpg -epochs 6 -max-tokens 100 -p "Describe this image" ``` 资料来源：[cmd/bench/README.md]() **图像生成 API：** ```bash curl http://localhost:11434/v1/images/generations \ -H "Content-Type: application/json" \ -d '{ "model": "z-image", "prompt": "a white cat", "size": "1024x1024" }' ``` 资料来源：[x/imagegen/README.md]() ### 3.4 图像生成参数 | 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | model | string | required | 模型名称 | | prompt | string | required | 生成提示词 | | size | string | 1024x1024 | 图像尺寸 | | steps | int | 9 | 去噪步数 | | seed | int | 42 | 随机种子 | 资料来源：[x/imagegen/README.md]() --- ## 4. 文本嵌入（Embeddings） ### 4.1 功能概述 嵌入功能将文本转换为高维向量表示，使得语义相似的文本在向量空间中距离更近。这对于语义搜索、文本聚类、相似度匹配等应用至关重要。 ### 4.2 嵌入端点 ```bash curl -X POST -H "Content-Type: application/json" \ -d '{"prompt": "turn me into an embedding"}' \ http://localhost:8080/embedding ``` 资料来源：[runner/README.md]() ### 4.3 应用场景 - **语义搜索**：基于内容相似度而非关键词匹配 - **文档聚类**：将相关文档分组 - **推荐系统**：计算内容相似度 - **文本分类**：作为下游分类器的特征输入 资料来源：[docs/capabilities/embeddings.mdx]() --- ## 5. 思维推理模式（Thinking） ### 5.1 功能概述 思维推理模式允许模型在生成最终答案之前展示其推理过程，特别适合复杂问题解决和需要多步推理的任务。 ### 5.2 思维层级配置 Ollama 提供了多级思维模式配置，用户可以根据任务复杂度选择合适的推理深度： | 思维层级 | 描述 | 适用场景 | |----------|------|----------| | none | 无思维推理 | 简单问答 | | low | 基础推理 | 简单推理任务 | | medium | 中级推理 | 常规复杂问题 | | high | 深度推理 | 复杂多步推理 | 资料来源：[app/ui/app/src/components/ThinkButton.tsx]() ### 5.3 前端实现 ```tsx {Object.entries(THINKING_LEVELS).map(([, level]) => ( ))} ``` 资料来源：[app/ui/app/src/components/ThinkButton.tsx]() ### 5.4 工作流程 ```mermaid graph TD A[用户输入] --> B[选择思维层级] B --> C[模型进行内部推理] C --> D{是否显示推理过程?} D -->|是| E[输出推理步骤] D -->|否| F[直接输出结论] E --> F F --> G[最终响应] ``` --- ## 6. JSON 渲染器 ### 6.1 功能概述 Ollama 包含专门的 JSON 渲染器组件，用于格式化和展示结构化 JSON 数据，确保模型输出的 JSON 内容正确显示。 ### 6.2 核心结构 ```go type JSONRenderer struct { // 渲染配置 indent int sortKeys bool } ``` 资料来源：[model/renderers/json.go]() ### 6.3 渲染特性 - **语法高亮**：区分键、值、类型 - **格式化输出**：美化 JSON 缩进 - **错误检测**：识别无效 JSON --- ## 7. 模型下载与进度跟踪 ### 7.1 下载管理 Ollama 提供可视化的模型下载进度跟踪功能，用户可以实时查看下载状态。 ### 7.2 下载界面组件 ```tsx
``` 资料来源：[app/ui/app/src/components/Downloading.tsx]() ### 7.3 进度显示格式 ``` ${formatBytes(completed, unit)} / ${formatBytes(total, unit)} (${Math.floor(percentage)}%) ``` 资料来源：[app/ui/app/src/components/Downloading.tsx]() --- ## 8. 云端与本地配置 ### 8.1 配置项 Ollama 支持灵活的云端与本地模型切换配置： | 配置项 | 说明 | |--------|------| | Expose | 允许网络暴露 | | Models | 模型存储位置 | | Cloud | 启用云端模型 | | Auto Update | 自动更新功能 | 资料来源：[app/ui/app/src/components/Settings.tsx]() ### 8.2 环境变量控制 某些配置可被环境变量强制覆盖： ```tsx {cloudOverriddenByEnv ? "The OLLAMA_NO_CLOUD environment variable is currently forcing cloud off." : "Enable cloud models and web search."} ``` 资料来源：[app/ui/app/src/components/Settings.tsx]() --- ## 9. 总结 Ollama 的高级功能通过模块化设计，为本地 AI 应用开发提供了强大的能力支撑： | 功能模块 | 主要作用 | 技术实现 | |----------|----------|----------| | 流式输出 | 实时响应反馈 | SSE 协议 | | 工具调用 | 扩展模型能力 | 函数注册表 | | 视觉支持 | 多模态理解 | 图像处理管线 | | 文本嵌入 | 语义表示 | 向量编码 | | 思维推理 | 推理过程展示 | 分层思维模式 | 这些功能的组合使用，使开发者能够在本地环境中构建功能丰富、性能优秀的 AI 应用，同时保持对数据和模型的完全控制。 --- ## 部署与构建 ### 相关页面 相关主题：[项目概述](#page-overview), [系统架构](#page-architecture)
相关源码文件 以下源码文件用于生成本页说明： - [llama/README.md](https://github.com/ollama/ollama/blob/main/llama/README.md) - [app/README.md](https://github.com/ollama/ollama/blob/main/app/README.md) - [api/examples/README.md](https://github.com/ollama/ollama/blob/main/api/examples/README.md) - [cmd/bench/README.md](https://github.com/ollama/ollama/blob/main/cmd/bench/README.md) - [runner/README.md](https://github.com/ollama/ollama/blob/main/runner/README.md) - [x/imagegen/cmd/engine/README.md](https://github.com/ollama/ollama/blob/main/x/imagegen/cmd/engine/README.md) - [llama/llama.cpp/src/llama.go](https://github.com/ollama/ollama/blob/main/llama/llama.cpp/src/llama.go) - [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)
# 部署与构建 Ollama 是一个本地大语言模型运行框架，支持跨平台部署与构建。本文详细介绍 Ollama 的构建系统、支持的平台、环境配置以及各平台的构建流程。 ## 系统概述 Ollama 采用模块化架构设计，支持多种后端计算框架和硬件加速。构建系统基于 Makefile 和 Go 语言工具链，可生成适用于不同操作系统的可执行文件和容器镜像。 ```mermaid graph TD A[Ollama 源码] --> B[构建系统] B --> C[Linux 构建] B --> D[macOS 构建] B --> E[Windows 构建] B --> F[Docker 构建] C --> G[二进制文件] D --> G E --> G F --> H[Docker 镜像] G --> I[本地部署] H --> J[容器化部署] ``` 资料来源：[llama/README.md:1-20]() ## 环境准备 ### Go 语言环境 Ollama 主要使用 Go 语言开发，构建系统要求安装 Go 1.22 或更高版本。Go 环境变量配置如下： | 环境变量 | 说明 | 示例值 | |---------|------|--------| | `GOPATH` | Go 工作目录 | `$HOME/go` | | `GOROOT` | Go 安装路径 | `/usr/local/go` | | `CGO_ENABLED` | C 互操作启用 | `1` | 资料来源：[llama/llama.cpp/src/llama.go:1-10]() ### 系统依赖 不同平台需要安装相应的编译工具链和依赖库。 **Linux 平台依赖：** - GCC/G++ 编译器（支持 C++17） - CMake（用于 ggml 后端构建） - CUDA Toolkit（GPU 加速可选） - Vulkan SDK（GPU 加速可选） **macOS 平台依赖：** - Xcode 14.1 或更高版本 - Xcode 命令行工具 - Metal 框架（GPU 加速） **Windows 平台依赖：** - Visual Studio 2022 或更高版本 - MinGW-w64（部分构建场景） - Windows SDK 资料来源：[app/README.md:1-50]() ## 多平台构建流程 ### Linux 构建 Linux 平台是 Ollama 最主要的部署目标，支持完整的 GPU 加速功能。 ```bash # 安装系统依赖 sudo apt-get update sudo apt-get install -y build-essential cmake # 克隆源码 git clone https://github.com/ollama/ollama.git cd ollama # 构建可执行文件 go build -o ollama . ``` 资料来源：[llama/README.md:10-25]() ### macOS 构建 macOS 平台支持 Metal GPU 加速，通过 Xcode 工具链进行构建。 ```bash # 设置 Xcode 开发环境 export DEVELOPER_DIR=/Applications/Xcode_14.1.0.app/Contents/Developer export SDKROOT=/Applications/Xcode_14.1.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk # 设置编译优化参数 export CGO_CFLAGS="-O3 -mmacosx-version-min=12.0" export CGO_CXXFLAGS="-O3 -mmacosx-version-min=12.0" export CGO_LDFLAGS="-mmacosx-version-min=12.0" # 安装本地依赖 ./scripts/deps_local.sh # 执行构建 ./scripts/build_darwin.sh ``` 资料来源：[app/README.md:30-55]() ### Windows 构建 Windows 平台通过 PowerShell 脚本自动化构建流程。 ```powershell # 安装本地依赖 .\scripts\deps_local.ps1 # 或使用发布版本依赖 .\scripts\deps_release.ps1 0.6.8 # 执行构建 .\scripts\build_windows.ps1 ``` 资料来源：[app/README.md:20-30]() ## GPU 后端支持 Ollama 通过 ggml（GGML 库）支持多种 GPU 加速后端。 ```mermaid graph LR A[Ollama Core] --> B[ggml-backend-reg] B --> C[CPU Backend] B --> D[CUDA Backend] B --> E[Metal Backend] B --> F[Vulkan Backend] B --> G[SYCL Backend] B --> H[WebGPU Backend] C --> I[ARM/x86] D --> J[NVIDIA GPU] E --> K[Apple Silicon] F --> L[AMD/Intel GPU] ``` 资料来源：[ml/backend/ggml/ggml/src/ggml-backend-reg.cpp:1-60]() ### 后端编译条件 | 后端 | 编译宏 | 依赖 | |------|--------|------| | CPU | `GGML_USE_CPU` | 无 | | CUDA | `GGML_USE_CUDA` | CUDA Toolkit | | Metal | `GGML_USE_METAL` | Xcode/Metal SDK | | Vulkan | `GGML_USE_VULKAN` | Vulkan SDK | | SYCL | `GGML_USE_SYCL` | oneAPI | | WebGPU | `GGML_USE_WEBGPU` | Dawn | | CANN | `GGML_USE_CANN` | 华为昇腾 | | BLAS | `GGML_USE_BLAS` | OpenBLAS | 资料来源：[ml/backend/ggml/ggml/src/ggml-backend-reg.cpp:25-55]() ### Vulkan 后端构建 Vulkan 后端需要使用 GLSL 编译器将着色器代码编译为 SPIR-V 格式。 ```bash # 编译 Vulkan 着色器生成器 g++ -std=c++17 -o vulkan-shaders-gen vulkan-shaders-gen.cpp # 生成着色器头文件 ./vulkan-shaders-gen --input ./shaders --output /tmp/vulkan_shaders.hpp ``` 资料来源：[ml/backend/ggml/ggml/src/ggml-vulkan/vulkan-shaders/vulkan-shaders-gen.cpp:1-50]() ## Docker 部署 Ollama 提供官方 Docker 镜像，支持容器化部署。 ### Docker 构建 ```bash # 构建 Docker 镜像 docker build -t ollama/ollama:latest . # 运行容器 docker run -d \ --gpus all \ -v ollama:/root/.ollama \ -p 11434:11434 \ ollama/ollama:latest ``` 资料来源：[app/README.md:5-15]() ### Docker 构建脚本 构建系统提供自动化 Docker 构建脚本： ```bash # 执行 Docker 构建 ./scripts/build_docker.sh # 指定镜像标签 docker build -t ollama/ollama:custom-tag . ``` ## 轻量级 Runner Ollama 提供一个精简的 `runner` 模块，用于在资源受限环境中加载模型并提供 HTTP 推理服务。 ```bash # 构建 runner go build -o runner ./x/imagegen/cmd/engine # 启动 runner ./runner -model ``` ### Runner API 接口 | 端点 | 方法 | 说明 | |------|------|------| | `/completion` | POST | 文本补全 | | `/embedding` | POST | 向量嵌入生成 | 资料来源：[runner/README.md:1-25]() **完成请求示例：** ```bash curl -X POST \ -H "Content-Type: application/json" \ -d '{"prompt": "hi"}' \ http://localhost:8080/completion ``` **嵌入请求示例：** ```bash curl -X POST \ -H "Content-Type: application/json" \ -d '{"prompt": "turn me into an embedding"}' \ http://localhost:8080/embedding ``` ## API 示例 Ollama 提供 Go 语言 API 示例，帮助开发者集成推理功能。 ### 可用示例 | 示例 | 文件路径 | 说明 | |------|----------|------| | 聊天 | `api/examples/chat/main.go` | 与模型对话 | | 生成 | `api/examples/generate/main.go` | 文本生成 | | 流式生成 | `api/examples/generate-streaming/main.go` | 流式文本生成 | | 拉取进度 | `api/examples/pull-progress/main.go` | 模型拉取进度 | 资料来源：[api/examples/README.md:1-20]() ### 运行示例 ```bash # 运行聊天示例 go run api/examples/chat/main.go # 运行生成示例 go run api/examples/generate/main.go # 运行流式生成示例 go run api/examples/generate-streaming/main.go ``` ## 交叉编译支持 Ollama 支持交叉编译，可在单一平台构建其他平台的二进制文件。 ### 编译目标配置 | 目标平台 | GOOS | GOARCH | 额外配置 | |----------|------|--------|----------| | Linux AMD64 | `linux` | `amd64` | 无 | | Linux ARM64 | `linux` | `arm64` | 无 | | macOS AMD64 | `darwin` | `amd64` | Xcode SDK | | macOS ARM64 | `darwin` | `arm64` | Xcode SDK | | Windows AMD64 | `windows` | `amd64` | MinGW | ### 交叉编译示例 ```bash # 编译 Linux ARM64 版本 GOOS=linux GOARCH=arm64 CGO_ENABLED=1 go build -o ollama-linux-arm64 . # 编译 Windows 版本 GOOS=windows GOARCH=amd64 CGO_ENABLED=1 go build -o ollama.exe . ``` ## 性能基准测试 Ollama 提供 `ollama-bench` 工具用于性能评估。 ```bash # 基本用法 ./ollama-bench -model llama3 -epochs 6 # 指定提示词 ./ollama-bench -model gemma3 -epochs 6 -p "Write me a short story" # 带图像提示词 ./ollama-bench -model qwen3-vl -image photo.jpg -epochs 6 -max-tokens 100 -p "Describe this image" # 控制提示词长度 ./ollama-bench -model gemma3 -epochs 6 -prompt-tokens 512 # 高级配置 ./ollama-bench -model llama3 -epochs 10 -temperature 0.7 -max-tokens 500 -seed 42 -format csv -output results.csv ``` ### 基准测试参数 | 参数 | 说明 | 默认值 | |------|------|--------| | `-model` | 模型名称（必填） | - | | `-epochs` | 迭代次数 | 6 | | `-max-tokens` | 最大生成 token 数 | 200 | | `-temperature` | 采样温度 | 0.0 | | `-seed` | 随机种子 | 0（随机） | | `-timeout` | 超时时间（秒） | 300 | | `-format` | 输出格式 | - | 资料来源：[cmd/bench/README.md:1-40]() ## 图像生成引擎 Ollama 的图像生成功能基于独立的 MLX 引擎。 ### 构建图像生成引擎 ```bash go build -o engine ./x/imagegen/cmd/engine ``` ### 使用图像生成 ```bash ./engine -zimage -model /path/to/z-image -prompt "a cat" -output cat.png ``` ### 可选参数 | 参数 | 说明 | 默认值 | |------|------|--------| | `-width` | 图像宽度 | 1024 | | `-height` | 图像高度 | 1024 | | `-steps` | 去噪步数 | 9 | | `-seed` | 随机种子 | 42 | 资料来源：[x/imagegen/cmd/engine/README.md:1-30]() ## 桌面应用构建 Ollama 提供跨平台桌面应用，支持 macOS 和 Windows。 ### 桌面应用依赖 | 平台 | 构建脚本 | 说明 | |------|----------|------| | macOS | `scripts/build_darwin.sh` | 使用 Xcode 构建 | | Windows | `scripts/build_windows.ps1` | 使用 PowerShell 构建 | ### 开发模式启动 ```bash # 生成代码并启动开发服务器 go generate ./... go run ./cmd/app # 启用调试模式 OLLAMA_DEBUG=1 go run ./cmd/app -dev ``` ### UI 开发模式 1. 启动 React 开发服务器： ```bash cd ui/app npm install npm run dev ``` 2. 启动 Ollama 应用（带 `-dev` 参数）： ```bash go generate ./... OLLAMA_DEBUG=1 go run ./cmd/app -dev ``` 开发模式下 `-dev` 参数启用以下功能： - 从 Vite 开发服务器加载 UI（http://localhost:5173） - 固定 API 请求端口（http://127.0.0.1:3001） - 启用 CORS 跨域请求支持 - 支持热模块替换 资料来源：[app/README.md:55-90]() ## 版本与发布 Ollama 使用语义化版本号管理发布版本。发布构建需要： 1. 更新版本号文件 2. 生成变更日志 3. 执行完整测试套件 4. 构建所有平台版本 5. 签名并发布工件 ## 常见问题排查 | 问题 | 可能原因 | 解决方案 | |------|----------|----------| | CGO 编译失败 | 缺少 C/C++ 编译器 | 安装 GCC 或 Clang | | GPU 不可用 | 驱动未正确安装 | 更新 GPU 驱动程序 | | 内存不足 | 模型过大 | 选择更小的模型 | | 端口占用 | 11434 端口被占用 | 更换端口或释放端口 | ## 总结 Ollama 的构建系统设计灵活，支持从源码编译到 Docker 容器化部署的完整流程。开发者可根据目标平台和硬件环境选择合适的构建方式，利用多后端支持实现最优的推理性能。 --- ## 模型转换系统 ### 相关页面 相关主题：[模型管理](#page-model-management), [LLM 后端系统](#page-llm-backend), [部署与构建](#page-deployment)
相关源码文件 以下源码文件用于生成本页说明： - [convert/convert.go](https://github.com/ollama/ollama/blob/main/convert/convert.go) - [convert/convert_llama.go](https://github.com/ollama/ollama/blob/main/convert/convert_llama.go) - [convert/convert_qwen3.go](https://github.com/ollama/ollama/blob/main/convert/convert_qwen3.go) - [convert/convert_gemma3.go](https://github.com/ollama/ollama/blob/main/convert/convert_gemma3.go) - [convert/reader_safetensors.go](https://github.com/ollama/ollama/blob/main/convert/reader_safetensors.go) - [convert/reader_torch.go](https://github.com/ollama/ollama/blob/main/convert/reader_torch.go) - [tokenizer/tokenizer.go](https://github.com/ollama/ollama/blob/main/tokenizer/tokenizer.go) - [parser/parser.go](https://github.com/ollama/ollama/blob/main/parser/parser.go)
# 模型转换系统 ## 概述 Ollama 的模型转换系统（Model Conversion System）是核心组件之一，负责将来自不同训练框架（如 PyTorch）和不同模型格式（如 SafeTensors）的预训练模型转换为 Ollama 专有的运行时格式。该系统支持多种模型架构，包括 Llama、Qwen3、Gemma3 等主流开源大语言模型。 模型转换系统的主要职责包括： - 解析源模型文件的权重和配置 - 处理不同量化级别的模型参数 - 生成 Ollama 运行时所需的 GGUF/GGML 格式文件 - 验证转换后模型的完整性和正确性 ## 系统架构 ### 整体架构图 ```mermaid graph TD A[输入模型文件] --> B[解析层 Parser] B --> C[读取器 Readers] C --> D{模型类型检测} D -->|PyTorch| E[reader_torch.go] D -->|SafeTensors| F[reader_safetensors.go] E --> G[转换层 Converter] F --> G G --> H[模型特定转换器] H --> I[convert_llama.go] H --> J[convert_qwen3.go] H --> K[convert_gemma3.go] I --> L[分词器 Tokenizer] J --> L K --> L L --> M[GGUF/GGML 输出] ``` ### 核心组件说明 | 组件 | 文件路径 | 职责描述 | |------|----------|----------| | 解析器 | `parser/parser.go` | 解析输入配置和模型元数据 | | SafeTensors 读取器 | `convert/reader_safetensors.go` | 读取 SafeTensors 格式的模型权重 | | PyTorch 读取器 | `convert/reader_torch.go` | 读取 PyTorch 格式的模型权重 | | Llama 转换器 | `convert/convert_llama.go` | Llama 系列模型的专用转换逻辑 | | Qwen3 转换器 | `convert/convert_qwen3.go` | Qwen3 系列模型的专用转换逻辑 | | Gemma3 转换器 | `convert/convert_gemma3.go` | Gemma3 系列模型的专用转换逻辑 | | 分词器 | `tokenizer/tokenizer.go` | 处理模型关联的分词器资源 | ## 转换流程 ### 标准转换工作流 ```mermaid sequenceDiagram participant User as 用户 participant Parser as 解析器 participant Reader as 读取器 participant Converter as 转换器 participant Tokenizer as 分词器 participant Output as 输出文件 User->>Parser: 提交原始模型路径 Parser->>Parser: 读取模型配置和架构 Parser->>Reader: 加载权重数据 Reader-->>Parser: 返回权重映射 Parser->>Converter: 调用架构专用转换 Converter->>Converter: 应用量化参数 Converter->>Tokenizer: 获取分词器配置 Tokenizer-->>Converter: 返回分词器数据 Converter->>Output: 生成 GGUF 文件 Output-->>User: 转换完成 ``` ### 转换步骤详解 #### 第一阶段：模型解析 解析器负责读取输入模型的配置信息和元数据。这一阶段会： 1. 检测模型文件格式（PyTorch checkpoint 或 SafeTensors） 2. 读取模型架构配置（层数、隐藏维度、注意力头数等） 3. 识别模型家族（Llama、Qwen、Gemma 等） 资料来源：[parser/parser.go]() #### 第二阶段：权重读取 根据检测到的模型格式，选择对应的读取器： - **SafeTensors 读取器**：高效读取 SafeTensors 格式文件，支持内存映射 - **PyTorch 读取器**：处理传统的 PyTorch 模型检查点文件 资料来源：[convert/reader_safetensors.go]()[convert/reader_torch.go]() #### 第三阶段：模型转换 针对不同模型架构，应用特定的转换逻辑： | 模型系列 | 转换器文件 | 特殊处理 | |----------|------------|----------| | Llama | `convert_llama.go` | 标准 Transformer 结构 | | Qwen3 | `convert_qwen3.go` | Qwen 特有的 RoPE 和注意力机制 | | Gemma3 | `convert_gemma3.go` | Gemma 特有的规范化层 | 资料来源：[convert/convert_llama.go]()[convert/convert_qwen3.go]()[convert/convert_gemma3.go]() #### 第四阶段：分词器处理 转换过程的最后阶段涉及分词器资源的整合，确保转换后的模型能够正确地进行文本编码和解码。 资料来源：[tokenizer/tokenizer.go]() ## 核心转换接口 ### 主转换函数 ```go // convert/convert.go func Convert(modelPath string, outputPath string, options *ConvertOptions) error ``` | 参数 | 类型 | 说明 | |------|------|------| | modelPath | string | 源模型文件的路径 | | outputPath | string | 输出 GGUF 文件的目标路径 | | options | ConvertOptions | 转换选项（量化级别、参数精度等） | ### 转换选项结构 | 选项 | 默认值 | 说明 | |------|--------|------| | Quantization | Q4_0 | 量化级别（Q4_0、Q5_1、Q8_0 等） | | BatchSize | 512 | 推理批次大小 | | Threads | 自动 | CPU 线程数 | ## 量化支持 模型转换系统支持多种量化级别，以平衡模型大小和推理质量： | 量化类型 | 压缩率 | 质量影响 | 适用场景 | |----------|--------|----------|----------| | F16 | 100% | 无 | 高精度需求 | | Q5_1 | ~60% | 极小 | 资源受限环境 | | Q4_0 | ~50% | 较小 | 推荐默认选项 | | Q3_K | ~35% | 中等 | 极致压缩 | | Q2_K | ~25% | 较明显 | 最低资源 | 资料来源：[convert/convert.go]() ## 输出格式 转换系统输出的 GGUF（GGML Unified Format）文件包含以下组件： ``` GGUF 文件结构 ├── Header（文件头） ├── Metadata KV（元数据键值对） ├── Tensor Info（张量信息） ├── Tensor Data（张量数据） └── Padding（对齐填充） ``` GGUF 格式设计用于支持： - 内存映射加载 - 元数据内嵌 - 张量信息自描述 - 跨平台兼容性 ## 相关文件参考 | 文件 | 功能 | |------|------| | `llama/llama.cpp/src/gguf.cpp` | GGUF 格式底层实现 | | `llama/llama.cpp/src/unicode.cpp` | Unicode 处理支持 | | `ml/backend/ggml/ggml/src/ggml-cpu/quants.c` | CPU 量化实现 | 资料来源：[llama/llama.cpp/src/gguf.cpp]()[llama/llama.cpp/src/unicode.cpp]()[ml/backend/ggml/ggml/src/ggml-cpu/quants.c]() ## 使用示例 ### 命令行转换 ```bash ollama convert --input /path/to/model --output model.gguf --quantize q4_0 ``` ### API 调用 ```go err := convert.Convert( "/models/llama3-8b", "/output/llama3-8b-q4.gguf", &convert.ConvertOptions{ Quantization: "q4_0", }, ) ``` ## 注意事项 1. **模型兼容性**：仅支持已实现转换器的模型架构 2. **资源需求**：大模型转换需要足够的磁盘空间和内存 3. **量化损失**：量化会引入精度损失，请根据需求选择量化级别 4. **版本兼容**：转换后的 GGUF 文件需与 Ollama 版本兼容 --- --- ## Doramagic 踩坑日志 项目：ollama/ollama 摘要：发现 23 个潜在踩坑项，其中 7 个为 high/blocking；最高优先级：安装坑 - 来源证据：0.23.1 : mlx runner failed。 ## 1. 安装坑 · 来源证据：0.23.1 : mlx runner failed - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：0.23.1 : mlx runner failed - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_06acaa8b4f9d4923977e39f0de3349df | https://github.com/ollama/ollama/issues/16007 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。 ## 2. 安装坑 · 来源证据：Ollama Cloud: Frequent 503 errors making cloud models unreliable - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Ollama Cloud: Frequent 503 errors making cloud models unreliable - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_568af28cdfb04c3eaf66b648ffff865f | https://github.com/ollama/ollama/issues/15419 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。 ## 3. 安装坑 · 来源证据：Support `ppc64le` architecture - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Support `ppc64le` architecture - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_82122f2d4dfd4202a09101c78837de0e | https://github.com/ollama/ollama/issues/796 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。 ## 4. 配置坑 · 来源证据：Not compatible with Glaude code Cli when using local model - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Not compatible with Glaude code Cli when using local model - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_18239d63b211480fa37ec3c6dfb773ee | https://github.com/ollama/ollama/issues/16094 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。 ## 5. 配置坑 · 来源证据：Registering fine-tuned models - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Registering fine-tuned models - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_3417faf9df79457e841e34e3df365558 | https://github.com/ollama/ollama/issues/16095 | 来源类型 github_issue 暴露的待验证使用条件。 ## 6. 运行坑 · 来源证据：[Bug] 0.23.2 Image generation succeeds but no image saved to disk or returned via API" - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：[Bug] 0.23.2 Image generation succeeds but no image saved to disk or returned via API" - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_294d6c7549c44529a06895132ef49777 | https://github.com/ollama/ollama/issues/16072 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。 ## 7. 安全/权限坑 · 来源证据：Feature Request: Expose account quota/usage details via Ollama Cloud API (headers and/or response body) - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Feature Request: Expose account quota/usage details via Ollama Cloud API (headers and/or response body) - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_56cc99bad67b43a6b9a0ccff38aef5e2 | https://github.com/ollama/ollama/issues/15663 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。 ## 8. 安装坑 · 来源证据：VRAM Detection Issue on Radeon 780M (gfx1035) - Kernel Page Fault - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：VRAM Detection Issue on Radeon 780M (gfx1035) - Kernel Page Fault - 对用户的影响：可能阻塞安装或首次运行。 - 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_26de977c783d40308b5962cd61c7a1df | https://github.com/ollama/ollama/issues/16040 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。 ## 9. 配置坑 · 来源证据：mistral-medium-3.5 - Produces nonsense outputs - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：mistral-medium-3.5 - Produces nonsense outputs - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_5516e9097bb34de3a29210537c23e393 | https://github.com/ollama/ollama/issues/15975 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。 ## 10. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 建议检查：将假设转成下游验证清单。 - 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。 - 证据：capability.assumptions | github_repo:658928958 | https://github.com/ollama/ollama | README/documentation is current enough for a first validation pass. ## 11. 运行坑 · 来源证据：SIGSEGV in MLX VAE decode after diffusion steps complete on M4 Pro (macOS 26.4.1, Ollama 0.23.2) - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：SIGSEGV in MLX VAE decode after diffusion steps complete on M4 Pro (macOS 26.4.1, Ollama 0.23.2) - 对用户的影响：可能阻塞安装或首次运行。 - 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_b8c07744d01f41b392c0ce87ebda37b4 | https://github.com/ollama/ollama/issues/16093 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。 ## 12. 运行坑 · 来源证据：ollama run 交互模式无法拖拽/粘贴图片 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：ollama run 交互模式无法拖拽/粘贴图片 - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_fc1e1d2e0e8e441d88c14ea3f7e6316e | https://github.com/ollama/ollama/issues/16091 | 来源类型 github_issue 暴露的待验证使用条件。 ## 13. 运行坑 · 来源证据：v0.23.0 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.23.0 - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_3c18127a820d4532885af7c07b2cf3c6 | https://github.com/ollama/ollama/releases/tag/v0.23.0 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。 ## 14. 维护坑 · 来源证据：Featured your project on osalt.dev — README badge available if you'd like to use it - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Featured your project on osalt.dev — README badge available if you'd like to use it - 对用户的影响：可能影响升级、迁移或版本选择。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_d786a153134241388add2323ae688dfa | https://github.com/ollama/ollama/issues/16092 | 来源类型 github_issue 暴露的待验证使用条件。 ## 15. 维护坑 · 来源证据：Running qwen3.6:27b-bf16 on an AMD Ryzen AI Max leads to gibberish - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Running qwen3.6:27b-bf16 on an AMD Ryzen AI Max leads to gibberish - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_ccd9e90075d24d39bf6fd43ae8b41221 | https://github.com/ollama/ollama/issues/15879 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。 ## 16. 维护坑 · 来源证据：Running qwen3.6:27b-q8_0 produces also gibberish on an AMD Ryzen AI Max+ - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Running qwen3.6:27b-q8_0 produces also gibberish on an AMD Ryzen AI Max+ - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_4c22a5e593dd4d5b85e18cf0a5f790f4 | https://github.com/ollama/ollama/issues/15903 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。 ## 17. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。 - 防护动作：维护活跃度未知时，推荐强度不能标为高信任。 - 证据：evidence.maintainer_signals | github_repo:658928958 | https://github.com/ollama/ollama | last_activity_observed missing ## 18. 安全/权限坑 · 下游验证发现风险项 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：下游已经要求复核，不能在页面中弱化。 - 建议检查：进入安全/权限治理复核队列。 - 防护动作：下游风险存在时必须保持 review/recommendation 降级。 - 证据：downstream_validation.risk_items | github_repo:658928958 | https://github.com/ollama/ollama | no_demo; severity=medium ## 19. 安全/权限坑 · 存在安全注意事项 - 严重度：medium - 证据强度：source_linked - 发现：No sandbox install has been executed yet; downstream must verify before user use. - 对用户的影响：用户安装前需要知道权限边界和敏感操作。 - 建议检查：转成明确权限清单和安全审查提示。 - 防护动作：安全注意事项必须面向用户前置展示。 - 证据：risks.safety_notes | github_repo:658928958 | https://github.com/ollama/ollama | No sandbox install has been executed yet; downstream must verify before user use. ## 20. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 建议检查：把风险写入边界卡，并确认是否需要人工复核。 - 防护动作：评分风险必须进入边界卡，不能只作为内部分数。 - 证据：risks.scoring_risks | github_repo:658928958 | https://github.com/ollama/ollama | no_demo; severity=medium ## 21. 安全/权限坑 · 来源证据：v0.23.1 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.23.1 - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_a04a5f2703d24cc9aa072bdfcdc5552c | https://github.com/ollama/ollama/releases/tag/v0.23.1 | 来源类型 github_release 暴露的待验证使用条件。 ## 22. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 建议检查：抽样最近 issue/PR，判断是否长期无人处理。 - 防护动作：issue/PR 响应未知时，必须提示维护风险。 - 证据：evidence.maintainer_signals | github_repo:658928958 | https://github.com/ollama/ollama | issue_or_pr_quality=unknown ## 23. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 建议检查：确认最近 release/tag 和 README 安装命令是否一致。 - 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。 - 证据：evidence.maintainer_signals | github_repo:658928958 | https://github.com/ollama/ollama | release_recency=unknown