BRAG-Pipeline

BRAG-Pipeline 是一个面向社交语境理解与回复生成的 LLM Agent 流程。系统会识别说话者的隐含表达机制，推断意图与期望反馈，选择回复策略，评估社交风险，并生成符合场景约束的短回复。

项目保留完整主流程：SkillFlow、结构化 Memory、response few-shot、本地规则校准、格式检查、dev 评分和 test 输出生成。

目录结构

BRAG-Pipeline/
├── data/                 # train、dev、test 数据
├── memory/               # 内置结构化 memory
├── scripts/              # 评分、格式检查和 test 运行脚本
├── src/                  # Pipeline、Skills、检索和后处理
├── tests/                # 离线单元测试
├── outputs/              # 运行结果，默认不提交到 Git
├── config.py             # 运行模式和功能配置
├── main.py               # 主入口
├── README.md
└── requirements.txt

安装

建议使用 Python 3.10 或更高版本。

pip install -r requirements.txt

复制 .env.example 为 .env。默认示例使用本地 Ollama Gemma3 12B：

OPENAI_BASE_URL=http://127.0.0.1:11434/v1
OPENAI_API_KEY=ollama
OPENAI_MODEL=gemma3:12b

模型名只在 .env 中设置，不需要写进代码。

常用配置

打开 config.py 修改顶部配置：

RUN_MODE = "dev"  # smoke / dev / test

USE_MEMORY = True
USE_FEWSHOT = True
FEWSHOT_RETRIEVAL_MODE = "jaccard"
MEMORY_ROUTER_MODE = "llm_rerank"

RUN_ERROR_ANALYSIS = True
SAVE_ERROR_MEMORY = False
USE_GENERATED_MEMORY = False

常用含义：

• RUN_MODE：选择冒烟测试、完整 dev 或最终 test。
• USE_MEMORY：加载 memory/memory.jsonl 中的结构化经验。
• USE_FEWSHOT：从 data/train.jsonl 检索 response 示例。
• MEMORY_ROUTER_MODE：控制 Memory 注入方式，默认 llm_rerank。
• RUN_ERROR_ANALYSIS：完整 dev 后生成错误分析。
• SAVE_ERROR_MEMORY：将错误分析候选写入 memory/generated.jsonl，默认关闭。
• USE_GENERATED_MEMORY：推理时加载人工确认后的生成记忆，默认关闭。

运行方式

三种模式都使用同一个入口：

python main.py

Smoke

在 config.py 中设置：

RUN_MODE = "smoke"

读取 dev 前 3 条，执行完整流程、格式检查和代理评分，适合检查 API 与环境是否可用。

Dev

在 config.py 中设置：

RUN_MODE = "dev"

读取全部 dev，执行格式检查、代理评分和结果记录。启用 RUN_ERROR_ANALYSIS 时会额外生成错误分析。

Test

最终 test 推荐使用专用脚本。先 dry-run 查看配置：

python scripts/run_final_test.py --dry-run

确认后运行：

python scripts/run_final_test.py

输出文件位于：

outputs/<run_id>/submission.jsonl

主流程

输入校验
  ↓
MechanismSkill：机制分类、规则校准、条件复核和缓存
  ↓
UnderstandingSkill：生成意图和期望反馈
  ↓
StrategySkill：根据场景规则矩阵选择回复策略
  ↓
RiskSkill：生成风险标签和风险控制计划
  ↓
ResponseSkill：结合 Memory 与 few-shot 生成回复
  ↓
ResponseRiskReviewSkill：检查过誉、说教、问句和策略一致性
  ↓
ValidatorSkill：校验七字段输出
  ↓
RewriterSkill：仅在校验失败时修复

机制分类只使用原帖文本，避免平台、关系或互动目标改变表达机制。策略选择使用确定性规则矩阵。回复生成使用模型，并注入结构化 Memory 与 response few-shot 示例。

Memory 与 Few-shot

memory/memory.jsonl 内置 48 条结构化 memory，覆盖机制规则、混淆规则、策略规则、场景规则、风险规则、回复风格和反模式。

Few-shot 默认从 data/train.jsonl 使用本地 Jaccard 检索，不依赖额外 embedding 服务。当前默认只为 ResponseSkill 检索示例，机制和策略不使用近邻投票。

输出文件

每次运行会生成独立目录：

outputs/<run_id>/
├── submission.jsonl
├── RES.md
├── run_manifest.json
├── format_report.json
├── dev_eval_report.json      # smoke/dev
├── error_analysis/           # dev 且启用错误分析时
└── debug/
    ├── trace.jsonl
    ├── fewshot.jsonl
    └── input_subset.jsonl    # smoke

outputs/ 默认被 Git 忽略，只保留 .gitkeep。

检查

运行单元测试：

python -m unittest discover -s tests -v

检查提交格式：

python scripts/format_checker.py outputs/<run_id>/submission.jsonl data/test_input.jsonl

Git 提交说明

以下内容默认不提交：

• .env
• .agent/
• outputs/*
• memory/generated.jsonl
• __pycache__/、.pytest_cache/、.cache/

公开仓库只保留运行代码、必要数据、内置 memory、测试和 README。