【LangChain】langchain_ollama.ChatOllama 类：调用 Ollama 本地对话模型

langchain_ollama.ChatOllama 类是 LangChain 中用于与 Ollama 本地对话模型交互的类，继承自 langchain_core.language_models.chat_models.BaseChatModel。

本文基于 LangChain 0.3.x，详细介绍 ChatOllama 的定义、初始化、常用方法和属性，并提供一个独立示例，展示如何使用 ChatOllama 调用 llama3 模型处理人工智能主题的对话，示例结合 ChatPromptTemplate 和 invoke 方法。

---

langchain_ollama.ChatOllama 简介

langchain_ollama.ChatOllama 是 LangChain 中用于调用 Ollama 本地对话模型的类，通过与 Ollama 服务（通常运行在 http://localhost:11434）交互，生成对话响应。它继承自 BaseChatModel，支持结构化的消息输入（如 SystemMessage、HumanMessage），适合本地化对话、问答和多轮交互场景。

核心功能：

• 调用 Ollama 本地对话模型，生成对话响应。
• 支持同步（invoke、generate）、异步（ainvoke、agenerate）和流式（stream、astream）生成。
• 处理结构化消息，支持系统提示、用户输入和对话历史。
• 配置 Ollama 特定的参数（如 temperature、num_predict）。
• 集成到 LCEL 链，适合本地 RAG、对话系统或测试。

适用场景：

• 在本地运行对话模型，节省云服务成本。
• 构建隐私敏感的对话或问答系统。
• 测试和开发 LLM 应用，利用本地硬件。
• 集成到本地向量存储或 RAG 工作流。

与 langchain_openai.ChatOpenAI 对比：

• ChatOpenAI：用于 OpenAI 云端对话模型，依赖 API 密钥和网络。
• ChatOllama：用于 Ollama 本地对话模型，无需云服务，依赖本地硬件。

---

类定义和初始化

以下是 langchain_ollama.ChatOllama 的定义，基于 LangChain 源码（langchain_ollama/chat_models.py）和官方文档（ChatOllama)。

类签名

class ChatOllama(BaseChatModel):
    def __init__(
        self,
        *,
        model: str = "llama3",
        base_url: str = "http://localhost:11434",
        temperature: Optional[float] = None,
        top_k: Optional[int] = None,
        top_p: Optional[float] = None,
        num_ctx: Optional[int] = None,
        num_predict: Optional[int] = None,
        num_gpu: Optional[int] = None,
        num_thread: Optional[int] = None,
        repeat_last_n: Optional[int] = None,
        repeat_penalty: Optional[float] = None,
        seed: Optional[int] = None,
        tfs_z: Optional[float] = None,
        mirostat: Optional[int] = None,
        mirostat_eta: Optional[float] = None,
        mirostat_tau: Optional[float] = None,
        stop: Optional[List[str]] = None,
        keep_alive: Optional[Union[int, str]] = None,
        format: Optional[str] = None,
        **kwargs: Any
    ) -> None

• 关键参数：
  • model（str，默认 "llama3"）：Ollama 模型名称（如 llama3、mistral）。
  • base_url（str，默认 "http://localhost:11434"）：Ollama 服务地址。
  • temperature（Optional[float]，默认 None）：控制生成随机性（0~2）。
  • top_k（Optional[int]，默认 None）：Top-k 采样参数。
  • top_p（Optional[float]，默认 None）：核采样概率。
  • num_ctx（Optional[int]，默认 None）：上下文窗口大小。
  • num_predict（Optional[int]，默认 None）：最大输出 token 数。
  • num_gpu（Optional[int]，默认 None）：使用的 GPU 数量。
  • num_thread（Optional[int]，默认 None）：使用的线程数。
  • repeat_penalty（Optional[float]，默认 None）：惩罚重复内容。
  • seed（Optional[int]，默认 None）：随机种子。
  • stop（Optional[List[str]]，默认 None）：停止词列表。
  • keep_alive（Optional[Union[int, str]]，默认 None）：模型在内存中的保持时间（秒或字符串，如 "5m"）。
  • format（Optional[str]，默认 None）：输出格式（"json" 或 None）。

