第27章 LMQL推理证书：追踪与复现LLM推理结果
第27章 推理证书（Inference Certificates）
推理证书：追踪并复现 LLM 推理结果。
推理证书是一种简单的数据结构，记录了复现某次推理结果所需的关键信息。只要是在 LMQL 上下文中发起的 LLM 调用，都可以生成对应的证书。
证书的主要用途是记录完整的（分词后的）prompt、环境信息和生成参数，从而为 LLM 推理结果提供一种可记录、可追踪、可复现的手段。
获取证书
要获取证书，只需在当前的生成上下文（例如查询函数或 lmql.generate 调用）中传入 certificate=True 参数。
这样会生成一份证书，涵盖该上下文执行期间发起的所有 LLM 调用。设置 certificate=True 时，结果数据结构只会打印到控制台；如果想把证书保存到文件，可以将 certificate 参数指定为一个路径。
下面这个例子会生成证书并保存到当前工作目录下的 my-certificate.json 文件：
python # 定义一个简单的查询函数 say_hello = lmql.F("Greet the world:[GREETING]")
# 调用并保存证书 say_hello(certificate="my-certificate.json")
证书文件
（已截断）
{
"name": "say_hello",
"type": "lmql.InferenceCertificate",
"lmql.version": "0.999999 (dev) (build on dev, commit dev)",
"time": "2023-10-02 23:37:55 +0200",
"events": [
{
"name": "openai.Completion",
"data": {
"endpoint": "https://api.openai.com/v1/completions",
"headers": {
"Authorization": "
Prompt 与生成参数：证书包含执行期间所有 LLM 推理调用的参数。对于基于 API 的 LLM，包括请求头、请求参数以及响应内容；对于本地模型，则包括分词后的 prompt 以及实例化模型时使用的具体参数和配置。
指标（Metrics）：证书还包含推理调用的基本指标。对于基于 API 的 LLM，包括请求次数、批量大小和 token 用量。
环境信息：证书还会记录环境信息，例如 LMQL 版本以及所用后端库的版本。
脱敏处理
默认情况下，OpenAI 密钥等敏感参数会从证书中移除。但请注意，证书中仍可能包含敏感信息，比如用于生成的 prompt 或环境信息。如果需要从证书中移除更多字段，可以使用 lmql.runtime.tracing.add_extra_redact_keys 函数。
为同一上下文中的多次调用生成证书
如果要为某个上下文中的多次生成生成一份证书，可以使用 lmql.traced 上下文管理器：
python with lmql.traced("my-context") as t: # 调用一次查询 res1 = say_hello(verbose=True)
# 调用 lmql.generate res2 = lmql.generate_sync("Greet the animals of the world:", max_tokens=10, verbose=True)
# 为该上下文中的所有调用生成一份合并证书 print(lmql.certificate(t))
这样会为该上下文中的所有调用生成一份证书，每个查询对应子证书列表中的一项，记录的事件会嵌套在子证书中。此外，顶层证书还会包含一个汇总所有（递归）调用后的指标对象。
证书回调与返回值
除了直接写入文件，证书也可以通过回调函数处理，或作为函数返回值返回。
要指定一个以生成的证书为参数的回调函数，将其作为 certificate=
回调函数会收到一个类型为 lmql.InferenceCertificate 的证书对象。该证书可通过字符串转换直接序列化为 JSON，即 str(certificate)。
