DigAnnotation – 个人开发测试站

项目简介

DigAnnotation 是一个面向上市公司数字化转型研究的数据标注与挖掘平台。本平台依据吴非等（2021）提出的数字化转型分析框架，从企业年度报告中”管理层讨论与分析（MD&A）”部分提取与数字化转型相关的文本信息，通过大语言模型（LLM）对文本进行自动分类标注，帮助研究者量化数字化转型程度。

平台采用前后端分离架构：后端基于 Python FastAPI 提供 REST API，前端基于 Next.js 提供可视化操作界面，支持断点续传、并发控制、实时进度推送等功能。

理论基础

本平台的分类体系依据以下文献构建：

吴非、胡慧芷、林慧妍、任晓怡. 企业数字化转型与资本市场表现——来自股票流动性的经验证据[J]. 管理世界, 2021, 37(07): 130-144+10.

该框架从”基础技术”与”技术应用”两个维度出发，设定五大核心主题及一个兜底类别：

维度	主题	关键词示例
基础技术	人工智能技术	机器学习、深度学习、自然语言处理、计算机视觉等
基础技术	大数据技术	大数据、数据挖掘、文本挖掘、数据可视化等
基础技术	云计算技术	云计算、物联网、信息物理系统、边缘计算等
基础技术	区块链技术	区块链、数字货币、分布式计算、智能合约等
技术应用	数字技术应用	电子商务、移动支付、工业互联网、智能制造等
—	其他类别	不涉及上述任何数字技术主题的文本

功能特性

年报文本预处理：从上市公司 PDF 年报中提取 MD&A 部分，按年份和股票代码归档
LLM 自动标注：调用大语言模型对 MD&A 句子进行六分类标注，支持多种模型接入
断点续传：基于 SQLite 记录处理进度，支持中断后继续处理，避免重复调用
并发控制：可配置并发数和批次大小，平衡处理速度与 API 限流
实时进度推送：通过 SSE（Server-Sent Events）实时推送处理进度和日志
错误重跑：对标注失败的记录支持一键 AI 重跑或人工重新标注
结果导出：支持导出 CSV 统计表格、JSONL 原始数据、逐股票明细文件
可视化统计：通过堆叠柱状图和饼图展示各类别分布情况
提示词可配置：支持在线编辑和保存标注提示词模板

技术架构

+-------------------+          +-------------------+
|                   |   HTTP   |                   |
|   Frontend        | <------> |   Backend         |
|   (Next.js 14)   |   REST   |   (FastAPI)       |
|   Port: 3000     |   API    |   Port: 8000      |
|                   |          |                   |
+-------------------+          +--------+----------+
                                       |
                                       v
                              +--------+----------+
                              |                   |
                              |   SQLite Database |
                              |   (进度与结果)     |
                              |                   |
                              +--------+----------+
                                       |
                                       v
                              +--------+----------+
                              |                   |
                              |   LLM API         |
                              |   (可配置模型)     |
                              |                   |
                              +-------------------+

层级	技术栈
前端	Next.js 14 (App Router)、React 18、TypeScript、TailwindCSS、Recharts
后端	Python、FastAPI、httpx（异步 HTTP）、PyYAML、Pydantic
存储	SQLite
LLM	支持 OpenAI 兼容接口（可配置 base_url 和 model）

项目结构

