1. 环境准备与基础配置

第一次接触Ollama时，我花了大半天时间才把环境搭好。现在回想起来，其实只需要三个简单步骤就能搞定。首先确保你的Python版本在3.8以上，这个可以用python --version快速检查。如果版本太低，建议直接安装最新版的Python，避免后续兼容性问题。

安装Ollama库时有个小技巧：使用清华镜像源速度会快很多。我实测过，默认源下载速度只有200KB/s，换成镜像源后直接飙升到8MB/s。具体命令是这样：

pip install ollama -i https://pypi.tuna.tsinghua.edu.cn/simple

安装完成后别急着写代码，先用命令行测试下基础功能是否正常：

ollama list

如果看到类似这样的输出，说明环境配置成功了：

NAME            ID              SIZE    MODIFIED
llama3:latest   71bdccf8ca4b    4.7GB   2 days ago

这里有个容易踩的坑：很多新手会忘记启动Ollama服务。我在团队内部分享时，至少有3个同事卡在这个环节。解决方法很简单，新开一个终端窗口运行：

ollama serve

保持这个窗口运行，API调用才能正常工作。建议把这个命令加到系统启动项里，避免每次手动启动。

2. 基础API调用实战

2.1 实现第一个对话程序

先来看最简单的对话实现。下面这段代码是我在项目中实际使用的精简版，去掉了不必要的参数，保留了核心逻辑：

from ollama import chat

response = chat(
    model='llama3',
    messages=[{
        'role': 'user',
        'content': '用一句话解释量子计算'
    }]
)
print(response['message']['content'])

运行后会得到类似这样的输出：

量子计算利用量子比特的叠加态和纠缠态实现并行计算，相比经典计算机在某些问题上具有指数级优势。

这里有几个实用技巧：

1. model参数要填本地已有的模型名，可以通过ollama list查询
2. messages是个列表，可以包含多轮对话历史
3. 实际项目中建议用f-string动态构造提问内容

2.2 流式响应处理

当处理长文本生成时，流式响应能显著提升用户体验。我做过对比测试，生成500字的文章，普通方式需要等待8秒才看到结果，而流式响应几乎是实时输出的。下面是优化后的代码：

from ollama import chat

stream = chat(
    model='llama3',
    messages=[{
        'role': 'user', 
        'content': '写一篇300字左右的科普文章，主题是黑洞'
    }],
    stream=True
)

for chunk in stream:
    content = chunk['message']['content']
    print(content, end='', flush=True)

关键点在于stream=True参数和flush=True的配合使用。我在实际项目中发现，不加flush=True时，控制台输出会有明显卡顿。此外，流式响应特别适合用在Web应用中，配合SSE(Server-Sent Events)技术可以实现类似ChatGPT的逐字输出效果。

2.3 结构化输出技巧

让AI返回结构化数据是实际项目中的常见需求。比如做智能客服时需要固定格式的工单信息，或者数据分析时需要标准化的报表数据。下面这个案例演示如何获取JSON格式的地理信息：

from ollama import chat
import json

response = chat(
    model='llama3',
    messages=[{
        'role': 'user',
        'content': '以JSON格式返回北京市的人口、面积和地标建筑，字段名为population、area和landmarks'
    }],
    format='json'
)

data = json.loads(response['message']['content'])
print(f"人口: {data['population']}")
print(f"面积: {data['area']}")
print(f"地标: {', '.join(data['landmarks'])}")

输出结果类似：

人口: 2171万
面积: 16410平方公里
地标: 故宫, 天安门, 长城, 颐和园

这里特别要注意format='json'参数，它能确保输出是标准JSON格式。我在早期项目中没加这个参数时，经常遇到AI返回非标准JSON的情况，导致解析失败。另一个技巧是在prompt中明确指定字段名，这样能大幅提高输出格式的准确性。

3. 高级模型管理

3.1 模型全生命周期操作

