第26章 LMQL Generations API：基于 Python 的轻量级文本生成与打分库

第26章 Generations API NEW

一个基于 Python 的简单 API，用于 LMQL 文本生成与打分。Generations API 是一个轻量级库，旨在为用户提供 LMQL 高级功能，如推理后端、受约束的生成和打分。该 API 设计易用，无需用户自行编写 LMQL 代码。

概述 以使用 openai/gpt-3.5-turbo-instruct 模型生成和打分为例，演示 Generations API：

import lmql

# 获取模型实例 m: lmql.LLM = lmql.model("openai/gpt-3.5-turbo-instruct")

# 简单生成 m.generate_sync("Hello", max_tokens=10) # -> Hello, I am a 23 year old female.

# 序列打分 m.score_sync("Hello", ["World", "Apples", "Oranges"]) # lmql.ScoringResult(model='openai/gpt-3.5-turbo-instruct') # -World: -3.9417848587036133 # -Apples: -15.26676321029663 # -Oranges: -16.22640037536621

上述片段展示了 Generations API 的不同组件：

lmql.LLM Generations API 的核心是 lmql.LLM 对象。通过 lmql.model(...) 构造函数，你可以访问广泛不同的模型，如 Models 章节所述。这包括对运行在同一进程、单独 worker 进程或通过 API endpoint 可用的云端模型的支持。

lmql.LLM.generate(...) 一个简单的函数，用于基于给定提示词生成文本补全。这有助于快速获得单步补全，或为提示词生成补全列表。

lmql.LLM.score(...) 允许直接访问模型为输入提示词及其延续部分的分词表示所分配的分值。这对于分类或排名等任务非常有用。

结果是一个 lmql.ScoringResult 对象，包含每个延续部分的分值，以及用于打分的提示词和延续部分。它为分值聚合、归一化和最大值选择提供了便捷接口。

兼容性 对于更高级的使用场景，Generation API 与标准 LMQL 无缝融合，允许用户根据用例需求逐步采用完整的语言运行时。

实现 内部而言，Generations API 是围绕 LMQL 的薄包装层，因此可以受益于 LMQL 的所有功能，如缓存、并行化等。该 API 完全异步，应使用 asyncio 调用。或者，所有 API 功能也可通过函数的 *_sync 变体同步使用。

lmql.LLM 对象 核心而言，lmql.LLM 对象代表特定的语言模型，并提供生成和打分方法。lmql.LLM 使用 lmql.model(...) 实例化，可以直接传递给 LMQL 查询程序或顶层 lmql.generate 和 lmql.score 函数。

LLM.generate(...) python async def generate( self, prompt: str, max_tokens: Optional[int] = None, decoder: str, kwargs ) -> Union[str, List[str]] 基于给定提示词生成文本补全。返回完整的提示词加补全作为一个字符串。

参数 prompt: str：用于生成补全的提示词。 max_tokens: Optional[int]：生成的最大 token 数。如果为 None，则生成文本直到模型返回序列结束 token。 decoder: str：用于生成的解码算法。默认为 "argmax"。 kwargs：传递给底层 LMQL 查询程序的其他关键字参数。这些可用于指定如 chunksize、解码器参数 n 或任何模型/解码器特定参数。

返回值 函数返回字符串或字符串列表，具体取决于使用的解码器（decoder=argmax 产生单个序列，decoder="sample", n=2 产生两个序列等）。

异步 该函数是异步的，应与 asyncio 和 await 一起使用。并行运行时，多次生成调用会被批处理并在相同模型的多个调用间并行化。对于同步使用，可以依赖 LLM.generate_sync，但请注意，此时函数将阻塞当前线程直到生成完成。

LLM.generate_sync(...) python def generate_sync(self, *args, kwargs): lmql.LLM.generate 的同步版本。

LLM.score_sync(...) python def score_sync(self, *args, kwargs) lmql.LLM.score 的同步版本。

顶层函数 Generation API 也可直接在 lmql 模块的顶层命名空间中访问。这允许直接进行生成和打分，无需先实例化 lmql.LLM 对象。

lmql.generate(...) python async def lmql.generate( prompt: str, max_tokens: Optional[int] = None, model: Optional[Union[LLM, str]] = None, kwargs ) -> Union[str, List[str]] lmql.generate 基于给定提示词生成文本补全，行为与 LLM.generate 类似，使用提供的模型实例或模型名称。

lmql.score(...) python async def score( prompt: str, values: Union[str, List[str]], model: Optional[Union[str, LLM]] = None, kwargs ) -> lmql.ScoringResult lmql.score 为给定提示词的不同延续值打分，行为与 LLM.score 类似，使用提供的模型实例或模型名称。

如果未提供模型，则使用默认模型。更多请见 lmql.set_default_model。

lmql.score_sync(...) lmql.score 的同步版本。

lmql.set_default_model(...) python def set_default_model(model: Union[str, LLM]) 设置当 LMQL 中未指定 from 子句或 @lmql.query(model=) 时要使用的模型。默认模型在当前进程中全局生效，影响 LMQL 查询以及 Generations API 方法，如 lmql.generate 和 lmql.score 函数。

你还可以通过指定环境变量 LMQL_DEFAULT_MODEL 来设置默认模型。