aigcqa 0.1.0

Production-grade quality gate for AIGC videos — not a benchmark

AIGCQA

中文 | English

AIGC 视频生产级质量门控 —— 不是学术基准，是工程工具。

AIGCQA 填补了学术基准（VBench、EvalCrafter —— 慢、重、仅限研究）与生产质量门控（快速、轻量、可组合）之间的空白。

---

核心特性

• 4 个可组合指标：人脸质量、时序一致性、手部质量、技术质量
• 3 档后端：fast（无需 GPU）/ light（消费级 GPU，CLIP-IQA + open_clip）/ full（LMM）
• 可解释输出：不只是一个数字，精确定位到哪一帧有什么问题
• 多格式输出：JSON / HTML（含雷达图 + 帧时间轴）
• 多接入方式：CLI、Python API、ComfyUI 节点

---

安装

pip install aigcqa                # fast 后端（无需 GPU）
pip install aigcqa[light]         # + piq CLIP-IQA + open_clip 时序分析
pip install aigcqa[full]          # + LMM 解释器（Qwen2.5-1.5B-Instruct）

---

快速开始

from aigcqa import quick_assess

result = quick_assess("video.mp4")
print(result.passed)           # True / False
print(result.overall_score)    # 例如 82.4
print(result.recommendation)   # "建议重新生成 frames 30-67"
result.to_html("report.html")  # 含雷达图 + 帧时间轴的 HTML 报告

---

完整流水线

from aigcqa import QualityPipeline, FaceMetric, TemporalMetric, HandMetric, TechnicalMetric

pipe = QualityPipeline(
    metrics=[
        FaceMetric(backend="light"),
        TemporalMetric(backend="light"),
        HandMetric(backend="fast"),
        TechnicalMetric(backend="light"),
    ],
    threshold=80.0,
    weights={"face": 0.3, "temporal": 0.3, "hand": 0.2, "technical": 0.2},
)
report = pipe.run("output.mp4")
report.to_html("report.html")
print(report.to_json())

---

CLI

# 基础评测
aigcqa assess video.mp4

# light 后端，自定义阈值，输出 HTML
aigcqa assess video.mp4 --backend light --threshold 80 --output report.html

# JSON 输出
aigcqa assess video.mp4 --format json

# 使用 LMM 解释器
aigcqa assess video.mp4 --explainer lmm --lmm-model Qwen/Qwen2.5-1.5B-Instruct

# 批量评测整个目录
aigcqa batch ./outputs/

# 查看所有指标
aigcqa list-metrics

---

指标说明

指标	fast 后端	light 后端	full 后端
face	OpenCV Haar + 拉普拉斯清晰度	+ CLIP 零样本人脸质量	Qwen2-VL
temporal	LPIPS 帧间差异	+ open_clip 身份漂移检测	T2VQA
hand	MediaPipe 手部检测	+ 骨架几何规则校验	HandEval + CLIP
technical	亮度/曝光分析	piq CLIP-IQA	FAST-VQA

后端对比

后端	速度	是否需要 GPU	精度	适用场景
fast	<0.5s/帧	否	基础	CI 流水线、快速过滤
light	~1s/帧	消费级 GPU	中等	日常生产工作流
full	~3s/帧	多卡	最高	最终质量验收

---

输出格式

{
  "overall_score": 68.4,
  "passed": false,
  "threshold": 75.0,
  "source": "output.mp4",
  "metrics": {
    "face": {"score": 82.1, "issues": [...], "meta": {...}},
    "temporal": {"score": 41.3, "issues": [...], "meta": {...}}
  },
  "explanation": {
    "backend": "rule",
    "summary": "视频时序一致性存在明显问题",
    "recommendation": "建议重新生成 frames 30-45",
    "detail": "时序一致性 41分（较差）；人脸质量 82分（良好）"
  }
}

---

LMM 解释器

from aigcqa import QualityPipeline, TechnicalMetric, FaceMetric, LMMExplainer

pipe = QualityPipeline(
    metrics=[TechnicalMetric(backend="light"), FaceMetric(backend="light")],
    explainer=LMMExplainer(model_name="Qwen/Qwen2.5-1.5B-Instruct"),
)
report = pipe.run("video.mp4")
print(report.explanation.summary)  # 自然语言质量分析

---

ComfyUI 集成

将 examples/comfyui_node.py 复制到 ComfyUI/custom_nodes/aigcqa_node.py。

注册两个节点：

• AIGCQA Quality Gate：输入 IMAGE batch → 输出分数、是否通过、报告 JSON
• AIGCQA Report Renderer：输入报告 JSON → 输出 HTML

---

学术背景

• DOVER (ICCV 2023)：分离式目标视频质量评估，美学 + 技术双分支
• HandEval (arXiv 2510.08978, 2025)：首篇生成图像手部质量评估论文
• NTIRE 2025 XGC Challenge：说话人头部质量评估，直接验证数字人质量市场需求
• VQAThinker (2025)：具备推理能力的可解释 VQA
• AgenticIQA (2025)：可解释图像质量评估的智能体框架

---

Roadmap

版本	状态	功能
v0.1.0	✅ 已发布	4 指标全后端（fast/light）、规则/LMM 解释器、CLI、HTML+JSON、ComfyUI
v1.0	规划中	full 后端（FAST-VQA、LLaVA）、REST API 服务

---

License

MIT — 详见 LICENSE