Ollama本地部署大模型：从零到生产级避坑指南

1. 真实场景：一个让我加班到凌晨3点的部署事故

2024年11月，公司要上线一个内部AI客服系统，要求所有数据不出内网。我选了Ollama部署Qwen2.5-7B，以为半小时搞定。结果：

• 第一次启动，Ollama直接OOM，服务器32GB内存瞬间吃满
• 调低模型量化后，首token延迟2.3秒，用户直接骂娘
• 并发3个请求，服务直接挂掉，日志全是"CUDA out of memory"
• 更坑的是，第二天发现模型回答全是乱码——因为Ollama默认用CPU推理

这篇文章就是我当时踩完坑后的完整方案。你照着做，至少省3天调试时间。

2. 方案对比：为什么选Ollama而不是vLLM/llama.cpp

先看三个主流方案的对比数据（测试环境：RTX 4090 24GB, Intel i9-13900K, 64GB DDR5, Ubuntu 22.04, 模型Qwen2.5-7B-Instruct-Q4_K_M）：

结论：

• 追求极致吞吐量选vLLM，但部署复杂，需要手动配置CUDA kernel
• 追求最低内存占用选llama.cpp，但并发能力弱，API需要自己写
• Ollama是平衡点：部署最快、API最友好、性能足够生产使用。我们最终选Ollama，因为团队只有2个后端，没时间折腾vLLM

3. 完整部署方案：Docker Compose + 多模型管理

3.1 环境准备

# 系统要求
# Ubuntu 22.04 / Debian 12
# NVIDIA Driver >= 545.23.08
# Docker >= 24.0.7
# NVIDIA Container Toolkit >= 1.14.5

# 验证GPU驱动
nvidia-smi
# 输出示例：
# +-----------------------------------------------------------------------------+
# | NVIDIA-SMI 545.23.08    Driver Version: 545.23.08    CUDA Version: 12.3     |
# | GPU 0: NVIDIA GeForce RTX 4090   24GB    |
# +-----------------------------------------------------------------------------+

# 安装NVIDIA Container Toolkit
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list | \
  sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
  sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit
sudo systemctl restart docker

3.2 Docker Compose部署（生产级配置）

# docker-compose.yml
# Ollama 0.3.12 + Open WebUI 0.3.8
# 支持多模型热切换，自动加载到GPU

version: '3.8'

services:
  ollama:
    image: ollama/ollama:0.3.12
    container_name: ollama-server
    restart: unless-stopped
    ports:
      - "11434:11434"
    volumes:
      - ./ollama_data:/root/.ollama  # 模型持久化
      - ./models:/models              # 自定义模型目录
    environment:
      - OLLAMA_HOST=0.0.0.0
      - OLLAMA_PORT=11434
      - OLLAMA_KEEP_ALIVE=5m         # 模型保持5分钟不卸载
      - OLLAMA_NUM_PARALLEL=4        # 并行请求数
      - OLLAMA_MAX_LOADED_MODELS=2   # 最多同时加载2个模型
      - CUDA_VISIBLE_DEVICES=0       # 指定GPU
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:11434/api/tags"]
      interval: 30s
      timeout: 10s
      retries: 3

  open-webui:
    image: ghcr.io/open-webui/open-webui:0.3.8
    container_name: open-webui
    restart: unless-stopped
    ports:
      - "3000:8080"
    volumes:
      - ./webui_data:/app/backend/data
    environment:
      - OLLAMA_BASE_URL=http://ollama:11434
      - WEBUI_SECRET_KEY=your-secret-key-here
    depends_on:
      ollama:
        condition: service_healthy

3.3 下载并运行模型

# 启动服务
docker compose up -d

# 查看日志确认GPU可用
docker logs ollama-server | grep -i "cuda\|gpu"
# 正常输出：CUDA available: true

# 下载模型（推荐Qwen2.5-7B，中文表现最好）
docker exec -it ollama-server ollama pull qwen2.5:7b-instruct-q4_K_M

# 查看已下载模型
docker exec -it ollama-server ollama list
# 输出示例：
# NAME                          ID              SIZE      MODIFIED
# qwen2.5:7b-instruct-q4_K_M   4b8e5f8a5c2a    4.1 GB    2 minutes ago

