BettaFish（微舆）深度技术解析：从0实现的多智能体舆情分析系统
一、项目概述
BettaFish（微舆） 是一个从零实现的多智能体舆情分析系统，由作者 666ghj 开源在 GitHub 上。项目名称中的"微舆"谐音"微鱼"（BettaFish是一种体型小但极具战斗力的观赏鱼），象征着"小而强大，不畏挑战"的设计理念。
该系统的核心能力是：用户只需像聊天一样提出分析需求，系统就能全自动完成从数据采集、多模态分析到报告生成的全流程，覆盖微博、小红书、抖音等30+主流社交媒体平台。
核心特性
- AI驱动的全域监控：AI爬虫集群7x24小时不间断作业，覆盖10+国内外关键社媒
- 超越LLM的复合分析引擎：5类专业Agent + 微调模型 + 统计模型协同工作
- 多模态能力：深度解析短视频内容，精准提取搜索引擎中的结构化信息卡片
- Agent"论坛"协作机制：辩论主持人模型引导链式思维碰撞，避免单一模型局限
- 公私域数据无缝融合：支持内部业务数据库与舆情数据集成
- 轻量化与高扩展性：纯Python模块化设计，一键式部署
二、技术原理
2.1 整体架构设计
BettaFish 采用了多智能体协同架构，主要由以下核心组件构成：
┌─────────────────────────────────────────────────────────┐
│ Flask 主应用 (app.py) │
│ ├── 统一入口管理 │
│ ├── Socket.IO 实时通信 │
│ └── 配置管理 (pydantic-settings) │
├─────────────────────────────────────────────────────────┤
│ 四大分析引擎 │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Query │ │ Media │ │ Insight │ │
│ │ Engine │ │ Engine │ │ Engine │ │
│ │ 新闻搜索 │ │ 多模态 │ │ 数据库挖掘 │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ └──────────────┼──────────────┘ │
│ ▼ │
│ ┌───────────────┐ │
│ │ ForumEngine │ ← 论坛协作机制 │
│ │ (主持人LLM) │ │
│ └───────┬───────┘ │
│ ▼ │
│ ┌───────────────┐ │
│ │ ReportEngine │ ← 报告生成引擎 │
│ │ (IR中间表示) │ │
│ └───────────────┘ │
├─────────────────────────────────────────────────────────┤
│ MindSpider 爬虫系统 │
│ ├── 话题提取 (BroadTopicExtraction) │
│ └── 深度舆情爬取 (DeepSentimentCrawling) │
└─────────────────────────────────────────────────────────┘
2.2 多智能体协作机制
这是 BettaFish 最具创新性的设计之一。系统采用 ForumEngine（论坛引擎） 作为 Agent 间的协作中枢：
协作流程
- 并行启动：用户提问后，Query Engine、Media Engine、Insight Engine 三个 Agent 同时开始工作
- 初步分析：各 Agent 使用专属工具进行概览搜索
- 策略制定：基于初步结果制定分块研究策略
- 循环协作阶段（核心）：
ForumEngine 实现细节
# ForumEngine/monitor.py 核心逻辑
class LogMonitor:"""基于文件变化的智能日志监控器"""def __init__(self):# 监控三个Agent的日志文件self.monitored_logs = {'insight': self.log_dir / 'insight.log','media': self.log_dir / 'media.log','query': self.log_dir / 'query.log',}# 主持人发言触发机制self.agent_speeches_buffer = []self.host_speech_threshold = 5 # 每5条Agent发言触发一次主持人发言self.is_host_generating = False
关键技术点：
- 使用文件监控而非内存通信，保证 Agent 间解耦
- JSON 内容捕获与解析，自动提取 Agent 的分析结果
- 主持人 LLM（默认使用 Qwen3 系列）基于 Agent 发言生成引导性观点
- ERROR 级别日志自动过滤，避免错误信息干扰讨论
2.3 报告生成引擎（ReportEngine）
报告生成是系统的最终输出环节，采用了创新的 IR（Intermediate Representation，中间表示） 设计：
章节生成 → JSON 结构 → IR 中间表示 → HTML/PDF/Markdown 渲染
IR 设计模式
# ReportEngine/ir/schema.py 定义块/标记Schema常量
ReportEngine/ir/validator.py 进行章节JSON结构校验
这种设计的好处是：
- 解耦生成与渲染：先生成结构化数据，再选择渲染格式
- 支持多格式输出：同一份 IR 可以渲染为 HTML、PDF 或 Markdown
- 便于调试：IR 文件保存为 JSON，方便查看中间状态
报告生成流程
- 模板选择：LLM 根据分析内容选择最合适的报告模板
- 文档布局：确定标题、目录、主题设计
- 篇幅规划：为每个章节分配字数预算
- 章节生成：逐章生成内容，并进行质量校验
- IR 装订：将所有章节组装为完整的 IR 文档
- 渲染输出：根据 IR 渲染为交互式 HTML 报告
2.4 爬虫系统（MindSpider）
MindSpider 是系统的数据采集层，包含两大核心模块：
话题提取（BroadTopicExtraction）
- 自动获取当日热点新闻
- 提取关键词用于后续爬取
- 支持新闻源自定义配置
深度舆情爬取（DeepSentimentCrawling）
- 支持多平台：微博、小红书、抖音、快手等
- 深度评论获取：不仅爬取帖子内容，还获取用户评论
- 关键词管理：动态调整爬取关键词
- 数据库存储：结构化存储爬取结果
# 爬虫使用示例
python main.py --setup # 项目初始化
python main.py --broad-topic # 话题提取
python main.py --complete --date 2024-01-20 # 完整爬取流程
2.5 情感分析模型集合
系统集成了多种情感分析方法，满足不同场景需求：
| 模型类型 | 特点 | 适用场景 | |---------|------|---------| | 多语言情感分析 | 支持中英文等多语言 | 国际舆情分析 | | BERT 中文微调 (LoRA) | 精准度高，资源占用中等 | 中文文本情感分析 | | GPT-2 LoRA 微调 | 轻量级，推理速度快 | 实时情感分析 | | Qwen3 小参数微调 | 国产模型，中文理解强 | 中文社交媒体 | | 传统机器学习 (SVM等) | 资源需求极低 | 资源受限环境 |
2.6 技术栈总结
- Web 框架：Flask + Flask-SocketIO（主应用）+ Streamlit（各 Agent 独立应用）
- LLM 接口：OpenAI SDK 兼容格式，支持任意兼容 API
- 数据库：PostgreSQL/MySQL + SQLAlchemy 异步引擎
- 爬虫：Playwright + BeautifulSoup + 各平台专用爬虫
- 数据处理：Pandas + NumPy + Jieba
- 可视化：Plotly + Matplotlib + WordCloud
- PDF 生成：WeasyPrint
- 机器学习：PyTorch + Transformers + Scikit-learn
三、安装与快速开始
3.1 环境要求
- 操作系统：Windows / Linux / macOS
- Python 版本：3.9+
- 数据库：PostgreSQL（推荐）或 MySQL
- 内存：建议 2GB 以上
3.2 Docker 部署（推荐）
# 1. 克隆仓库
git clone https://github.com/666ghj/BettaFish.git
cd BettaFish
2. 配置环境变量
cp .env.example .env
编辑 .env 文件，填入 LLM API Key 和数据库配置
3. 启动所有服务
docker compose up -d
3.3 源码部署
# 1. 创建 Python 环境
conda create -n bettafish python=3.11
conda activate bettafish
2. 安装依赖
pip install -r requirements.txt
3. 安装 Playwright 驱动
playwright install chromium
4. 配置环境变量
cp .env.example .env
编辑 .env 文件
5. 启动系统
python app.py
3.4 环境变量配置
# 数据库配置
DB_HOST=db
DB_PORT=5432
DB_USER=bettafish
DB_PASSWORD=bettafish
DB_NAME=bettafish
LLM 配置（以 Moonshot Kimi 为例）
INSIGHT_ENGINE_API_KEY=your_api_key
INSIGHT_ENGINE_BASE_URL=https://api.moonshot.cn/v1
INSIGHT_ENGINE_MODEL_NAME=kimi-k2-0711-preview
Media Agent（推荐 Gemini）
MEDIA_ENGINE_API_KEY=your_api_key
MEDIA_ENGINE_BASE_URL=https://aihubmix.com/v1
MEDIA_ENGINE_MODEL_NAME=gemini-2.5-pro
Query Agent（推荐 DeepSeek）
QUERY_ENGINE_API_KEY=your_api_key
QUERY_ENGINE_BASE_URL=https://api.deepseek.com
QUERY_ENGINE_MODEL_NAME=deepseek-chat
四、使用方法与实战
4.1 完整系统使用
启动后访问 http://localhost:5000，在 Web 界面中：
- 提出分析需求（如"武汉大学舆情分析"）
- 系统自动开始多 Agent 协同分析
- 实时查看 ForumEngine 中的讨论过程
- 最终生成交互式 HTML 报告
4.2 单独启动 Agent
# 启动 QueryEngine（新闻搜索）
streamlit run SingleEngineApp/query_engine_streamlit_app.py --server.port 8503
启动 MediaEngine（多模态分析）
streamlit run SingleEngineApp/media_engine_streamlit_app.py --server.port 8502
启动 InsightEngine（数据库挖掘）
streamlit run SingleEngineApp/insight_engine_streamlit_app.py --server.port 8501
4.3 命令行报告生成
# 基本使用（自动从最新日志生成报告）
python report_engine_only.py
指定主题
python report_engine_only.py --query "土木工程行业分析"
跳过 PDF 生成
python report_engine_only.py --skip-pdf
显示详细日志
python report_engine_only.py --verbose
4.4 情感分析模型使用
# 多语言情感分析
cd SentimentAnalysisModel/WeiboMultilingualSentiment
python predict.py --text "This product is amazing!" --lang "en"
BERT 中文微调模型
cd SentimentAnalysisModel/WeiboSentiment_Finetuned/BertChinese-Lora
python predict.py --text "这个产品真的很不错"
Qwen3 小参数微调
cd SentimentAnalysisModel/WeiboSentiment_SmallQwen
python predict_universal.py --text "这次活动办得很成功"
4.5 自定义业务数据库集成
# 1. 在 config.py 中添加业务数据库配置
BUSINESS_DB_HOST = "your_db_host"
BUSINESS_DB_USER = "your_db_user"
BUSINESS_DB_PASSWORD = "your_password"
BUSINESS_DB_NAME = "your_business_db"
2. 创建自定义数据访问工具
class CustomBusinessDBTool:def search_business_data(self, query: str, table: str):# 实现业务逻辑pass
3. 集成到 InsightEngine
from .tools.custom_db_tool import CustomBusinessDBTool
agent.custom_db_tool = CustomBusinessDBTool()
4.6 自定义报告模板
在 ReportEngine/report_template/ 目录下创建新的 .md 模板文件，系统会自动选择最合适的模板进行报告生成。
五、常见问题与解决方案
5.1 安装失败
问题：pip install -r requirements.txt 失败
解决方案：
- 确保 Python 版本 ≥ 3.9
- 使用 Conda 或 uv 管理环境
- 如果遇到 weasyprint 安装失败，先安装系统依赖（参考
static/Partial README for PDF Exporting/README.md） - 如果不需要本地情感分析模型，可注释掉 requirements.txt 中的"机器学习"部分
5.2 数据库初始化失败
问题：启动时提示数据库连接失败
解决方案：
- Docker 部署：确保
DB_HOST=db（对应 docker-compose.yml 中的服务名） - 源码部署：确保 PostgreSQL/MySQL 已启动，端口配置正确
- 检查
.env文件中的数据库凭据是否正确
5.3 LLM API 调用失败
问题：Agent 无法获取 LLM 响应
解决方案：
- 检查
.env中的 API Key 是否正确 - 确保 BASE_URL 与模型提供商匹配
- 所有 LLM 调用均使用 OpenAI 兼容格式，可参考：
from openai import OpenAI
client = OpenAI(api_key="your_key", base_url="https://your-provider.com/v1")
response = client.chat.completions.create(model="your-model",messages=[{'role': 'user', 'content': "你的问题"}]
)
5.4 爬虫功能异常
问题：MindSpider 无法爬取数据
解决方案：
- 确保已安装 Playwright 驱动：
playwright install chromium - 检查目标网站的反爬策略，可能需要配置代理
- 遵守目标网站的 robots.txt 协议
5.5 报告生成质量不佳
问题：生成的报告内容不理想
解决方案：
- 使用
report_engine_only.py快速重试，无需重新运行分析 - 调整各 Agent 的配置参数（如
max_search_results、max_content_length） - 尝试更换报告模板
- 使用
regenerate_latest_html.py/regenerate_latest_md.py重渲染最新结果
5.6 内存/性能问题
问题：系统运行缓慢或内存占用过高
解决方案：
- 减少各 Agent 的
max_search_results和max_content_length - 使用较小的 LLM 模型
- 对于情感分析，使用传统机器学习方法替代深度学习模型
- 调整数据库连接池参数
5.7 Streamlit 端口占用
问题：重启后端口仍被占用
解决方案：
# 查找占用端口的进程
lsof -i :8501 # macOS/Linux
netstat -ano | findstr 8501 # Windows
终止进程
kill -9 # macOS/Linux
taskkill /F /PID # Windows
六、总结
BettaFish（微舆）是一个设计精巧、架构清晰的多智能体舆情分析系统。其最大的亮点在于：
- 创新的 Agent 论坛协作机制：通过主持人和多 Agent 辩论，有效避免了单一模型的思维局限
- IR 中间表示设计：解耦了内容生成与格式渲染，支持多格式输出
- 完整的工程化实现：从数据采集、分析到报告生成，形成完整闭环
- 高扩展性：模块化设计使得自定义模型、数据库、报告模板变得简单
稳定可靠低价的AI中转站：X API