vitepress-template

Appearance

bi-chat AI对话系统 ​

**本文档引用的文件** - [[bi_chat/main.py]](../file/bi-chat/bi-chat/main.py) - [[bi_chat/src/core/config.py]](../file/bi-chat/bi-chat/src/core/config.py) - [[bi_chat/src/agents/conversation_manager.py]](../file/bi-chat/bi-chat/src/agents/conversation-manager.py) - [[bi_chat/src/agents/bi_agent.py]](../file/bi-chat/bi-chat/src/agents/bi-agent.py) - [[bi_chat/src/routes/chat.py]](../file/bi-chat/bi-chat/src/routes/chat.py) - [[bi_chat/src/agents/tools.py]](../file/bi-chat/bi-chat/src/agents/tools.py) - [[bi_chat/src/services/session_service_async.py]](../file/bi-chat/bi-chat/src/services/session-service-async.py) - [[bi_chat/src/services/long_term_memory.py]](../file/bi-chat/bi-chat/src/services/long-term-memory.py) - [[bi_chat/src/utils/progress_context.py]](../file/bi-chat/bi-chat/src/utils/progress-context.py) - [[bi-chat/docs/chat_v1_design.md]](../file/bi-chat/docs/chat-v1-design.md) - [[bi-chat/docs/launch_guide.md]](../file/bi-chat/docs/launch-guide.md) - [[bi-chat/bi_chat/src/db/__init__.py]](../file/bi-chat/bi-chat/src/db/init-.py)

目录 ​

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

简介 ​

本文件为基于 AgentScope 框架构建的多智能体 BI 对话系统 bi-chat 的技术文档。系统以 FastAPI 提供 REST 接口，采用 ReAct 推理范式，结合短期记忆与长期记忆（Mem0 + Milvus），支持工具调用（实体检索、指标检索、SQL 执行、知识图谱查询、营销策略生成等），并提供流式与非流式响应。文档涵盖智能体设计模式、工具调用机制、记忆管理、对话流程、与数据分析服务的集成、可扩展性与性能优化、部署与监控等内容。

项目结构 ​

bi-chat 项目位于 bi-chat 目录，核心由以下部分组成：

  • 应用入口与生命周期管理：FastAPI 应用、AgentScope 初始化、共享资源预加载、会话清理任务
  • 配置中心：统一读取环境变量，覆盖 LLM、数据库、Milvus、Redis、Neo4j、内存压缩等配置
  • 会话管理：LRU 缓存、并发锁、记忆加载与持久化、动态注册环境感知工具
  • 智能体：BIReActAgent 扩展、共享模型与工具包、自动保存记忆
  • 路由与流水线：消息路由、流式输出、SSE 兼容封装、工具调用解析
  • 工具集：实体检索、指标检索、SQL 执行沙箱、知识图谱查询、营销策略生成
  • 服务层：异步会话服务（PostgreSQL）、长期记忆服务（Mem0 + Milvus）
  • 进度上下文：跨序列化传递进度汇报器

图表来源

章节来源

核心组件 ​

  • 应用入口与生命周期
    • 初始化 AgentScope，注册路由，预加载共享资源（模型与工具包），启动定时清理任务
  • 会话管理器
    • LRU 缓存、并发锁、记忆加载与持久化、动态注册环境感知工具、工作流 Agent 构建
  • BIReActAgent
    • 继承 ReActAgent，自动保存记忆、支持长期记忆、可配置记忆压缩
  • 工具集
    • 实体检索、指标检索、SQL 执行沙箱、知识图谱查询、营销策略生成
  • 服务层
    • 异步会话服务（PostgreSQL）、长期记忆服务（Mem0 + Milvus）

章节来源

架构总览 ​

系统采用分层架构：

  • 表现层：FastAPI 路由，支持流式与非流式响应
  • 智能体层：ReAct 推理循环，工具调用与观察
  • 服务层：会话持久化、长期记忆检索与存储
  • 数据层：PostgreSQL（会话历史）、Milvus（长期记忆向量）、Neo4j（知识图谱）、StarRocks（业务数据查询）

图表来源

详细组件分析 ​

会话管理器（ConversationManager） ​

  • LRU 缓存与并发控制：使用有序字典与会话级锁，支持最大会话数与空闲超时清理
  • 记忆加载策略：智能加载历史，避免触发压缩；历史消息清洗，修复不完整工具调用链
  • 动态工具注册：根据页面信息注册环境感知工具
  • 工作流构建：支持多 Agent 协作（Manager、Data、General、Knowledge、Calculation、Summary、Guard）

图表来源

章节来源

BIReActAgent 与智能体设计 ​

  • 继承 ReActAgent，扩展自动保存记忆、长期记忆支持、可配置压缩
  • 共享资源：模型与工具包应用级单例，工具包深拷贝独立
  • 推理循环：最多 10 次迭代，支持工具调用与观察
  • 进度汇报：通过上下文变量传递进度汇报器

图表来源

章节来源

