STARWARCLOUD STARWAR.AI
返回市场
语言链-VLLM工作坊

语言链-VLLM工作坊

作者：vrknetha9 星标更新：2025-11-15
安装使用来源：spider==github.com

项目介绍

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进行持久性。服务器将在以下地址启动：

首次运行时，代理会自动创建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是否已被占用
  • 查看控制台输出中的错误

资源

许可

MIT许可 - 详情见LICENSE文件

贡献

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

致谢

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