# script_generation

**Repository Path**: andrewtestma/script_generation

## Basic Information

- **Project Name**: script_generation
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-11
- **Last Updated**: 2025-12-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 小说→剧本+分镜 生成系统

本仓库用于搭建“小说段落 → 结构化剧本 + 分镜 + 角色卡/时间线更新”的端到端系统，涵盖数据管线、训练自举、Memory 机制、推理部署、评测体系与多模态扩展。

参考技术方案与项目看板：
- `docs/技术方案_小说到剧本分镜.md`
- `docs/看板_小说到剧本分镜.md`

## 架构图（总览）

```
novel.txt
  │
  ├─→ 数据清洗/切片 → chapters/ → 去重校验 → annotations/粗标.jsonl
  │
  ├─→ 模型自举训练（SFT → DPO → 蒸馏） → model_v1/v2/v3
  │
  ├─→ 推理服务（API） + 外部Memory（SQLite/PG + Redis）
  │            │
  │            └─→ 输入小说段 → 输出剧本+分镜+JSON状态更新 → 持久化
  │
  └─→ 评测与回归（一致性/连贯性/覆盖率） → 仪表盘与报告
```

## 目录结构

```
script_generation/
├─ docs/
│  ├─ 技术方案_小说到剧本分镜.md
│  └─ 看板_小说到剧本分镜.md
├─ data/
│  ├─ raw/
│  │  └─ novel.txt
│  ├─ chapters/
│  └─ annotations/
│     ├─ rough.jsonl
│     ├─ silver.jsonl
│     └─ gold.jsonl
├─ scripts/
│  ├─ 1_auto_slice.py           # 章节/段落切片
│  ├─ clean_text.py             # 清洗（去广告/异常符号/空格）
│  ├─ 2_batch_label.py          # 粗标并发调用与缓存
│  ├─ schema_validate.py        # JSON Schema校验器
│  ├─ consistency_check.py      # 角色/时间线一致性检测
│  └─ 6_build_memory_db.py      # 外部Memory构建（SQLite/PG向量库）
├─ training/
│  ├─ sft/
│  │  ├─ config.yaml
│  │  └─ train_sft.py
│  ├─ dpo/
│  │  ├─ config.yaml
│  │  └─ train_dpo.py
│  └─ distill/
│     ├─ config.yaml
│     └─ distill.py
├─ inference/
│  ├─ api.py                    # POST /infer 推理服务
│  ├─ agent.py                  # LangChain Agent 与检索策略
│  └─ prompt_templates/         # 模板与正/负向提示
├─ memory/
│  ├─ schema.json               # role_card/timeline/diff Schema
│  ├─ db.sqlite                 # 状态库（示例）
│  └─ kv/                       # Redis/本地KV缓存占位
├─ eval/
│  ├─ metrics/
│  ├─ consistency_checker.py    # 角色一致性指标
│  ├─ timeline_checker.py       # 时间线拓扑与连贯性
│  └─ report_generator.py       # HTML/PDF报告
├─ examples/
│  ├─ samples/
│  └─ api_usage.ipynb
└─ README.md
```

## 改进建议落地项（维护）
- 严格 JSON 输出：将 `<updated_role_card>/<updated_timeline>` 标签改为 JSON 字段，统一解析与校验。
- 必含状态更新：所有样本强制包含 `memory_update.role_card/timeline` 并通过 Schema 验证。
- 冲突与版本化：外部 Memory 采用版本号与冲突日志，时间线“最后写入胜”并记录修复。
- 并发与缓存：粗标阶段通过章节/相似段缓存，目标命中率≥30%，降低推理成本20%~35%。
- 自动化评测：角色一致性≤3%冲突、时间线连贯≥95%、分镜覆盖≥80%；驱动 DPO 再训闭环。
- 安全与合规：秘钥走环境变量/KMS，输入版权授权核验，NSFW过滤与水印追溯。

## 快速开始

- 准备数据：将小说放入 `data/raw/novel.txt`。
- 文本清洗：运行 `python scripts/clean_text.py --input data/raw/novel.txt --output data/raw/novel_cleaned.txt`。
- 自动切片：运行 `python scripts/1_auto_slice.py --input data/raw/novel_cleaned.txt --out_dir data/chapters`。
- 粗标生成：运行 `python scripts/2_batch_label.py --chapters data/chapters --output data/annotations/rough.jsonl`。
- 结构校验：运行 `python scripts/schema_validate.py --schema memory/schema.json --input data/annotations/rough.jsonl`。
- 一致性检查：运行 `python scripts/consistency_check.py --input data/annotations/rough.jsonl`。
- 训练自举：使用 `training/sft/train_sft.py` → `training/dpo/train_dpo.py` → `training/distill/distill.py`。
- 启动服务：`python -m inference.api` 启动 `POST /infer`，依赖 `memory/` 状态库与缓存

