AVLingua

把预训练音视频编码器接入大语言模型的多模态框架——一条链路统一「视听问答、视频描述与多模态指令跟随」。

AVLingua 把音频编码器（如 Whisper / BEATs）与视频编码器（如 CLIP-ViT / VideoMAE） 产出的特征，经由投影器 / 适配层映射进大语言模型的词嵌入空间，再把这些 模态 token 织进多模态提示词，交给 LLM 完成生成式的视听理解任务。

整套推理链路是：

原始信号 ──▶ 模态编码器 ──▶ 投影器 ──▶ 多模态提示词 ──▶ 语言模型 ──▶ 文本
 (音/视频)     (T, D_enc)     (M, D_llm)    <video><audio>…        (回答/描述)

为什么再造一个框架

现有的 Video-LLaMA / LLaVA 系工作把「编码器 → 投影器 → LLM」耦合在庞大的 训练脚本里，想单独替换投影器、对比不同重采样策略、或在没有 GPU 的机器上 跑通一条最小链路都很费劲。AVLingua 的取舍是：

• 核心纯 NumPy、零重依赖：编码器、投影器、解码栈、提示词组装、评测指标 全部只依赖 NumPy，pip install avlingua 即可在 CPU / 无网络环境完整跑通。
• 确定性 mock 后端：内置可复现的 mock 音视频编码器与 mock LLM，让整条 链路无需任何预训练权重就能运行、测试与教学。
• 投影器可插拔：线性、MLP、Q-Former 查询重采样三种适配层开箱即用， 遵循统一接口，方便做消融。
• 真实后端可选：安装 avlingua[torch] 后，把编码器与 LLM 换成 HuggingFace 预训练权重，接口保持不变。

安装

pip install avlingua              # 纯 NumPy 核心
pip install "avlingua[torch]"     # 追加 torch + transformers 后端

从源码安装：

git clone https://github.com/HuggingNobody/avlingua.git
cd avlingua
pip install -e ".[dev]"

快速上手

from avlingua import AVLinguaConfig, AVLinguaModel
from avlingua.data import synth_sample

model = AVLinguaModel.from_config(AVLinguaConfig())
sample = synth_sample(seed=0)          # 一段合成的音视频素材

print(model.caption(sample))                     # 视频描述
print(model.answer(sample, "画面里发生了什么？"))   # 视听问答

命令行：

avlingua info                                   # 查看可用组件
avlingua demo -q "有什么声音？" --projector qformer
avlingua caption --projector mlp

核心组件

模块	作用
avlingua.encoders	音/视频编码器（mock + 可选 torch）
avlingua.projectors	线性 / MLP / Q-Former 投影器，把特征接入 LLM 空间
avlingua.prompt	多模态提示词组装：占位符 <audio> / <video> 展开
avlingua.generation	解码栈：温度、top-k、top-p、重复惩罚
avlingua.llm	语言模型后端（mock + 可选 HuggingFace 因果 LM）
avlingua.alignment	跨模态对比对齐与检索评测
avlingua.metrics	BLEU / ROUGE-L / CIDEr / QA-F1

更完整的说明见 docs/：架构、用法、设计笔记与 API 参考。

开发

pip install -e ".[dev]"
ruff check src tests
mypy src
pytest --cov=avlingua

许可证

MIT © You Tao