语言模型格式强制器

强制语言模型的输出格式（JSON Schema、正则表达式等）

语言模型能够生成文本，但在需要精确输出格式时，它们并不总是按指示执行。虽然已经提出了多种提示工程技巧来提高生成文本的鲁棒性，但这些方法并不总是足够有效。本项目通过在每个时间步过滤语言模型允许生成的标记，从而确保输出格式得到遵守，同时将对语言模型的限制降至最低。

安装

pip install lm-format-enforcer

基础教程

# 如果在配备T4 GPU的Google Colab上运行，需安装以下依赖。
!pip install transformers torch lm-format-enforcer huggingface_hub optimum
!pip install auto-gptq --extra-index-url https://huggingface.github.io/autogptq-index/whl/cu118/ 

from pydantic import BaseModel
from lmformatenforcer import JsonSchemaParser
from lmformatenforcer.integrations.transformers import build_transformers_prefix_allowed_tokens_fn
from transformers import pipeline

class AnswerFormat(BaseModel):
    first_name: str
    last_name: str
    year_of_birth: int
    num_seasons_in_nba: int

# 创建一个transformers管道
hf_pipeline = pipeline('text-generation', model='TheBloke/Llama-2-7b-Chat-GPTQ', device_map='auto')
prompt = f'以下是关于迈克尔·乔丹的信息，采用以下JSON模式：{AnswerFormat.schema_json()} :\n'

# 创建一个字符级解析器，并基于它构建transformers前缀允许标记函数
parser = JsonSchemaParser(AnswerFormat.schema())
prefix_function = build_transformers_prefix_allowed_tokens_fn(hf_pipeline.tokenizer, parser)

# 使用前缀函数调用管道
output_dict = hf_pipeline(prompt, prefix_allowed_tokens_fn=prefix_function)

# 提取结果
result = output_dict[0]['generated_text'][len(prompt):]
print(result)
# {'first_name': 'Michael', 'last_name': 'Jordan', 'year_of_birth': 1963, 'num_seasons_in_nba': 15}

功能与优势

• 适用于任何Python语言模型和分词器。目前已支持transformers、LangChain、LlamaIndex、llama.cpp、vLLM、Haystack、NVIDIA TensorRT-LLM以及ExLlamaV2。
• 支持批量生成和束搜索——每个输入或束在每个时间步都可以有不同的标记被过滤。
• 支持JSON Schema、JSON Mode（无模式）和正则表达式格式。
• 支持JSON模式中的必填字段和可选字段。
• 支持JSON模式中的嵌套字段、数组和字典。
• 允许语言模型自由控制JSON模式中的空格和字段顺序，从而减少幻觉现象。
• 不修改transformers API的高层循环，因此可在任何场景下使用。

与其他库的比较

功能	语言模型格式强制器	Guidance	Jsonformer	Outlines
正则表达式	✅	✅	❌	✅
JSON Schema	✅	🟡（可通过部分转换实现）	✅	✅
批量生成	✅	❌	❌	✅
束搜索	✅	❌	❌	✅
集成到现有管道	✅	❌	❌	✅
可选JSON字段	✅	❌	❌	❌
LLM控制JSON字段顺序和空格	✅	❌	❌	❌
包含递归类的JSON Schema	✅	❌	✅	❌
视觉模型支持	✅	✅	❌	❌

发现错误？或者该库已更新新功能？请提交问题！

详细示例

我们创建了一个Google Colab笔记本，其中包含如何使用此库强制llama2输出格式的完整示例，还包括对中间结果的解释。该笔记本可以在Colab的免费GPU运行环境中运行。

你也可以在GitHub上查看该笔记本。

有关与Hugging Face Transformers集成的不同方式，请参阅单元测试。

vLLM 服务器集成

LM Format Enforcer 已集成到 vLLM 推理服务器中。vLLM 包含一个与 OpenAI 兼容的服务器，该服务器具备额外的功能，允许在无需编写自定义推理代码的情况下使用 LM Format Enforcer。

您可以通过添加 vLLM 命令行参数 来在 vLLM 的 OpenAI 服务器中使用 LM Format Enforcer：

