Ollama 是目前最流行的本地大模型运行工具之一——它把模型下载、量化、推理和 API 服务打包成一个极简的命令行工具，让用户在自己的电脑上就能运行开源大模型。本文合并 Ollama 官方 GitHub README与官方文档站（docs.ollama.com），覆盖安装、日常使用、REST API 与生态集成。
一、安装
Ollama 支持 macOS、Windows 和 Linux（另有 Docker 镜像），安装方式：
# macOS / Windows：官网下载安装包
# https://ollama.com/download
# Linux 一键安装
curl -fsSL https://ollama.com/install.sh | sh
# Docker
docker run -d -v ollama:/root/.ollama -p 11434:11434 --name ollama ollama/ollama二、快速上手：三步完成第一次对话
按照官方文档 Quickstart 的步骤：
第 1 步：安装完成后，在终端运行 ollama 打开交互式菜单。从菜单中可以：
- Run a model——启动一次交互式聊天；
- Launch tools——启动 Claude Code、OpenClaw、VS Code 等集成工具。
第 2 步：运行模型开始第一次聊天：
ollama run gemma4云端模型的使用方式完全相同：
ollama run gemma4:cloud第 3 步：发送第一条消息（例如 “Explain why the sky is blue in one paragraph.”），输入 /bye 退出聊天。
三、常用命令
| 命令 | 作用 |
|---|---|
| ollama run <model> | 下载并运行模型（本地不存在时自动拉取），进入交互式对话 |
| ollama pull <model> | 仅下载模型到本地 |
| ollama list | 列出本地已下载的模型 |
| ollama ps | 查看当前正在运行的模型 |
| ollama show <model> | 查看模型详细信息（参数量、量化、模板等） |
| ollama rm <model> | 删除本地模型 |
| ollama serve | 启动 API 服务（安装包默认已作为后台服务运行） |
四、REST API：与任意应用集成
Ollama 安装后 API 服务自动可用，默认地址为 http://localhost:11434/api。官方文档给出的 curl 示例：
curl http://localhost:11434/api/generate -d '{
"model": "gemma4",
"prompt": "Why is the sky blue?"
}'常用的 API 端点包括：
| 端点 | 功能 |
|---|---|
| /api/generate | 文本生成（一次补全） |
| /api/chat | 多轮对话（消息列表） |
| /api/tags | 列出本地模型 |
| /api/show | 查看模型信息 |
| /api/embeddings | 生成文本向量 |
云端模型的 API 基地址为 https://ollama.com/api，与本地 API 完全一致——代码无需修改即可切换云端/本地。
五、OpenAI 兼容接口与官方库
Ollama 提供 OpenAI 兼容接口，凡是支持自定义 base_url 的 OpenAI SDK/应用都能直接对接，将 base_url 指向 http://localhost:11434/v1 即可。同时 Ollama 提供官方 Python 与 JavaScript 库：
# Python 官方库
pip install ollama
from ollama import chat
response = chat(model='gemma4', messages=[
{'role': 'user', 'content': 'Why is the sky blue?'}
])
print(response['message']['content'])社区维护的第三方库覆盖 Go、Java、PHP、Ruby、Rust、Swift 等十余种语言，完整列表见 Ollama GitHub 仓库。
六、工具集成
得益于 OpenAI 兼容接口，Ollama 已被大量主流工具支持，官方文档专门列出了集成指南，包括 Claude Code、VS Code、各类桌面客户端与 Web UI 等——把本地模型作为这些工具的后端，即可在完全不联网的环境里使用 AI 编程助手。
七、Modelfile：自定义模型
类似 Dockerfile，Ollama 用 Modelfile 描述一个模型的构建方式：
FROM qwen3:8b
# 调整生成参数
PARAMETER temperature 0.7
PARAMETER num_ctx 4096
# 设定系统提示词
SYSTEM """
你是一个严谨的技术助手，回答问题时要给出依据。
"""然后执行 ollama create my-model -f Modelfile 即可基于基础模型创建带自定义配置的私有模型。支持从 GGUF 量化文件直接导入，也支持从 PyTorch Safetensors 导入并自动转换。
八、API 版本策略
官方文档说明：Ollama 的 API 没有严格的版本号，但保持稳定和向后兼容；废弃（Deprecation）极少发生，会在发布说明（release notes）中提前公告。
九、/api/generate 完整参数详解
按照官方 API 文档，/api/generate 端点支持以下主要参数：
| 参数 | 类型 | 说明（官方文档原文要点） |
|---|---|---|
| model | string（必填） | 模型名称 |
| prompt | string | 用于生成回复的文本 |
| suffix | string | 用于 fill-in-the-middle 模型：出现在用户提示之后、模型回复之前的文本 |
| images | string[] | Base64 编码的图片，供支持图像输入的模型使用 |
| format | string / object | 结构化输出格式：支持字符串 “json” 或 JSON Schema 对象 |
| system | string | 系统提示词 |
| stream | boolean（默认 true） | 为 true 时返回部分响应的流 |
| think | boolean / enum | 为 true 时在内容之外返回独立的思考输出；支持 “high”/”medium”/”low”/”max” 思考级别 |
| raw | boolean | 为 true 时跳过提示模板，返回模型原始回复 |
| keep_alive | string / number | 模型驻留时长（如 5m；设 0 表示用完立即卸载） |
| options | object | 控制文本生成的运行时选项（temperature、num_ctx 等） |
| logprobs / top_logprobs | boolean / integer | 是否返回输出 token 的对数概率及返回数量 |
响应体包含丰富的统计信息：response（生成文本）、thinking（思考输出）、total_duration/load_duration/eval_duration（以纳秒计的耗时）、prompt_eval_count/eval_count（输入/输出 token 数）等——方便做性能测量与成本核算。例如一个最小请求：
curl http://localhost:11434/api/generate -d '{
"model": "gemma4",
"prompt": "Why is the sky blue?"
}'值得注意的三个能力：结构化输出（format 传 JSON Schema 即可约束模型按 schema 输出，适合程序化消费）；多模态输入（images 参数传 Base64 图片即可做视觉理解）；思考模型支持（think 参数控制思考输出与级别）。
参考来源
- Ollama 官方文档（docs.ollama.com）：Quickstart、API Introduction
- Ollama 官方 GitHub README（github.com/ollama/ollama）
- Ollama 模型库（ollama.com/search）
- 官方 Python 库（github.com/ollama/ollama-python）、JavaScript 库（github.com/ollama/ollama-js）
本文为技术文档摘录整理，内容合并自下列官方资料（官方文档、官方 GitHub 仓库、论文与权威媒体报道），技术数字以官方原文为准，版权归原作者所有。
