一个Agent，通吃所有数据！LangGraph实现从“文本”到“洞察”的终极进化！

在陆续发布了多篇聚焦单一功能点的介绍文章后，今天为大家带来一份全面、系统的整体说明。

朝阳区靓仔_James

264人浏览 · 2025-12-07 12:00:00

朝阳区靓仔_James · 2025-12-07 12:00:00 发布

一、项目概述

在陆续发布了多篇聚焦单一功能点的介绍文章后，今天为大家带来一份全面、系统的整体说明。

Sanic-Web 是一个基于 LangGraph 框架构建的企业级智能问答平台，深度融合大语言模型（LLM）与智能 Agent 编排技术，致力于为用户提供多场景、多模态的智能化问答与数据分析能力。平台以高性能异步 Web 框架 Sanic 作为服务基座，确保高并发下的响应速度与系统稳定性。

Sanic-Web 目前集成了四大核心问答能力：

智能问答：基于语义理解与上下文感知，实现自然语言到精准答案的端到端生成；
数据问答：支持对接结构化数据库，用户可通过自然语言直接查询、分析业务数据；
表格问答：针对 Excel、CSV 等表格文件，提供即传即问的交互式分析体验；
深度搜索：结合向量检索与 LLM 推理，实现对海量非结构化文档的语义级深度问答。

通过模块化设计与可扩展架构，Sanic-Web 不仅适用于企业知识库、客服助手、BI 分析等典型场景，是一个很好的二开项目。

二、核心技术栈

2.1 整体技术架构

技术分类	技术选型	用途说明
Web 框架	Sanic	高性能异步 Web 服务框架
AI 编排框架	LangGraph	Agent 工作流编排与状态管理
LLM 集成	LangChain	大语言模型调用与工具封装
向量检索	Neo4j	图数据库，用于表关系存储
数据处理	DuckDB	内存数据库，用于 Excel 数据查询
对象存储	MinIO	文件上传与管理
可观测性	Langfuse	LLM 应用链路追踪与监控
工具协议	MCP (Model Context Protocol)	统一工具调用接口

2.2 各模块技术栈对比

模块	核心框架	数据源	特殊技术	输出形式
智能问答	LangChain Agent	MCP 工具集	中间件（总结压缩、上下文编辑）	Markdown 流式输出
数据问答	LangGraph	MySQL/PostgreSQL	Neo4j 表关系、SQL 生成与验证	文本 + ECharts 图表
表格问答	LangGraph StateGraph	Excel/CSV 文件	DuckDB 内存查询、多文件管理	文本 + ECharts 图表
深度搜索	DeepAgents	网络搜索 API	多子智能体协作（规划师、研究员、分析师）	Markdown 研究报告

三、模块详解

3.1 智能问答（Common React Agent）

技术实现

智能问答模块基于 LangChain 的 ReAct Agent 模式，通过工具调用和推理循环实现复杂问题的解答。

核心技术点：

MCP 工具集成：通过 MultiServerMCPClient 接入外部工具服务
中间件机制：

SummarizationMiddleware：当对话超过 4000 tokens 时自动总结压缩
ContextEditingMiddleware：定期清理失败的工具调用记录

会话持久化：使用 InMemorySaver 实现跨请求的对话状态保持
流式输出：通过 stream_mode="messages" 实现逐 token 流式响应

关键代码架构：

源码位置: agent/common_react_agent.py

# 创建 Agentagent = create_agent(    model=self.llm,    tools=tools,  # MCP 工具    system_prompt=system_message.content,    checkpointer=self.checkpointer,  # 会话持久化    middleware=[        log_before_model,        SummarizationMiddleware(self.llm, max_tokens_before_summary=4000),        ContextEditingMiddleware(edits=[ClearToolUsesEdit(trigger=10000)]),    ],)# 流式执行asyncfor message_chunk, metadata in agent.astream(    input={"messages": [HumanMessage(content=query)]},    config={"configurable": {"thread_id": session_id}},    stream_mode="messages",):    # 处理工具调用和内容输出