初始化示例

from langchain_ollama import ChatOllama
llm = ChatOllama(
    model="llama3",
    base_url="http://localhost:11434",
    temperature=0.7,
    num_predict=512
)

支持的模型（需通过 Ollama 拉取）：

• llama3（默认，8B 参数）
• llama3.1（8B、70B 等）
• mistral
• phi3
• 更多见 Ollama 模型库.

---

常用方法

ChatOllama 继承自 BaseChatModel，支持对话模型的特定接口。以下是常用方法，基于使用频率和 ChatOllama 特性。

1. invoke

def invoke(self, input: LanguageModelInput, config: Optional[RunnableConfig] = None, *, stop: Optional[List[str]] = None, **kwargs: Any) -> AIMessage

• 功能：同步调用，处理消息列表，返回 AIMessage。
• 输入：LanguageModelInput（通常是 List[BaseMessage]，如 [SystemMessage, HumanMessage]）。
• 使用场景：单次对话、问答。
• 示例：

  from langchain_core.messages import HumanMessage
  response = llm.invoke([HumanMessage(content="什么是人工智能？")])
  print(response.content)
  

2. generate

def generate(self, messages: List[List[BaseMessage]], stop: Optional[List[str]] = None, callbacks: Optional[Callbacks] = None, **kwargs: Any) -> LLMResult

• 功能：同步批量生成，返回 LLMResult。
• 输入：List[List[BaseMessage]]，每个子列表是一组对话消息。
• 使用场景：批量对话。
• 示例：

  messages = [
      [HumanMessage(content="什么是人工智能？")],
      [HumanMessage(content="AI 有哪些应用？")]
  ]
  result = llm.generate(messages)
  for generations in result.generations:
      print(generations[0].text)
  

3. stream

def stream(self, input: LanguageModelInput, config: Optional[RunnableConfig] = None, *, stop: Optional[List[str]] = None, **kwargs: Any) -> Iterator[AIMessageChunk]

• 功能：同步流式生成，逐块返回 AIMessageChunk。
• 使用场景：实时聊天界面。
• 示例：

  for chunk in llm.stream([HumanMessage(content="人工智能有哪些应用？")]):
      print(chunk.content, end="", flush=True)
  

4. ainvoke

async def ainvoke(self, input: LanguageModelInput, config: Optional[RunnableConfig] = None, *, stop: Optional[List[str]] = None, **kwargs: Any) -> AIMessage

• 功能：异步单次生成。
• 使用场景：高并发 Web 服务。
• 示例：

  import asyncio
  async def run():
      response = await llm.ainvoke([HumanMessage(content="什么是人工智能？")])
      print(response.content)
  asyncio.run(run())
  

5. agenerate

async def agenerate(self, messages: List[List[BaseMessage]], stop: Optional[List[str]] = None, callbacks: Optional[Callbacks] = None, **kwargs: Any) -> LLMResult

• 功能：异步批量生成。
• 使用场景：异步批量对话。
• 示例：

  async def run():
      result = await llm.agenerate(messages)
      for generations in result.generations:
          print(generations[0].text)
  asyncio.run(run())
  

6. astream

async def astream(self, input: LanguageModelInput, config: Optional[RunnableConfig] = None, *, stop: Optional[List[str]] = None, **kwargs: Any) -> AsyncIterator[AIMessageChunk]

• 功能：异步流式生成。
• 使用场景：WebSocket 聊天。
• 示例：

  async def run():
      async for chunk in llm.astream([HumanMessage(content="人工智能有哪些应用？")]):
          print(chunk.content, end="", flush=True)
  asyncio.run(run())
  

ChatOllama 特有特性：

• 支持 JSON 格式输出：

  llm = ChatOllama(model="llama3", format="json")
  

• 支持多模态（视觉模型，如 llava）：

  llm = ChatOllama(model="llava")
  

---

常用属性

以下是 ChatOllama 类的常用属性，基于源码和文档。

1. model