# 测试推理
curl http://localhost:11434/api/generate -d '{
  "model": "qwen2.5:7b-instruct-q4_K_M",
  "prompt": "用中文解释什么是Ollama，50字以内",
  "stream": false
}'

4. API调用代码（Python + PHP双版本）

4.1 Python异步客户端（生产级）

# ollama_client.py
# Python 3.11+, aiohttp 3.9+
# 支持流式输出、超时控制、自动重试

import asyncio
import json
import time
from typing import AsyncGenerator, Optional
import aiohttp

class OllamaClient:
    def __init__(self, base_url: str = "http://localhost:11434", timeout: int = 60):
        self.base_url = base_url.rstrip('/')
        self.timeout = aiohttp.ClientTimeout(total=timeout)
        self.session: Optional[aiohttp.ClientSession] = None

    async def __aenter__(self):
        self.session = aiohttp.ClientSession(timeout=self.timeout)
        return self

    async def __aexit__(self, *args):
        if self.session:
            await self.session.close()

    async def generate(
        self,
        model: str,
        prompt: str,
        system_prompt: str = "你是一个有用的AI助手。",
        temperature: float = 0.7,
        max_tokens: int = 2048,
        stream: bool = True
    ) -> AsyncGenerator[str, None]:
        """流式生成，逐token返回"""
        payload = {
            "model": model,
            "prompt": prompt,
            "system": system_prompt,
            "options": {
                "temperature": temperature,
                "num_predict": max_tokens
            },
            "stream": stream
        }

        async with self.session.post(
            f"{self.base_url}/api/generate",
            json=payload
        ) as resp:
            if resp.status != 200:
                error_text = await resp.text()
                raise Exception(f"API error {resp.status}: {error_text}")

            if stream:
                async for line in resp.content:
                    if line:
                        try:
                            data = json.loads(line.decode('utf-8').strip())
                            if 'response' in data:
                                yield data['response']
                            if data.get('done', False):
                                break
                        except json.JSONDecodeError:
                            continue
            else:
                data = await resp.json()
                yield data.get('response', '')

    async def chat(
        self,
        model: str,
        messages: list,
        stream: bool = True
    ) -> AsyncGenerator[str, None]:
        """聊天接口，兼容OpenAI格式"""
        payload = {
            "model": model,
            "messages": messages,
            "stream": stream
        }

        async with self.session.post(
            f"{self.base_url}/api/chat",
            json=payload
        ) as resp:
            if resp.status != 200:
                error_text = await resp.text()
                raise Exception(f"Chat API error {resp.status}: {error_text}")

            if stream:
                async for line in resp.content:
                    if line:
                        try:
                            data = json.loads(line.decode('utf-8').strip())
                            if 'message' in data and 'content' in data['message']:
                                yield data['message']['content']
                            if data.get('done', False):
                                break
                        except json.JSONDecodeError:
                            continue
            else:
                data = await resp.json()
                yield data['message']['content']

# 使用示例
async def main():
    async with OllamaClient() as client:
        print("=== 流式生成 ===")
        async for token in client.generate(
            model="qwen2.5:7b-instruct-q4_K_M",
            prompt="写一首关于春天的五言绝句",
            stream=True
        ):
            print(token, end='', flush=True)
        print("\n")

        print("=== 聊天模式 ===")
        messages = [
            {"role": "system", "content": "你是一个诗人。"},
            {"role": "user", "content": "写一首关于秋天的诗"}
        ]
        async for token in client.chat(
            model="qwen2.5:7b-instruct-q4_K_M",
            messages=messages,
            stream=True
        ):
            print(token, end='', flush=True)

if __name__ == "__main__":
    asyncio.run(main())

4.2 PHP同步客户端（兼容旧项目）

