Article

模型部署 Ollama

更新于：2026-07-20

第一章：Ollama 概述与核心概念

1.1 什么是 Ollama

概念名称说明注意事项
Ollama一个轻量级、本地优先的大型语言模型（LLM）运行框架，支持在本地设备上部署和运行各类开源模型（如 Llama、Mistral、Gemma 等）。主要面向开发者和研究人员，强调易用性与本地化部署，不依赖云端服务。
开源与本地运行Ollama 允许用户在无网络连接的情况下运行模型，所有数据处理均在本地完成。保障数据隐私，适合处理敏感信息，但需本地具备足够的计算资源（尤其是 GPU）。
命令行驱动提供简洁的 CLI 工具，通过命令即可完成模型下载、运行、定制和管理。用户需熟悉基本命令行操作，适合集成到脚本或自动化流程中。
模型封装格式使用自定义的模型封装机制（基于 Modelfile），便于模型共享与版本管理。类似 Docker 镜像机制，支持构建、推送、拉取等操作。

1.2 Ollama 的设计目标与适用场景

设计目标/适用场景说明注意事项
简化本地 LLM 部署降低运行大模型的技术门槛，无需复杂配置即可启动模型。特别适合初学者和快速原型开发。
支持多种模型架构兼容主流开源模型（Llama 系列、Mistral、Phi、Qwen、Gemma 等）。模型兼容性持续扩展，可通过 Modelfile 自定义加载方式。
资源优化自动适配 CPU/GPU（CUDA、Metal），支持量化模型以减少显存占用。在消费级设备上也能运行中等规模模型（如 7B 参数级别）。
可扩展性提供 API 接口，便于集成到应用、框架（如 LangChain）或 Web UI 中。支持 RESTful API 和 Python 客户端，适合构建 AI 应用。
适用场景：开发测试快速验证模型能力、提示工程、本地推理测试。不依赖云服务，节省成本，适合离线环境使用。
适用场景：教育科研教学演示、学生实验、模型微调研究等。数据可控，便于分析模型行为。
适用场景：私有部署企业内部知识问答、文档处理、代码生成等需数据保密的场景。需注意模型本身的知识截止日期和准确性限制。

1.3 核心术语解析（模型、提示词、上下文、量化等）

术语说明注意事项
模型（Model）指训练好的大型语言模型（如 llama3:8b、mistral:7b），包含参数和结构信息。不同模型在性能、速度、知识广度上有差异，选择需权衡资源与需求。
提示词（Prompt）用户输入给模型的文本指令或问题，用于引导模型生成响应。提示词设计质量直接影响输出效果，可结合系统提示（SYSTEM）优化行为。
上下文（Context）模型在生成响应时能”记住”的历史对话或输入文本长度，通常以 token 数衡量。默认上下文长度有限（如 2048、4096），过长可能导致截断或性能下降。
Token文本的基本单位，一个 token 可能是一个词、子词或标点符号。中文通常一个汉字 ≈ 1~2 个 token，英文单词按子词切分。
量化（Quantization）通过降低模型参数精度（如从 float32 到 int4）来减小模型体积和运行资源消耗。量化会轻微损失精度，但显著提升运行效率，适合本地部署。
Modelfile定义模型构建过程的配置文件，类似 Dockerfile，用于定制模型行为。可设置基础模型、系统提示、参数、适配器等，是模型定制的核心。
GGUFGeoff’s GGUF Format，一种用于存储大模型的二进制格式，支持量化和快速加载。Ollama 内部使用 GGUF 格式管理本地模型文件，用户通常无需直接操作。
本地推理（Local Inference）在用户本地设备上执行模型计算，而非调用远程 API。保障隐私，但依赖本地硬件性能，尤其是 GPU 显存。

第二章：安装与环境配置

2.1 支持的操作系统与硬件要求

操作系统/硬件支持情况与要求注意事项
macOS支持 Intel 和 Apple Silicon（M1/M2/M3）芯片，推荐 macOS 10.15+Apple Silicon 性能更优，可利用 Metal 加速 GPU 运算。
Linux支持主流发行版（Ubuntu 20.04+、Debian、Fedora、Arch 等），x86_64 和 ARM64 架构。需确保内核版本较新，部分功能依赖 GLIBC 版本。
Windows支持 Windows 10/11，64 位系统，需启用 WSL2（Windows Subsystem for Linux）原生 Windows 支持正在开发中，当前推荐使用 WSL2 以获得完整功能。
CPU支持 x86_64 和 ARM64 架构无 GPU 时依赖 CPU 推理，响应速度较慢，建议至少 4 核以上。
GPU支持 NVIDIA（CUDA）、Apple Silicon（Metal）、实验性支持 AMD（ROCm）NVIDIA 显卡需安装 CUDA 驱动；Apple Silicon 自动启用 Metal 加速。
内存（RAM）推荐 8GB 以上，运行 7B 模型至少需 8GB，13B 及以上建议 16GB 或更高内存不足可能导致模型加载失败或运行缓慢。
显存（VRAM）4-bit 量化 7B 模型约需 6GB，13B 模型约需 10GB显存不足时自动回退到 CPU 推理，性能显著下降。
磁盘空间至少 10GB 可用空间，具体取决于模型大小（7B 模型约 4-6GB，13B 约 8-12GB）模型缓存和多个版本会占用更多空间，建议 SSD 提升加载速度。

