AI Agent / 系统课时
创建隔离的 Python 项目
创建隔离的 Python 项目
本篇从空目录搭一个可重复运行的 LangGraph Python 项目:用虚拟环境隔离依赖,用依赖文件固定项目入口,用 .env 管理环境变量,最后运行一个最小状态图验证安装结果。完成后,你会得到可以继续扩展节点和状态的干净项目骨架。
学习目标
- 使用
venv创建与系统 Python 隔离的运行环境 - 用依赖文件和
.env组织可重复的本地配置 - 运行最小 LangGraph 状态图并验证环境确实可用
先确认 Python 可用
先在空项目目录中确认解释器能正常启动。示例使用 python3,如果你的系统命令是 python,后续保持一致即可。
python3 --version预期输出
Python 3.<MINOR>.<PATCH>版本号会因本机环境不同而变化;关键是命令能正常返回一个 Python 3 版本。如果命令不存在,先安装受当前 LangGraph 版本支持的 Python,再继续创建项目。
建立虚拟环境
在项目根目录创建 .venv,激活后再验证当前解释器前缀确实指向这个目录。下面命令适用于 macOS 或 Linux shell。
python3 -m venv .venv
source .venv/bin/activate
python -c "import sys; print(sys.prefix.endswith('.venv'))"预期输出
True激活虚拟环境后,后续安装的包都会进入 .venv,不会污染系统 Python。重新打开终端时需要再次执行激活命令。
固化依赖与环境变量
在项目根目录新建 requirements.txt,只放当前最小示例需要的依赖。
langgraph
python-dotenv然后安装依赖,并用一次导入检查确认两个包都可用。
python -m pip install -r requirements.txt >/dev/null
python -m pip freeze > requirements.lock
python -c "from langgraph.graph import StateGraph; from dotenv import load_dotenv; print('dependencies ok')"预期输出
dependencies ok同时会生成记录当前精确依赖版本的 requirements.lock,应将它纳入版本控制,用于后续复现同一环境。
接着新建 .env,先放一个无敏感信息的本地变量,后续接入模型 API 时也可以沿用同一种方式。
APP_ENV=local同时创建 .gitignore,避免把虚拟环境和本地密钥文件提交到仓库。
.venv/
.env
__pycache__/requirements.txt 应进入版本控制,而 .env 通常不应提交。团队需要共享变量名时,可以另外维护不含真实密钥的 .env.example。
写一个最小状态图入口
在根目录创建 app.py。这个示例定义一个只有一个业务节点的状态图:输入字符串进入 normalize 节点,被去掉首尾空白并转换成大写,然后到达结束节点。
import os
from typing import TypedDict
from dotenv import load_dotenv
from langgraph.graph import END, START, StateGraph
load_dotenv()
class State(TypedDict):
message: str
def normalize(state: State) -> dict[str, str]:
# 节点只返回发生变化的状态字段,便于后续扩展更多字段。
return {"message": state["message"].strip().upper()}
builder = StateGraph(State)
builder.add_node("normalize", normalize)
builder.add_edge(START, "normalize")
builder.add_edge("normalize", END)
graph = builder.compile()
if __name__ == "__main__":
result = graph.invoke({"message": " hello langgraph "})
print(f"env={os.getenv('APP_ENV')}")
print(result["message"])预期结果:文件保存后不会自行执行;下一节从项目根目录运行它,成功时应读取 .env 并返回节点更新后的状态。
运行并验收
保持虚拟环境已激活,在项目根目录执行入口文件。
python app.py预期输出
env=local
HELLO LANGGRAPH看到两行结果说明三个关键环节都已打通:.env 被成功加载,LangGraph 能创建并编译状态图,状态也确实经过节点更新后返回。
处理最常见的启动失败
如果出现 ModuleNotFoundError,先检查终端是否仍处于 .venv,再执行 python -m pip show langgraph 确认依赖是否安装在当前解释器中。不要混用系统 pip 和虚拟环境里的 python。
如果 .env 没有生效,确认文件位于运行 python app.py 时的项目根目录,并检查变量名是否与代码一致。真实 API 密钥应继续放在 .env 或密钥管理系统中,不要直接写进 app.py。当最小入口能够稳定输出预期结果后,再开始加入模型、工具、分支和检查点,环境问题会更容易与工作流问题分开定位。