baseUrl = rtrim($baseUrl, '/');
        $this->client = new Client([
            'base_uri' => $this->baseUrl,
            'timeout' => 60,
            'http_errors' => false
        ]);
    }
    
    /**
     * 非流式生成
     */
    public function generate(
        string $model,
        string $prompt,
        string $systemPrompt = '你是一个有用的AI助手。',
        float $temperature = 0.7,
        int $maxTokens = 2048
    ): string {
        $payload = [
            'model' => $model,
            'prompt' => $prompt,
            'system' => $systemPrompt,
            'options' => [
                'temperature' => $temperature,
                'num_predict' => $maxTokens
            ],
            'stream' => false
        ];
        
        try {
            $response = $this->client->post('/api/generate', [
                'json' => $payload
            ]);
            
            if ($response->getStatusCode() !== 200) {
                throw new \Exception("API error: " . $response->getBody());
            }
            
            $data = json_decode($response->getBody(), true);
            return $data['response'] ?? '';
            
        } catch (RequestException $e) {
            throw new \Exception("Request failed: " . $e->getMessage());
        }
    }
    
    /**
     * 流式生成（回调方式）
     */
    public function generateStream(
        string $model,
        string $prompt,
        callable $callback,
        string $systemPrompt = '你是一个有用的AI助手。',
        float $temperature = 0.7,
        int $maxTokens = 2048
    ): void {
        $payload = [
            'model' => $model,
            'prompt' => $prompt,
            'system' => $systemPrompt,
            'options' => [
                'temperature' => $temperature,
                'num_predict' => $maxTokens
            ],
            'stream' => true
        ];
        
        try {
            $response = $this->client->post('/api/generate', [
                'json' => $payload,
                'stream' => true
            ]);
            
            $body = $response->getBody();
            while (!$body->eof()) {
                $line = $body->read(1024);
                $lines = explode("\n", $line);
                
                foreach ($lines as $jsonLine) {
                    $jsonLine = trim($jsonLine);
                    if (empty($jsonLine)) continue;
                    
                    $data = json_decode($jsonLine, true);
                    if (isset($data['response'])) {
                        call_user_func($callback, $data['response']);
                    }
                    if (isset($data['done']) && $data['done']) {
                        break 2;
                    }
                }
            }
        } catch (RequestException $e) {
            throw new \Exception("Stream request failed: " . $e->getMessage());
        }
    }
}

// 使用示例
$client = new OllamaClient();

// 非流式调用
$result = $client->generate(
    'qwen2.5:7b-instruct-q4_K_M',
    '用一句话解释量子纠缠'
);
echo "非流式结果: " . $result . "\n";

// 流式调用
echo "流式结果: ";
$client->generateStream(
    'qwen2.5:7b-instruct-q4_K_M',
    '写一个关于AI的短故事',
    function($token) {
        echo $token;
        ob_flush();
        flush();
    }
);
echo "\n";

5. 性能压测与优化

5.1 压测脚本

# benchmark.sh
# 使用hey压测工具，模拟并发请求
# 安装：go install github.com/rakyll/hey@latest

# 测试1：单请求延迟
echo "=== 单请求延迟测试 ==="
time curl -X POST http://localhost:11434/api/generate \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen2.5:7b-instruct-q4_K_M",
    "prompt": "请用50字以内解释什么是机器学习",
    "stream": false,
    "options": {"num_predict": 100}
  }'

# 测试2：并发压测（4并发，100请求）
echo "=== 4并发压测 ==="
hey -n 100 -c 4 \
  -m POST \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen2.5:7b-instruct-q4_K_M",
    "prompt": "请用50字以内解释什么是深度学习",
    "stream": false,
    "options": {"num_predict": 100}
  }' \
  http://localhost:11434/api/generate

# 测试3：8并发压测
echo "=== 8并发压测 ==="
hey -n 200 -c 8 \
  -m POST \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen2.5:7b-instruct-q4_K_M",
    "prompt": "请用50字以内解释什么是神经网络",
    "stream": false,
    "options": {"num_predict": 100}
  }' \
  http://localhost:11434/api/generate

5.2 实测数据（RTX 4090, Qwen2.5-7B-Q4_K_M）

关键发现：

• OLLAMA_NUM_PARALLEL从1调到4，首token延迟降低82%，吞吐量提升184%
• 调到8后收益递减，显存占用增加15%，但吞吐量只提升22%
• 7B模型在4090上性价比最高，14B模型虽然效果更好但吞吐量腰斩

6. 避坑指南（我踩过的5个坑）

坑1：Ollama默认用CPU推理

现象：部署后推理速度极慢，一个简单问题要10秒以上。
原因：Ollama在Docker中默认不启用GPU，需要显式配置。
解决：在docker-compose.yml中添加deploy.resources.reservations.devices配置，并设置CUDA_VISIBLE_DEVICES=0。
验证：docker logs ollama-server | grep "CUDA available"，如果输出false，说明没启用GPU。

