🧩 LLM Structured Output Benchmarks

作者：stephenleo（Marie Stephen Leo），GitHub：stephenleo，LinkedIn：Marie Stephen Leo，DOI：10.5281/zenodo.12327266

🎯 一句话总结

一款专注于 LLM 结构化输出能力的标准化基准测试工具，通过多任务、多框架对比，直观呈现各结构化方案在可靠性、精度和延迟上的差异，帮助开发者为具体业务场景选择最优方案。

📖 背景故事：为什么需要这个工具？

当开发者想让 LLM 输出结构化数据（如 JSON、枚举、Pydantic 模型）时，市面上涌现了大量方案——Instructor、Mirascope、Outlines、LMFormatEnforcer、Marvin、Fructose、LlamaIndex……每个框架都声称自己"更好"。但实际效果如何？延迟多少？可靠性怎样？不同任务上的表现差异大不大？

在 Marie Stephen Leo 的 Medium 博客中，他详细描述了做这个项目的动机：他和团队在真实项目中选型时发现，没有统一的基准来对比这些框架，于是决定自己动手，用科学的方法——标准化测试环境、统一评估指标——给出客观答案。

这个项目自 2024 年 6 月发布至今（2026 年 7 月），已获得 189 颗 Stars，覆盖了当前主流的结构化输出框架，堪称该领域的"评测百科"。

🧱 核心功能：三大任务 × 十大框架

项目设计了三个典型任务来覆盖结构化输出的主流场景：

任务	说明	典型应用
多标签分类（multilabel_classification）	从预定义标签集合中选出所有适用的类别	内容审核、话题标注、情感多维度分析
命名实体识别（ner）	提取文本中的实体及其类型	简历解析、医疗记录提取、法律文档分析
合成数据生成（synthetic_data_generation）	根据提示词生成符合 Pydantic 模型的随机数据	测试数据生成、数据增强、模拟真实场景

目前已接入的框架包括：

框架	核心机制	重试机制
Instructor	基于 Pydantic 模型定义输出结构，自动解析	✅ 支持（可配置重试次数）
Mirascope	装饰器驱动的 LLM 调用 + 结构化响应	✅ 支持
Outlines	CFG（上下文无关文法）引导解码，严格控制输出格式	❌ 不支持重试（依赖 Grammar 约束）
LMFormatEnforcer	字符级 JSON 状态机，逐步构建合法 JSON	❌ 不支持重试
Fructose	Rust 驱动的高性能 JSON 解析器	❌ 不支持重试
Marvin	AI 声明式编程风格，零样本分类/实体提取	✅ 支持
LlamaIndex	基于 LLM 输出解析器的结构化提取	支持
Vanilla OpenAI	直接调用 OpenAI API（baseline 对照组）	✅ 支持
Modelsmith	结构化输出工具	支持
OpenAI Structured Output	OpenAI 官方的 strict mode 结构化输出	✅ 支持

📊 评估指标：三重维度看框架

项目从三个维度量化框架表现：

Reliability（可靠性）：多次运行中，框架成功返回符合 schema 的输出的比例。成功率越高，说明框架对不同 prompt 变化的鲁棒性越强。
Precision / Recall / F1（NER 任务专用）：对于命名实体识别任务，计算各类实体的 micro 级别精确率、召回率和 F1 分数，衡量框架提取实体的准确性。
Latency P95（延迟）：第 95 百分位响应时间——即 95% 的请求都在这个时间内完成。对于生产环境，这个指标比平均值更能反映用户体验。

从 README 公布的初步结果来看，Fructose 和 OpenAI Structured Output 在可靠性上均达到 1.000（100% 成功），Outlines/LMFormatEnforcer 紧随其后，而依赖纯 prompt engineering 的 Vanilla OpenAI 可靠性相对较低。延迟方面，Grammar 约束类方法（Outlines/LMFormatEnforcer）因为减少了 token 协商，通常比纯重试驱动的方法更高效。

⚙️ 技术架构：模块化工厂模式

项目的代码架构非常清晰，体现了作者的工程素养：

