> ## Documentation Index
> Fetch the complete documentation index at: https://langchain-docs-zh.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# ChatOllama 集成
> 使用 LangChain Python 集成 ChatOllama 对话模型。
[Ollama](https://ollama.com/) 允许您在本地运行开放权重的大型语言模型（LLMs），例如 `gpt-oss`。
Ollama 将模型权重、配置和数据打包成一个 Modelfile 定义的单一包，优化了设置和配置细节（包括 GPU 使用）。
要查看支持的完整模型及变体列表，请参考 [Ollama 模型库](https://ollama.com/search)。
> [!TIP]
>
> **API Reference**
>
> 所有功能及配置选项的详细文档，请访问 @\[`ChatOllama`] API reference。
## 概述
### 集成细节
| 类别 | 包 | 可序列化 | [JS 支持](https://langchain-docs-zh.mintlify.site/langchain/oss/javascript/integrations/chat/ollama.md) | 下载量 | 版本 |
| :- | :- | :-: | :-: | :-: | :-: |
| @\[`ChatOllama`] | @\[`langchain-ollama`] | ❌ | ✅ |  |  |
### 模型特性
| [工具调用](https://langchain-docs-zh.mintlify.site/langchain/oss/langchain/tools.md) | [结构化输出](https://langchain-docs-zh.mintlify.site/langchain/oss/langchain/structured-output.md) | [图像输入](https://langchain-docs-zh.mintlify.site/langchain/oss/langchain/messages.md#多模态) | 音频输入 | 视频输入 | [Token 级流式输出](https://langchain-docs-zh.mintlify.site/langchain/oss/langchain/streaming.md) | 原生异步 | [Token 使用量](https://langchain-docs-zh.mintlify.site/langchain/oss/langchain/models.md#token-使用) | [对数概率](https://langchain-docs-zh.mintlify.site/langchain/oss/langchain/models.md#对数概率) |
| :-: | :-: | :-: | :-: | :-: | :-: | :-: | :-: | :-: |
| ✅ | ✅ | ✅ | ❌ | ❌ | ✅ | ✅ | ❌ | ✅ |
## 安装
[下载并安装 Ollama](https://ollama.ai/download)，然后按照 [Ollama 安装指南](https://github.com/ollama/ollama?tab=readme-ov-file#ollama) 启动本地实例。
拉取聊天和工具调用示例中使用的模型：
```bash theme={null}
ollama pull gpt-oss:20b
```
使用 `ollama pull` 和 `ChatOllama(model=...)` 中相同的模型标签。以下图像、对数概率和自定义角色示例包含各自模型的单独拉取命令。
* 列出已下载模型：`ollama list`
* 终端聊天：`ollama run gpt-oss:20b`
* 查看可用命令：`ollama help`
可选：通过设置以下环境变量启用 [LangSmith](https://docs.langchain.com/langsmith/observability) 的模型调用追踪：
```python theme={null}
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` 包中：
```bash theme={null}
pip install -qU langchain-ollama
```
## 实例化
实例化在设置过程中下载的模型：
```python theme={null}
from langchain_ollama import ChatOllama
llm = ChatOllama(
model="gpt-oss:20b",
temperature=0,
)
```
## 调用
```python theme={null}
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
```
读取响应内容块：
```python theme={null}
print(ai_msg.content_blocks)
```
## 工具调用
使用支持[工具调用](https://ollama.com/search?\&c=tools)的Ollama模型（例如`gpt-oss:20b`），并配置`bind_tools()`参数。通过@`@tool`装饰器创建工具。更多细节请参考[自定义工具属性](https://langchain-docs-zh.mintlify.site/langchain/oss/langchain/tools.md#自定义工具属性)。
```python theme={null}
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)
```
```text theme={null}
[{'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](https://ollama.com/library/gemma3)），运行前先拉取`4b`版本：
```bash theme={null}
ollama pull gemma3:4b
```
```bash theme={null}
pip install pillow
```
```python theme={null}
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'
'
# 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)
```
```html theme={null}
```
```python theme={null}
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的出现概率。
```bash theme={null}
ollama pull llama3.1
```
### 基础用法
```python theme={null}
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}")
```
```text theme={null}
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：
```python theme={null}
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}")
```
```text theme={null}
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](https://ollama.com/library/granite3.2)）支持通过自定义消息角色实现思考过程。
要启用Granite 3.2的思考功能，需向模型传递具有`"control"`角色且内容为`"thinking"`的消息。由于`"control"`是非标准角色，需通过[ChatMessage](https://reference.langchain.com/python/langchain-core/messages/chat/ChatMessage)对象实现：
```bash theme={null}
ollama pull granite3.2:8b
```
```python theme={null}
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)
```
```text theme={null}
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参考](https://reference.langchain.com/python/langchain-ollama/chat_models/ChatOllama)。
***
> 官方原文：[src/oss/python/integrations/chat/ollama.mdx](https://github.com/langchain-ai/docs/blob/main/src/oss/python/integrations/chat/ollama.mdx) · 非官方翻译，译文由 AI 生成，以英文原文为准。
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.