• 类型：str
• 功能：指定 Ollama 模型名称。
• 示例：

  print(llm.model)  # llama3
  

2. temperature

• 类型：Optional[float]
• 功能：控制生成随机性。
• 示例：

  llm.temperature = 0.5
  

3. num_predict

• 类型：Optional[int]
• 功能：最大输出 token 数。
• 示例：

  llm.num_predict = 1024
  

4. base_url

• 类型：str
• 功能：Ollama 服务地址。
• 示例：

  llm.base_url = "http://your-ollama-server:11434"
  

5. cache

• 类型：Optional[BaseCache]
• 功能：缓存生成结果。
• 示例：

  from langchain_core.caches import InMemoryCache
  llm.cache = InMemoryCache()
  

6. callbacks

• 类型：Optional[Callbacks]
• 功能：默认回调函数。
• 示例：

  from langchain_core.callbacks import StdOutCallbackHandler
  llm.callbacks = [StdOutCallbackHandler()]
  

---

使用 langchain_ollama.ChatOllama 的对话示例

以下是一个独立示例，展示如何使用 langchain_ollama.ChatOllama 调用 llama3 模型处理人工智能主题的对话，结合 ChatPromptTemplate 和 invoke 方法，启用缓存和回调，支持系统消息和用户问题。

准备环境：

• 安装 Ollama：

  curl -fsSL https://ollama.com/install.sh | sh
  

• 启动 Ollama 服务：

  ollama serve
  

• 拉取 llama3 模型：

  ollama pull llama3
  

• 安装依赖：

  pip install --upgrade langchain langchain-ollama
  

代码：

from langchain_ollama import ChatOllama
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser
from langchain_core.runnables import RunnablePassthrough
from langchain_core.caches import InMemoryCache
from langchain_core.callbacks import StdOutCallbackHandler

# 初始化 ChatOllama
llm = ChatOllama(
    model="llama3",
    base_url="http://localhost:11434",
    temperature=0.7,
    num_predict=512,
    cache=InMemoryCache(),  # 启用缓存
    callbacks=[StdOutCallbackHandler()]  # 默认回调
)

# 定义 ChatPromptTemplate
prompt = ChatPromptTemplate.from_messages([
    ("system", "你是一个人工智能专家，回答以下问题。"),
    ("human", "{question}")
])

# 创建问答链
qa_chain = (
    {"question": RunnablePassthrough()}
    | prompt
    | llm
    | StrOutputParser()
)

# 使用 invoke 方法
print("invoke 方法：")
question = "什么是人工智能？"
try:
    response = llm.invoke(
        prompt.format_prompt(question=question).to_messages(),
        config={
            "tags": ["ai_question"]
        }
    )
    print(f"问题: {question}")
    print(f"回答: {response.content}")
except Exception as e:
    print(f"错误: {e}")

# 使用链调用 invoke
print("\n链式 invoke：")
response = qa_chain.invoke(question)
print(f"问题: {question}")
print(f"回答: {response}")

# 查看属性
print("\n模型属性：")
print(f"模型: {llm.model}")
print(f"温度: {llm.temperature}")
print(f"缓存状态: {llm.cache is not None}")

输出示例（实际输出取决于模型和硬件）：

invoke 方法：
[StdOutCallbackHandler] 开始生成...
[StdOutCallbackHandler] 生成结束
问题: 什么是人工智能？
回答: 人工智能（AI）是计算机科学的一个分支，致力于创建能够模拟人类智能的系统，如学习、推理和问题解决。

链式 invoke：
问题: 什么是人工智能？
回答: 人工智能（AI）是计算机科学的一个分支，致力于创建能够模拟人类智能的系统，如学习、推理和问题解决。

模型属性：
模型: llama3
温度: 0.7
缓存状态: True

代码说明

1. LLM 初始化：
   • 使用 ChatOllama 调用 llama3，配置 temperature=0.7、num_predict=512。
   • 启用 InMemoryCache 和 StdOutCallbackHandler。
2. 提示模板：
   • ChatPromptTemplate 定义系统消息和用户问题。