python -m vllm.entrypoints.openai.api_server \
  --model mistralai/Mistral-7B-Instruct-v0.2 \
  --guided-decoding-backend lm-format-enforcer

或者，您也可以在每次请求时通过将 guided_decoding_backend 参数与引导解码参数一起添加到请求中来实现：

completion = client.chat.completions.create(
  model="mistralai/Mistral-7B-Instruct-v0.2",
  messages=[
    {"role": "user", "content": "请分类以下情感：LMFE 非常棒！"}
  ],
  extra_body={
    "guided_regex": "[Pp]ositive|[Nn]egative",
    "guided_decoding_backend": "lm-format-enforcer"
  }
)

此外，JSON 模式和选项解码也支持通过 guided_json 和 guided_choice 额外参数 实现。

它是如何工作的？

该库通过将字符级解析器和分词器前缀树结合，形成一种智能的标记过滤机制。

字符级解析器

将字符串解析为任何格式都可以被视为一种隐式的树结构——在解析过程中的任何时刻，都有一组允许的下一个字符；一旦选择了其中任何一个字符，就会产生一组新的允许的下一个字符，以此类推。

CharacterLevelParser 是一个用于按照这种隐式结构进行解析的接口。add_character() 和 get_allowed_characters() 可以看作是树的遍历方法。

该接口有多种实现：

• JsonSchemaParser —— 根据 JSON 模式进行解析（或纯 JSON 输出——JsonSchemaParser(None) 将允许任何 JSON 对象）。
• StringParser —— 强制生成精确的字符串（主要用于诊断）。
• RegexParser —— 根据正则表达式进行解析。需要注意的是，它不能使用 Python 内置的正则表达式引擎，而是使用手动实现的版本（通过 interegular 库），因此无法完全覆盖所有的正则表达式标准。

分词器前缀树

给定某种语言模型所使用的分词器，我们可以构建该语言模型能够生成的所有标记的前缀树。具体做法是生成所有可能的标记序列，并将其添加到树中。 详情参见 TokenizerPrefixTree。

两者的结合

有了字符级解析器和分词器前缀树，我们就可以优雅且高效地过滤出语言模型在下一个时间步中被允许生成的标记： 我们只遍历同时存在于字符级解析节点和分词器前缀树节点中的字符。这样就能找到所有的标记（包括复杂的子词标记，例如 ","，这在 JSON 解析中至关重要）。我们在两棵树上递归执行此操作，并返回所有允许的标记。当语言模型生成一个标记时，我们会根据新字符推进字符级解析器，以便为下一个时间步的过滤做好准备。

这种方法有何不同？为什么它更好？

这并不是第一个用于强制语言模型输出格式的库。然而，其他类似的库（如 Guidance、JsonFormer 和 Outlines）会强制要求严格的输出格式。这意味着语言模型无法控制空格、字段的可选性以及字段的顺序（以 JSON 为例）。虽然这对人类来说似乎无关紧要，但这意味着语言模型可能不会生成它“想要”的 JSON 格式，从而导致其内部状态处于次优值，进而降低后续时间步的输出质量。

这就迫使语言模型的使用者必须了解他们所使用的语言模型的具体细节（例如，JSON 是否在预训练之前就已经被压缩过？），并修改相关库以生成精确的格式。

而我们则通过扫描潜在的下一个标记，并允许任何能够被解析为所需输出格式的标记序列来避免这一问题。这意味着语言模型可以自主控制这些方面，以最自然的方式输出与其风格相符的标记序列，而无需开发者深入了解底层细节。

诊断 - 我是否总能获得良好的结果？

使用该库可以确保输出符合指定格式，但并不能保证语义上的正确性。强制语言模型遵循特定的输出格式可能会导致幻觉现象增多。通过提示工程引导模型仍然更有可能改善结果。