工具调用机制 ​

  • 工具注册：search_entities、search_indicators、execute_sql、get_database_info、env_perception、trigger_parallel_analysis、search_knowledge_graph、create_promotion_plan、promotion_strategy
  • SQL 执行沙箱：安全关键字过滤、结果截断、错误处理
  • 知识图谱查询：Neo4j Cypher 模糊匹配
  • 营销策略：基于分析结果智能推荐投放策略

图表来源

章节来源

记忆管理 ​

  • 短期记忆（InMemoryMemory）：会话级独立，自动保存增量消息，支持压缩阈值与保留最近轮次
  • 长期记忆（Mem0 + Milvus）：用户级共享实例，带去重检索与 Milvus update 修复
  • 历史加载清洗：修复不完整工具调用链，剥离孤儿 Tool 消息

图表来源

章节来源

对话流程与流式输出 ​

  • 路由层：接收消息、分流流式与非流式、封装 SSE
  • 流式解析：增量文本、工具调用缓存、工具结果输出顺序保证
  • 输出类型：conversation_id、text、tool_use、tool_result、error

图表来源

章节来源

配置与资源管理 ​

  • 配置项：LLM、数据库、Milvus、Redis、Neo4j、沙箱、内存压缩、长期记忆模式
  • 共享资源：DashScopeChatModel、Toolkit（深拷贝）、InMemoryMemory、Mem0LongTermMemory（用户级共享）

章节来源

依赖关系分析 ​

更新 移除了对 bi-proto 模块的依赖，更新了聊天服务的依赖分析

  • 组件耦合
    • 路由依赖会话管理器与数据库会话
    • 会话管理器依赖配置、工具包、长期记忆服务
    • BIReActAgent 依赖模型、工具包、内存、会话服务
    • 工具集依赖沙箱、本体检索器、Neo4j 客户端
  • 外部依赖
    • AgentScope（ReActAgent、Memory、Formatter、Token）
    • PostgreSQL（会话历史）
    • Milvus（长期记忆向量）
    • Neo4j（知识图谱）
    • StarRocks（业务数据查询）

图表来源

章节来源

性能考虑 ​

  • 资源共享与隔离
    • 模型与嵌入模型应用级单例，减少初始化开销
    • 工具包深拷贝，避免共享状态竞争
    • InMemoryMemory 独立，降低跨会话干扰
  • 记忆压缩
    • 智能阈值加载，避免压缩触发
    • 可配置压缩阈值与保留最近轮次
  • 并发与清理
    • 会话级锁避免并发冲突
    • 定时清理空闲会话，释放内存
  • I/O 优化
    • 异步会话服务与数据库交互
    • 工具结果截断，控制响应大小

故障排除指南 ​

  • SSE 结束标记缺失
    • 现象：客户端长时间等待，无 [DONE] 结束
    • 处理：确保 finally 分支发送 finish_reason 与 [DONE]
  • 工具调用链不完整
    • 现象：历史消息中存在孤立 Tool 消息或 Assistant 缺失 tool_calls
    • 处理：加载时进行历史清洗，剥离不完整链路
  • SQL 执行异常
    • 现象：危险关键字被拦截或沙箱执行失败
    • 处理：检查 SQL 关键字白名单与沙箱配置
  • 长期记忆 Milvus 更新错误
    • 现象：仅更新 metadata 时报 vectors is nil
    • 处理：使用修复后的 VectorStore，避免 vector=None 时的 upsert

章节来源

结论 ​

bi-chat 通过 AgentScope 的 ReAct 智能体与工具链，实现了从自然语言到业务数据查询与分析的闭环。系统在会话管理、记忆管理、工具调用与流式输出方面具备良好的可扩展性与稳定性。通过共享资源、异步服务与压缩策略，兼顾性能与用户体验。建议在生产环境中完善监控与告警，持续优化工具链与检索质量。

附录 ​

部署与运维 ​

  • 启动步骤
    • 后端：运行 Python 应用入口
    • 前端：Next.js 开发服务器
  • 端口占用与停止
    • 检查 8100（后端）与 3000（前端）
    • 通过 PID 杀死进程

章节来源

对话示例与使用场景 ​

  • 场景示例
    • 实体与指标检索：快速定位业务对象与口径
    • SQL 查询：在 StarRocks 中执行聚合分析
    • 知识图谱查询：获取精确的业务关系
    • 营销策略：基于分析结果生成投放方案
  • 输出类型
    • conversation_id：首次返回会话标识
    • text：模型推理文本（增量）
    • tool_use：工具调用信息
    • tool_result：工具执行结果
    • error：错误信息

章节来源

智能体开发指南 ​

  • 自定义 Agent
    • 继承 ReActAgent，配置模型、工具包、内存与压缩
    • 在会话管理器中注册与构建
  • 工具扩展
    • 在工具集中注册新工具，遵循 ToolResponse 格式
    • 如需数据库访问，使用沙箱或服务层封装
  • 对话策略配置
    • 通过配置中心调整模型、压缩与长期记忆模式
    • 在路由层控制流式与非流式输出

章节来源