Ollama【一、初识】

Ollama 已成为本地运行大语言模型（LLM）最主流的工具，支持 Windows、macOS 和 Linux。

---

一、快速安装 (Installation)

1. Windows / macOS

• 下载: 访问官网 ollama.com 下载安装包。
  • Windows: 直接运行 .exe 安装包，安装后会自动在后台运行服务。
  • macOS: 拖动 .dmg 中的图标到应用程序文件夹，或在终端运行 brew install ollama。
• 验证: 打开终端（CMD/PowerShell/Terminal），输入：

  ollama --version
  

2. Linux

• 一键安装脚本:

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

• 手动启动服务 (如果未自动启动):

  ollama serve
  

3. Docker 部署 (推荐高级用户)

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

---

二、核心命令详解 (Core Commands)

Ollama 的命令行工具非常直观，以下是常用命令：

命令	功能描述	示例
ollama pull <model>	下载并准备模型	ollama pull qwen2.5:7b
ollama run <model>	运行模型并与之交互	ollama run llama3.1
ollama start <model>	后台运行模型，不进行对话	ollama start llama3:latest
ollama run <model> <prompt>	单次运行并输出结果	ollama run gemma2 "你好"
ollama stop <model>	停止正在运行的模型	ollama stop llama3:latest
ollama stop all	停止所有正在运行的模型	ollama stop all
ollama list	查看本地已下载的模型	ollama list
ollama ps	查看正在运行的模型	ollama ps
ollama rm <model>	删除本地模型以释放空间	ollama rm mistral
ollama rm --prune <模型名>	删除模型的同时清理缓存	ollama rm --prune mistral
ollama cp <old> <new>	复制/重命名模型	ollama cp qwen2.5 my-qwen
ollama show <model>	查看模型详细信息 (Modelfile, 参数等)	ollama show llama3.1 --modelfile
ollama create <name>	从 Modelfile 创建自定义模型	ollama create my-agent -f Modelfile
ollama serve	启动 Ollama 服务 (通常默认自启)	ollama serve

---

三、实战使用流程

1. 下载并运行第一个模型

假设我们要下载阿里最新的 Qwen2.5 (7B 版本)，它在中文理解和代码能力上表现优异：

# 1. 拉取模型
ollama pull qwen2.5:7b

# 2. 进入交互式对话
ollama run qwen2.5:7b

进入交互模式后，你可以直接输入问题，输入 /bye 退出。

2. 单次指令调用 (适合脚本集成)

如果你想在 Shell 脚本中直接使用：

response=$(ollama run qwen2.5:7b "用一句话解释量子纠缠")
echo $response

3. 查看和管理模型

# 查看本地所有模型及其大小
ollama list

# 删除不需要的旧模型
ollama rm llama3

---

四、高级定制：Modelfile 详解

Ollama 的强大之处在于可以通过 Modelfile 自定义模型行为（如设定系统提示词、调整参数、绑定技能）。

1. 什么是 Modelfile?

它是一个简单的文本文件，定义了模型的“性格”和运行参数。

2. 创建一个专属客服机器人

创建一个名为 Modelfile 的文件（无后缀）：

# 基础模型
FROM qwen2.5:7b

# 设置系统提示词 (System Prompt)
SYSTEM """
你是一名专业的售后技术支持助手。
1. 语气要亲切、专业且耐心。
2. 只回答与产品技术支持相关的问题。
3. 如果用户询问无关话题，请礼貌地引导回技术支持。
4. 输出格式尽量使用 Markdown 列表。
"""

# 调整运行参数
PARAMETER temperature 0.7       # 创造性 (0-1, 越高越发散)
PARAMETER num_ctx 8192          # 上下文窗口长度 (默认4096, 建议调大)
PARAMETER top_p 0.9             # 核采样

# 定义元数据
LICENSE Apache 2.0

3. 构建并使用自定义模型

# 创建名为 'support-bot' 的新模型
ollama create support-bot -f Modelfile

# 运行它
ollama run support-bot

现在，这个模型已经“记住”了它的客服身份，无需每次重复提示词。

---

五、API 集成 (开发者的最爱)

Ollama 默认提供兼容 OpenAI API 格式的接口，方便集成到 OpenClaw、LangChain 或其他应用中。

• 默认地址: http://127.0.0.1:11434
• OpenAI 兼容端点: http://127.0.0.1:11434/v1

1. 测试 API 连通性

curl http://127.0.0.1:11434/v1/models

2. Python 调用示例 (使用 openai 库)

即使没有 OpenAI Key，也可以使用 openai 库连接本地 Ollama：

from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:11434/v1",
    api_key="ollama"  # 任意非空字符串即可
)

response = client.chat.completions.create(
    model="qwen2.5:7b",
    messages=[
        {"role": "system", "content": "你是一个有用的助手。"},
        {"role": "user", "content": "写一个 Python 快速排序函数。"}
    ],
    stream=True  # 支持流式输出
)

for chunk in response:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

---

六、常见问题与优化 (2026 版)

1. 跨设备访问 (局域网部署)

默认 Ollama 只监听 127.0.0.1。若要让局域网内其他电脑访问：

• Linux/Mac:

  export OLLAMA_HOST=0.0.0.0:11434
  ollama serve
  

• Windows:
  1. 退出任务栏 Ollama 图标。
  2. 设置系统环境变量 OLLAMA_HOST = 0.0.0.0:11434。
  3. 重启 Ollama。
  4. 注意: 需在防火墙中放行 11434 端口。

2. 显存不足 (OOM) 怎么办？

• 使用量化模型: Ollama 默认下载 4-bit 量化版 (q4_0)，显存占用极低。如果需要更小，可搜索 q2_k 版本。

  ollama pull llama3.1:8b-q2_K
  

• 限制 GPU 使用: 强制部分层在 CPU 运行（速度变慢但能跑起来）。

  # 在 Modelfile 中设置
  PARAMETER num_gpu 20  # 仅将前 20 层加载到 GPU
  

3. 上下文窗口不够长？

很多模型默认上下文只有 4k 或 8k，处理长文档会丢失信息。

• 解决方法: 必须通过 Modelfile 重新创建模型，设置 PARAMETER num_ctx 32768 (或更高，取决于显存)。

  FROM qwen2.5:7b
  PARAMETER num_ctx 32768
  

  然后 ollama create qwen-long -f Modelfile。

4. 模型下载速度慢

国内用户直接从官方源下载可能较慢。

• 方案: 使用镜像站或手动下载 GGUF 文件导入。
  1. 从魔搭社区 (ModelScope) 或 HuggingFace 镜像站下载 .gguf 文件。
  2. 编写 Modelfile: FROM ./path/to/model.gguf。
  3. 执行 ollama create mymodel -f Modelfile。