企业研报智能体

赛段：S1W3
项目版本：v3

企业研报智能体是一个面向企业年报、研报、财报和行业资料的智能分析系统。v3 版本在原有 PDF 知识库、RAG 问答和研报生成基础上，完成了平台化升级：引入用户认证与多用户隔离、LangChain / LangGraph 智能体编排、真正的 SSE 流式输出、异步文档入库任务、OCR、用户自定义模型配置、自定义报告模板、表格结构化抽取、财务指标入表和语义化企业能力评分。

系统仍保持核心链路：上传 PDF -> 解析 / OCR -> chunking -> embedding -> retriever -> agent 编排 -> Markdown 生成 -> PDF 导出。

v3 更新摘要

• 用户体系：支持注册、登录、JWT 鉴权和按 user_id 隔离知识库、文档、对话、报告、评分、模型配置和报告模板。
• 文档入库：上传 PDF 默认进入 SQLite 轻量任务队列，后台异步完成解析、OCR、分块、embedding 和向量入库。
• OCR：集成 Tesseract，支持扫描件 PDF 页面文本不足时自动 OCR，默认语言为 chi_sim+eng。
• LangChain / LangGraph：文档切分、embedding、retriever、LLM answer、web search tool、报告生成和评分流程统一接入 LangChain，并由 LangGraph 编排。
• 真流式输出：问答和报告生成新增 SSE 接口，前端使用 fetch + ReadableStream 增量渲染 Markdown。
• 多轮对话：问答从单次 QA 升级为多会话消息流，加入历史摘要和 token 预算截断策略。
• 用户模型配置：登录后可配置 OpenAI-compatible 模型，填写模型名、API Key、Base URL 后即可用于问答、报告和评分。
• 联网搜索：web research 抽象为 provider registry，默认 DuckDuckGo，并预留 Bing / SerpAPI provider。
• 报告模板：支持用户自定义章节结构，按模板生成 Markdown，再转换为 PDF。
• 语义化企业评分：评分 Agent 使用 LLM 结构化语义评估，结合知识库证据、财务指标和联网资料输出总分、维度分、置信度和原因。
• 前端体验：使用项目目录 skills/frontend-design 的设计原则优化专业投研控制台，支持消息流、任务进度、模型配置、模板管理和评分可视化。

项目展示

展示素材位于仓库内 show/ 目录。

文件预览

多轮问答

报告生成

企业评分

自定义模型配置

自定义报告模板

当前功能

1. 用户与权限

• 用户注册、登录、当前用户信息查询。
• JWT 鉴权，前端自动携带 Authorization: Bearer <token>。
• 知识库、文档、对话、报告、评分、模型配置、报告模板按用户隔离。
• 首个注册用户为 admin，并接管升级前历史数据。
• 非本人资源访问返回 404，避免泄露资源存在性。

2. 知识库与文档

• 多知识库管理：新建、重命名、删除。
• PDF 上传、替换、删除、批量删除和在线预览。
• 上传后立即返回任务，后台异步索引。
• 文档状态支持 queued、processing、indexed、failed。
• 任务进度接口支持轮询和 SSE 事件。
• PDF 预览和报告下载支持登录鉴权。

3. 文档解析、表格和财务指标

• PyMuPDF 解析 PDF 文本、页码和表格。
• 页面文本过少时自动调用 Tesseract OCR。
• LangChain RecursiveCharacterTextSplitter 完成 chunking。
• 表格作为 chunk_type="table" 的 Document 入库，参与问答、报告和评分检索。
• document_tables 保存结构化表格。
• financial_metrics 自动识别常见财务指标：营业收入、净利润、归母净利润、毛利率、净利率、经营现金流、资产负债率、ROE、研发费用、研发费用率等。

4. RAG 问答

• 支持按知识库问答，也支持限定单个文档问答。
• 支持多会话、多轮对话和历史消息查看。
• 使用 token 预算 + 最近消息 + 历史摘要控制上下文长度。
• 新增 SSE 流式接口，前端实时渲染 Markdown。
• 引用证据仅显示文档名、页码和章节，不展示证据原文，避免乱码和界面噪声。

5. 报告生成

• 根据主题从知识库检索证据，并调用联网搜索补充公开资料。
• 支持同步生成和 SSE 流式生成。
• 支持用户自定义报告模板。
• 报告正文先生成 Markdown，再转换为 PDF。
• 支持 Markdown 导出、PDF 下载和在线 PDF 预览。
• 优化 Markdown 表格到 PDF 的排版稳定性。