2.2 安装 Ollama（Windows / macOS / Linux）

操作系统安装方法操作细节注意事项
macOS官方安装脚本或下载 dmg 安装包终端执行：curl -fsSL https://ollama.com/install.sh | sh也可从官网下载 .dmg 安装包直接安装。
Linux使用官方安装脚本终端执行：curl -fsSL https://ollama.com/install.sh | sh支持通过包管理器手动安装，但官方脚本最便捷。
Windows通过 WSL2 安装1. 启用 WSL2 并安装 Ubuntu 发行版
2. 在 WSL 终端执行安装脚本		原生 Windows 安装尚未正式发布，WSL2 是当前推荐方式，需配置网络和文件共享。
所有平台验证安装安装完成后执行 ollama --version 检查版本若命令未找到，请检查 PATH 或重启终端。

2.3 验证安装与基础运行测试

步骤名称操作细节注意事项
检查版本执行命令：ollama --version应输出类似 ollama version 0.1.x 的信息
启动 Ollama 服务执行命令：ollama serve（可选，大多数命令会自动启动）服务在后台运行，监听默认端口 11434
拉取测试模型执行命令：ollama pull llama3:8b首次拉取可能较慢，依赖网络速度
运行交互式对话执行命令：ollama run llama3:8b进入交互模式后输入任意问题（如 “你好”）测试响应
测试一次性提示执行命令：ollama run llama3:8b "请用一句话介绍你自己"模型应输出一段介绍文本后自动退出
查看运行状态执行命令：ollama list应显示已下载的模型列表及其信息

2.4 环境变量与配置文件说明

环境变量/配置项默认值用途说明注意事项
OLLAMA_HOST127.0.0.1:11434设置 Ollama 服务监听地址修改后需重启服务，远程访问时需绑定 0.0.0.0 并注意防火墙设置。
OLLAMA_MODELS~/.ollama/models指定模型存储路径可更改至其他磁盘以节省系统空间，需确保目录有读写权限。
OLLAMA_NUM_PARALLELCPU 核心数控制并行处理请求数高并发场景可调高，但可能增加资源消耗。
OLLAMA_NO_TRACKING未设置启用后禁用使用统计与遥测推荐在隐私敏感环境中设置为 1
OLLAMA_GPU_MEMORY自动检测限制 GPU 显存使用（实验性）用于多任务环境，避免 Ollama 占满显存。
配置文件路径~/.ollama/config.json存储高级配置（当前版本功能有限，主要通过环境变量配置）手动编辑需谨慎，建议通过环境变量控制。
日志输出标准输出或日志文件服务模式下可通过 journalctl（Linux）或日志文件查看运行信息排查问题时可查看日志确认模型加载、错误信息等。

第三章：基础模型操作

3.1 拉取模型（ollama pull）

方法名称语法用途说明代码示例注意事项
拉取指定模型ollama pull <model_name>从 Ollama 模型库下载指定模型到本地ollama pull llama3:8b模型名称区分大小写，标签（tag）可选，如不指定默认为 latest
拉取特定版本ollama pull <model_name>:<tag>下载模型的特定版本（基于参数量或量化等级）ollama pull mistral:7b-instruct-q4_K_M常见标签：q4_0、q4_K_M、q5_K_S 等表示不同量化级别，影响性能与精度
拉取自定义命名模型ollama pull <namespace/model>支持从命名空间拉取社区或私有模型ollama pull myuser/custom-model适用于推送至 Ollama Library 的自定义模型
后台异步拉取ollama pull <model> &在后台运行拉取命令，释放终端ollama pull llama3 &可结合 nohup 使用，适合大模型长时间下载
查看拉取进度-实时显示下载和加载进度ollama pull llama3:8b终端自动输出分层下载状态（manifest）、文件下载、加载完成提示

3.2 列出本地模型（ollama list）

方法名称语法用途说明代码示例注意事项
列出所有模型ollama list显示本地已下载的所有模型及其基本信息ollama list输出包含 MODEL、SIZE、MODIFIED（最后修改时间）
简化列表输出ollama list --short仅显示模型名称，便于脚本处理ollama list --short适合在自动化脚本中用于判断模型是否存在
JSON 格式输出ollama list --format json以 JSON 格式输出模型信息，便于程序解析ollama list --format json可用于与其他工具集成，如 Python 脚本解析模型列表

3.3 删除模型（ollama rm）

