LLM Preflight

LLM Preflight

最近审查： 2026-10-19 · 截至： v2.22.2

在更改模型、提示词、架构或服务商之前，先检查大模型响应是否符合应用依赖的输出规则。

定义功能所需的 JSON 结构、路由标签或精确输出。 根据这些规则检查响应，预览服务商请求和预估费用， 并为变更审查留存证据。

专为维护大模型功能的工程师打造。可在本地作为 CLI、GitHub Action 或 MCP 服务运行。支持 Python 3.10+；无第三方运行时依赖。

立即试用 · 已观察的模型 · 使用自己的契约 · CI 和 Agent

观看无效响应被发现并修正（23 秒）。

billing 通过 → 将响应改为 sales → 检查失败 → 恢复为 billing → 检查通过。允许的标签保持不变。

真实 CLI 输出，使用合成响应样例。这会检查验证器； 不会请求服务商，也不会执行应用的解析器。 观看 MP4。

60 秒上手

在新目录中安装工具并运行本地模拟，无需 API 密钥或 请求服务商：

python3 -m venv .venv
. .venv/bin/activate
python3 -m pip install llm-preflight
llm-preflight init
llm-preflight benchmark.json --no-save --no-env-file

上面的激活命令适用于 POSIX shell；PowerShell 使用 .\.venv\Scripts\Activate.ps1。

init 不会覆盖已有配置。在质量门中查找带有 PASS 的 local-mock：模拟器返回了 ok，并通过精确输出 测试。由于本地模拟器不提供真实服务商证据，整体判定为 inconclusive（退出码 3）。 演示运行成功，但无法据此批准某个模型。 --no-save 会跳过 JSON/Markdown 结果文件；--no-env-file 会跳过凭据文件。

观看交互式默认模板演示（30 秒）

选择模拟器和默认的 Reply with ok 测试，检查计划并确认本地运行。 会话还会通过 CLI JSON 读取相同的判定：

本地测试：通过。真实服务商：未测试。没有使用 API 密钥或发起服务商调用。 观看 MP4 或从文字教程 和交互式 CLI JSON 示例开始。

对于基准测试运行，请先阅读判定，再采取行动：

• pass，退出码 0： 已配置的检查通过，且证据符合要求。
• fail，退出码 1： 某项已配置的检查失败；请检查原因。
• inconclusive，退出码 3： 证据不足；请阅读阻塞警告。

运行通过只能证明已配置工作负载的结果，不能作为生产环境批准。

支持路由契约的实测结果

以下是精选的真实服务商观测结果，包括检查失败和请求被拒绝的情况。每个模型收到 16 个请求。日期、路由和请求设置各不相同；这些结果描述的是一种工作负载，并非通用排名。

延迟涵盖成功的 API 响应，包括未通过契约的响应，不包括 API 错误。— 表示不可用；缺少用量信息时，总成本为未知。OpenRouter 的观测结果不能证明原生服务商的行为。 以文本形式阅读结果、请求设置和失败分析。

首次实测运行

从应用已强制执行的一条规则开始。 项目集成指南 提供了完整的路由契约，其中包含通过／拒绝用例和无需花费的拉取请求检查。请与已部署的提示词和响应解析器保持一致；本地用例检查不会自动执行应用代码。

若要改用精简的服务商入门示例：

llm-preflight init live.json --template provider \
  --provider openai --model gpt-6.1-sol --api-key-env OPENAI_API_KEY

该入门示例要求的内容必须恰好是 ok。在 live.json 中添加以下顶层字段，并保留现有字段，即可在本地检查验证器：

{
  "validation_fixtures": [
    {"name": "accepted-label", "response": "ok", "expect": "pass"},
    {"name": "rejected-label", "response": "not ok", "expect": "fail"}
  ]
}

在 shell 中设置 OPENAI_API_KEY，或将其设在 live.json 旁、尚未提交的 .env.production 文件中。配置中只保存变量名，绝不保存密钥。预览检查，但不发起生成请求：

llm-preflight live.json --contract-check
llm-preflight live.json --doctor
llm-preflight live.json --pricing-check
llm-preflight live.json --dry-run

该入门示例最多发起 3 个请求，预估成本上限为 $0.05。请解决警告，并检查路由、计入重试后的请求上限、定价和数据保留设置。该入门示例默认会保存失败的响应；分享前请检查生成的文件。

**付费请求：**只有在检查并批准该计划后，才运行：

llm-preflight live.json

直接运行 CLI 不会另行提示确认。除非使用 --no-save，否则结果将以 JSON 和 Markdown 格式保存在 results/ 下。CLI 会读取与配置文件同目录的 .env.production，但不会覆盖已有的 shell 值；使用 --env-file PATH 选择其他文件，或使用 --no-env-file 跳过。

选择你的路径

• 设置真实项目。 使用 项目集成指南 调整一条应用规则。
• 验证变更。 使用 模型变更指南 对比已批准配置和候选配置。
• 自动化已确立的契约。 使用 CI 和 JSON 输出 或 GitHub Action。
• 配置编码 Agent。 在受信任的仓库中运行 llm-preflight-mcp --workspace "$PWD"，并参阅 MCP 服务指南。

查看合约变更导致失败