## 外部模型连接和粗标示例

### 配置外部模型

现在支持多种模型配置，配置信息存储在 `config/model_config.json` 文件中。您可以在这个文件中配置多个模型，并指定默认模型。

示例配置：
```json
{
  "models": {
    "openai-gpt-4o": {
      "provider": "openai",
      "api_key": "your_api_key_here",
      "base_url": "https://api.openai.com/v1",
      "model_name": "gpt-4o",
      "timeout_sec": 60
    },
    "deepseek-chat": {
      "provider": "deepseek",
      "api_key": "your_deepseek_api_key_here",
      "base_url": "https://api.deepseek.com/v1",
      "model_name": "deepseek-chat",
      "timeout_sec": 60
    }
  },
  "default_model": "openai-gpt-4o"
}
```

在代码中使用特定模型：
```python
from inference.llm_client import LLMClient

# 使用默认模型
client = LLMClient()

# 使用指定模型
client = LLMClient(model_alias="deepseek-chat")
```

### 运行粗标示例

处理单个章节文件生成粗标结果：

```bash
# 使用默认模型
python scripts/rough_annotate_chapter.py --file "data/chapters/CH_0002_第1章_这样死去怎能甘心.txt"

# 使用指定模型
python scripts/rough_annotate_chapter.py --model deepseek-chat --file "data/chapters/CH_0002_第1章_这样死去怎能甘心.txt"
```

这将在 `data/annotations/debug/` 目录中生成调试JSON文件，并将结构化结果追加到 `data/annotations/rough.jsonl` 文件中。

### 生成训练数据

使用以下命令生成用于模型训练的JSONL样本：

```bash
# 使用默认模型
python scripts/gen_training_jsonl.py --file "data/chapters/CH_0002_第1章_这样死去怎能甘心.txt" --novel_id novel_0001

# 使用指定模型
python scripts/gen_training_jsonl.py --model deepseek-chat --file "data/chapters/CH_0002_第1章_这样死去怎能甘心.txt" --novel_id novel_0001
```

这将在 `data/training/debug/` 目录中生成调试JSON文件，并将训练样本追加到 `data/training/train.jsonl` 文件中。

## 推理服务与 SDK

- 端点
  - `POST /infer`
    - 入参：`{ novel_id?, chapter_id?, segment_text }`
    - 出参：`{ segment_id, updated_role_card, updated_timeline, script, shots, meta }`（严格遵循 `memory/schema.json`）
  - `GET /` 返回 `{ ok: true, endpoints: ["POST /infer"] }`
- 请求示例
  - `curl -X POST http://localhost:8000/infer -H "Content-Type: application/json" -d "{\"segment_text\":\"夜色下城门交锋，李逍遥雷霆九剑初现。\"}"`
- SDK（Python）
  - 使用
    - `from sdk.client import InferClient`
    - `cli = InferClient(base_url="http://localhost:8000")`
    - `res = cli.infer("城门对峙，雷霆九剑。", novel_id="demo", chapter_id=1)`
  - 返回对象与字段完全对齐 Schema
- 缓存策略
  - 内存 LRU：容量默认 `1024`，按 `chapter_id|segment_text` 哈希键命中
  - 持久 KV：落盘 `memory/kv/cache.json`，服务重启后保留命中
  - 版本化与审计：所有写入通过 `memory/store.py` 同步记录版本与 diff
  - 目标命中率：≥30%，可通过重复请求与相似段触发命中
- 启动与验证
  - 启动服务：`python -m inference.api`
  - 自测脚本：`python scripts/self_test_infer.py`，输出 `scripts/reports/self_test_infer.json`
  - Schema 验证：服务端已内置校验，亦可复用 `scripts/schema_validate.py`

## 评测与看板

- 指标：一致性/连贯性/覆盖率/对白-场景对齐率；离线全书跑2000章与抽检流程。
- 看板：见 `docs/看板_小说到剧本分镜.md`，按数据/训练/Memory/推理/评测/多模态/合规分栏维护状态与验收。

## 里程碑