方法名称语法用途说明代码示例注意事项
删除指定模型ollama rm <model_name>从本地删除已下载的模型ollama rm llama3:8b删除后模型文件将被永久移除，需重新拉取才能使用
批量删除模型ollama rm <model1> <model2>一次性删除多个模型ollama rm mistral:7b llama3模型名之间用空格分隔，支持多个
强制删除ollama rm -f <model_name>不提示确认，直接删除（适用于脚本）ollama rm -f qwen:4b-f 参数避免交互式确认，适合自动化流程
删除不存在模型-尝试删除未下载模型时报错ollama rm nonexistent-model系统提示 Error: model 'nonexistent-model' not found

3.4 模型信息查看（ollama show）

方法名称语法用途说明代码示例注意事项
查看模型基本信息ollama show --model <model_name>显示模型的 Modelfile、参数、系统提示等内容ollama show --model llama3:8b默认输出较详细，包含构建信息和配置
仅显示 Modelfileollama show --model <model> --modelfile输出模型的 Modelfile 定义ollama show --model llama3 --modelfile可查看模型是如何构建的，便于复现或修改
仅显示参数ollama show --model <model> --parameters显示模型运行时的默认参数设置ollama show --model mistral --parameters包括 num_ctx、temperature 等，可用于调试或覆盖
仅显示系统提示ollama show --model <model> --system查看模型的系统级提示（SYSTEM prompt）ollama show --model llama3 --system系统提示影响模型行为，如角色设定、输出格式等
JSON 格式输出ollama show --model <model> --format json以 JSON 格式返回模型信息，便于程序集成ollama show --model qwen --format json适合在自动化工具中解析模型元数据

第四章：运行与交互式对话

4.1 启动模型对话（ollama run）

方法名称语法用途说明代码示例注意事项
启动交互会话ollama run <model_name>启动指定模型进入交互式对话模式ollama run llama3:8b进入后可连续输入多轮提示，模型保留上下文
指定模型版本ollama run <model>:<tag>使用特定版本或量化等级的模型ollama run mistral:7b-instruct-q4_K_M确保该版本已本地存在或可自动拉取
自动拉取运行ollama run <unknown_model>若模型未下载，自动执行 pull 后运行ollama run phi3:mini首次运行较慢，需等待下载完成
设置运行参数ollama run <model> --param=value在运行时覆盖模型默认参数ollama run llama3 --num_ctx 4096支持常见参数如 temperature、top_p、repeat_penalty 等

4.2 交互模式下的基本操作（输入、退出、多轮对话）

操作名称操作细节注意事项
输入提示在 > 提示符后输入文本，按 Enter 发送支持中文、英文、代码等多种输入，模型按上下文生成响应
多轮对话连续输入多条消息，模型自动保留上下文上下文长度受 num_ctx 限制，过长会被截断
退出会话输入 /exit 或按 Ctrl+C安全退出交互模式，不中断正在生成的响应
中断生成按 Ctrl+C立即停止当前生成过程，返回提示符
清除上下文重启 ollama run 或切换模型Ollama 无内置清空上下文命令，需重新启动会话

4.3 一次性提示输入（非交互模式）

方法名称语法用途说明代码示例注意事项
单次提示运行ollama run <model> "prompt"直接传入提示文本，模型生成后自动退出ollama run llama3 "解释什么是人工智能"适合脚本调用、自动化任务
多行提示ollama run <model> "$(cat prompt.txt)"从文件读取提示内容ollama run qwen "$(cat question.md)"使用命令替换将文件内容作为输入
管道输入echo "prompt" | ollama run <model>通过管道传递提示echo "请总结以下内容：" | ollama run mistral适合与其他命令行工具组合
结合变量使用PROMPT="你好，世界" && ollama run llama3 "$PROMPT"在 Shell 脚本中动态传入提示适用于自动化流程和批处理任务

4.4 指定模型运行与上下文管理

方法名称语法用途说明代码示例注意事项
指定模型运行ollama run <model_name>明确使用特定模型处理请求ollama run phi3:mini "写一个Python冒泡排序"不同模型在代码、推理、对话能力上有差异，需按需选择
设置上下文长度ollama run <model> --num_ctx <value>覆盖模型默认上下文窗口大小ollama run llama3 --num_ctx 8192 "处理长文本..."值越大越耗内存，需硬件支持；默认通常为 2048 或 4096
控制生成长度ollama run <model> --num_predict <value>限制模型单次生成的最大 token 数ollama run mistral --num_predict 100 "简要回答"防止生成过长内容，提高响应速度
保留上下文进行多轮连续使用 ollama run 并保持会话在交互模式下自动管理上下文ollama run llama3 → 输入多条消息上下文保存在内存中，退出后丢失
上下文溢出处理-当输入 + 历史超过 num_ctx 时，旧内容被截断系统自动处理，无警告长对话中可能丢失早期信息，建议关键信息重复提及
多模型上下文隔离分别运行不同模型的 ollama run 会话不同模型间上下文完全独立ollama run llama3 与 ollama run qwen 互不影响可同时运行多个模型会话，资源允许即可

第五章：模型定制与 Modelfile 详解

5.1 什么是 Modelfile

