使用说明

数据科学家助手代理

生产级多智能体人工智能系统 用于会话数据分析——3个专用MCP服务器、29个工具、LangGraph编排和完整的LLM可观察性。

概述

一个由人工智能驱动的数据科学助手，允许用户上传CSV文件，用自然语言提问，并通过聊天界面接收分析、可视化和训练的ML模型。用a建造 微服务架构 使用 模型上下文协议（MCP） 用于工具编排和 LangGraph 用于代理推理。

关键指标：

10集装箱服务 通过Docker Compose编排
3台MCP服务器 和 29工具 用于可视化、代码执行和ML管道
端到端LLM可观测性 通过Langfuse（追踪、成本、延迟）
PII合规性 通过微软Presidio+spaCy NER

技术栈

层	技术
前端	React 18、TypeScript、Vite、顺风CSS、Vega嵌入
代理	Python、FastAPI、LangGraph、OpenAI GPT-4
MCP服务器	Python、FastMCP、Vega Lite、Pandas、Scikit学习
可观测性	Langfuse，PostgreSQL
安全	微软Presidio，spaCy NER
基础设施	Docker Compose、Nginx、WebSocket

特性

现代React用户界面 具有深色主题、聊天界面和会话管理
Vega嵌入可视化 -图表直接在聊天中呈现
Langfuse集成 -所有LLM调用和工具使用的完全可观察性
PII保护 -基于Microsoft Presidio的检测和编辑
三台MCP服务器:
- Vega Lite -创建漂亮的数据可视化
- Python执行器 -沙盒Python代码执行
- 管道设计器 -ETL操作和ML模型训练
对话记忆 -带上下文的多回合对话
CSV分析 -直接上传和分析数据文件

建筑

┌─────────────────────────────────────────────────────────────────┐
│                        Docker Compose                            │
├─────────────────────────────────────────────────────────────────┤
│  ┌──────────────┐                                               │
│  │   Frontend   │──────────┐                                    │
│  │   (React)    │          │                                    │
│  │   :3000      │          ▼                                    │
│  └──────────────┘   ┌─────────────────────────────────────┐    │
│                     │          Agent Service               │    │
│                     │  ┌─────────┐  ┌─────────┐  ┌──────┐ │    │
│                     │  │LangGraph│  │Langfuse │  │ PII  │ │    │
│                     │  │ Agent   │──│Callback │──│Guard │ │    │
│                     │  └─────────┘  └─────────┘  └──────┘ │    │
│                     │       │         :8000                │    │
│                     └───────┼──────────────────────────────┘    │
│                             │ MCP Client                        │
│    ┌────────────────────────┼────────────────────────┐         │
│    ▼                        ▼                        ▼         │
│  ┌──────────────┐    ┌──────────────┐    ┌───────────────────┐ │
│  │  MCP Server  │    │  MCP Server  │    │    MCP Server     │ │
│  │  Vega-Lite   │    │   Python     │    │     Pipeline      │ │
│  │    :8001     │    │    :8002     │    │      :8003        │ │
│  └──────────────┘    └──────────────┘    └───────────────────┘ │
│                                                                 │
│  ┌──────────────┐    ┌──────────────┐                          │
│  │   Langfuse   │────│  PostgreSQL  │                          │
│  │    :3001     │    │  (internal)  │                          │
│  └──────────────┘    └──────────────┘                          │
└─────────────────────────────────────────────────────────────────┘

快速开始

先决条件

Docker和Docker Compose
OpenAI API密钥

1.克隆和配置

cd /path/to/project
cp .env.example .env

编辑 .env 并添加您的OpenAI API密钥：

OPENAI_API_KEY=sk-your-actual-api-key

2.开始一切

./start.sh

或手动：

docker compose up --build -d

3.访问应用程序

服务	URL	描述
前端	http://localhost:3000	主聊天界面
API	http://localhost:8000	REST API和WebSocket
浪伏	http://localhost:3001	LLM可观察性仪表板

设置廊坊

首选http://localhost:3001
创建一个新账户
创建一个新项目
前往设置→ API密钥→ 创建新密钥

将钥匙复制到您的 .env 文件：

LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_PUBLIC_KEY=pk-lf-...

重新启动代理： docker compose restart agent

用法示例

分析CSV文件