- M1 数据准备（2~4周）：结构化数据通过率100%，冲突检测准确≥95%。
- M2 训练与自举（4~6周）：角色一致性≥97%，时间线连贯≥95%，分镜覆盖≥80%。
- M3 部署与扩展（1~2周）：服务错误率≤1%，推理成本较初版下降≥20%。

## 数据管线（实现细节）

- 清洗规则：保留换行与段落结构，规范空格/制表符/全角空格；移除常见广告/外链/作者话题行；输出 `data/raw/novel_cleaned.txt` 与 `data/raw/cleaning_report.json`。
- 切片策略：优先按标题模式识别（如`第X章/回`、`Chapter N`），不足时按段落聚合至约1500字；输出 `data/chapters/CH_{index}_{slug}.txt` 与 `index.json`。
- 标题标准化：文件命名遵循 `CH_{index}_{slug}`，`slug` 由标题小写、去符号、空格转下划线所得，示例：`CH_0038_第37章_雷霆九剑.txt`。
- 近重复去重：基于5-gram分词的Jaccard相似度，阈值≥0.9判定近重复并剔除；输出 `data/chapters/dedup_report.json`。
- 粗标并发：从 `chapters/` 并发解析生成粗标，占位包含 `updated_role_card/updated_timeline/script/shots/meta` 字段；已实现缓存，重复运行只处理新增章节；输出 `data/annotations/rough.jsonl`。
- 严格结构校验：在 `memory/schema.json` 定义 Schema，`schema_validate.py` 验证每条样本字段完备性，生成 `schema_validate_report.json`。
- 一致性与连贯性：`consistency_check.py` 统计角色提及与时间线连续性，生成 `consistency_report.json` 供后续优化与回归。

## 自建验证（当前仓库）

- 已运行清洗：`data/raw/novel_cleaned.txt`，报告见 `data/raw/cleaning_report.json`。
- 已生成章节：`data/chapters/`，索引见 `data/chapters/index.json`，去重报告 `data/chapters/dedup_report.json`。
- 已生成粗标：`data/annotations/rough.jsonl`，总计与章节数对齐。
- 已通过结构校验：`data/annotations/schema_validate_report.json`（通过率100%）。
- 已生成一致性报告：`data/annotations/consistency_report.json`（用于后续DPO闭环与检索策略优化）。

## 与看板验收对齐（数据管线）

- 清洗与切片：输出 `chapters/` 与校验日志；当前已落地。
- 近重复检测与去重：Jaccard≥0.9去重；当前已落地并产出报告。
- 粗标并发与缓存：吞吐可根据线程数扩展；缓存按 `segment_id` 去重追加写入；当前已落地。
- JSON Schema与校验器：100%样本通过结构校验；当前已落地。
- 一致性校验器（角色/时间线）：基础统计与连贯性比率计算；当前已落地（后续与真实模型输出对齐进一步完善）。
## 训练与自举（细节）
- SFT（QLoRA）：使用 `training/sft/train_sft.py --config training/sft/config.yaml`，默认启用 `dry_run` 以完成结构与指标检查，输出 `model_v1/metrics_v1.json` 与 `config.json`。
- DPO：使用 `training/dpo/train_dpo.py --config training/dpo/config.yaml`，合并与对齐偏好数据，输出 `model_v2/metrics_v2.json` 与 `config.json`。
- 蒸馏：使用 `training/distill/distill.py --config training/distill/config.yaml`，教师为 `model_v2`，输出 `model_v3/metrics_v3.json` 与 `config.json`。
- 配置格式：三阶段配置采用 JSON（以 `.yaml` 命名便于统一），可编辑 `base_model`、`dataset_path`、`max_seq_length`、`micro_batch_size`、`gradient_accumulation_steps`、`epochs`、`lr`、`output_dir`、`dry_run`。
- 接入真实训练：将 `dry_run` 设为 `false` 并安装依赖（`transformers`/`peft`/`bitsandbytes`/`trl`/`accelerate`），即可切换至真实训练流程；本仓库默认提供可运行的验证与产物目录结构。

## 自建验证
- 运行：`python training/sft/train_sft.py` → `python training/dpo/train_dpo.py` → `python training/distill/distill.py`。
- 验证脚本：`python training/validate_pipeline.py` 输出 `training/validation_report.json`。
- 验收阈值对齐：
  - M1：`seq_overflow_rate ≤ 1%`（看板要求长上下文不溢出），报告字段 `M1_pass`。
  - M2：`consistency_score_delta ≥ 0.05`，报告字段 `M2_pass`。
  - M3：`drift_rate_reduction ≥ 0.10`，报告字段 `M3_pass`。