概念名称说明注意事项
Modelfile类似 Dockerfile 的配置文件，用于定义如何构建和定制 Ollama 模型。是文本文件，无扩展名或可命名为 Modelfile，支持版本控制和共享。
构建上下文Modelfile 所在目录为构建上下文，其中可包含模型权重、适配器等文件。所有路径引用基于该目录，避免使用绝对路径。
分层构建支持指令分层，每条指令生成一个”层”，便于缓存和增量更新。修改靠后的指令时，前面的层可复用，提升构建效率。
可重复性同一 Modelfile 构建出的模型完全一致，确保环境一致性。适合团队协作、部署和模型分发。
本地优先所有构建过程在本地完成，无需上传原始模型或数据。保障数据隐私，尤其适用于企业敏感场景。

5.2 Modelfile 指令集（FROM、PARAMETER、TEMPLATE、SYSTEM、ADAPTER 等）

指令名称语法示例用途说明注意事项
FROMFROM llama3:8b指定基础模型，必须是第一条指令支持本地已有的模型或可自动拉取的远程模型
PARAMETERPARAMETER temperature 0.7
PARAMETER num_ctx 4096		设置模型运行时参数常见参数：temperature、top_p、repeat_penalty、num_ctx、num_gpu 等
SYSTEMSYSTEM """You are a helpful assistant."""定义系统级提示，影响模型整体行为使用三引号包裹多行内容；可设定角色、风格、输出格式等
TEMPLATETEMPLATE """{{ if .System }}<start_header_id>{{ .System }}<end_header_id>{{ end }}..."""定义对话模板格式用于控制模型输入输出的消息格式，支持 Jinja2 风格模板
ADAPTERADAPTER ./my-lora/加载本地 LoRA 适配器进行微调路径为相对构建上下文的路径，需包含 adapter_config.json 和 bin 文件
LICENSELICENSE "Copyright 2025 MyCompany"嵌入许可证信息便于模型分发时声明版权或使用条款
MESSAGEMESSAGE "First message in chat history"预置第一条对话消息（常用于演示或初始化）可模拟历史对话，影响后续响应
MERGEMERGE model1.gguf
MERGE model2.bin		合并多个模型（实验性）需确保架构兼容，通常用于模型融合研究

5.3 构建自定义模型（ollama create）

方法名称语法用途说明代码示例注意事项
构建自定义模型ollama create <model_name> -f Modelfile根据 Modelfile 创建新模型ollama create my-llama3 -f Modelfile模型名可带命名空间（如 myuser/llama3-tutor）
指定文件路径ollama create <model> -f <path/to/Modelfile>使用非当前目录的 Modelfileollama create test-model -f ./custom/Modelfile路径需正确，否则报错
查看构建日志-实时输出构建过程（拉取基础模型、应用配置等）ollama create my-model -f Modelfile若基础模型未下载会自动拉取
构建失败处理-检查 Modelfile 语法、路径、网络等错误提示如 “failed to read adapter”常见问题：路径错误、模型不存在、权限不足
验证构建结果ollama list查看新模型是否出现在本地模型列表ollama list构建成功后即可通过 ollama run 调用

5.4 推送自定义模型到仓库（ollama push）

方法名称语法用途说明代码示例注意事项
推送模型ollama push <model_name>将本地自定义模型推送到 Ollama Libraryollama push myuser/my-llama3需先登录 ollama login，且模型名为命名空间格式
推送指定标签ollama push <model>:<tag>推送特定版本的模型ollama push myuser/qa-bot:v1tag 用于版本管理，如 v1、latest、beta 等
登录认证ollama login登录 Ollama 账户（基于 Docker Hub）ollama login首次推送前必须执行，使用 Docker Hub 凭据
推送私有模型ollama push <namespace/model>默认为私有（仅自己可见），需订阅计划ollama push myorg/internal-model免费账户仅支持公开模型，私有需付费计划
推送进度监控-终端实时显示分块上传进度ollama push llama3-custom大模型上传耗时较长，依赖网络带宽
推送失败处理-检查网络、登录状态、磁盘空间、权限错误如 “unauthorized” 或 “timeout”确保模型已成功构建且存在于本地列表

第六章：高级参数调优

6.1 常用运行参数详解（num_ctx、temperature、top_p、repeat_penalty 等）

参数名称默认值用途说明注意事项
num_ctx2048~8192设置上下文窗口大小（token 数）值越大越耗内存，超过硬件限制会导致加载失败或性能下降
temperature0.8控制生成随机性：值越高越随机，越低越确定建议范围：0.1（严谨）~ 1.0（创意），过高可能导致胡言乱语
top_p (nucleus)0.9采样概率阈值，选择累积概率最高的 token 子集与 temperature 协同作用，降低可减少冗余输出
repeat_penalty1.1抑制重复 token，值 >1.0 表示惩罚重复过高可能导致语句不连贯，建议 1.0 ~ 1.3
num_predict-1最大生成 token 数，-1 表示无限制用于控制响应长度，防止无限生成
num_gpu自动检测指定用于推理的 GPU 层数（按 layer 计算）值为 0 表示纯 CPU 推理，需 GPU 支持
stop[]自定义停止词，遇到即终止生成如 stop ["\n", "。"] 可在句末停止
frequency_penalty0.0惩罚高频词出现频率类似 repeat_penalty，但作用于词频层面
presence_penalty0.0惩罚已出现过的 token鼓励模型探索新内容

