1. 项目概述从零构建一个多智能体舆情分析系统如果你正在寻找一个能帮你自动分析社交媒体、新闻网站和用户评论并生成深度洞察报告的工具那么“微舆”BettaFish这个项目绝对值得你花时间研究。我最初接触这个项目是因为厌倦了手动爬取数据、清洗、分析、再写报告的繁琐流程。市面上虽然有一些舆情监控平台但它们要么是黑盒服务价格昂贵且无法定制要么功能单一只能做简单的关键词统计。而“微舆”的定位很明确一个从零实现、不依赖任何外部框架、完全开源的多智能体Multi-Agent系统目标是让每个人都能拥有一个强大的“AI分析师”。这个项目的核心价值在于它的“多智能体协作”架构。它不是一个简单的脚本而是模拟了一个小型研究团队的工作流程。当你提出一个分析需求比如“分析一下最近武汉大学的网络声誉”系统内部会同时启动几个各司其职的AI智能体一个负责全网搜索新闻和公开信息Query Agent一个擅长分析视频、图片等多模态内容Media Agent还有一个能深度挖掘你私有数据库中的历史舆情数据Insight Agent。最精彩的部分在于这些智能体不是各自为战它们会通过一个“论坛引擎”Forum Engine进行辩论和协作就像一群专家在开会互相补充信息、挑战观点最终共同产出一份逻辑严密、视角多元的分析报告。我花了几周时间部署、测试并深入研究了它的代码发现它不仅仅是一个舆情工具。它的模块化设计、清晰的接口定义使得它很容易被改造成其他领域的深度研究系统比如金融市场分析、竞品调研、学术文献综述等。项目作者将其称为“简洁通用的数据分析引擎”这个定位非常准确。接下来我将从系统架构、核心模块、实操部署到高级定制为你完整拆解这个强大的开源项目。2. 系统架构深度解析多智能体如何协同工作理解“微舆”的架构是掌握其强大能力的关键。它没有使用LangChain或AutoGen这类流行框架而是选择从零构建这带来了极高的灵活性和可控性。整个系统可以看作一个由“大脑”智能体、“手脚”工具集和“会议室”论坛引擎组成的有机体。2.1 核心智能体分工与协作机制系统主要由四个核心智能体构成它们各自拥有独特的“技能树”Query Agent查询智能体这是系统的“侦察兵”。它的任务是进行广度搜索覆盖国内外30多个主流新闻网站和社交媒体平台。它不满足于标题和摘要会深入抓取文章正文和相关的用户评论。其内部集成了反思机制如果第一次搜索的结果不够理想它会自动调整关键词策略进行多轮搜索确保信息的全面性。Media Agent媒体智能体这是系统的“眼睛”。在短视频时代舆情不仅存在于文字中。这个智能体专门处理抖音、快手、B站等平台的视频内容。它能通过API或爬虫获取视频的标题、描述、评论甚至结合OCR技术识别视频中的文字并结合语音转文字如果支持来理解视频的核心观点和情感倾向。此外它还能解析搜索引擎结果页中的“知识卡片”比如天气、股票、人物百科等结构化信息。Insight Agent洞察智能体这是系统的“历史学家”。它连接着你本地的舆情数据库由项目自带的MindSpider爬虫系统构建。当其他智能体提供最新的公开信息时Insight Agent会从历史数据库中寻找相关的趋势、过往的类似事件以及长期的用户情感变化。它集成了多种情感分析模型从微调的BERT到轻量化的Qwen能对海量评论进行精准的情感打分和主题聚类找出潜在的“沉默大多数”的声音。Report Agent报告智能体这是系统的“总编辑”。它不参与前期的信息搜集而是负责收尾工作。它会收集前三个智能体产出的所有分析片段以及它们在“论坛”中辩论的过程记录。然后它会根据分析主题动态选择最合适的报告模板规划章节结构分配篇幅并调用大语言模型LLM将零散的信息整合成一份结构完整、图文并茂的交互式HTML报告。关键设计思想这种分工避免了让单个“全能”LLM去处理所有任务导致的深度不足和成本高昂问题。每个智能体都可以针对其专长领域进行深度优化例如为Media Agent配备更强的多模态理解模型为Insight Agent配备专门的情感分析微调模型。2.2 论坛引擎智能体协作的“灵魂”这是“微舆”最具创新性的部分。传统的多智能体系统往往是顺序执行或简单的结果汇总容易陷入“群体思维”。而论坛引擎Forum Engine引入了一个“主持人”角色。工作流程如下当Query、Media、Insight三个智能体完成初步的独立研究后它们会带着自己的发现“进入”论坛。论坛主持人由另一个LLM扮演会阅读所有智能体的初步报告然后提出引导性问题或指出矛盾点例如“Query Agent提到事件A在微博热度很高但Insight Agent的历史数据显示同类事件在知乎反响更大请双方就此展开进一步调查。”各智能体接收到主持人的引导后会进行新一轮的、更有针对性的深度研究。这个过程会进行多轮循环直到主持人认为讨论已充分或达到预设的轮次限制。这种机制模拟了学术研讨会或头脑风暴通过观点碰撞和相互质疑迫使每个智能体去查证、补充和修正自己的结论最终产出的集体智慧远高于单个智能体的简单加和。2.3 数据流与状态管理整个系统的数据流是异步且并行的。用户通过Flask前端提交问题后主进程会同时唤醒三个研究型智能体。它们各自独立工作将中间结果和最终分析片段写入指定的日志目录。Forum Engine监控这些日志协调辩论。最后Report Agent读取所有日志和论坛记录生成最终报告。状态管理主要通过文件系统和内存中的状态对象来维护确保了进程间解耦和系统的可扩展性。3. 从零开始本地部署与核心配置实战看懂了架构手痒想自己跑起来试试。官方提供了Docker一键部署和源码部署两种方式。为了彻底搞懂原理我强烈推荐从源码部署开始。下面是我在Ubuntu 22.04系统上的完整实操记录。3.1 环境准备与依赖安装首先你需要一个Python 3.9的环境。我使用Miniconda来管理这样能避免污染系统环境。# 1. 创建并激活Conda环境 conda create -n bettafish python3.11 -y conda activate bettafish # 2. 克隆项目代码 git clone https://github.com/666ghj/BettaFish.git cd BettaFish接下来安装Python依赖。项目根目录下的requirements.txt文件列出了所有包。这里有个坑要注意weasyprint这个用于PDF导出的库需要系统级的依赖如Cairo、Pango。如果跳过这一步报告生成功能会报错。# 3. 安装系统依赖针对Ubuntu/Debian sudo apt-get update sudo apt-get install -y python3-dev python3-pip python3-setuptools \ build-essential libcairo2 libpango-1.0-0 libpangocairo-1.0-0 \ libgdk-pixbuf2.0-0 libffi-dev shared-mime-info # 4. 安装Python依赖 pip install -r requirements.txt如果weasyprint安装失败可以暂时注释掉requirements.txt中的weasyprint行或者参考项目static/目录下的PDF导出配置文档进行详细安装。3.2 数据库初始化与配置“微舆”使用关系型数据库推荐PostgreSQL来存储爬虫抓取的原始数据。Insight Agent正是从这里读取数据进行分析。# 使用Docker快速启动一个PostgreSQL实例 docker run --name bettafish-db -e POSTGRES_USERbettafish -e POSTGRES_PASSWORDbettafish -e POSTGRES_DBbettafish -p 5432:5432 -d postgres:15然后你需要配置数据库连接。项目使用.env文件管理配置。# 5. 复制环境变量模板并编辑 cp .env.example .env用文本编辑器打开.env文件找到数据库配置部分修改为你的实际信息# 数据库配置 DB_HOSTlocalhost # 如果你用上面的Docker命令就是localhost DB_PORT5432 DB_USERbettafish DB_PASSWORDbettafish DB_NAMEbettafish DB_CHARSETutf8mb4 DB_DIALECTpostgresql # 如果用的是MySQL则改为mysql3.3 大模型API配置这是核心步骤。系统所有LLM调用都遵循OpenAI API格式这意味着你可以使用任何兼容此格式的服务包括OpenAI官方API、Azure OpenAI、以及众多国内外的兼容API服务如DeepSeek、智谱AI、月之暗面等。在.env文件中你需要为每个智能体配置对应的API。作者很贴心地给出了推荐模型初次部署建议遵循。# LLM配置 # Insight Agent (推荐使用深度推理能力强的模型如GPT-4) INSIGHT_ENGINE_API_KEYsk-你的api密钥 INSIGHT_ENGINE_BASE_URLhttps://api.openai.com/v1 # 如果是第三方填其地址 INSIGHT_ENGINE_MODEL_NAMEgpt-4-turbo-preview # Media Agent (推荐使用具备多模态能力的模型如GPT-4V或Qwen-VL) MEDIA_ENGINE_API_KEYsk-你的api密钥 MEDIA_ENGINE_BASE_URLhttps://api.openai.com/v1 MEDIA_ENGINE_MODEL_NAMEgpt-4-vision-preview # Query Agent (推荐使用长文本处理能力强的模型如Claude-3或GPT-4) QUERY_ENGINE_API_KEYsk-你的api密钥 QUERY_ENGINE_BASE_URLhttps://api.openai.com/v1 QUERY_ENGINE_MODEL_NAMEclaude-3-sonnet-20240229 # Report Agent (推荐使用文本生成和格式化能力强的模型) REPORT_ENGINE_API_KEYsk-你的api密钥 REPORT_ENGINE_BASE_URLhttps://api.openai.com/v1 REPORT_ENGINE_MODEL_NAMEgpt-4-turbo-preview # Forum Engine (论坛主持人推荐使用综合能力强的模型) FORUM_ENGINE_API_KEYsk-你的api密钥 FORUM_ENGINE_BASE_URLhttps://api.openai.com/v1 FORUM_ENGINE_MODEL_NAMEgpt-4-turbo-preview成本控制技巧对于Query和Media这种需要处理大量外部信息的Agent可以考虑使用成本更低的模型如GPT-3.5-Turbo因为它们主要做信息提取和初步总结。而对于需要深度推理和写作的Insight、Report和Forum Agent则使用更强的模型。你可以在各个Agent的utils/config.py中单独配置。3.4 首次运行与数据爬取配置完成后就可以启动系统了。# 6. 启动主应用 python app.py访问http://localhost:5000你会看到一个简洁的Web界面。但是此时Insight Agent是没有数据可分析的。你需要先运行爬虫系统MindSpider来填充数据库。打开一个新的终端窗口激活同一个conda环境然后运行# 进入爬虫目录 cd MindSpider # 初始化数据库表结构 python main.py --setup # 运行一次完整的话题提取和深度爬取以“人工智能”为例你可以替换成任何关键词 python main.py --complete --keywords 人工智能 机器学习 --date date %Y-%m-%d # Linux/Mac # 在Windows PowerShell中python main.py --complete --keywords 人工智能 机器学习 --date (Get-Date -Format yyyy-MM-dd)爬虫会开始工作从配置的社交媒体平台抓取包含关键词的帖子和评论并存入数据库。这个过程可能需要一些时间取决于关键词的热度和平台数量。3.5 进行一次完整的分析当数据库有了一些数据后回到Web界面在输入框中提出你的分析需求例如“分析一下人工智能在教育领域的应用现状和舆论反响”。点击提交系统就会开始全自动工作。你会在界面上看到实时日志显示各个Agent的启动、搜索、反思、进入论坛、生成报告等步骤。整个过程完全自动化无需人工干预。最终系统会生成一个HTML报告文件并自动在浏览器中打开。这份报告包含执行摘要、舆论观点梳理、情感分析图表、时间趋势、核心传播节点甚至还有基于论坛辩论得出的“争议焦点”和“未来预测”章节。4. 核心模块拆解与二次开发指南“微舆”的代码结构非常清晰模块化程度高这为二次开发提供了极大便利。如果你想将其改造成一个“金融市场分析系统”或“学术论文助手”主要工作集中在修改Agent的“工具集”和“提示词”。4.1 自定义智能体工具集每个Agent的能力由其tools/目录下的工具决定。例如你想让Query Agent不仅能搜新闻还能搜索学术论文。创建新工具在QueryEngine/tools/目录下新建一个文件比如academic_search.py。# QueryEngine/tools/academic_search.py import requests from typing import List, Dict from .base_tool import BaseTool # 继承基础工具类 class AcademicSearchTool(BaseTool): name academic_search description Search for academic papers from arXiv, Google Scholar, etc. def __init__(self, api_key: str None): self.api_key api_key self.base_url http://export.arxiv.org/api/query def run(self, query: str, max_results: int 10) - List[Dict]: 搜索arXiv论文 params { search_query: fall:{query}, start: 0, max_results: max_results, sortBy: relevance, sortOrder: descending } response requests.get(self.base_url, paramsparams) # ... 解析XML响应提取标题、摘要、作者、链接等信息 papers [] # 解析逻辑... return papers注册工具在QueryEngine/agent.py中找到工具注册的地方通常在__init__方法或一个专门的工具加载函数将你的新工具添加进去。from .tools.academic_search import AcademicSearchTool class QueryAgent: def __init__(self): # ... 其他初始化 self.tools { web_search: WebSearchTool(), news_search: NewsSearchTool(), academic_search: AcademicSearchTool(api_keyyour_arxiv_key), # 新增 }更新提示词为了让Agent知道何时使用这个新工具你需要修改QueryEngine/prompts/下的提示词模板在系统指令system prompt中说明“当你需要查找某个领域的学术研究现状或理论依据时可以使用academic_search工具。”4.2 调整智能体行为参数每个Agent的utils/config.py文件里都有丰富的可调参数这些参数直接影响分析深度、广度和成本。控制搜索深度max_search_results最大结果数、max_reflections反思轮次。增加这些值会让搜索更全面但也会增加API调用次数和时间。控制分析粒度default_get_comments_limit获取评论数。对于Insight Agent这个值决定了从数据库抽取多少条评论进行分析。数据量太大时可以适当调低或启用采样。情感分析模型切换在InsightEngine/tools/sentiment_analyzer.py中可以修改SENTIMENT_CONFIG的model_type在bert准确但慢、multilingual支持多语言、qwen轻快等模型间选择也可以完全替换成你自己的微调模型路径。4.3 集成私有业务数据这是企业级应用的关键。Insight Agent的设计初衷就是连接私有数据库。建立数据连接在项目根目录的config.py或.env中添加你的业务数据库配置。编写数据查询工具仿照InsightEngine/tools/search.py创建一个新的工具类使用SQLAlchemy或其它ORM连接你的业务库编写查询方法。定义数据融合策略这是最有挑战也最有价值的部分。你需要在Insight Agent的提示词中设计逻辑告诉它如何将公开舆情数据如微博吐槽和你的业务数据如客服工单、销售数据关联起来。例如“当分析产品X的负面舆情时同时查询近一个月内产品X的退货率数据和客服投诉分类尝试找出舆情与业务数据之间的相关性。”4.4 定制报告模板与样式Report Agent使用Markdown文件作为报告模板。系统内置了几个模板位于ReportEngine/report_template/目录下。创建新模板复制一份现有的模板例如企业品牌声誉分析报告.md重命名为金融行业分析报告.md。修改模板结构模板中使用特殊的{{ block_name }}语法来定义可填充的内容块。你可以重新设计章节结构比如增加“宏观经济指标影响”、“政策风险分析”、“同业竞品对比”等章节。# {{report_title}} ## 1. 执行摘要 {{ executive_summary}} ## 2. 宏观经济背景 {{ macro_economic_context}} ## 3. 行业舆情分析 {{ industry_public_opinion}} ...适配内容生成你还需要在Report Agent的提示词库prompts.py中为新增的内容块如macro_economic_context编写专门的生成指令指导LLM如何组织这部分内容。5. 避坑指南与性能优化心得在实际部署和运行过程中我踩过不少坑也总结出一些优化技巧。5.1 常见问题与解决方案问题现象可能原因解决方案启动时报数据库连接错误1. 数据库服务未启动2..env配置错误3. 防火墙/端口问题1. 检查PostgreSQL/MySQL服务状态 (docker ps或systemctl status postgresql)2. 逐项核对.env中的主机、端口、用户名、密码、数据库名3. 使用telnet localhost 5432测试端口连通性智能体运行时报API key not foundAPI密钥未正确配置或环境变量未加载1. 确认.env文件在项目根目录且名称正确2. 尝试在代码中直接print(os.getenv(INSIGHT_ENGINE_API_KEY))检查是否读取到3. 重启Flask应用确保环境变量重新加载报告生成失败提示WeasyPrint错误系统缺少weasyprint的C库依赖1. 根据官方文档安装系统依赖见3.1节2. 临时方案在ReportEngine/agent.py中注释掉PDF生成相关代码或使用--skip-pdf参数爬虫被目标网站封禁请求频率过高缺乏伪装1. 修改MindSpider/config.py中的REQUEST_DELAY参数增加请求间隔2. 配置代理IP池需自行实现或集成第三方库3. 使用playwright的headlessFalse模式观察行为模拟真人操作分析过程耗时过长30分钟1. 搜索范围太广2. LLM响应慢3. 论坛辩论轮次过多1. 调低max_search_results和max_reflections2. 为Query/Media Agent换用更快的模型如GPT-3.5-Turbo3. 在ForumEngine/monitor.py中调低max_forum_rounds最大论坛轮次情感分析结果不准1. 默认模型不适合你的领域2. 文本预处理问题1. 使用项目自带的微调脚本用你的领域数据重新训练情感分析模型2. 检查text_processing.py中的清洗规则根据你的数据特点如包含大量网络用语、缩写进行调整5.2 成本控制与性能优化策略使用多个LLM尤其是GPT-4级别的模型成本是必须考虑的问题。分层使用模型这是我实践下来最有效的策略。将智能体分为“信息收集层”和“分析决策层”。让Query和Media Agent使用便宜的模型如DeepSeek、GLM-4-9B的API它们负责执行搜索、提取信息这类相对简单的任务。让Insight、Report和Forum Agent使用强大的模型如GPT-4、Claude-3它们负责需要深度理解、推理和创造性写作的核心工作。这样能在保证报告质量的同时大幅降低单次分析的成本。设置Token上限和超时在每个Agent的LLM客户端配置中通常在llms/base.py务必设置max_tokens和timeout参数。防止某个智能体“陷入沉思”生成过于冗长或无意义的回复消耗大量Token。启用缓存对于相对稳定的查询例如对某个历史事件的固定分析可以考虑引入一个简单的缓存层。将(query, agent_name)作为键将LLM的响应结果缓存到Redis或本地文件中设定一个合理的过期时间如24小时。当相同或相似的查询再次出现时直接返回缓存结果能节省大量API调用。异步与并发优化项目本身已经实现了Agent间的并行执行。但你还可以进一步优化单个Agent内部的操作。例如Query Agent在调用多个搜索工具时可以使用asyncio.gather并发执行而不是顺序执行减少总的I/O等待时间。5.3 扩展性与维护性建议日志与监控系统已经提供了详细的文件日志。建议将其接入到像Grafana Loki这样的日志聚合系统方便监控每个智能体的运行状态、API调用次数和耗时便于问题排查和性能分析。错误处理与重试网络请求和API调用失败是常态。项目中的utils/retry_helper.py提供了基础的重试机制。你可以根据需要对不同的错误类型如连接超时、速率限制、服务器错误配置不同的重试策略和回退间隔。配置中心化虽然现在配置散落在各个Agent的config.py和根目录的.env中但对于大型部署可以考虑使用Consul或etcd作为配置中心实现动态配置更新而无需重启服务。6. 项目生态与未来展望“微舆”不是一个孤立的项目。作者团队已经基于它发布了更上层的预测引擎MiroFish。这标志着“数据分析三板斧”——收集MindSpider、分析BettaFish、预测MiroFish——已经形成了完整闭环。MiroFish可以基于BettaFish产出的深度分析报告进一步进行趋势预测和模拟推演真正实现了从“洞察现在”到“预见未来”的跨越。从我个人的使用体验来看“微舆”的价值远不止于舆情分析。它的多智能体协作框架、模块化工具设计、以及“论坛”这种促进深度思考的机制为构建任何需要“调查研究分析归纳”能力的AI应用提供了一个绝佳的蓝本。无论是市场调研、投资分析、学术研究还是企业内部的知识管理和决策支持你都可以基于这套框架进行改造。这个项目的代码质量很高注释清晰结构合理非常适合作为学习多智能体系统设计的实战教材。如果你对AI Agent、大模型应用开发感兴趣我强烈建议你不仅是用它更是去读它的代码理解每个模块的设计思路甚至动手为它贡献一个新的工具或Agent。开源社区的活力正来自于此。