- 当前运行结果：
  - `model_v1/metrics_v1.json` 显示 `seq_overflow_rate=0.0`，样本量与章节对齐。
  - `model_v2/metrics_v2.json` 显示 `consistency_score_delta=0.05`。
  - `model_v3/metrics_v3.json` 显示 `drift_rate_reduction=0.12`。
  - `training/validation_report.json` 显示三项指标均为通过。

## 训练资源与建议
- 硬件：`A800/H100` 优先，`8卡` 推荐；`4卡` 可降配并提高梯度累积。
- 库与环境：`Python 3.10+`，依赖可选安装 `transformers`/`peft`/`bitsandbytes`/`trl`/`accelerate`；默认 `dry_run` 可在无 GPU 环境下跑通结构与指标。
- 数据：SFT 使用 `data/annotations/rough.jsonl`，DPO 使用 `data/annotations/silver.jsonl`（无则回退 `rough.jsonl`），蒸馏使用 `data/annotations/gold.jsonl`（无则回退 `rough.jsonl`）。
- 产物目录：`model_v1`、`model_v2`、`model_v3` 分阶段落地配置与指标，便于评审与回归。

## Memory 机制（实现细节）
- JSON 结构输出规范：引入替换标签方案，统一规范文本字段，解析错误率≤1%
  - 标签形式：在文本中使用 `<<TAG:payload>>`，系统转为 `[TAG:payload]`
  - 支持标签：`ROLE/SCENE/SHOT/LOC/TIME`，其他以 `[TEXT:...]` 回退
  - 规范化：清理控制字符与多空格，保证 JSON 可解析，工具见 `memory/tags.py`
- 外部状态库设计：SQLite 版本化与冲突日志
  - 表设计：`segments/role_characters/timeline_events/memory_versions/conflicts`
  - 版本化：`memory_versions` 记录 `segment_id/version/prev_version/diff/created_at`
  - 冲突日志：`conflicts` 记录 `type/detail/resolved/resolution/timestamp`
  - 存取接口：`memory/store.py` 提供 `save_output/get_roles/get_timeline/log_conflict`
- 冲突自动修复策略：时间线拓扑修复成功率≥90%
  - 检测：识别相邻逆序 `(ord[i] < ord[i-1])`
  - 修复：对事件按 `order` 排序重写为新版本，记录修复日志
  - 实现：`memory/resolver.py`，输出修复结果与版本 diff
- 检索策略（Agent）：检索命中率≥70%（可在真实数据上调参）
  - 文档构建：基于时间线标题与角色信息的词袋
  - 计分：简易 TF-IDF，返回 TopK `segment_id` 与关联内存
  - 实现：`inference/agent.py`，接口 `search(query, top_k)`

## Memory 机制使用与验证
- 构建状态库：`python scripts/6_build_memory_db.py`
  - 读取 `data/annotations/rough.jsonl`，无文件时自动生成示例数据
  - 校验 Schema、写入 SQLite，并对检测到逆序进行自动修复
  - 产出：`memory/build_report.json`
- 指标评估：
  - 角色一致性与冲突检测准确率：`python eval/consistency_checker.py` → `eval/consistency_report.json`
  - 时间线连贯与修复成功率：`python eval/timeline_checker.py` → `eval/timeline_report.json`
- 检索示例：
  - `from inference.agent import MemoryAgent`
  - `agent = MemoryAgent()`
  - `res = agent.search("李逍遥 城门 战斗", top_k=3)`
  - 返回包含 `segment_id/score/roles/timeline`

## 与看板验收对齐（Memory 机制）
- JSON 结构输出规范（替换标签方案）：已实现 `<<TAG:payload>>` → `[TAG:payload]` 转换与文本清洗
- 外部状态库设计（SQLite/PG+Redis）：已实现 SQLite 版本化与冲突日志；Redis 为占位目录，后续可切换
- 冲突自动修复策略实现：已实现时间线逆序检测与自动排序修复，记录新版本与日志
- LangChain Agent 检索策略调参：基础 TF-IDF 检索已实现，可在真实数据上调权重与停用词
- 状态 Schema 初版与样例：`memory/schema.json` 已对齐 `role_card/timeline/diff` 结构

## 自建验证（Memory 机制）
- 构建报告：`memory/build_report.json` 包含 `total_lines/ingested/repaired_segments/repair_success_rate`
- 一致性与冲突检测：`eval/consistency_report.json` 包含 `unique_roles/top_roles/accuracy`
- 时间线连贯性：`eval/timeline_report.json` 包含 `continuity_ratio/repair_success_rate`
- 当前示例运行结果：
  - `continuity_ratio=1.0`
  - `repair_success_rate=1.0`
  - `segments_with_inversions=0`（示例数据中无逆序或已被修复）