坑2：OLLAMA_KEEP_ALIVE设置不当导致内存泄漏

现象：运行一段时间后，内存持续增长，最终OOM。
原因：OLLAMA_KEEP_ALIVE默认5分钟，如果频繁切换模型，旧模型不会立即卸载。
解决：设置OLLAMA_KEEP_ALIVE=1m，或者根据业务调整。如果只用一个模型，设置成0（永久加载）。
监控：用docker stats ollama-server实时查看内存。

坑3：模型量化版本选错导致回答质量下降

现象：模型回答逻辑混乱，甚至出现乱码。
原因：使用了Q2_K或Q3_K等低精度量化版本，信息损失严重。
解决：生产环境至少用Q4_K_M，7B模型大小约4.1GB，效果接近原版。Q8_0效果最好但显存翻倍。
数据：Q4_K_M在MMLU基准测试上比原版仅下降1.2%，但显存减少60%。

坑4：并发请求导致CUDA OOM

现象：并发超过4个请求时，服务直接崩溃，日志显示"CUDA out of memory"。
原因：Ollama默认每个请求分配独立的KV cache，24GB显存不够用。
解决：设置OLLAMA_NUM_PARALLEL=4，限制最大并发数。同时设置OLLAMA_MAX_LOADED_MODELS=1，避免多模型抢占显存。
优化：如果必须高并发，考虑使用vLLM的PagedAttention机制。

坑5：模型文件损坏导致启动失败

现象：docker exec ollama-server ollama pull完成后，启动时报"model file corrupted"。
原因：网络中断导致模型文件下载不完整。
解决：删除损坏的模型重新下载：docker exec ollama-server ollama rm qwen2.5:7b-instruct-q4_K_M，然后重新pull。
预防：在docker-compose.yml中配置健康检查，自动重启服务。

7. 生产环境监控与告警

# monitor.sh
# 监控Ollama服务状态，异常时发送告警

#!/bin/bash

OLLAMA_URL="http://localhost:11434"
WEBHOOK_URL="https://hooks.slack.com/services/YOUR/WEBHOOK/URL"

# 检查服务健康
health_check() {
    response=$(curl -s -o /dev/null -w "%{http_code}" $OLLAMA_URL/api/tags)
    if [ "$response" != "200" ]; then
        curl -X POST -H "Content-Type: application/json" \
            -d '{"text":"Ollama服务异常，HTTP状态码: '$response'"}' \
            $WEBHOOK_URL
        return 1
    fi
    return 0
}

# 检查GPU使用率
gpu_check() {
    gpu_usage=$(nvidia-smi --query-gpu=memory.used --format=csv,noheader,nounits)
    if [ "$gpu_usage" -gt 20000 ]; then  # 显存超过20GB告警
        curl -X POST -H "Content-Type: application/json" \
            -d '{"text":"GPU显存使用率过高: '$gpu_usage'MB"}' \
            $WEBHOOK_URL
    fi
}

# 检查模型响应时间
latency_check() {
    start_time=$(date +%s%N)
    curl -s -X POST $OLLAMA_URL/api/generate \
        -H "Content-Type: application/json" \
        -d '{"model":"qwen2.5:7b-instruct-q4_K_M","prompt":"test","stream":false}' > /dev/null
    end_time=$(date +%s%N)
    latency=$(( (end_time - start_time) / 1000000 ))  # 转换为毫秒
    
    if [ "$latency" -gt 5000 ]; then  # 超过5秒告警
        curl -X POST -H "Content-Type: application/json" \
            -d '{"text":"模型响应延迟过高: '$latency'ms"}' \
            $WEBHOOK_URL
    fi
}

# 每30秒执行一次
while true; do
    health_check
    gpu_check
    latency_check
    sleep 30
done

8. 总结

Ollama是目前本地部署大模型最省心的方案，没有之一。5分钟部署，API兼容OpenAI，性能足够支撑中小规模生产环境。

关键参数速查：

• OLLAMA_NUM_PARALLEL=4（并发数，4090推荐值）
• OLLAMA_KEEP_ALIVE=5m（模型保活时间）
• OLLAMA_MAX_LOADED_MODELS=2（最大加载模型数）
• 模型量化：Q4_K_M（性价比最高）

如果你遇到任何问题，先看docker logs ollama-server，90%的问题都能在日志里找到线索。