大模型应用开发 / 系统课时

使用 Python SDK

使用 Python SDK

学习目标

完成本课后,你将能够:

  • 安装并导入官方 ollama Python 库
  • 使用 generate 和 chat 完成调用
  • 处理流式迭代器与客户端配置
  • 捕获连接错误和服务端响应错误

准备 Python 环境

创建虚拟环境:

bash
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install ollama

Windows PowerShell 激活命令为:

powershell
.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install ollama

预期输出:

text
Successfully installed ollama-<VERSION> ...
或提示 requirement already satisfied。

生成接口

保存为 sdk_generate.py:

python
from ollama import generate

response = generate(
    model="gemma3:1b",
    prompt="用两句话解释 Python SDK 的价值。",
    options={
        "temperature": 0,
        "num_predict": 100,
    },
)

print(response["response"].strip())
print(f"done={response['done']}")

运行:

bash
python sdk_generate.py

预期输出结构:

text
<MODEL_RESPONSE>
done=True

对话接口

保存为 sdk_chat.py:

python
from ollama import chat

messages = [
    {
        "role": "system",
        "content": "你是技术助教,回答必须使用中文。",
    },
    {
        "role": "user",
        "content": "Ollama 的 chat 和 generate 有什么区别?",
    },
]

response = chat(
    model="gemma3:1b",
    messages=messages,
    options={"temperature": 0},
)

print(response["message"]["content"].strip())

运行:

bash
python sdk_chat.py

预期输出:

text
<MODEL_RESPONSE>

流式聊天

保存为 sdk_stream.py:

python
from ollama import chat

stream = chat(
    model="gemma3:1b",
    messages=[
        {
            "role": "user",
            "content": "用四个要点说明流式输出的注意事项。",
        }
    ],
    stream=True,
)

for part in stream:
    content = part["message"].get("content", "")
    if content:
        print(content, end="", flush=True)

print()

运行:

bash
python sdk_stream.py

预期输出:

text
<INCREMENTAL_MODEL_RESPONSE>

自定义客户端地址

当 Ollama 位于其他受控主机时:

python
from ollama import Client

client = Client(
    host="http://<OLLAMA_HOST>:11434",
    headers={"X-Client-Name": "anystack-tutorial"},
)

response = client.chat(
    model="gemma3:1b",
    messages=[{"role": "user", "content": "只回答:connected"}],
)

print(response["message"]["content"].strip())

预期输出:

text
<MODEL_RESPONSE>

<OLLAMA_HOST> 替换为真实地址。远程服务必须由网络访问控制、TLS 和认证代理保护。

异常处理

保存为 sdk_error_handling.py:

python
import ollama

try:
    response = ollama.chat(
        model="gemma3:1b",
        messages=[{"role": "user", "content": "你好"}],
    )
except ollama.ResponseError as exc:
    raise SystemExit(
        f"Ollama 返回错误: status={exc.status_code}, error={exc.error}"
    ) from exc
except ConnectionError as exc:
    raise SystemExit("无法连接 Ollama 服务") from exc

print(response["message"]["content"].strip())

运行:

bash
python sdk_error_handling.py

预期结果:

text
服务正常时输出模型回答;服务或模型异常时输出明确错误并以非零状态退出。

同步与异步

官方库同时提供同步客户端和 AsyncClient。Web 服务中可使用异步调用避免阻塞事件循环,但仍需设置:

  • 请求超时
  • 并发上限
  • 取消传播
  • 错误重试边界
  • 模型驻留策略
  • 日志脱敏

异步不会让单个模型计算变快,只是改善应用线程或协程的调度。

本课练习

练习 1:封装 SDK 服务类

任务目标:统一模型、地址和超时。输入或初始条件:Python 项目已安装官方库。

实现要求:提供 generate 与 chat 方法。验收条件:错误转换为业务可识别异常。

练习 2:实现异步流式聊天

任务目标:练习 AsyncClient。输入或初始条件:使用支持 asyncio 的 Python。实现要求:逐块输出并支持取消。验收条件:取消后不保存残缺助手消息。

练习 3:增加响应指标

任务目标:采集性能元数据。输入或初始条件:非流式 SDK 调用。实现要求:记录 Token 和耗时字段。验收条件:能计算输出 Token/s。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

使用 Python SDK

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通