Ollama 本地 CPU 部署开源大模型实战指南

此模式适合简单的脚本调用，返回完整的响应内容。

3.2 使用 OpenAI 兼容接口

为了利用更广泛的生态工具，推荐使用 OpenAI 客户端库。

pip install openai

代码示例（流式输出）：

from openai import OpenAI
from IPython.display import display, clear_output

client = OpenAI(
    base_url='http://localhost:11434/v1/',
    api_key='ollama', # 本地部署通常不需要真实 Key
)

completion = client.chat.completions.create(
    messages=[
        {
            'role': 'user',
            'content': '段子赏析：爱一个人的眼神是藏不住的，爱两个人就一定要藏住。',
        }
    ],
    model='qwen2',
    stream=True
)

response = ""
for chunk in completion:
    response += chunk.choices[0].delta.content
    print(response)
    clear_output(wait=True)

流式输出能显著提升用户体验，特别是在长文本生成场景下。

四、Jupyter Notebook 魔法命令集成

在数据分析或科研场景中，Jupyter Notebook 是常用的开发环境。通过自定义魔法命令，可以实现多轮对话上下文保持，避免重复输入历史消息。

4.1 自定义类实现

以下代码定义了一个 Ollama 类，封装了对话逻辑和历史管理：

import sys
class Ollama:
    def __init__(self, model='qwen2', max_chat_rounds=20, stream=True, system=None, history=None):
        self.model = model
        self.history = [] if history is None else history
        self.max_chat_rounds = max_chat_rounds
        self.stream = stream
        self.system = system
        try:
            self.register_magic()
            response = self('你好')
            if not self.stream:
                print(response)
            print('register magic %%chat succeeded ...', file=sys.stderr)
            self.history = self.history[:-1]
        except Exception as err:
            print('register magic %%chat failed ...', file=sys.stderr)
            print(err)

    @classmethod
    def build_messages(cls, query=None, history=None, system=None):
        messages = []
        history = history if history else []
        if system is not None:
            messages.append({'role': 'system', 'content': system})
        for prompt, response in history:
            pair = [{"role": "user", "content": prompt}, {"role": "assistant", "content": response}]
            messages.extend(pair)
        if query is not None:
            messages.append({"role": "user", "content": query})
        return messages

    def chat(self, messages, stream=True):
        from openai import OpenAI
        client = OpenAI(base_url='http://localhost:11434/v1/', api_key='ollama')
        completion = client.chat.completions.create(messages=messages, model=self.model, stream=stream)
        return completion

    def __call__(self, query):
        from IPython.display import display, clear_output
        len_his = len(self.history)
        if len_his >= self.max_chat_rounds + 1:
            self.history = self.history[len_his - self.max_chat_rounds:]
        messages = self.build_messages(query=query, history=self.history, system=self.system)
        
        if not self.stream:
            completion = self.chat(messages, stream=False)
            response = completion.choices[0].message.content
            self.history.append((query, response))
            return response
        
        completion = self.chat(messages, stream=True)
        response = ""
        for chunk in completion:
            response += chunk.choices[0].delta.content
            print(response)
            clear_output(wait=True)
        self.history.append((query, response))
        return response

    def register_magic(self):
        import IPython
        from IPython.core.magic import Magics, magics_class, line_cell_magic
        
        @magics_class
        class ChatMagics(Magics):
            def __init__(self, shell, pipe):
                super().__init__(shell)
                self.pipe = pipe

            @line_cell_magic
            def chat(self, line, cell=None):
                if cell is None:
                    return self.pipe(line)
                else:
                    print(self.pipe(cell))
        
        ipython = IPython.get_ipython()
        magic = ChatMagics(ipython, self)
        ipython.register_magics(magic)

4.2 使用方法

在 Notebook 中运行上述代码后，即可使用 %chat 或 %%chat 命令进行对话。该实现自动维护最近 20 轮的对话历史，并在达到上限时自动裁剪旧记录，节省显存/内存资源。

五、性能优化与常见问题

5.1 量化与内存管理

在 CPU 上运行大模型时，内存是关键瓶颈。Ollama 默认使用量化版本（如 Q4_K_M），这能在精度和速度间取得平衡。

• 减少并发：CPU 推理受限于单核或多核频率，避免同时运行多个大模型实例。
• 模型选择：优先选择参数量较小的模型（如 7B 以下），除非硬件配置极高。

5.2 常见错误排查

• 端口占用：如果报错 address already in use，检查是否有旧进程占用 11434 端口。
• 权限问题：Linux 下可能需要添加用户到 docker 组或使用 sudo（视安装方式而定）。
• 网络超时：首次下载模型较慢，建议使用国内镜像源或稳定网络环境。

六、安全与隐私注意事项

本地部署的最大优势在于数据不出域。

1. 网络隔离：建议将 Ollama 服务绑定到内网 IP，避免暴露在公网。
2. API 密钥：虽然本地模拟 OpenAI 接口，但生产环境中应配置鉴权中间件。
3. 敏感数据：避免向模型输入个人隐私信息，尽管是本地运行，仍需防范 Prompt 注入攻击。

七、总结

Ollama 为开发者提供了一个轻量级、易用的本地大模型运行方案。通过本文介绍的安装、CLI 控制、Python 集成及 Jupyter 扩展，您可以快速构建基于开源模型的私有化 AI 应用。结合 OpenAI 兼容接口，还能轻松复用现有的 AI 工程生态，极大降低了本地部署的门槛。