大模型应用开发 / 系统课时
使用 Python SDK
使用 Python SDK
学习目标
完成本课后,你将能够:
- 安装并导入官方
ollamaPython 库- 使用
generate和chat完成调用- 处理流式迭代器与客户端配置
- 捕获连接错误和服务端响应错误
准备 Python 环境
创建虚拟环境:
bash
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install ollamaWindows 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。
按自己的节奏,确认真正理解。