从Java转行大模型应用，LangGraph 平台介绍与项目部署学习

一、LangGraph 平台核心介绍1. 平台定义与定位LangGraph 是LangChain 生态中专门用于构建、编排与执行多步骤、多代理Multi-Agent复杂 AI 工作流的可视化 / 代码化开发平台核心解决传统 LLM 应用 “单轮对话、线性执行、无状态管理” 的局限性支持构建具备循环、分支、状态持久化、多代理协作的高级 AI 系统如自主 Agent、工作流引擎、复杂 RAG 增强系统。它是 LangChain 官方推出的 “工作流编排层”既提供Python 代码 SDK核心开发方式也配套LangGraph Studio 可视化工具本地 / 云端调试、监控、可视化工作流同时兼容 LangChain 生态所有组件LLM、向量库、工具、记忆模块等是构建企业级、生产级复杂 AI 应用的核心基础设施。2. 核心技术特性状态驱动Stateful工作流全程维护共享状态State所有节点Node可读写状态支持状态持久化与恢复解决多轮交互的上下文丢失问题。图结构编排以有向无环图DAG 循环节点为核心支持线性、分支if/else、循环、并行、多代理协作等任意复杂流程突破线性执行限制。多代理协作原生支持多个 Agent 节点分工协作如 “规划 Agent→执行 Agent→验证 Agent”每个 Agent 可独立配置 LLM、工具、提示词实现复杂任务拆解。工具集成与调用无缝对接 LangChain 工具生态如搜索、数据库、API、文件处理支持工具调用的自动路由、错误重试、结果校验。可视化调试配套 LangGraph Studio可实时查看工作流执行轨迹、状态变化、节点日志支持断点调试与流程回溯。生产级部署支持本地部署、容器化Docker、云端部署AWS/GCP/Azure兼容 FastAPI、Streamlit 等服务化框架支持异步执行、并发控制、日志监控。3. 核心应用场景自主智能代理Autonomous Agent如个人助理、代码生成 Agent、数据分析 Agent具备自主规划、执行、反思能力。复杂 RAG 增强系统多步骤检索→过滤→重排→生成→验证的闭环工作流解决单轮 RAG 的信息不准确问题。企业工作流自动化如合同审核、数据报表生成、客服工单处理多节点协作、分支判断、循环重试。多模态 AI 应用文本→图像→视频→音频的跨模态工作流编排。教育 / 科研工具如论文写作助手、实验流程自动化、代码调试 Agent。二、LangGraph 项目部署全流程学习笔记一环境准备基础依赖安装1. 核心环境要求Python 版本3.9~3.12LangGraph 对 Python 版本兼容性严格建议 3.10包管理工具pip/conda推荐 conda 创建虚拟环境避免依赖冲突必备依赖langgraph、langchain、langchain-openai或其他 LLM SDK、python-dotenv环境变量管理2. 虚拟环境创建与激活# 1. 创建conda虚拟环境推荐 conda create -n langgraph-env python3.11 conda activate langgraph-env # 2. 或使用venvPython原生 python -m venv langgraph-env # Windows激活 langgraph-env\Scripts\activate # Mac/Linux激活 source langgraph-env/bin/activate3. 核心依赖安装# 安装LangGraph核心库 pip install langgraph # 安装LangChain生态依赖根据LLM选择以OpenAI为例 pip install langchain langchain-openai python-dotenv # 安装可视化/调试工具LangGraph Studio可选但推荐 pip install langgraph-studio # 安装部署相关依赖FastAPIUvicorn用于服务化部署 pip install fastapi uvicorn4. 环境变量配置.env 文件在项目根目录创建.env文件配置 LLM API 密钥以 OpenAI 为例# OpenAI API密钥必填 OPENAI_API_KEYyour-openai-api-key # 可选模型版本、温度参数 OPENAI_MODELgpt-3.5-turbo OPENAI_TEMPERATURE0.1二基础项目结构标准模板plaintextlanggraph-project/ ├── .env # 环境变量配置 ├── main.py # 工作流核心代码定义State、Node、Graph ├── nodes/ # 自定义节点模块拆分复杂逻辑 │ ├── __init__.py │ ├── planner.py # 规划节点 │ ├── executor.py # 执行节点 │ └── validator.py # 验证节点 ├── tools/ # 自定义工具模块如搜索、数据库 │ ├── __init__.py │ └── web_search.py # 网页搜索工具 ├── state.py # 状态State定义推荐单独拆分 ├── requirements.txt # 依赖清单 └── README.md # 项目说明三核心代码实现以 “简单问答 Agent” 为例1. 定义状态State—— 核心数据结构在state.py中定义工作流共享状态所有节点共享该数据from typing import TypedDict, List, Dict # 定义Agent工作流状态继承TypedDict支持类型校验 class AgentState(TypedDict): # 用户输入问题 query: str # 中间思考过程规划步骤 thought: List[str] # 执行结果工具调用/LLM生成 result: str # 执行状态是否完成 is_finished: bool # 错误信息可选 error: str2. 定义节点Node—— 工作流执行单元在main.py中导入状态并定义节点每个节点是一个函数接收状态返回更新后的状态from langgraph.graph import StateGraph, END from langchain_openai import ChatOpenAI from dotenv import load_dotenv import os from state import AgentState # 加载环境变量 load_dotenv() # 初始化LLM llm ChatOpenAI( modelos.getenv(OPENAI_MODEL), temperaturefloat(os.getenv(OPENAI_TEMPERATURE)) ) # 1. 规划节点分析用户问题生成执行步骤 def planner_node(state: AgentState) - AgentState: query state[query] # 调用LLM生成思考步骤 prompt f分析问题{query}生成1-3个执行步骤用列表返回 thought llm.invoke(prompt).content return {thought: [thought], is_finished: False} # 2. 执行节点根据规划步骤执行生成答案 def executor_node(state: AgentState) - AgentState: query state[query] thought state[thought][-1] # 结合思考步骤生成最终答案 prompt f问题{query}\n思考步骤{thought}\n请生成最终答案 result llm.invoke(prompt).content return {result: result, is_finished: True} # 3. 条件判断节点判断是否结束工作流 def should_continue(state: AgentState) - str: if state[is_finished]: return END # 结束流程 else: return executor # 跳转到执行节点3. 构建工作流图Graph—— 编排节点与流程# 初始化状态图传入定义的State类型 workflow StateGraph(AgentState) # 添加节点节点名节点函数 workflow.add_node(planner, planner_node) workflow.add_node(executor, executor_node) # 设置入口节点流程起始点 workflow.set_entry_point(planner) # 添加边节点跳转逻辑 # 1. 规划节点 → 条件判断是否执行/结束 workflow.add_conditional_edges( planner, should_continue, # 条件映射条件返回值 → 目标节点 { executor: executor, END: END } ) # 2. 执行节点 → 结束 workflow.add_edge(executor, END) # 编译工作流生成可执行的Graph对象 app workflow.compile()4. 运行工作流本地调试# 测试运行工作流 if __name__ __main__: # 初始状态输入 initial_state { query: LangGraph是什么有什么核心作用, thought: [], result: , is_finished: False, error: } # 执行工作流同步调用 final_state app.invoke(initial_state) # 输出结果 print(用户问题, final_state[query]) print(思考步骤, final_state[thought]) print(最终答案, final_state[result])四可视化调试LangGraph Studio1. 启动 LangGraph Studio在项目根目录终端执行langgraph-studio启动后会自动打开浏览器默认地址http://localhost:3978进入可视化调试界面。2. 核心调试功能工作流可视化自动解析代码中的 Graph 结构展示节点、边、条件分支的拓扑图。状态实时查看执行过程中实时查看 State 的每一步变化输入→中间→输出。节点日志查看每个节点的输入 / 输出、LLM 调用日志、工具调用结果。断点调试在任意节点设置断点单步执行工作流排查逻辑问题。流程回溯支持重新执行历史流程对比不同输入的执行差异。五生产级部署三种主流方式方式 1FastAPI 服务化部署API 接口在main.py中添加 FastAPI 路由from fastapi import FastAPI from pydantic import BaseModel # 初始化FastAPI应用 app_api FastAPI(titleLangGraph Agent API, version1.0) # 定义请求体模型 class QueryRequest(BaseModel): query: str # 定义API接口异步调用提升性能 app_api.post(/agent/query, summary调用LangGraph Agent) async def agent_query(request: QueryRequest): initial_state { query: request.query, thought: [], result: , is_finished: False, error: } # 异步执行工作流 final_state await app.ainvoke(initial_state) return { query: final_state[query], thought: final_state[thought], result: final_state[result], status: success }启动 FastAPI 服务uvicorn main:app_api --host 0.0.0.0 --port 8000 --reload访问接口http://localhost:8000/docsSwagger UI可直接测试接口方式 2Docker 容器化部署标准化部署在项目根目录创建Dockerfile# 基础镜像 FROM python:3.11-slim # 设置工作目录 WORKDIR /app # 复制依赖清单 COPY requirements.txt . # 安装依赖 RUN pip install --no-cache-dir -r requirements.txt # 复制项目代码 COPY . . # 暴露端口 EXPOSE 8000 # 启动命令 CMD [uvicorn, main:app_api, --host, 0.0.0.0, --port, 8000]创建requirements.txt导出依赖pip freeze requirements.txt构建并运行 Docker 容器# 构建镜像 docker build -t langgraph-agent:v1 . # 运行容器挂载.env文件避免密钥泄露 docker run -d -p 8000:8000 --env-file .env langgraph-agent:v1方式 3云端部署AWS/GCP/Azure以 AWS 为例核心步骤将 Docker 镜像推送至 AWS ECR容器镜像仓库。使用 AWS ECS弹性容器服务或 EKSK8s部署容器。配置 API Gateway对外提供稳定 API 入口、CloudWatch日志监控、IAM权限管理。配置自动扩缩容应对高并发请求。六部署常见问题与解决方案依赖冲突问题安装 langgraph 后langchain 版本不兼容。解决指定版本安装如pip install langgraph0.0.56 langchain0.1.20参考 LangGraph 官方兼容表。LLM 调用失败问题OPENAI_API_KEY未生效报错 “API key not found”。解决确保.env文件在项目根目录且load_dotenv()在代码最开头执行检查密钥是否正确无多余空格。工作流执行卡住问题节点执行无响应状态未更新。解决使用 LangGraph Studio 查看节点日志排查 LLM 超时、工具调用错误添加超时机制与错误捕获。Docker 部署环境变量丢失问题容器内无法读取.env中的 API 密钥。解决通过--env-file .env参数挂载环境变量或在 Docker run 时直接传入-e OPENAI_API_KEYxxx。三、学习总结与进阶方向1. 核心学习要点LangGraph 的核心是状态驱动 图结构编排State 是工作流的 “数据核心”Node 是 “执行单元”Graph 是 “流程逻辑”。开发流程定义 State → 编写 Node → 编排 Graph → 调试运行 → 部署服务。可视化调试LangGraph Studio是开发复杂工作流的必备工具大幅提升排查效率。2. 进阶学习方向多代理协作构建 “规划→执行→验证→反思” 的闭环自主 Agent。工具增强集成自定义工具如数据库、文件处理、API 调用实现复杂业务逻辑。状态持久化使用 Redis / 数据库存储 State支持工作流中断恢复。异步 / 并发优化工作流异步执行提升高并发场景下的性能。监控与运维集成 Prometheus/Grafana实现工作流执行监控、告警、日志分析。