LangGraph + vLLM: 职业转换顾问，配备PostgreSQL内存

使用LangGraph构建的智能职业转换顾问，具备生产就绪的持久内存，由PostgreSQL和vLLM推理提供支持。

概览

该项目演示了一个具有对话记忆的状态化AI代理：

• PostgreSQL持久性 - 使用AsyncPostgresSaver实现生产就绪的对话存储
• 多轮推理 - 维护跨对话轮次和服务器重启的上下文
• 网络研究工具 - 通过Firecrawl MCP进行搜索和抓取能力
• 实时API + 聊天UI - 内置LangGraph Studio界面
• 生产就绪 - vLLM后端用于快速推理 + PostgreSQL用于可扩展的持久性

关键技术

• LangGraph - 带内置记忆的状态机框架
• PostgreSQL - 生产级持久对话存储
• AsyncPostgresSaver - 异步检查点器，带连接池
• vLLM - 在GPU上快速的LLM推理（比HuggingFace快4-24倍）
• Hermes-2-Pro-Mistral-7B - 具有出色工具调用能力的7B参数模型
• Firecrawl MCP - 通过模型上下文协议进行生产级网页抓取
• LangGraph CLI - 内置API服务器和Studio UI

架构

用户查询 → LangGraph代理 → [记忆检查] → vLLM + 工具 → 响应
                                      ↓
                            PostgreSQL检查点器
                            （持久记忆）
                                      ↓
                            Docker容器
                            （postgres:16-alpine）

关键特性：

• 状态化对话 - 每条消息都保存在PostgreSQL中
• 基于线程的记忆 - 多个并发对话，各自独立的记忆
• 跨重启持久性 - 对话历史在服务器重启后仍然存在
• 多轮推理 - 代理记得前一轮的上下文
• 工具集成 - 通过Firecrawl MCP进行网络搜索和抓取
• 自动表创建 - 数据库模式在首次运行时自动创建

快速开始

1. 克隆仓库

git clone <your-repo-url>
cd langchain-vllm

2. 启动PostgreSQL数据库

# 在Docker中启动PostgreSQL
docker-compose up -d

# 验证是否正在运行
docker-compose ps

这会创建一个PostgreSQL 16容器，包含：

• 数据库：langchain_db
• 用户：langchain
• 端口：5432
• 持久卷：postgres_data

3. 安装依赖项

uv pip install -r requirements.txt

或者使用pip：

pip install -r requirements.txt

4. 配置环境

cp .env.example .env
# 编辑.env文件，添加您的API密钥、RunPod端点和PostgreSQL凭据

所需变量：

• FIRECRAWL_API_KEY - 从firecrawl.dev获取
• RUNPOD_ENDPOINT_URL - 您的RunPod vLLM端点
• RUNPOD_API_KEY - 您的RunPod API密钥
• POSTGRES_PASSWORD - 设置为langchain_dev_password（与docker-compose.yml匹配）

5. 在RunPod上部署vLLM

选项A：使用预构建的Docker镜像（最快）：

1. 进入RunPod控制台 → 部署Pod
2. 选择GPU（推荐A4000或更好）
3. 在“容器镜像”下输入：vrknetha/langchain-vllm-workshop:latest
4. 设置容器磁盘：50GB+
5. 暴露端口：8000
6. 部署并等待启动
7. 将端点URL复制到.env

选项B：构建自定义镜像：

# 构建vLLM Docker镜像
docker build -f Dockerfile.vllm -t your-dockerhub-username/vllm-hermes:latest .

# 推送到Docker Hub
docker push your-dockerhub-username/vllm-hermes:latest

# 使用自定义镜像在RunPod上部署

详细说明见DEPLOYMENT.md。

6. 启动LangGraph服务器

开发模式（热重载，内存存储）：

langgraph dev --port 2024
# 使用内存存储，对话历史在重启时丢失

生产模式（PostgreSQL持久性）：

langgraph up --port 2024
# 自动读取POSTGRES_URI从.env
# 对话历史在重启时保留

替代方式（显式postgres-uri）：

langgraph up --port 2024 --postgres-uri "postgresql://langchain:langchain_dev_password@localhost:5432/langchain_db"

两种模式现在都使用PostgreSQL进行持久性。服务器将在以下地址启动：

• API：http://localhost:2024
• Studio UI：http://localhost:2024（内置聊天界面）

首次运行时，代理会自动创建PostgreSQL表：

