LangChain 入门学习第一篇-环境准备和模型调用

最近准备系统练习一下 LangChain 的使用，所以先在 code/langchain-demo 目录下搭了一个最小 demo。

这一篇先不急着讲 Agent、RAG、Memory 这些概念，第一步只做一件事情：把 Python 环境准备好，然后通过 LangChain 调用一次 OpenAI 兼容接口。

本文对应代码位于 code/langchain-demo/chapter01。后面的第二篇、第三篇会继续使用 chapter02、chapter03 这种目录结构，避免后续代码改动影响前面文章的示例。

只要这个链路跑通了，后面继续做 Prompt、结构化输出、工具调用和 RAG，才算有了一个稳定的起点。

准备 Python 环境

项目使用 uv 来管理 Python 虚拟环境和依赖。

在 code/langchain-demo 目录下创建虚拟环境：

uv venv --python /opt/homebrew/bin/python3.12 .venv
uv python pin 3.12

这里选择 Python 3.12，主要是为了避开太新的 Python 版本可能带来的兼容性问题。LangChain 需要 Python 3.10+，使用 3.12 会比较稳。

接着在 pyproject.toml 里维护依赖：

[project]
name = "langchain-demo"
version = "0.1.0"
description = "A uv-managed sandbox for practicing LangChain."
readme = "README.md"
requires-python = ">=3.12,<3.13"
dependencies = [
    "langchain",
    "langchain-community",
    "langchain-openai",
    "langchain-text-splitters",
    "pydantic",
    "python-dotenv",
]

[dependency-groups]
dev = [
    "ruff",
]

[tool.uv]
package = false

然后同步依赖：

uv sync --all-groups

这样 .venv、uv.lock、pyproject.toml 都准备好了，后面新增 demo 时继续通过 uv 来管理即可。

配置 OpenAI 兼容接口

这个 demo 使用的是 OpenAI 兼容接口，所以配置集中放在 .env 文件里：

OPENAI_API_KEY="your-api-key"
OPENAI_MODEL="gpt-5.5"
OPENAI_BASE_URL="http://127.0.0.1:8787/v1"

这里需要注意的是，OPENAI_BASE_URL 指向的是本地代理服务。只要这个服务兼容 OpenAI API，LangChain 的 ChatOpenAI 就可以直接使用。

.env 文件只作为本地配置使用，不提交到 Git 仓库，所以 .gitignore 里也加上了：

.venv/
.env
.ruff_cache/
__pycache__/

读取配置

为了后面的 demo 可以复用配置，在 chapter01/config.py 里单独写了一份配置读取代码。

核心代码如下：

from dataclasses import dataclass
import os
from pathlib import Path

from dotenv import load_dotenv


PROJECT_ROOT = Path(__file__).resolve().parents[1]


class ConfigError(RuntimeError):
    """Raised when required demo configuration is missing."""


@dataclass(frozen=True)
class OpenAISettings:
    api_key: str
    model: str
    base_url: str | None


def load_environment(project_root: Path = PROJECT_ROOT) -> Path | None:
    env_path = project_root / ".env"

    if env_path.exists():
        load_dotenv(env_path, override=True)
        return env_path

    return None


def get_openai_settings() -> OpenAISettings:
    api_key = os.getenv("OPENAI_API_KEY")
    model = os.getenv("OPENAI_MODEL")
    base_url = os.getenv("OPENAI_BASE_URL")

    missing = [
        name
        for name, value in (
            ("OPENAI_API_KEY", api_key),
            ("OPENAI_MODEL", model),
        )
        if not value
    ]
    if missing:
        joined = ", ".join(missing)
        raise ConfigError(f"Missing required environment variable(s): {joined}")

    return OpenAISettings(
        api_key=api_key,
        model=model,
        base_url=base_url,
    )

这里做的事情很简单：

通过当前文件位置找到项目根目录。
读取项目根目录下的 .env。
从环境变量里拿到 OPENAI_API_KEY、OPENAI_MODEL、OPENAI_BASE_URL。
如果缺少必要配置，就直接抛出错误。

配置代码不复杂，但单独拆出来很有必要。后面写结构化输出、Agent、RAG 时，都可以继续复用这部分。

第一次模型调用

接下来就是最小的 LangChain 调用代码。

文件是 chapter01/chat_basic.py：

import sys

from langchain_core.messages import HumanMessage, SystemMessage
from langchain_openai import ChatOpenAI

from chapter01.config import get_openai_settings, load_environment


DEFAULT_QUESTION = "请用一句话介绍 LangChain 是什么。"


def main() -> None:
    """最小聊天示例：加载配置，创建模型，发送一条消息。"""

    load_environment()
    settings = get_openai_settings()

    question = " ".join(sys.argv[1:]) or DEFAULT_QUESTION

    model = ChatOpenAI(
        model=settings.model,
        api_key=settings.api_key,
        base_url=settings.base_url,
        temperature=0.2,
    )

    response = model.invoke(
        [
            SystemMessage(content="你是一个简洁、准确的 LangChain 学习助手。"),
            HumanMessage(content=question),
        ]
    )

    print("Question:")
    print(question)
    print()
    print("Answer:")
    print(response.content)


if __name__ == "__main__":
    main()

可以看到，这个文件没有做复杂封装，就是按顺序完成四步：

读取 .env 配置。
创建 ChatOpenAI 模型对象。
构造一组消息。
调用 model.invoke() 获取回复。

在 LangChain 里，对话消息是有角色区分的：

SystemMessage：告诉模型应该以什么方式工作。
HumanMessage：用户真正提出的问题。

这和直接拼一个字符串给模型不太一样。把消息角色分清楚后，后面扩展多轮对话、Agent、工具调用时会更自然。

运行 Demo

在 code/langchain-demo 目录下运行：

uv run python -m chapter01.chat_basic

默认问题是：

请用一句话介绍 LangChain 是什么。

也可以自己传入问题：

uv run python -m chapter01.chat_basic "LangChain 是用来做什么的？"

如果当前 shell 里残留了其他项目的 PYTHONPATH，可以先清掉再运行：

env -u PYTHONPATH uv run python -m chapter01.chat_basic

正常情况下，会看到类似输出：

Question:
请用一句话介绍 LangChain 是什么。

Answer:
LangChain 是一个用于构建基于大语言模型应用的开发框架，可以把模型、提示词、工具、记忆和外部数据源连接起来。

如果这里可以正常返回，说明本地模型服务、API Key、模型名、LangChain 调用链路都已经跑通了。

小结

这一篇主要完成了 LangChain 系列教程的第一步：

用 uv 准备 Python 3.12 虚拟环境。
安装 LangChain 相关依赖。
通过 .env 配置 OpenAI 兼容接口。
写一个最小的 ChatOpenAI 调用 demo。
用 uv run python -m chapter01.chat_basic 跑通第一次模型调用。

这一步的代码尽量保持简单，不引入 Web 框架，也不急着写 Agent。先把模型调用链路打通，后面再继续往上叠 PromptTemplate、结构化输出、工具调用和 RAG。

LangChain 入门学习第一篇-环境准备和模型调用

标签: LangChain Python AI

分类目录: code

准备 Python 环境

配置 OpenAI 兼容接口

读取配置

第一次模型调用

运行 Demo

小结

参考

相关文章

留言板