AI_POC/catonline_ai

Fork 0

Files

Ye Shijie db0e5965ec init

2025-09-26 17:15:54 +08:00

6.4 KiB

Raw Permalink Blame History

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 运行:

cd /home/fl/code/ai-solution/agentic-rag-4
./start_service.sh

2. 前端应用

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 自定义

定义了多个工具的可视化组件:

文档检索工具 (retrieval)
- 显示检索到的文档
- 相关度评分
- 来源信息
Web 搜索工具 (web_search)
- 搜索结果列表
- 链接和摘要
- 执行时间
代码执行工具 (python)
- 代码高亮显示
- stdout/stderr 输出
- 执行状态
URL 抓取工具 (fetch_url)
- 页面标题和内容
- 错误处理

流式集成

// 前端运行时配置
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. 多步推理

助手支持复杂的多步推理流程，每个步骤都会实时显示进度。

开发和调试

查看后端日志

tail -f service.log

检查 Data Stream 协议

curl -N -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"Hello"}],"session_id":"test"}' \
  http://localhost:8000/api/ai-sdk/chat

前端开发

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
工具调用和结果正确传输
会话状态正确管理
错误处理和异常流处理

后续优化建议

性能优化
- 实现消息缓存
- 添加请求去重
- 优化大文件传输
功能扩展
- 添加更多工具 UI
- 支持文件上传
- 实现消息编辑和分支
用户体验
- 添加加载状态指示
- 实现消息重试机制
- 支持键盘快捷键
部署和监控
- 添加性能监控
- 实现日志聚合
- 配置生产环境部署

总结

本项目成功实现了 assistant-ui 与 LangGraph + FastAPI 的无缝集成，提供了完整的流式 AI 对话体验。通过标准的 Data Stream Protocol，确保了前后端的协议兼容性，同时通过自定义 Tool UI 提供了丰富的交互体验。整个架构具有良好的可扩展性和维护性，为进一步的功能开发和优化奠定了坚实基础。

6.4 KiB Raw Permalink Blame History Unescape Escape