Kiln 测试资产库全解析:`tests/assets` 资产清单、来源归因与多模态提取测试实践

原创2026-10-13 07:31:462,163 阅读
文章标签:人工智能AI 应用大模型模型评测提示工程微调RAGAI Agent数据标注数据增强LLMOps本地部署桌面应用

Kiln 测试资产库全解析:tests/assets 资产清单、来源归因与多模态提取测试实践

本文以 Kiln 仓库中 libs/core/tests/assets/README.md 这份资产归因清单为核心,系统梳理仓库内置的 14 个跨媒体测试资产(PDF、CSV、文本、图片、音频、视频)的来源与生成方式,并结合 conftest.py、pytest_mock_files.py 等源码,讲透这些资产如何通过 pytest fixture 被多模态文档提取(extraction)、RAG 等模块消费。读完本文,你将掌握 Kiln 测试资产目录的完整图谱、正确的 fixture 使用姿势,以及测试资产在生产代码中的编码与传递链路。

一、为什么 Kiln 需要一份"资产归因"文档

Kiln 是一个面向 AI 系统的构建、评估与优化平台,其核心能力之一是从文档、图片、音频、视频等异构文件中提取结构化内容(参见 litellm_extractor.py 中的多模态编码逻辑)。这类功能对测试数据的要求非常苛刻:测试用例必须覆盖不同 MIME 类型、不同内容形态的真实文件,且这些文件必须可复现、可追溯、许可合规。

tests/assets 目录正是为此而设的"标准测试素材库",而 README 则充当这份素材库的来源账本(attribution manifest):它逐条记录每个资产来自哪里、由谁生成、使用何种许可。这解决了三个实际问题:

  1. 许可合规:测试资产常复用公开数据集或公开材料(arXiv 论文、NASA 图片等),必须明确许可条款,避免把第三方内容悄悄带进开源仓库;
  2. 可复现性:标注来源后,任何人(包括 CI、下游镜像、Agent 或 LLM 读者)都能追溯资产的原始出处;
  3. 可审计性:区分"真实世界样本"与"合成生成样本",让测试设计者清楚每个资产覆盖的边界。

这份 README 只有 40 行,但它定义了一个规范:仓库内的任何测试二进制资产,都应伴随一段来源说明。下面按目录逐类展开。

二、资产目录全景

资产统一存放在 libs/core/tests/assets/ 目录下,共 14 个文件(含 README 本身为 15 个),覆盖四大类 MIME 类型:

类别 文件 MIME 类型
文档 document_paper.pdf application/pdf
文档 document_people.csv text/csv
文档 document_ice_cubes.txt text/plain
文档 document_ice_cubes.md text/markdown
文档 document_ice_cubes.html text/html
图片 image_kodim23.png image/png
图片 image_nasa.jpg / image_nasa.jpeg image/jpeg
音频 audio_ice_cubes.wav audio/wav
音频 audio_ice_cubes.mp3 audio/mpeg
音频 audio_ice_cubes.ogg audio/ogg
视频 video_tv_bars.mp4 video/mp4
视频 video_tv_bars.mov video/quicktime

可以看到,这份清单几乎与 pytest_mock_files.py 中定义的 MockFileFactoryMimeType 枚举一一对应(见下文第四节),说明资产目录是专门为测试工厂按 MIME 类型取料而设计的。

三、逐项资产来源与生成方式(ATTRIBUTIONS 全文继承)

README 正文即是完整的归因清单,以下逐条保留原始信息并补充解读:

