vitepress-template

Appearance

聊天服务API ​

**本文档引用的文件** - [[[[[bi_chat/src/routes/chat_v2.py]]]]](file/bi-chat/src/routes/chat-v2.py) - [[[[[bi_chat/src/routes/sessions.py]]]]](file/bi-chat/src/routes/sessions.py) - [[[[[bi_chat/src/services/session_service_async.py]]]]](file/bi-chat/src/services/session-service-async.py) - [[[[[bi_chat/src/services/message_storage.py]]]]](file/bi-chat/src/services/message-storage.py) - [[[[[bi_chat/src/db/models.py]]]]](file/bi-chat/src/db/models.py) - [[[[[bi_chat/src/agents/tools.py]]]]](file/bi-chat/src/agents/tools.py) - [[[[[bi_chat/src/routes/health.py]]]]](file/bi-chat/src/routes/health.py) - [[[[[bi_chat/main.py]]]]](file/bi-chat/main.py) - [[[[[bi_chat/src/core/config.py]]]]](file/bi-chat/src/core/config.py) - [[[[[bi-chat-web/src/app/api/v2/chat/message/route.ts]]]]](file/bi-chat-web/src/app/api/v2/chat/message/route.ts) - [[[[[bi-chat-web/src/hooks/use-chat.ts]]]]](file/bi-chat-web/src/hooks/use-chat.ts) - [[[[[bi-chat-web/src/context/ChatContext.tsx]]]]](file/bi-chat-web/src/context/chatcontext.tsx)

目录 ​

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构概览
  5. 详细组件分析
  6. 依赖分析
  7. 性能考虑
  8. 故障排除指南
  9. 结论
  10. 附录

简介 ​

本文件为 bi-chat 聊天服务的详细API文档，覆盖AI对话系统的HTTP API接口与WebSocket实时交互协议。文档重点包括：

  • 会话管理：创建、查询、删除、历史消息获取
  • 消息发送：基于多Agent协作的v2接口，支持OpenAI兼容的SSE流式响应
  • 智能体工具调用：实体检索、指标查询、SQL执行、知识图谱搜索、并行分析等
  • 对话状态管理：上下文保持、历史清洗、断头工具调用修复
  • 并发控制：会话清理、流式传输、队列管理
  • 集成方式与性能：健康检查、依赖服务监控、配置管理

项目结构 ​

bi-chat 服务采用FastAPI作为后端，Next.js作为前端，核心模块分布如下：

  • 后端（Python/FastAPI）：路由、服务层、数据库模型、Agent工具、配置与健康检查
  • 前端（Next.js）：聊天API代理、聊天上下文与Hook、SSE解析与渲染

图表来源

章节来源

核心组件 ​

  • 路由与API
    • v2聊天消息接口：统一OpenAI兼容SSE流，支持文本增量、工具调用状态与结果、可视化事件
    • 会话管理接口：创建、查询、删除、历史消息获取
    • 健康检查接口：PostgreSQL与Milvus连接状态检查
  • 服务层
    • 异步会话服务：创建/更新/查询会话，保存消息，格式化历史
    • 消息存储：聚合一次完整对话并持久化
  • 数据库模型
    • 会话表与消息历史表，支持级联删除与JSON内容存储
  • Agent工具集
    • 实体检索、指标查询、SQL执行、知识图谱搜索、并行分析、环境感知等
  • 前端集成
    • Next.js API代理（解决SSE重写问题）、SSE解析与渲染、本地状态管理

章节来源

架构概览 ​

后端通过FastAPI注册路由，v2聊天接口使用SSE流统一传输文本增量、工具调用、结果与可视化事件。服务层负责会话与消息的持久化，Agent工具集提供数据检索与计算能力。前端通过Next.js代理转发SSE流，解析事件并渲染组件。

图表来源

章节来源

详细组件分析 ​

v2聊天消息接口（/api/v2/chat/message） ​

  • 方法与路径
    • POST /api/v2/chat/message
  • 请求体参数
    • message: 用户消息内容（必填）
    • conversation_id: 会话ID（可选，未提供时自动生成UUID）
    • current_user: 当前用户信息（可选，包含user_id、username、dept_id等）
    • current_page_info: 当前页面信息（可选，用于环境感知）
    • stream: 是否启用流式传输（默认True）
  • 响应
    • text/event-stream（OpenAI兼容chunk + A2UI渲染事件）
    • 支持的事件类型：
      • choices[].delta.content：文本增量
      • render：A2UI组件渲染事件（ThinkingProcess、TaskPlanCard等）
      • visualization：可视化数据事件
      • done/pipeline_end：流程结束事件
      • error：错误事件
  • 上下文与历史
    • 从数据库获取最近N条消息并格式化
    • 断头工具调用修复：若assistant消息携带tool_calls但缺少对应tool消息，则剥离tool_calls
  • 执行流程
    • 构建Agent团队（会话管理器）
    • 创建事件队列与异步任务
    • MainPipeline执行并推送事件
    • 完成后存储最终消息（用户消息 + AI回复）