6. 企业能力评分 Agent

评分维度总分 100 分：

• 财务健康与盈利质量：25
• 成长性与业务韧性：20
• 行业地位与竞争壁垒：20
• 创新能力与研发投入：15
• 治理合规与风险控制：10
• 外部舆情与可持续发展：10

v3 已将评分从“证据数量公式”升级为“LLM 结构化语义评估 + 规则兜底”：

• 每个维度先检索候选证据，再由 LLM 判断相关性和质量。
• 输入包含维度定义、rubric、内部证据、财务指标、联网资料和数据缺口。
• 输出包含 score、confidence、rationale、key_facts、data_gaps、evidence_assessments、metric_assessments、web_assessments。
• 无模型或 mock 模式下使用 deterministic fallback，并标记 scoring_method="rule_fallback"。
• 前端展示总分、评级、置信度、维度分数条、说明、数据缺口和来源定位。

7. 用户模型配置

登录后可在前端配置模型：

• display_name：展示名称。
• provider：当前优先支持 openai_compatible。
• base_url：例如 https://api.deepseek.com。
• model_name：例如 deepseek-v4-flash、deepseek-v4-pro 或其他兼容模型名。
• api_key：写入数据库前加密，响应不回显明文。

问答、报告和评分请求可指定模型配置；未指定时使用用户 active model；无用户配置时回退 .env 环境变量。

技术栈

• 前端：React、Vite、Ant Design
• 后端：FastAPI、SQLite、PyMuPDF、Tesseract OCR
• 智能体框架：LangChain、LangGraph
• 向量库：Milvus，测试和离线演示可使用 Memory Vector Store
• Embedding：sentence-transformers，默认 BAAI/bge-small-zh-v1.5；支持 hash fallback
• LLM：OpenAI-compatible Chat Model，默认 DeepSeek 配置；支持 mock 模式
• 联网搜索：LangChain tool 封装 DuckDuckGo / DDGS，预留 Bing / SerpAPI
• 报告导出：Markdown 原文导出，Markdown 渲染为 PDF
• 前端设计：项目内 skills/frontend-design，来源为 anthropics/skills

环境准备

推荐使用 conda 环境，不要把依赖安装到用户 site。

conda env create -f environment.yml
conda activate enterprise-report-agent

如果已经存在环境，可更新依赖：

conda env update -p "D:\Anaconda_envs\envs\enterprise-report-agent" -f environment.yml --prune

手动安装 Python 依赖时，使用明确解释器和 --no-user：

$env:PYTHONNOUSERSITE="1"
& "D:\Anaconda_envs\envs\enterprise-report-agent\python.exe" -m pip install --no-user -r requirements.txt

前端依赖：

cd frontend
npm install

配置

复制 .env.example 为 .env：

Copy-Item .env.example .env

LLM

LLM_MODE=openai
LLM_BASE_URL=https://api.deepseek.com
LLM_MODEL=deepseek-v4-flash
DEEPSEEK_API_KEY=your-deepseek-key

也可以使用通用变量：

LLM_API_KEY=your-api-key

无 API Key 时系统会走 mock 路径，便于离线演示和测试。

Embedding

EMBEDDING_BACKEND=sentence_transformers
EMBEDDING_MODEL=BAAI/bge-small-zh-v1.5
EMBEDDING_ALLOW_HASH_FALLBACK=true
HASH_EMBEDDING_DIM=384

无法访问 HuggingFace 时可使用：

EMBEDDING_BACKEND=hash

OCR

v3 默认启用 Tesseract OCR：

OCR_ENABLED=true
OCR_ENGINE=tesseract
OCR_LANG=chi_sim+eng
OCR_MIN_TEXT_CHARS=40

如果 Tesseract 没有在 PATH 中，可显式指定：

TESSERACT_CMD=D:\Anaconda_envs\envs\enterprise-report-agent\Library\bin\tesseract.exe

Web Research

WEB_RESEARCH_ENABLED=true
WEB_RESEARCH_PROVIDER=duckduckgo
WEB_RESEARCH_MAX_RESULTS=4
WEB_RESEARCH_TIMEOUT_SECONDS=6

可选：

BING_SEARCH_API_KEY=your-bing-key
SERPAPI_API_KEY=your-serpapi-key

Auth

AUTH_ENABLED=true
APP_SECRET=change-me-in-production
JWT_EXPIRE_MINUTES=10080

