lm-format-enforcer

LMFE标志

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

解决方案概览

语言模型能够生成文本，但在需要精确的输出格式时，它们并不总是按照指示执行。各种提示工程技术被引入以提高生成文本的稳健性，但它们并不总是足够的。这个项目通过在每个时间步过滤语言模型允许生成的标记来解决这些问题，从而确保输出格式得到遵守，同时最小化对语言模型的限制。

安装

pip install lm-format-enforcer

基础教程

# 如果在Google Colab上使用T4 GPU运行，需要安装以下依赖
!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 pipeline
hf_pipeline = pipeline('text-generation', model='TheBloke/Llama-2-7b-Chat-GPTQ', device_map='auto')
prompt = f'以下是Michael Jordan的信息，符合以下JSON模式: {AnswerFormat.schema_json()} :\n'

# 创建一个字符级解析器并从中构建transformers前缀函数
parser = JsonSchemaParser(AnswerFormat.schema())
prefix_function = build_transformers_prefix_allowed_tokens_fn(hf_pipeline.tokenizer, parser)

# 使用前缀函数调用pipeline
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模式（无模式）和正则表达式格式
支持JSON模式中的必需和可选字段
支持JSON模式中的嵌套字段、数组和字典
允许语言模型控制JSON模式中的空白和字段顺序，减少幻觉
不修改transformers API的高级循环，因此可以在任何场景中使用

与其他库的比较

功能	LM Format Enforcer	Guidance	Jsonformer	Outlines
正则表达式	✅	✅	❌	✅
JSON Schema	✅	🟡 (可进行部分转换)	✅	✅
批处理生成	✅	❌	❌	✅
束搜索	✅	❌	❌	✅
集成到现有管道	✅	❌	❌	✅
可选JSON字段	✅	❌	❌	❌
LLM控制JSON字段排序和空白	✅	❌	❌	❌
带递归类的JSON Schema	✅	❌	✅	❌

发现错误？库更新了新功能？提出问题！

详细示例

我们创建了一个Google Colab笔记本，其中包含了如何使用这个库来强制执行llama2的输出格式的完整示例，包括解释中间结果。这个笔记本可以在Colab的免费GPU支持运行时上运行。

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

关于与huggingface transformers集成的不同方式，请查看单元测试。

vLLM服务器集成

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

通过以下方式在vLLM OpenAI服务器中使用LM Format Enforcer，可以添加vLLM命令行参数：

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库），因此它不能覆盖100%的正则表达式标准。

分词器前缀树

给定某个语言模型使用的分词器，我们可以构建该语言模型可以生成的所有标记的前缀树。这是通过生成所有可能的标记序列并将它们添加到树中来完成的。参见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 - 在token 1中存在很大差距。之后，几乎所有的leading scores都在允许的token集合内，这意味着模型可能不会因为token强制而产生幻觉。唯一的例外是时间步骤4 - " Born"被强制使用，而LLM想要选择"born"。这为提示工程师提供了一个提示，建议将提示中的B改为小写。

配置选项

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

选项1：通过环境变量

有几个可以设置的环境变量，会影响库的运行。当你不想修改代码时，这种方法很有用，例如通过vLLM OpenAI服务器使用库时。

LMFE_MAX_CONSECUTIVE_WHITESPACES - 解析JsonSchemaObjects时允许的最大连续空白字符数。默认值：12。
LMFE_STRICT_JSON_FIELD_ORDER - JsonSchemaParser是否应该强制属性按照JsonSchema的'required'列表中出现的顺序排列？（注：这与Pydantic模型中的声明顺序一致）。默认值：False。
LMFE_MAX_JSON_ARRAY_LENGTH - 如果未在架构中指定，JSON数组的最大长度是多少。帮助LLM避免无限循环。默认值：20。

选项2：通过CharacterLevelParserConfig类

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

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

已知问题和限制

LM Format Enforcer需要一个Python API来处理语言模型的输出logits。这意味着在API扩展之前，它无法与OpenAI ChatGPT和类似的基于API的解决方案一起使用。
不完全支持正则表达式语法。更多详情请参见interegular。
LM Format Enforcer正则表达式解析器只能生成存在于分词器词汇表中的字符。这可能会在以后的版本中解决，请参见GitHub上的问题。