适用场景：

通用知识问答
需要调用外部工具的复杂任务（如查询数据库、调用 API）
多轮对话场景

3.2 数据问答（Text2SQL Agent）

技术实现

数据问答模块将自然语言转换为 SQL 查询，实现对结构化数据库的智能问答。

核心技术点：

源码位置: agent/text2sql/text2_sql_agent.py

LangGraph 状态图：定义了完整的 Text2SQL 工作流

schema_inspector：数据库表结构检索
table_relationship：从 Neo4j 获取表关系
sql_generator：生成 SQL 语句
sql_executor：执行 SQL 并返回结果
summarize：总结查询结果
data_render：生成可视化图表

Neo4j 表关系管理：通过图数据库存储表之间的关联关系，提升多表查询准确性
思考过程可视化：通过 HTML <details> 标签展示每个步骤的执行过程
图表渲染：支持生成 ECharts 配置数据，前端直接渲染

工作流程：

用户问题 → 表结构检索 → 表关系查询 → SQL生成 → SQL执行 → 结果总结 → 图表渲染

关键状态定义：

class AgentState(TypedDict):    user_query: str              # 用户问题    db_info: Dict[str, Any]      # 数据库表结构    table_relationship: Dict     # 表关系    generated_sql: str           # 生成的SQL    execution_result: ExecutionResult  # 执行结果    report_summary: str          # 结果总结    apache_chart_data: Dict      # 图表数据

适用场景：

业务数据查询（销售报表、用户统计等）
BI 报表生成
数据探索与分析

3.3 表格问答（Excel Agent）

技术实现

表格问答模块专门处理 Excel/CSV 文件的智能分析，无需导入数据库即可实现复杂查询。

核心技术点：

源码位置: agent/excel/excel_agent.py

DuckDB 内存数据库：

将 Excel 文件加载到内存数据库
支持标准 SQL 查询
支持多文件、多 Sheet 管理

会话级数据隔离：每个 chat_id 对应独立的 DuckDB 实例
文件元数据管理：

file_metadata：文件级信息（文件名、上传时间、Sheet 数量）
sheet_metadata：Sheet 级信息（Sheet 名称、行列数）
catalog_info：Catalog 映射关系

多轮对话支持：上传一次文件后可进行多次问答

工作流程：

文件上传 → Excel解析 → 加载到DuckDB → SQL生成 → 查询执行 → 结果总结 → 图表渲染

DuckDB 管理器设计：

class ChatDuckDBManager:    """管理多个 chat_id 的 DuckDB 连接"""        def get_or_create_manager(self, chat_id: str) -> DuckDBManager:        """获取或创建指定 chat_id 的 DuckDB 管理器"""            def close_manager(self, chat_id: str) -> bool:        """关闭并清理指定 chat_id 的 DuckDB 连接"""

适用场景：

Excel 数据分析
临时数据查询（无需建表）
多文件数据对比分析

3.4 深度搜索（Deep Research Agent）

技术实现

深度搜索模块基于 DeepAgents 框架，通过多智能体协作完成复杂的研究任务。

核心技术点：

源码位置: agent/deepagent/deep_research_agent.py

三智能体协作架构：

Planner（规划师）：分解用户问题，制定研究计划
Researcher（研究员）：执行网络搜索，收集信息
Analyst（分析师）：整合信息，生成研究报告

任务规划可视化：通过 write_todos 工具展示任务分解结果
搜索过程追踪：实时显示每次搜索的关键词和进度
Markdown 报告生成：输出结构化的研究报告

智能体配置示例：

{  "planner": {    "name": "规划师",    "role": "任务分解与规划",    "description": "将复杂问题分解为可执行的子任务"  },"researcher": {    "name": "研究员",    "role": "信息收集",    "description": "通过搜索工具收集相关信息"  },"analyst": {    "name": "分析师",    "role": "信息整合与报告生成",    "description": "分析数据并生成结构化报告"  }}

工作流程：

用户问题 → 任务规划 → 并行搜索 → 信息整合 → 报告生成

