Ollama 本地大模型
部署与应用集成实战

一、Ollama 是什么：本地 AI 的 Docker

如果你曾经为高昂的 API 费用犯愁，或者担心把公司代码、个人文档发送给第三方服务存在安全隐患，那么 Ollama 就是你一直在寻找的答案。

Ollama 是一个开源工具，让你能在自己的笔记本或服务器上本地运行 Llama、Mistral、DeepSeek、Gemma 等主流大语言模型。它的理念就像 Docker 之于容器：把复杂的模型权重、运行时依赖、推理引擎全部打包成一个简单的命令，一行搞定。

Ollama 目前在 GitHub 上已积累超过 10 万 Star，是 2025-2026 年度最热门的本地 AI 工具之一。支持 macOS（Apple Silicon 原生加速）、Linux（CUDA / ROCm GPU 加速）、Windows（WSL2 / 原生）三大平台。

二、环境准备与安装

硬件要求

安装步骤

# 方式一：Homebrew（推荐）
brew install ollama

# 方式二：官网下载安装包
# 访问 https://ollama.com/download 下载 .dmg 文件

# 官方一键安装脚本（自动配置 systemd 服务）
curl -fsSL https://ollama.com/install.sh | sh

# 安装完成后验证服务状态
systemctl status ollama

# 方式一：winget 包管理器
winget install Ollama.Ollama

# 方式二：官网下载 OllamaSetup.exe 直接安装
# 安装后可在 Windows 任务栏找到 Ollama 图标

# CPU 版本（适合测试环境）
docker run -d -v ollama:/root/.ollama \
  -p 11434:11434 \
  --name ollama \
  ollama/ollama

# NVIDIA GPU 版本（需安装 NVIDIA Container Toolkit）
docker run -d --gpus=all \
  -v ollama:/root/.ollama \
  -p 11434:11434 \
  --name ollama \
  ollama/ollama

# 查看版本
ollama --version

# 手动启动服务（如果没有自动启动）
ollama serve

# 检查 API 是否可用（应返回 "Ollama is running"）
curl http://localhost:11434

三、运行你的第一个大模型

安装完成后，一条命令即可下载并运行模型。Ollama 会自动从官方模型库拉取模型文件（类似 Docker pull）：

# 下载并进入交互式聊天（模型首次使用时自动下载）
ollama run llama3.2

# 也可以先 pull 下载，再 run 运行
ollama pull llama3.2
ollama run llama3.2

进入交互模式后，直接输入文字对话。试试这几个命令：

>>> 用一句话解释什么是量子计算
量子计算利用量子力学原理（叠加态和纠缠态）进行并行计算，能够在某些问题上比传统计算机快得多。

>>> /bye       # 退出对话
>>> /?         # 查看内置命令帮助

常用的 Ollama 命令行操作：

# 查看已下载的模型列表
ollama list

# 删除模型（释放磁盘空间）
ollama rm llama3.2

# 查看模型详情和参数
ollama show llama3.2

# 将提示词通过管道传入（非交互模式，适合脚本调用）
echo "用中文解释 Docker 的作用" | ollama run llama3.2

四、主流模型选型指南

Ollama 官方模型库（ollama.com/library）提供了 200+ 个模型，按任务场景选择合适的模型非常关键：

# 快速下载并体验各个模型
ollama pull deepseek-r1:7b       # DeepSeek R1 蒸馏版
ollama pull codellama:7b         # 代码专用
ollama pull mistral              # 快速通用
ollama pull gemma3               # Google Gemma3
ollama pull qwen2.5:7b           # 阿里千问，中文优化

五、REST API 集成实战

Ollama 内置 HTTP 服务，提供两套 API 接口：

• 原生 Ollama API：功能完整，支持流式输出、模型管理
• OpenAI 兼容 API：直接替换 OpenAI，改一行 base_url 即可

原生 API：文本生成