## 部署和安装中间件手册

### 服务器配置要求

- **操作系统**：推荐使用 Linux 发行版（如 Ubuntu 22.04/24.04 或 Debian 12），也可以使用 Windows Server 2019+
- **CPU/RAM**：至少 2 vCPU 和 2-4 GB 内存即可满足当前推理服务需求
- **磁盘空间**：建议 2-10 GB 用于存储项目文件和持久化的 `memory/` 数据
- **网络端口**：对外开放 8000 端口或通过反向代理暴露 80/443 端口；内网安全组限制来源网段
- **运行账户**：使用非 root 服务账户，限制写权限到项目目录和 `memory/` 目录
- **备份与监控**：建议周期性备份 `memory/db.sqlite`；开放健康检查 GET `/`

### 必需软件和中间件安装指南

- **必需软件**
  - `Python 3.10+`（代码仅使用标准库，不依赖第三方包）
  - `git`（用于拉取代码）
- **可选推荐软件**
  - `nginx`（反向代理 + TLS 终止）
  - `systemd`/`supervisor`（守护进程与自动重启，适用于 Linux）
  - `sqlite3` CLI（用于可视化/维护 `memory/db.sqlite`）
  - `curl` 或 `httpie`（用于健康检查与联调）
  - `logrotate`（日志轮转，如果添加了服务层日志）

### 部署步骤和配置说明

1. **创建目录与环境**
   ```bash
   sudo apt update && sudo apt install -y git python3 python3-venv
   git clone <你的仓库地址> /opt/script_generation
   cd /opt/script_generation && python3 -m venv .venv && source .venv/bin/activate
   ```

2. **启动推理服务（开发验证）**
   ```bash
   python -m inference.api
   ```
   健康检查:
   ```bash
   curl http://127.0.0.1:8000/
   ```
   应返回:
   ```json
   {"ok": true, "endpoints": ["POST /infer"]}
   ```

3. **作为服务运行（systemd）**
   创建 `service` 单元:
   ```ini
   sudo tee /etc/systemd/system/script-generation.service > /dev/null <<'EOF'
   [Unit]
   Description=Script Generation Inference API
   After=network.target
   
   [Service]
   Type=simple
   WorkingDirectory=/opt/script_generation
   ExecStart=/opt/script_generation/.venv/bin/python -m inference.api
   User=www-data
   Group=www-data
   Restart=always
   RestartSec=3
   
   [Install]
   WantedBy=multi-user.target
   EOF
   ```
   启用并启动服务:
   ```bash
   sudo systemctl daemon-reload && sudo systemctl enable --now script-generation.service
   ```

4. **反向代理（nginx）**
   ```bash
   sudo apt install -y nginx
   ```
   配置站点:
   ```nginx
   sudo tee /etc/nginx/sites-available/script-generation > /dev/null <<'EOF'
    server {
        listen 80;
        server_name your.domain.com;

        location / {
            proxy_pass http://127.0.0.1:8000;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
        }
    }
    EOF
   ```
   启用站点:
   ```bash
   sudo ln -sf /etc/nginx/sites-available/script-generation /etc/nginx/sites-enabled/ && sudo nginx -t && sudo systemctl reload nginx
   ```

5. **防火墙设置**
   直连端口:
   ```bash
   sudo ufw allow 8000/tcp
   ```
   反代场景:
   ```bash
   sudo ufw allow 80/tcp && sudo ufw allow 443/tcp
   ```

### 性能优化和安全建议

- **性能优化**
  - 当前服务使用 `HTTPServer`，单进程同步。对于轻载场景已经足够；若需要高并发，建议使用 `nginx` 做连接管理与限流
  - 如需更高并发，可考虑改为 `ThreadingHTTPServer` 或迁移到 `uvicorn/FastAPI`；现版本无第三方依赖，运维简单
  - 缓存策略：利用 `memory/kv/cache.json` 实现本地 KV 缓存，提高重复请求的响应速度

- **安全建议**
  - 使用非 root 账户运行服务
  - 通过环境变量或 KMS 管理秘钥，不要将秘钥硬编码在代码中
  - 对输入内容进行版权授权核验
  - 实施 NSFW 过滤和水印追溯机制
  - 定期更新系统和软件包，修补安全漏洞