图表来源

章节来源

会话管理接口（/api/v1/sessions） ​

  • 创建会话
    • POST /api/v1/sessions
    • 请求体：current_user（可选）
    • 响应：conversation_id与状态
  • 查询会话列表
    • GET /api/v1/sessions?user_id=&limit=&status=
    • 响应：会话总数与会话数组（id、title、created_at、updated_at）
  • 删除会话
    • DELETE /api/v1/sessions/
    • 响应：状态（success/warning）
  • 获取会话历史消息
    • GET /api/v1/sessions/{conversation_id}/messages?limit=
    • 响应：按时间正序的前端消息数组（过滤tool_use、tool_result等中间消息）

图表来源

章节来源

健康检查接口（/api/v1/health/health） ​

  • GET /api/v1/health/health
  • 检查项：
    • PostgreSQL：解析连接URL并执行简单查询
    • Milvus：连接验证
  • 响应：整体状态与各服务详细状态

章节来源

Agent工具调用接口与结果处理 ​

  • 工具清单
    • search_entities(query, top_k)：实体表检索
    • search_indicators(query, top_k)：业务指标检索
    • execute_sql(sql)：StarRocks SQL执行（仅SELECT）
    • get_database_info()：数据库配置与SQL规范
    • env_perception(current_page_info)：页面环境感知
    • trigger_parallel_analysis(task_description, agents_to_use)：多专家并行分析
    • search_knowledge_graph(keyword, limit)：Neo4j知识图谱检索
    • create_promotion_plan(analysis_result, product_id)：投放计划模板创建
    • promotion_strategy(template_id, strategy_info)：推广执行方案链接
  • 结果格式
    • 统一返回ToolResponse，content为TextBlock或JSON字符串
    • 错误时返回包含status与message的对象

图表来源

章节来源

前端集成与SSE解析 ​

  • Next.js API代理
    • 解决SSR/rewrites对SSE流转发的问题，直接转发后端SSE响应
  • 前端Hook
    • 解析SSE事件：findCompleteJSONObjects
    • 处理事件类型：content增量、A2UI渲染、可视化、错误、完成
    • 乐观更新：先插入用户消息与AI占位消息，流式更新AI内容
  • 本地状态
    • ChatContext：消息、流状态、会话ID、API版本、任务事件、会话列表

图表来源

章节来源

依赖分析 ​

  • 应用生命周期与资源初始化
    • 初始化AgentScope、预加载共享模型与工具集
    • 定期清理超时会话（每5分钟）
  • 数据库与外部服务
    • PostgreSQL：会话与消息存储
    • Milvus：向量检索
    • Redis：缓存（配置项）
    • Neo4j：知识图谱检索（工具调用）
  • 配置管理
    • 环境变量驱动LLM、数据库、向量库、Redis、Neo4j等配置

图表来源

章节来源

性能考虑 ​

  • 流式传输
    • 使用SSE与异步队列，降低首字节延迟，提升用户体验
  • 历史清洗
    • 断头工具调用修复避免无效参数导致的错误
  • 数据截断
    • 工具结果超过阈值自动截断，避免大体积响应影响性能
  • 并发清理
    • 定期清理闲置会话，释放内存与资源
  • 数据库优化
    • 会话与消息表使用索引，查询限制与排序优化

[本节为通用性能指导，无需特定文件引用]

故障排除指南 ​

  • 常见错误与处理
    • 400 Bad Request：message为空
    • PostgreSQL/Milvus连接失败：健康检查接口返回unhealthy，检查服务状态与配置
    • SSE流中断：前端重试与断线重连，后端生成器优雅退出
    • 工具调用异常：工具返回status为error，前端展示错误状态
  • 日志与监控
    • 后端使用loguru记录关键事件与异常
    • 健康检查接口返回详细错误信息
  • 建议排查步骤
    • 确认后端服务健康状态
    • 检查数据库连接与表结构
    • 验证Agent工具可用性（向量库、图数据库）
    • 前端确认SSE代理与事件解析逻辑

章节来源

结论 ​

bi-chat 聊天服务通过统一的v2聊天接口与SSE流式传输，结合多Agent协作与丰富的工具集，提供了完整的AI对话体验。会话管理、历史清洗、工具调用与可视化事件均在后端统一处理，前端通过Next.js代理与Hook实现流畅的实时交互。健康检查与生命周期管理保障了服务稳定性与性能。

[本节为总结性内容，无需特定文件引用]

附录 ​

API规范速查 ​

  • v2聊天消息
    • 方法：POST
    • 路径：/api/v2/chat/message
    • 参数：message、conversation_id、current_user、current_page_info、stream
    • 响应：text/event-stream（OpenAI兼容chunk + A2UI事件）
  • 会话管理
    • 创建：POST /api/v1/sessions
    • 查询：GET /api/v1/sessions?user_id=&limit=&status=
    • 删除：DELETE /api/v1/sessions/
    • 历史：GET /api/v1/sessions/{conversation_id}/messages?limit=
  • 健康检查
    • GET /api/v1/health/health

章节来源