3.1 文档类资产

  • document_paper.pdf

    • 来源:https://arxiv.org/pdf/1706.03762(即著名的 "Attention Is All You Need" 论文摘录);
    • 描述:从 arXiv 下载的科研论文摘录,用于测试目的。arXiv 内容按其分发许可条款提供;
    • 用途解读:PDF 是文档提取(application/pdf)路径的典型样本,摘录自真实论文意味着包含标题、段落、数学符号、参考文献等真实排版结构,比人工捏造的 PDF 更能检验提取器的真实表现。
  • document_people.csv

    • 来源:使用 https://mockaroo.com/ 生成;
    • 描述:通过 Mockaroo(免费版,合成数据)创建的合成 CSV;
    • 用途解读:Mockaroo 是知名的在线合成数据生成服务,生成的 CSV 用于覆盖 text/csv 类型的表格结构提取测试。
  • document_ice_cubes.txt / document_ice_cubes.md / document_ice_cubes.html

    • 来源:使用 ChatGPT 生成;
    • 描述:关于冰块与冷饮的合成短文,同一内容提供三种格式(纯文本、Markdown、HTML);
    • 用途解读:三份文件内容同源但格式不同,非常适合验证同一提取器在 text/plain、text/markdown、text/html 三种 MIME 下的行为差异,例如 HTML 标签清理、Markdown 语法解析等。

3.2 图片类资产

  • image_kodim23.png

    • 来源:https://github.com/MohamedBakrAli/Kodak-Lossless-True-Color-Image-Suite;
    • 描述:Kodak 测试图第 23 号,广泛用于图像处理基准测试;
    • 用途解读:Kodak 图像套件是图像编码、压缩与质量评估领域的经典基准图集,用真实摄影图(而非色块图)测试视觉模型提取更贴近生产场景。
  • image_nasa.jpg / image_nasa.jpeg

    • 来源:https://www.nasa.gov/image-detail/gsfc-20171208-archive-e001436orig/;
    • 许可:公有领域(NASA,Public Domain);
    • 描述:来自 NASA 官方图片档案的地球观测图像;
    • 用途解读:同一张图同时提供 .jpg 与 .jpeg 两种扩展名,用于覆盖 image/jpeg MIME 下扩展名差异带来的边界情况;NASA 公有领域许可让该资产可以安全地随仓库分发。

3.3 视频类资产

  • video_tv_bars.mp4 / video_tv_bars.mov
    • 来源:使用 ChatGPT 生成;
    • 描述:展示经典电视彩条(TV color bars)并带运动的合成动画视频;
    • 用途解读:彩条视频色彩信息稳定、内容简单且可预期,是视频理解测试的理想最小样本;.mp4 与 .mov 分别对应 video/mp4 与 video/quicktime 两种 MIME。

3.4 音频类资产

  • audio_ice_cubes.wav / audio_ice_cubes.mp3 / audio_ice_cubes.ogg
    • 来源:使用 ChatGPT 生成;
    • 描述:一段合成语音,内容是 "I like putting ice cubes into my drink...";
    • 用途解读:同一句语音提供 WAV(无损)、MP3(有损压缩)与 OGG 三种编码,用于验证音频提取在不同编码格式下的兼容性。

四、资产如何被测试消费:MIME 枚举与 fixture 工厂

资产本身不会自动进入测试,它们通过三条 fixture 被注入到测试用例中,定义于根目录 conftest.py。

4.1 枚举:MockFileFactoryMimeType

libs/core/kiln_ai/pytest_mock_files.py 定义了字符串枚举 MockFileFactoryMimeType,其值与资产清单一一对应:

from enum import Enum

class MockFileFactoryMimeType(str, Enum):
    # documents
    PDF = "application/pdf"
    CSV = "text/csv"
    TXT = "text/plain"
    HTML = "text/html"
    MD = "text/markdown"

    # images
    PNG = "image/png"
    JPG = "image/jpeg"
    JPEG = "image/jpeg"

    # audio
    MP3 = "audio/mpeg"
    WAV = "audio/wav"
    OGG = "audio/ogg"

    # video
    MP4 = "video/mp4"
    MOV = "video/quicktime"

注意两个细节:JPG 与 JPEG 都映射到 image/jpeg(但底层指向不同扩展名的文件),MP3 使用官方的 audio/mpeg 而非常见的 audio/mp3——这与 litellm_extractor.py 中注释强调的"audio/mpeg 才是官方 MIME 类型"完全一致,说明枚举值与生产代码的 MIME 判定是同一套口径。

4.2 fixture 一:test_data_dir