3. 问答链：
   • LCEL 链组合 prompt、llm 和 StrOutputParser，简化调用。
4. invoke 使用：
   • 直接调用 llm.invoke，使用格式化的消息列表。
   • 通过 qa_chain.invoke 调用链，展示集成方式。
5. 属性展示：
   • 打印 model、temperature 和 cache 状态。
6. 错误处理：
   • 使用 try-except 捕获服务错误。

运行要求：

• Ollama 服务运行且 llama3 模型已拉取：

  ollama serve
  ollama pull llama3
  

• 安装依赖：

  pip install --upgrade langchain langchain-ollama
  

• 硬件支持：llama3:8b 需 8GB+ RAM，GPU 可加速。

---

注意事项

1. Ollama 服务：
   • 验证服务：

     curl http://localhost:11434
     

   • 确保模型已拉取：

     ollama list
     

   • 远程服务：

     llm = ChatOllama(base_url="http://your-ollama-server:11434")
     

2. 模型选择：
   • 确认模型支持对话（如 llama3、mistral）：

     print(llm.model)
     

   • 拉取模型：

     ollama pull llama3
     

3. 消息格式：
   • 使用 SystemMessage 和 HumanMessage：

     from langchain_core.messages import SystemMessage, HumanMessage
     messages = [SystemMessage(content="系统提示"), HumanMessage(content="用户问题")]
     

   • 或使用 ChatPromptTemplate：

     prompt = ChatPromptTemplate.from_messages([("system", "提示"), ("human", "{question}")])
     

4. 参数配置：
   • num_predict：控制输出长度：

     llm.num_predict = 1024
     

   • stop：控制终止：

     response = llm.invoke(messages, stop=["\n"])
     

   • 回调：使用 StdOutCallbackHandler：

     response = llm.invoke(messages, config={"callbacks": [StdOutCallbackHandler()]})
     

5. 性能优化：
   • 缓存：启用 InMemoryCache：

     llm.cache = InMemoryCache()
     

   • GPU 加速：Ollama 支持 NVIDIA GPU：

     nvidia-smi
     

     llm = ChatOllama(num_gpu=1)
     

   • 线程优化：

     llm = ChatOllama(num_thread=4)
     

6. 错误调试：
   • 服务不可用：
     • 检查服务：

       ollama serve
       

     • 验证 base_url：

       import requests
       requests.get("http://localhost:11434")
       

   • 模型未找到：
     • 确认模型：

       ollama list
       

     • 拉取模型：

       ollama pull llama3
       

   • 输出为空：
     • 检查消息：

       print(messages)
       

     • 增加 num_predict：

       llm.num_predict = 1024
       

---

常见问题

Q1：如何选择 ChatOllama 和 ChatOpenAI？
A：

• ChatOllama：本地运行，适合隐私敏感或无网络环境。
• ChatOpenAI：云端运行，性能更强但需 API 密钥。

from langchain_openai import ChatOpenAI
llm = ChatOpenAI(model="gpt-3.5-turbo")

Q2：如何启用流式生成？
A：使用 stream 或 astream：

for chunk in llm.stream(messages):
    print(chunk.content, end="")
# 异步
async for chunk in llm.astream(messages):
    print(chunk.content, end="")

Q3：如何支持多模态？
A：使用视觉模型（如 llava）：

llm = ChatOllama(model="llava")

Q4：如何在 FastAPI 中使用？
A：异步调用 ainvoke 或 astream：

from fastapi import FastAPI
from langchain_core.messages import HumanMessage
app = FastAPI()
@app.post("/chat")
async def chat(prompt: str):
    response = await llm.ainvoke([HumanMessage(content=prompt)])
    return {"result": response.content}

---

总结

langchain_ollama.ChatOllama 是 LangChain 中调用 Ollama 本地对话模型的核心类，核心功能包括：

• 定义：继承 BaseChatModel，支持 Ollama 本地对话。
• 初始化：配置 model、base_url、temperature 等。
• 常用方法：invoke（单次）、generate（批量）、stream（流式）等。
• 常用属性：model、temperature、num_predict 等。