6.2 通过命令行设置参数

方法名称语法用途说明代码示例注意事项
运行时传参ollama run <model> --param=value在 run 命令中直接覆盖参数ollama run llama3 --temperature 0.5 --top_p 0.8参数名不带横线（如 num_ctx），多个参数可同时设置
设置多个参数ollama run <model> --param1=v1 --param2=v2同时调整多个生成行为ollama run qwen --num_ctx 4096 --repeat_penalty 1.2参数顺序无关
交互模式生效ollama run <model> --temperature 0.3进入交互后所有生成均使用该参数ollama run mistral --temperature 0.3参数在会话期间持续有效
非交互模式应用ollama run <model> --num_predict 100 "prompt"限制一次性提示的输出长度ollama run phi3 "写一首五言诗" --num_predict 50适合批处理任务
参数验证-若参数无效，Ollama 会忽略并使用默认值ollama run llama3 --invalid_param 1.0不会报错，但可能达不到预期效果

6.3 在 Modelfile 中固化参数

方法名称语法示例用途说明代码示例注意事项
固化单个参数PARAMETER temperature 0.5在构建时设定默认值PARAMETER num_ctx 4096所有使用该模型的 run 命令将继承此设置
固化多个参数PARAMETER temperature 0.7
PARAMETER top_p 0.9		连续写入多条 PARAMETER 指令见左栏指令顺序不影响最终效果
覆盖机制ollama run <model> --temperature 1.0命令行参数优先级高于 Modelfile即使 Modelfile 设为 0.5，仍可用 1.0提供灵活性，允许临时调整
动态参数组合结合 SYSTEM 与 PARAMETER构建专用模型（如”代码生成”、“学术写作”）SYSTEM "你是一名Python专家..."
PARAMETER temperature 0.2		适合创建领域专用模型

6.4 参数对生成效果的影响对比

参数组合场景temperaturetop_prepeat_penalty生成效果特点适用场景举例注意事项
高创造性0.90.951.0输出多样、富有想象力，但可能不准确创意写作、头脑风暴、故事生成需人工审核，避免事实错误
低温度（确定性）0.20.51.1输出稳定、保守，倾向于最高概率答案数学计算、代码生成、事实问答可能缺乏多样性，回答模式化
长文本生成0.70.91.2平衡流畅性与连贯性，减少重复文章撰写、摘要生成配合较大 num_ctx（如 8192）使用
防止重复0.80.91.3显著减少词语和句子重复对话系统、长篇内容生成过高可能导致语义断裂
快速响应（短输出）0.60.81.1结合 num_predict=100，快速给出简要回答聊天机器人、即时问答避免生成过长内容，提升用户体验
严格逻辑推理0.1~0.30.1~0.51.0~1.1强调准确性，减少随机跳跃科研辅助、法律文书、技术文档需确保模型本身具备相关领域知识

第七章：API 服务与集成

7.1 启动 Ollama API 服务（ollama serve）

方法名称语法用途说明代码示例注意事项
启动默认 API 服务ollama serve启动 Ollama 后台服务，默认监听 127.0.0.1:11434ollama serve通常在后台自动运行，无需手动执行；若未启动可手动调用
设置监听地址OLLAMA_HOST=0.0.0.0 ollama serve允许外部网络访问 API 服务OLLAMA_HOST=0.0.0.0 ollama serve默认仅本地访问，如需远程调用需设置此环境变量
自定义端口OLLAMA_PORT=8080 ollama serve更改 API 监听端口OLLAMA_PORT=8080 ollama serve避免端口冲突，需确保防火墙放行
后台守护进程运行nohup ollama serve &将服务放入后台持续运行nohup ollama serve &防止终端关闭导致服务中断，输出日志到 nohup.out
查看服务状态ps aux | grep ollama检查 ollama 进程是否运行ps aux | grep ollama确认服务已启动

7.2 REST API 接口概览（/api/generate、/api/chat、/api/embeddings 等）

API 端点请求方法参数说明用途说明示例请求体片段
/api/generatePOSTmodel、prompt、stream（可选）、options（含 temperature 等参数）生成文本（非聊天模式），适合单次补全任务{ "model": "llama3", "prompt": "Hello" }
/api/chatPOSTmodel、messages[]（含 role/content）、stream（可选）支持多轮对话的聊天接口，遵循 chat 格式{ "model": "qwen", "messages": [{"role": "user", "content": "你好"}] }
/api/embeddingsPOSTmodel、prompt 或 text获取文本的嵌入向量（embedding）{ "model": "nomic-embed-text", "prompt": "AI is great" }
/api/tagsGET无列出本地所有模型信息（等同于 ollama list）-
/api/showPOSTname（模型名）、modelfile、parameters、system 等可选字段获取模型详细信息（等同于 ollama show）{ "name": "llama3", "format": "json" }
/api/pullPOSTname（模型名）下载模型（等同于 ollama pull）{ "name": "mistral" }
/api/pushPOSTname（模型名）推送模型到远程仓库{ "name": "myuser/model" }
/api/createPOSTname、modelfile通过 API 创建自定义模型{ "name": "my-model", "modelfile": "FROM llama3..." }