点击📎 附加CSV文件的按钮
类型：“分析此数据集并向我显示关键统计数据”
代理将加载、分析和可视化您的数据

创建可视化

问代理人：

“创建按地区显示销售额的条形图”
“绘制年龄与工资的散点图”
“显示价格分布的直方图”

图表直接在聊天中使用Vega Lite渲染！

训练ML模型

Train a random forest model to predict salary using
age, department, and years_experience as features.
Then evaluate the model and show feature importance.

执行Python代码

Use Python to calculate the correlation matrix
for all numeric columns and identify the strongest
correlations.

API 参考

聊天

curl -X POST http://localhost:8000/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello!", "session_id": "my-session"}'

分析文件

curl -X POST http://localhost:8000/analyze \
  -F "file=@data.csv" \
  -F "prompt=Analyze this data"

检查PII

curl -X POST http://localhost:8000/check-pii \
  -H "Content-Type: application/json" \
  -d '{"text": "Contact john@example.com"}'

Websocket聊天

连接到 ws://localhost:8000/ws/{session_id} 用于实时聊天。

MCP服务器工具

Vega Lite服务器

工具	说明
`save_data`	存储数据以进行可视化
`create_chart`	用简单的界面创建图表
`visualize_data`	使用完整的Vega Lite规范创建图表
`list_datasets`	列出存储的数据集

Python执行器

工具	说明
`execute_python`	使用数据科学库运行Python代码
`load_csv_to_namespace`	将CSV加载到执行命名空间中
`get_variable`	从命名空间获取变量
`list_variables`	列出所有变量

管道设计器

工具	说明
`load_csv`	将CSV加载到DataFrame中
`describe_data`	获取统计摘要
`filter_data`	按条件筛选行
`aggregate_data`	分组和汇总
`train_model`	训练ML模型
`predict`	做出预测
`evaluate_model`	评估模型性能

项目结构

├── frontend/              # React application
│   ├── src/
│   │   ├── components/   # React components
│   │   ├── hooks/        # Custom hooks
│   │   ├── services/     # API services
│   │   └── types/        # TypeScript types
│   ├── Dockerfile
│   └── nginx.conf
│
├── agent/                 # Python agent service
│   ├── app/
│   │   ├── main.py       # FastAPI application
│   │   ├── agent.py      # LangGraph agent
│   │   ├── pii_handler.py # Presidio PII
│   │   └── mcp_client.py # MCP connections
│   └── Dockerfile
│
├── mcp-vegalite/         # Vega-Lite MCP server
├── mcp-python-executor/  # Python executor MCP
├── mcp-pipeline/         # Pipeline MCP server
│
├── docker-compose.yml    # Service orchestration
├── start.sh             # Startup script
└── .env.example         # Environment template

发展

不使用Docker运行

# Install frontend dependencies
cd frontend && npm install && npm run dev

# Install agent dependencies
cd agent && pip install -r requirements.txt
python -m spacy download en_core_web_sm
uvicorn app.main:app --reload

# Run MCP servers
python mcp-vegalite/server.py
python mcp-python-executor/server.py
python mcp-pipeline/server.py

运行测试

# Unit tests
cd agent && pytest tests/ -v

# Integration tests (with Docker running)
pytest tests/test_integration.py -v

配置

变量	描述	默认值
`OPENAI_API_KEY`	OpenAI API密钥	必需
`OPENAI_MODEL`	要使用的模型	`gpt-4`
`LANGFUSE_SECRET_KEY`	Langfuse机密	可选
`LANGFUSE_PUBLIC_KEY`	Langfuse公钥	可选
`LANGFUSE_HOST`	Langfuse URL	`http://langfuse:3000`

故障排除

服务无法启动

docker compose logs -f          # View all logs
docker compose logs agent       # View agent logs
docker compose restart agent    # Restart agent

廊坊未连接

确保Langfuse健康： docker compose ps
在Langfuse UI中创建API键
更新 .env 带钥匙
重新启动： docker compose restart agent

MCP工具不可用

docker compose logs mcp-vegalite
docker compose logs mcp-python-executor
docker compose logs mcp-pipeline

安全

PII保护：在处理之前，扫描所有用户消息并编辑PII
沙盒执行：Python代码在隔离环境中运行
无持久存储：对话数据仅存储在浏览器本地存储中

许可证

MIT许可证