frameworks/ 目录：每个框架对应一个独立的 .py 文件，继承自 BaseFramework 抽象基类。基类定义了统一的 run() 接口和 @experiment 装饰器，保证所有框架以相同方式统计延迟和成功率。
frameworks/__init__.py 中的 factory() 函数：根据配置文件中指定的框架名称动态实例化对应的框架类，支持热插拔新框架而无需修改主流程。
@experiment 装饰器：这是一个精妙的设计——它将"重复运行 + 统计指标"的逻辑从具体框架实现中解耦出来。任何 run() 方法只需加上这个装饰器，即可自动获得 n 次运行、延迟记录和成功率计算的能力。
data_sources/data_models.py：定义了三个 Pydantic 数据模型，分别对应三个任务。值得注意的是 pydantic_to_dataclass() 函数，可以将 Pydantic 模型转换为标准 dataclass，这在需要与纯 Python dataclass 生态交互时非常有用。
config.yaml：配置驱动——每个框架的每次任务配置都在 YAML 中声明，包括使用的 LLM 模型、prompt 模板、数据路径和运行次数。添加新框架或新任务，只需在对应位置加上配置，无需改动 Python 代码。

整体技术栈为：Python 3.11 + Pydantic + Typer（CLI）+ Loguru（日志）+ PyTorch（本地模型支持）+ Transformers + Accelerate + BitsAndBytes（量化推理）。

🚀 如何运行：本地 CLI 方式

项目没有 Web UI，是纯 CLI 工具。安装和运行步骤：

# 克隆仓库
git clone https://github.com/stephenleo/llm-structured-output-benchmarks.git
cd llm-structured-output-benchmarks

# 以开发模式安装（项目内有 frameworks/ 子目录需要被识别）
pip install -e .

# 运行基准测试（默认使用 config.yaml 配置）
python -m main run-benchmark

# 或指定配置文件路径
python -m main run-benchmark --config-path config.yaml

环境要求：Python 3.11+，支持 OpenAI API Key（默认使用 gpt-4o-mini）。同时支持本地模型（如通过 Transformers 加载的模型），需要 CUDA GPU 环境。

扩展自定义测试：

准备 pickle 格式的数据文件，放入 data/ 目录
在 config.yaml 中添加新框架配置（或在现有框架下添加新任务）
在 frameworks/ 中新建对应的 xxx_framework.py，继承 BaseFramework
运行 python -m main run-benchmark 即可

⚠️ 局限与争议

仅覆盖结构化输出，未覆盖格式验证后的语义正确性：框架能返回合法的 JSON/Pydantic 对象，但对象的语义是否符合业务意图，仍需人工评估。
依赖 OpenAI gpt-4o-mini 作为默认模型：结果仅反映该模型的能力。不同模型对结构化约束的接受程度差异很大（尤其是 GPT-4o 与 Claude 3.5 的 JSON Mode 行为差异），跨模型对比才是更有价值的评测方向。
没有自动化报告可视化：benchmark 运行后生成 pickle 文件，需要自己编写分析脚本来可视化结果。项目内有 plotly 依赖，但似乎没有内置图表生成逻辑。
任务数量有限：目前只有 3 个任务。真实业务中的结构化输出场景远不止这些——例如链式调用（先提取实体，再查询数据库，再生成报告）、条件输出（有选择性地返回不同 schema）等复杂场景尚未覆盖。

🌟 行业意义与竞争格局

该项目处于一个快速发展的细分领域。2025 年以后，LLM 结构化输出赛道出现了多个强力竞争者：

StructEval（arXiv:2505.20139）：更全面的评测体系，覆盖 18 种格式（JSON、YAML、CSV、HTML、React、SVG 等），44 种任务类型，提出"格式保真度"和"结构正确性"的量化指标，评测对象是各大基础模型本身而非中间框架。
Cleanlab Structured Output Benchmark：关注现有公开评测集中的标注错误问题，提供 4 个经过严格清洗的数据集。
BAML vs DSPy 对比（thedataquarry/structured-outputs）：在小模型和嵌套 JSON 场景下，BAML 表现优于 DSPy，反映了结构化输出方案对模型能力的强依赖性。

尽管如此，llm-structured-output-benchmarks 的独特价值在于：它评测的是框架层而非模型层，帮助开发者在选型阶段做出数据驱动的决策，而非依赖文档或直觉。

📦 适用人群

AI 应用开发者：正在为项目选择结构化输出方案，需要对比 Instructor vs Outlines vs Mirascope 的实际效果
框架作者/贡献者：了解自家框架在真实任务上的表现，发现优化方向
LLM 应用研究者：研究不同结构化约束方法对 LLM 输出的影响
工程团队 Tech Lead：制定团队内部的结构化输出技术选型标准