syncode

SynCode: 基于语法增强的LLM生成

ℹ️ 关于

SynCode是一个新型框架，用于大型语言模型(LLMs)的语法引导生成，可扩展到通用编程语言，并具有可靠性和完整性保证。
使用SynCode，您可以确保您的语言模型生成的输出在语法上符合上下文无关文法(CFG)定义的规则。
例如，SynCode使用Gemma-2b在JSON生成方面达到了99%的准确率（查看这里），比标准的无约束生成快10-20%。

内置语法

Python SQL JSON

查看语法目录了解支持的语法

使用简单的EBNF语法定义您自己的语法。查看我们的notebooks目录获取示例，以及中的快速示例

📚 特性


🔥 快速的语法引导生成（Python和Go的生成开销仅为10%！）
🤖 无缝使用任何HuggingFace语言模型，包括代码、聊天和指令模型
🖍️ 以EBNF格式输入任何CFG（甚至是Python和Go等编程语言的大型语法！）
📝 内置Python、Go、SQL、数学、JSON等语言的CFG！
🎲 支持任何现有的解码策略（如贪婪搜索、束搜索、核采样）

📖 更多关于SynCode

SynCode如何工作？

在SynCode工作流程中，LLM接收部分代码_C_k并生成下一个标记_t_k+1的分布。增量解析器处理_C_k以生成接受序列_A，即可以跟随部分代码的终结符序列。同时，增量解析器从部分代码计算出余数_r，表示在后续生成中可能改变其终结符类型的后缀。SynCode的核心是离线构建DFA掩码存储，这是一个从表示语言语法终结符的正则表达式派生的查找表。DFA掩码存储便于高效遍历DFA状态，从而检索映射到每个状态和接受序列的掩码。SynCode使用余数遍历DFA，并使用掩码存储来计算特定于每个接受序列的掩码。通过统一每个接受序列的掩码，SynCode获得语法上有效的标记集。LLM使用分布和掩码迭代生成标记_t_k+1，将其附加到_C_k以创建更新后的代码_C_k+1。这个过程持续进行，直到LLM根据定义的停止条件返回最终代码_C_n_。

🚀 快速开始

Python 安装和使用说明

只需通过 PyPi 使用以下命令安装 SynCode：

pip install git+https://github.com/uiuc-focal-lab/syncode.git

使用方法一：

SynCode 可以作为一个简单的 logit 处理器与 HuggingFace transformers 库接口一起使用。查看这个示例笔记本。

只需导入并使用适当的语法初始化它：

from syncode import SyncodeLogitsProcessor

然后可以将其作为参数传递给 generate 函数。例如：

output = model.generate(
          inputs,
          max_length=100, 
          pad_token_id=tokenizer.eos_token_id, 
          logits_processor=[syncode_logits_processor]
        )

使用方法二：

另一种选择是使用 SynCode 对象进行推理（这带有额外的优化）：

from syncode import Syncode

参考 SynCode 参数获取初始化 SynCode 类的完整参数列表。在 Python 中，使用 SynCode 类的 infer() 方法进行推理。infer() 有以下参数：

prompt（str，可选）：语言模型的提示。默认为 None。
task_id（int，可选）：从数据集中选择问题的任务 ID。默认为 None。

如果 prompt 和 task_id 都未指定，infer() 将通过 stdin 读取用户输入。

以下示例展示了 SynCode 的优势：

在下面的示例中，未受约束的原始 Phi-2 模型未能生成有效的 JSON 对象，而是生成了 Python 代码。

from syncode import Syncode

# 加载未受约束的原始模型
llm = Syncode(model="microsoft/phi-2", mode='original', max_new_tokens=50)

prompt = "请返回一个 JSON 对象来表示印度国家，包含名称、首都和人口？"
output = llm.infer(prompt)[0]
print(f"LLM 输出:\n{output}\n")

# LLM 输出:
#
# A:
#
# You can use the following code:
# import json
#
# def get_country_info(country_name):
#    country_info = {
#        'name': country_name,
#        'capital':

当使用 JSON 语法引导 SynCode 时，模型可以生成语法正确的 JSON 对象。

from syncode import Syncode

# 加载 Syncode 增强模型
syn_llm = Syncode(model = "microsoft/phi-2", grammar='json', parse_output_only=True, max_new_tokens=50)

prompt = "请返回一个 JSON 对象来表示印度国家，包含名称、首都和人口？"
output = syn_llm.infer(prompt)[0]
print(f"SynCode 输出:\n{output}")

# SynCode 输出:
# {
#     "name": "India",
#     "capital": "New Delhi",
#     "population": "1,366,417,754"
# }

查看更多使用 Python、Go 和其他语法的示例，请参考笔记本和此快速示例：

环境变量

您可以选择通过导出以下环境变量来设置缓存目录。将以下行添加到您的 .bashrc 或 .zshrc 文件中：