• checkpoints - 对话状态快照
• checkpoint_blobs - 大型二进制数据
• checkpoint_writes - 检查点写操作

🎯 演示：职业转换顾问

本项目展示了一个职业转换顾问——一个引人注目的演示，通过实际应用场景展示了LangGraph v1的记忆和状态管理功能。

功能介绍

职业顾问帮助专业人士导航职业转换：

• 理解背景：通过对话捕捉背景、技能和目标
• 实时研究：使用Firecrawl搜索工作市场、要求和学习资源
• 技能差距分析：比较当前技能与目标角色的要求
• 个性化指导：创建定制的学习路径和工作目标
• 持久记忆：在多个对话轮次内保持完整的上下文

为什么引人注目

1. 普遍吸引力 - 每个人都在思考职业发展和技能提升
2. 情感共鸣 - 职业焦虑和不确定性是广泛相关的
3. 多轮智能 - 展示了持久对话记忆的强大
4. 实用价值 - 解决人们每天面临的真实问题
5. 技术展示 - 精美地展示了所有关键的LangGraph v1功能

演示脚本

参见**DEMO_CAREER.md**，其中包含完整的10分钟演示脚本：

• 演示前检查清单
• 每轮对话流程及预期行为
• 每一步需要强调的内容
• LangGraph Studio UI演示
• 线程隔离演示
• 常见问题的故障排除
• 准备问答环节

快速演示示例

第1轮："我是Sarah，一名拥有5年经验的Python开发者，想要转向AI/ML"
→ 代理：确认背景，开始建立关系

第2轮："我缺少哪些技能？"
→ 代理：搜索工作要求，分析技能差距，利用Python作为基础

第3轮："找到这些技能的相关课程"
→ 代理：记住第2轮的具体技能，找到相关学习资源

第4轮："6个月内我可以瞄准哪些工作？"
→ 代理：综合整个对话上下文，建议现实的目标

线程隔离测试：
→ 新线程："我的名字是什么？" → "我没有这些信息"
→ 原始线程："我的名字是什么？" → "你是Sarah，Python开发者..."

展示的关键特性

• MessagesState - LangGraph v1的预构建状态类（无需自定义类）
• tools_condition - 自动路由（取代18行自定义逻辑）
• 平台持久性 - 由LangGraph CLI管理的基于线程的记忆
• 异步模式 - 使用ainvoke()提高I/O性能
• MCP集成 - 标准化的工具协议，与Firecrawl集成

替代演示：短期记忆研究助手

对于更简单、通用的研究演示，请参见以下内容。

示例对话流程

这是如何展示记忆特性的：

第1轮：设置背景

用户："我的名字是Alex，我对电动汽车感兴趣"
代理："很高兴见到你，Alex！我很乐意帮你了解电动汽车..."

第2轮：跟进（使用记忆）

用户："前三名是什么？"
代理：[搜索电动汽车，记住Alex对电动汽车感兴趣]

第3轮：深入探讨（使用完整上下文）

用户："哪一款最适合长途旅行？"
代理：[分析之前的搜索结果，考虑Alex的需求，提供建议]

第4轮：新线程测试

用户：[在新线程中]"我的名字是什么？"
代理："我还没有这些信息..."
[演示线程隔离——每个对话都有独立的记忆]

展示的记忆特性

1. 对话连续性 - 代理记得讨论过的内容
2. 线程隔离 - 每个对话线程都有独立的记忆
3. 持久性 - 记忆在服务器重启后仍然存在（使用langgraph up）
4. 状态检查 - 在Studio UI中查看完整的对话历史

您将学到什么

1. LangGraph状态机 - 使用StateGraph构建代理
2. 检查点 - 基于SQLite的持久记忆
3. 多轮推理 - 上下文感知对话
4. MCP集成 - 直接访问工具进行网络搜索/抓取
5. 生产部署 - API + UI，使用LangGraph CLI

要求

• Python 3.10+
• Docker & Docker Compose（用于PostgreSQL数据库）
• Node.js（用于npx/Firecrawl MCP）
• Firecrawl API密钥（免费获取于firecrawl.dev）
• 带GPU信用的RunPod账户

理解记忆模式

开发模式：langgraph dev

• 记忆：内存存储（langgraph_runtime_inmem）
• 持久性：不持久 - 对话历史在重启时丢失
• 重新加载：代码更改时热重载
• 使用场景：快速开发迭代

生产模式：langgraph up --postgres-uri

