CoolFace
Apppublic

Paperman619/jesuits-china-letters

sourceHugging Faceupdated 10h agoView on Hugging Face
0likes
App README

《耶稣会士中国书简集：中国回忆录》数字人文智能分析平台

AI赋能文献研究 —— 基于大模型 + RAG 的历史文献智能检索与分析系统

项目简介

本平台以《耶稣会士中国书简集：中国回忆录》（上中下卷）为核心文本，通过 AI 智能语义检索与分析，辅助研究人员对 17-18 世纪西方传教士笔下的"中国形象"进行量化统计与质性分析。

核心研究问题：西方传教士构建了怎样的中国形象？又是如何构建的？

功能模块

| 📖 文献浏览 | 书简信件 + 《跨文化形象学》章节双 Tab，支持人工金标准分类 | | 🔍 智能问答 | 分轨 RAG（书简证据 + 周宁理论透镜），多会话管理，点名取文与追问分流 | | 📊 关键词统计 | 书简全文检索（不含理论文献）、频次统计与持久化 | | 🎯 中国形象分析 | 六大维度深度分析 + 建构策略识别 + 综合研究全覆盖流水线 | | 📚 文献管理 | 文献列表、多格式上传（TXT/DOCX/PDF）与可恢复多模态 OCR | | 📝 报告导出 | 导出含双页码出处与证据覆盖核验表格的完整 Word/Markdown 报告 | | 🩺 系统健康与验收 | 系统健康聚合看板、组件诊断、自动化验收套件与运维报告导出 |

技术栈

  • —Web 框架: Streamlit 1.53+
  • —大模型 API: DeepSeek V4 (Flash + Pro) / Qwen 3.7 Plus
  • —OCR: Qwen VL Max（多模态大模型）
  • —向量数据库: ChromaDB
  • —Embedding: BAAI/bge-large-zh-v1.5（本地运行）
  • —RAG: 自建混合检索（向量语义 + FTS5 关键词）
  • —关系数据库: SQLite + FTS5 全文索引
  • —可视化: Plotly

快速开始

1. 环境准备

bash
cd jesuits-china-letters

python -m venv .venv
# Windows:
.\.venv\Scripts\python -m pip install -r requirements.txt
.\.venv\Scripts\python scripts\run_tests.py
# Linux/Mac:
source .venv/bin/activate
python -m pip install -r requirements.txt
python scripts/run_tests.py

运行测试请使用项目虚拟环境入口，脚本会先检查解释器和关键依赖，避免误用 LibreOffice Python：

bash
.\.venv\Scripts\python scripts\run_tests.py

2. 配置 API Key

bash
# DeepSeek（必须，批处理 + 问答）
set DEEPSEEK_API_KEY=your_key        # Windows CMD
$env:DEEPSEEK_API_KEY="your_key"     # PowerShell
export DEEPSEEK_API_KEY=your_key     # Linux/Mac

# Qwen 通义千问（可选，OCR + 备选问答）
set DASHSCOPE_API_KEY=your_key

也可通过项目根目录 .env 或环境变量配置（不要把密钥写进仓库）。 如需轮换 Hugging Face 凭据或修复 remote，请遵循凭据轮换操作说明。

3. 运行数据处理管线

bash
# 如有扫描版 PDF 需先 OCR（需 DASHSCOPE_API_KEY）
python scripts/00_pdf_to_txt.py

# 依次运行（从项目根目录执行）
python scripts/01_preprocess.py        # 文本清洗
python scripts/02_split_letters.py     # 书简拆分入库（写入全局 letter_no 1–152）
python scripts/03_batch_analyze.py     # AI 批量分析书简（耗时较长）
python scripts/04_build_vectorstore.py # 书简向量化（只删 source_type=primary_source，写入 letter_no）

# 若已有旧版向量库只缺 letter_no metadata，可先做无重嵌入回填
# 有 ChromaDB 依赖时优先走 Chroma collection API；否则回退到本地 SQLite
python scripts/05_backfill_vector_letter_no.py

# 理论文献《跨文化形象学》（可选，与书简分轨）
python scripts/01_preprocess.py --corpus reference
python scripts/02b_split_chapters.py   # 章节切分；若用边界 JSON 须 confirmed: true
python scripts/03b_analyze_chapters.py
python scripts/04b_embed_chapters.py   # 只重建 source_type=reference，不删书简/上传

4. 启动应用

bash
streamlit run app/Home.py

浏览器自动打开 http://localhost:8501（Docker / Hugging Face Spaces 为 7860）。

