242 lines
6.4 KiB
Markdown
242 lines
6.4 KiB
Markdown
|
# Assistant-UI + LangGraph + FastAPI Web Chatbot
|
|||
|
|
|
|||
|
|
本项目成功集成了 assistant-ui 前端框架与基于 LangGraph + FastAPI 的后端服务，实现了流式 AI 对话界面，支持多步推理和工具调用。
|
|||
|
|
|
|||
|
|
## 项目架构
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
|
|||
|
|
│ React Web │ │ Next.js API │ │ FastAPI+ │
|
|||
|
|
│ (assistant-ui) │◄──►│ Route │◄──►│ LangGraph │
|
|||
|
|
│ │ │ │ │ Backend │
|
|||
|
|
└─────────────────┘ └──────────────────┘ └─────────────────┘
|
|||
|
|
│ │ │
|
|||
|
|
▼ ▼ ▼
|
|||
|
|
用户界面 API 代理/转发 AI Agent + 工具
|
|||
|
|
- Thread 组件 - /api/chat 路由 - 检索工具
|
|||
|
|
- Tool UI 显示 - Data Stream 协议 - 代码分析
|
|||
|
|
- 流式消息渲染 - 请求转发处理 - 多步推理
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 核心特性
|
|||
|
|
|
|||
|
|
### 1. 前端 (assistant-ui)
|
|||
|
|
|
|||
|
|
- **框架**: Next.js 15 + React 19 + TypeScript + Tailwind CSS v3
|
|||
|
|
- **UI 库**: @assistant-ui/react, @assistant-ui/react-ui
|
|||
|
|
- **协议**: Data Stream Protocol (SSE 流式通信)
|
|||
|
|
- **组件**:
|
|||
|
|
- `Thread`: 主对话界面
|
|||
|
|
- 自定义 Tool UI: 文档检索、Web搜索、代码执行等
|
|||
|
|
- 响应式设计，支持明暗主题
|
|||
|
|
|
|||
|
|
### 2. 中间层 (Next.js API)
|
|||
|
|
|
|||
|
|
- **路由**: `/api/chat` - 转发请求到 FastAPI 后端
|
|||
|
|
- **协议转换**: 确保 Data Stream Protocol 兼容性
|
|||
|
|
- **headers**: 设置正确的 `x-vercel-ai-data-stream: v1` 头
|
|||
|
|
|
|||
|
|
### 3. 后端 (FastAPI + LangGraph)
|
|||
|
|
|
|||
|
|
- **框架**: FastAPI + LangGraph
|
|||
|
|
- **协议**: AI SDK Data Stream Protocol
|
|||
|
|
- **功能**:
|
|||
|
|
- 多步 AI 推理
|
|||
|
|
- 工具调用 (检索、搜索、代码分析等)
|
|||
|
|
- 会话状态管理
|
|||
|
|
- 流式响应
|
|||
|
|
|
|||
|
|
## 安装和配置
|
|||
|
|
|
|||
|
|
### 1. 后端服务
|
|||
|
|
|
|||
|
|
确保后端服务在端口 8000 运行:
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
cd /home/fl/code/ai-solution/agentic-rag-4
|
|||
|
|
./start_service.sh
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 2. 前端应用
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
cd web
|
|||
|
|
pnpm install
|
|||
|
|
pnpm dev
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
访问: http://localhost:3000
|
|||
|
|
|
|||
|
|
## 技术实现细节
|
|||
|
|
|
|||
|
|
### Data Stream Protocol
|
|||
|
|
|
|||
|
|
实现了 AI SDK 标准的 Data Stream Protocol:
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
类型格式: TYPE_ID:CONTENT_JSON\n
|
|||
|
|
|
|||
|
|
支持的事件类型:
|
|||
|
|
- 0: 文本流 (text)
|
|||
|
|
- 2: 数据 (data)
|
|||
|
|
- 3: 错误 (error)
|
|||
|
|
- 9: 工具调用 (tool call)
|
|||
|
|
- a: 工具结果 (tool result)
|
|||
|
|
- d: 消息完成 (finish message)
|
|||
|
|
- e: 步骤完成 (finish step)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 工具 UI 自定义
|
|||
|
|
|
|||
|
|
定义了多个工具的可视化组件:
|
|||
|
|
|
|||
|
|
1. **文档检索工具** (`retrieval`)
|
|||
|
|
- 显示检索到的文档
|
|||
|
|
- 相关度评分
|
|||
|
|
- 来源信息
|
|||
|
|
|
|||
|
|
2. **Web 搜索工具** (`web_search`)
|
|||
|
|
- 搜索结果列表
|
|||
|
|
- 链接和摘要
|
|||
|
|
- 执行时间
|
|||
|
|
|
|||
|
|
3. **代码执行工具** (`python`)
|
|||
|
|
- 代码高亮显示
|
|||
|
|
- stdout/stderr 输出
|
|||
|
|
- 执行状态
|
|||
|
|
|
|||
|
|
4. **URL 抓取工具** (`fetch_url`)
|
|||
|
|
- 页面标题和内容
|
|||
|
|
- 错误处理
|
|||
|
|
|
|||
|
|
### 流式集成
|
|||
|
|
|
|||
|
|
```typescript
|
|||
|
|
// 前端运行时配置
|
|||
|
|
const runtime = useDataStreamRuntime({
|
|||
|
|
api: "/api/chat",
|
|||
|
|
});
|
|||
|
|
|
|||
|
|
// 后端事件转换
|
|||
|
|
async function stream_ai_sdk_compatible(internal_stream) {
|
|||
|
|
for await (const event of internal_stream) {
|
|||
|
|
const converted = adapter.convert_event(event);
|
|||
|
|
if (converted) yield converted;
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 文件结构
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
web/
|
|||
|
|
├── src/
|
|||
|
|
│ ├── app/
|
|||
|
|
│ │ ├── page.tsx # 主聊天界面
|
|||
|
|
│ │ ├── globals.css # 全局样式 + assistant-ui
|
|||
|
|
│ │ ├── layout.tsx # 布局配置
|
|||
|
|
│ │ └── api/
|
|||
|
|
│ │ └── chat/
|
|||
|
|
│ │ └── route.ts # API 路由代理
|
|||
|
|
│ └── ...
|
|||
|
|
├── tailwind.config.ts # Tailwind + assistant-ui 插件
|
|||
|
|
├── package.json # 依赖配置
|
|||
|
|
└── ...
|
|||
|
|
|
|||
|
|
service/
|
|||
|
|
├── ai_sdk_adapter.py # Data Stream Protocol 适配器
|
|||
|
|
├── ai_sdk_chat.py # AI SDK 兼容的聊天端点
|
|||
|
|
├── main.py # FastAPI 应用入口
|
|||
|
|
└── ...
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 使用指南
|
|||
|
|
|
|||
|
|
### 1. 启动对话
|
|||
|
|
|
|||
|
|
打开 http://localhost:3000，在输入框中输入问题，例如:
|
|||
|
|
- "帮我搜索关于 Python 异步编程的资料"
|
|||
|
|
- "分析一下这段代码的性能问题"
|
|||
|
|
- "检索关于机器学习的文档"
|
|||
|
|
|
|||
|
|
### 2. 观察工具调用
|
|||
|
|
|
|||
|
|
AI 助手会根据问题自动调用相应工具:
|
|||
|
|
- 文档检索会显示相关文档卡片
|
|||
|
|
- Web 搜索会显示搜索结果列表
|
|||
|
|
- 代码分析会显示执行过程和结果
|
|||
|
|
|
|||
|
|
### 3. 多步推理
|
|||
|
|
|
|||
|
|
助手支持复杂的多步推理流程，每个步骤都会实时显示进度。
|
|||
|
|
|
|||
|
|
## 开发和调试
|
|||
|
|
|
|||
|
|
### 查看后端日志
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
tail -f service.log
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 检查 Data Stream 协议
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
curl -N -H "Content-Type: application/json" \
|
|||
|
|
-d '{"messages":[{"role":"user","content":"Hello"}],"session_id":"test"}' \
|
|||
|
|
http://localhost:8000/api/ai-sdk/chat
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 前端开发
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
cd web
|
|||
|
|
pnpm dev
|
|||
|
|
# 访问 http://localhost:3000
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 协议兼容性确认
|
|||
|
|
|
|||
|
|
✅ **Data Stream Protocol 兼容**
|
|||
|
|
- 正确的事件格式: `TYPE_ID:JSON\n`
|
|||
|
|
- 必需的 HTTP 头: `x-vercel-ai-data-stream: v1`
|
|||
|
|
- 支持工具调用流式渲染
|
|||
|
|
- 支持多步推理可视化
|
|||
|
|
|
|||
|
|
✅ **assistant-ui 集成**
|
|||
|
|
- useDataStreamRuntime 正确配置
|
|||
|
|
- Thread 组件正常渲染
|
|||
|
|
- 自定义 Tool UI 正常显示
|
|||
|
|
- 样式和主题配置正确
|
|||
|
|
|
|||
|
|
✅ **LangGraph + FastAPI 后端**
|
|||
|
|
- 事件正确转换为 Data Stream Protocol
|
|||
|
|
- 工具调用和结果正确传输
|
|||
|
|
- 会话状态正确管理
|
|||
|
|
- 错误处理和异常流处理
|
|||
|
|
|
|||
|
|
## 后续优化建议
|
|||
|
|
|
|||
|
|
1. **性能优化**
|
|||
|
|
- 实现消息缓存
|
|||
|
|
- 添加请求去重
|
|||
|
|
- 优化大文件传输
|
|||
|
|
|
|||
|
|
2. **功能扩展**
|
|||
|
|
- 添加更多工具 UI
|
|||
|
|
- 支持文件上传
|
|||
|
|
- 实现消息编辑和分支
|
|||
|
|
|
|||
|
|
3. **用户体验**
|
|||
|
|
- 添加加载状态指示
|
|||
|
|
- 实现消息重试机制
|
|||
|
|
- 支持键盘快捷键
|
|||
|
|
|
|||
|
|
4. **部署和监控**
|
|||
|
|
- 添加性能监控
|
|||
|
|
- 实现日志聚合
|
|||
|
|
- 配置生产环境部署
|
|||
|
|
|
|||
|
|
## 总结
|
|||
|
|
|
|||
|
|
本项目成功实现了 assistant-ui 与 LangGraph + FastAPI 的无缝集成，提供了完整的流式 AI 对话体验。通过标准的 Data Stream Protocol，确保了前后端的协议兼容性，同时通过自定义 Tool UI 提供了丰富的交互体验。整个架构具有良好的可扩展性和维护性，为进一步的功能开发和优化奠定了坚实基础。
|