为了帮助您理解格式强制带来的激进性，如果您在调用 generate_enforced() 时，在 kwargs 中传递 output_scores=True 和 return_dict_in_generate=True（这些都是 transformers 库中已有的可选参数），您还将得到一个逐 token 的数据框，显示每个被选择的 token、其得分，以及如果不应用格式强制的话原本会被选择的 token 是什么。如果发现格式强制器迫使语言模型选择了权重非常低的 token，这很可能是导致结果不佳的原因之一。您可以尝试修改提示，以引导语言模型避免让格式强制器过于激进。

以下是一个使用正则表达式格式 Michael Jordan was Born in (\d)+. 的示例：

idx	generated_token	generated_token_idx	generated_score	leading_token	leading_token_idx	leading_score
0	▁	29871	1.000000	▁	29871	1.000000
1	Michael	24083	0.000027	▁Sure	18585	0.959473
2	▁Jordan	18284	1.000000	▁Jordan	18284	1.000000
3	▁was	471	1.000000	▁was	471	1.000000
4	▁Born	19298	0.000008	▁born	6345	1.000000
5	▁in	297	0.994629	▁in	297	0.994629
6	▁	29871	0.982422	▁	29871	0.982422
7	1	29896	1.000000	1	29896	1.000000
8	9	29929	1.000000	9	29929	1.000000
9	6	29953	1.000000	6	29953	1.000000
10	3	29941	1.000000	3	29941	1.000000
11	.	29889	0.999512	.	29889	0.999512
12	</s>	2	0.981445	</s>	2	0.981445

从表中可以看出，模型“想要”用 Sure 开头，但格式强制器却迫使其使用了 Michael——在第 1 个 token 处出现了较大的差距。此后，几乎所有的领先得分都落在允许的 token 集合内，这意味着模型可能并未因 token 强制而产生幻觉。唯一的例外是第 4 个时间步——“Born”被强制出现，而 LLM 原本希望选择的是“born”。这对提示工程师来说是一个提示：可以将提示中的 “Born” 改为小写的 “born”。

配置选项

LM Format Enforcer 使用多种启发式方法来避免语言模型生成结构化输出时可能出现的边缘情况。 有两种方式可以控制这些启发式方法：

选项 1：通过环境变量

有几个环境变量可以设置，它们会影响库的行为。这种方法在不希望修改代码时很有用，例如通过 vLLM OpenAI 服务器使用该库时。

• LMFE_MAX_CONSECUTIVE_WHITESPACES - 解析 JsonSchema 对象时允许的最大连续空格数。默认值：12。
• LMFE_STRICT_JSON_FIELD_ORDER - JsonSchemaParser 是否应强制属性按照 JsonSchema 的 required 列表中的顺序出现？（注意：这与 Pydantic 模型中的声明顺序一致）。默认值：False。
• LMFE_MAX_JSON_ARRAY_LENGTH - 如果模式未指定，则 JSON 数组的最大长度是多少。有助于防止 LLM 进入无限循环。默认值：20。
• LMFE_DEFAULT_ALPHABET - 默认使用的允许字符集是什么？请参阅 consts.py 了解默认值。可以覆盖并扩展以包含特定语言的字符。如果您希望这些字符作为 JsonSchemaParser 中的 JSON 键或枚举值出现，则需要此设置。

选项 2：通过 CharacterLevelParserConfig 类

当通过代码使用该库时，任何 CharacterLevelParser（如 JsonSchemaParser、RegexParser 等）的构造函数都会接收一个可选的 CharacterLevelParserConfig 对象。

因此，要配置单个解析器的启发式方法，只需实例化一个 CharacterLevelParserConfig 对象，修改其值，并将其传递给 CharacterLevelParser 的构造函数。

已知问题和限制

• LM Format Enforcer 需要 Python API 来处理语言模型的输出 logits。这意味着在 API 尚未扩展之前，它无法与 OpenAI ChatGPT 及类似基于 API 的解决方案一起使用。
• 正则表达式语法并非 100% 支持。有关详细信息，请参阅 interegular。
• LM Format Enforcer 的正则表达式解析器只能生成存在于分词器词汇表中的字符。这一点可能会在后续版本中得到解决，详情请参见 GitHub 上的议题。

贡献者及贡献方式

有关贡献者列表，请参阅 CONTRIBUTORS.md。

