Ollama 本地 LLM 配置指南

一、安装 Ollama

1.1 macOS

前往 https://ollama.com/download 下载 macOS 版本，拖入 Applications 安装。

也可以用 Homebrew：

bash 复制代码

brew install ollama

1.2 Linux

bash 复制代码

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

1.3 升级 Ollama

新模型（如 qwen3.5）通常要求最新版 Ollama。如果 ollama pull 报 412 错误提示需要新版本：

去 https://ollama.com/download 下载最新版覆盖安装
关键：重启 Ollama 服务进程（仅更新客户端不够，服务端也要重启）：

bash 复制代码

# macOS：杀掉旧进程，重新打开
pkill -f Ollama
open /Applications/Ollama.app

# Linux：重启服务
sudo systemctl restart ollama

验证版本一致：

bash 复制代码

ollama --version                         # 客户端版本
curl http://localhost:11434/api/version  # 服务端版本

二、Ollama配置

2.1 常用命令

bash 复制代码

ollama pull <模型名>           # 下载模型
ollama run <模型名>            # 交互式对话（如果模型不存在会自动下载）
ollama list                    # 查看已安装的模型
ollama ps                      # 查看正在运行的模型
ollama show <模型名>           # 查看模型详情（参数量、大小等）
ollama rm <模型名>             # 删除模型
ollama stop <模型名>           # 停止运行中的模型，释放内存
ollama serve                   # 启动 API 服务（默认 localhost:11434）

提示： 模型命名格式为 名称:参数量，如 qwen3:4b、llama3:8b。请以 ollama list 显示的名称为准填写配置。如果不确定模型名称，可以直接 ollama run qwen3:4b 试一下，能对话说明名称正确。

2.2 启动 Ollama 服务

macOS 打开 Ollama.app 即可自动启动服务。Linux 下手动启动：

bash 复制代码

ollama serve

默认监听 http://localhost:11434。

2.3 其他配置

Ollama 通过环境变量进行配置。

(1) 模型存储位置

默认模型存储路径：
- macOS: ~/.ollama/models
- Linux: /usr/share/ollama/.ollama/models
目录下有两个子目录：
- manifests/
  
  模型的元数据索引，路径格式为 manifests/registry.ollama.ai/library/<模型名>/<tag>。
  
  每个文件是 JSON，记录该模型由哪些层（layer）组成及其 SHA256 摘要。
- blobs/
  
  实际的数据文件，按 SHA256 哈希命名，包括模型权重、prompt 模板、参数配置等。
如需更改（比如磁盘空间不足），设置 OLLAMA_MODELS 环境变量：

bash 复制代码

# 临时生效
export OLLAMA_MODELS=/path/to/your/models
ollama serve

# Linux 永久生效（systemd 方式）
sudo systemctl edit ollama
# 添加以下内容：
# [Service]
# Environment="OLLAMA_MODELS=/path/to/your/models"
sudo systemctl restart ollama

# macOS 永久生效
launchctl setenv OLLAMA_MODELS /path/to/your/models
# 然后重启 Ollama.app

(2) 上下文长度（Context Length）

模型默认上下文长度为 4096 tokens（4K）。如果对话较长或需要处理长文本，可以指定更大的上下文窗口：

bash 复制代码

# 命令行方式
ollama run qwen3:4b --ctx-size 8192

# API 调用方式（通过 num_ctx 参数）
curl http://localhost:11434/api/chat -d '{
  "model": "qwen3:4b",
  "options": { "num_ctx": 8192 },
  "messages": [{"role": "user", "content": "你好"}]
}'

注意： 上下文越大，内存/显存占用越高。建议根据硬件条件调整：

8GB 内存/显存：num_ctx 建议不超过 4096

16GB 及以上：可以设为 8192 或更大

三、下载模型

在 Ollama 中，可以通过 ollama pull 命令下载本地模型。

3.1 推荐模型

复制代码

# 推荐：Qwen3.5 系列（性能与体积比较均衡）
ollama pull qwen3.5:4b      # 推荐，CPU/GPU 均可运行

该模型体积约 3～4GB，在普通笔记本上即可运行，推理速度和效果较为均衡，适合作为本地大模型的入门选择。

3.2 不同尺寸版本

复制代码

# Qwen3.5 不同参数规模
ollama pull qwen3.5:0.8b    # ~0.5GB，极轻量
ollama pull qwen3.5:2b      # ~1.5GB，轻量对话
ollama pull qwen3.5:9b      # ~6GB，建议 GPU

一般来说：

0.8B：适合超轻量部署
2B：适合简单对话和工具调用
4B：综合性能较好（推荐）
9B：效果更好，但对显存要求更高

3.3 其他可选模型

复制代码

ollama pull llama3:8b       # Meta Llama 3
ollama pull mistral:7b      # Mistral
ollama pull qwen2.5vl:7b    # 通义千问（支持视觉）

这些模型在代码生成、多语言对话或视觉任务上也有不错表现，可以根据实际需求选择。

3.4 查看已下载模型

复制代码

ollama list

3.5 下载示例

例如下载 qwen3.5:4b：

bash 复制代码

ollama pull qwen3.5:4b

终端输出示例：

bash 复制代码

pulling manifest 
pulling 81fb60c7daa8: 100% ▕█████████████████████████████████████████████▏ 3.4 GB     pulling 7339fa418c9a: 100% ▕█████████████████████████████████████████████▏  11 KB     pulling 9371364b27a5: 100% ▕█████████████████████████████████████████████▏   65 B     pulling de9fed2251b3: 100% ▕█████████████████████████████████████████████▏  475 B     verifying sha256 digest 
writing manifest 
success

