Python SDK集成：ollama-python库实战

好，咱们进入第三章节。前面两章我们把Ollama的安装和基础API摸透了，现在该聊聊怎么在Python项目里真正用起来。说白了，Python SDK才是我们日常开发中最常打交道的东西。

我个人习惯把ollama-python看作一个「翻译官」——它把Ollama的HTTP API包装成Python开发者熟悉的函数调用。你想想看，如果每次调用都要自己拼HTTP请求、处理JSON响应，那得多累？

3.1 安装ollama-python库

安装过程其实很简单，但有几个坑我得提前说。

# 基础安装
pip install ollama

# 如果你在虚拟环境里，记得先激活
# 我建议用Python 3.10+，3.8以下就别折腾了
⚠️ 注意： 我曾经在Windows上遇到过pip安装卡住的情况，后来发现是网络问题。建议用国内镜像源： 
pip install ollama -i https://pypi.tuna.tsinghua.edu.cn/simple

安装完成后，验证一下：

import ollama
print(ollama.__version__)  # 我写这章时是0.3.7

3.2 客户端初始化

初始化客户端，说白了就是告诉SDK：「嘿，我的Ollama服务跑在哪？」

from ollama import Client

# 默认连接本地localhost:11434
client = Client()

# 如果你部署在远程服务器
client = Client(host='http://192.168.1.100:11434')

# 或者用环境变量，我项目里常用这种方式
import os
client = Client(host=os.getenv('OLLAMA_HOST', 'http://localhost:11434'))
💡 小技巧： 我在微服务架构里习惯把Ollama地址配在配置中心，这样切换环境时不用改代码。你想想看，开发、测试、生产环境各一套配置，多省心。

3.3 同步调用

同步调用是最直观的方式。你调用一个函数，它阻塞等待，返回结果。适合简单的脚本或者对实时性要求不高的场景。

# 最简单的对话
response = client.chat(model='llama3.2', messages=[
    {'role': 'user', 'content': '你好，请介绍一下你自己'}
])
print(response['message']['content'])

# 生成文本（补全模式）
response = client.generate(model='llama3.2', prompt='Python是一种')
print(response['response'])

嗯，这里要注意：chat和generate的区别。chat是对话模式，带消息历史；generate是纯文本补全。我刚开始用的时候经常搞混，后来养成了习惯——做聊天机器人用chat，做文本生成用generate。

3.4 异步调用

为什么需要异步？我在项目中遇到过这样的场景：同时调用3个不同模型做对比，如果同步调用，一个接一个等，总耗时就是3个模型响应时间之和。异步调用可以并发执行，总耗时≈最慢的那个模型。

import asyncio
from ollama import AsyncClient

async def main():
    # 初始化异步客户端
    async_client = AsyncClient()
    
    # 异步对话
    response = await async_client.chat(model='llama3.2', messages=[
        {'role': 'user', 'content': '用Python写一个快速排序'}
    ])
    print(response['message']['content'])
    
    # 并发调用多个模型
    models = ['llama3.2', 'mistral', 'qwen2.5']
    tasks = []
    for model in models:
        tasks.append(async_client.chat(
            model=model,
            messages=[{'role': 'user', 'content': '1+1等于几？'}]
        ))
    
    # 等待所有任务完成
    results = await asyncio.gather(*tasks)
    for model, result in zip(models, results):
        print(f"{model}: {result['message']['content']}")

# 运行
asyncio.run(main())
🔑 关键点： 异步调用必须配合await关键字，而且整个调用链都得是异步的。我曾经在Flask视图函数里直接写await，结果报错——Flask默认是同步的，得用quart或者fastapi才行。

3.5 错误处理机制

网络请求嘛，总会出各种幺蛾子。模型加载失败、服务宕机、超时……我见过最离谱的是有人把模型名拼错了，然后debug了一整天。

from ollama import Client, ResponseError
import time

client = Client()

def safe_chat(model, messages, max_retries=3):
    """带重试机制的对话函数"""
    for attempt in range(max_retries):
        try:
            response = client.chat(model=model, messages=messages)
            return response['message']['content']
        
        except ResponseError as e:
            # 模型不存在或加载失败
            print(f"模型错误: {e.error}")
            if 'not found' in str(e.error).lower():
                print(f"模型 {model} 未找到，请先 pull")
                return None
            # 其他错误，重试
            if attempt < max_retries - 1:
                wait = 2 ** attempt  # 指数退避
                print(f"第{attempt+1}次失败，{wait}秒后重试...")
                time.sleep(wait)
            else:
                raise
        
        except ConnectionError as e:
            print(f"连接失败: {e}")
            print("请检查Ollama服务是否启动")
            return None
        
        except TimeoutError as e:
            print(f"请求超时: {e}")
            if attempt < max_retries - 1:
                time.sleep(1)
            else:
                raise
    
    return None

# 使用示例
try:
    result = safe_chat(
        model='llama3.2',
        messages=[{'role': 'user', 'content': '你好'}]
    )
    if result:
        print(result)
except Exception as e:
    print(f"最终失败: {e}")
⚠️ 避坑指南： 我曾经在生产环境遇到过Ollama服务突然重启，导致所有请求都返回ConnectionError。后来我加了健康检查——每次调用前先ping一下： 
def is_ollama_ready():
    try:
        client.list()  # 列出模型，如果服务正常会返回
        return True
    except:
        return False

3.6 知识体系总览

下面这张图是我自己梳理的，把本章的核心知识点串起来了。你保存下来，以后写代码时对照着看。

ollama-python SDK 集成知识体系 ① 安装与初始化 pip install ollama → Client(host='...') → 环境变量配置 ② 调用方式 同步调用 client.chat() / client.generate() 异步调用 AsyncClient → await → asyncio.gather() ③ 核心功能 chat() 对话模式 generate() 文本补全 list() 模型管理 ④ 错误处理机制 ResponseError ConnectionError TimeoutError 重试+指数退避

3.7 实战建议

最后，分享几个我在项目中沉淀下来的经验：

  • 连接池复用：不要在每次请求时都new一个Client，全局初始化一次就够了。我见过有人每次调用都创建客户端，结果把Ollama服务搞崩了。
  • 超时设置：大模型响应时间波动很大，我一般设30秒超时，复杂任务设60秒。
  • 日志记录：每次调用都记录模型名、输入长度、响应时间，方便排查问题。
  • 模型预热：如果模型第一次加载很慢，可以在服务启动时先发一个空请求「预热」一下。
💡 我的习惯： 我会封装一个ModelClient类，把初始化、重试、日志、健康检查都包进去。这样业务代码里只需要client.chat()，清爽得很。

好了，这一章就到这里。Python SDK这块其实不难，关键是养成良好的错误处理习惯。下一章我们会聊更高级的话题——模型热加载与动态切换，到时候这些基础就派上用场了。

公众号:蓝海资料掘金营，微信deep3321

← 上一章 📖 返回目录 下一章 →