KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #typescript #ai-agent #developer-tools #claude-code #codex #deepseek-harness #ai-agents #react #mcp #rust

ai-short-drama-role-consistency

★ 2 Open GitHub ↗

面向短剧与小说改编的角色一致性训练工程，用于构造角色行为数据、进行 SFT/DPO 微调，并评估同一情境下不同角色的反应区分度。A role-consistency training toolkit for short dramas and novel adaptations, supporting character behavior data construction, SFT/DPO fine-tuning, and evaluation of role-specific reactions under shared scenarios.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# AI短剧角色一致性

[English README](README_EN.md)

`role_creator` 是面向短剧与小说改编的角色一致性训练工程，用于构造角色行为数据、进行 SFT/DPO 微调，并评估同一情境下不同角色的反应区分度。

English: A role-consistency training toolkit for short dramas and novel adaptations, supporting character behavior data construction, SFT/DPO fine-tuning, and evaluation of role-specific reactions under shared scenarios.

当前目标是训练一个 `BehaviorExecutor`：给定小说上下文与目标角色，补全该角色的下一段行为。行为包括台词、动作、表情、心理活动和局部语气/动作词。

仓库 remote 示例：

```text
origin  git@github.com:<your-org-or-user>/role_creator.git (fetch)
origin  git@github.com:<your-org-or-user>/role_creator.git (push)
```

项目文档：

```text
README.md                         快速使用入口
TRAINING.md                       训练说明
docs/skill_curation_design.md     BehaviorExecutor / RoleCritic / RoleCurator 技术设计
```

## 目录

```text
src/role_creator/                 数据构造代码
scripts/call_qwen.py              调用自部署 Qwen endpoint
scripts/export_sft.py             导出 LLaMA-Factory SFT 数据
scripts/setup_llamafactory_env.sh 配置 LLaMA-Factory 环境
scripts/train_full_sft_b200.sh    启动 B200 全参 SFT
training/llamafactory/            LLaMA-Factory 配置
data/processed/                   生成后的训练原始数据，git 忽略
data/llamafactory/                导出的 SFT 数据，git 忽略
```

## 本地开发

在仓库根目录执行：

```bash
pip install -e ".[dev]"
role-creator --help
pytest
```

当前验证结果：

```text
3 passed
```

## 自部署 Qwen 验证

默认 endpoint 可通过环境变量或脚本参数配置。不要把内部服务地址、真实 token 或调用凭据提交到仓库。

```text
base_url: <your-openai-compatible-endpoint>/v1
model: <your-model-name>
api_key: <your-api-key-or-EMPTY>
```

验证命令：

```bash
python3 scripts/call_qwen.py --prompt "只回复：OK" --max-tokens 16 --timeout 30
```

预期输出：

```text
OK
```

## 生成《红楼梦》角色数据

当前使用四个目标角色：

```text
黛玉 / 宝玉 / 宝钗 / 凤姐
```

真实数据生成命令：

```bash
role-creator 红楼梦.txt \
  --characters "黛玉,宝玉,宝钗,凤姐" \
  --aliases "黛玉=林黛玉|林妹妹|颦儿|潇湘妃子,宝玉=贾宝玉|宝二爷|怡红公子|宝兄弟,宝钗=薛宝钗|宝姐姐|蘅芜君,凤姐=王熙凤|凤姐儿|凤丫头|琏二奶奶|凤辣子" \
  --use-llm-refine \
  --llm-context-chars 1200 \
  --llm-timeout 30 \
  --llm-progress-every 200 \
  --llm-max-output-chars 240 \
  --local-multiplier 3 \
  --none-ratio 0.25 \
  --max-prompt-chars 2200 \
  --out data/processed/hongloumeng_four_llm_local
```

当前已生成数据目录：

```text
data/processed/hongloumeng_four_llm_local
```

当前数据规模：

```text
mask_behavior total: 3778
behavior: 2223
dialogue: 622
local: 933

role_classifier total: 4447
none: 669
```

输出文件：

```text
data/processed/hongloumeng_four_llm_local/
  stats.json
  mask_behavior_train.jsonl
  mask_behavior_val.jsonl
  mask_behavior_test.jsonl
  role_classifier_train.jsonl
  role_classifier_val.jsonl
  role_classifier_test.jsonl
```

## 导出 LLaMA-Factory SFT 数据

真实导出命令：

```bash
python3 scripts/export_sft.py \
  --input-dir data/processed/hongloumeng_four_llm_local \
  --out-dir data/llamafactory/hongloumeng_sft
```

当前导出结果：

