ChatOllama 集成

使用 LangChain Python 集成 ChatOllama 对话模型。

Ollama 允许您在本地运行开放权重的大型语言模型（LLMs），例如 gpt-oss。

Ollama 将模型权重、配置和数据打包成一个 Modelfile 定义的单一包，优化了设置和配置细节（包括 GPU 使用）。

要查看支持的完整模型及变体列表，请参考 Ollama 模型库。

API Reference

所有功能及配置选项的详细文档，请访问 @[ChatOllama] API reference。

概述

集成细节

类别	包	可序列化	JS 支持	下载量	版本
@[ChatOllama]	@[langchain-ollama]	❌	✅

模型特性

工具调用	结构化输出	图像输入	音频输入	视频输入	Token 级流式输出	原生异步	Token 使用量	对数概率
✅	✅	✅	❌	❌	✅	✅	❌	✅

安装

下载并安装 Ollama，然后按照 Ollama 安装指南 启动本地实例。

拉取聊天和工具调用示例中使用的模型：

ollama pull gpt-oss:20b

使用 ollama pull 和 ChatOllama(model=...) 中相同的模型标签。以下图像、对数概率和自定义角色示例包含各自模型的单独拉取命令。

• 列出已下载模型：ollama list
• 终端聊天：ollama run gpt-oss:20b
• 查看可用命令：ollama help

可选：通过设置以下环境变量启用 LangSmith 的模型调用追踪：

import getpass
import os

os.environ["LANGSMITH_TRACING"] = "true"
os.environ["LANGSMITH_API_KEY"] = getpass.getpass("Enter your LangSmith API key: ")

安装

LangChain Ollama 集成位于 langchain-ollama 包中：

pip install -qU langchain-ollama

实例化

实例化在设置过程中下载的模型：

from langchain_ollama import ChatOllama

llm = ChatOllama(
    model="gpt-oss:20b",
    temperature=0,
)

调用

messages = [
    (
        "system",
        "You are a helpful assistant that translates English to French. Translate the user sentence.",
    ),
    ("human", "I love programming."),
]
ai_msg = llm.invoke(messages)
ai_msg

读取响应内容块：

print(ai_msg.content_blocks)

工具调用

使用支持工具调用的Ollama模型（例如gpt-oss:20b），并配置bind_tools()参数。通过@@tool装饰器创建工具。更多细节请参考自定义工具属性。

from typing import List

from langchain.messages import AIMessage
from langchain.tools import tool
from langchain_ollama import ChatOllama


@tool
def validate_user(user_id: int, addresses: List[str]) -> bool:
    """Validate user using historical addresses.

    Args:
        user_id (int): the user ID.
        addresses (List[str]): Previous addresses as a list of strings.
    """
    return True


llm = ChatOllama(
    model="gpt-oss:20b",
    validate_model_on_init=True,
    temperature=0,
).bind_tools([validate_user])

result = llm.invoke(
    "Could you validate user 123? They previously lived at "
    "123 Fake St in Boston MA and 234 Pretend Boulevard in "
    "Houston TX."
)

if isinstance(result, AIMessage) and result.tool_calls:
    print(result.tool_calls)

[{'name': 'validate_user', 'args': {'addresses': ['123 Fake St, Boston, MA', '234 Pretend Boulevard, Houston, TX'], 'user_id': '123'}, 'id': 'aef33a32-a34b-4b37-b054-e0d85584772f', 'type': 'tool_call'}]

多模态

使用支持图像处理能力的模型（例如Gemma 3），运行前先拉取4b版本：

ollama pull gemma3:4b

pip install pillow

import base64
from io import BytesIO

from IPython.display import HTML, display
from PIL import Image


def convert_to_base64(pil_image):
    """
    Convert PIL images to Base64 encoded strings

    :param pil_image: PIL image
    :return: Re-sized Base64 string
    """

    buffered = BytesIO()
    pil_image.save(buffered, format="JPEG")  # You can change the format if needed
    img_str = base64.b64encode(buffered.getvalue()).decode("utf-8")
    return img_str


