Skip to content

Instantly share code, notes, and snippets.

@JimLiu

JimLiu/Gemini Fullstack LangGraph 技术架构详解.md

Created June 7, 2025 03:57
Show Gist options
  • Save JimLiu/ca25ba4e4fccac2b6a16270c8e82b11a to your computer and use it in GitHub Desktop.
Save JimLiu/ca25ba4e4fccac2b6a16270c8e82b11a to your computer and use it in GitHub Desktop.
Download ZIP
Raw
Gemini Fullstack LangGraph 技术架构详解.md

Gemini Fullstack LangGraph 技术架构详解

项目概述

这是一个基于 LangGraph 和 Google Gemini 的全栈 AI 研究助手应用。该系统能够根据用户的问题自动生成搜索查询，利用 Google Search API 进行网络研究，通过反思机制识别知识空白，并迭代优化搜索直到能够提供带有引用来源的完整答案。

技术栈

后端技术栈

  • Python 3.11+ - 主要编程语言
  • LangGraph (v0.2.6+) - 构建智能代理的状态图框架
  • LangChain (v0.3.19+) - LLM 应用开发框架
  • Google Gemini API - 大语言模型服务
    • Gemini 2.0 Flash - 用于查询生成和网络搜索
    • Gemini 2.5 Flash (默认) - 用于推理和答案生成
  • FastAPI - Web 框架
  • LangGraph API - 提供 Agent 运行时环境
  • Redis - 发布订阅消息代理，支持实时流式输出
  • PostgreSQL - 存储助手、线程、运行状态和长期记忆

前端技术栈

  • React 19 - UI 框架
  • TypeScript - 类型安全的 JavaScript
  • Vite - 构建工具
  • Tailwind CSS - 样式框架
  • Shadcn UI - UI 组件库
  • @langchain/langgraph-sdk - LangGraph 客户端 SDK
  • React Router DOM - 路由管理

核心架构设计

系统架构流程图

graph TB
    A[用户输入问题] --> B[前端 React 应用]
    B --> C[LangGraph API]
    C --> D[Agent Graph 状态机]
    
    D --> E[生成查询节点]
    E --> F[并行执行多个搜索]
    F --> G[Web 研究节点]
    G --> H[反思节点]
    H --> I{知识是否充足?}
    
    I -->|否| J[生成后续查询]
    J --> F
    
    I -->|是| K[最终答案节点]
    K --> L[返回带引用的答案]
    L --> B
    
    G -.-> M[Google Search API]
    E -.-> N[Gemini 2.0 Flash]
    H -.-> O[Gemini 2.5 Flash]
    K -.-> O
Loading

Agent 工作流程详解

1. 查询生成阶段 (Query Generation)

def generate_query(state: OverallState, config: RunnableConfig) -> QueryGenerationState:
    # 使用 Gemini 2.0 Flash 生成初始搜索查询
    # 根据用户设置的努力级别生成 1-5 个查询
  • 输入: 用户的问题
  • 处理: 调用 Gemini 2.0 Flash 分析问题并生成多个优化的搜索查询
  • 输出: 搜索查询列表

2. 并行网络研究 (Web Research)

def web_research(state: WebSearchState, config: RunnableConfig) -> OverallState:
    # 使用 Google Search API 工具进行搜索
    # 解析搜索结果并提取引用信息
  • 并行执行: 使用 LangGraph 的 Send 机制并行执行多个搜索
  • 搜索工具: 集成 Google Search API 原生工具
  • 引用处理: 自动解析和缩短 URL，插入引用标记

3. 反思评估 (Reflection)

def reflection(state: OverallState, config: RunnableConfig) -> ReflectionState:
    # 分析当前收集的信息
    # 识别知识空白
    # 决定是否需要继续研究
  • 知识评估: 使用 Gemini 分析已收集信息的完整性
  • 空白识别: 自动识别缺失的关键信息
  • 查询优化: 生成更精准的后续查询

4. 迭代优化循环

  • 循环控制: 基于配置的最大循环次数（1-10 次）
  • 动态调整: 根据知识充足性自动决定是否继续
  • 效率优化: 避免重复搜索，聚焦知识空白

5. 答案生成 (Answer Finalization)