```text
data/llamafactory/hongloumeng_sft/
  dataset_info.json
  hongloumeng_sft_train.json
  hongloumeng_sft_val.json
  hongloumeng_sft_test.json
```

## 训练机环境

示例 B200 训练镜像检测结果：

```text
OS: CentOS 7
Python: <CONDA_ENV_PATH>/bin/python
Python version: 3.12.13
torch: 2.11.0+cu130
CUDA driver: 13.0
nvcc: 12.8
GPU: 8 x NVIDIA B200, each 183GB
```

注意：

```text
不要默认重装 torch
不要默认启用 flash-attn
当前 flash_attn 存在 ABI 报错
第一轮训练使用 TRAIN_FLASH_ATTN=disabled
```

## 配置 LLaMA-Factory 环境

训练机上执行：

```bash

cd <REMOTE_ROLE_CREATOR_DIR>

export PIP_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/
export PIP_TRUSTED_HOST=mirrors.aliyun.com
export PIP_EXTRA_INDEX_URL=https://download.pytorch.org/whl/cu130

pip uninstall -y deepspeed kernels kernels-data

pip install \
  "transformers==4.57.1" \
  "peft==0.17.1" \
  "trl==0.24.0" \
  "huggingface-hub==0.36.2" \
  "deepspeed==0.16.9"

USE_EXISTING_ENV=1 \
INSTALL_TORCH=0 \
INSTALL_FLASH_ATTN=0 \
INSTALL_DEEPSPEED=0 \
INSTALL_MISSING_CORE=1 \
LLAMAFACTORY_INSTALL_MODE=pip \
bash scripts/setup_llamafactory_env.sh

```

脚本默认行为：

```text
USE_EXISTING_ENV=1
INSTALL_TORCH=0
INSTALL_FLASH_ATTN=0
INSTALL_DEEPSPEED=1
INSTALL_MISSING_CORE=1
EXPORT_SFT_DATA=1
```

如果已经手动下载 LLaMA-Factory 源码到 `third_party/LLaMA-Factory`：

```bash
cd role_creator
source <CONDA_ENV_PATH>/bin/activate
LLAMAFACTORY_INSTALL_MODE=local \
LLAMAFACTORY_DIR=third_party/LLaMA-Factory \
bash scripts/setup_llamafactory_env.sh
```

## 启动全参 SFT

训练前必须让 `MODEL_NAME_OR_PATH` 指向训练机上的 Qwen3.5-9B-Instruct 权重目录。为了避免误用空路径，使用下面的校验写法：

```bash
cd role_creator
source <CONDA_ENV_PATH>/bin/activate

export MODEL_NAME_OR_PATH=/media/cfs/ai-jingyan-train/model/Qwen3-4B-Instruct-2507
export NPROC_PER_NODE=8
export TRAIN_FLASH_ATTN=disabled
export EVAL_STEPS=25
export SAVE_STEPS=25
export LOGGING_STEPS=5

# 如需写入 W&B，先确认登录或配置有效 key。
# 不要把真实 key 提交到仓库；只在当前 shell 里 export。
# export WANDB_PROJECT=llamafactory
# export WANDB_ENTITY=<your-wandb-entity>
# export WANDB_API_KEY=<your-wandb-api-key>

bash scripts/train_full_sft_b200.sh
```

训练输出目录：

```text
saves/hongloumeng/qwen35_9b_full_sft
```

训练日志目录：

```text
logs/train_YYYYMMDD_HHMMSS/
  train.log          完整 stdout/stderr，包含训练时间、wandb、模型路径、GPU、依赖版本
  train_config.yaml  实际提交给 LLaMA-Factory 的运行时配置
```

默认训练行为：

```text
logging_steps: 5
eval_steps: 25
save_steps: 25
save_total_limit: 5
report_to: wandb
run_name: hongloumeng-sft-YYYYMMDD_HHMMSS
```

如果只想本地训练，不上报 W&B：

```bash
export WANDB_DISABLED=true
export REPORT_TO=none
bash scripts/train_full_sft_b200.sh
```

## 评估 SFT 模型

评估脚本会默认读取训练输出目录：

```text
saves/hongloumeng/qwen35_9b_full_sft
```

如果最终目录已经是完整 Hugging Face 模型，就直接评估最终目录；如果训练还在中途、只保存了 `checkpoint-*`，脚本会自动选择最新可加载 checkpoint。

训练机上直接复制执行：

```bash
cd <REMOTE_ROLE_CREATOR_DIR>
source <CONDA_ENV_PATH>/bin/activate

export WANDB_DISABLED=true
export WANDB_MODE=disabled
export REPORT_TO=none

scripts/evaluate_sft.sh eval
```