conftest.py 中定义,直接解析出资产目录的绝对路径:

@pytest.fixture
def test_data_dir() -> Path:
    """The directory that contains test files with various mime types."""
    return Path(__file__).parent / "libs" / "core" / "tests" / "assets"

该路径基于 __file__ 动态计算,因此在任何工作目录下运行 pytest 都能正确定位资产,不依赖环境变量或相对 cwd。

4.3 fixture 二:mock_file_factory

conftest.py 是核心工厂:根据传入的 MockFileFactoryMimeType 匹配资产文件,并拷贝一份到 pytest 的 tmp_path 后返回新路径:

@pytest.fixture
def mock_file_factory(tmp_path, test_data_dir) -> Callable[[MockFileFactoryMimeType], Path]:
    def create_file(mime_type: MockFileFactoryMimeType) -> Path:
        match mime_type:
            # document
            case MockFileFactoryMimeType.PDF:
                filename = test_data_dir / "document_paper.pdf"
            case MockFileFactoryMimeType.CSV:
                filename = test_data_dir / "document_people.csv"
            case MockFileFactoryMimeType.TXT:
                filename = test_data_dir / "document_ice_cubes.txt"
            case MockFileFactoryMimeType.HTML:
                filename = test_data_dir / "document_ice_cubes.html"
            case MockFileFactoryMimeType.MD:
                filename = test_data_dir / "document_ice_cubes.md"
            # images
            case MockFileFactoryMimeType.PNG:
                filename = test_data_dir / "image_kodim23.png"
            case MockFileFactoryMimeType.JPG:
                filename = test_data_dir / "image_nasa.jpg"
            case MockFileFactoryMimeType.JPEG:
                filename = test_data_dir / "image_nasa.jpeg"
            # audio
            case MockFileFactoryMimeType.OGG:
                filename = test_data_dir / "audio_ice_cubes.ogg"
            case MockFileFactoryMimeType.MP3:
                filename = test_data_dir / "audio_ice_cubes.mp3"
            case MockFileFactoryMimeType.WAV:
                filename = test_data_dir / "audio_ice_cubes.wav"
            # video
            case MockFileFactoryMimeType.MP4:
                filename = test_data_dir / "video_tv_bars.mp4"
            case MockFileFactoryMimeType.MOV:
                filename = test_data_dir / "video_tv_bars.mov"
            case _:
                raise ValueError(f"No test file found for mime type: {mime_type}")

        # copy the file to the tmp path to avoid test contamination of the original file
        path_copy = tmp_path / f"{uuid.uuid4()!s}.{filename.suffix}"
        shutil.copy(filename, path_copy)
        return path_copy

    return create_file

这段实现包含一个重要的工程决策:绝不直接修改原始资产。测试代码拿到的永远是 tmp_path 下的随机文件名副本(uuid4 命名 + 保留原扩展名),这样即使某个测试对文件进行了改写或损坏,也不会污染仓库内的原始素材,保证资产目录在任意次测试运行后保持字节级一致。

4.4 fixture 三:mock_attachment_factory

conftest.py 在文件工厂之上再封装一层,产出数据模型层的 KilnAttachmentModel:

@pytest.fixture
def mock_attachment_factory(mock_file_factory):
    def create_attachment(
        mime_type: MockFileFactoryMimeType,
        text: str | None = None,
    ) -> "KilnAttachmentModel":
        from kiln_ai.datamodel.basemodel import KilnAttachmentModel

        if text is not None:
            return KilnAttachmentModel.from_data(text, mime_type)

        path = mock_file_factory(mime_type)
        return KilnAttachmentModel.from_file(path)

    return create_attachment

KilnAttachmentModel.from_file / from_data 定义在 basemodel.py:from_file 直接持有输入路径,from_data 会按 guess_extension(mime_type) 推断扩展名写入临时文件。这条 fixture 让测试可以直接从"MIME 类型"一步得到"附件模型",省去手工构造。

五、资产背后的生产链路:从 MIME 到模型输入

