Ollama Python库完整配置与使用指南
【免费下载链接】ollama-python 
项目地址: https://gitcode.com/GitHub_Trending/ol/ollama-python
Ollama Python库是官方提供的Python客户端，为开发者提供了与Ollama AI平台集成的便捷接口。本指南将详细介绍该库的安装配置、核心功能和使用方法。
项目概述
Ollama Python库基于Python 3.8+开发，采用现代异步编程架构，支持与本地和云端Ollama实例的无缝通信。该库简化了AI模型的管理和使用流程，让开发者能够专注于业务逻辑而非底层技术细节。
技术栈与依赖
项目采用以下核心技术：
- Python 3.8+：现代Python版本支持
- httpx >=0.27：高性能HTTP客户端
- pydantic >=2.9：数据验证和序列化
- 异步编程：支持并发处理和高性能操作
环境准备
在开始安装之前，请确保系统满足以下要求：
- Python 3.8或更高版本
- pip包管理工具
- 已安装并运行的Ollama服务
验证环境
打开终端，检查Python和pip版本：
python --version
pip --version
安装步骤
方式一：使用pip安装
通过pip直接安装最新版本：
pip install ollama
方式二：从源码安装
如需使用最新功能或进行定制开发，可以从源码安装：
git clone https://gitcode.com/GitHub_Trending/ol/ollama-python
cd ollama-python
pip install .
基础配置
验证安装
创建一个简单的测试脚本来验证安装是否成功：
import ollama
# 基础聊天功能测试
response = ollama.chat(model='gemma3', messages=[
{'role': 'user', 'content': 'Hello, Ollama!'}
])
print("安装成功！AI响应：", response['message']['content'])
自定义客户端配置
如需更精细的控制，可以创建自定义客户端：
from ollama import Client
# 个性化配置选项
custom_client = Client(
host='http://localhost:11434',
timeout=30,
headers={'x-custom-header': 'custom-value'}
)
# 使用自定义客户端
response = custom_client.chat(model='gemma3', messages=[
{'role': 'user', 'content': 'Why is the sky blue?'}
])
核心功能详解
聊天功能
基础聊天功能是Ollama Python库的核心特性：
from ollama import chat
from ollama import ChatResponse
response: ChatResponse = chat(model='gemma3', messages=[
{
'role': 'user',
'content': 'Why is the sky blue?',
},
])
print(response['message']['content'])
# 或者直接访问响应对象的字段
print(response.message.content)
流式响应
启用流式响应可以实时接收AI模型的输出：
from ollama import chat
stream = chat(
model='gemma3',
messages=[{'role': 'user', 'content': 'Why is the sky blue?'}],
stream=True,
)
for chunk in stream:
print(chunk['message']['content'], end='', flush=True)
异步客户端
对于高性能应用，可以使用异步客户端：
import asyncio
from ollama import AsyncClient
async def chat():
message = {'role': 'user', 'content': 'Why is the sky blue?'}
response = await AsyncClient().chat(model='gemma3', messages=[message])
print(response.message.content)
asyncio.run(chat())
异步流式响应：
import asyncio
from ollama import AsyncClient
async def chat():
message = {'role': 'user', 'content': 'Why is the sky blue?'}
async for part in await AsyncClient().chat(model='gemma3', messages=[message], stream=True):
print(part['message']['content'], end='', flush=True)
asyncio.run(chat())
高级功能
文本生成
使用generate函数进行文本生成：
response = ollama.generate(model='gemma3', prompt='Why is the sky blue?')
print(response.response)
向量嵌入
支持文本向量嵌入功能：
# 单文本嵌入
response = ollama.embed(model='gemma3', input='The sky is blue because of rayleigh scattering')
# 批量文本嵌入
response = ollama.embed(model='gemma3', input=[
'The sky is blue because of rayleigh scattering',
'Grass is green because of chlorophyll'
])
模型管理
Ollama Python库提供了完整的模型管理功能：
# 列出可用模型
models = ollama.list()
print(models.models)
# 显示模型详细信息
model_info = ollama.show('gemma3')
print(model_info)
# 拉取模型
ollama.pull('gemma3')
# 创建自定义模型
ollama.create(model='example', from_='gemma3', system="You are Mario from Super Mario Bros.")
# 删除模型
ollama.delete('gemma3')
错误处理
合理的错误处理机制确保应用的稳定性：
model = 'does-not-yet-exist'
try:
ollama.chat(model)
except ollama.ResponseError as e:
print('Error:', e.error)
if e.status_code == 404:
ollama.pull(model)
性能优化建议
- 合理设置超时时间：根据网络状况调整timeout参数
- 启用请求重试：在网络不稳定的环境中特别有用
- 使用流式响应：对于长文本生成可以提升用户体验
- 异步处理：在高并发场景下使用异步客户端
示例项目
项目中提供了丰富的使用示例，位于examples目录下：
- examples/chat.py：基础聊天示例
- examples/chat-stream.py：流式聊天示例
- examples/async-chat.py：异步聊天示例
- examples/generate.py：文本生成示例
- examples/embed.py：向量嵌入示例
这些示例涵盖了从基础到高级的各种使用场景，是学习Ollama Python库的最佳参考资料。
通过本指南，您应该能够顺利完成Ollama Python库的安装配置，并开始构建基于AI的Python应用。随着对库功能的深入理解，您可以根据具体需求选择最适合的功能组合。
【免费下载链接】ollama-python 项目地址: https://gitcode.com/GitHub_Trending/ol/ollama-python
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