export HF_CACHE="path_to_hf_cache"
export SYNCODE_CACHE="path_to_syncode_cache"

如果未设置这些环境变量，工具将使用默认缓存目录。要使用 HuggingFace 上的受限模型（如 Llama 模型），您可以设置环境变量 HF_ACCESS_TOKEN：

export HF_ACCESS_TOKEN="your_huggingface_api_key"

SynCode 参数

点击展开 SynCode 参数列表

mode（str，可选）：推理模式。grammar_mask 和 grammar_strict 是启用我们工具的模式。original 是原始 LLM 的模式。默认为 "grammar_strict"。"original" 模式用于没有任何语法约束的原始 LLM，"grammar_strict" 模式是用于语法约束生成的更严格模式。
model（str）：Hugging Face 模型库的模型 ID 或本地存储的模型名称。
quantize（bool，可选）：将模型量化为 bfloat16。默认为 True。
device（str，可选）：运行模型的设备。默认为 cuda。
grammar（str，可选）：EBNF 形式的语法（字符串或文件路径）或用于约束生成的语言。默认为 None。您可以使用 python、go、sql、json、java、calc 之一，或传入 EBNF 格式的自定义语法（查看笔记本获取示例）。
num_samples（int，可选）：样本数量。默认为 1。
dataset（str，可选）：数据集。默认为 "input"。"input" 表示用户可以通过 CLI 提供输入或作为字符串传入提示。
num_few_shot（int，可选）：少样本提示的示例数量。默认为 0。
chat_mode（bool，可选）：如果使用聊天/指令 LLM，则为 True。否则为 False。默认为 False。
dev_mode（bool，可选）：开发模式，在该模式下我们不会静默处理解析器错误。默认为 False。
log_level（int，可选）：0 表示无日志，1 表示最少日志，2 表示包括时间在内的所有日志。默认为 2。
new_mask_store（布尔值，可选）：强制使用新的掩码存储，否则如果可用则使用缓存的掩码存储。默认为False。
parser（字符串，可选）：在LR(1)和LALR(1)解析之间选择。默认为'lalr'。
task_id（整数，可选）：用于从数据集中选择问题的问题任务ID。
kwargs（void，可选）：当前支持的kwargs包括max_length、max_new_tokens、min_length、min_new_tokens、early_stopping、do_sample、num_beams、use_cache、temperature、top_k、top_p、num_return_sequences、pad_token_id和eos_token_id。更多信息请参阅HuggingFace文本生成文档。

通过CLI运行

通过CLI运行SynCode

克隆此仓库：

git clone https://github.com/uiuc-focal-lab/syncode.git

要通过CLI运行该工具，请使用以下命令：

python3 syncode/infer.py
    --mode [original, grammar_mask, grammar_strict]
    --model [模型名称]
    --quantize [True, False]
    --device ["cpu", "cuda", "cuda:1"等]
    --num_samples [样本数]
    --dataset [mbxp, humaneval, mathqa-x, input]
    --few_shot [True, False]
    --num_fs_examples [少样本示例数]
    --chat_mode [True, False]
    --dev_mode [True, False]
    --log_level [0, 1, 2]
    --new_mask_store [True, False]
    --parser ["lr", "lalr"]
    --task_id [任务ID]

👀 使用示例

查看我们的notebooks目录，其中包含各种交互式示例，展示了SynCode的不同用例！一些常见编程语言的语法定义在grammars目录中。我们还允许用户使用从Lark改编的简单EBNF语法定义语法。用户可以传入一串规则或.lark文件的路径。

🐍 生成无缩进错误的Python代码

大型语言模型往往难以生成具有正确缩进的Python代码。考虑以下示例。未受约束的original WizardCoder模型无法生成具有正确空格数的代码补全。执行此代码时，我们会得到缩进错误。

from syncode import Syncode

model_name = "WizardLM/WizardCoder-1B-V1.0"

# 加载未受约束的原始模型
llm = Syncode(model = model_name, mode='original', max_new_tokens=200)
partial_code = "def is_prime(n):\n    '''Return if prime'''\n  "

#生成输入部分代码的补全
unconstrained_output = partial_code+llm.infer(partial_code)[0]

print(unconstrained_output)
# def is_prime(n):
#     '''Return if prime'''
#    if n < 2:
#        return False
#    for i in range(2, int(n**0.5)+1):
#        if n % i == 0:
#            return False
#    return True
exec(unconstrained_output)
# IndentationError: unindent does not match any outer indentation level

SynCode可以解决这个问题！我们只需将模式切换为grammar_mask/grammar_strict来加载SynCode增强模型。通过SynCode的约束解码，LLM能够生成正确的Python程序。

from syncode import Syncode

model_name = "WizardLM/WizardCoder-1B-V1.0"