lm-format-enforcer 快速上手指南

lm-format-enforcer 是一个用于强制语言模型输出特定格式（如 JSON Schema、正则表达式等）的开源工具。它通过在生成过程的每一步过滤允许的 Token，确保输出严格符合指定格式，同时最大程度保留模型的生成自由度。

环境准备

• 系统要求：支持 Linux、macOS 和 Windows。若在 Google Colab 或本地使用 GPU 加速，建议配备 NVIDIA GPU 并安装对应的 CUDA 驱动。
• 前置依赖：
  • Python 3.8+
  • 主流深度学习框架（如 transformers, torch）
  • 目标语言模型（本示例以 Llama-2 为例）

国内加速建议： 在中国大陆地区，建议使用国内镜像源加速依赖下载：

• PyPI 镜像：https://pypi.tuna.tsinghua.edu.cn/simple
• Hugging Face 镜像：设置环境变量 HF_ENDPOINT=https://hf-mirror.com

安装步骤

使用 pip 安装核心库。如果使用量化模型（如 GPTQ），还需安装相关依赖。

# 设置国内 Hugging Face 镜像 (可选，推荐国内用户)
export HF_ENDPOINT=https://hf-mirror.com

# 安装核心库
pip install lm-format-enforcer -i https://pypi.tuna.tsinghua.edu.cn/simple

# 若需在 Colab 或本地运行完整示例 (包含 transformers, torch 等)
pip install transformers torch huggingface_hub optimum -i https://pypi.tuna.tsinghua.edu.cn/simple

# 若使用 GPTQ 量化模型 (如 Llama-2-GPTQ)，需额外安装 auto-gptq
pip install auto-gptq --extra-index-url https://huggingface.github.io/autogptq-index/whl/cu118/

基本使用

以下示例演示如何使用 lm-format-enforcer 强制 Llama-2 模型输出符合特定 Pydantic 模型的 JSON 数据。

代码示例

from pydantic import BaseModel
from lmformatenforcer import JsonSchemaParser
from lmformatenforcer.integrations.transformers import build_transformers_prefix_allowed_tokens_fn
from transformers import pipeline

# 1. 定义期望的输出格式 (Pydantic Model)
class AnswerFormat(BaseModel):
    first_name: str
    last_name: str
    year_of_birth: int
    num_seasons_in_nba: int

# 2. 创建 transformers 管道 (加载模型)
# 注意：首次运行会自动下载模型，国内用户请确保已设置 HF_ENDPOINT
hf_pipeline = pipeline('text-generation', model='TheBloke/Llama-2-7b-Chat-GPTQ', device_map='auto')

# 构造提示词，包含 JSON Schema 信息
prompt = f'Here is information about Michael Jordan in the following json schema: {AnswerFormat.schema_json()} :\n'

# 3. 创建解析器并构建 transformers 的前缀过滤函数
parser = JsonSchemaParser(AnswerFormat.schema())
prefix_function = build_transformers_prefix_allowed_tokens_fn(hf_pipeline.tokenizer, parser)

# 4. 调用管道生成内容 (传入 prefix_allowed_tokens_fn)
output_dict = hf_pipeline(prompt, prefix_allowed_tokens_fn=prefix_function)

# 5. 提取结果
result = output_dict[0]['generated_text'][len(prompt):]
print(result)
# 预期输出示例: {"first_name": "Michael", "last_name": "Jordan", "year_of_birth": 1963, "num_seasons_in_nba": 15}

关键点说明

• JsonSchemaParser：将 Pydantic 模型或 JSON Schema 转换为字符级解析器。
• build_transformers_prefix_allowed_tokens_fn：将解析器与模型的 Tokenizer 结合，生成一个过滤函数。
• prefix_allowed_tokens_fn：在 pipeline 或 model.generate 中传入此参数，即可在生成过程中实时拦截不符合格式的 Token。

该工具还支持正则表达式 (RegexParser)、无模式 JSON (JsonSchemaParser(None)) 以及 LangChain、LlamaIndex、vLLM 等多种框架的集成。