TableGPT Agent：专为分析复杂表格数据设计的智能工具

综合介绍

TableGPT Agent 是一个基于 GitHub 开源项目的智能工具，专为处理和分析表格数据设计。它依托 TableGPT2 大语言模型，利用自然语言交互的方式，让用户能够轻松查询、操作和理解复杂的表格内容。无论是从 CSV 文件中提取数据、生成可视化图表，还是回答基于表格的具体问题，这个工具都能高效完成任务。它由 tablegpt 团队开发，构建在 Langgraph 库之上，支持多样化的表格相关应用场景，非常适合需要数据分析但不擅长编程的用户。项目采用 Apache 2.0 许可证，鼓励开发者参与贡献，目前在 GitHub 上已有活跃社区支持。

功能列表

• 表格数据读取与处理: 支持从本地上传的 CSV、Excel 文件或数据库中读取表格数据，并进行结构化处理。
• 自然语言查询: 用户可以用日常语言提问，例如“有多少男性幸存？”或“销售额最高的产品是什么？”。
• 代码自动生成: 根据用户需求生成 Python 代码，例如筛选数据、计算统计值或绘制图表。
• 数据可视化支持: 配合工具生成折线图、柱状图等可视化结果，直观展示数据分析结论。
• 复杂表格任务支持: 处理多层表格结构或不规则数据，提供准确的分析结果。
• 会话记忆功能: 通过 checkpointer 和 session_id，保留分析上下文，支持连续多轮对话。
• 开源扩展性: 提供丰富的 API 和文档，开发者可自定义功能或集成到其他项目。

使用帮助

安装流程

TableGPT Agent 是一个基于 Python 的工具，需要一定的环境配置才能运行。以下是详细的安装步骤：

1. 环境准备

• 安装 Python: 确保你的电脑安装了 Python 3.8 或更高版本，可从 Python 官网 下载。
• 安装 Git: 用于克隆 GitHub 仓库，Windows/Mac 用户可从 Git 官网 下载。
• 安装 vLLM: TableGPT Agent 推荐使用 vLLM 部署 TableGPT2 模型，确保高效推理。运行以下命令：

  pip install vllm==0.5.5 --extra-index-url https://download.pytorch.org/whl/cu124

（根据你的 CUDA 版本调整 cu124，如无 GPU 可跳过此步，但需手动部署模型）。

2. 克隆仓库

打开终端（Windows 可使用 CMD 或 PowerShell，Mac/Linux 使用 Terminal），运行：

git clone https://github.com/tablegpt/tablegpt-agent.git
cd tablegpt-agent

3. 安装依赖

在项目目录下，安装所需 Python 库：

pip install -r requirements.txt

如果需要本地运行完整功能，安装额外依赖：

pip install ".[local]"

4. 部署 TableGPT2 模型

TableGPT Agent 需要 TableGPT2 模型支持。先从 Hugging Face 下载模型（如 TableGPT2-7B），然后使用 vLLM 启动服务：

python -m vllm.entrypoints.openai.api_server --served-model-name TableGPT2-7B --model path/to/weights

服务启动后，默认监听 http://localhost:8000，记下此 URL。

5. 配置代理

编辑代码或配置文件，将 LLM 的 API 地址指向你部署的 vLLM 服务，例如：

llm = ChatOpenAI(openai_api_base="http://localhost:8000/v1", openai_api_key="whatever", model_name="TableGPT2-7B")

使用方法

安装完成后，TableGPT Agent 即可运行。以下是主要功能的详细操作流程：

功能 1: 读取表格数据

1. 准备数据文件: 将 CSV 或 Excel 文件放在本地目录（如 gpt_workspace 文件夹）。
2. 启动代理: 在 Python 环境中运行以下代码，初始化代理：

   from langchain_openai import ChatOpenAI
   from langgraph.checkpoint.memory import MemorySaver
   from pybox import LocalPyBoxManager
   from tablegpt.agent import create_tablegpt_graph
   llm = ChatOpenAI(openai_api_base="http://localhost:8000/v1", openai_api_key="whatever", model_name="TableGPT2-7B")
   pybox_manager = LocalPyBoxManager()
   checkpointer = MemorySaver()
   agent = create_tablegpt_graph(llm=llm, pybox_manager=pybox_manager, checkpointer=checkpointer, session_id="my-session")
   

3. 上传文件: 使用以下代码上传文件并让代理读取：

   from datetime import date
   from tablegpt.agent.file_reading import Stage
   from langchain_core.messages import HumanMessage
   attachment_msg = HumanMessage(content="请读取文件 data.csv", additional_kwargs={"file_path": "path/to/data.csv"})
   response = await agent.ainvoke(
   input={"entry_message": attachment_msg, "processing_stage": Stage.UPLOADED, "messages": [attachment_msg], "date": date.today()},
   config={"configurable": {"thread_id": "my-thread"}}
   )
   print(response["messages"])
   

   代理会返回确认信息，表示文件已读取。

功能 2: 自然语言查询

1. 提问: 在同一会话中，继续输入问题：

   human_message = HumanMessage(content="有多少行数据？")
   response = await agent.ainvoke(
   input={"messages": [human_message], "date": date.today()},
   config={"configurable": {"thread_id": "my-thread"}}
   )
   print(response["messages"])
   

2. 结果: 代理会返回答案，如“数据共有 100 行”。

功能 3: 生成可视化图表

1. 请求图表: 输入类似“绘制销售额的柱状图”：

   human_message = HumanMessage(content="绘制销售额的柱状图")
   async for event in agent.astream_events(
   input={"messages": [human_message], "date": date.today()},
   config={"configurable": {"thread_id": "my-thread"}},
   version="v2"
   ):
   if event["event"] == "on_chat_model_end":
   print(event["data"]["output"])
   

2. 输出: 代理会生成 Python 代码并返回图表结果（需配合 matplotlib 等库本地运行）。

功能 4: 复杂任务处理

对于多层表格或不规则数据，直接提问如“统计每个部门的平均年龄”，代理会自动解析并生成结果。

注意事项

• 环境依赖: 确保网络畅通，vLLM 服务正常运行。
• 文件路径: 上传文件时需提供正确路径。
• 会话管理: 使用相同的 session_id 和 thread_id 保持上下文连续性。

通过以上步骤，你可以轻松上手 TableGPT Agent，完成从数据读取到分析的全流程！