`eval_loss` 是验证集 teacher-forcing 交叉熵，表示模型在给定标准答案前文时预测下一个 token 的平均损失；越低通常越好，但它不等同于最终生成质量。`scripts/evaluate_sft.sh eval` 会在指标后默认抽 3 条样本打印 `PROMPT / GT / PRED`，用于人工检查角色口吻、事实一致性和原文风格。

控制人工对比样本数量：

```bash
PRINT_SAMPLES=5 scripts/evaluate_sft.sh eval
PRINT_SAMPLES=0 scripts/evaluate_sft.sh eval  # 只看 eval_loss，不打印样本
```

评估测试集：

```bash
cd <REMOTE_ROLE_CREATOR_DIR>
source <CONDA_ENV_PATH>/bin/activate

export WANDB_DISABLED=true
export WANDB_MODE=disabled
export REPORT_TO=none

DATASET=hongloumeng_sft_test scripts/evaluate_sft.sh eval
```

指定某个 checkpoint 评估：

```bash
cd <REMOTE_ROLE_CREATOR_DIR>
source <CONDA_ENV_PATH>/bin/activate

MODEL_PATH=saves/hongloumeng/qwen35_9b_full_sft/checkpoint-100 \
DATASET=hongloumeng_sft_val \
scripts/evaluate_sft.sh eval
```

抽样生成，人工检查角色口吻：

```bash
cd <REMOTE_ROLE_CREATOR_DIR>
source <CONDA_ENV_PATH>/bin/activate

scripts/evaluate_sft.sh sample
```

同一背景下对比不同角色反应：

```bash
cd <REMOTE_ROLE_CREATOR_DIR>
source <CONDA_ENV_PATH>/bin/activate

scripts/compare_role_reactions.sh
```

默认内置 12 个背景，每个背景分别生成 `黛玉 / 宝玉 / 宝钗 / 凤姐` 的反应。这个脚本负责“生成对比样本”，输出文件：

```text
saves/hongloumeng/role_compare_YYYYMMDD_HHMMSS/role_compare.md
saves/hongloumeng/role_compare_YYYYMMDD_HHMMSS/role_compare.jsonl
```

控制场景数量、生成长度和角色：

```bash
SCENARIO_LIMIT=20 \
MAX_NEW_TOKENS=160 \
ROLES=黛玉,宝玉,宝钗,凤姐 \
scripts/compare_role_reactions.sh
```

读取 `role_compare.jsonl`，输出角色区分度报告：

```bash
latest=$(ls -td saves/hongloumeng/role_compare_* | head -1)
python3 scripts/evaluate_role_distinctness.py \
  "${latest}/role_compare.jsonl" \
  --out "${latest}/role_distinctness_report.md"
cat "${latest}/role_distinctness_report.md"
```

`evaluate_role_distinctness.py` 负责“分析对比结果”，会输出平均相似度、区分度、近重复场景、各角色长度分布、角色标志词命中率、最相似/最不同的角色 pair，以及几条人工对比样例。

自定义抽样 prompt：

```bash
cat >/tmp/hongloumeng_eval_prompts.txt <<'EOF'
请你以林黛玉的口吻，评价宝玉摔玉这件事。
请你以薛宝钗的口吻，劝慰一个心事重重的人。
请以王熙凤的语气，写一段短短的管家训话。
EOF

PROMPTS_FILE=/tmp/hongloumeng_eval_prompts.txt \
MAX_NEW_TOKENS=256 \
scripts/evaluate_sft.sh sample
```

查看最近一次评估日志：

```bash
latest=$(ls -td saves/hongloumeng/eval_* | head -1)
echo "${latest}"
tail -n 120 "${latest}/eval.log"
```

评估输出会打印 `eval_loss` 等指标；日志保存在：

```text
saves/hongloumeng/eval_YYYYMMDD_HHMMSS/eval.log
```

## DPO 偏好学习

当前 DPO 使用 **LLaMA-Factory**，原因是 SFT、B200 训练环境、W&B、数据目录都已经按 LLaMA-Factory 跑通。LLaMA-Factory 的偏好数据使用 `chosen/rejected` 字段，并在 `dataset_info.json` 中设置 `ranking: true`。

当前按全参 DPO 训练，继续使用 B200 + Deepspeed ZeRO-3。全参 DPO 会比 LoRA 更吃显存和训练时间，建议先跑 1 个 epoch 看 W&B 的 loss、grad_norm 和角色对比输出，再决定是否加长。

导出 DPO 偏好数据：

```bash
cd <REMOTE_ROLE_CREATOR_DIR>
source <CONDA_ENV_PATH>/bin/activate

python3 scripts/export_dpo.py \
  --input-dir data/processed/hongloumeng_four_llm_local \
  --out-dir data/llamafactory/hongloumeng_dpo
```