# 基础文本生成（流式输出）
curl http://localhost:11434/api/generate \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama3.2",
    "prompt": "请用三句话解释什么是 RAG 技术",
    "stream": false
  }'

原生 API：多轮对话（Chat）

# 多轮对话接口（维护 messages 历史）
curl http://localhost:11434/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama3.2",
    "messages": [
      {
        "role": "system",
        "content": "你是一位专业的 TypeScript 开发助手，回答简洁精准。"
      },
      {
        "role": "user",
        "content": "如何在 TypeScript 中定义一个泛型工厂函数？"
      }
    ],
    "stream": false
  }'

OpenAI 兼容接口

Ollama 完全兼容 OpenAI Chat Completions API，只需修改 base_url，无需改动任何业务逻辑：

# OpenAI 兼容接口（/v1/chat/completions）
curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ollama" \
  -d '{
    "model": "llama3.2",
    "messages": [
      {"role": "user", "content": "Hello! What can you do?"}
    ]
  }'

模型管理 API

# 列出所有可用模型
curl http://localhost:11434/api/tags

# 拉取新模型（异步，可查看进度）
curl http://localhost:11434/api/pull \
  -d '{"name": "mistral"}'

# 查看模型详细信息
curl http://localhost:11434/api/show \
  -d '{"name": "llama3.2"}'

六、Python 与 JavaScript SDK 集成

Python 集成

Ollama 提供官方 Python SDK，同时也可以直接用 OpenAI SDK 切换到本地模型：

# 安装 Ollama Python 官方库
pip install ollama

# 或者用 OpenAI SDK（修改 base_url 即可）
pip install openai

import ollama

# 方式一：官方 SDK - 简单问答
response = ollama.chat(
    model='llama3.2',
    messages=[
        {'role': 'user', 'content': '请解释 Python 的 GIL 机制'}
    ]
)
print(response['message']['content'])

# 方式二：流式输出（适合实时显示）
stream = ollama.chat(
    model='llama3.2',
    messages=[{'role': 'user', 'content': '写一首关于代码的诗'}],
    stream=True
)
for chunk in stream:
    print(chunk['message']['content'], end='', flush=True)

# 方式三：通过 OpenAI SDK 使用 Ollama（最少改动迁移）
from openai import OpenAI

client = OpenAI(
    base_url='http://localhost:11434/v1',
    api_key='ollama',  # 任意字符串即可
)

completion = client.chat.completions.create(
    model='llama3.2',
    messages=[
        {'role': 'system', 'content': '你是一个专业的代码审查助手'},
        {'role': 'user', 'content': '请帮我审查以下 Python 代码的安全性'}
    ]
)
print(completion.choices[0].message.content)

JavaScript / TypeScript 集成

# 安装 Ollama JS 官方库
npm install ollama
# 或者 bun add ollama

import ollama from 'ollama';

// 方式一：官方 SDK - 简单问答
async function simpleChat() {
  const response = await ollama.chat({
    model: 'llama3.2',
    messages: [{ role: 'user', content: '解释 TypeScript 装饰器的用法' }],
  });
  console.log(response.message.content);
}

// 方式二：流式输出
async function streamChat() {
  const stream = await ollama.chat({
    model: 'llama3.2',
    messages: [{ role: 'user', content: '写一个 React Hook 最佳实践示例' }],
    stream: true,
  });

  for await (const part of stream) {
    process.stdout.write(part.message.content);
  }
}

// 方式三：使用 OpenAI SDK 接入 Ollama（Next.js / Node.js 项目迁移首选）
import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'http://localhost:11434/v1',
  apiKey: 'ollama',
});

async function openaiCompatible() {
  const completion = await client.chat.completions.create({
    model: 'llama3.2',
    messages: [
      { role: 'system', content: '你是一个专业的前端架构师' },
      { role: 'user', content: '请推荐 2026 年 React 项目的最佳目录结构' },
    ],
  });
  console.log(completion.choices[0].message.content);
}

simpleChat();