审查产物会保留决策、合约有效性、延迟、用量、预估费用和阻止性警告。无需再次请求提供方，即可将保存的 schema-version-1 JSON 渲染为独立报告。将运行输出的已保存 JSON 路径替换 results/run.json：

llm-preflight report results/run.json --output report.html

渲染器会省略提示词、响应、本地路径和可识别运行的元数据。要运行可复现示例，请在源代码检出目录中运行以下命令：

python3 -m llm_preflight report examples/reports/schema-baseline.json --format markdown
python3 -m llm_preflight report examples/reports/schema-break.json --format markdown

第一个合成结果通过；第二个报告 contract_failure、67% 的合约有效性，以及一次仅由合约导致的失败。 报告图库 还演示了被 no_record 阻止的门禁（退出码 1）。这些测试数据不会调用提供方，也不能提供经证明的 CI 证据。

CLI、CI 和 MCP

可用作 CLI、GitHub Action 和本地 MCP 服务。 Action 默认不发送生成请求；实时 MCP 运行需要明确确认会产生费用。请保持客户端的工具审批启用：其确认字段不能证明有人授权了支出。

不做预检，不予合并。 配置必需检查后，离线门禁要求有一条最新且通过的 CI 记录，并且与当前合约、路由、提示词和运行选择相匹配。保护生成方和门禁工作流；对于签名记录，还需在门禁运行前执行 gh attestation verify。按照 预检证明 进行配置。本地测试数据通过或安装了软件包，并不能强制执行合并策略。

它不会认证生产环境中的行为，只能证明检查已完成。

面向编码 Agent 的 MCP

在 MCP 客户端中配置已安装的 stdio 命令：

{
  "mcpServers": {
    "llm-preflight": {
      "command": "llm-preflight-mcp",
      "args": ["--workspace", "/absolute/path/to/repository"]
    }
  }
}

这七个工具可审计字面模型 ID、验证配置、预览计划、运行预检、比较已保存的基线、验证记录，以及检查 CI 证据是否满足门禁要求。对于现有合约，请从 validate_config 和 dry_run_plan 开始。Agent 必须读取结构化决策并报告缺失的证据。有关请求和结果示例及工作区边界，请参阅 MCP 指南。

agent-smoke 套件使用 --smoke 时，每个模型会在配置的重试次数之前发送六个请求。CLI 命令请参阅 编码 Agent 工作流。 Agent 不得为了通过检查而弱化验证器，也不得根据门禁结果推断自己已获准执行付费操作。

常见任务

• 审计现有模型 ID： llm-preflight --audit-source . 会报告捆绑快照中标记为已弃用或即将弃用的字面 ID。无需配置或密钥。添加 --ci 可让弃用判定影响退出码；不添加时，发现问题通常以 0 退出。在 Git 仓库中，扫描会读取已跟踪且未被忽略的文件。请参阅模型弃用。

• 检查定价： --doctor 提供定价参考；--pricing-check 是默认失败关闭的覆盖率门禁。使用 llm-preflight benchmark.json --dry-run 预览运行。

• 审查 Git 变更： llm-preflight benchmark.json --change-plan 会根据静态信号提出检查方案；这不代表已授权执行。

• 发现候选模型： 刷新元数据、准备计划并预览：

  llm-preflight catalog refresh benchmarks/watch.json
  llm-preflight catalog prepare benchmarks/watch.json \
    --against benchmarks/approved.json --output benchmarks/candidates.json
  llm-preflight benchmarks/candidates.json --migration-check --dry-run
  

  请先按照模型目录指南创建 watch/approved 文件。目录探测是单独的步骤，可能会产生费用。

安全地更换模型

将已批准和候选模型放入经过审核的配置中，然后预览内置兼容性测试包：

llm-preflight benchmark.json --migration-check --dry-run

批准该计划后，llm-preflight benchmark.json --migration-check 会在配置的重试次数之前，为每个模型发送三个内置测试用例：回答一个首都问题、总结和改写。这些测试用于检查基本兼容性；请使用你自己的应用契约测试，确认此次更换是否符合功能要求。

安全边界

结果仅适用于某一时刻配置的账户、路由、提示词和验证器。模型响应仍具有随机性。确定性验证会检查你声明的规则，但无法确认语义准确性或生产环境安全性。发送实时请求前，请预览用量限制，并由集成负责人掌握付费运行权限。

对比说明

如果你需要在更改集成前进行范围明确的契约检查并留存可审核的证据，请使用本项目。评估框架也支持断言和 CI；如果现有框架已满足需求，请继续使用。更全面的评估套件适用于语义评分和统计比较；可观测性工具则适用于生产环境追踪和事件调查。请参阅适用场景。

获取帮助或在你的项目中试用

寻求设置帮助或契约示例。请提供版本、预期检查内容和已脱敏的输出。切勿分享密钥、私人提示词或提供商响应。漏洞问题请使用安全政策。

文档

文档主页按任务分类提供导航。有关确切行为，请参阅 CLI 参考、配置和结果 JSON。原生路由和按日期整理的定价信息请见当前快照。 AI 实现测试指南说明了预期工作流和范围。

每个版本的发行说明都在变更日志中。

贡献和许可证

开发和文档标准请参阅贡献指南。本项目根据 MIT 许可证发布。