测试资产最终要喂给提取器。理解资产的价值,需要知道它们在生产代码中如何被处理——这由 litellm_extractor.py 的 encode_file_litellm_format 完成,其编码策略按 MIME 分派:

  1. 纯文本文档(application/pdf、text/csv、text/html、text/markdown、text/plain)以及通用音频/视频:编码为 LiteLLM 的通用 file 块,file_data 使用 data:{mime_type};base64,{...} 的 Data URL(见 encoding.py);
  2. 图片(image/*):使用专用的 image_url 块;
  3. OpenRouter 提供商的音频/视频:上游会拒绝通用 file 块,因此特判为 OpenAI 风格的 input_audio(带 format: "wav" | "mp3" | "ogg")与 video_url 块。

同时,base_extractor.py 中存在一条"直通(passthrough)"捷径:若文件的 MIME 命中 ExtractorConfig.passthrough_mimetypes,则直接 read_text 返回文件内容而不调用模型。换言之,测试资产的 MIME 值直接决定走直通还是模型提取路径,资产选型因此会影响测试的覆盖语义。

MIME 判定本身由 mime_type.py 的 guess_mime_type 负责,它对标准库 mimetypes.guess_type 做了覆盖修正(.mov → video/quicktime、.mp3 → audio/mpeg 等),与资产目录的扩展名设计遥相呼应。

六、测试消费实例与迁移历史

6.1 真实用例

  • test_litellm_extractor.py 用参数化方式遍历 TXT/MD/HTML/CSV/PNG/JPG/MP4/MP3 等多种资产,逐 MIME 断言提取器返回的 content 分类("Content from text file"、"Content from image file" 等);
  • test_document_api.py 作为服务端唯一消费者,通过根级 fixture 复用同一批资产,验证 document_api 的 RAG 工作流;
  • test_encoding.py 用 JPEG 资产验证 base64 Data URL 编码的正确性。

6.2 目录迁移:为什么在 libs/core/tests/assets

资产目录并非一直位于 libs/core 之下。据 root_cleanup 项目计划 记载,Phase 9 将资产从仓库根目录 tests/assets/ 迁移至 libs/core/tests/assets/,与主要消费方(core 库)就近存放,同时把 test_data_dir、mock_file_factory、mock_attachment_factory 等 fixture 从根 conftest.py 下放(根 conftest.py 仍保留实现),并为服务端消费者建立桥接。这说明资产目录位置是随项目演进而动态调整的,阅读代码时若在别处看到旧路径引用,应以 libs/core/tests/assets 为准。

七、如何在自己的测试中使用这批资产

在 Kiln 仓库内运行测试即可直接使用,无需任何安装步骤:

# 在仓库根目录运行(根 conftest.py 会自动注册 fixture)
python -m pytest libs/core/kiln_ai/adapters/extractors/test_litellm_extractor.py -v

在自己的测试函数中:

def test_pdf_extraction(mock_file_factory):
    pdf_path = mock_file_factory(MockFileFactoryMimeType.PDF)
    # pdf_path 指向 tmp_path 下的 PDF 副本,可直接交给提取器
    assert pdf_path.suffix == ".pdf"

def test_attachment_from_video(mock_attachment_factory):
    attachment = mock_attachment_factory(MockFileFactoryMimeType.MP4)
    # attachment 是 KilnAttachmentModel,input_path 指向资产副本

需要新增 MIME 覆盖时,遵循仓库既定约定:在 MockFileFactoryMimeType 中加枚举值、在 mock_file_factory 的 match 分支中登记资产文件名,并在 README 中补一行来源归因——这正是这份 ATTRIBUTIONS 文档存在的意义。

结语

Kiln 的测试资产目录是一套"小而完整"的多模态素材工程:README 负责来源与许可的可追溯性,fixture 工厂负责把资产安全地注入测试,提取器负责把资产转换成模型输入。理解这三层,既能读懂 Kiln 的测试体系,也能为自建多模态测试素材库提供可直接复用的范式——每一个测试资产都应有来源账本,每一条 MIME 路径都应有对应的真实样本。

登录后查看全文
Kiln