Ollama 安装与使用指南（基于官方文档）

本文基于官方文档 https://docs.ollama.com/ 汇总，目标是让你从 0 到可用，并覆盖常见的本地调用方式。

1. Ollama 是什么

Ollama 用于在本机或服务器运行大语言模型，默认本地 API 地址为：

• http://localhost:11434/api

如果使用 Ollama Cloud，对应 API 基址为：

• https://ollama.com/api

2. 安装指南

2.1 Linux（官方脚本）

curl -fsSL https://ollama.com/install.sh | sh

手动安装（如需）：

curl -fsSL https://ollama.com/download/ollama-linux-amd64.tar.zst | sudo tar x -C /usr

AMD GPU 额外包（按需）：

curl -fsSL https://ollama.com/download/ollama-linux-amd64-rocm.tar.zst | sudo tar x -C /usr

ARM64 包（按需）：

curl -fsSL https://ollama.com/download/ollama-linux-arm64.tar.zst | sudo tar x -C /usr

启动与验证：

ollama serve
ollama -v

可作为系统服务启动（Linux）：

sudo systemctl start ollama
sudo systemctl status ollama

2.2 macOS

官方建议通过下载 ollama.dmg 安装应用后拖到 Applications。首次启动会协助把 ollama CLI 放入 PATH。

系统要求（文档给出）：

• macOS 14+（Sonoma 或更新）
• Apple 芯片（CPU/GPU）或 x86（CPU）

2.3 Windows

官方推荐使用 OllamaSetup.exe。如需以服务方式嵌入运行，可使用 ollama-windows-amd64.zip（CLI 包）并配合 ollama serve。

3. 10 分钟快速上手

3.1 打开交互菜单

ollama

你可以在菜单中直接：

1. Run a model（聊天）
2. Launch tools（Codex/OpenClaw 等集成）
3. More（更多集成）

3.2 拉取并运行一个模型

ollama pull gemma3
ollama run gemma3

3.3 常用 CLI 命令

# 模型管理
ollama pull <model>
ollama rm <model>
ollama ls

# 运行状态
ollama ps
ollama stop <model>

# 服务
ollama serve

# 工具集成
ollama launch
ollama launch codex
ollama launch openclaw

4. API 使用（本地服务）

4.1 文本生成 /api/generate

curl http://localhost:11434/api/generate -d '{
  "model": "gemma3",
  "prompt": "Why is the sky blue?"
}'

实用参数（官方接口支持）：

• stream：默认 true（流式返回）
• system：系统提示词
• format：可设为 "json" 或 JSON Schema
• think：支持的模型可输出思考信息
• keep_alive：模型保活时长

4.2 多轮对话 /api/chat

curl http://localhost:11434/api/chat -d '{
  "model": "gemma3",
  "messages": [
    {"role": "user", "content": "Hello!"}
  ]
}'

4.3 向量接口 /api/embed

curl http://localhost:11434/api/embed -d '{
  "model": "embeddinggemma",
  "input": "Why is the sky blue?"
}'

说明：/api/embed 返回向量，可用于语义检索、RAG 等。

5. Docker 部署（官方命令）

5.1 CPU

docker run -d -v ollama:/root/.ollama -p 11434:11434 --name ollama ollama/ollama

5.2 NVIDIA GPU

docker run -d --gpus=all -v ollama:/root/.ollama -p 11434:11434 --name ollama ollama/ollama

5.3 AMD GPU（ROCm）

docker run -d --device /dev/kfd --device /dev/dri -v ollama:/root/.ollama -p 11434:11434 --name ollama ollama/ollama:rocm

容器内运行模型：

docker exec -it ollama ollama run llama3.2

6. OpenAI 兼容接口（迁移现有应用）

Ollama 提供 OpenAI 风格接口，典型基址：

• http://localhost:11434/v1/

Python（官方示例思路）：

from openai import OpenAI

client = OpenAI(
    base_url='http://localhost:11434/v1/',
    api_key='ollama',  # 必填但会被忽略
)

resp = client.chat.completions.create(
    model='gpt-oss:20b',
    messages=[{'role': 'user', 'content': 'Say this is a test'}],
)

print(resp.choices[0].message.content)

如果你的上层工具固定写死模型名（如 gpt-3.5-turbo），可用模型别名方式：

ollama cp llama3.2 gpt-3.5-turbo

7. 性能与上下文长度建议

官方文档给出默认上下文策略（与显存相关）：

• < 24 GiB：约 4k
• 24-48 GiB：约 32k
• >= 48 GiB：约 256k

需要更大上下文（如 Agent、代码场景）可在启动服务时设置：

OLLAMA_CONTEXT_LENGTH=64000 ollama serve

可用以下命令观察模型运行与上下文分配：

ollama ps

8. 常见问题速查

1. 连接失败：先确认 ollama serve 是否运行，或 Docker 容器是否已映射 11434 端口。
2. 拉模型慢：优先检查网络质量和模型体积；首次下载通常较慢。
3. 显存不足：降低上下文长度、改用小模型，或使用 CPU 模式。
4. OpenAI SDK 报错：确认 base_url 指向 http://localhost:11434/v1/，并先 ollama pull 对应模型。

9. 官方参考链接

• 文档首页：https://docs.ollama.com/
• Quickstart：https://docs.ollama.com/quickstart
• CLI：https://docs.ollama.com/cli
• Linux：https://docs.ollama.com/linux
• macOS：https://docs.ollama.com/macos
• Windows：https://docs.ollama.com/windows
• Docker：https://docs.ollama.com/docker
• API 介绍：https://docs.ollama.com/api/introduction
• API Generate：https://docs.ollama.com/api/generate
• API Chat：https://docs.ollama.com/api/chat
• API Embed：https://docs.ollama.com/api/embed
• OpenAI 兼容：https://docs.ollama.com/api/openai-compatibility
• Context length：https://docs.ollama.com/context-length