Ollama 本地大模型私有化部署与 API 集成实战

一句话总结：Ollama 是目前本地跑大模型最省心的方案，一条命令就能拉起 Llama 3、Qwen 2、DeepSeek 等模型。但生产级 API 集成时，并发控制、上下文窗口和模型热切换是三个绕不开的坑。

---

背景

几个月前，团队要做内部代码审查助手。数据不能出内网，ChatGPT 不让用，只能本地部署。我评估了三个方案：

• llama.cpp：性能好但 API 层太薄，路由和并发得自己写
• vLLM：生产级吞吐，但对 CUDA 版本要求严格，Windows 用户直接劝退
• Ollama：极致简单，Go 写的守护进程，自带 REST API

最后选了 Ollama。不是因为它最强，而是最快跑通。

---

环境准备

我的机器：

配置	参数
CPU	i7-14700K
内存	64 GB
GPU	RTX 4090 24 GB
系统	Ubuntu 22.04 + Windows 11 双持

注意：Ollama 在 Linux/NVIDIA 下最稳定。Windows 版基于 WSL2，有网络和 GPU 穿透的小问题，后面会讲。

---

安装

Linux

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

装完自动注册 systemd 服务，默认监听 127.0.0.1:11434。

Windows

去 ollama.com/download 下载安装包。本质是 WSL2 里跑个 Linux 实例，ollama list 之类的命令通过 ollama.exe 桥接进来。

验证

ollama --version
# ollama version 0.3.12

---

拉模型并跑起来

Ollama 的模型库分两种：官方维护的和社区改的。我的选择：

# 通用对话（推荐首选）
ollama pull llama3.1:8b

# 中文能力更强
ollama pull qwen2:7b

# 代码专用
ollama pull deepseek-coder:6.7b

用 ollama run 可以直接对话测试：

ollama run llama3.1:8b "用 Python 写一个斐波那契生成器"

第一次加载会慢（模型从磁盘加载到显存），后续几乎秒回。

模型存在哪

~/.ollama/models/
├── blobs/          # 模型权重文件（大）
└── manifests/      # 元数据

一个 7B 模型大约占 4-5 GB 磁盘，8B 约 5-6 GB。磁盘不够的话，可以在启动前设置 OLLAMA_MODELS 环境变量迁移到其他盘。

---

API 集成——最核心的部分

Ollama 暴露的是标准 REST API，任意语言都能调。

基础调用

curl http://localhost:11434/api/generate -d '{
  "model": "llama3.1:8b",
  "prompt": "什么是 CAP 定理？",
  "stream": false
}'

返回 JSON 结构清晰，response 字段就是生成的文本。

Python SDK 集成

官方提供了 ollama Python 库：

pip install ollama

import ollama

response = ollama.chat(
    model='llama3.1:8b',
    messages=[
        {'role': 'user', 'content': '用三句话解释什么是 RESTful API'}
    ]
)
print(response['message']['content'])

但这个 SDK 在 stream 和 context 管理上封装得过于"友好"，深入控制时反而受限。 我建议直接走 REST API：

import requests
import json

class OllamaClient:
    def __init__(self, base_url="http://localhost:11434"):
        self.base_url = base_url

    def generate(self, model: str, prompt: str,
                 system: str = "", stream: bool = False,
                 options: dict = None) -> str:
        payload = {
            "model": model,
            "prompt": prompt,
            "system": system,
            "stream": stream,
            "options": options or {}
        }
        resp = requests.post(
            f"{self.base_url}/api/generate",
            json=payload,
            stream=stream,
            timeout=120
        )
        if stream:
            return self._handle_stream(resp)
        return resp.json()["response"]

    def chat(self, model: str, messages: list,
             stream: bool = False, options: dict = None) -> str:
        payload = {
            "model": model,
            "messages": messages,
            "stream": stream,
            "options": options or {}
        }
        resp = requests.post(
            f"{self.base_url}/api/chat",
            json=payload,
            stream=stream,
            timeout=120
        )
        if stream:
            return self._handle_stream(resp)
        return resp.json()["message"]["content"]

    def _handle_stream(self, resp):
        for line in resp.iter_lines():
            if line:
                data = json.loads(line)
                if "response" in data:
                    yield data["response"]
                if data.get("done"):
                    break

保存成 ollama_client.py，用起来就一个 import：

