758 lines
22 KiB
Markdown
758 lines
22 KiB
Markdown
# Story Extractor — 后端架构设计文档
|
||
|
||
> 版本：v1.3 · 2026-04-21
|
||
|
||
---
|
||
|
||
## 一、架构总览
|
||
|
||
### 1.1 技术栈
|
||
|
||
| 层级 | 技术 | 选型理由 |
|
||
|------|------|----------|
|
||
| **Web 框架** | FastAPI | 异步支持、自动 API 文档、类型提示、高性能 |
|
||
| **前端** | Vue 3 + Element Plus | 组件丰富、中文生态好、适合管理类交互 |
|
||
| **数据库** | SQLite | 轻量零安装、局域网场景够用、后续可迁移 |
|
||
| **LLM 接口** | OpenAI Python SDK（兼容协议） | 一套代码适配 OpenAI / DeepSeek / 通义千问 / Ollama |
|
||
| **DOCX 处理** | python-docx | 读写 DOCX 的标准 Python 库 |
|
||
| **部署** | Docker Compose | 一键启动，局域网分发方便 |
|
||
|
||
> **设计原则：极简架构**，不引入 Redis、Celery、Nginx 等外部依赖，全部基于 FastAPI 原生能力。
|
||
|
||
### 1.2 系统架构图
|
||
|
||
```
|
||
┌──────────────────┐
|
||
│ 浏览器 (Vue 3) │
|
||
└────────┬─────────┘
|
||
│ HTTP / SSE
|
||
┌────────┴─────────┐
|
||
│ │
|
||
┌──────┴──────┐ ┌────────┴──┐
|
||
│ FastAPI │ │ SQLite │
|
||
│ (Web + API │ │ (数据库) │
|
||
│ + 静态托管 │ │ │
|
||
│ + 后台任务) │ │ │
|
||
└──────┬──────┘ └───────────┘
|
||
│
|
||
┌───────────┼───────────┐
|
||
│ │ │
|
||
┌─────┴─────┐ ┌──┴───┐ ┌────┴────┐
|
||
│ 预处理器 │ │ LLM │ │ DOCX │
|
||
│ + 提取器 │ │ 服务 │ │ 生成器 │
|
||
└───────────┘ └──────┘ └─────────┘
|
||
```
|
||
|
||
**极简设计**：
|
||
- ❌ 无 Redis（进度追踪用内存）
|
||
- ❌ 无 Celery（后台任务用 asyncio）
|
||
- ❌ 无 Nginx（FastAPI 托管静态文件）
|
||
- ✅ **单容器部署**，一键启动
|
||
|
||
### 1.3 项目目录结构
|
||
|
||
```
|
||
story-extractor/
|
||
├── docker-compose.yml
|
||
├── Dockerfile
|
||
├── requirements.txt
|
||
├── .env.example
|
||
│
|
||
├── backend/
|
||
│ ├── app/
|
||
│ │ ├── __init__.py
|
||
│ │ ├── main.py # FastAPI 入口，路由注册，SSE
|
||
│ │ ├── config.py # 配置管理（读取 .env）
|
||
│ │ ├── database.py # SQLite 连接与 ORM
|
||
│ │ ├── state.py # 内存状态管理（进度追踪）
|
||
│ │ │
|
||
│ │ ├── api/ # API 路由层
|
||
│ │ │ ├── __init__.py
|
||
│ │ │ ├── files.py # 文件上传/删除/列表
|
||
│ │ │ ├── extraction.py # 提取任务管理
|
||
│ │ │ ├── stories.py # 故事 CRUD（含删除）
|
||
│ │ │ ├── matching.py # 匹配关系管理
|
||
│ │ │ ├── export.py # 预览与导出
|
||
│ │ │ └── settings.py # 系统配置
|
||
│ │ │
|
||
│ │ ├── models/ # 数据模型（SQLAlchemy）
|
||
│ │ │ ├── __init__.py
|
||
│ │ │ ├── transcript.py
|
||
│ │ │ ├── person.py
|
||
│ │ │ ├── story.py
|
||
│ │ │ └── config.py
|
||
│ │ │
|
||
│ │ ├── schemas/ # Pydantic 请求/响应模型
|
||
│ │ │ ├── __init__.py
|
||
│ │ │ ├── file.py
|
||
│ │ │ ├── story.py
|
||
│ │ │ ├── match.py
|
||
│ │ │ └── config.py
|
||
│ │ │
|
||
│ │ └── services/ # 业务逻辑层
|
||
│ │ ├── __init__.py
|
||
│ │ ├── file_service.py # 文件存储与管理
|
||
│ │ ├── docx_parser.py # DOCX 解析
|
||
│ │ ├── preprocessor.py # 预处理（过滤非故事内容）
|
||
│ │ ├── extractor.py # 故事提取核心（三阶段 Pipeline）
|
||
│ │ ├── llm_client.py # LLM 抽象层
|
||
│ │ ├── match_service.py # 匹配关系管理
|
||
│ │ └── docx_generator.py # 最终 DOCX 生成
|
||
│ │
|
||
│ ├── uploads/ # 上传文件存储
|
||
│ │ ├── transcripts/
|
||
│ │ └── persons/
|
||
│ │
|
||
│ └── exports/ # 导出文件存储
|
||
│
|
||
├── frontend/ # Vue 3 前端项目
|
||
│ ├── src/
|
||
│ │ ├── views/
|
||
│ │ │ ├── WelcomeView.vue
|
||
│ │ │ ├── UploadView.vue
|
||
│ │ │ ├── ExtractView.vue
|
||
│ │ │ ├── MatchView.vue
|
||
│ │ │ └── ExportView.vue
|
||
│ │ ├── components/
|
||
│ │ │ ├── Stepper.vue
|
||
│ │ │ ├── BottomNav.vue
|
||
│ │ │ ├── UploadZone.vue
|
||
│ │ │ ├── StoryCard.vue
|
||
│ │ │ ├── PersonCard.vue
|
||
│ │ │ ├── MatchPanel.vue
|
||
│ │ │ ├── DocPreview.vue
|
||
│ │ │ ├── SettingsModal.vue
|
||
│ │ │ └── Toast.vue
|
||
│ │ ├── api/
|
||
│ │ │ └── index.js
|
||
│ │ ├── stores/
|
||
│ │ │ └── app.js
|
||
│ │ ├── App.vue
|
||
│ │ └── main.js
|
||
│ ├── package.json
|
||
│ └── vite.config.js
|
||
│
|
||
├── Dockerfile
|
||
├── docker-compose.yml
|
||
├── requirements.txt
|
||
└── .env.example
|
||
```
|
||
|
||
---
|
||
|
||
## 二、API 设计
|
||
|
||
### 2.1 API 总览
|
||
|
||
所有 API 以 `/api/v1` 为前缀。
|
||
|
||
| 模块 | 方法 | 路径 | 说明 |
|
||
|------|------|------|------|
|
||
| **文件** | POST | `/api/v1/files/transcripts` | 上传文字稿（支持批量） |
|
||
| | POST | `/api/v1/files/persons` | 上传讲述者信息（支持批量） |
|
||
| | GET | `/api/v1/files/transcripts` | 获取文字稿列表 |
|
||
| | GET | `/api/v1/files/persons` | 获取讲述者列表 |
|
||
| | DELETE | `/api/v1/files/transcripts/{id}` | 删除文字稿 |
|
||
| | DELETE | `/api/v1/files/persons/{id}` | 删除讲述者信息 |
|
||
| | GET | `/api/v1/files/persons/{id}/preview` | 预览讲述者信息 |
|
||
| **提取** | POST | `/api/v1/extraction/start` | 启动提取任务（后台异步） |
|
||
| | GET | `/api/v1/extraction/status` | 获取提取进度 |
|
||
| | GET | `/api/v1/extraction/status/stream` | SSE 实时进度推送 |
|
||
| | POST | `/api/v1/extraction/stop` | 停止提取任务 |
|
||
| **故事** | GET | `/api/v1/stories` | 获取故事列表（支持筛选） |
|
||
| | GET | `/api/v1/stories/{id}` | 获取故事详情 |
|
||
| | PUT | `/api/v1/stories/{id}` | 编辑故事 |
|
||
| | DELETE | `/api/v1/stories/{id}` | 删除故事 |
|
||
| **匹配** | POST | `/api/v1/matches` | 创建匹配关系 |
|
||
| | DELETE | `/api/v1/matches/{story_id}` | 取消匹配 |
|
||
| | GET | `/api/v1/matches` | 获取所有匹配关系 |
|
||
| **导出** | GET | `/api/v1/export/preview/{person_id}` | 预览文档 |
|
||
| | GET | `/api/v1/export/download/{person_id}` | 下载单个 DOCX |
|
||
| | GET | `/api/v1/export/download-all` | 批量下载 ZIP |
|
||
| | GET | `/api/v1/export/list` | 获取导出列表 |
|
||
| **设置** | GET | `/api/v1/settings` | 获取系统配置 |
|
||
| | PUT | `/api/v1/settings` | 更新系统配置 |
|
||
| | POST | `/api/v1/settings/test-llm` | 测试 LLM 连接 |
|
||
|
||
### 2.2 关键 API 详细设计
|
||
|
||
#### 启动提取任务
|
||
|
||
```
|
||
POST /api/v1/extraction/start
|
||
```
|
||
|
||
**响应**：
|
||
```json
|
||
{
|
||
"task_id": "uuid",
|
||
"status": "started",
|
||
"total_files": 10
|
||
}
|
||
```
|
||
|
||
#### SSE 实时进度推送
|
||
|
||
```
|
||
GET /api/v1/extraction/status/stream
|
||
```
|
||
|
||
**实现方式**：FastAPI `StreamingResponse` + `asyncio.Queue`
|
||
|
||
```python
|
||
@router.get("/extraction/status/stream")
|
||
async def stream_progress():
|
||
async def event_generator():
|
||
while True:
|
||
data = await extraction_state.get_update()
|
||
yield f"event: progress\ndata: {json.dumps(data)}\n\n"
|
||
if data.get("status") == "completed":
|
||
break
|
||
return StreamingResponse(event_generator(), media_type="text/event-stream")
|
||
```
|
||
|
||
**SSE 事件格式**：
|
||
```
|
||
event: progress
|
||
data: {
|
||
"percent": 35,
|
||
"current_file": "2026年1月21日 第10营训练营.docx",
|
||
"action": "故事识别：检测学员发言...",
|
||
"files_read": 3,
|
||
"files_total": 10,
|
||
"segments_found": 42,
|
||
"stories_found": 2
|
||
}
|
||
|
||
event: story_found
|
||
data: {
|
||
"id": "uuid",
|
||
"title": "代际传承的体罚创伤",
|
||
"speaker_nickname": "14班+HCM",
|
||
"summary": "从小被妈妈体罚，长大后用同样方式对待女儿...",
|
||
"confidence": 0.85,
|
||
"source": "2026年1月21日 第10营训练营.docx"
|
||
}
|
||
|
||
event: completed
|
||
data: {
|
||
"total_files": 10,
|
||
"total_stories": 15,
|
||
"duration_seconds": 186
|
||
}
|
||
```
|
||
|
||
#### 停止提取任务
|
||
|
||
```
|
||
POST /api/v1/extraction/stop
|
||
```
|
||
|
||
**说明**：通过 `asyncio.Event` 取消后台任务。
|
||
|
||
---
|
||
|
||
## 三、核心服务设计
|
||
|
||
### 3.1 内存状态管理（state.py）
|
||
|
||
**替代 Redis 的方案**：用 Python 模块级变量 + `asyncio.Queue` 管理进度。
|
||
|
||
```python
|
||
class ExtractionState:
|
||
"""提取任务状态管理（内存中，无需 Redis）"""
|
||
|
||
def __init__(self):
|
||
self.is_running: bool = False
|
||
self.cancel_event: asyncio.Event = asyncio.Event()
|
||
self.progress: dict = {
|
||
"percent": 0,
|
||
"current_file": "",
|
||
"action": "",
|
||
"files_read": 0,
|
||
"files_total": 0,
|
||
"segments_found": 0,
|
||
"stories_found": 0,
|
||
}
|
||
self.queue: asyncio.Queue = asyncio.Queue()
|
||
|
||
def update(self, **kwargs):
|
||
"""更新进度，同时推送到 SSE 队列"""
|
||
self.progress.update(kwargs)
|
||
self.queue.put_nowait(self.progress.copy())
|
||
|
||
async def get_update(self) -> dict:
|
||
"""SSE 消费端：等待新的进度更新"""
|
||
return await self.queue.get()
|
||
|
||
def reset(self):
|
||
"""重置状态"""
|
||
self.is_running = False
|
||
self.cancel_event.clear()
|
||
self.progress = {k: 0 if k != "" else "" for k in self.progress}
|
||
self.queue = asyncio.Queue()
|
||
|
||
# 全局单例
|
||
extraction_state = ExtractionState()
|
||
```
|
||
|
||
**局限性**：
|
||
- 服务重启后进度丢失（可接受，重新提取即可）
|
||
- 单进程内有效（FastAPI 单进程部署，无问题）
|
||
|
||
### 3.2 后台任务管理
|
||
|
||
**替代 Celery 的方案**：FastAPI `asyncio.create_task()`
|
||
|
||
```python
|
||
# main.py
|
||
from app.services.extractor import run_extraction
|
||
|
||
@router.post("/extraction/start")
|
||
async def start_extraction():
|
||
if extraction_state.is_running:
|
||
return {"error": "提取任务正在进行中"}
|
||
extraction_state.reset()
|
||
extraction_state.is_running = True
|
||
asyncio.create_task(run_extraction(extraction_state))
|
||
return {"task_id": str(uuid4()), "status": "started"}
|
||
|
||
@router.post("/extraction/stop")
|
||
async def stop_extraction():
|
||
extraction_state.cancel_event.set()
|
||
return {"status": "stopping"}
|
||
```
|
||
|
||
```python
|
||
# extractor.py
|
||
async def run_extraction(state: ExtractionState):
|
||
"""后台提取任务主循环"""
|
||
try:
|
||
transcripts = get_all_transcripts()
|
||
state.update(files_total=len(transcripts))
|
||
|
||
for i, transcript in enumerate(transcripts):
|
||
if state.cancel_event.is_set():
|
||
break
|
||
|
||
state.update(
|
||
current_file=transcript.filename,
|
||
action="预处理：过滤课堂管理内容...",
|
||
files_read=i + 1,
|
||
)
|
||
|
||
paragraphs = parse_transcript(transcript.file_path)
|
||
filtered = preprocess(paragraphs)
|
||
segments = await segment_text(filtered, state)
|
||
stories = await identify_and_extract(segments, state)
|
||
|
||
save_stories(stories, transcript.id)
|
||
|
||
state.update(
|
||
percent=round((i + 1) / len(transcripts) * 100),
|
||
action=f"已完成：{transcript.filename}",
|
||
)
|
||
|
||
state.update(status="completed", percent=100)
|
||
except Exception as e:
|
||
state.update(status="error", action=f"错误：{str(e)}")
|
||
finally:
|
||
state.is_running = False
|
||
```
|
||
|
||
### 3.3 文字稿解析器（docx_parser.py）
|
||
|
||
```python
|
||
def parse_transcript(file_path: str) -> TranscriptData:
|
||
"""
|
||
解析直播回放文字稿 DOCX
|
||
格式：发言者(时间戳): 内容
|
||
|
||
返回：
|
||
- paragraphs: [{index, speaker, timestamp, content, raw_text}]
|
||
- total_lines: 总行数
|
||
"""
|
||
```
|
||
|
||
**关键处理**：
|
||
- 解析每段的发言者、时间戳、内容
|
||
- 识别发言者类型：老师（卢慧老师、静静、督导）vs 学员
|
||
- 建立行号映射关系
|
||
|
||
### 3.4 预处理器（preprocessor.py）
|
||
|
||
```python
|
||
class Preprocessor:
|
||
"""预处理：过滤非故事内容"""
|
||
|
||
def filter_classroom_management(self, paragraphs: list) -> list:
|
||
"""过滤课堂管理内容（改昵称、纪律提醒、进组讨论）"""
|
||
|
||
def filter_short_responses(self, paragraphs: list) -> list:
|
||
"""过滤学员短回应（"好的""收到"等，长度<10字）"""
|
||
|
||
def filter_healing_exercises(self, paragraphs: list) -> list:
|
||
"""过滤疗愈练习重复内容（连续"我愿意看见且释放"模式）"""
|
||
|
||
def extract_student_segments(self, paragraphs: list) -> list:
|
||
"""提取学员发言段落，保留上下文"""
|
||
```
|
||
|
||
**过滤规则**：
|
||
- 课堂管理关键词：昵称、纪律、进组、会议室、扣三个一
|
||
- 短回应：长度 < 10 字，且不含情感词
|
||
- 疗愈练习：连续 3 段以上匹配"我愿意看见且释放"模式
|
||
|
||
### 3.5 故事提取器（extractor.py）
|
||
|
||
**核心算法：三阶段 Pipeline**
|
||
|
||
```
|
||
阶段1: 预处理 → 阶段2: 故事识别 → 阶段3: 故事提取
|
||
```
|
||
|
||
#### 阶段一：预处理（规则过滤）
|
||
|
||
```python
|
||
def preprocess(self, paragraphs: list) -> list:
|
||
"""
|
||
1. 过滤课堂管理内容
|
||
2. 过滤短回应
|
||
3. 过滤疗愈练习重复
|
||
4. 提取学员发言段落
|
||
"""
|
||
```
|
||
|
||
#### 阶段二：故事识别（LLM）
|
||
|
||
**分块策略**：
|
||
- 按 300-500 行分块，块间重叠 30 行
|
||
- 每块送入 LLM 判断是否包含学员故事
|
||
|
||
**Prompt 模板**：
|
||
```
|
||
你是一个文本分析助手。以下是某心理成长训练营直播的文字稿片段。
|
||
|
||
每段格式为：发言者(时间戳): 内容
|
||
|
||
请判断该片段是否包含"学员个人故事"。
|
||
|
||
【学员个人故事】的定义：
|
||
1. 学员（非老师）讲述的自己或家人的真实经历
|
||
2. 涉及具体的事件、人物、时间线
|
||
3. 有情感色彩（痛苦、挣扎、觉醒等）
|
||
4. 主题通常围绕：原生家庭、亲子关系、婚姻情感、财富限制、身体健康、职业发展
|
||
|
||
【不属于学员故事】的内容：
|
||
1. 老师的理论讲解和方法论
|
||
2. 课堂管理（改昵称、纪律提醒）
|
||
3. 疗愈练习引导语（"我愿意看见且释放..."）
|
||
4. 学员的简短回应（"好的""明白了"）
|
||
5. 老师引用的案例（非现场学员讲述）
|
||
|
||
请返回 JSON：
|
||
{
|
||
"has_story": true/false,
|
||
"story_speaker": "学员昵称（如14班+HCM）",
|
||
"story_topic": "一句话概括主题（15字以内）",
|
||
"story_start_line": 起始行号,
|
||
"story_end_line": 结束行号,
|
||
"confidence": 0.0-1.0
|
||
}
|
||
```
|
||
|
||
#### 阶段三：故事提取（LLM）
|
||
|
||
**Prompt 模板**：
|
||
```
|
||
以下是某学员在训练营中讲述的个人故事（对话片段）。
|
||
|
||
请完成以下任务：
|
||
1. 整理出完整的故事叙述（去掉老师的提问和引导语，只保留学员的讲述）
|
||
2. 为故事起一个简洁的标题（10字以内）
|
||
3. 写一段故事摘要（80-150字，第三人称）
|
||
4. 识别故事的核心主题标签
|
||
|
||
【重要】只提取学员讲述的内容，过滤掉：
|
||
- 老师的提问、引导、追问
|
||
- 疗愈练习引导语
|
||
- 其他学员的发言
|
||
|
||
【输出格式】JSON：
|
||
{
|
||
"title": "故事标题",
|
||
"summary": "故事摘要",
|
||
"content": "整理后的完整故事叙述（第一人称，仅学员讲述部分）",
|
||
"themes": ["原生家庭", "体罚", "代际传承"],
|
||
"emotion_tone": "痛苦/挣扎/觉醒/释然/..."
|
||
}
|
||
```
|
||
|
||
### 3.6 LLM 客户端（llm_client.py）
|
||
|
||
```python
|
||
class LLMClient:
|
||
"""LLM 统一调用接口"""
|
||
|
||
def __init__(self, config: LLMConfig):
|
||
self.client = AsyncOpenAI(
|
||
api_key=config.api_key,
|
||
base_url=config.base_url,
|
||
)
|
||
self.model = config.model
|
||
|
||
async def chat(self, messages: list[dict], temperature: float = 0.3) -> str:
|
||
"""发送对话请求"""
|
||
|
||
async def chat_json(self, messages: list[dict], temperature: float = 0.3) -> dict:
|
||
"""发送对话请求，期望返回 JSON"""
|
||
```
|
||
|
||
**支持的提供商**（通过 base_url 切换）：
|
||
|
||
| 提供商 | Base URL |
|
||
|--------|----------|
|
||
| OpenAI | `https://api.openai.com/v1` |
|
||
| DeepSeek | `https://api.deepseek.com/v1` |
|
||
| 通义千问 | `https://dashscope.aliyuncs.com/compatible-mode/v1` |
|
||
| Ollama (本地) | `http://localhost:11434/v1` |
|
||
|
||
### 3.7 匹配服务（match_service.py）
|
||
|
||
```python
|
||
class MatchService:
|
||
"""匹配关系管理"""
|
||
|
||
def create_match(self, story_id: str, person_id: str) -> Match:
|
||
"""创建匹配关系"""
|
||
|
||
def remove_match(self, story_id: str) -> bool:
|
||
"""取消匹配"""
|
||
|
||
def get_matched_persons(self) -> list[Person]:
|
||
"""获取已匹配的讲述者列表（用于导出）"""
|
||
```
|
||
|
||
### 3.8 DOCX 生成器（docx_generator.py）
|
||
|
||
```python
|
||
def generate_person_doc(person: Person, stories: list[Story], output_path: str):
|
||
"""
|
||
为一位讲述者生成最终 DOCX 文档
|
||
|
||
结构：
|
||
┌─ 照片（居中）
|
||
├─ 个人信息（姓名、性别、年龄、城市、职业）
|
||
├─ 分隔线
|
||
└─ 故事正文（仅学员讲述内容，多个故事依次排列）
|
||
"""
|
||
```
|
||
|
||
---
|
||
|
||
## 四、错误处理
|
||
|
||
| 错误类型 | 处理方式 |
|
||
|----------|----------|
|
||
| 单个文字稿解析失败 | 记录错误，跳过，继续处理其他文件 |
|
||
| LLM API 调用失败 | 自动重试 3 次（指数退避），仍失败则标记该段为 error |
|
||
| LLM 返回格式异常 | 尝试修复 JSON，无法修复则丢弃该段结果 |
|
||
| DOCX 文件损坏 | 提示用户文件异常，跳过 |
|
||
| 提取任务中断（服务重启） | 进度丢失，用户需重新启动提取 |
|
||
|
||
---
|
||
|
||
## 五、数据库设计
|
||
|
||
### 5.1 ER 关系
|
||
|
||
```
|
||
Transcript 1───* Story *───0..1 Person
|
||
|
||
Config (单例)
|
||
```
|
||
|
||
### 5.2 表结构
|
||
|
||
#### transcripts 表
|
||
|
||
```sql
|
||
CREATE TABLE transcripts (
|
||
id TEXT PRIMARY KEY,
|
||
filename TEXT NOT NULL,
|
||
file_path TEXT NOT NULL,
|
||
line_count INTEGER DEFAULT 0,
|
||
file_size INTEGER DEFAULT 0,
|
||
status TEXT DEFAULT 'pending',
|
||
error_message TEXT,
|
||
uploaded_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
|
||
);
|
||
```
|
||
|
||
#### persons 表
|
||
|
||
```sql
|
||
CREATE TABLE persons (
|
||
id TEXT PRIMARY KEY,
|
||
name TEXT NOT NULL,
|
||
nickname TEXT,
|
||
filename TEXT NOT NULL,
|
||
file_path TEXT NOT NULL,
|
||
photo_path TEXT,
|
||
info TEXT,
|
||
uploaded_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
|
||
);
|
||
```
|
||
|
||
#### stories 表
|
||
|
||
```sql
|
||
CREATE TABLE stories (
|
||
id TEXT PRIMARY KEY,
|
||
title TEXT NOT NULL,
|
||
summary TEXT,
|
||
content TEXT,
|
||
speaker_nickname TEXT,
|
||
source_transcript_id TEXT NOT NULL,
|
||
source_lines TEXT,
|
||
duration_minutes REAL,
|
||
confidence REAL,
|
||
confidence_level TEXT,
|
||
person_id TEXT,
|
||
match_status TEXT DEFAULT 'pending',
|
||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||
FOREIGN KEY (source_transcript_id) REFERENCES transcripts(id),
|
||
FOREIGN KEY (person_id) REFERENCES persons(id)
|
||
);
|
||
```
|
||
|
||
#### config 表
|
||
|
||
```sql
|
||
CREATE TABLE config (
|
||
key TEXT PRIMARY KEY,
|
||
value TEXT NOT NULL
|
||
);
|
||
```
|
||
|
||
---
|
||
|
||
## 六、部署方案
|
||
|
||
### 6.1 Docker Compose（单容器）
|
||
|
||
```yaml
|
||
version: '3.8'
|
||
services:
|
||
app:
|
||
build: .
|
||
ports:
|
||
- "80:8000"
|
||
volumes:
|
||
- ./data/uploads:/app/uploads
|
||
- ./data/exports:/app/exports
|
||
- ./data/db:/app/data
|
||
env_file: .env
|
||
```
|
||
|
||
### 6.2 FastAPI 托管静态文件
|
||
|
||
```python
|
||
# main.py
|
||
from fastapi import FastAPI
|
||
from fastapi.staticfiles import StaticFiles
|
||
|
||
app = FastAPI()
|
||
|
||
# API 路由（先注册）
|
||
app.include_router(files_router, prefix="/api/v1")
|
||
app.include_router(extraction_router, prefix="/api/v1")
|
||
app.include_router(stories_router, prefix="/api/v1")
|
||
app.include_router(matching_router, prefix="/api/v1")
|
||
app.include_router(export_router, prefix="/api/v1")
|
||
app.include_router(settings_router, prefix="/api/v1")
|
||
|
||
# 托管前端静态文件（放在最后，作为 fallback）
|
||
app.mount("/", StaticFiles(directory="frontend/dist", html=True), name="static")
|
||
```
|
||
|
||
### 6.3 环境变量（.env）
|
||
|
||
```env
|
||
# LLM 配置
|
||
LLM_PROVIDER=openai
|
||
LLM_MODEL=gpt-4
|
||
LLM_BASE_URL=https://api.openai.com/v1
|
||
LLM_API_KEY=sk-xxx
|
||
|
||
# 提取参数
|
||
SEGMENT_MAX_LINES=500
|
||
STORY_MIN_LINES=50
|
||
CONFIDENCE_THRESHOLD=0.5
|
||
TEMPERATURE=0.3
|
||
|
||
# 应用
|
||
APP_HOST=0.0.0.0
|
||
APP_PORT=8000
|
||
UPLOAD_DIR=/app/uploads
|
||
EXPORT_DIR=/app/exports
|
||
```
|
||
|
||
### 6.4 启动流程
|
||
|
||
```bash
|
||
# 1. 配置环境变量
|
||
cp .env.example .env
|
||
vim .env
|
||
|
||
# 2. 构建前端
|
||
cd frontend && npm install && npm run build && cd ..
|
||
|
||
# 3. 一键启动（单容器）
|
||
docker-compose up -d
|
||
|
||
# 4. 访问
|
||
# http://<局域网IP>
|
||
```
|
||
|
||
### 6.5 依赖清单（requirements.txt）
|
||
|
||
```
|
||
fastapi>=0.110.0
|
||
uvicorn>=0.27.0
|
||
python-multipart>=0.0.9
|
||
sqlalchemy>=2.0
|
||
aiosqlite>=0.19.0
|
||
python-docx>=1.1.0
|
||
openai>=1.12.0
|
||
pydantic>=2.0
|
||
```
|
||
|
||
> 仅 8 个依赖，无 Redis、无 Celery。
|
||
|
||
---
|
||
|
||
## 七、扩展性设计
|
||
|
||
### 7.1 LLM 升级
|
||
|
||
- 所有 LLM 调用通过 `LLMClient` 抽象层
|
||
- 切换模型只需修改配置（base_url + model + api_key）
|
||
|
||
### 7.2 文章搜索引擎（预留）
|
||
|
||
- stories 表已存储完整内容 + 结构化元数据
|
||
- 后续可接入 SQLite FTS5 全文搜索或 Meilisearch
|
||
|
||
### 7.3 多用户支持（预留）
|
||
|
||
- 当前为单用户模式（局域网共享）
|
||
- 后续可加入用户认证（JWT）
|
||
|
||
### 7.4 从极简架构升级
|
||
|
||
如果后续需要更强的任务管理能力，可以平滑升级：
|
||
- `ExtractionState` → Redis
|
||
- `asyncio.create_task()` → Celery
|
||
- 架构设计已预留接口，业务逻辑层不需要改动
|