做 AI 选型和技术方案评审时最头疼的问题之一就是如何验证厂商或开源项目在发布说明里写的性能声明。推理速度提升了多少、准确率提高了几个点、成本降低到什么程度这些数字如果只看宣传材料很难判断是否可信。一个务实的做法是把每一条声明都转化成一个公开的、可重复运行的探针probe让任何人在任何环境下都能复现验证。本文就从理念、设计到代码实现完整拆解一个这样的项目把所有 AI 声明与可公开运行的验证探针放在同一个页面上每条声明都能被独立 rerun。1. 背景AI 声明的可信度问题与验证痛点1.1 为什么 AI 声明很难直接采信近两年 AI 领域的新模型、新框架发布几乎每周都有每次发布都伴随着一大堆性能声明。有的是官方 README 里的一句话比如“推理速度提升 40%”有的是技术白皮书里的 benchmark 表格比如“在 MMLU 上超过某某模型”还有的是演讲和论文里的经验数据比如“Agent 方案能把成本降低一半”。这些声明本质上都是信息源给自己的产品背书缺少外部交叉验证。问题不在于这些信息源故意造假而在于测试条件、数据集版本、硬件环境、随机种子、量化方式这些变量任何一个发生变化结果就可能完全不同。我在实践中遇到过不少类似情况一个模型在官方评测里看起来表现很好放到自己的业务数据上效果大打折扣一套推理框架宣传的吞吐量非常惊艳部署到自己的 GPU 上后连一半都达不到。这类问题不是某一个团队特有的而是整个 AI 工程化过程中的共性挑战。如果把这些声明当成不可置疑的结论技术选型就会建立在沙地上。更合理的做法是把每条声明当成一个待验证的假设而不是既定事实。1.2 从“看到结论”到“复现结论”复现reproducibility这个概念在传统科学研究和软件工程里已经非常成熟。一个实验结论如果不能被其他人用相同条件重新验证就很难进入知识体系。放到 AI 领域道理是一样的一个模型声称能达到某个指标那么给出模型权重、数据集、评测脚本、运行环境其他人应该能独立复现出接近的结果。但在工程实践中复现 AI 结论比想象中困难。模型权重经常更新数据集文件可能被重新处理依赖库版本升级后行为会变化GPU 驱动和 CUDA 版本会影响算子性能甚至同样的代码在不同型号显卡上的运行结果都会有差异。既然完全复现很难就需要退一步把验证的最小单元变小。不要求每一条声明都被所有人完整复现先把声明拆成可以被脚本执行的验证步骤把硬件、版本、数据等关键条件记录清楚让后来者能沿着这条链条重新走一遍。1.3 这个项目的核心思路本文要构建的项目受“每条 AI 声明都配一个可公开运行的探针”这个想法启发核心思路可以概括为一句话一个页面就是一个长期维护的验证面板页面上每一条 AI 相关声明旁边都挂着对应的探针定义、运行入口和最新结果任何人拿到这个页面都能看懂声明是什么也能重新运行探针来复核。具体来说项目包含三部分。探针probe把声明抽象成一个可执行脚本脚本接收固定参数输出可解析的结果。运行器runner统一调度探针收集运行结果生成结构化数据。展示页面page把探针清单和运行结果渲染成网页支持一键触发 rerun。这样的结构适合团队内部做 AI 产品的持续验证也适合个人维护自己的评测指标。它不追求自动化到极致而是先保证每一条声明都能被验证、被复现、被追踪。2. 核心概念Claim、Probe 与 Rerun2.1 Claim可验证的 AI 声明Claim 指一条具体的 AI 性能或行为声明它必须满足两个条件足够具体可以被脚本验证。良好的 Claim 示例“在 A100 上运行 Llama 3 7B文本生成速度达到每秒 180 tokens。”“该模型在 MMLU 5-shot 评测集上的准确率为 72.3%。”“使用这套提示词模板客服场景的意图识别准确率不低于 90%。”不良好的 Claim 示例“我们的模型性能大幅提升。”没有量化指标。“在多种 GPU 上运行速度都很快。”环境不明确。“效果非常好。”没有评测口径。在实际项目中声明通常由产品、算法、运营等不同角色提出。项目的第一步就是把这些模糊的话术整理成结构化描述写入统一的探针配置文件。2.2 Probe可执行的验证探针Probe 可以理解为一个独立的最小验证单元。它通常包含两部分内容。第一部分是配置元数据记录声明内容、指标名称、阈值、依赖环境、运行时长等。第二部分是执行逻辑一段可以运行的脚本执行后输出机器可读的结果比如 JSON 格式的指标值。探针设计上要注意几点。单一职责一个探针只验证一条声明。输入确定探针运行所需的输入如数据集、提示词、模型路径必须是代码或配置中固定的不能依赖交互输入。输出规范探针运行成功后将指标写入 stdout运行失败则通过非零退出码表达。多个探针组合在一起就形成了一套 AI 声明验证套件。套件维护得越好页面上的信息就越可信。2.3 Rerun可复现的验证行为Rerun 是验证动作本身。它代表任何一个人在自己的环境下按照探针记录的运行方式把验证脚本重新执行一遍。Rerun 的价值在于可重复性。为了让 rerun 有意义探针定义中必须记录足够多的环境信息比如操作系统、Python 版本、依赖锁定文件、GPU 型号、驱动版本。缺少这些信息别人即使拿到脚本也很难判断自己运行出来的结果和声明结果之间的差异来自哪里。在实际工程中rerun 可以由三种方式触发本地命令行手动运行、定时任务自动运行、页面上一键触发。无论哪种方式结果都要回写到统一的存储中形成历史趋势。3. 环境准备与整体设计3.1 技术选型这个项目不依赖重型框架尽量用轻量工具完成闭环方便阅读源码和二次开发。模块选型说明探针脚本Python 3.10生态丰富方便调用各类模型和评测库配置格式YAML可读性高适合描述声明元数据运行器Python PyYAML subprocess统一调度探针脚本结果存储JSON 文件简单可靠便于页面直接渲染展示页面原生 HTML JavaScript无构建步骤部署到 GitHub Pages 即可自动复现GitHub Actions定时触发探针运行并更新结果以上选型适合大多数团队快速搭建。如果探针数量多、需要并发执行可以考虑引入消息队列和分布式执行框架但这是后话。3.2 项目目录结构项目目录设计如下保持概念清晰。ai-probe-hub/ ├── README.md ├── requirements.txt ├── probes/ │ └── demo_llm_speed/ │ ├── probe.yaml │ └── probe.py ├── runner/ │ └── probe_runner.py ├── scripts/ │ ├── build_index.py │ └── run_all.sh ├── results/ │ └── latest_results.json ├── docs/ │ ├── index.html │ └── assets/ └── .github/ └── workflows/ └── rerun-probes.yml目录职责说明probes存放所有探针每个探针一个独立目录。runner存放探针运行器和公共工具。scripts存放构建页面数据的辅助脚本。results存放探针运行结果页面从这里读取数据。docs静态站点根目录可以直接部署到 GitHub Pages。3.3 开发环境准备开始之前先确保本机环境满足以下条件操作系统Windows / macOS / Linux 均可本文命令以 Linux 风格为例。Python 版本3.10 或更高版本。Git管理项目代码和提交结果。GitHub 账号用于远程仓库、Actions 自动运行和 Pages 部署。安装 Python 依赖pip install pyyaml如需在探针中调用模型推理再根据实际情况安装相应依赖。例如验证 OpenAI 兼容接口时可能需要openai库验证开源模型时可能需要transformers、torch等。这些依赖建议按探针分别管理不要全部装进根环境避免版本冲突。4. 探针定义与执行器实现4.1 用 YAML 定义探针每条声明对应一个probe.yaml文件。下面是一个完整的探针定义示例# 文件路径probes/demo_llm_speed/probe.yaml id: demo-llm-speed title: Demo LLM 文本生成速度验证 claim: 在 NVIDIA A100 GPU 上Demo LLM 的文本生成速度不低于每秒 180 tokens。 metric: tokens_per_second threshold: 180 comparison: environment: os: Ubuntu 22.04 python: 3.10 gpu: NVIDIA A100 80G cuda: 12.x command: python probes/demo_llm_speed/probe.py params: model_path: /models/demo-llm prompt: 请用三句话介绍人工智能的发展历史。 max_tokens: 512 temperature: 0.7 repeat_times: 3字段含义说明id探针唯一标识建议使用短横线命名。claim要验证的原始声明展示在页面上。metric输出指标名称。threshold和comparison判断声明是否成立的条件。get表示实际结果大于等于阈值才视为通过。environment记录关键环境信息方便他人复现。command探针执行命令相对于项目根目录。params探针运行参数由执行器透传给探针脚本。在实际项目中声明会不断变化。一个好的做法是每修改一次声明就同步修改探针元数据并保留 changelog避免页面上的展示信息和实际验证逻辑脱节。4.2 探针执行器 probe_runner.py执行器的作用是读取所有或指定探针的 YAML 配置调用命令收集 stdout 和退出码最后汇总成统一格式的结果文件。# 文件路径runner/probe_runner.py import argparse import json import os import subprocess import sys import yaml from datetime import datetime, timezone, timedelta PROBES_DIR os.path.join(os.path.dirname(__file__), .., probes) RESULTS_DIR os.path.join(os.path.dirname(__file__), .., results) DEFAULT_RESULT_FILE os.path.join(RESULTS_DIR, latest_results.json) def load_probe_config(probe_path: str) - dict: with open(probe_path, r, encodingutf-8) as f: config yaml.safe_load(f) if not isinstance(config, dict): raise ValueError(f探针配置格式错误: {probe_path}) if id not in config or command not in config: raise ValueError(f探针配置缺少 id 或 command 字段: {probe_path}) return config def find_all_probes() - list: probes [] for root, _, files in os.walk(PROBES_DIR): if probe.yaml in files: probes.append(os.path.join(root, probe.yaml)) return sorted(probes) def run_single_probe(config: dict, probe_file: str) - dict: command config[command] env os.environ.copy() result { id: config[id], title: config.get(title, ), claim: config.get(claim, ), metric: config.get(metric, ), threshold: config.get(threshold), comparison: config.get(comparison, ), passed: False, actual_value: None, stdout: , stderr: , exit_code: None, run_at: , probe_file: probe_file, } print(fRunning probe: {config[id]}) try: proc subprocess.run( command, shellTrue, capture_outputTrue, textTrue, timeoutconfig.get(timeout_seconds, 600), envenv, cwdos.path.dirname(probe_file), ) result[exit_code] proc.returncode result[stdout] proc.stdout[-2000:] result[stderr] proc.stderr[-2000:] if proc.returncode 0: metrics parse_probe_output(proc.stdout) actual metrics.get(config.get(metric)) result[actual_value] actual if actual is None: result[passed] False result[stderr] result[stderr] 未从输出中解析到指标值 else: result[passed] compare_value( actual, config.get(threshold), config.get(comparison, ) ) except subprocess.TimeoutExpired: result[stderr] 探针运行超时已终止。 except Exception as e: result[stderr] f执行异常: {str(e)} result[run_at] datetime.now(timezone.utc).strftime(%Y-%m-%dT%H:%M:%SZ) return result def parse_probe_output(stdout: str) - dict: 尝试从 stdout 中解析 JSON 指标兼容单行 JSON 输出。 import re json_pattern r\{.*\} match re.search(json_pattern, stdout, re.DOTALL) if match: try: return json.loads(match.group()) except json.JSONDecodeError: pass return {} def compare_value(actual, threshold, comparison: str) - bool: if actual is None or threshold is None: return False try: actual float(actual) threshold float(threshold) except (TypeError, ValueError): return False if comparison : return actual threshold elif comparison : return actual threshold elif comparison : return actual threshold elif comparison : return actual threshold elif comparison : return actual threshold return False def main(): parser argparse.ArgumentParser(descriptionAI Probe Runner) parser.add_argument(--probe, help指定探针的 probe.yaml 路径) parser.add_argument(--output, defaultDEFAULT_RESULT_FILE) args parser.parse_args() os.makedirs(RESULTS_DIR, exist_okTrue) if args.probe: configs [load_probe_config(args.probe)] else: probe_files find_all_probes() configs [load_probe_config(p) for p in probe_files] results [run_single_probe(c, p) for c, p in zip(configs, [args.probe] * len(configs) if args.probe else find_all_probes())] summary { total: len(results), passed: sum(1 for r in results if r[passed]), failed: sum(1 for r in results if not r[passed]), generated_at: datetime.now(timezone.utc).strftime(%Y-%m-%dT%H:%M:%SZ), results: results, } with open(args.output, w, encodingutf-8) as f: json.dump(summary, f, ensure_asciiFalse, indent2) print(fResults written to {args.output}) sys.exit(0 if summary[failed] 0 else 1) if __name__ __main__: main()执行器有几个关键设计。第一支持断点调试和批量运行。通过--probe只跑单个探针适合开发阶段快速验证不传参数则扫描整个probes目录适合 CI 全量回归。第二结果标准化。无论探针脚本内部实现多复杂执行器只关心三样东西stdout 中的 JSON 指标、退出码、运行时间。这种约束让新探针的接入成本变得很低。第三输出包含摘要。total、passed、failed三个字段可以直接用于页面顶部统计也可以用于 CI 的判断逻辑。4.3 运行探针并输出结果在项目根目录执行python runner/probe_runner.py --probe probes/demo_llm_speed/probe.yaml假设探针输出正常执行器会在终端打印类似信息Running probe: demo-llm-speed Results written to results/latest_results.json查看生成的结果文件cat results/latest_results.json结果文件结构清晰页面可以直接引用。5. 公开验证页面的实现5.1 页面功能设计页面是整个项目的门面也是“每条 AI 声明都配一个可复现探针”这一理念的最直接表达。设计上优先保证三件事声明可读、状态清晰、操作简单。页面顶部展示统计概览探针总数、通过数、失败数、最近一次运行时间。下方是一个探针卡片列表每个卡片依次包含声明内容、指标名称、实际数值、阈值、通过状态和运行时间。卡片底部提供“查看探针配置”和“触发 rerun”两个入口。为了部署简单页面用原生 HTML 加少量 JavaScript 实现不引入前端框架不依赖构建工具。数据访问方式采用 fetch 读取 JSON 文件。如果要部署到 GitHub Pages本地结果文件提交后页面和 JSON 会一起被发布。5.2 生成展示数据的 JSON执行器生成的结果文件可以直接用于页面展示但字段比较多页面端解析麻烦。可以写一个简单的构建脚本把结果转换成页面友好的格式。# 文件路径scripts/build_index.py import json import os RESULTS_DIR os.path.join(os.path.dirname(__file__), .., results) DOCS_DIR os.path.join(os.path.dirname(__file__), .., docs) def build_page_data(): result_path os.path.join(RESULTS_DIR, latest_results.json) with open(result_path, r, encodingutf-8) as f: data json.load(f) cards [] for item in data[results]: cards.append({ id: item[id], title: item[title], claim: item[claim], metric: item[metric], actual: item[actual_value], threshold: item[threshold], comparison: item[comparison], passed: item[passed], run_at: item[run_at], probe_file: item[probe_file], }) page_data { generated_at: data[generated_at], total: data[total], passed: data[passed], failed: data[failed], cards: cards, } os.makedirs(DOCS_DIR, exist_okTrue) output_path os.path.join(DOCS_DIR, assets, page_data.json) os.makedirs(os.path.dirname(output_path), exist_okTrue) with open(output_path, w, encodingutf-8) as f: json.dump(page_data, f, ensure_asciiFalse, indent2) print(fPage data written to {output_path}) if __name__ __main__: build_page_data()5.3 页面 HTML 与渲染逻辑docs/index.html的核心代码如下。!DOCTYPE html html langzh-CN head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 titleAI Probe Hub/title style body { font-family: -apple-system, Segoe UI, PingFang SC, Microsoft YaHei, sans-serif; margin: 0; padding: 24px; background: #f5f6f8; color: #333; } .container { max-width: 960px; margin: 0 auto; } .summary { display: flex; gap: 16px; margin-bottom: 24px; flex-wrap: wrap; } .summary-box { background: #fff; border-radius: 8px; padding: 16px 24px; box-shadow: 0 1px 4px rgba(0,0,0,0.08); flex: 1; min-width: 140px; text-align: center; } .summary-box .num { font-size: 28px; font-weight: 700; } .summary-box .label { color: #777; font-size: 14px; } .card { background: #fff; border-radius: 8px; padding: 20px 24px; margin-bottom: 16px; box-shadow: 0 1px 4px rgba(0,0,0,0.08); border-left: 4px solid #ddd; } .card.passed { border-left-color: #2ecc71; } .card.failed { border-left-color: #e74c3c; } .claim { font-size: 16px; margin-bottom: 12px; } .meta { color: #666; font-size: 14px; line-height: 1.8; } .badge { display: inline-block; padding: 2px 10px; border-radius: 12px; font-size: 13px; color: #fff; margin-left: 8px; } .badge.passed { background: #2ecc71; } .badge.failed { background: #e74c3c; } .actions a { color: #0366d6; text-decoration: none; margin-right: 16px; } /style /head body div classcontainer h1AI Probe Hub/h1 p每条 AI 声明都对应一个可公开运行的探针probe任何人都可以重新运行验证。/p div classsummary div classsummary-boxdiv classnum idtotal0/divdiv classlabel探针总数/div/div div classsummary-boxdiv classnum idpassed0/divdiv classlabel通过/div/div div classsummary-boxdiv classnum idfailed0/divdiv classlabel失败/div/div div classsummary-boxdiv classnum idupdated-/divdiv classlabel更新时间/div/div /div div idcards/div /div script async function loadData() { try { const response await fetch(./assets/page_data.json); const data await response.json(); document.getElementById(total).textContent data.total; document.getElementById(passed).textContent data.passed; document.getElementById(failed).textContent data.failed; document.getElementById(updated).textContent data.generated_at.split(T)[0]; const container document.getElementById(cards); container.innerHTML ; data.cards.forEach(card { const div document.createElement(div); div.className card ${card.passed ? passed : failed}; const badge card.passed ? span classbadge passed通过/span : span classbadge failed失败/span; div.innerHTML div classclaim${card.claim} ${badge}/div div classmeta strong指标/strong${card.metric} ${card.actual ! null ? card.actual : 未解析} nbsp; | nbsp; strong阈值/strong${card.comparison} ${card.threshold} /div div classmeta strong探针/strong${card.id} nbsp; | nbsp; strong最近运行/strong${card.run_at} /div div classactions a href# onclickviewProbe(${card.probe_file})查看探针配置/a a href# onclickrerunProbe(${card.id})触发 rerun/a /div ; container.appendChild(div); }); } catch (e) { document.getElementById(cards).textContent 加载数据失败请检查 page_data.json。 e.message; } } function viewProbe(file) { window.open(file, _blank); } async function rerunProbe(id) { // 实际部署时可在这里调用服务端或 GitHub 相关接口。 // 演示页面中先提示用户。 alert(示例页面不支持在线 rerun。本地可执行: python runner/probe_runner.py --probe 探针路径); } loadData(); /script /body /html页面中rerunProbe在示例环境中是一个提示因为在纯静态页面里无法直接执行服务端脚本。但是接入 GitHub Actions 后可以通过workflow_dispatch接口触发线上运行页面端做成一个带 token 的提交表单即可。6. 完整实战验证一条 AI 推理速度声明6.1 声明描述这个 Demo 探针的声明确认为“在 NVIDIA A100 GPU 上Demo LLM 的文本生成速度不低于每秒 180 tokens。”为了能在普通开发机上演示运行流程这里不真正加载大模型而是在探针脚本中模拟推理测速逻辑生成一段随机长度的文本通过一个幂模拟 token 生成最终输出 tokens 每秒的测量值。真实项目中将模拟部分替换为实际模型推理代码即可。6.2 编写探针脚本探针脚本路径为probes/demo_llm_speed/probe.py。# 文件路径probes/demo_llm_speed/probe.py import json import random import time # 模拟参数实际项目中从 probe.yaml 读取或直接替换为真实模型调用 MAX_TOKENS 512 REPEAT_TIMES 3 # 模拟生成速度的基准值单位 tokens/s BASE_SPEED 195 # 模拟波动范围 JITTER 8 def simulate_generate_once(max_tokens: int) - float: 模拟一次文本生成返回每秒生成的 token 数。 真实场景中这里应该加载模型并调用推理接口。 start time.time() # 模拟推理耗时假设生成 max_tokens 约耗时 2.5 秒 time.sleep(2.5) elapsed time.time() - start speed max_tokens / elapsed # 模拟随机波动 speed * random.uniform(1 - JITTER / 100, 1 JITTER / 100) return speed def main(): random.seed(42) speeds [] for _ in range(REPEAT_TIMES): speed simulate_generate_once(MAX_TOKENS) speeds.append(speed) avg_speed sum(speeds) / len(speeds) output { tokens_per_second: round(avg_speed, 2), speeds: [round(s, 2) for s in speeds], repeat_times: REPEAT_TIMES, } print(json.dumps(output, ensure_asciiFalse)) if __name__ __main__: main()脚本逻辑说明REPEAT_TIMES设为 3表示重复跑 3 次取平均降低偶发波动影响。random.seed(42)固定随机种子让同一环境下的结果更稳定。输出使用 JSON 格式执行器会自动解析tokens_per_second字段。真实场景中把这个脚本替换为实际的模型推理代码即可比如调用transformers的pipeline、OpenAI 兼容接口或者本地推理引擎。只要最终以 JSON 格式输出目标指标执行器不需要任何改动。6.3 运行与验证先执行探针运行器python runner/probe_runner.py --probe probes/demo_llm_speed/probe.yaml执行完成后查看结果cat results/latest_results.json结果中passed字段会根据阈值判断自动计算。如果模拟基准值保持在 195 tokens/s 左右阈值是 180结果应该为true。如果手动修改probe.yaml里的阈值到 200再次运行结果就会变为false页面卡片也会显示失败状态。这一步演示了“探针验证声明”的完整链路声明配置、脚本执行、指标解析、阈值判断、结果输出。6.4 查看页面效果更新页面数据python scripts/build_index.py打开docs/index.html可以看到探针卡片、通过状态、指标值和更新时间。如果后续接入 CI页面还能展示历史趋势。7. 自动复现接入 GitHub Actions7.1 为什么需要自动 rerun探针验证不能只靠人手动跑。手动运行最大的问题是不可追溯你记不清上次跑是什么时候、什么环境、什么结果。没有历史记录就无法回答“这个声明在最近几次验证中是否一直通过”。GitHub Actions 可以很好地解决这个问题。通过定时触发和手动触发探针会自动运行结果自动提交到仓库。这样页面上的数据始终是新鲜的任何团队成员都能查看最新状态。7.2 workflow 配置在.github/workflows/rerun-probes.yml中添加配置# 文件路径.github/workflows/rerun-probes.yml name: Rerun AI Probes on: schedule: # 每天凌晨 2 点自动运行 - cron: 0 2 * * * workflow_dispatch: inputs: probe_id: description: 指定探针 ID留空则运行全部 required: false default: jobs: run-probes: runs-on: ubuntu-latest permissions: contents: write steps: - name: Checkout repository uses: actions/checkoutv4 - name: Setup Python uses: actions/setup-pythonv5 with: python-version: 3.10 - name: Install dependencies run: | pip install pyyaml - name: Run all probes run: | if [ -n ${{ github.event.inputs.probe_id }} ]; then python runner/probe_runner.py --probe probes/${{ github.event.inputs.probe_id }}/probe.yaml else python runner/probe_runner.py fi - name: Build page data run: | python scripts/build_index.py - name: Commit results run: | git config --local user.name github-actions[bot] git config --local user.email github-actions[bot]users.noreply.github.com git add results/ docs/assets/ git diff --quiet git diff --cached --quiet || git commit -m chore: update AI probe results git push注意几点workflow_dispatch支持手动触发可以在 GitHub 页面选择指定探针运行。提交结果的git diff --quiet判断用于在没有变化时跳过 commit。如果探针涉及真实模型推理Runner 上需要配置 GPU 或使用自托管 Runner。GitHub 托管的ubuntu-latest默认没有 GPU真实场景中应改为使用 GPU Runner 或把探针设计成 CPU 可运行的逻辑。7.3 定时运行与结果更新工作流配置好之后每天凌晨 2 点会自动运行所有探针并把结果提交回仓库。点击 workflow 界面的 Run workflow 可以手动触发指定单个探针编号相当于在页面上执行了一次落地的 rerun。在静态页面中可以增加一个按钮链接到 GitHub 的 workflow 触发页面。源码中提供的 rerun 函数可以改为跳转window.open(https://github.com/your-org/ai-probe-hub/actions/workflows/rerun-probes.yml, _blank);这样页面上的“触发 rerun”入口就变成了一个真正可操作的动作。8. 常见问题与排查思路问题现象常见原因解决思路本地能跑但 CI 失败本地环境与 Actions 环境不一致在 workflow 中锁定 Python 版本使用 requirements.txt 固定依赖探针结果每次波动很大未固定随机种子、未设置温度、并发影响固定 seed设置模型 temperature0增加重复次数取平均探针输出中解析不到指标脚本 stdout 不是合法 JSON或字段名与 probe.yaml 不一致本地先手动执行 probe.py确认输出格式检查 metric 字段拼写模型加载时显存不足多探针并发运行导致资源竞争限制并发数或给每个探针分配独立 GPUYAML 解析报错配置缩进错误或缺少必填字段用python -c import yaml; print(yaml.safe_load(open(probe.yaml)))定位错误页面显示更新时间很久GitHub Actions 运行失败或未 push 结果查看 Actions 日志确认结果提交步骤是否成功手动触发 rerun 无效果workflow 配置中 inputs 拼写错误核对github.event.inputs.probe_id参数名是否一致排查问题遵循一个顺序先看探针本身能否独立运行再看执行器解析是否正常最后才看 CI 和页面。把探针脚本从执行器里剥离开来单独调试是最有效的定位手段。9. 最佳实践与工程建议9.1 声明拆解要原子化每条声明只验证一件事。如果一个声明包含多个指标拆成多个探针。例如“响应延迟低于 500ms 且成本降低 30%”应该写成两个探针。原子化拆解后页面状态更加直观失败定位也更加准确。9.2 固定所有输入探针运行中能影响结果的输入都必须固定随机种子、数据集版本、提示词内容、模型权重 commit、依赖版本、系统环境。任何一项变化都可能让结果失去可比性。建议在probe.yaml中记录指纹信息比如模型权重 hash、数据集 commit id。9.3 记录环境指纹除了探针自己的输出执行器还可以在结果文件中补充环境指纹字段比如 Python 版本、操作系统版本、CPU 型号、GPU 型号、CUDA 版本。这个信息对复现他人结果非常有价值。import platform import socket def collect_env_info() - dict: return { platform: platform.platform(), python: platform.python_version(), hostname: socket.gethostname(), }9.4 探针要有明确的退出码探针脚本不能只用 JSON 表达结果还要通过退出码表达运行状态。执行器如果发现退出码非零应把该探针标记为“异常”而不是简单判定“失败”。这样可以把“性能不达标”和“探针本身坏了”区分开。9.5 结果 JSON 版本化每次让执行器生成带时间戳的结果文件比如results/20250214_020300.json再维护一个latest_results.json指向最新结果。这样既方便页面展示又能在历史记录里追溯。9.6 安全与资源限制如果探针要执行外部命令或加载网络模型必须限制执行器运行的网络范围、依赖来源和资源占用。在 CI 中使用最小权限 token在本地环境中为探针设置超时时间避免长时间异常运行占用过多资源。9.7 团队协作规范探针配置和脚本应该像代码一样接受 code review。新增探针时必须写清楚声明来源、验证方式和数据预期。修改声明阈值时应该更新探针描述和 changelog。这样页面上的信息就不会成为无人维护的僵尸文档。10. 总结与后续扩展这个项目的核心价值是把 AI 领域模糊的“我非常厉害”变成具体的“你可以这样验证我很厉害”。页面上的每一条声明都绑定一个探针探针可以被任何人、在任何时间重新运行。这种机制不需要复杂的系统只需要一组配置、一个执行器、一个页面和一套 CI就能让 AI 声明的可信度大大提高。你可以从最简单的一条探针开始维护把自己模型、框架或团队内部工具的性能声明逐步接入。先跑通本地链路再接入 GitHub Actions最后把页面部署到静态站点上。过程中你会发现声明验证不只是为了对外展示更多时候是在帮自己排查问题很多隐藏的依赖、环境差异和性能瓶颈都是在写探针的时候暴露出来的。下一步可以扩展的方向包括支持多数据类型结果图表、接入更多基准测试框架、把探针结果与模型权重版本关联、通过 webhook 在探针失败时通知团队。如果团队已经有监控平台也可以把探针运行结果同步过去形成更完整的验证体系。建议从今天遇到的一条 AI 性能声明开始把它写成第一条探针。验证过一条之后你会对“声明”和“证据”之间的距离有完全不同的感受。 AI声明验证探针：将每条性能声明变成可复现的公开验证
做 AI 选型和技术方案评审时最头疼的问题之一就是如何验证厂商或开源项目在发布说明里写的性能声明。推理速度提升了多少、准确率提高了几个点、成本降低到什么程度这些数字如果只看宣传材料很难判断是否可信。一个务实的做法是把每一条声明都转化成一个公开的、可重复运行的探针probe让任何人在任何环境下都能复现验证。本文就从理念、设计到代码实现完整拆解一个这样的项目把所有 AI 声明与可公开运行的验证探针放在同一个页面上每条声明都能被独立 rerun。1. 背景AI 声明的可信度问题与验证痛点1.1 为什么 AI 声明很难直接采信近两年 AI 领域的新模型、新框架发布几乎每周都有每次发布都伴随着一大堆性能声明。有的是官方 README 里的一句话比如“推理速度提升 40%”有的是技术白皮书里的 benchmark 表格比如“在 MMLU 上超过某某模型”还有的是演讲和论文里的经验数据比如“Agent 方案能把成本降低一半”。这些声明本质上都是信息源给自己的产品背书缺少外部交叉验证。问题不在于这些信息源故意造假而在于测试条件、数据集版本、硬件环境、随机种子、量化方式这些变量任何一个发生变化结果就可能完全不同。我在实践中遇到过不少类似情况一个模型在官方评测里看起来表现很好放到自己的业务数据上效果大打折扣一套推理框架宣传的吞吐量非常惊艳部署到自己的 GPU 上后连一半都达不到。这类问题不是某一个团队特有的而是整个 AI 工程化过程中的共性挑战。如果把这些声明当成不可置疑的结论技术选型就会建立在沙地上。更合理的做法是把每条声明当成一个待验证的假设而不是既定事实。1.2 从“看到结论”到“复现结论”复现reproducibility这个概念在传统科学研究和软件工程里已经非常成熟。一个实验结论如果不能被其他人用相同条件重新验证就很难进入知识体系。放到 AI 领域道理是一样的一个模型声称能达到某个指标那么给出模型权重、数据集、评测脚本、运行环境其他人应该能独立复现出接近的结果。但在工程实践中复现 AI 结论比想象中困难。模型权重经常更新数据集文件可能被重新处理依赖库版本升级后行为会变化GPU 驱动和 CUDA 版本会影响算子性能甚至同样的代码在不同型号显卡上的运行结果都会有差异。既然完全复现很难就需要退一步把验证的最小单元变小。不要求每一条声明都被所有人完整复现先把声明拆成可以被脚本执行的验证步骤把硬件、版本、数据等关键条件记录清楚让后来者能沿着这条链条重新走一遍。1.3 这个项目的核心思路本文要构建的项目受“每条 AI 声明都配一个可公开运行的探针”这个想法启发核心思路可以概括为一句话一个页面就是一个长期维护的验证面板页面上每一条 AI 相关声明旁边都挂着对应的探针定义、运行入口和最新结果任何人拿到这个页面都能看懂声明是什么也能重新运行探针来复核。具体来说项目包含三部分。探针probe把声明抽象成一个可执行脚本脚本接收固定参数输出可解析的结果。运行器runner统一调度探针收集运行结果生成结构化数据。展示页面page把探针清单和运行结果渲染成网页支持一键触发 rerun。这样的结构适合团队内部做 AI 产品的持续验证也适合个人维护自己的评测指标。它不追求自动化到极致而是先保证每一条声明都能被验证、被复现、被追踪。2. 核心概念Claim、Probe 与 Rerun2.1 Claim可验证的 AI 声明Claim 指一条具体的 AI 性能或行为声明它必须满足两个条件足够具体可以被脚本验证。良好的 Claim 示例“在 A100 上运行 Llama 3 7B文本生成速度达到每秒 180 tokens。”“该模型在 MMLU 5-shot 评测集上的准确率为 72.3%。”“使用这套提示词模板客服场景的意图识别准确率不低于 90%。”不良好的 Claim 示例“我们的模型性能大幅提升。”没有量化指标。“在多种 GPU 上运行速度都很快。”环境不明确。“效果非常好。”没有评测口径。在实际项目中声明通常由产品、算法、运营等不同角色提出。项目的第一步就是把这些模糊的话术整理成结构化描述写入统一的探针配置文件。2.2 Probe可执行的验证探针Probe 可以理解为一个独立的最小验证单元。它通常包含两部分内容。第一部分是配置元数据记录声明内容、指标名称、阈值、依赖环境、运行时长等。第二部分是执行逻辑一段可以运行的脚本执行后输出机器可读的结果比如 JSON 格式的指标值。探针设计上要注意几点。单一职责一个探针只验证一条声明。输入确定探针运行所需的输入如数据集、提示词、模型路径必须是代码或配置中固定的不能依赖交互输入。输出规范探针运行成功后将指标写入 stdout运行失败则通过非零退出码表达。多个探针组合在一起就形成了一套 AI 声明验证套件。套件维护得越好页面上的信息就越可信。2.3 Rerun可复现的验证行为Rerun 是验证动作本身。它代表任何一个人在自己的环境下按照探针记录的运行方式把验证脚本重新执行一遍。Rerun 的价值在于可重复性。为了让 rerun 有意义探针定义中必须记录足够多的环境信息比如操作系统、Python 版本、依赖锁定文件、GPU 型号、驱动版本。缺少这些信息别人即使拿到脚本也很难判断自己运行出来的结果和声明结果之间的差异来自哪里。在实际工程中rerun 可以由三种方式触发本地命令行手动运行、定时任务自动运行、页面上一键触发。无论哪种方式结果都要回写到统一的存储中形成历史趋势。3. 环境准备与整体设计3.1 技术选型这个项目不依赖重型框架尽量用轻量工具完成闭环方便阅读源码和二次开发。模块选型说明探针脚本Python 3.10生态丰富方便调用各类模型和评测库配置格式YAML可读性高适合描述声明元数据运行器Python PyYAML subprocess统一调度探针脚本结果存储JSON 文件简单可靠便于页面直接渲染展示页面原生 HTML JavaScript无构建步骤部署到 GitHub Pages 即可自动复现GitHub Actions定时触发探针运行并更新结果以上选型适合大多数团队快速搭建。如果探针数量多、需要并发执行可以考虑引入消息队列和分布式执行框架但这是后话。3.2 项目目录结构项目目录设计如下保持概念清晰。ai-probe-hub/ ├── README.md ├── requirements.txt ├── probes/ │ └── demo_llm_speed/ │ ├── probe.yaml │ └── probe.py ├── runner/ │ └── probe_runner.py ├── scripts/ │ ├── build_index.py │ └── run_all.sh ├── results/ │ └── latest_results.json ├── docs/ │ ├── index.html │ └── assets/ └── .github/ └── workflows/ └── rerun-probes.yml目录职责说明probes存放所有探针每个探针一个独立目录。runner存放探针运行器和公共工具。scripts存放构建页面数据的辅助脚本。results存放探针运行结果页面从这里读取数据。docs静态站点根目录可以直接部署到 GitHub Pages。3.3 开发环境准备开始之前先确保本机环境满足以下条件操作系统Windows / macOS / Linux 均可本文命令以 Linux 风格为例。Python 版本3.10 或更高版本。Git管理项目代码和提交结果。GitHub 账号用于远程仓库、Actions 自动运行和 Pages 部署。安装 Python 依赖pip install pyyaml如需在探针中调用模型推理再根据实际情况安装相应依赖。例如验证 OpenAI 兼容接口时可能需要openai库验证开源模型时可能需要transformers、torch等。这些依赖建议按探针分别管理不要全部装进根环境避免版本冲突。4. 探针定义与执行器实现4.1 用 YAML 定义探针每条声明对应一个probe.yaml文件。下面是一个完整的探针定义示例# 文件路径probes/demo_llm_speed/probe.yaml id: demo-llm-speed title: Demo LLM 文本生成速度验证 claim: 在 NVIDIA A100 GPU 上Demo LLM 的文本生成速度不低于每秒 180 tokens。 metric: tokens_per_second threshold: 180 comparison: environment: os: Ubuntu 22.04 python: 3.10 gpu: NVIDIA A100 80G cuda: 12.x command: python probes/demo_llm_speed/probe.py params: model_path: /models/demo-llm prompt: 请用三句话介绍人工智能的发展历史。 max_tokens: 512 temperature: 0.7 repeat_times: 3字段含义说明id探针唯一标识建议使用短横线命名。claim要验证的原始声明展示在页面上。metric输出指标名称。threshold和comparison判断声明是否成立的条件。get表示实际结果大于等于阈值才视为通过。environment记录关键环境信息方便他人复现。command探针执行命令相对于项目根目录。params探针运行参数由执行器透传给探针脚本。在实际项目中声明会不断变化。一个好的做法是每修改一次声明就同步修改探针元数据并保留 changelog避免页面上的展示信息和实际验证逻辑脱节。4.2 探针执行器 probe_runner.py执行器的作用是读取所有或指定探针的 YAML 配置调用命令收集 stdout 和退出码最后汇总成统一格式的结果文件。# 文件路径runner/probe_runner.py import argparse import json import os import subprocess import sys import yaml from datetime import datetime, timezone, timedelta PROBES_DIR os.path.join(os.path.dirname(__file__), .., probes) RESULTS_DIR os.path.join(os.path.dirname(__file__), .., results) DEFAULT_RESULT_FILE os.path.join(RESULTS_DIR, latest_results.json) def load_probe_config(probe_path: str) - dict: with open(probe_path, r, encodingutf-8) as f: config yaml.safe_load(f) if not isinstance(config, dict): raise ValueError(f探针配置格式错误: {probe_path}) if id not in config or command not in config: raise ValueError(f探针配置缺少 id 或 command 字段: {probe_path}) return config def find_all_probes() - list: probes [] for root, _, files in os.walk(PROBES_DIR): if probe.yaml in files: probes.append(os.path.join(root, probe.yaml)) return sorted(probes) def run_single_probe(config: dict, probe_file: str) - dict: command config[command] env os.environ.copy() result { id: config[id], title: config.get(title, ), claim: config.get(claim, ), metric: config.get(metric, ), threshold: config.get(threshold), comparison: config.get(comparison, ), passed: False, actual_value: None, stdout: , stderr: , exit_code: None, run_at: , probe_file: probe_file, } print(fRunning probe: {config[id]}) try: proc subprocess.run( command, shellTrue, capture_outputTrue, textTrue, timeoutconfig.get(timeout_seconds, 600), envenv, cwdos.path.dirname(probe_file), ) result[exit_code] proc.returncode result[stdout] proc.stdout[-2000:] result[stderr] proc.stderr[-2000:] if proc.returncode 0: metrics parse_probe_output(proc.stdout) actual metrics.get(config.get(metric)) result[actual_value] actual if actual is None: result[passed] False result[stderr] result[stderr] 未从输出中解析到指标值 else: result[passed] compare_value( actual, config.get(threshold), config.get(comparison, ) ) except subprocess.TimeoutExpired: result[stderr] 探针运行超时已终止。 except Exception as e: result[stderr] f执行异常: {str(e)} result[run_at] datetime.now(timezone.utc).strftime(%Y-%m-%dT%H:%M:%SZ) return result def parse_probe_output(stdout: str) - dict: 尝试从 stdout 中解析 JSON 指标兼容单行 JSON 输出。 import re json_pattern r\{.*\} match re.search(json_pattern, stdout, re.DOTALL) if match: try: return json.loads(match.group()) except json.JSONDecodeError: pass return {} def compare_value(actual, threshold, comparison: str) - bool: if actual is None or threshold is None: return False try: actual float(actual) threshold float(threshold) except (TypeError, ValueError): return False if comparison : return actual threshold elif comparison : return actual threshold elif comparison : return actual threshold elif comparison : return actual threshold elif comparison : return actual threshold return False def main(): parser argparse.ArgumentParser(descriptionAI Probe Runner) parser.add_argument(--probe, help指定探针的 probe.yaml 路径) parser.add_argument(--output, defaultDEFAULT_RESULT_FILE) args parser.parse_args() os.makedirs(RESULTS_DIR, exist_okTrue) if args.probe: configs [load_probe_config(args.probe)] else: probe_files find_all_probes() configs [load_probe_config(p) for p in probe_files] results [run_single_probe(c, p) for c, p in zip(configs, [args.probe] * len(configs) if args.probe else find_all_probes())] summary { total: len(results), passed: sum(1 for r in results if r[passed]), failed: sum(1 for r in results if not r[passed]), generated_at: datetime.now(timezone.utc).strftime(%Y-%m-%dT%H:%M:%SZ), results: results, } with open(args.output, w, encodingutf-8) as f: json.dump(summary, f, ensure_asciiFalse, indent2) print(fResults written to {args.output}) sys.exit(0 if summary[failed] 0 else 1) if __name__ __main__: main()执行器有几个关键设计。第一支持断点调试和批量运行。通过--probe只跑单个探针适合开发阶段快速验证不传参数则扫描整个probes目录适合 CI 全量回归。第二结果标准化。无论探针脚本内部实现多复杂执行器只关心三样东西stdout 中的 JSON 指标、退出码、运行时间。这种约束让新探针的接入成本变得很低。第三输出包含摘要。total、passed、failed三个字段可以直接用于页面顶部统计也可以用于 CI 的判断逻辑。4.3 运行探针并输出结果在项目根目录执行python runner/probe_runner.py --probe probes/demo_llm_speed/probe.yaml假设探针输出正常执行器会在终端打印类似信息Running probe: demo-llm-speed Results written to results/latest_results.json查看生成的结果文件cat results/latest_results.json结果文件结构清晰页面可以直接引用。5. 公开验证页面的实现5.1 页面功能设计页面是整个项目的门面也是“每条 AI 声明都配一个可复现探针”这一理念的最直接表达。设计上优先保证三件事声明可读、状态清晰、操作简单。页面顶部展示统计概览探针总数、通过数、失败数、最近一次运行时间。下方是一个探针卡片列表每个卡片依次包含声明内容、指标名称、实际数值、阈值、通过状态和运行时间。卡片底部提供“查看探针配置”和“触发 rerun”两个入口。为了部署简单页面用原生 HTML 加少量 JavaScript 实现不引入前端框架不依赖构建工具。数据访问方式采用 fetch 读取 JSON 文件。如果要部署到 GitHub Pages本地结果文件提交后页面和 JSON 会一起被发布。5.2 生成展示数据的 JSON执行器生成的结果文件可以直接用于页面展示但字段比较多页面端解析麻烦。可以写一个简单的构建脚本把结果转换成页面友好的格式。# 文件路径scripts/build_index.py import json import os RESULTS_DIR os.path.join(os.path.dirname(__file__), .., results) DOCS_DIR os.path.join(os.path.dirname(__file__), .., docs) def build_page_data(): result_path os.path.join(RESULTS_DIR, latest_results.json) with open(result_path, r, encodingutf-8) as f: data json.load(f) cards [] for item in data[results]: cards.append({ id: item[id], title: item[title], claim: item[claim], metric: item[metric], actual: item[actual_value], threshold: item[threshold], comparison: item[comparison], passed: item[passed], run_at: item[run_at], probe_file: item[probe_file], }) page_data { generated_at: data[generated_at], total: data[total], passed: data[passed], failed: data[failed], cards: cards, } os.makedirs(DOCS_DIR, exist_okTrue) output_path os.path.join(DOCS_DIR, assets, page_data.json) os.makedirs(os.path.dirname(output_path), exist_okTrue) with open(output_path, w, encodingutf-8) as f: json.dump(page_data, f, ensure_asciiFalse, indent2) print(fPage data written to {output_path}) if __name__ __main__: build_page_data()5.3 页面 HTML 与渲染逻辑docs/index.html的核心代码如下。!DOCTYPE html html langzh-CN head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 titleAI Probe Hub/title style body { font-family: -apple-system, Segoe UI, PingFang SC, Microsoft YaHei, sans-serif; margin: 0; padding: 24px; background: #f5f6f8; color: #333; } .container { max-width: 960px; margin: 0 auto; } .summary { display: flex; gap: 16px; margin-bottom: 24px; flex-wrap: wrap; } .summary-box { background: #fff; border-radius: 8px; padding: 16px 24px; box-shadow: 0 1px 4px rgba(0,0,0,0.08); flex: 1; min-width: 140px; text-align: center; } .summary-box .num { font-size: 28px; font-weight: 700; } .summary-box .label { color: #777; font-size: 14px; } .card { background: #fff; border-radius: 8px; padding: 20px 24px; margin-bottom: 16px; box-shadow: 0 1px 4px rgba(0,0,0,0.08); border-left: 4px solid #ddd; } .card.passed { border-left-color: #2ecc71; } .card.failed { border-left-color: #e74c3c; } .claim { font-size: 16px; margin-bottom: 12px; } .meta { color: #666; font-size: 14px; line-height: 1.8; } .badge { display: inline-block; padding: 2px 10px; border-radius: 12px; font-size: 13px; color: #fff; margin-left: 8px; } .badge.passed { background: #2ecc71; } .badge.failed { background: #e74c3c; } .actions a { color: #0366d6; text-decoration: none; margin-right: 16px; } /style /head body div classcontainer h1AI Probe Hub/h1 p每条 AI 声明都对应一个可公开运行的探针probe任何人都可以重新运行验证。/p div classsummary div classsummary-boxdiv classnum idtotal0/divdiv classlabel探针总数/div/div div classsummary-boxdiv classnum idpassed0/divdiv classlabel通过/div/div div classsummary-boxdiv classnum idfailed0/divdiv classlabel失败/div/div div classsummary-boxdiv classnum idupdated-/divdiv classlabel更新时间/div/div /div div idcards/div /div script async function loadData() { try { const response await fetch(./assets/page_data.json); const data await response.json(); document.getElementById(total).textContent data.total; document.getElementById(passed).textContent data.passed; document.getElementById(failed).textContent data.failed; document.getElementById(updated).textContent data.generated_at.split(T)[0]; const container document.getElementById(cards); container.innerHTML ; data.cards.forEach(card { const div document.createElement(div); div.className card ${card.passed ? passed : failed}; const badge card.passed ? span classbadge passed通过/span : span classbadge failed失败/span; div.innerHTML div classclaim${card.claim} ${badge}/div div classmeta strong指标/strong${card.metric} ${card.actual ! null ? card.actual : 未解析} nbsp; | nbsp; strong阈值/strong${card.comparison} ${card.threshold} /div div classmeta strong探针/strong${card.id} nbsp; | nbsp; strong最近运行/strong${card.run_at} /div div classactions a href# onclickviewProbe(${card.probe_file})查看探针配置/a a href# onclickrerunProbe(${card.id})触发 rerun/a /div ; container.appendChild(div); }); } catch (e) { document.getElementById(cards).textContent 加载数据失败请检查 page_data.json。 e.message; } } function viewProbe(file) { window.open(file, _blank); } async function rerunProbe(id) { // 实际部署时可在这里调用服务端或 GitHub 相关接口。 // 演示页面中先提示用户。 alert(示例页面不支持在线 rerun。本地可执行: python runner/probe_runner.py --probe 探针路径); } loadData(); /script /body /html页面中rerunProbe在示例环境中是一个提示因为在纯静态页面里无法直接执行服务端脚本。但是接入 GitHub Actions 后可以通过workflow_dispatch接口触发线上运行页面端做成一个带 token 的提交表单即可。6. 完整实战验证一条 AI 推理速度声明6.1 声明描述这个 Demo 探针的声明确认为“在 NVIDIA A100 GPU 上Demo LLM 的文本生成速度不低于每秒 180 tokens。”为了能在普通开发机上演示运行流程这里不真正加载大模型而是在探针脚本中模拟推理测速逻辑生成一段随机长度的文本通过一个幂模拟 token 生成最终输出 tokens 每秒的测量值。真实项目中将模拟部分替换为实际模型推理代码即可。6.2 编写探针脚本探针脚本路径为probes/demo_llm_speed/probe.py。# 文件路径probes/demo_llm_speed/probe.py import json import random import time # 模拟参数实际项目中从 probe.yaml 读取或直接替换为真实模型调用 MAX_TOKENS 512 REPEAT_TIMES 3 # 模拟生成速度的基准值单位 tokens/s BASE_SPEED 195 # 模拟波动范围 JITTER 8 def simulate_generate_once(max_tokens: int) - float: 模拟一次文本生成返回每秒生成的 token 数。 真实场景中这里应该加载模型并调用推理接口。 start time.time() # 模拟推理耗时假设生成 max_tokens 约耗时 2.5 秒 time.sleep(2.5) elapsed time.time() - start speed max_tokens / elapsed # 模拟随机波动 speed * random.uniform(1 - JITTER / 100, 1 JITTER / 100) return speed def main(): random.seed(42) speeds [] for _ in range(REPEAT_TIMES): speed simulate_generate_once(MAX_TOKENS) speeds.append(speed) avg_speed sum(speeds) / len(speeds) output { tokens_per_second: round(avg_speed, 2), speeds: [round(s, 2) for s in speeds], repeat_times: REPEAT_TIMES, } print(json.dumps(output, ensure_asciiFalse)) if __name__ __main__: main()脚本逻辑说明REPEAT_TIMES设为 3表示重复跑 3 次取平均降低偶发波动影响。random.seed(42)固定随机种子让同一环境下的结果更稳定。输出使用 JSON 格式执行器会自动解析tokens_per_second字段。真实场景中把这个脚本替换为实际的模型推理代码即可比如调用transformers的pipeline、OpenAI 兼容接口或者本地推理引擎。只要最终以 JSON 格式输出目标指标执行器不需要任何改动。6.3 运行与验证先执行探针运行器python runner/probe_runner.py --probe probes/demo_llm_speed/probe.yaml执行完成后查看结果cat results/latest_results.json结果中passed字段会根据阈值判断自动计算。如果模拟基准值保持在 195 tokens/s 左右阈值是 180结果应该为true。如果手动修改probe.yaml里的阈值到 200再次运行结果就会变为false页面卡片也会显示失败状态。这一步演示了“探针验证声明”的完整链路声明配置、脚本执行、指标解析、阈值判断、结果输出。6.4 查看页面效果更新页面数据python scripts/build_index.py打开docs/index.html可以看到探针卡片、通过状态、指标值和更新时间。如果后续接入 CI页面还能展示历史趋势。7. 自动复现接入 GitHub Actions7.1 为什么需要自动 rerun探针验证不能只靠人手动跑。手动运行最大的问题是不可追溯你记不清上次跑是什么时候、什么环境、什么结果。没有历史记录就无法回答“这个声明在最近几次验证中是否一直通过”。GitHub Actions 可以很好地解决这个问题。通过定时触发和手动触发探针会自动运行结果自动提交到仓库。这样页面上的数据始终是新鲜的任何团队成员都能查看最新状态。7.2 workflow 配置在.github/workflows/rerun-probes.yml中添加配置# 文件路径.github/workflows/rerun-probes.yml name: Rerun AI Probes on: schedule: # 每天凌晨 2 点自动运行 - cron: 0 2 * * * workflow_dispatch: inputs: probe_id: description: 指定探针 ID留空则运行全部 required: false default: jobs: run-probes: runs-on: ubuntu-latest permissions: contents: write steps: - name: Checkout repository uses: actions/checkoutv4 - name: Setup Python uses: actions/setup-pythonv5 with: python-version: 3.10 - name: Install dependencies run: | pip install pyyaml - name: Run all probes run: | if [ -n ${{ github.event.inputs.probe_id }} ]; then python runner/probe_runner.py --probe probes/${{ github.event.inputs.probe_id }}/probe.yaml else python runner/probe_runner.py fi - name: Build page data run: | python scripts/build_index.py - name: Commit results run: | git config --local user.name github-actions[bot] git config --local user.email github-actions[bot]users.noreply.github.com git add results/ docs/assets/ git diff --quiet git diff --cached --quiet || git commit -m chore: update AI probe results git push注意几点workflow_dispatch支持手动触发可以在 GitHub 页面选择指定探针运行。提交结果的git diff --quiet判断用于在没有变化时跳过 commit。如果探针涉及真实模型推理Runner 上需要配置 GPU 或使用自托管 Runner。GitHub 托管的ubuntu-latest默认没有 GPU真实场景中应改为使用 GPU Runner 或把探针设计成 CPU 可运行的逻辑。7.3 定时运行与结果更新工作流配置好之后每天凌晨 2 点会自动运行所有探针并把结果提交回仓库。点击 workflow 界面的 Run workflow 可以手动触发指定单个探针编号相当于在页面上执行了一次落地的 rerun。在静态页面中可以增加一个按钮链接到 GitHub 的 workflow 触发页面。源码中提供的 rerun 函数可以改为跳转window.open(https://github.com/your-org/ai-probe-hub/actions/workflows/rerun-probes.yml, _blank);这样页面上的“触发 rerun”入口就变成了一个真正可操作的动作。8. 常见问题与排查思路问题现象常见原因解决思路本地能跑但 CI 失败本地环境与 Actions 环境不一致在 workflow 中锁定 Python 版本使用 requirements.txt 固定依赖探针结果每次波动很大未固定随机种子、未设置温度、并发影响固定 seed设置模型 temperature0增加重复次数取平均探针输出中解析不到指标脚本 stdout 不是合法 JSON或字段名与 probe.yaml 不一致本地先手动执行 probe.py确认输出格式检查 metric 字段拼写模型加载时显存不足多探针并发运行导致资源竞争限制并发数或给每个探针分配独立 GPUYAML 解析报错配置缩进错误或缺少必填字段用python -c import yaml; print(yaml.safe_load(open(probe.yaml)))定位错误页面显示更新时间很久GitHub Actions 运行失败或未 push 结果查看 Actions 日志确认结果提交步骤是否成功手动触发 rerun 无效果workflow 配置中 inputs 拼写错误核对github.event.inputs.probe_id参数名是否一致排查问题遵循一个顺序先看探针本身能否独立运行再看执行器解析是否正常最后才看 CI 和页面。把探针脚本从执行器里剥离开来单独调试是最有效的定位手段。9. 最佳实践与工程建议9.1 声明拆解要原子化每条声明只验证一件事。如果一个声明包含多个指标拆成多个探针。例如“响应延迟低于 500ms 且成本降低 30%”应该写成两个探针。原子化拆解后页面状态更加直观失败定位也更加准确。9.2 固定所有输入探针运行中能影响结果的输入都必须固定随机种子、数据集版本、提示词内容、模型权重 commit、依赖版本、系统环境。任何一项变化都可能让结果失去可比性。建议在probe.yaml中记录指纹信息比如模型权重 hash、数据集 commit id。9.3 记录环境指纹除了探针自己的输出执行器还可以在结果文件中补充环境指纹字段比如 Python 版本、操作系统版本、CPU 型号、GPU 型号、CUDA 版本。这个信息对复现他人结果非常有价值。import platform import socket def collect_env_info() - dict: return { platform: platform.platform(), python: platform.python_version(), hostname: socket.gethostname(), }9.4 探针要有明确的退出码探针脚本不能只用 JSON 表达结果还要通过退出码表达运行状态。执行器如果发现退出码非零应把该探针标记为“异常”而不是简单判定“失败”。这样可以把“性能不达标”和“探针本身坏了”区分开。9.5 结果 JSON 版本化每次让执行器生成带时间戳的结果文件比如results/20250214_020300.json再维护一个latest_results.json指向最新结果。这样既方便页面展示又能在历史记录里追溯。9.6 安全与资源限制如果探针要执行外部命令或加载网络模型必须限制执行器运行的网络范围、依赖来源和资源占用。在 CI 中使用最小权限 token在本地环境中为探针设置超时时间避免长时间异常运行占用过多资源。9.7 团队协作规范探针配置和脚本应该像代码一样接受 code review。新增探针时必须写清楚声明来源、验证方式和数据预期。修改声明阈值时应该更新探针描述和 changelog。这样页面上的信息就不会成为无人维护的僵尸文档。10. 总结与后续扩展这个项目的核心价值是把 AI 领域模糊的“我非常厉害”变成具体的“你可以这样验证我很厉害”。页面上的每一条声明都绑定一个探针探针可以被任何人、在任何时间重新运行。这种机制不需要复杂的系统只需要一组配置、一个执行器、一个页面和一套 CI就能让 AI 声明的可信度大大提高。你可以从最简单的一条探针开始维护把自己模型、框架或团队内部工具的性能声明逐步接入。先跑通本地链路再接入 GitHub Actions最后把页面部署到静态站点上。过程中你会发现声明验证不只是为了对外展示更多时候是在帮自己排查问题很多隐藏的依赖、环境差异和性能瓶颈都是在写探针的时候暴露出来的。下一步可以扩展的方向包括支持多数据类型结果图表、接入更多基准测试框架、把探针结果与模型权重版本关联、通过 webhook 在探针失败时通知团队。如果团队已经有监控平台也可以把探针运行结果同步过去形成更完整的验证体系。建议从今天遇到的一条 AI 性能声明开始把它写成第一条探针。验证过一条之后你会对“声明”和“证据”之间的距离有完全不同的感受。