生产环境必须设置稳定的 APP_SECRET，否则 token 和 API Key 加密会受影响。

运行

必须在项目根目录运行后端，也就是包含 backend、frontend、README.md 的目录。

启动 Milvus：

docker compose up -d

启动后端：

python -m uvicorn backend.main:app --reload

如果当前 shell 的 PATH 不稳定，可直接使用 conda 环境解释器：

& "D:\Anaconda_envs\envs\enterprise-report-agent\python.exe" -m uvicorn backend.main:app --reload --host 127.0.0.1 --port 8000

启动前端：

cd frontend
npm run dev

默认访问：

• 前端：http://127.0.0.1:5173
• 后端文档：http://127.0.0.1:8000/docs
• Milvus：127.0.0.1:19530

如果 5173 被占用，Vite 可能自动使用 5174，请以终端输出为准。

主要 API

Auth

• POST /api/auth/register
• POST /api/auth/login
• GET /api/auth/me

Knowledge Base / Document

• GET /api/knowledge-bases
• POST /api/knowledge-bases
• PATCH /api/knowledge-bases/{id}
• DELETE /api/knowledge-bases/{id}
• GET /api/documents
• GET /api/knowledge-bases/{id}/documents
• POST /api/knowledge-bases/{id}/documents/upload
• PUT /api/documents/{id}/replace
• DELETE /api/documents/{id}
• GET /api/documents/{id}/preview
• GET /api/documents/{id}/tables
• GET /api/knowledge-bases/{id}/financial-metrics

Tasks

• GET /api/tasks
• GET /api/tasks/{task_id}
• GET /api/tasks/{task_id}/events

Chat

• POST /api/chat/ask
• POST /api/chat/ask/stream
• GET /api/chat/conversations
• POST /api/chat/conversations
• GET /api/chat/conversations/{id}/messages
• DELETE /api/chat/conversations/{id}

Reports

• POST /api/reports/generate
• POST /api/reports/generate/stream
• GET /api/reports
• GET /api/reports/{id}
• DELETE /api/reports/{id}
• GET /api/reports/{id}/export.md
• GET /api/reports/{id}/export.pdf
• GET /api/reports/{id}/preview.pdf

Scores

• POST /api/scores/generate
• GET /api/scores
• GET /api/scores/{id}
• DELETE /api/scores/{id}

User Model Configs / Report Templates

• GET /api/model-configs
• POST /api/model-configs
• PATCH /api/model-configs/{id}
• POST /api/model-configs/{id}/activate
• DELETE /api/model-configs/{id}
• GET /api/report-templates
• POST /api/report-templates
• PATCH /api/report-templates/{id}
• DELETE /api/report-templates/{id}

测试

默认测试使用 hash embedding、内存向量库和 mock LLM，不依赖真实模型 API。

pytest

运行 Milvus 集成测试前先启动 Milvus：

docker compose up -d
$env:RUN_MILVUS_TESTS="1"
pytest tests/test_milvus_store.py

前端构建：

cd frontend
npm run build

常见问题

启动时报 No module named backend

请先进入项目根目录：

cd "D:\文件\技术学习\Enterprise Research Report Agent\enterprise-report-agent"
python -m uvicorn backend.main:app --reload

端口 8000 报权限或占用

检查占用：

netstat -ano | findstr :8000

也可以换端口：

python -m uvicorn backend.main:app --reload --host 127.0.0.1 --port 8001

OCR 找不到 Tesseract

确认 conda 环境里有 Tesseract：

conda list -p "D:\Anaconda_envs\envs\enterprise-report-agent" tesseract

必要时显式配置：

TESSERACT_CMD=D:\Anaconda_envs\envs\enterprise-report-agent\Library\bin\tesseract.exe
OCR_LANG=chi_sim+eng

HuggingFace 模型下载慢

可临时切换为 hash embedding：

EMBEDDING_BACKEND=hash

iframe 预览提示未登录

v3 已支持给 PDF 预览和报告导出链接附加登录 token。若仍出现该问题，请重新登录并刷新前端。

v3 已知边界

• OCR 已支持扫描件文本检索，但扫描件表格结构化抽取仍不保证高精度。
• Web search 质量受搜索 provider 和网络环境影响，搜索失败时会自动降级为空引用。
• Claude、GLM 等模型优先通过 OpenAI-compatible 网关接入；原生 provider 适配可继续扩展。
• 任务队列为 SQLite in-process worker，适合课程项目和单机演示；生产场景可升级为 Redis / Celery。