DigAnnotation/
├── README.md                    # 项目说明（英文）
├── README_zh.md                 # 项目说明（中文）
├── LICENSE                      # GPL v3 开源协议
├── 启动后端.bat                  # Windows 后端启动脚本
├── 启动前端.bat                  # Windows 前端启动脚本
├── backend/                     # 后端目录
│   ├── app.py                   # FastAPI 主程序（路由与 API）
│   ├── config.py                # 配置加载与保存
│   ├── config.yaml              # 运行配置文件
│   ├── database.py              # SQLite 数据库操作
│   ├── processor.py             # 标注处理器（LLM 调用）
│   ├── preprocessor.py          # 年报文本预处理器
│   ├── scanner.py               # 文件扫描器
│   ├── requirements.txt         # Python 依赖
│   ├── templates/               # 提示词模板目录
│   │   └── prompt_template.txt  # 标注提示词模板
│   └── data/                    # 输出数据目录
└── frontend/                    # 前端目录
    ├── app/
    │   ├── page.tsx             # 首页（配置 + 进度 + 结果）
    │   ├── config/page.tsx      # 提示词配置页
    │   ├── results/page.tsx     # 历史结果页
    │   └── preprocess/page.tsx  # 预处理页
    ├── components/              # React 组件
    ├── lib/api.ts               # 后端 API 封装
    ├── package.json             # Node.js 依赖
    └── tailwind.config.js       # TailwindCSS 配置

快速开始

环境要求

Python >= 3.8
Node.js >= 18
npm 或 yarn

安装与运行

1. 克隆项目

git clone https://github.com/yourusername/DigAnnotation.git
cd DigAnnotation

2. 启动后端

cd backend
pip install -r requirements.txt
python app.py

后端将在 http://localhost:8000 启动。

3. 启动前端

cd frontend
npm install
npm run dev

前端将在 http://localhost:3000 启动。

Windows 用户可直接双击 启动后端.bat 和 启动前端.bat。

配置说明

编辑 backend/config.yaml 进行配置：

api:
  api_key: "your-api-key"           # LLM API 密钥
  base_url: "https://api.example.com"  # API 地址
  model: "model-name"               # 模型名称
  max_concurrency: 5                # 最大并发数
  retry_times: 3                    # 失败重试次数

processing:
  input_dir: "/path/to/mda/files"   # 输入目录（年报 MD&A 文件）
  output_dir: "/path/to/output"     # 输出目录
  mode: continue                    # continue=断点续传 | restart=重新开始
  start_year: 2012                  # 起始年份
  end_year: 2024                    # 结束年份

使用流程

在首页配置 API 密钥、模型、输入输出目录等参数
进入预处理页面，选择年份范围，对原始年报进行文本提取
返回首页，设置年份范围，点击”开始处理”启动标注任务
通过进度面板实时查看处理进度和日志
处理完成后，在结果页查看统计数据并导出 CSV/JSONL

API 接口

端点	方法	说明
`/api/config`	GET / PUT	获取 / 更新配置
`/api/scan`	GET	扫描输入目录文件
`/api/start`	POST	启动标注任务
`/api/stop`	POST	停止标注任务
`/api/status`	GET	获取任务状态
`/api/status/stream`	GET	SSE 实时进度推送
`/api/results/summary`	GET	获取结果汇总
`/api/results/{year}`	GET	下载某年 CSV
`/api/results/{year}/jsonl`	GET	下载某年 JSONL
`/api/results/{year}/stocks`	GET	分页查询某年股票
`/api/errors/summary`	GET	获取错误汇总
`/api/errors/{year}/rerun-ai`	POST	AI 重跑某年错误
`/api/preprocess/start`	POST	启动预处理任务
`/api/clear-results`	POST	清空所有结果

参考文献

吴非、胡慧芷、林慧妍、任晓怡. 企业数字化转型与资本市场表现——来自股票流动性的经验证据[J]. 管理世界, 2021, 37(07): 130-144+10.

贡献

欢迎提交 Issue 和 Pull Request。对于重大变更，请先打开 Issue 讨论。

许可证

本项目采用 GNU General Public License v3.0 开源协议。

本程序是自由软件：你可以再分发之和/或修改之，依据的是 GNU 通用公共许可证，
由自由软件基金会发布，版本 3 或（由你选择的）任何更新的版本。

本程序的发布目的是希望它是有用的，但没有任何担保，甚至没有适销性或特定用途适用性的
隐含担保。详见 GNU 通用公共许可证了解更多细节。