# 加载SynCode增强模型
syn_llm = Syncode(model=model_name, mode='grammar_strict', grammar='python')
partial_code = "def is_prime(n):\n    '''Return if prime'''\n  "

#生成输入部分代码的补全
constrained_output = partial_code+ syn_llm.infer(partial_code)[0]
print(constrained_output)
# def is_prime(n):
#     '''Return if prime'''
#     if n < 2:
#         return False
#     for i in range(2, int(n**0.5) + 1):
#         if n % i == 0:
#             return False
#     return True
exec(constrained_output)
# 正确代码 :)

🔤 JSON模式生成

在下面的示例中，未受约束的原始Phi-2模型无法生成有效的JSON对象，而是生成Python代码。

from syncode import Syncode

# 加载未受约束的原始模型
llm = Syncode(model = "microsoft/phi-2", mode='original', max_new_tokens=50)

prompt = "请返回一个表示印度国家的json对象，包含名称、首都和人口？"
output = llm.infer(prompt)[0]
print(f"LLM输出:\n{output}\n")

# LLM输出:
#
# A:
#
# 您可以使用以下代码：
# import json
#
# def get_country_info(country_name):
#    country_info = {
#        'name': country_name,
#        'capital':

当使用SynCode的JSON语法引导时，模型能够生成语法正确的JSON对象。

from syncode import Syncode

# 加载SynCode增强模型
syn_llm = Syncode(model="microsoft/phi-2", grammar='json', parse_output_only=True, max_new_tokens=50)

prompt = "请返回一个表示印度国家的json对象，包含名称、首都和人口？"
output = syn_llm.infer(prompt)[0]
print(f"SynCode输出:\n{output}")
# SynCode 输出:
# {
#     "name": "印度",
#     "capital": "新德里",
#     "population": "1,366,417,754"
# }

👤 自定义语法输入

Syncode 允许用户使用从 Lark 改编的简单 EBNF 语法定义语法。也可以简单地直接将语法规则作为规则字符串输入，如下所示。

请参考 notebooks 目录中使用自定义语法的示例和说明，了解如何定义自己的自定义语法。

在我们的示例中，我们希望模型仅以 月份日期 格式响应。没有约束解码，语言模型可能无法生成遵循此语法的输出。考虑以下代码片段。

from syncode import Syncode

model_name = "microsoft/phi-2"

# 加载未约束的原始模型
llm = Syncode(model=model_name, mode='original', max_new_tokens=20)

inp = "圣诞节是哪一天？"

output = llm.infer(inp)
print(f"LLM 输出:\n{repr(output)}\n")
# LLM 输出:
# '圣诞节是 12 月 25 日。\n<|im_end|>\n<|im'

如上所示，LLM 生成了正确的响应，但不是我们想要的格式。我们可以传入一个语法，并利用 SynCode 引导 LLM 生成符合这个语法的能力。如下面的代码片段所示，SynCode 增强的 LLM 以正确的 月份日期 格式生成输出。

from syncode import Syncode

# 以 EBNF 格式的规则字符串传入语法
grammar = """ start: month day 
              
              day: /[1-9]/ | /[1-2][0-9]/ | /3[0-1]/
              
              month: "一月" | "二月" | "三月" | "四月" | "五月" | "六月" | "七月" | "八月" | "九月" | "十月" | "十一月" | "十二月"
"""

model_name = "microsoft/phi-2"

# 加载 Syncode 增强的模型
syn_llm = Syncode(model=model_name, grammar=grammar, parse_output_only=True)

inp = "圣诞节是哪一天？"

output = syn_llm.infer(inp)
print(f"Syncode 增强的 LLM 输出:\n{output}")
# Syncode 增强的 LLM 输出:
# 十二月 25

SynCode 与其他约束解码器相比如何？

工具	正则表达式	CFG*	预计算*	GPL*
`LMQL`	✅	❌	❌	❌
`GUIDANCE`	✅	✅	❌	❌
`OUTLINES`	✅	✅	✅	❌
`PICARD`	✅	✅	❌	❌
`SYNCHROMESH`	✅	✅	❌	❌
`LLAMA.CPP`	✅	✅	❌	❌
`GCD`	✅	✅	❌	❌
SynCode	✅	✅	✅	✅

CFG*: 使用上下文无关文法（CFG）引导生成

预计算*: 预先计算词汇表上的掩码以显著提高生成速度

GPL*: 支持通用编程语言，包括非上下文无关的片段，如 Python 中的缩进和 Golang 中的作用域结束标记。

📜 引用

@misc{ugare2024syncode,
      title={SynCode: LLM Generation with Grammar Augmentation}, 
      author={Shubham Ugare and Tarun Suresh and Hangoo Kang and Sasa Misailovic and Gagandeep Singh},
      year={2024},
      eprint={2403.01632},
      archivePrefix={arXiv},
      primaryClass={cs.LG}
}

联系方式

如有问题，请联系 Shubham Ugare。