02. 使用 Ollama 调用本地模型

学习目标

完成本章后，你应该能够：

• 说明 Ollama 在本地 LangChain 应用中的作用。
• 使用 ChatOllama 调用本地模型完成最小对话。
• 理解 model、base_url、temperature 这些关键参数。
• 区分“模型能聊天”和“模型能稳定完成工具调用”这两件事。
• 根据错误信息判断 Ollama 未启动或模型未安装。

Ollama 是什么

Ollama 是本地模型运行时。它负责下载、管理、加载和运行模型，并通过本地 HTTP API 暴露模型能力。LangChain 不直接运行模型，而是通过 langchain-ollama 里的 ChatOllama 客户端连接 Ollama。

在本教程中，Ollama 的职责是：

• 在本机运行 qwen3 等模型。
• 提供默认地址 http://localhost:11434。
• 接收 LangChain 发来的聊天消息。
• 返回模型生成的文本或后续章节会用到的工具调用请求。

注意：聊天质量不等于工具调用可靠性。一个模型可以流畅回答普通问题，但在工具选择、参数生成、结构化输出和多步推理上仍然不稳定。后续构建 Agent 时要单独验证工具调用能力。

安装和模型准备

先安装并启动 Ollama。你可以打开 Ollama 应用，或者在终端运行：

ollama serve

下载本教程默认使用的模型：

ollama pull qwen3

确认模型已经存在：

ollama list

项目默认读取 .env 中的配置；如果没有 .env，会使用：

• OLLAMA_BASE_URL=http://localhost:11434
• OLLAMA_MODEL=qwen3

如果你使用其他模型，需要确保 .env 里的 OLLAMA_MODEL 和 ollama list 里看到的模型名称一致。

最小调用

本章示例是一个最小聊天 CLI：

uv run python examples/01_chat_cli.py

程序启动时会先做两项检查：

1. 调用 Ollama 的 /api/tags，确认 Ollama 服务可访问。
2. 检查配置中的模型是否已经安装。

通过检查后，程序会创建 ChatOllama，并把用户输入交给模型：

model = ChatOllama(
    model=config.ollama_model,
    base_url=config.ollama_base_url,
    temperature=0,
)

response = model.invoke(user_input)

model.invoke(...) 是最小调用方式。输入可以是字符串，也可以是后续章节会介绍的 message 列表。返回值通常是一个 AI message，对话文本在 response.content 中。

关键参数

ChatOllama 是 LangChain 对 Ollama 聊天模型接口的封装。它让本地模型可以像其他 LangChain chat model 一样被调用，并能参与 prompt、message、tool 和 agent 组合。

关键参数包括：

• model：要调用的 Ollama 模型名称，例如 qwen3。名称必须和本机已安装模型匹配。
• base_url：Ollama 服务地址，默认通常是 http://localhost:11434。如果 Ollama 在远程机器或容器中运行，需要改成对应地址。
• temperature：控制输出随机性。教程示例使用 0，便于复现实验结果。值越高，回答越发散，但不代表更准确。

学习阶段建议先固定 temperature=0。当基础链路稳定后，再尝试调整模型、提示词和采样参数。

常见错误

排查重点

Ollama 不可用：

• 现象：程序提示无法连接 Ollama，或访问 /api/tags 失败。
• 原因：Ollama 应用未打开、ollama serve 未运行、端口不是 11434，或者 OLLAMA_BASE_URL 配错。
• 处理：启动 Ollama，并确认浏览器或命令行能访问配置中的 base URL。

模型不存在：

• 现象：程序提示模型未安装。
• 原因：OLLAMA_MODEL 指向的模型不在 ollama list 结果中。
• 处理：运行 ollama pull qwen3，或把配置改成已经安装的模型名称。

回答质量不稳定：

• 现象：普通聊天能回答，但 Agent 工具调用时参数错误、漏调工具或胡乱总结工具结果。
• 原因：聊天能力和工具调用能力不是同一个指标。
• 处理：先用本章确认模型调用链路，再在工具章节单独验证工具 schema、工具描述和模型的 tool-calling 表现。

代码阅读重点

阅读 examples/01_chat_cli.py 时，重点看四处：

1. load_config()：所有模型配置都从 .env 或默认值读取，不写死在业务代码里。
2. assert_ollama_running()：先检查服务是否可达，避免后面出现难懂的连接错误。
3. assert_model_available()：先检查模型是否安装，避免第一次调用模型时才失败。
4. model.invoke(user_input)：这是最小模型调用。此时还没有 PromptTemplate、Tool 或 Agent loop。

这个脚本故意保持简单。它的目标不是做一个完整聊天应用，而是确认“Python -> LangChain -> Ollama -> 本地模型”这条链路是通的。

实验练习

• 把 .env 中的 OLLAMA_MODEL 改成你本机已有的其他模型，观察回答风格差异。
• 把 temperature=0 改成 temperature=0.7，连续问同一个问题，观察稳定性变化。
• 停掉 Ollama 后运行脚本，确认错误提示是否能帮你定位问题。
• 输入很短的问题和很长的问题，观察本地模型延迟差异。

自测问题

• LangChain 是否负责下载和运行模型？
• ChatOllama 的 base_url 指向哪里？
• 为什么教程默认使用较低 temperature？
• 为什么能正常聊天不代表能稳定做工具调用？

完整示例

下面的源码是本章可直接运行的聊天 CLI：

from __future__ import annotations

import sys
from pathlib import Path

sys.path.append(str(Path(__file__).resolve().parents[1]))

from langchain_ollama import ChatOllama

from examples.common.config import load_config, ollama_client_kwargs
from examples.common.ollama_check import assert_model_available, assert_ollama_running


def main() -> None:
    config = load_config()
    try:
        assert_ollama_running(config.ollama_base_url)
        assert_model_available(config.ollama_base_url, config.ollama_model)
    except RuntimeError as exc:
        print(f"错误：{exc}")
        return

    model = ChatOllama(
        model=config.ollama_model,
        base_url=config.ollama_base_url,
        client_kwargs=ollama_client_kwargs(),
        temperature=0,
    )

    print("LangChain + Ollama 聊天示例。输入 `exit` 退出。")
    while True:
        user_input = input("\n你：").strip()
        if user_input.lower() in {"exit", "quit"}:
            break
        if not user_input:
            continue

        response = model.invoke(user_input)
        print(f"AI：{response.content}")


if __name__ == "__main__":
    main()