client = OllamaClient()
resp = client.chat("qwen2:7b", [
    {"role": "system", "content": "你是一个代码审查助手，只挑真正的 bug。"},
    {"role": "user", "content": "审查以下代码：..."}
])
print(resp)

---

踩坑记录

这节是我最想写的。网上教程千篇一律"三分钟上手 Ollama"，但真实场景里遇到的问题没人讲。

坑 1：并发请求直接崩

默认 Ollama 一个模型只能同时处理一个请求。多发几个并行请求，后面的会排队超时。

解决：设置 OLLAMA_NUM_PARALLEL：

# 启动时指定
OLLAMA_NUM_PARALLEL=4 ollama serve

# 或写入 systemd 配置

# /etc/systemd/system/ollama.service
[Service]
Environment="OLLAMA_NUM_PARALLEL=4"

但注意：并发数不是越高越好。RTX 4090 实测 4 路并发，推理速度从 50 tokens/s 掉到 15 tokens/s。GPU 内存就那么大，并行请求共享显存，总吞吐有限。

坑 2：上下文窗口不够

Ollama 默认 num_ctx 是 2048 tokens。代码审查一次要塞几千行代码，直接截断。

client.generate("llama3.1:8b", long_code,
    options={"num_ctx": 8192})

调大上下文后显存占用暴涨。7B 模型 8K 窗口约多占 2 GB 显存。开到 32K 的话，24 GB 显存可能直接填满。

经验：7B/8B 模型控制在 8K 窗口以内，超过后用滑动窗口或 RAG 切分。

坑 3：Windows WSL2 的 GPU 穿透

Windows 下的 Ollama 默认走 CPU，慢到怀疑人生。需要手动让 WSL2 用上 NVIDIA 显卡：

# Windows 端装 NVIDIA Driver for WSL
# WSL2 内装 CUDA Toolkit
wget https://developer.download.nvidia.com/compute/cuda/repos/wsl-ubuntu/x86_64/cuda-keyring_1.1-1_all.deb
sudo dpkg -i cuda-keyring_1.1-1_all.deb
sudo apt update
sudo apt install cuda-toolkit-12-4

装完重启 WSL，nvidia-smi 能看到了，Ollama 才会自动走 GPU。

坑 4：模型热切换

Ollama 切换到另一个模型时，原先模型的权重不会自动卸载。两个模型抢显存，直接 OOM。

解决：手动卸载：

ollama stop llama3.1:8b
ollama run qwen2:7b

如果用 API 切换，先调 api/generate 加空 prompt 触发另一个模型加载，但前一个模型仍然在显存里。生产环境建议一个进程只管一个模型，别在代码里动态切。

---

进阶：自定义 Modelfile

Ollama 支持用 Modelfile 调整模型参数——不是微调权重，是改推理参数和系统提示。相当于给模型写一个配置文件。

# Modelfile
FROM qwen2:7b

# 系统级角色设定
SYSTEM """你是一个严谨的代码审查助手。
检查重点：
1. 安全漏洞（SQL 注入、XSS）
2. 内存泄漏
3. 并发竞态条件
只报告确定的问题，不要 AI 幻觉。"""

# 调整推理参数
PARAMETER temperature 0.2
PARAMETER top_p 0.9
PARAMETER num_ctx 8192

ollama create code-reviewer -f Modelfile
ollama run code-reviewer

这样打成一个"模型"，团队内分发只需导出 Modelfile 文件，不需要每个人手调参数。

---

延伸思考

1. Ollama 只是一个起点。单机部署终究有瓶颈，生产环境吞吐量要求高时，vLLM + TensorRT-LLM 才是答案。Ollama 的价值在于开发阶段和低并发场景的快速迭代。
2. 显存就是钱。本地部署大模型，瓶颈永远是显存。7B 模型是性价比最高的入门点，13B 以上需要双卡或 A100，预算跳跃极大。
3. API 兼容性陷阱。Ollama 的 API 和 OpenAI API 不完全兼容。如果你想做"今天 Ollama，明天 OpenAI"的平滑迁移，需要在客户端封装一层 adapter，而不是直接用 Ollama 的 SDK。
4. 数据安全不是"本地部署"四个字就能解决的。模型本身可能是开源的，但你的 prompt 会写进日志、模型输出可能包含敏感信息、本地部署不等于没有漏洞。安全是系统工程，本地推理只是其中一环。

---

资源

• Ollama GitHub
• Ollama 模型库
• Modelfile 文档

\n