def plt_img_base64(img_base64):
    """
    Display base64 encoded string as image

    :param img_base64:  Base64 string
    """
    # Create an HTML img tag with the base64 string as the source
    image_html = f'<img src="data:image/jpeg;base64,{img_base64}" />'
    # Display the image by rendering the HTML
    display(HTML(image_html))


file_path = "../../../static/img/ollama_example_img.jpg"
pil_image = Image.open(file_path)

image_b64 = convert_to_base64(pil_image)
plt_img_base64(image_b64)

<img src="data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJ..." />

from langchain.messages import HumanMessage
from langchain_ollama import ChatOllama

llm = ChatOllama(model="gemma3:4b", temperature=0)


def prompt_func(data):
    text = data["text"]
    image = data["image"]

    image_part = {
        "type": "image_url",
        "image_url": f"data:image/jpeg;base64,{image}",
    }

    content_parts = []

    text_part = {"type": "text", "text": text}

    content_parts.append(image_part)
    content_parts.append(text_part)

    return [HumanMessage(content=content_parts)]


from langchain_core.output_parsers import StrOutputParser

chain = prompt_func | llm | StrOutputParser()

query_chain = chain.invoke(
    {"text": "What is the Dollar-based gross retention rate?", "image": image_b64}
)

print(query_chain)

对数概率

ChatOllama支持通过logprobs和top_logprobs参数获取token级对数概率。对数概率表示每个生成步骤中各token的出现概率。

ollama pull llama3.1

基础用法

from langchain_ollama import ChatOllama

llm = ChatOllama(model="llama3.1", logprobs=True)

response = llm.invoke("What color is the sky?")
logprobs = response.response_metadata["logprobs"]
for entry in logprobs[:5]:
    print(f"Token: {entry['token']!r:>15}  logprob: {entry['logprob']:.4f}")

Token:           'The'  logprob: -0.1094
Token:       ' answer'  logprob: -1.7309
Token:             ','  logprob: -1.5854
Token:           ' of'  logprob: -0.4066
Token:       ' course'  logprob: -0.0000

每个token的Top-K替代方案

使用top_logprobs参数返回每个位置最可能的替代token：

llm = ChatOllama(model="llama3.1", logprobs=True, top_logprobs=3)

response = llm.invoke("The capital of France is")
logprobs = response.response_metadata["logprobs"]
for entry in logprobs[:3]:
    print(f"Chosen: {entry['token']!r}")
    if entry.get("top_logprobs"):
        for alt in entry["top_logprobs"]:
            print(f"    {alt['token']!r:>12}  logprob: {alt['logprob']:.4f}")

Chosen: 'Paris'
         'Paris'  logprob: -0.5567
           'The'  logprob: -0.9152
            '**'  logprob: -4.0410
Chosen: '.'
             '.'  logprob: -0.3831
    '<|eot_id|>'  logprob: -1.5511
             '!'  logprob: -2.3379

理性化模型与自定义消息角色

某些模型（如IBM的Granite 3.2）支持通过自定义消息角色实现思考过程。

要启用Granite 3.2的思考功能，需向模型传递具有"control"角色且内容为"thinking"的消息。由于"control"是非标准角色，需通过ChatMessage对象实现：

ollama pull granite3.2:8b

from langchain.messages import HumanMessage
from langchain_core.messages import ChatMessage
from langchain_ollama import ChatOllama

llm = ChatOllama(model="granite3.2:8b")

messages = [
    ChatMessage(role="control", content="thinking"),
    HumanMessage("What is 3^3?"),
]

response = llm.invoke(messages)
print(response.content)

Here is my thought process:
The user is asking for the value of 3 raised to the power of 3, which is a basic exponentiation operation.

Here is my response:

3^3 (read as "3 to the power of 3") equals 27.

This calculation is performed by multiplying 3 by itself three times: 3*3*3 = 27.

模型会同时返回最终响应和思考过程。

API参考

ChatOllama功能及配置选项的完整文档请查阅API参考。

---

官方原文：src/oss/python/integrations/chat/ollama.mdx · 非官方翻译，译文由 AI 生成，以英文原文为准。