212 lines
4.5 KiB
Markdown
212 lines
4.5 KiB
Markdown
# 快速开始指南
|
||
|
||
## 1. 环境准备
|
||
|
||
### 激活虚拟环境
|
||
|
||
```bash
|
||
# 如果虚拟环境不存在，先创建
|
||
conda create -n deep_research_env python=3.11
|
||
conda activate deep_research_env
|
||
```
|
||
|
||
### 安装依赖
|
||
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
## 2. 配置API密钥
|
||
|
||
编辑 `.env` 文件，填写你的API密钥：
|
||
|
||
```bash
|
||
# DashScope API配置（阿里云Qwen模型）
|
||
DASHSCOPE_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx
|
||
|
||
# Tavily搜索API配置
|
||
TAVILY_API_KEY=tvly-xxxxxxxxxxxxxxxxxxxxxxxx
|
||
```
|
||
|
||
### 获取API密钥
|
||
|
||
- **DashScope**: https://dashscope.aliyun.com/
|
||
1. 注册/登录阿里云账号
|
||
2. 开通通义千问服务
|
||
3. 获取API Key
|
||
|
||
- **Tavily**: https://tavily.com/
|
||
1. 注册账号
|
||
2. 获取免费API Key（支持1000次/月）
|
||
|
||
## 3. 验证安装
|
||
|
||
运行测试脚本验证环境：
|
||
|
||
```bash
|
||
# Windows Git Bash
|
||
export PYTHONIOENCODING=utf-8 && python tests/test_phase1_setup.py
|
||
|
||
# Linux/Mac
|
||
python tests/test_phase1_setup.py
|
||
```
|
||
|
||
如果所有测试通过，说明环境配置成功！
|
||
|
||
## 4. 开始使用
|
||
|
||
### 基础用法
|
||
|
||
```bash
|
||
# 执行研究（standard模式）
|
||
python -m src.main research "Python asyncio最佳实践"
|
||
```
|
||
|
||
### 高级用法
|
||
|
||
```bash
|
||
# 使用deep模式进行深度研究
|
||
python -m src.main research "量子计算最新进展" --depth deep
|
||
|
||
# 指定学术格式
|
||
python -m src.main research "机器学习可解释性" --format academic
|
||
|
||
# 保存报告到指定路径
|
||
python -m src.main research "微服务架构设计" --output report.md
|
||
|
||
# quick模式（快速研究，约2分钟）
|
||
python -m src.main research "Docker容器化" --depth quick
|
||
```
|
||
|
||
### 其他命令
|
||
|
||
```bash
|
||
# 查看配置
|
||
python -m src.main config --show
|
||
|
||
# 查看历史记录
|
||
python -m src.main history
|
||
|
||
# 查看指定历史记录
|
||
python -m src.main history --view research_20251031_120000
|
||
|
||
# 恢复之前的研究
|
||
python -m src.main resume research_20251031_120000
|
||
```
|
||
|
||
## 5. 深度模式说明
|
||
|
||
| 模式 | 迭代轮次 | 目标来源数 | 置信度目标 | 预期时长 | 适用场景 |
|
||
|------|---------|-----------|-----------|---------|---------|
|
||
| **quick** | 1-2 | 5-10 | 0.6 | ~2分钟 | 快速了解、简单问题 |
|
||
| **standard** | 2-3 | 10-20 | 0.7 | ~5分钟 | 日常研究、平衡速度和质量 |
|
||
| **deep** | 3-5 | 20-40 | 0.8 | ~10分钟 | 重要决策、高质量要求 |
|
||
|
||
## 6. 报告格式说明
|
||
|
||
- **technical** - 技术报告格式，面向开发者
|
||
- 包含代码示例
|
||
- 最佳实践
|
||
- 常见问题
|
||
|
||
- **academic** - 学术报告格式，面向研究者
|
||
- 结构化摘要
|
||
- 文献综述
|
||
- 引用规范
|
||
|
||
- **auto** - 自动选择格式（根据问题类型）
|
||
- 技术问题 → technical
|
||
- 学术问题 → academic
|
||
|
||
## 7. 常见问题
|
||
|
||
### Q1: API调用失败怎么办？
|
||
|
||
检查：
|
||
1. API密钥是否正确配置
|
||
2. 网络连接是否正常
|
||
3. API额度是否充足
|
||
|
||
### Q2: 研究结果置信度低怎么办？
|
||
|
||
解决方案：
|
||
1. 使用更高的深度模式（deep）
|
||
2. 尝试不同的问题表述
|
||
3. 检查是否有高质量来源
|
||
|
||
### Q3: 如何提高研究质量？
|
||
|
||
建议：
|
||
1. 使用deep模式
|
||
2. 提供更具体的问题
|
||
3. 使用英文问题（可获取更多高质量来源）
|
||
4. 设置更低的min-tier（如1或2）
|
||
|
||
### Q4: 如何查看详细的执行日志？
|
||
|
||
在代码中设置verbose=True：
|
||
```python
|
||
from src.agents.coordinator import run_research
|
||
|
||
result = run_research(
|
||
question="你的问题",
|
||
verbose=True # 显示详细日志
|
||
)
|
||
```
|
||
|
||
## 8. 示例场景
|
||
|
||
### 场景1: 学习新技术
|
||
|
||
```bash
|
||
# 快速了解技术概念
|
||
python -m src.main research "什么是Rust所有权系统" --depth quick
|
||
|
||
# 深入学习技术细节
|
||
python -m src.main research "Rust所有权系统实现原理" --depth deep
|
||
```
|
||
|
||
### 场景2: 技术选型
|
||
|
||
```bash
|
||
# 对比不同技术方案
|
||
python -m src.main research "gRPC vs REST API比较" --depth standard --format technical
|
||
```
|
||
|
||
### 场景3: 学术研究
|
||
|
||
```bash
|
||
# 学术文献综述
|
||
python -m src.main research "Transformer模型发展历程" --depth deep --format academic
|
||
```
|
||
|
||
### 场景4: 问题排查
|
||
|
||
```bash
|
||
# 快速查找解决方案
|
||
python -m src.main research "Python内存泄漏排查方法" --depth quick
|
||
```
|
||
|
||
## 9. 下一步
|
||
|
||
- 查看 [README.md](README.md) 了解项目架构
|
||
- 查看 [需求文档_V1.md](需求文档_V1.md) 了解功能详情
|
||
- 查看 [开发文档_V1.md](开发文档_V1.md) 了解技术实现
|
||
- 运行测试：`python -m pytest tests/`
|
||
|
||
## 10. 获取帮助
|
||
|
||
```bash
|
||
# 查看帮助
|
||
python -m src.main --help
|
||
|
||
# 查看specific命令帮助
|
||
python -m src.main research --help
|
||
python -m src.main config --help
|
||
python -m src.main history --help
|
||
```
|
||
|
||
---
|
||
|
||
祝你研究顺利！🚀
|