跳到主内容

LangChain Python

最后更新: 2026-10-11

1. 概述

在 Python 中,模块通常就是一个以 .py 结尾的文件。文件里定义的变量、函数和类,都可以被其他 Python 文件导入和复用。

你可以先把模块理解成一个有名字的代码文件:greeting.py 是一个模块,main.py 也是一个模块。模块名通常就是文件名去掉 .py 后的部分。

把代码拆成多个模块,有三个直接好处:

  • 每个文件只负责一类事情,更容易阅读;
  • 一段逻辑写一次,就可以在多个地方复用;
  • 修改某个功能时,不需要在一个很长的文件里寻找所有代码。

Python 自带的标准库和通过 uv 安装的第三方库,本质上也都是可以被导入的模块或模块集合。我们在 FastAPI 项目中导入 FastAPI,在 LangChain 项目中导入 ChatOpenAI,使用的就是同一套模块机制。

2. 创建第一个模块

先在项目根目录创建一个 greeting.py,在里面定义一个问候函数:

greeting.py
1
def say_hello(name: str) -> str:
2
return f"你好,{name}!"

再创建 main.py,从 greeting 模块中导入这个函数:

main.py
1
from greeting import say_hello
2
3
message = say_hello("小微")
4
print(message)

在项目根目录运行:

code.ts
1
uv run python main.py

程序会输出:

code.ts
1
你好,小微!

这句 from greeting import say_hello 可以拆成两部分理解:greeting 是模块名,say_hello 是要从模块中取出的函数。导入之后,main.py 就可以像使用本地函数一样调用它。

3. 导入模块

我们来学习一下几种常见的导入模块的方式,第一种是导入整个模块

code.ts
1
import math
2
3
radius = 3
4
area = math.pi * radius ** 2
5
print(area)

使用 import math 时,math 是一个模块对象。调用模块中的内容时,要写成 math.pi、math.sqrt(...) 这样的形式。这样写的好处是来源清楚:看到 math.sqrt 就知道这个函数来自 math 模块。

第二种是只导入需要的内容

code.ts
1
from math import pi, sqrt
2
3
radius = 3
4
area = pi * radius ** 2
5
distance = sqrt(16)
6
print(area, distance)

这种写法可以少写一个模块前缀,但阅读代码时需要记住 pi 和 sqrt 从哪里来。导入内容较少、来源很明确时可以使用。

第三种是使用别名

code.ts
1
import datetime as dt
2
3
today = dt.date.today()
4
print(today)

as 为模块取一个更短的别名。别名只在当前模块有效,不会修改原模块的名字。常见的第三方库也会使用约定俗成的别名,例如 import numpy as np。

还有一种通配导入写法,可以一次导入模块公开的名称:

code.ts
1
from math import *

import * 会把模块中的许多名字直接放进当前文件。这样虽然少写了前缀,却会让人很难判断一个名字来自哪里,还可能覆盖当前文件中已有的变量。实际项目中,优先使用 import math 或明确列出 from math import sqrt

4. 导出

Python 没有 export 关键字。模块顶层的定义,以及实际执行到的赋值和导入,会把名称放进模块的命名空间中,因此其他代码可以显式导入这些名称。定义在函数内部的局部变量则不属于模块的公开名称。

greeting.py
1
DEFAULT_GREETING = "你好"
2
3
def say_hello(name: str) -> str:
4
return f"{DEFAULT_GREETING},{name}!"
5
6
class Greeter:
7
def greet(self, name: str) -> str:
8
return say_hello(name)

上面的 DEFAULT_GREETING、say_hello 和 Greeter 都可以被导入:

main.py
1
from greeting import DEFAULT_GREETING, Greeter, say_hello
2
3
print(DEFAULT_GREETING)
4
print(say_hello("小微"))
5
print(Greeter().greet("小明"))

所以,通常不需要额外声明「哪些内容可以导出」。只要名称存在于模块的顶层命名空间,就可以通过 from module import name 这种方式导入。这里的「导出」更准确地说,是其他模块能够访问当前模块的公开名称。