适用场景：

行业研究报告
竞品分析
技术调研
深度问题解答

unsetunset四、统一技术特性unsetunset

4.1 流式响应机制

所有模块均采用 SSE（Server-Sent Events） 实现流式输出：

async def _send_response(response, content: str, message_type: str = "continue"):    formatted_message = {        "data": {            "messageType": message_type,  # continue/info/error/end            "content": content,        },        "dataType": "t02",  # 数据类型标识    }    await response.write("data:" + json.dumps(formatted_message, ensure_ascii=False) + "\n\n")

消息类型：

messageType	说明	使用场景
`continue`	持续输出内容	正常的流式文本输出
`info`	提示信息	步骤开始、工具调用等
`error`	错误信息	异常处理
`end`	流结束标识	任务完成或取消

4.2 可观测性设计

集成 Langfuse 实现全链路追踪：

if self.ENABLE_TRACING:    langfuse = get_client()    with langfuse.start_as_current_observation(        input=query,        as_type="agent",        name="数据问答",    ) as rootspan:        rootspan.update_trace(session_id=session_id, user_id=user_id)        # 执行 Agent

追踪维度：

每次问答的完整执行链路
LLM 调用次数与 Token 消耗
工具调用详情
执行耗时分析

4.3 任务取消机制

支持用户主动取消长时间运行的任务：

async def cancel_task(self, task_id: str) -> bool:    """取消指定的任务"""    if task_id in self.running_tasks:        self.running_tasks[task_id]["cancelled"] = True        return True    return False

在流式输出过程中定期检查取消标志：

if self.running_tasks[task_id]["cancelled"]:    await response.write(self._create_response("\n> 这条消息已停止", "info"))    await response.write(self._create_response("", "end"))    break

unsetunset五、架构优势unsetunset

5.1 技术优势

优势点	说明
异步高性能	Sanic 框架 + asyncio 实现高并发处理
模块化设计	四大模块独立解耦，易于扩展
流式体验	SSE 实时输出，用户体验流畅
可观测性	Langfuse 全链路追踪，便于调试优化
会话管理	支持多轮对话，上下文自动压缩

5.2 业务优势

优势点	说明
多场景覆盖	通用问答、数据查询、文件分析、深度研究
零 SQL 门槛	自然语言直接查询数据库和 Excel
智能可视化	自动生成图表，无需手动配置
企业级特性	用户认证、任务取消、会话隔离

六、总结

Sanic-Web 项目通过整合 LangChain、LangGraph、DeepAgents 等先进的 AI 编排框架，构建了一个功能完善、技术先进的智能问答平台。项目的核心价值在于：

降低数据分析门槛：通过自然语言交互，让非技术人员也能轻松查询数据
提升工作效率：自动化的 SQL 生成、图表渲染、报告生成
技术架构先进：异步流式、状态管理、多智能体协作等前沿技术的综合应用
可扩展性强：模块化设计，易于接入新的数据源和工具

无论是企业内部的数据分析需求，还是面向用户的智能助手服务，Sanic-Web 都提供了一套完整、可靠的技术解决方案。

如何学习大模型 AI ？

由于新岗位的生产效率，要优于被取代岗位的生产效率，所以实际上整个社会的生产效率是提升的。

但是具体到个人，只能说是：

“最先掌握AI的人，将会比较晚掌握AI的人有竞争优势”。

这句话，放在计算机、互联网、移动互联网的开局时期，都是一样的道理。

我在一线互联网企业工作十余年里，指导过不少同行后辈。帮助很多人得到了学习和成长。

我意识到有很多经验和知识值得分享给大家，也可以通过我们的能力和经验解答大家在人工智能学习中的很多困惑，所以在工作繁忙的情况下还是坚持各种整理和分享。但苦于知识传播途径有限，很多互联网行业朋友无法获得正确的资料得到学习提升，故此将并将重要的AI大模型资料包括AI大模型入门学习思维导图、精品AI大模型学习书籍手册、视频教程、实战学习等录播视频免费分享出来。

在这里插入图片描述