7.3 使用 curl 调用 API 示例

操作名称代码示例说明
生成文本curl http://localhost:11434/api/generate -d '{"model":"llama3","prompt":"你好，世界"}'非流式生成，等待完整响应返回
流式生成curl http://localhost:11434/api/generate -d '{"model":"llama3","prompt":"解释AI","stream":true}'每生成一个 token 返回一个 JSON 对象，适合实时显示
多轮对话curl http://localhost:11434/api/chat -d '{"model":"qwen","messages":[{"role":"user","content":"你好"},{"role":"assistant","content":"你好！"},{"role":"user","content":"你是谁？"}]}'模拟完整对话历史，模型基于上下文回复
获取嵌入向量curl http://localhost:11434/api/embeddings -d '{"model":"nomic-embed-text","prompt":"机器学习"}'返回浮点数数组，可用于向量数据库、语义搜索等
拉取模型curl http://localhost:11434/api/pull -d '{"name":"phi3"}'触发后台下载模型
查看模型标签curl http://localhost:11434/api/tagsGET 请求，无需请求体，返回本地模型列表

7.4 与 Python 应用集成（使用 ollama Python 包）

前提：pip install ollama

操作名称代码示例说明
生成文本import ollama
response = ollama.generate(model='llama3', prompt='解释什么是光合作用')
print(response['response'])		简单调用，获取完整生成结果
流式生成stream = ollama.generate(model='llama3', prompt='写一首诗', stream=True)
for chunk in stream:
print(chunk['response'], end='', flush=True)		实时输出每个生成片段，提升用户体验
多轮对话messages = [
{'role': 'user', 'content': '你好'},
{'role': 'assistant', 'content': '你好！有什么帮助？'},
{'role': 'user', 'content': '推荐一本好书'}
]
response = ollama.chat(model='qwen', messages=messages)
print(response['message']['content'])		支持完整的聊天协议，自动管理上下文
获取嵌入embedding = ollama.embeddings(model='nomic-embed-text', prompt='人工智能')
print(len(embedding['embedding']))		用于构建 RAG 系统或语义相似度计算，输出向量维度
自定义参数response = ollama.generate(
model='llama3',
prompt='解释量子力学',
options={'temperature': 0.5, 'num_ctx': 4096}
)		在调用时覆盖模型默认参数
异步支持import asyncio
import ollama

async def main():
resp = await ollama.generate(model='phi3', prompt='你好')
print(resp['response'])

asyncio.run(main())		使用 await ollama.generate() 等异步方法，适合高并发场景

第八章：模型管理与优化

8.1 查看模型运行状态（ollama ps）

方法名称语法用途说明代码示例注意事项
查看运行中模型ollama ps显示当前正在被加载或运行的模型ollama ps输出包含 MODEL、SIZE、PROCESS_ID、GPU_VRAM、MEMORY 等资源占用信息
空闲状态说明-模型加载后未使用时 CPU 占用低，内存仍保留ollama run llama3 → 等待输入内存不会释放，直到退出会话
多模型并发ollama ps若同时运行多个模型，会全部列出同时运行 qwen 和 phi3每个模型独立占用内存和 GPU 资源
结合 top 使用ollama ps && top综合查看进程资源使用情况-可进一步分析 CPU、内存瓶颈
无运行模型ollama ps若无模型运行，输出为空或提示 “no models”退出所有会话后执行表示 Ollama 核心服务运行但无模型加载

8.2 模型缓存与磁盘空间管理

管理项说明操作建议
缓存位置默认路径：
- Linux: ~/.ollama/models
- macOS: ~/.ollama/models
- Windows: C:\Users\<user>\.ollama\models		可通过 OLLAMA_MODELS 环境变量修改路径
清理未使用模型Ollama 自动缓存模型文件（GGUF），不会自动清理定期使用 ollama rm <model> 删除不再需要的模型
查看磁盘占用du -sh ~/.ollama/models评估模型存储开销，大型模型（如 70B）可达 40GB+
符号链接技巧将 models 目录链接到大容量磁盘ln -s /mnt/bigdisk/ollama_models ~/.ollama/models
避免重复下载相同模型不同 tag 可能共享底层文件使用 ollama list 管理版本，避免冗余

8.3 模型量化与格式支持（GGUF 等）

