Python中使用Ollama API完整教程（附核心代码与结构化输出）

准备环境与安装依赖

在终端中确保已安装 Python 3.8 或以上版本，并确认本地 Ollama 服务正在后台运行。随后安装官方提供的交互库：

pip install ollama

执行核心调用流程

第1步：发起基础对话请求

目的：获取模型的直接文本回复。通过 chat 方法传入模型名称与消息历史即可。

from ollama import chat
from ollama import ChatResponse

response: ChatResponse = chat(
    model='llama3.1', 
    messages=[{'role': 'user', 'content': '为什么天空是蓝色的？'}]
)
print(response.message.content)

第2步：开启流式输出模式

目的：优化长文本阅读体验或降低前端首屏延迟。设置 stream=True 后函数返回一个生成器对象，适合逐字渲染而不必等待全部返回。

stream = chat(
    model='llama3.1',
    messages=[{'role': 'user', 'content': '为什么天空是蓝色的？'}],
    stream=True
)
for chunk in stream:
    print(chunk['message']['content'], end='', flush=True)

第3步：配置结构化JSON输出

目的：将非结构化自然语言转换为程序可读的数据格式。利用 format="json" 配合 temperature=0 锁定输出确定性，并使用 pydantic 进行强类型校验。

from pydantic import BaseModel, Field
from ollama import chat
import json

class CountryInfo(BaseModel):
    capital: str = Field(..., alias="首都")
    population: str = Field(..., alias="人口")
    area: str = Field(..., alias="占地面积")

response = chat(
    model='llama3.1',
    messages=[{'role': 'user', 'content': '请介绍美国的首都、人口和占地面积，并以JSON格式返回。'}],
    format="json",
    options={'temperature': 0}
)
raw_json = response["message"]["content"]
validated_data = CountryInfo.model_validate(json.loads(raw_json))
print(validated_data)

模型全生命周期管理

除了对话交互，Python SDK 封装了完整的底层接口，方便开发者自动管理本地镜像。

模型查询与向量生成

# 列出所有本地已下载模型
ollama.list()

# 查看模型详情与参数配置
ollama.show('llama3.1')

# 拉取模型到本地缓存
ollama.pull('llama3.1')

# 批量生成向量嵌入用于检索增强(Embeddings)
ollama.embed(model='llama3.1', input=['科技动态', '市场分析'])

模型构建与分发

# 基于基础模型创建自定义指令集
modelfile = '''FROM llama3.1
SYSTEM 你是一个专业的大语言模型专家。'''
ollama.create(model='my_expert_bot', modelfile=modelfile)

# 重命名或备份模型快照
ollama.copy('llama3.1', 'backup/v1_llama3.1')

# 推送至远程仓库或清理冗余文件
ollama.push('user/my_expert_bot')
ollama.delete('llama3.1')

高级客户端配置与异常处理

默认情况下SDK直连 http://localhost:11434。对于高并发场景或跨节点部署需求，可按需定制连接参数。

自定义TCP连接

传入特定IP地址、端口或自定义Header以适配企业级网关：

from ollama import Client
client = Client(host='http://custom-ollama-server:11434', headers={'x-api-key': 'xxxx'})
response = client.chat(model='llama3.1', messages=[{'role': 'user', 'content': 'Hello'}])
print(response)

异步非阻塞通信

结合 asyncio 提升Web框架吞吐量：

import asyncio
from ollama import AsyncClient

async def fetch():
    res = await AsyncClient().chat(model='llama3.1', messages=[{'role': 'user', 'content': '写首诗'}])
    return res.message.content

result = asyncio.run(fetch())

捕获与修复网络报错

当请求的模型不存在或服务宕机时，会抛出 ResponseError。可通过状态码判断触发降级或自动修复逻辑：

model = 'does-not-exist'
try:
    ollama.chat(model)
except ollama.ResponseError as e:
    print('捕获错误:', e.error)
    if e.status_code == 404:
        ollama.pull(model) # 自动补全缺失模型