七、搭建私有化 RAG 知识库

RAG（Retrieval-Augmented Generation，检索增强生成）是当前最实用的 AI 应用模式。结合 Ollama 本地模型，你可以搭建一套完全私有化、零成本的企业知识库。

整个 RAG 流程分为两阶段：

# 安装必要的 Python 包
pip install ollama chromadb pypdf2 langchain langchain-community

# nomic-embed-text 是目前 Ollama 最推荐的 Embedding 模型
ollama pull nomic-embed-text

# 验证 Embedding 是否正常工作
curl http://localhost:11434/api/embeddings \
  -d '{"model": "nomic-embed-text", "prompt": "Ollama 是一个本地 AI 工具"}'

import ollama
import chromadb
from pathlib import Path

# 初始化向量数据库（本地持久化）
client = chromadb.PersistentClient(path="./knowledge_base")
collection = client.get_or_create_collection(
    name="my_docs",
    metadata={"hnsw:space": "cosine"}
)

def get_embedding(text: str) -> list[float]:
    """调用 Ollama 生成文本向量"""
    response = ollama.embeddings(
        model='nomic-embed-text',
        prompt=text
    )
    return response['embedding']

def index_document(file_path: str, doc_id: str):
    """将文档索引到向量数据库"""
    text = Path(file_path).read_text(encoding='utf-8')

    # 按段落分块（简单示例，生产环境建议用 langchain 的 TextSplitter）
    chunks = [chunk.strip() for chunk in text.split('\n\n') if len(chunk.strip()) > 50]

    embeddings = [get_embedding(chunk) for chunk in chunks]
    ids = [f"{doc_id}_{i}" for i in range(len(chunks))]

    collection.add(
        embeddings=embeddings,
        documents=chunks,
        ids=ids
    )
    print(f"✅ 已索引 {len(chunks)} 个文本块")

def rag_query(question: str, top_k: int = 3) -> str:
    """执行 RAG 查询：检索相关文档 + 生成答案"""
    # Step 1: 将问题向量化，检索相关文档
    query_embedding = get_embedding(question)
    results = collection.query(
        query_embeddings=[query_embedding],
        n_results=top_k
    )

    # Step 2: 构建包含上下文的 Prompt
    context = "\n\n".join(results['documents'][0])
    prompt = f"""请根据以下参考资料回答问题。如果资料中没有相关信息，请如实说明。

参考资料：
{context}

问题：{question}

回答："""

    # Step 3: 调用本地 LLM 生成答案
    response = ollama.chat(
        model='llama3.2',
        messages=[{'role': 'user', 'content': prompt}]
    )
    return response['message']['content']

# 使用示例
if __name__ == "__main__":
    # 索引你的文档
    index_document("./docs/api-manual.txt", "api_manual")
    index_document("./docs/user-guide.txt", "user_guide")

    # 开始问答
    answer = rag_query("如何重置用户密码？")
    print(answer)

八、常见问题排查

# macOS 查看日志
cat ~/.ollama/logs/server.log

# Linux 查看日志
journalctl -u ollama -n 50

# 强制指定 GPU 库（NVIDIA）
OLLAMA_LLM_LIBRARY=cuda ollama serve

# Linux / macOS
OLLAMA_HOST=0.0.0.0:11434 ollama serve

# 也可以写入系统环境变量（以 Linux systemd 为例）
sudo systemctl edit ollama  # 添加 Environment="OLLAMA_HOST=0.0.0.0:11434"

TMPDIR=/var/tmp ollama serve

# 创建 Modelfile
cat > Modelfile << 'EOF'
FROM llama3.2
SYSTEM """你是公司内部的技术文档助手，专注于回答关于我们产品的问题。
请始终使用中文回答，保持专业、简洁的风格。"""
PARAMETER temperature 0.7
EOF

# 基于 Modelfile 创建新模型
ollama create my-assistant -f Modelfile

# 使用自定义模型
ollama run my-assistant