概念名称说明常见类型与说明
GGUF 格式Geoff’s GGUF，二进制格式，专为 llama.cpp 优化，Ollama 原生支持替代旧的 GGML，支持元数据、多模态等扩展
量化等级减少模型精度以降低体积和内存占用，提升推理速度- F16: 半精度，体积大，质量最高
- Q4_K_M: 4-bit 中等质量，平衡选择
- Q2_K: 2-bit，极小体积，质量差
量化影响位数越低，模型越小越快，但可能损失准确性、出现逻辑错误推荐：Q4_K_M 或 Q5_K_S 用于通用任务；Q8 用于高精度需求
如何选择根据硬件选择：
- 8GB RAM: Q4 或 Q3
- 16GB+: Q5 或 Q6
- 高性能: F16		查看 Ollama Library 中模型标签（如 :q4_K_M）
自定义量化需借助 llama.cpp 工具链（如 quantize）对模型进行重新量化高级用法，需专业知识

8.4 多模型并行运行与资源分配

场景说明建议配置
并行运行可同时运行多个 ollama run 会话，每个模型独立加载支持，但总内存需满足所有模型之和
GPU 资源分配Ollama 自动分配 GPU 层（layers）给模型，支持多卡（CUDA、Metal）使用 num_gpu 参数控制，如 --num_gpu 20 表示使用 20 层 GPU 加速
内存不足处理若 RAM/VRAM 不足，模型加载失败或运行极慢降低量化等级、关闭部分模型、增加 swap
混合推理CPU + GPU 混合模式，部分层在 CPU，部分在 GPU自动处理，无需配置
性能监控使用 ollama ps 查看各模型资源占用避免同时运行多个大模型（如 70B）
资源优化建议- 优先使用量化模型
- 按需加载模型
- 使用 SSD 提升加载速度		合理规划模型使用策略，提升整体效率

第九章：安全与部署实践

9.1 本地部署的安全建议

安全措施说明实施建议
默认本地监听Ollama API 默认绑定 127.0.0.1:11434，仅允许本机访问无需额外配置，保障本地开发安全
禁用远程访问避免将 API 暴露在公网或局域网中不设置 OLLAMA_HOST=0.0.0.0，防止未授权访问
防火墙规则使用系统防火墙限制端口访问Linux: ufw deny 11434；Windows: 阻止入站连接
模型来源可信仅从官方 Ollama Library 或可信渠道拉取模型避免运行来源不明的自定义模型，防止恶意代码注入
权限最小化以普通用户运行 Ollama，避免使用 root 权限提升系统安全性，限制潜在攻击面
定期更新保持 Ollama CLI 和模型为最新版本修复已知漏洞，获取性能优化
敏感数据保护避免在提示词（prompt）中输入密码、身份证等敏感信息模型可能记录或泄露输入内容，尤其在调试日志中

9.2 远程访问配置与认证机制

配置项说明配置方法与注意事项
开启远程访问允许其他设备调用 APIOLLAMA_HOST=0.0.0.0 ollama serve
绑定特定 IP仅允许指定 IP 访问OLLAMA_HOST=192.168.1.100 ollama serve
使用反向代理通过 Nginx/Caddy 转发请求，增强安全和管理可结合 HTTPS、访问日志、速率限制等
添加认证机制（Basic Auth）Ollama 原生不支持认证，需通过代理层实现Nginx 示例：
auth_basic "Restricted";
auth_basic_user_file /etc/nginx/.htpasswd;
使用 API Token在应用层实现 Token 验证（如 Flask/FastAPI 中间件）客户端调用时需携带 Authorization: Bearer <token>
TLS/HTTPS 加密防止数据在传输中被窃听配合反向代理使用 Let’s Encrypt 证书
访问控制列表（ACL）限制特定 IP 段访问Nginx 中使用 allow / deny 指令

9.3 在 Docker 中运行 Ollama

场景配置示例与说明注意事项
基础运行docker run -d -p 11434:11434 ollama/ollama默认仅本地访问，适合测试
支持 GPU（NVIDIA）docker run -d --gpus=all -p 11434:11434 --device /dev/nvidiactl --device /dev/nvidia-uvm ollama/ollama需安装 nvidia-docker，确保驱动兼容
持久化模型存储docker run -d -v ollama_models:/root/.ollama/models -p 11434:11434 ollama/ollama避免模型在容器重启后丢失
自定义主机绑定docker run -d -e OLLAMA_HOST=0.0.0.0 -p 11434:11434 ollama/ollama实现远程访问
构建自定义镜像Dockerfile:
FROM ollama/ollama
RUN ollama pull llama3		预加载模型，加快部署
资源限制docker run -d --memory="8g" --cpus="4" ... ollama/ollama防止 Ollama 占用过多资源

9.4 生产环境部署最佳实践

实践项说明推荐方案
高可用架构避免单点故障使用负载均衡（如 Nginx）分发请求到多个 Ollama 实例
容器化部署提升部署一致性与可维护性使用 Docker + Kubernetes 或 Docker Compose 管理
监控与日志实时掌握服务状态集成 Prometheus + Grafana 监控资源；使用 ELK 收集日志
模型版本管理确保环境一致性使用 model:tag 明确指定版本，避免自动更新导致行为变化
自动化 CI/CD实现模型更新与部署自动化结合 Git + CI 工具自动构建 Modelfile 并推送
资源规划根据模型大小合理分配内存与 GPU例如：7B 模型 Q4 量化约需 6GB RAM；70B 需 48GB+
备份策略防止模型数据丢失定期备份 ~/.ollama/models 目录
性能压测评估服务吞吐与延迟使用 hey 或 wrk 对 /api/generate 进行压力测试
安全审计定期检查访问日志与配置确保无未授权访问，及时修复漏洞