智能问答可写「上卷16、书简16、第16封」点名取文；追问默认锁定上一轮书简。勾选「书简 / 形象学 / 我的文献」才会检索对应轨。侧栏「深度思考」默认关闭（显式关掉模型思考模式）。

项目结构

jesuits-china-letters/
├── config.py                    # 全局配置（API Key、模型、路径等）
├── requirements.txt
├── .gitignore
├── data/
│   ├── raw/                     # PDF 原始文件 + OCR 输出的 TXT
│   ├── processed/               # 清洗后文本（管线自动生成）
│   └── supplementary/           # 用户上传的补充文献
├── database/
│   └── letters.db               # SQLite 数据库（管线自动生成）
├── vectorstore/
│   └── chroma_db/               # ChromaDB 向量库（管线自动生成）
├── scripts/
│   ├── 00_pdf_to_txt.py         # PDF OCR
│   ├── 01_preprocess.py         # 文本清洗（可 --corpus reference）
│   ├── 02_split_letters.py      # 书简拆分
│   ├── 02b_split_chapters.py    # 理论章节切分
│   ├── 03_batch_analyze.py      # 书简批量 AI 分析
│   ├── 03b_analyze_chapters.py  # 理论章节分析
│   ├── 04_build_vectorstore.py  # 书简向量化（保留理论/上传）
│   ├── 04b_embed_chapters.py    # 理论向量化（保留书简/上传）
│   ├── 05_backfill_vector_letter_no.py # 为旧向量库补齐书简号 metadata
│   ├── run_acceptance.py        # 离线与真实模型自动化验收套件
│   ├── run_tests.py             # 带环境诊断与验收联动的 unittest 入口
│   └── utils.py                 # 共用工具函数
└── app/
    ├── Home.py                  # 主页仪表盘
    ├── pages/
    │   ├── 1_📖_文献浏览.py      # 书简 + 理论章节 + 人工分类
    │   ├── 2_📊_关键词检索.py    # 仅书简全文检索与统计
    │   ├── 3_🔍_智能问答.py      # 分轨 RAG 问答（点名/追问/上传）
    │   ├── 4_🎯_中国形象分析.py  # 中国形象专题分析与综合研究
    │   ├── 5_📚_文献管理.py      # 文献列表与用户上传
    │   ├── 6_📝_报告导出.py      # 报告导出（含双页码与覆盖表）
    │   └── 7_🩺_系统健康与验收.py # 系统健康监控与验收报告导出
    └── components/
        ├── db_manager.py        # 数据库操作
        ├── health_service.py    # 系统健康聚合监控服务
        ├── llm_client.py        # 大模型 API 封装（思考模式显式开关）
        ├── llm_orchestrator.py  # 统一模型编排与重试/引用校验
        ├── rag_engine.py        # retrieve_for_question 统一检索
        ├── letter_refs.py       # 书简号解析
        └── prompts.py           # 提示词模板

数据库表结构

表名用途
letters书简内容与元数据（含全书连续 letter_no 1–152）
keywordsAI 提取的语义关键词
theme_tagsAI 提取的主题标签与情感倾向
keyword_searches全文检索的关键词及频次（持久化）
keyword_occurrences关键词在每封信中的出处（含精确页码）
documents理论文献与用户上传元信息
letter_user_tags同学人工分类（金标准，不覆盖 AI 六维）
conversations问答对话会话
qa_history问答历史记录（关联 conversation，含双页码与覆盖表）
letters_ftsFTS5 全文索引（自动同步）

注意事项与运维指引

  • —全局书简身份：书简使用全局 1–152 连续编号；学术引用契约规范格式为：书简{n} · 卷次 · 篇名 · 印刷页码 (PDF第n页)，严禁将「引文 N」或「卡片 N」作为书简身份。
  • —持久化运行目录：系统运行时所有可变数据均集中管理于 APP_DATA_ROOT，支持容器或 Space 重启后无损恢复。
  • —运维与验收手册：
  • —部署与环境配置：`docs/operations/deployment-runbook.md`
  • —数据库备份恢复：`docs/operations/backup-restore-runbook.md`
  • —大模型故障排查：`docs/operations/model-troubleshooting.md`
  • —师生验收清单与记录：`docs/acceptance/法语学院验收清单.md` 与 `docs/acceptance/验收结果记录.md`
  • —批量分析（步骤3）和 OCR（步骤0）支持断点续传；Embedding 模型（约 1.3GB）首次使用会自动下载。
  • —网页上传限制为 50MB；PDF/DOCX 会先做轻量格式校验，扫描版由系统检测后支持可恢复多模态 OCR。
  • —运行完整离线验收：python scripts/run_acceptance.py --offline；全量单元测试联动：python scripts/run_tests.py --skip-env-check --acceptance。