用下划线表示内部实现

如果某个函数或变量只想作为模块内部的辅助实现,可以给它加一个前导下划线:

greeting.py
1
def _normalize_name(name: str) -> str:
2
return name.strip()
3
4
def say_hello(name: str) -> str:
5
return f"你好,{_normalize_name(name)}!"

前导下划线主要是一种约定,表示「这是内部使用的名称」。它不会真正阻止别人显式导入,下面的写法仍然可以工作:

code.ts
1
from greeting import _normalize_name

因此,下划线是可读性和协作约定,不是访问权限控制。

用 __all__ 控制通配导入

如果确实需要控制 from greeting import * 能够导入哪些名称,可以在模块中定义 __all__:

greeting.py
1
__all__ = ["DEFAULT_GREETING", "say_hello"]
2
3
DEFAULT_GREETING = "你好"
4
5
def say_hello(name: str) -> str:
6
return f"{DEFAULT_GREETING},{name}!"
7
8
def _normalize_name(name: str) -> str:
9
return name.strip()

此时执行 from greeting import * 时,只会导入 __all__ 中列出的两个名称。没有定义 __all__ 时,通配导入通常会排除以下划线开头的名称。__all__ 不会阻止显式导入,也不会提供真正的权限控制;它主要用于约定模块的公开 API。实际项目中仍然建议显式导入名称,而不是依赖通配导入。

5. 机制剖析

当 Python 第一次导入一个模块时,会创建模块对象,把它登记到 sys.modules 缓存中,再执行模块的顶层代码。成功加载后,再次导入同一个模块通常会复用缓存;如果加载失败,导入系统会移除这次加载失败的模块。

因此,模块的顶层位置适合放函数、类和常量定义,不适合放会在导入时自动执行的业务操作。例如,下面的打印语句会在同一个解释器第一次导入 greeting 时执行;后续普通导入通常会复用缓存,不会重复打印:

greeting.py
1
print("greeting 模块正在加载")
2
3
def say_hello(name: str) -> str:
4
return f"你好,{name}!"

更常见的做法是把可执行逻辑放进函数中,需要时再调用。这样可以让导入过程主要用于准备定义,避免在导入时启动服务、发送请求或修改数据。

另外,同一个 Python 文件既可以被直接运行,也可以被其他文件导入。Python 会根据使用方式设置特殊变量 __name__,来区分这两种情况:

  • 直接执行 python main.py 时,__name__ 的值是 "__main__";
  • 被其他模块导入时,__name__ 的值是导入使用的模块名,例如 "greeting";包内模块则可能是 "app.agent"。

利用这个差异,可以让一个模块同时支持「被导入」和「直接运行」两种方式:

greeting.py
1
def say_hello(name: str) -> str:
2
return f"你好,{name}!"
3
4
def main() -> None:
5
print(say_hello("小微"))
6
7
if __name__ == "__main__":
8
main()

当执行 uv run python greeting.py 时,main() 会被调用;当 main.py 导入 say_hello 时,main() 不会自动执行。这一层判断是 Python 模块中非常常见的结构。

6. 从模块到包

当项目中的模块越来越多时,可以用包把相关模块组织在同一个目录中。对于初学者,可以先把包理解成「用目录组织起来的一组模块」。

例如,我们可以把项目整理成下面这样:

目录结构
使用上下方向键浏览目录,左右方向键展开或收起,Enter 或空格切换展开状态。
    • main.py应用入口
      • __init__.py声明普通包
      • model.py模型模块
      • prompts.py提示词模块

__init__.py 可以是空文件,它的作用是明确告诉 Python:这个目录可以作为一个包来组织代码。现代 Python 也支持不放这个文件的命名空间包,但在学习和普通应用项目中保留它更直观。

假设 prompts.py 中定义了一个提示词:

app/prompts.py
1
SYSTEM_PROMPT = "你是一名温和、可靠的助手。"

在项目根目录的 main.py 中,可以使用包路径导入:

