进阶 lmql.ai 2026-10-11 18:10:44 · 27 阅读
第10章 LMQL 教程：第 10 章 解码器
解码器（Decoders）
LMQL 支持多种解码算法，用于根据语言模型的 token 分布生成文本。你可以在查询的开头直接指定要使用的解码算法，例如通过 argmax 等解码器关键字。
所有受支持的解码算法均与模型无关，可配合 LMQL 支持的任何推理后端使用。关于支持的推理后端的更多信息，请参阅“模型”一章。
设置解码算法
视具体场景而定，LMQL 提供两种指定解码算法的方式：
在查询中配置解码器：第一种方式是直接在查询中指定解码算法及其参数。当解码器的选择与你正在编写的具体程序逻辑密切相关时，这种方式特别实用。 lmql# 在整个程序中使用宽度为 2 的 beam search beam(n=2) # 使用 beam search 生成 RESPONSE "This is a query with a specified decoder: [RESPONSE]" 解码算法的设定始终作用于整个查询程序，无法在程序内部进行更改。若希望在不同部分使用不同的解码器，需将程序拆分为多个查询。
在外部指定解码算法：第二种方式是在外部（即与实际程序代码分离）指定解码算法及其参数： ```python import lmql @lmql.query(model="openai/text-davinci-003", decoder="sample", temperature=1.8) def tell_a_joke(): '''lmql """A list good dad joke. A indicates the punchline: Q:[JOKE] A:[PUNCHLINE]""" where STOPS_AT(JOKE, "?") and STOPS_AT(PUNCHLINE, "\n") ''' tell_a_joke() # 使用 @lmql.query(...) 中指定的解码器 tell_a_joke(decoder="beam", n=2) # 使用 beam search 解码器，n=2 ``` 这种方式只能在 Python 环境中使用 LMQL 时实现。 解码算法 一般来说，LMQL 查询的第一个关键字就指定了要使用的解码算法。可用的解码器关键字如下： argmax argmax 是 LMQL 中最简单的解码器，它在解码过程的每一步都贪心地选择概率最高的 token。它没有额外的参数。由于 argmax 解码是确定性的，每次只能生成一条序列。 sample(n: int, temperature: float) sample 解码器从模型中并行采样 n 条序列。temperature 参数控制采样的随机程度：值越高，采样结果越随机；值越低，采样结果越接近高概率序列。temperature 为 0.0 时等价于 argmax 解码器。 beam(n: int) 一个简单的 beam search 解码器。n 参数控制束宽。beam search 解码器是确定性的，因此每次都会生成相同的 n 条序列。beam 查询的结果是按似然排序的 n 条序列的列表。 beam_sample(n: int, temperature: float) 一种在每一步从束中采样的 beam search 解码器。n 参数控制束宽，temperature 参数控制采样的随机程度。beam_sample 查询的结果是按似然排序的 n 条序列的列表。 新型解码器 LMQL 还实现了若干新型解码器。这些解码器尚处于实验阶段，可能无法按预期工作，也不保证在不同 LMQL 版本之间保持稳定。相关文档将在未来提供。 var(b: int, n: int) variable-level beam search 的实验性实现。 beam_var(n: int) 一种 beam search 的实验性实现，按当前解码的变量分组，并应用调整后的长度惩罚。 查看解码树 LMQL 还支持查看解码器生成的解码树。为此，请在 Playground IDE 中执行查询，并点击 Playground 右上角的 Advanced Mode 按钮。这会打开一个新面板，你可以在其中浏览和检查 LMQL 解码树： 第10章：解码器 解码树的可视化界面，展示于 LMQL Playground 中。该视图允许你追踪解码过程、活跃假设及解释器状态，包括 where 子句的当前求值结果。示例可查看 Playground 中的翻译案例（需启用高级模式）。 编写自定义解码器 LMQL 还内置了一个基于数组的解码库 dclib，可用于实现自定义解码器。相关信息将在后续提供。可用解码逻辑的实现代码位于 LMQL 仓库的 src/lmql/runtime/dclib/decoders.py。 附加解码参数 除了解码算法，LMQL 还支持多个附加解码参数，这些参数会影响采样行为和 token 评分： max_len: int 生成序列的最大长度。若未指定，max_len 的默认值为 2048。请注意，若达到最大长度且查询尚未根据提供的 where 子句得出有效结果，LMQL 运行时将抛出错误。 top_k: int 基于 Fan et. al (2018)，限制解码过程每一步中参与采样的 token 数量（仅适用于采样解码器）。 top_p: float 基于 Holtzman et. al (2019) 的 Top-p（核）采样方法（仅适用于采样解码器）。 repetition_penalty: float 重复惩罚系数，1.0 表示无惩罚，基于 Keskar et. al (2019)。生成的序列中已存在的 token 越多，其概率受到的惩罚越大。 frequency_penalty: float OpenAI API 文档中定义的 frequency_penalty。 presence_penalty: float OpenAI API 文档中定义的 presence_penalty。 提示 注意，不同推理后端的具体实现和可用附加解码参数可能存在差异。请参考相应推理接口的 API 文档，例如 HuggingFace 的 generate() 函数或 OpenAI API。 运行时参数 最后，还有一些额外的运行时参数可用，用于控制解码过程的辅助方面： chunksize: int chunksize 参数用于 OpenAI API 请求中的 max_tokens 或本地模型的推测解码。若未指定，chunksize 的默认值为 32。也可参见 Models 章节中对该参数的说明。 verbose: bool 启用详细控制台日志记录，针对单个 LLM 推理调用（本地生成调用或 OpenAI API 请求负载）。 cache: Union[bool,str] 设为 True 或 False 以启用内存 token 缓存。若未指定，cache 的默认值为 True，表示启用内存缓存。
将 cache 设置为一个字符串值，可指定一个本地文件用于基于磁盘的缓存，从而让缓存在多次查询执行和多个会话之间共享。openai_nonstop 实验性选项，启用 OpenAI 特有的不间断生成（non-stop generation），在某些场景下可以进一步提升缓存效果。chunk_timeout OpenAI 特有参数，等待下一批 token 到达的最长时间（秒）。如果超时，当前 API 请求会以合适的退避策略进行重试。
如果不设置，chunk_timeout 的默认值为 2.5。如果你在 LMQL 运行时的控制台输出中看到大量超时，可以调整这个参数。
在查询中配置解码器：第一种方式是直接在查询中指定解码算法及其参数。当解码器的选择与你正在编写的具体程序逻辑密切相关时，这种方式特别实用。 lmql# 在整个程序中使用宽度为 2 的 beam search beam(n=2) # 使用 beam search 生成 RESPONSE "This is a query with a specified decoder: [RESPONSE]" 解码算法的设定始终作用于整个查询程序，无法在程序内部进行更改。若希望在不同部分使用不同的解码器，需将程序拆分为多个查询。
在外部指定解码算法：第二种方式是在外部（即与实际程序代码分离）指定解码算法及其参数： ```python import lmql @lmql.query(model="openai/text-davinci-003", decoder="sample", temperature=1.8) def tell_a_joke(): '''lmql """A list good dad joke. A indicates the punchline: Q:[JOKE] A:[PUNCHLINE]""" where STOPS_AT(JOKE, "?") and STOPS_AT(PUNCHLINE, "\n") ''' tell_a_joke() # 使用 @lmql.query(...) 中指定的解码器 tell_a_joke(decoder="beam", n=2) # 使用 beam search 解码器，n=2 ``` 这种方式只能在 Python 环境中使用 LMQL 时实现。 解码算法 一般来说，LMQL 查询的第一个关键字就指定了要使用的解码算法。可用的解码器关键字如下： argmax argmax 是 LMQL 中最简单的解码器，它在解码过程的每一步都贪心地选择概率最高的 token。它没有额外的参数。由于 argmax 解码是确定性的，每次只能生成一条序列。 sample(n: int, temperature: float) sample 解码器从模型中并行采样 n 条序列。temperature 参数控制采样的随机程度：值越高，采样结果越随机；值越低，采样结果越接近高概率序列。temperature 为 0.0 时等价于 argmax 解码器。 beam(n: int) 一个简单的 beam search 解码器。n 参数控制束宽。beam search 解码器是确定性的，因此每次都会生成相同的 n 条序列。beam 查询的结果是按似然排序的 n 条序列的列表。 beam_sample(n: int, temperature: float) 一种在每一步从束中采样的 beam search 解码器。n 参数控制束宽，temperature 参数控制采样的随机程度。beam_sample 查询的结果是按似然排序的 n 条序列的列表。 新型解码器 LMQL 还实现了若干新型解码器。这些解码器尚处于实验阶段，可能无法按预期工作，也不保证在不同 LMQL 版本之间保持稳定。相关文档将在未来提供。 var(b: int, n: int) variable-level beam search 的实验性实现。 beam_var(n: int) 一种 beam search 的实验性实现，按当前解码的变量分组，并应用调整后的长度惩罚。 查看解码树 LMQL 还支持查看解码器生成的解码树。为此，请在 Playground IDE 中执行查询，并点击 Playground 右上角的 Advanced Mode 按钮。这会打开一个新面板，你可以在其中浏览和检查 LMQL 解码树： 第10章：解码器 解码树的可视化界面，展示于 LMQL Playground 中。该视图允许你追踪解码过程、活跃假设及解释器状态，包括 where 子句的当前求值结果。示例可查看 Playground 中的翻译案例（需启用高级模式）。 编写自定义解码器 LMQL 还内置了一个基于数组的解码库 dclib，可用于实现自定义解码器。相关信息将在后续提供。可用解码逻辑的实现代码位于 LMQL 仓库的 src/lmql/runtime/dclib/decoders.py。 附加解码参数 除了解码算法，LMQL 还支持多个附加解码参数，这些参数会影响采样行为和 token 评分： max_len: int 生成序列的最大长度。若未指定，max_len 的默认值为 2048。请注意，若达到最大长度且查询尚未根据提供的 where 子句得出有效结果，LMQL 运行时将抛出错误。 top_k: int 基于 Fan et. al (2018)，限制解码过程每一步中参与采样的 token 数量（仅适用于采样解码器）。 top_p: float 基于 Holtzman et. al (2019) 的 Top-p（核）采样方法（仅适用于采样解码器）。 repetition_penalty: float 重复惩罚系数，1.0 表示无惩罚，基于 Keskar et. al (2019)。生成的序列中已存在的 token 越多，其概率受到的惩罚越大。 frequency_penalty: float OpenAI API 文档中定义的 frequency_penalty。 presence_penalty: float OpenAI API 文档中定义的 presence_penalty。 提示 注意，不同推理后端的具体实现和可用附加解码参数可能存在差异。请参考相应推理接口的 API 文档，例如 HuggingFace 的 generate() 函数或 OpenAI API。 运行时参数 最后，还有一些额外的运行时参数可用，用于控制解码过程的辅助方面： chunksize: int chunksize 参数用于 OpenAI API 请求中的 max_tokens 或本地模型的推测解码。若未指定，chunksize 的默认值为 32。也可参见 Models 章节中对该参数的说明。 verbose: bool 启用详细控制台日志记录，针对单个 LLM 推理调用（本地生成调用或 OpenAI API 请求负载）。 cache: Union[bool,str] 设为 True 或 False 以启用内存 token 缓存。若未指定，cache 的默认值为 True，表示启用内存缓存。
将 cache 设置为一个字符串值，可指定一个本地文件用于基于磁盘的缓存，从而让缓存在多次查询执行和多个会话之间共享。openai_nonstop 实验性选项，启用 OpenAI 特有的不间断生成（non-stop generation），在某些场景下可以进一步提升缓存效果。chunk_timeout OpenAI 特有参数，等待下一批 token 到达的最长时间（秒）。如果超时，当前 API 请求会以合适的退避策略进行重试。
如果不设置，chunk_timeout 的默认值为 2.5。如果你在 LMQL 运行时的控制台输出中看到大量超时，可以调整这个参数。
