arag-query-expand

arag-query-expand

面向 Qwen3-VL 的多模态 Query Expansion 训练脚手架，支持图片输入、结构化输出、多语言与多阶段训练（SFT/GRPO），并提供公开数据源与网页抓取的预留接口。

目标

• 输入：图像 + 文本查询
• 输出：固定字段结构（每行一个字段），用于多路检索融合（BM25 / Dense / Hybrid / HyDE + 视觉字段）
• 训练：SFT → GRPO（可选）

目录结构

• configs/：数据与训练配置
• scripts/：命令行入口
• src/：核心代码
• data/：本地数据（默认不入库）

输出字段规范

默认字段（可在 configs/pipeline.yaml 或 configs/data.yaml 调整）：

lang
intent
entities
constraints
bm25
dense
hybrid
hyde
vision_ocr
vision_scene
vision_anchors

要求：每行一个字段，格式为 field: value。

训练流程概览

1. 准备数据
   • 公开数据集 → manifest.jsonl
   • 通过第三方 LLM 生成结构化输出 → train.jsonl
2. SFT 微调
   • LoRA/QLoRA，支持图文
3. GRPO 强化（可选）
   • 用规则奖励函数优化结构一致性、多样性、视觉一致性
4. 推理验证
   • 图文输入 → 结构化输出

---

一键流程（推荐）

1) 配置公开数据集

编辑 configs/pipeline.yaml 中 public_datasets 段落（已内置推荐数据集组合）。

2) 设置 OpenAI API Key

export OPENAI_API_KEY=你的key

3) 生成 manifest 与训练集

python scripts/prepare_pipeline.py --config configs/pipeline.yaml

生成结果：

• data/manifest.jsonl
• data/train.jsonl

断点续跑（检查进度并自动继续）

python scripts/resume_pipeline.py --config configs/pipeline.yaml

只查看进度：

python scripts/resume_pipeline.py --config configs/pipeline.yaml --status-only

强制重建 manifest：

python scripts/resume_pipeline.py --config configs/pipeline.yaml --rebuild-manifest

---

分阶段训练指南（不同规模）

以下建议基于 4×16G 与 Qwen3-VL-2B-Instruct + QLoRA。

A. 小规模（1万-5万样本）

用途：快速 PoC、验证流程。

• SFT：epoch 2-3
• batch：2（卡内）× accum 8
• seq_len：2048
• 训练时间：数小时

B. 中规模（5万-20万样本）

用途：可用的基础版本。

• SFT：epoch 2-3
• 建议增加多语种、图文比例
• 训练时间：1-2 天

C. 大规模（20万-40万样本）

用途：稳定版本 + 多语种覆盖。

• SFT：epoch 1-2（避免过拟合）
• 可考虑更严格过滤 + 更高质量样本
• 训练时间：2-4 天

D. 超大规模（>40万样本）

用途：长期优化。

• 降低 epoch，增加采样质量门槛
• GRPO 比例控制在 10-20% 高质量子集

---

SFT 训练

配置文件：configs/sft.yaml

python scripts/run_sft.py --config configs/sft.yaml

关键参数建议：

• model_name_or_path: Qwen/Qwen3-VL-2B-Instruct
• use_qlora: true
• max_seq_len: 2048
• gradient_accumulation_steps: 8

---

GRPO 强化（可选）

配置文件：configs/grpo.yaml

python scripts/run_grpo.py --config configs/grpo.yaml

奖励函数位于：src/train/rewards.py 默认包含：

• format（结构完整）
• relevance（语义相关）
• diversity（bm25/dense/hybrid 多样性）
• vision_consistency（视觉一致性）
• language_consistency（语言一致性）

说明：TRL 的 GRPO API 版本可能变化，如报错需按实际版本微调 src/train/grpo.py。

---

推理验证

python scripts/expand.py \
  --model Qwen/Qwen3-VL-2B-Instruct \
  --image path/to/image.png \
  --query "你的查询"

---

数据构建细节

A. 构建 manifest（公开数据集）

python scripts/build_manifest.py --config configs/pipeline.yaml

B. 使用 OpenAI 生成 SFT 数据

python scripts/generate_sft.py --config configs/pipeline.yaml

---

manifest 格式示例

{"id":"1","type":"text","text":"段落内容","title":"标题","lang":"zh","image_path":null}
{"id":"2","type":"image","text":null,"title":"图片标题","lang":"en","image_path":"images/sample.jpg"}
{"id":"3","type":"multimodal","text":"说明文字","title":"标题","lang":"en","image_path":"images/sample.jpg"}

---

常见问题

1. 数据太大怎么办？

• 调整 max_rows 或增加筛选规则。

1. 训练显存不足？

• 降低 max_seq_len 或提高 gradient_accumulation_steps。

1. 输出格式漂移？

• 强化 SFT 模板，或启用 GRPO 的格式奖励。

---

下一步建议

• 增加更高质量的 query 合成策略（基于真实检索日志或业务 query）
• 引入 OCR/Caption 模型，将视觉信息写入 vision_* 字段
• 增加检索评估闭环（NDCG/MRR/Recall@K）