main.py
1
from app.prompts import SYSTEM_PROMPT
2
3
print(SYSTEM_PROMPT)

app.prompts 表示先找到 app 包,再找到其中的 prompts 模块。使用完整的包路径,能够让代码的来源更加清楚。

7. 在 FastAPI 和 LangChain 中拆分模块

前面文章里的 main.py 为了方便入门,把 FastAPI、模型和 Agent 都写在了同一个文件。这一篇沿用相同的服务,再把问候函数、模型配置、提示词和 Agent 按职责放进不同模块。

切换到在线案例后,可以先点击运行,再发送默认的 GET /hello?name=小微。这个接口只调用项目中的问候模块,保留 xxxx 密钥也能使用。确认模块导入正常后,再配置模型并调用 /chat。

目录结构
使用上下方向键浏览目录,左右方向键展开或收起,Enter 或空格切换展开状态。
      • __init__.py声明 app 为普通 Python 包
      • model.py创建和配置聊天模型
      • prompts.py维护系统提示词
      • agent.py按需创建并复用 Agent
    • greeting.py可独立运行的问候模块
    • main.pyFastAPI 服务入口
    • .env填写自己的模型密钥
    • .env.example不含真实密钥的配置模板
    • pyproject.toml项目和依赖声明
    • .python-version本机 Python 版本
    • .gitignore排除密钥、环境和缓存
    • README.md运行与练习说明

7.1 准备问候模块

把前面介绍的常量、内部函数、类和 __name__ 判断组合成一个完整的 greeting.py:

greeting.py
01
__all__ = ["DEFAULT_GREETING", "say_hello", "Greeter"]
02
03
DEFAULT_GREETING = "你好"
04
05
def _normalize_name(name: str) -> str:
06
return name.strip() or "朋友"
07
08
def say_hello(name: str) -> str:
09
return f"{DEFAULT_GREETING},{_normalize_name(name)}!"
10
11
class Greeter:
12
def greet(self, name: str) -> str:
13
return say_hello(name)
14
15
def main() -> None:
16
print(say_hello("小微"))
17
18
if __name__ == "__main__":
19
main()

_normalize_name 会去掉名字两端的空格,空名字则使用「朋友」。Greeter 复用同一个问候函数;显式导入 Greeter 或 say_hello 都不会触发最后的 main()。

7.2 拆分模型和提示词

模型模块负责读取配置,并提供创建模型的函数。导入这个模块时只定义函数,等真正调用它时才读取环境变量:

app/model.py
01
import os
02
03
from langchain_openai import ChatOpenAI
04
05
def create_model() -> ChatOpenAI:
06
return ChatOpenAI(
07
model=os.environ["DEEPSEEK_MODEL"],
08
api_key=os.environ["DEEPSEEK_API_KEY"],
09
base_url=os.environ.get("DEEPSEEK_BASE_URL", "https://api.deepseek.com"),
10
)

提示词也可以是独立模块里的常量。创建 app/prompts.py,写入:

app/prompts.py
1
SYSTEM_PROMPT = "你是一名温和、可靠的 Python 学习助手。"

7.3 组装 Agent

创建 app/agent.py,通过包内的相对导入组合模型和提示词:

app/agent.py
01
from functools import cache
02
03
from langchain.agents import create_agent
04
05
from .model import create_model
06
from .prompts import SYSTEM_PROMPT
07
08
@cache
09
def get_agent():
10
return create_agent(
11
model=create_model(),
12
system_prompt=SYSTEM_PROMPT,
13
)

这里的点号表示相对当前包导入。agent.py、model.py 和 prompts.py 都在 app 包中,因此 from .model import create_model 可以找到同一个包里的模型模块。

get_agent() 在第一次调用时才创建模型和 Agent。标准库的 @cache 会保存返回值,后续请求复用同一个 Agent;重新运行在线项目后,模块会重新加载,缓存也重新建立。这种做法避免了仅仅导入模块就创建模型实例。

