AI Agent / 系统课时

创建隔离的 Python 项目

创建隔离的 Python 项目

本篇从空目录搭一个可重复运行的 LangGraph Python 项目:用虚拟环境隔离依赖,用依赖文件固定项目入口,用 .env 管理环境变量,最后运行一个最小状态图验证安装结果。完成后,你会得到可以继续扩展节点和状态的干净项目骨架。

学习目标

  • 使用 venv 创建与系统 Python 隔离的运行环境
  • 用依赖文件和 .env 组织可重复的本地配置
  • 运行最小 LangGraph 状态图并验证环境确实可用

先确认 Python 可用

先在空项目目录中确认解释器能正常启动。示例使用 python3,如果你的系统命令是 python,后续保持一致即可。

bash
python3 --version

预期输出

text
Python 3.<MINOR>.<PATCH>

版本号会因本机环境不同而变化;关键是命令能正常返回一个 Python 3 版本。如果命令不存在,先安装受当前 LangGraph 版本支持的 Python,再继续创建项目。

建立虚拟环境

在项目根目录创建 .venv,激活后再验证当前解释器前缀确实指向这个目录。下面命令适用于 macOS 或 Linux shell。

bash
python3 -m venv .venv
source .venv/bin/activate
python -c "import sys; print(sys.prefix.endswith('.venv'))"

预期输出

text
True

激活虚拟环境后,后续安装的包都会进入 .venv,不会污染系统 Python。重新打开终端时需要再次执行激活命令。

固化依赖与环境变量

在项目根目录新建 requirements.txt,只放当前最小示例需要的依赖。

text
langgraph
python-dotenv

然后安装依赖,并用一次导入检查确认两个包都可用。

bash
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')"

预期输出

text
dependencies ok

同时会生成记录当前精确依赖版本的 requirements.lock,应将它纳入版本控制,用于后续复现同一环境。

接着新建 .env,先放一个无敏感信息的本地变量,后续接入模型 API 时也可以沿用同一种方式。

text
APP_ENV=local

同时创建 .gitignore,避免把虚拟环境和本地密钥文件提交到仓库。

text
.venv/
.env
__pycache__/

requirements.txt 应进入版本控制,而 .env 通常不应提交。团队需要共享变量名时,可以另外维护不含真实密钥的 .env.example。

写一个最小状态图入口

在根目录创建 app.py。这个示例定义一个只有一个业务节点的状态图:输入字符串进入 normalize 节点,被去掉首尾空白并转换成大写,然后到达结束节点。

python
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 并返回节点更新后的状态。

运行并验收

保持虚拟环境已激活,在项目根目录执行入口文件。

bash
python app.py

预期输出

text
env=local
HELLO LANGGRAPH

看到两行结果说明三个关键环节都已打通:.env 被成功加载,LangGraph 能创建并编译状态图,状态也确实经过节点更新后返回。

处理最常见的启动失败

如果出现 ModuleNotFoundError,先检查终端是否仍处于 .venv,再执行 python -m pip show langgraph 确认依赖是否安装在当前解释器中。不要混用系统 pip 和虚拟环境里的 python。

如果 .env 没有生效,确认文件位于运行 python app.py 时的项目根目录,并检查变量名是否与代码一致。真实 API 密钥应继续放在 .env 或密钥管理系统中,不要直接写进 app.py。当最小入口能够稳定输出预期结果后,再开始加入模型、工具、分支和检查点,环境问题会更容易与工作流问题分开定位。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

创建隔离的 Python 项目

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通