init
This commit is contained in:
241
vw-agentic-rag/docs/topics/WEB_INTEGRATION_README.md
Normal file
241
vw-agentic-rag/docs/topics/WEB_INTEGRATION_README.md
Normal file
@@ -0,0 +1,241 @@
|
||||
# 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 提供了丰富的交互体验。整个架构具有良好的可扩展性和维护性，为进一步的功能开发和优化奠定了坚实基础。
|
||||
Reference in New Issue
Block a user