lift是一款开源文档抽取（Document Extraction）工具：它是一个 9B 参数的视觉模型，只要你传入一份 JSON Schema，就能把 PDF 或图片中的内容提取为与 Schema 对齐的结构化 JSON，并借助 schema 约束解码保证输出合法。对于要部署 lift 的新手来说，最常被问到的问题就是：local.env文件该放在哪？里面的环境变量到底控制什么？哪些参数值得调？

本文基于官方仓库的配置系统 lift/settings.py 逐参数讲解，帮你在 10 分钟内完成 lift 环境变量配置，并完成关键性能调优。

一、先搞懂 lift 的两种推理模式

lift 内置两种推理后端，你调哪些参数、怎么调，取决于你选哪一种：

• vLLM 请求与重试逻辑：lift/model/vllm.py
• HF 模型加载逻辑：lift/model/hf.py

两种模式下，模型字段级准确率均保持高水平，且 lift 单文档处理延迟明显低于同类方案：

二、local.env 快速上手：3 分钟完成配置

lift 使用pydantic-settings+python-dotenv读取配置。你只需在当前工作目录下创建一个名为local.env的文件，所有设置即可生效（查找逻辑见 lift/settings.py 中的find_dotenv("local.env")）。

一个最小可用的local.env模板（完整示例见 README.md 的 Configuration 一节）：

# 模型设置 MODEL_CHECKPOINT=datalab-to/lift MAX_OUTPUT_TOKENS=12384 # vLLM 设置 VLLM_API_BASE=http://localhost:8000/v1 VLLM_MODEL_NAME=lift

💡 小技巧：local.env中多写的无关变量会被自动忽略（extra = "ignore"），可以放心混放。

三、8 大关键调优参数详解

以下 8 个参数覆盖了 lift 日常部署中 90% 以上的调优需求。每个参数都给出：默认值 → 作用 → 何时修改 → 建议值。

1️⃣ MODEL_CHECKPOINT —— 模型检查点

• 默认值：datalab-to/lift
• 作用：HF 模式下加载哪个模型权重（见 lift/model/hf.py），vLLM 模式下lift_vllm启动 Docker 容器时传入的--model参数（见 lift/scripts/vllm_launcher.py）。
• 何时改：需要加载自托管/微调的模型副本时。

2️⃣ MAX_OUTPUT_TOKENS —— 最大输出 token 数

• 默认值：12384
• 作用：限制模型单次生成上限，两种后端共用（HF：max_new_tokens；vLLM：max_tokens）。字段很多的 Schema（如长明细清单）若输出被截断，就是它太小了。
• 建议：默认值已足够绝大多数场景；超大表格类文档可保持默认或略调高。

3️⃣ TORCH_DEVICE —— 指定 HF 后端设备

• 默认值：None（即device_map="auto"自动分配）
• 作用：把 HF 后端固定到指定设备，例如TORCH_DEVICE=cuda:0（实现见 lift/model/hf.py）。
• 何时改：多 GPU 机器上想避开被占用的显卡，或明确指定推理卡时。

4️⃣ TORCH_ATTN —— 注意力实现方式

• 默认值：None（transformers 默认实现）
• 作用：设置attn_implementation，HF 模式下强烈建议设为 flash attention 以获得更好性能。
• 建议：已安装 flash-attention 时设为flash_attention_2（README 的官方推荐）。

5️⃣ IMAGE_DPI —— PDF 渲染 DPI

• 默认值：96
• 作用：PDF 转图片时的渲染分辨率下限。渲染逻辑在 lift/input.py：实际 DPI 会按页面尺寸自动放大，但不会低于IMAGE_DPI。
• 何时改：扫描件模糊、小字提取不准时可适当调高（如 120–150）；追求速度则调低。

6️⃣ VLLM_API_BASE —— vLLM 服务器地址

• 默认值：http://localhost:8000/v1
• 作用：OpenAI 兼容 API 的 Base URL，lift_extract、Python SDK 都靠它定位服务器。
• 何时改：vLLM 跑在远程机器或改了端口时，指向http://<host>:<port>/v1即可。

7️⃣ VLLM_GPUS —— 指定 GPU 设备号

• 默认值：0
• 作用：lift_vllm启动 Docker 容器时的--gpus device=N参数（见 lift/scripts/vllm_launcher.py）。
• 何时改：机器有多张卡、想让推理服务占用指定显卡时。

8️⃣ MAX_VLLM_RETRIES —— 失败自动重试次数

• 默认值：6
• 作用：vLLM 检测到"重复 token 死循环"或请求报错时自动重试（含递增等待），逻辑见 lift/model/vllm.py。重试时会自动抬高 temperature 以跳出重复模式。
• 建议：高负载环境可适当调大；追求快速失败则调小。

四、其他实用配置速查表

以下参数在 lift/settings.py 中同样可配，使用频率稍低：

五、两套可直接抄的实战配置

场景 A：本地 HuggingFace 模式（单机体验）

MODEL_CHECKPOINT=datalab-to/lift TORCH_DEVICE=cuda:0 TORCH_ATTN=flash_attention_2 MAX_OUTPUT_TOKENS=12384

然后执行：lift_extract input.pdf ./output --schema schema.json --method hf

场景 B：vLLM 远程模式（批量/生产，推荐）

VLLM_API_BASE=http://10.0.0.5:8000/v1 VLLM_MODEL_NAME=lift MAX_VLLM_RETRIES=8

服务器上先按 GPU 型号启动：lift_vllm --gpu a100-80。启动器会按显存自动缩放批处理参数（H100 80GB 为基准），支持h100、a100-80、a100、l40s、a10、l4、4090、3090、t4（见 lift/scripts/vllm_launcher.py）。

六、常见问题（FAQ）

Q1：改完 local.env 需要重启进程吗？需要。配置在进程启动时读取一次，修改后请重启lift_extract会话或 Python 进程。

Q2：输出 JSON 总是被截断怎么办？优先检查MAX_OUTPUT_TOKENS是否偏小，其次确认 Schema 是否过于冗长——字段越多，生成的 JSON 越长。

Q3：--max-output-tokens命令行参数和MAX_OUTPUT_TOKENS什么关系？命令行参数（见 lift/scripts/extract_cli.py）只在单次调用中生效，未传时回退到local.env的配置，相当于"临时覆盖"。

Q4：远程 vLLM 连不上，如何排查？依次确认：VLLM_API_BASE的 host/port 是否正确、服务器上VLLM_MODEL_NAME与容器--served-model-name是否一致、VLLM_API_KEY是否与服务端匹配。

📌 完整项目信息、基准数据与安装方式详见 README.md；CLI 选项一览见 lift/scripts/extract_cli.py。

掌握local.env与这 8 大参数后，你即可在单机体验与生产集群之间自由切换，把 lift 的文档抽取能力稳定地跑起来。