下载完成后，可以使用 ollama list 查看本地模型：

bash 复制代码

NAME                     ID              SIZE      MODIFIED
qwen3.5:4b               2a654d98e6fb    3.4 GB    11 minutes ago
deepseek-coder:latest    3ddd2d3fc8d2    776 MB    6 months ago
deepseek-r1:latest       0a8c26691023    4.7 GB    12 months ago

注意

由于模型仓库会持续更新，模型名称可能发生变化。例如 qwen3 可能升级为 qwen3.5。如果 ollama pull 提示 找不到模型 ，可以前往官方模型库搜索最新名称：https://ollama.com/search

四、Ollama使用

下载模型后，就可以开始与本地模型进行交互。Ollama 提供了多种使用方式，包括 命令行对话、REST API 调用以及 OpenAI 兼容接口。

4.1 命令行交互

最简单的方式是直接通过命令行与模型对话：

bash 复制代码

# 进入交互式对话
ollama run qwen3.5:4b

进入对话后，可以直接输入文本并按 Enter 发送消息。

常用命令包括：
- /bye：退出对话
- /set parameter num_ctx 8192：临时调整上下文长度
- /show info：查看当前模型信息
- /?：查看所有可用命令
这种方式适合 快速测试模型能力或进行简单对话。

4.2 REST API 调用

Ollama 在启动后会自动提供一个 本地 REST API 服务 （默认端口 11434），可以通过 curl 或任意 HTTP 客户端调用。

(1) 对话接口（Chat）

复制代码

curl http://localhost:11434/api/chat -d '{
  "model": "qwen3.5:4b",
  "messages": [
    {"role": "user", "content": "你好"}
  ],
  "stream": false
}'

该接口适用于 多轮对话场景。

(2) 单次生成（Generate）

复制代码

curl http://localhost:11434/api/generate -d '{
  "model": "qwen3.5:4b",
  "prompt": "什么是人工智能？",
  "stream": false
}'

该接口适用于 单轮文本生成任务。

默认情况下 stream=true，接口会逐 token 流式返回结果。若设置为 false，则会等待模型生成完成后一次性返回完整响应。

(3) 查看本地模型

可以通过以下接口查看已下载的模型：

复制代码

curl http://localhost:11434/api/tags

4.3 OpenAI 兼容接口

Ollama 还提供 兼容 OpenAI API 的接口 （路径前缀 /v1），因此可以直接使用现有的 OpenAI SDK 或第三方工具。

例如：

复制代码

curl http://localhost:11434/v1/chat/completions -d '{
  "model": "qwen3:4b",
  "messages": [
    {"role": "user", "content": "你好"}
  ]
}'

4.4 Python 调用示例

使用 OpenAI Python SDK 也可以直接连接本地 Ollama：

python 复制代码

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1",
    api_key="ollama"
)

resp = client.chat.completions.create(
    model="qwen3:4b",
    messages=[{"role": "user", "content": "你好"}],
)

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

输出

bash 复制代码

你好！很高兴见到你。今天有什么可以帮你的吗？无论是解答疑问、处理任务，还是只是想随便聊聊，我都在这里为你提供帮助。😊

通过这种方式，可以让 原本使用 OpenAI API 的应用程序几乎无需修改代码，就能接入本地模型。

常见使用场景
本地 AI 助手
文档问答（RAG）
代码辅助生成
数据分析助手

附录：常见问题

Q: Ollama 服务没启动？

bash 复制代码

# 检查状态
curl http://localhost:11434/api/tags
# 如果连不上，手动启动（Linux）
ollama serve
# macOS 打开 app
open /Applications/Ollama.app

Q: ollama pull 报 412 错误？

Ollama 版本太旧。参考上方「升级 Ollama」章节，注意客户端和服务端都要更新并重启。

Q: MLX 动态库报错（macOS）？

复制代码

ERROR - generated.c - CHECK failed: mlx_array_item_float16_
ERROR Failed to load MLX dynamic library symbols

这是 Apple Silicon MLX 相关的警告，不影响正常使用。如果持续出现，确保 Ollama.app 是从官网下载的最新版。

Q: Python 调用报 APIConnectionError: Connection error？

curl 能正常访问但 Python openai 库报连接错误，通常是代理导致的。检查是否设置了 HTTP 代理：

bash 复制代码

echo $http_proxy
echo $https_proxy

如果有值，临时取消代理再运行：

bash 复制代码

unset http_proxy https_proxy
python your_script.py

macOS 上开了代理工具（梯子）会导致 localhost 请求也走代理从而连接失败。

也可能是 openai 库未安装或环境不对：

bash 复制代码

# 确认版本 >= 1.0
python -c "import openai; print(openai.__version__)"

Ollama 本地 LLM 配置指南

一、 安装 Ollama

1.1 macOS

1.2 Linux

1.3 升级 Ollama

二、Ollama配置

2.1 常用命令

2.2 启动 Ollama 服务

2.3 其他配置

(1) 模型存储位置

(2) 上下文长度（Context Length）

三、 下载模型

3.1 推荐模型

3.2 不同尺寸版本

3.3 其他可选模型

3.4 查看已下载模型

3.5 下载示例

四、Ollama使用

4.1 命令行交互

4.2 REST API 调用

(1) 对话接口（Chat）

(2) 单次生成（Generate）

(3) 查看本地模型

4.3 OpenAI 兼容接口

4.4 Python 调用示例

附录：常见问题

一、安装 Ollama

三、下载模型