def finalize_answer(state: OverallState, config: RunnableConfig):
    # 综合所有研究结果
    # 生成结构化的答案
    # 添加引用来源
  • 内容综合: 整合所有研究结果
  • 引用管理: 自动替换短链接为原始 URL
  • 格式化输出: 生成带有正确引用的 Markdown 格式答案

状态管理机制

LangGraph 状态定义

class OverallState(TypedDict):
    messages: Annotated[list, add_messages]  # 消息历史
    search_query: Annotated[list, operator.add]  # 搜索查询列表
    web_research_result: Annotated[list, operator.add]  # 研究结果
    sources_gathered: Annotated[list, operator.add]  # 收集的来源
    initial_search_query_count: int  # 初始查询数量
    max_research_loops: int  # 最大研究循环次数
    research_loop_count: int  # 当前循环次数
    reasoning_model: str  # 推理模型选择

状态流转机制

  • 状态累积: 使用 operator.add 注解实现列表的自动累积
  • 消息管理: 使用 add_messages 函数处理消息历史
  • 并行状态: 支持多个并行分支的状态管理

前后端通信架构

WebSocket 实时流

const thread = useStream<{
    messages: Message[];
    initial_search_query_count: number;
    max_research_loops: number;
    reasoning_model: string;
}>({
    apiUrl: "http://localhost:2024",
    assistantId: "agent",
    onUpdateEvent: (event) => {
        // 处理实时事件流
    }
});

事件处理机制

  1. 查询生成事件: 显示正在生成的搜索查询
  2. 网络研究事件: 展示收集到的源数量和类型
  3. 反思事件: 显示是否需要继续研究
  4. 最终答案事件: 标记答案生成完成

配置管理

努力级别配置

switch (effort) {
    case "low":
        initial_search_query_count = 1;
        max_research_loops = 1;
        break;
    case "medium":
        initial_search_query_count = 3;
        max_research_loops = 3;
        break;
    case "high":
        initial_search_query_count = 5;
        max_research_loops = 10;
        break;
}

模型配置

  • 查询生成模型: gemini-2.0-flash-exp
  • 推理模型: 可选 gemini-2.0-flash-thinking-exp 或 gemini-1.5-flash

部署架构

Docker 容器化

services:
  gemini-fullstack:
    image: gemini-fullstack-langgraph
    environment:
      - GEMINI_API_KEY=${GEMINI_API_KEY}
      - LANGSMITH_API_KEY=${LANGSMITH_API_KEY}
    ports:
      - "8123:8123"

生产环境架构

  • 前端构建: 使用 Vite 生成优化的静态资源
  • 后端服务: FastAPI 同时服务 API 和静态文件
  • 数据持久化: PostgreSQL 存储会话状态
  • 消息队列: Redis 处理实时消息流

关键技术特性

1. 并行处理能力

  • 使用 LangGraph 的 Send 机制实现查询的并行执行
  • 提高搜索效率，减少等待时间

2. 智能引用管理

  • 自动解析搜索结果中的引用
  • 短链接优化减少 Token 使用
  • 最终答案中自动还原完整 URL

3. 动态推理能力

  • 基于上下文的知识空白识别
  • 自适应的查询优化策略
  • 支持多轮迭代直到获得满意答案

4. 流式响应

  • 实时展示 Agent 的思考过程
  • 用户可以看到每个步骤的执行状态
  • 支持中断和取消操作

安全性考虑

  1. API 密钥管理: 使用环境变量存储敏感信息
  2. 输入验证: 前端和后端双重验证
  3. 速率限制: 通过配置控制最大循环次数
  4. 错误处理: 完善的异常捕获和用户友好的错误提示

性能优化

  1. Token 优化: 使用短链接减少 Token 消耗
  2. 并行搜索: 多个查询并行执行
  3. 缓存机制: LangGraph 内置的状态缓存
  4. 按需加载: 前端资源的代码分割和懒加载

总结

这个项目展示了如何构建一个生产级的 AI 研究助手应用，通过 LangGraph 的状态管理和 Google Gemini 的强大能力，实现了一个能够自主进行网络研究并提供高质量答案的智能系统。整个架构设计注重可扩展性、性能和用户体验，是构建类似 AI 应用的优秀参考实现。

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment