Ollama Python 教程：使用 ollama 包与 OpenAI SDK

安装

pip install ollama

请先确认 Ollama 服务正在运行，并已下载要使用的模型（例如 ollama pull qwen3:8b）。

基本对话

from ollama import chat

response = chat(
    model="qwen3:8b",
    messages=[
        {"role": "system", "content": "请用简体中文回答。"},
        {"role": "user", "content": "用三点说明什么是机器学习。"},
    ],
)

print(response.message.content)

也可以像读取字典一样读取响应对象：response["message"]["content"]。

流式输出

让文本在生成时逐步显示：

from ollama import chat

stream = chat(
    model="qwen3:8b",
    messages=[{"role": "user", "content": "写一段 100 字的自我介绍示例"}],
    stream=True,
)

for chunk in stream:
    print(chunk.message.content, end="", flush=True)
print()

多轮对话：创建一个终端聊天程序

模型不会自动记住历史记录，你需要将每一轮消息都保存在列表中：

from ollama import chat

messages = [{"role": "system", "content": "你是一位亲切的助手，请用简体中文回答。"}]

while True:
    user_input = input("你：").strip()
    if user_input in {"exit", "quit", "退出"}:
        break
    messages.append({"role": "user", "content": user_input})

    reply = ""
    print("AI：", end="", flush=True)
    for chunk in chat(model="qwen3:8b", messages=messages, stream=True):
        piece = chunk.message.content
        reply += piece
        print(piece, end="", flush=True)
    print()

    messages.append({"role": "assistant", "content": reply})

对话越长，发送的内容越多，最后可能超过上下文长度。实际使用时，可以只保留最近几轮，或将较早的对话总结起来。

参数与思考模式

response = chat(
    model="qwen3:8b",
    messages=[{"role": "user", "content": "1 到 100 的总和是多少？"}],
    options={"temperature": 0.2, "num_ctx": 8192},
    think=True,
    keep_alive="30m",
)

print("思考：", response.message.thinking)
print("回答：", response.message.content)

读取图片

response = chat(
    model="gemma3",
    messages=[{
        "role": "user",
        "content": "这张图片里有什么？",
        "images": ["./photo.jpg"],   # 也可以传入 bytes 或 base64 字符串
    }],
)
print(response.message.content)

其他功能

import ollama

ollama.generate(model="qwen3:8b", prompt="用一句话介绍台北")  # 单次生成
ollama.list()                                               # 已下载的模型
ollama.ps()                                                 # 已加载的模型
ollama.pull("nomic-embed-text")                             # 下载模型
ollama.show("qwen3:8b")                                     # 模型信息
ollama.embed(model="nomic-embed-text", input="你好")         # 文本嵌入

连接到其他主机

from ollama import Client

client = Client(host="http://192.168.1.50:11434")
response = client.chat(model="qwen3:8b", messages=[{"role": "user", "content": "你好"}])
print(response.message.content)

也可以设置环境变量 OLLAMA_HOST，默认的 chat() 函数就会使用它。

异步调用

在 FastAPI 等异步框架中使用：

import asyncio
from ollama import AsyncClient


async def main():
    client = AsyncClient()
    response = await client.chat(
        model="qwen3:8b",
        messages=[{"role": "user", "content": "你好"}],
    )
    print(response.message.content)


asyncio.run(main())

错误处理

import ollama

try:
    ollama.chat(model="not-exist", messages=[{"role": "user", "content": "hi"}])
except ollama.ResponseError as e:
    print("错误：", e.error, e.status_code)
    if e.status_code == 404:
        print("模型不存在，请先 ollama pull")
except ConnectionError:
    print("无法连接到 Ollama，请确认服务正在运行")

改用 OpenAI Python SDK

如果你的程序原本使用 OpenAI SDK，只需修改 base_url：

pip install openai

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1/",
    api_key="ollama",  # 必须填写，但 Ollama 不会检查
)

completion = client.chat.completions.create(
    model="qwen3:8b",
    messages=[{"role": "user", "content": "你好，请自我介绍"}],
)
print(completion.choices[0].message.content)

这样，同一份程序就可以在本地模型和云端 API 之间切换，LangChain、LlamaIndex 等框架也可以用同样的方式接入 Ollama。

下一节介绍 JavaScript / Node.js 的用法。

更新于 2026年10月12日