管理本地模型是Ollama的特色功能，我整理了实际项目中最常用的几个操作：

拉取模型（相当于下载）：

from ollama import pull

pull('llama3')

这个操作会显示实时进度条，类似docker pull。建议在后台任务中执行，因为大模型下载可能需要较长时间。

创建自定义模型：

from ollama import create

modelfile = '''
FROM llama3
SYSTEM 你是一位资深Python工程师，回答要专业且简洁
'''

create('my_python_expert', modelfile)

我常用这个功能创建领域专家模型，比如法律顾问、医疗助手等。SYSTEM指令可以定义模型的行为特征。

删除模型释放空间：

from ollama import delete

delete('old_model')

当磁盘空间不足时，这个命令非常有用。不过删除前建议先备份重要模型。

3.2 模型信息查询

在开发模型管理界面时，这些查询接口特别实用：

from ollama import list, show

# 列出所有本地模型
models = list()
print(f"本地模型数: {len(models)}")

# 查看模型详情
details = show('llama3')
print(f"模型大小: {details['size']/1024/1024:.2f}MB")

输出示例：

本地模型数: 5
模型大小: 4837.52MB

3.3 批量操作技巧

当需要处理多个模型时，可以结合Python的多线程提升效率：

from concurrent.futures import ThreadPoolExecutor
from ollama import pull

models = ['llama3', 'mistral', 'gemma']

def download_model(model):
    pull(model)

with ThreadPoolExecutor(max_workers=3) as executor:
    executor.map(download_model, models)

这个技巧在我部署多模型服务时节省了大量时间。注意max_workers不要设置过大，否则可能导致网络拥堵。

4. 性能优化实战

4.1 同步 vs 异步客户端

在处理高并发请求时，异步客户端的优势非常明显。下面是我做过的性能对比测试结果：

请求类型	100次请求总耗时	平均单次耗时
同步	42.7秒	427ms
异步	6.3秒	63ms

异步客户端实现代码：

import asyncio
from ollama import AsyncClient

async def query_async():
    client = AsyncClient()
    tasks = []
    for _ in range(100):
        task = client.chat(
            model='llama3',
            messages=[{'role':'user', 'content':'2+2等于几'}]
        )
        tasks.append(task)
    return await asyncio.gather(*tasks)

asyncio.run(query_async())

关键点：

1. 使用AsyncClient替代普通Client
2. 通过asyncio.gather批量执行任务
3. 注意要在异步环境中运行（如Jupyter需要nest_asyncio）

4.2 缓存机制实现

频繁查询相同内容时，添加缓存能大幅降低延迟。这是我的实现方案：

from functools import lru_cache
from ollama import chat

@lru_cache(maxsize=100)
def cached_chat(prompt):
    return chat(
        model='llama3',
        messages=[{'role':'user', 'content':prompt}]
    )

# 第一次调用会实际请求AI
response1 = cached_chat('Python的GIL是什么')
# 第二次相同提问直接返回缓存
response2 = cached_chat('Python的GIL是什么')

lru_cache是Python内置的缓存装饰器，maxsize参数控制缓存数量。实测命中缓存时，响应时间可以从500ms降到5ms以内。

4.3 超时与重试机制

网络不稳定时，合理的重试策略能提高系统健壮性：

from tenacity import retry, stop_after_attempt, wait_exponential
from ollama import chat

@retry(
    stop=stop_after_attempt(3),
    wait=wait_exponential(multiplier=1, min=4, max=10)
)
def robust_chat(prompt):
    try:
        return chat(
            model='llama3',
            messages=[{'role':'user', 'content':prompt}],
            timeout=30
        )
    except Exception as e:
        print(f"请求失败: {e}")
        raise

response = robust_chat('解释TCP三次握手')

这个方案使用了tenacity库，实现了：

• 最多重试3次
• 指数退避等待（4-10秒）
• 30秒超时设置

在生产环境中，这类异常处理能有效应对网络波动问题。