🔩

报告后端 deep-research-python

基于 FastAPI 的智能研究报告生成服务。编排 5 步研究流水线，读取舆情素材，调 LLM 逐章撰写，SSE 流式输出，并渲染图表。

FastAPI Python 3.11 LangChain MongoDB Redis SSE :8000

本页导航

# 一、接口（`api/`，经 `setup_routers()` 注册）

统一响应格式 {code, message, data, timestamp}；鉴权头 Authorization / X-Tenant-Id / X-User-Id；流水线步骤均返回 SSE 流。完整文档见 /docs。

路由文件	路径/职责
`api_report.py`	`/report` — 报告 CRUD（如 `POST /report/create`）
`api_write_report_*.py`	每个流水线步骤一个路由：`/ask_questions`、`/write_report_plan`、`/write_report_serp`、`/write_report_search_summary`、`/write_report_final`
`api_write_report_value_extract.py`	从章节做结构化数值抽取
`api_write_report_indicator.py`	财务指标计算
`api_custom_api.py`	自定义 API 配置管理
`api_report_chat.py`	报告生成后的问答

# 二、服务层（`services/`）

模块	职责
`llm_service.py`	LangChain `ChatOpenAI` 封装；支持流式、经 ReAct agent 的 MCP 工具调用
`mongo_api_service_manager.py`	流水线编排器：MongoDB → 构造提示词 → LLM → 存储 → SSE 流
`mongo_stream_storage_service.py`	处理流式 LLM 响应到 SSE + MongoDB 持久化
`report_service.py`	报告 CRUD（MongoDB `reports` 集合），带 5 步进度跟踪
`step_record_service.py`	管理每步的 MongoDB 集合
`search_service.py`	web 搜索（Sogou/Tavily）+ Insight MySQL 查询
`knowledge_service.py`	内部知识库 REST 集成
`custom_api_caller_service.py`	执行用户自定义外部 API（含鉴权/模板）
`indicator_service.py`	财务指标，LLM 公式翻译
`oss_service.py`	MinIO 对象存储（图片）

# 三、基础设施层（`utils/` · `models/`）

模块	职责
`utils/database.py`	Redis + MongoDB 连接
`utils/dependencies.py`	`GlobalHeaderMiddleware`：把 Token/TenantId 提取进 `ContextVar`
`utils/response_models.py`	统一 `Result{code,message,data}` 封装；`BizError` 异常
`utils/echarts_renderer.py`	解析 `echarts` 代码块 → 调 Node.js 渲染 → 上传 PNG 到 MinIO
`utils/exception_handler.py`	全局异常处理 + `ErrorCode` 枚举
`models/mongo_models.py`	MongoDB 文档模型（reports/templates/variables）
`models/step_models.py`	每步记录模型

# 四、关键模式

SSE 流式：所有流水线步骤返回 StreamingResponse（text/event-stream）。
ContextVar 鉴权：Token/TenantId 通过异步上下文传播，而非函数参数。
任务级 LLM 路由：每个流水线步骤可用不同 LLM 模型，经 LLM_ENTITY 配置。
动态模型注册：config.py 用 LLM_MODEL_{name}_NAME/URL/KEY 构建模型注册表，LLM_ENTITY_{task} 把步骤映射到模型别名。

# 五、配置

Pydantic BaseSettings，APP_ENV 选择 .env.{APP_ENV}（dev/test/prod）。Python 严格要求 >=3.11,<3.12。

数据库

MongoDB（共享库 deep-research，读舆情素材 sentiment_data）+ Redis 缓存

对象存储

MinIO（报告图片与图表 PNG）

图表微服务

ECharts server：cd echarts-server && npm install && node server.js（端口 3000）

LLM

动态模型配置，任务级路由到不同模型

# 六、部署

运行依赖

依赖	类别	端口 / 标识	必需性	说明
MongoDB	数据库	`27017` · 库 `deep-research`	✅ 必需	读舆情素材 `sentiment_data`、存报告 `reports`，与采集端共享
Redis	缓存	—	✅ 必需	`utils/database.py` 与 MongoDB 一同初始化
MinIO	对象存储	—	⚙ 图表导出必需	`services/oss_service.py`：报告图片与 ECharts 渲染出的 PNG
ECharts 渲染服务	渲染微服务	`3000`	⚙ 图表导出必需	Node.js 微服务，把报告 `echarts` 代码块渲染成 PNG
LLM（动态注册）	外部服务	`LLM_MODEL_` / `LLM_ENTITY_`	✅ 必需	逐章撰写；任务级路由到不同模型

MinIO 与 ECharts 服务服务于报告图表导出这条支线：报告正文里的 echarts 代码块经 utils/echarts_renderer.py 调 ECharts 服务渲成 PNG，再传 MinIO。不导出带图报告时这两者非强制。

# 本地开发
pip install -r requirements.txt
APP_ENV=dev uvicorn main:app --host 0.0.0.0 --port 8000 --reload
# 服务: http://localhost:8000   文档: http://localhost:8000/docs

# Docker（用 APP_ENV 指定环境）
APP_ENV=prod docker-compose up -d
docker-compose logs -f
docker-compose down

# 单独构建/运行
docker build -t deep-research-api .
docker run -d --name deep-research-api -p 8000:8000 -e APP_ENV=prod deep-research-api

环境要求：Python 3.11+、MongoDB、Redis、MinIO、ECharts 渲染服务（:3000）、Docker（可选）。Docker 用私有基础镜像 192.168.111.90:30002/ai/python:3.11-slim。