第十章：生态与扩展应用

10.1 Ollama 与 LangChain 集成

集成方式代码示例说明
使用 Ollama 类from langchain_community.llms import Ollama

llm = Ollama(model="llama3", temperature=0.7)
response = llm.invoke("解释量子纠缠")
print(response)		最简单方式，直接调用 Ollama 模型
作为 Chat Modelfrom langchain_community.chat_models import ChatOllama

chat = ChatOllama(model="qwen", temperature=0.5)
response = chat.invoke([HumanMessage(content="你好")])		支持消息历史，适合构建对话 Agent
在 RAG 中使用from langchain_community.vectorstores import Chroma
from langchain_community.embeddings import OllamaEmbeddings

embeddings = OllamaEmbeddings(model="nomic-embed-text")
vectorstore = Chroma(embedding_function=embeddings)		结合 Ollama 嵌入模型实现本地 RAG 系统
流式输出for chunk in llm.stream("写一首诗"):
print(chunk, end="", flush=True)		支持实时响应，提升用户体验
自定义提示模板from langchain_core.prompts import PromptTemplate

prompt = PromptTemplate.from_template("你是一个{role}，{query}")
chain = prompt | llm
chain.invoke({"role": "诗人", "query": "写一首春景诗"})		灵活控制模型行为

10.2 与 LlamaIndex 的结合使用

集成方式代码示例说明
设置 Ollama 为 LLMfrom llama_index.core import Settings
from llama_index.llms.ollama import Ollama

llm = Ollama(model="llama3", request_timeout=120.0)
Settings.llm = llm		全局设置 LLM，后续索引操作均使用 Ollama
使用 Ollama 嵌入模型from llama_index.embeddings.ollama import OllamaEmbedding

embed_model = OllamaEmbedding(model_name="nomic-embed-text")
Settings.embed_model = embed_model		实现纯本地向量化，无需外部 API
构建文档索引from llama_index.core import VectorStoreIndex, SimpleDirectoryReader

documents = SimpleDirectoryReader("data").load_data()
index = VectorStoreIndex.from_documents(documents)		自动使用 Settings 中配置的 LLM 和 Embedding
查询与响应query_engine = index.as_query_engine()
response = query_engine.query("文档讲了什么？")
print(response)		支持自然语言查询，返回引用来源
流式查询for text in query_engine.query("总结内容").response_gen:
print(text, end="", flush=True)		实时输出查询结果

10.3 常用前端工具（Open WebUI、Text Generation WebUI）

工具名称项目地址 / 安装方式核心功能与特点
Open WebUIhttps://openwebui.com
docker run -d -p 3000:8080 -v open-webui:/app/backend/data -e OLLAMA_BASE_URL=http://host.docker.internal:11434 --name open-webui ghcr.io/open-webui/open-webui:main		- 类 ChatGPT 的现代 UI
- 支持多模型切换、对话管理、文件上传
- 插件系统（RAG、语音等）
- 易于部署，Docker 一键启动
Text Generation WebUIhttps://github.com/oobabooga/text-generation-webui
pip install -r requirements.txt		- 功能极其丰富，支持多种后端（transformers、llama.cpp、Ollama）
- 高级参数调优界面
- LoRA 训练、语音合成等扩展
- 学习成本较高，适合高级用户
Ollama WebUIhttps://github.com/ollama-webui/ollama-webui轻量级 Web UI，简洁易用，适合快速部署
Faradayhttps://faraday.dev桌面应用，集成 Ollama，支持语音输入、快捷指令，适合个人使用

10.4 社区模型库（Ollama Library）使用指南

功能说明使用方法与技巧
模型搜索访问 https://ollama.com/library 浏览所有公开模型支持按名称、标签（如 llm、coding、vision）筛选
拉取模型ollama pull <model>:<tag>如 ollama pull llama3:8b-instruct-q4_K_M
查看模型详情网页上查看模型描述、参数、量化信息、Modelfile帮助判断是否适合特定任务
版本标签同一模型有多种量化版本（如 q4、q8）和用途变体（如 -instruct、-chat）选择合适版本：q4_K_M 通用，q8 高质量，instruct 擅长指令遵循
推送自定义模型ollama push <namespace/model>:<tag>需登录 ollama login，命名空间为用户名
关注热门模型如 llama3、qwen、mistral、phi3、nomic-embed-text 等社区活跃，更新频繁，文档丰富
使用模型别名ollama create my-model -f Modelfile
ollama tag my-model llama3-custom		便于管理和调用
报告问题在模型页面下留言或提交 issue帮助维护者改进模型