• 记忆：PostgreSQL检查点器
• 持久性：在服务器重启后存活（存储在PostgreSQL中）
• 重新加载：代码更改时需要重建
• 使用场景：开发和测试
• 优点：快速迭代 + 持久记忆
• 需要：PostgreSQL正在运行（docker-compose up -d）

生产模式：langgraph up

• 记忆：PostgreSQL检查点器
• 持久性：在PostgreSQL中的完全生产持久性
• 重新加载：手动重启
• 使用场景：生产部署和演示
• 优点：带有持久记忆的生产就绪
• 需要：PostgreSQL正在运行（docker-compose up -d）

独立模式：python src/agent.py

• 记忆：PostgreSQL检查点器
• 持久性：PostgreSQL数据库
• 使用场景：测试代理初始化和表创建
• 注意：此模式初始化代理并显示配置信息
• 需要：PostgreSQL正在运行（docker-compose up -d）

数据库管理

查看对话历史：

docker exec -it langchain-postgres psql -U langchain -d langchain_db

# 列出表格
\dt

# 查看检查点
SELECT thread_id, checkpoint_id FROM checkpoints;

# 退出
\q

重置所有对话：

docker-compose down -v  # 移除卷
docker-compose up -d    # 新鲜数据库

停止PostgreSQL：

docker-compose down  # 数据在卷中保留

项目结构

langchain-vllm/
├── src/
│   └── career_advisor/     # LangGraph代理包
│       ├── __init__.py     # 包导出
│       ├── config.py       # 配置管理
│       ├── checkpointer.py # PostgreSQL持久性
│       ├── tools.py        # MCP工具设置
│       ├── prompts.py      # 系统提示
│       ├── nodes.py        # 图节点
│       └── agent.py        # 图构造
├── docker-compose.yml      # PostgreSQL数据库配置
├── langgraph.json          # LangGraph CLI配置
├── requirements.txt        # Python依赖项（包括PostgreSQL库）
├── .env                    # 环境变量（API密钥 + 数据库配置）
├── start_vllm.sh           # vLLM启动脚本
└── README.md               # 此文件

故障排除

PostgreSQL问题

"POSTGRES_PASSWORD环境变量是必需的"

• 复制.env.example到.env
• 设置POSTGRES_PASSWORD=langchain_dev_password

连接被拒绝到localhost:5432

• 启动PostgreSQL：docker-compose up -d
• 检查状态：docker-compose ps
• 查看日志：docker-compose logs -f postgres

"关系'checkpoints'不存在"

• 表在首次运行时通过checkpointer.setup()自动创建
• 验证代理成功初始化
• 检查PostgreSQL权限问题的日志

记忆未持久？

• PostgreSQL必须正在运行（docker-compose up -d）
• 验证请求之间使用相同的thread_id
• 检查PostgreSQL表是否存在：docker exec -it langchain-postgres psql -U langchain -d langchain_db -c "\dt"

vLLM问题

模型加载慢？

• 第一次请求需要2-3分钟来将模型加载到vLLM
• 在演示前用测试查询预热端点

"模型不存在" 404错误

• 检查src/agent.py和vLLM服务器中的模型名称是否匹配
• 验证vLLM已完成加载（2-3分钟）
• 测试：curl https://your-pod-8000.proxy.runpod.net/v1/models

MCP/工具问题

Firecrawl搜索错误？

• 如果看到“sources参数验证失败”，这是预期的——系统提示指示LLM避免使用sources参数
• 验证.env中设置了FIRECRAWL_API_KEY
• 检查Node.js是否已安装（npx所需）
• 确保可以手动运行npx -y firecrawl-mcp

工具无法工作？

• 验证.env中设置了所有必需的环境变量
• 检查Node.js是否已安装（npx所需）
• 查看服务器日志以查找任何MCP连接错误

服务器问题

服务器无法启动？

• 验证所有依赖项已安装：uv pip install -r requirements.txt
• 确保PostgreSQL正在运行：docker-compose ps
• 检查端口8123是否已被占用
• 查看控制台输出中的错误

资源

• LangGraph文档
• LangGraph记忆指南
• LangGraph CLI文档
• vLLM文档
• 模型上下文协议
• Firecrawl MCP服务器
• RunPod文档

许可

MIT许可 - 详情见LICENSE文件

贡献

欢迎贡献！请打开问题或PR。

致谢

• LangChain团队提供的优秀框架
• vLLM团队提供的超高速推理
• NousResearch提供的Hermes-2-Pro-Mistral-7B
• Firecrawl提供的生产级网页抓取