导出的数据：

```text
data/llamafactory/hongloumeng_dpo/
  dataset_info.json
  hongloumeng_dpo_train.json
  hongloumeng_dpo_val.json
  hongloumeng_dpo_test.json
```

DPO 数据构造方式：

```text
chosen   = 原始训练目标，也就是更贴角色和上下文的红楼梦反应
rejected = 同类型错角色反应，或“你放心 / 你别哄我”等泛化短句 hard negative
```

启动全参 DPO：

```bash
cd <REMOTE_ROLE_CREATOR_DIR>
source <CONDA_ENV_PATH>/bin/activate

export MODEL_NAME_OR_PATH=saves/hongloumeng/qwen35_9b_full_sft
export REF_MODEL_NAME_OR_PATH=saves/hongloumeng/qwen35_9b_full_sft
export NPROC_PER_NODE=8
export TRAIN_FLASH_ATTN=disabled
export EVAL_STEPS=25
export SAVE_STEPS=25
export LOGGING_STEPS=5

export WANDB_PROJECT=llamafactory
export WANDB_ENTITY=<your-wandb-entity>
export WANDB_API_KEY=<your-wandb-api-key>

bash scripts/train_full_dpo_b200.sh
```

如果只想本地训练，不上报 W&B：

```bash
unset WANDB_API_KEY
export WANDB_DISABLED=true
export REPORT_TO=none
bash scripts/train_full_dpo_b200.sh
```

DPO 输出目录：

```text
saves/hongloumeng/qwen35_9b_full_dpo
logs/dpo_YYYYMMDD_HHMMSS/
```

训练后继续用同背景角色对比评估：

```bash
MODEL_PATH=saves/hongloumeng/qwen35_9b_full_dpo \
SCENARIO_LIMIT=12 \
MAX_NEW_TOKENS=160 \
DO_SAMPLE=false \
scripts/compare_role_reactions.sh
```

输出角色区分度报告：

```bash
latest=$(ls -td saves/hongloumeng/role_compare_* | head -1)
python3 scripts/evaluate_role_distinctness.py \
  "${latest}/role_compare.jsonl" \
  --out "${latest}/role_distinctness_report.md"
cat "${latest}/role_distinctness_report.md"
```

如果当前远程机器上实际跑出来的是旧 LoRA DPO 输出，用这个路径评估：

```bash
MODEL_PATH=saves/hongloumeng/qwen35_9b_dpo_lora \
SCENARIO_LIMIT=12 \
MAX_NEW_TOKENS=160 \
DO_SAMPLE=false \
scripts/compare_role_reactions.sh

latest=$(ls -td saves/hongloumeng/role_compare_* | head -1)
python3 scripts/evaluate_role_distinctness.py \
  "${latest}/role_compare.jsonl" \
  --out "${latest}/role_distinctness_report.md"
cat "${latest}/role_distinctness_report.md"
```

当前 DPO 训练配置：

```text
framework: LLaMA-Factory
stage: dpo
finetuning_type: full
deepspeed: ZeRO-3
precision: bf16
learning_rate: 5e-6
epochs: 1
pref_beta: 0.1
pref_ftx: 0.05
eval_strategy: steps
eval_steps: 25
save_strategy: steps
save_steps: 25
```

当前 SFT 训练配置：

```text
framework: LLaMA-Factory
finetuning_type: full
deepspeed: ZeRO-3
precision: bf16
flash_attn: disabled
cutoff_len: 4096
per_device_train_batch_size: 1
gradient_accumulation_steps: 8
learning_rate: 1e-5
epochs: 2
logging_steps: 5
eval_strategy: steps
eval_steps: 25
save_strategy: steps
save_steps: 25
save_total_limit: 5
eval_dataset: hongloumeng_sft_val
report_to: wandb
```

## Git 使用

当前远端：

```bash
git remote -v
```

预期：

```text
origin  git@github.com:<your-org-or-user>/role_creator.git (fetch)
origin  git@github.com:<your-org-or-user>/role_creator.git (push)
```

推送：

```bash
git push
```

如果本地还没有绑定 upstream：

```bash
git push --set-upstream origin main
```

## 下一步

```text
1. 在 B200 训练机跑通 BehaviorExecutor 全参 SFT
2. 抽样评估生成质量
3. 训练 RoleCritic 分类器
4. 做离线候选重排
5. 用全参 DPO 拉开同背景下的角色反应差异
6. 再考虑 GRPO 或更强的自动偏好打分
```

ai-short-drama-role-consistency

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README