相对导入需要包上下文,因此应从项目根目录启动 main.py,不要直接执行 python app/agent.py。需要单独执行包内模块时,可使用 uv run python -m app.agent;当前模块只定义函数,单独执行它不会自动发送模型请求。

7.4 保留服务入口

FastAPI 入口负责接收请求和返回响应。/hello 使用问候模块,/chat 则在收到问题后调用 Agent:

main.py
01
from fastapi import FastAPI
02
from pydantic import BaseModel
03
04
from app.agent import get_agent
05
from greeting import DEFAULT_GREETING, Greeter
06
07
app = FastAPI()
08
09
class ChatRequest(BaseModel):
10
question: str
11
12
@app.get("/hello")
13
async def hello(name: str = "小微") -> dict[str, str]:
14
return {
15
"message": Greeter().greet(name),
16
"default_greeting": DEFAULT_GREETING,
17
}
18
19
@app.post("/chat")
20
async def chat(request: ChatRequest) -> dict[str, str]:
21
result = await get_agent().ainvoke({
22
"messages": [{"role": "user", "content": request.question}],
23
})
24
return {"answer": result["messages"][-1].content}

此时模块依赖可以顺着代码读出来:main 导入 greeting 和 app.agent,app.agent 再导入 app.model 和 app.prompts。这些模块都不需要反过来导入 main,可以避免这组文件之间产生循环导入。

7.5 运行与修改

在线案例默认发送 GET /hello?name=小微,返回:

code.ts
1
{
2
"message": "你好,小微!",
3
"default_greeting": "你好"
4
}

我们可以把 greeting.py 中的 DEFAULT_GREETING 改成 "欢迎",保存后重新运行,再发送请求。返回的问候语和常量都会变化,这就能看到入口如何复用另一个模块里的最新定义。

调用模型之前,打开项目里的 .env:

.env
1
DEEPSEEK_MODEL=deepseek-v4-flash
2
DEEPSEEK_BASE_URL=https://api.deepseek.com
3
# 请将 xxxx 替换为你自己的 DeepSeek API Key,保存后重新运行。
4
DEEPSEEK_API_KEY=xxxx

将 DEEPSEEK_API_KEY 的 xxxx 替换为自己的密钥,保存并重新运行。然后把请求方法改成 POST、地址改成 /chat,请求体填写:

code.ts
1
{"question": "请用一句话介绍 Python 模块。"}

这个接口会使用真实的 LangChain create_agent 和 LangGraph ainvoke 执行图,再返回模型的回答。.env.example 只保留占位符,不要把真实密钥写进去或提交到 Git。

下载案例后,在项目根目录执行下面的命令启动本机服务:

macos.sh
1
uv run --env-file .env fastapi dev main.py

然后发送请求:

macos.sh
1
curl "http://127.0.0.1:8000/hello?name=Python"
2
3
curl -X POST http://127.0.0.1:8000/chat \
4
-H "Content-Type: application/json" \
5
-d '{"question":"请用一句话介绍 Python 模块。"}'

浏览器案例会先加载 .env,再导入 main:app,通过内存中的 FastAPI 应用处理请求,不运行上述终端命令或监听本机端口。此时 main.py 的 __name__ 是 "main",因此不要把 FastAPI 路由定义放进 if __name__ == "__main__" 中。greeting.py 中的独立运行示例仍可以在本机通过 uv run python greeting.py 执行。

依赖声明在 pyproject.toml 中,在线案例复用前一篇已经适配浏览器的版本组合。相同依赖的下载缓存可以在本站文章之间复用,本篇的代码草稿和日志则独立保存。模型地址还需要允许网站的跨域请求;这里使用异步 ainvoke,以适配浏览器 Python 运行环境。

正在验证登录状态
请稍候,验证完成后将继续显示文章内容

此段落已有评论,按 Enter 查看评论及回复列表。

评论-

文章反应
评论与回复

连接 GitHub 后查看和发表评论,也可在 GitHub 查看公开讨论。

添加评论
    即时渲染