Fish Researcher

基于大语言模型的智能研究报告生成系统

🌟 项目概述

Fish Researcher 是一个先进的智能研究报告生成系统，支持多LLM提供商、智能字数分配和流式输出。系统能够自动进行深度研究、生成结构化报告，并提供多种格式的输出选项。

✨ 核心特性

• 🤖 多LLM支持：兼容OpenAI、Ollama和Mock模式
• 📊 智能字数控制：大纲10%原则 + 重要性驱动的精确字数分配
• 🎯 多搜索引擎：支持Searx、Tavily、Google等7种搜索引擎
• 📄 多格式输出：同时生成Markdown、HTML和PDF专业报告
• 🌈 流式界面：彩色终端输出，实时进度显示
• ⚙️ 智能配置：自动验证和修正配置参数
• 🔧 自动化测试：完整的测试框架支持

🚀 快速开始

环境要求

Python 3.8+
虚拟环境（推荐）

安装步骤

1. 克隆项目

git clone <repository-url>
cd fish-researcher

2. 创建虚拟环境

python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或
venv\Scripts\activate     # Windows

3. 安装依赖

pip install -r requirements.txt

4. 配置环境

cp .env.example .env
# 编辑 .env 文件，配置API密钥和服务地址

运行方式

交互模式

python main.py

自动测试模式

python main_test.py

📋 配置说明

基础配置

# LLM提供商选择
LLM_PROVIDER=ollama  # 可选: openai, ollama, mock

# 报告目标字数
TOTAL_WORDS=15000

# 搜索引擎
SEARCH_RETRIEVER=searx  # 可选: searx, tavily, google, duckduckgo, bing, serper, serpapi

OpenAI配置

OPENAI_API_KEY=your_api_key_here
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_FAST_MODEL=gpt-3.5-turbo
OPENAI_SMART_MODEL=gpt-4

Ollama配置

OLLAMA_BASE_URL=http://localhost:11434/v1
OLLAMA_FAST_MODEL=qwen3:8b
OLLAMA_SMART_MODEL=qwen3:30b

🎯 使用指南

生成报告

1. 启动程序

python main.py

2. 选择运行模式：按照提示选择LLM提供商

3. 设置报告参数：

   • 报告类型：full_report 或 outline_report
   • 报告标题：输入您的研究主题
   • 目标字数：设置报告总字数

4. 等待生成：系统将自动进行研究和报告生成

自动化测试

# 运行完整测试流程
python main_test.py

# 运行特定测试
python main_test.py --test-basic      # 基础功能测试
python main_test.py --test-config     # 配置加载测试
python main_test.py --test-llm        # LLM连接测试
python main_test.py --test-agent      # Agent工作流测试

📊 输出说明

报告保存在 outputs/ 目录，采用智能命名规则：

{报告题目}_{生成时间}.md    # Markdown格式
{报告题目}_{生成时间}.html   # HTML格式
{报告题目}_{生成时间}.pdf    # PDF格式（推荐）

文件示例

大学生创业方向研究_20251203_154530.md
大学生创业方向研究_20251203_154530.html
大学生创业方向研究_20251203_154530.pdf

🔧 高级功能

智能字数管理

• 大纲10%原则：大纲严格控制在总字数的10%
• 重要性驱动分配：基于LLM标注的重要性(0.5-2.0)进行字数分配
• 动态平衡调整：自动调整分配偏差，确保目标字数精确达成
• 实时监控反馈：章节生成过程中显示字数达标状态

多格式报告输出

• Markdown：便于编辑和版本控制
• HTML：支持网页浏览和分享
• PDF：专业排版，适合正式发布

搜索引擎集成

支持7种搜索引擎，满足不同需求：

搜索引擎	特点	适用场景
Searx	私有化，无限制	企业内部使用
Tavily	高质量，API友好	商业应用
Google	覆盖面广	通用搜索
DuckDuckGo	隐私保护	匿名搜索
Bing	微软生态	企业环境
Serper	快速稳定	开发测试
SerpApi	功能丰富	高级需求

🛠️ 项目结构

fish-researcher/
├── agent/              # 研究流程核心
│   └── agent.py        # Agent主逻辑
├── config/             # 配置管理
│   └── config.py       # 配置验证和加载
├── llm/                # LLM接口层
│   ├── llm.py          # LLM统一接口
│   ├── openai_provider.py  # OpenAI适配器
│   └── prompts.py      # 提示词模板
├── memory/             # 向量化存储
│   ├── memory.py       # 内存管理
│   └── faiss_storage.py  # 向量数据库
├── tools/              # 搜索工具
│   ├── tools.py        # 工具协调
│   ├── retrievers/     # 搜索引擎
│   └── scraper/        # 网页抓取
├── utils/              # 工具函数
│   ├── report_word_manager.py  # 字数管理
│   ├── util.py         # 通用工具
│   └── logs.py         # 日志系统
├── outputs/            # 报告输出目录
├── main.py             # 主入口
└── main_test.py        # 自动化测试

🔍 故障排除

常见问题

1. 配置错误

   • 检查base_url是否以/v1结尾
   • 验证API密钥是否正确

2. 连接失败

   • 确认网络连接正常
   • 检查防火墙设置

3. 字数异常

   • 确保大纲包含重要性标注
   • 查看字数分配验证结果

4. PDF生成失败

   • 安装WeasyPrint：pip install weasyprint
   • 或使用PDFKit：pip install pdfkit

错误处理

系统提供完整的错误处理机制：

• 🔍 自动诊断：详细的问题分析和建议
• 🔄 自动重试：网络错误和限流自动重试
• 📝 详细日志：完整的运行日志记录
• ⚠️ 降级处理：服务不可用时的自动降级

🤝 贡献指南

1. Fork 项目
2. 创建特性分支：git checkout -b feature/AmazingFeature
3. 提交更改：git commit -m 'Add some AmazingFeature'
4. 推送到分支：git push origin feature/AmazingFeature
5. 开启 Pull Request

📄 许可证

本项目采用 LICENSE 许可证 - 查看 LICENSE 文件了解详情

🙏 致谢

感谢所有为这个项目做出贡献的开发者和用户！

---

Fish Researcher - 让智能研究报告生成变得简单高效！