local-deep-research 统一指标模块Unified Metrics Module基准测试与参数优化的指标计算、报告与可视化实战指南【免费下载链接】local-deep-research~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10 search engines - arXiv, PubMed, your private documents. Everything Local Encrypted.项目地址: https://gitcode.com/GitHub_Trending/lo/local-deep-research本篇技术指南围绕 local-deep-research 项目中的统一指标模块metrics 模块 README展开系统讲解该模块如何用一套统一的 API 同时服务标准基准测试如 SimpleQA与参数优化两类场景从结果文件计算指标、生成详细报告到面向优化器输出质量/速度/资源三维评分与组合得分再到绘制优化历史曲线。读完本文你将掌握calculate_metrics、generate_report、calculate_combined_score等核心函数的使用方法、参数语义与底层实现原理能够直接在自己的基准测试与调参流程中落地这套指标管线。一、模块定位一套指标管线服务两类场景local-deep-research 的基准测试框架详见 benchmarks 目录 README既承担着对系统回答准确性的标准化评测SimpleQA、BrowseComp也承担着为参数优化器提供目标函数数值的重任。传统做法下这两类场景往往各自维护一套指标计算逻辑容易产生口径不一致、维护成本高的问题。统一指标模块src/local_deep_research/benchmarks/metrics/正是为解决这一问题而设计。其 README 明确将模块职责划分为三个主组件计算Calculation从基准测试结果与系统配置计算指标的核心函数报告Reporting基于基准测试结果生成结构化 Markdown 报告的函数可视化Visualization将优化结果绘制为图表供人观察的工具。对应源码实现分布在 calculation.py、reporting.py、visualization.py并由 statistics.py 提供置信区间、样本量等统计支撑。所有公共 API 统一在 metrics/init.py 中导出使用者只需一行from local_deep_research.benchmarks.metrics import ...即可按需取用。此外模块还保留了向后兼容的别名层optimization/metrics.py 直接转导出本模块的四个优化指标函数并在源码注释中明确提示新代码应使用统一指标模块可见该模块已取代旧有的分散指标实现成为项目内指标计算的统一入口。二、基本指标计算从 results.jsonl 到完整指标字典2.1 最小用法按照 README 给出的最简示例从一份基准测试结果文件即可直接得到指标字典from local_deep_research.benchmarks.metrics import calculate_metrics # Calculate metrics from a results file metrics calculate_metrics(path/to/results.jsonl)calculate_metrics的输入是 JSON Lines 格式每行一个 JSON 对象的结果文件输出是一个包含完整指标信息的字典。2.2 输入格式约定结合 calculation.py 的实现可以看出解析逻辑为逐行读取文件、忽略空行、对每行执行json.loads。若文件不存在或解析失败函数会记录异常并以{error: str(e)}返回若文件为空返回{error: No results found}。这种宁可返回错误字典也不抛异常中断的设计保证了在批量跑基准时单个失败文件不会拖垮整个流程。每条记录可携带的字段依据calculate_metrics与报告模块 reporting.py 中的读取逻辑包括字段含义is_correct布尔值该条结果是否判定正确用于计算准确率processing_time该条处理的耗时秒用于计算平均处理时间confidence置信度数值用于计算平均置信度error若存在该字段则计入错误统计category类别标签可选存在时额外输出按类别的指标problem/correct_answer/extracted_answer/reasoning问题、标准答案、模型答案与推理过程用于报告中的示例展示2.3 输出指标字段详解calculate_metrics返回的字典包含以下基础指标对应 calculation.py字段说明total_examples结果总条数graded_examples含is_correct字段、可参与准确率统计的条数correct判定正确的条数accuracy正确率 correct / graded_examples无可评分样本时为 0accuracy_ci准确率的 Wilson 得分区间详见第三节average_processing_time平均处理时间秒average_confidence平均置信度对每条confidence做整数转换后取均值error_count/error_rate含error字段的记录数与占比timestampUTC 时间戳ISO 8601 格式当结果中存在category字段时函数还会汇总每个类别下的total、correct、accuracy与accuracy_ci放入返回字典的categories键中calculation.py。这对于按题型、按难度、按领域拆分分析基准结果非常实用SimpleQA 等数据集天然带类别信息可直接受益。2.4 一个完整的最小可运行示例from local_deep_research.benchmarks.metrics import calculate_metrics metrics calculate_metrics(path/to/results.jsonl) print(fAccuracy: {metrics[accuracy]:.3f}) print(f95% CI: [{metrics[accuracy_ci][lower]:.3f}, {metrics[accuracy_ci][upper]:.3f}]) print(fAvg time: {metrics[average_processing_time]:.2f}s) # 若存在分类信息逐一打印 for cat, cm in metrics.get(categories, {}).items(): print(f{cat}: {cm[accuracy]:.3f} ({cm[correct]}/{cm[total]}))三、统计支撑Wilson 得分区间与样本量规划准确率本身只是一个点估计样本量小的时候波动很大。统一指标模块通过 statistics.py 提供了一套纯 Python 实现无第三方依赖的统计工具这也是calculate_metrics输出accuracy_ci的底层依据。3.1 Wilson 得分区间wilson_score_interval与朴素正态Wald近似相比Wilson 区间具备三个关键优点源码 docstring 中明确列出区间边界永远不会超出 [0, 1]在准确率为 0% 或 100% 时行为依然正确在小样本下覆盖率更好。签名与返回值如下from local_deep_research.benchmarks.metrics import wilson_score_interval ci wilson_score_interval(successes85, total100, confidence0.95) # 返回: {lower: ..., upper: ..., center: ..., margin_of_error: ..., sample_size: 100}参数confidence默认为 0.95即 95% 置信区间。center是 Wilson 区间的中心非原始比例、margin_of_error为区间半宽sample_size为实际使用的样本数。当total 0时返回全 0 的空区间当successes不在[0, total]内会抛出ValueErrorstatistics.py。区间计算依赖normal_quantile求标准正态分布分位数其采用 Beasley-Springer-Moro 有理逼近实现精度约 1e-8无需引入 scipy因此该统计层可离线、轻量运行。3.2 样本量规划sample_size_for_difference在对比两套配置的准确率差异时样本量不足会导致结论不可靠。sample_size_for_difference(p1, p2, power0.8, alpha0.05)基于双侧双比例 z 检验公式n (z_alpha/2 z_beta)^2 * (p1(1-p1) p2(1-p2)) / (p1 - p2)^2给出每组需要多少样本才能以给定功效检出差异。默认功效 80%、显著性水平 0.05若p1 p2会抛出ValueError因为无差异可检statistics.py。在跑配置对比如 compare 命令之前先用它估算每个配置至少需要的样例数能有效避免跑完才发现统计功效不足的返工。四、报告生成把指标沉淀为可分享的 Markdown4.1 基本用法from local_deep_research.benchmarks.metrics import generate_report # Generate a detailed report report_path generate_report( metricsmetrics, results_filepath/to/results.jsonl, output_filereport.md, dataset_nameSimpleQA, config_info{Dataset: SimpleQA, Examples: 100} )generate_report的参数reporting.py参数默认值说明metrics必填calculate_metrics输出的指标字典results_file必填原始结果文件路径用于抽取正/误例展示output_fileevaluation_report.md报告保存路径dataset_nameUnknown数据集名称写入报告标题与元数据config_infoNone配置信息字典如{Dataset: SimpleQA, Examples: 100}逐项写入报告4.2 报告结构从源码可见生成的报告依次包含以下章节reporting.py标题与 Summary总样本数、已评分样本数、正确数、准确率保留 3 位小数以及若可用95% Wilson 置信区间、平均处理时间、平均置信度、错误数与错误率Category Performance当指标中含categories时每个类别单独成节列出 Total / Correct / Accuracy / 95% CIConfigurationconfig_info中传入的参数逐行列出保证报告可复现Example Correct Answers / Example Incorrect Answers从结果文件分别抽取最多 5 条正确与 5 条错误样例每条展示 Question、Correct Answer、Model Answer、Reasoning 四个字段方便人工复核模型在哪些问题上失手Metadata报告生成时间UTC与数据集名称。4.3 安全写入机制值得注意的是报告最终通过write_file_verified(output_file, content, benchmark.allow_file_output, contextbenchmark report)落盘reporting.py。这意味着文件写入需要经过项目的安全文件写入校验器授权权限名benchmark.allow_file_output这是 local-deep-research 安全体系的一部分。若你在自定义集成中调用generate_report遇到写入被拒应检查该权限/校验器的配置而不是绕过安全层。五、面向参数优化的指标族质量、速度、资源与组合得分这是统一指标模块的另一核心应用面把某套系统配置如迭代次数、每轮问题数、搜索引擎换算成可被优化器比较的标量分数。5.1 质量指标calculate_quality_metricsfrom local_deep_research.benchmarks.metrics import ( calculate_quality_metrics, calculate_speed_metrics, calculate_resource_metrics, calculate_combined_score ) # Calculate quality metrics for a configuration quality_metrics calculate_quality_metrics( system_config{iterations: 3, questions_per_iteration: 3} )其内部先调用evaluate_benchmark_quality将system_config中的iterations、questions_per_iteration、search_strategy默认source-based、search_tool默认searxng、model_name、provider组装成搜索配置交给run_simpleqa_benchmark跑一轮真实 SimpleQA 基准默认 2 个样例、启用自动评分然后把准确率直接映射为quality_scorecalculation.py。返回字典含quality_score与accuracy两个键calculation.py。需要注意num_examples默认值为 2源码注释明确写着Reduced for quicker demo为快速演示而缩减。正式评估时应显式传更大的num_examples否则单个样例的波动会直接左右评分。5.2 速度指标calculate_speed_metricsspeed_metrics calculate_speed_metrics( system_config{iterations: 3, questions_per_iteration: 3}, querytest query, num_runs1, )calculate_speed_metrics委托给measure_execution_time它会基于system_config实例化AdvancedSearchSystemmax_iterations、questions_per_iteration、strategy_name均来自配置用指定query跑num_runs次完整检索统计平均耗时并按下式做归一化calculation.pyspeed_score 1 / (1 average_time / 30)该式本质是围绕 30 秒的 sigmoid 型归一化耗时约 30 秒得分约 0.5、10 秒以内得分高于 0.8、超过 2 分钟则低于 0.2。返回的speed_metrics含speed_score与average_time。另外函数在finally中通过safe_close统一回收 LLM、搜索引擎与搜索系统实例避免长时间优化循环中资源泄漏calculation.py。5.3 资源指标calculate_resource_metricsresource_metrics calculate_resource_metrics( system_config{iterations: 3, questions_per_iteration: 3} )当前实现为基于配置值的启发式评估源码注释明确说明这是简化版真实场景应测量内存占用、API 调用次数等。它取iterations、questions_per_iteration、max_results默认 50计算复杂度complexity iterations * questions * (max_results / 50) resource_score 1 / (1 complexity / 4)返回resource_score越低越好已归一化到 0–1与estimated_complexitycalculation.py。在解读该分数时务必记住其启发式性质它衡量的是配置的计算量预期而非真实资源占用。5.4 组合得分calculate_combined_scorecombined_score calculate_combined_score( metrics{ quality: quality_metrics, speed: speed_metrics, resource: resource_metrics }, weights{quality: 0.6, speed: 0.3, resource: 0.1} )calculate_combined_score对三类指标做加权求和。权重默认值为{quality: 0.6, speed: 0.3, resource: 0.1}若传入的权重和不为 1会自动归一化和为 0 时返回 0.0。每个分项从对应指标字典中取quality_score、speed_score、resource_score键缺失视为 0最终返回 0–1 之间的组合得分calculation.py。加权设计让使用者可以按业务侧重更看重答案质量、还是更看重响应速度自由调配三者的比重。5.5 在优化器中的实际应用从源码看组合/分项得分确实被项目自身的优化器消费optuna_optimizer.py 在目标函数中同时读取质量得分与速度得分并参考self.metric_weights中的speed权重默认 0.4计算综合目标值其可视化与结果汇总也大量使用speed_score字段。可见统一指标模块正是参数自动优化闭环中的度量层——优化器只面向这些归一化分数工作指标口径由 metrics 模块统一保障。六、可视化观察优化收敛过程from local_deep_research.benchmarks.metrics.visualization import ( plot_optimization_history, ) # Plot optimization history fig plot_optimization_history( trial_values[0.5, 0.6, 0.7, 0.65, 0.8], best_values[0.5, 0.6, 0.7, 0.7, 0.8], output_fileoptimization_history.png )plot_optimization_history(trial_values, best_values, output_fileNone, titleOptimization History)绘制两条曲线淡色点线为每次试验trial的目标值红色实线为截至该试验的历史最优值visualization.py。两线之间的分离程度直观反映了优化的收敛情况与噪声水平。实现细节上值得注意两点依赖容错模块在导入时用try/except ImportError探测 matplotlib。若环境中没有 matplotlibMATPLOTLIB_AVAILABLE置为Falseplot_optimization_history不会崩溃而是记录警告并返回Nonevisualization.py。因此在仅跑指标计算的环境中可以安全导入整个 metrics 包输出控制output_file为None时直接返回Figure对象交给调用方处理提供路径时以 300 dpi、bbox_inchestight保存。trial_values与best_values长度应一致x 轴从 1 开始编号试验序号。七、实战编排把三类能力串成一条完整管线综合以上 API一个典型的跑基准 → 出报告 → 供优化全流程可以这样组织from local_deep_research.benchmarks.metrics import ( calculate_metrics, generate_report, calculate_quality_metrics, calculate_speed_metrics, calculate_resource_metrics, calculate_combined_score, ) # 1. 标准基准计算指标 生成报告 metrics calculate_metrics(results/simpleqa_run.jsonl) report_path generate_report( metricsmetrics, results_fileresults/simpleqa_run.jsonl, output_filereports/simpleqa_report.md, dataset_nameSimpleQA, config_info{iterations: 3, questions_per_iteration: 3, search_tool: searxng}, ) print(Report:, report_path) # 2. 参数优化把一套候选配置映射为组合得分 system_config {iterations: 3, questions_per_iteration: 3, max_results: 50} quality calculate_quality_metrics(system_config, num_examples10) # 正式评估加大样本 speed calculate_speed_metrics(system_config, num_runs2) # 多次取平均 resource calculate_resource_metrics(system_config) score calculate_combined_score( metrics{quality: quality, speed: speed, resource: resource}, weights{quality: 0.6, speed: 0.3, resource: 0.1}, ) print(fCombined score: {score:.3f})八、使用建议与注意事项样本量决定结论可靠性默认的num_examples2质量指标与num_runs1速度指标仅适合快速冒烟测试正式评估请显式增大并优先用sample_size_for_difference预估所需样例数再用calculate_metrics输出的 Wilson 置信区间判断两套配置的差异是否显著。速度归一化的参考系speed_score的 30 秒基准是项目自身的经验设定对应约 0.5 分横向对比不同机器上的分数时需注意硬件差异。资源指标是启发式calculate_resource_metrics基于配置复杂度估算不测量真实内存/调用量对资源敏感的场景应结合 efficiency 目录下的资源监控/性能剖析工具补充实测数据。报告写入受安全校验generate_report走benchmark.allow_file_output权限校验接入自定义流程时需保证该校验器配置就绪。保持模块作为统一入口项目已通过 optimization/metrics.py 完成向后兼容转导新代码应统一从local_deep_research.benchmarks.metrics导入避免产生第二套指标口径。延伸阅读统一指标模块说明本文依据的原始文档指标计算实现基础指标、优化指标族与组合得分的完整实现报告生成实现Markdown 报告结构与安全写入逻辑统计工具实现Wilson 区间与样本量计算纯 Python可视化实现优化历史绘图与 matplotlib 依赖容错基准测试框架说明SimpleQA/BrowseComp、CLI、Web 界面与配置对比的整体背景优化器使用示例指标族在参数自动优化中的真实消费方式。【免费下载链接】local-deep-research~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10 search engines - arXiv, PubMed, your private documents. Everything Local Encrypted.项目地址: https://gitcode.com/GitHub_Trending/lo/local-deep-research创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 local-deep-research 统一指标模块（Unified Metrics Module）：基准测试与参数优化的指标计算、报告与可视化实战指南
local-deep-research 统一指标模块Unified Metrics Module基准测试与参数优化的指标计算、报告与可视化实战指南【免费下载链接】local-deep-research~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10 search engines - arXiv, PubMed, your private documents. Everything Local Encrypted.项目地址: https://gitcode.com/GitHub_Trending/lo/local-deep-research本篇技术指南围绕 local-deep-research 项目中的统一指标模块metrics 模块 README展开系统讲解该模块如何用一套统一的 API 同时服务标准基准测试如 SimpleQA与参数优化两类场景从结果文件计算指标、生成详细报告到面向优化器输出质量/速度/资源三维评分与组合得分再到绘制优化历史曲线。读完本文你将掌握calculate_metrics、generate_report、calculate_combined_score等核心函数的使用方法、参数语义与底层实现原理能够直接在自己的基准测试与调参流程中落地这套指标管线。一、模块定位一套指标管线服务两类场景local-deep-research 的基准测试框架详见 benchmarks 目录 README既承担着对系统回答准确性的标准化评测SimpleQA、BrowseComp也承担着为参数优化器提供目标函数数值的重任。传统做法下这两类场景往往各自维护一套指标计算逻辑容易产生口径不一致、维护成本高的问题。统一指标模块src/local_deep_research/benchmarks/metrics/正是为解决这一问题而设计。其 README 明确将模块职责划分为三个主组件计算Calculation从基准测试结果与系统配置计算指标的核心函数报告Reporting基于基准测试结果生成结构化 Markdown 报告的函数可视化Visualization将优化结果绘制为图表供人观察的工具。对应源码实现分布在 calculation.py、reporting.py、visualization.py并由 statistics.py 提供置信区间、样本量等统计支撑。所有公共 API 统一在 metrics/init.py 中导出使用者只需一行from local_deep_research.benchmarks.metrics import ...即可按需取用。此外模块还保留了向后兼容的别名层optimization/metrics.py 直接转导出本模块的四个优化指标函数并在源码注释中明确提示新代码应使用统一指标模块可见该模块已取代旧有的分散指标实现成为项目内指标计算的统一入口。二、基本指标计算从 results.jsonl 到完整指标字典2.1 最小用法按照 README 给出的最简示例从一份基准测试结果文件即可直接得到指标字典from local_deep_research.benchmarks.metrics import calculate_metrics # Calculate metrics from a results file metrics calculate_metrics(path/to/results.jsonl)calculate_metrics的输入是 JSON Lines 格式每行一个 JSON 对象的结果文件输出是一个包含完整指标信息的字典。2.2 输入格式约定结合 calculation.py 的实现可以看出解析逻辑为逐行读取文件、忽略空行、对每行执行json.loads。若文件不存在或解析失败函数会记录异常并以{error: str(e)}返回若文件为空返回{error: No results found}。这种宁可返回错误字典也不抛异常中断的设计保证了在批量跑基准时单个失败文件不会拖垮整个流程。每条记录可携带的字段依据calculate_metrics与报告模块 reporting.py 中的读取逻辑包括字段含义is_correct布尔值该条结果是否判定正确用于计算准确率processing_time该条处理的耗时秒用于计算平均处理时间confidence置信度数值用于计算平均置信度error若存在该字段则计入错误统计category类别标签可选存在时额外输出按类别的指标problem/correct_answer/extracted_answer/reasoning问题、标准答案、模型答案与推理过程用于报告中的示例展示2.3 输出指标字段详解calculate_metrics返回的字典包含以下基础指标对应 calculation.py字段说明total_examples结果总条数graded_examples含is_correct字段、可参与准确率统计的条数correct判定正确的条数accuracy正确率 correct / graded_examples无可评分样本时为 0accuracy_ci准确率的 Wilson 得分区间详见第三节average_processing_time平均处理时间秒average_confidence平均置信度对每条confidence做整数转换后取均值error_count/error_rate含error字段的记录数与占比timestampUTC 时间戳ISO 8601 格式当结果中存在category字段时函数还会汇总每个类别下的total、correct、accuracy与accuracy_ci放入返回字典的categories键中calculation.py。这对于按题型、按难度、按领域拆分分析基准结果非常实用SimpleQA 等数据集天然带类别信息可直接受益。2.4 一个完整的最小可运行示例from local_deep_research.benchmarks.metrics import calculate_metrics metrics calculate_metrics(path/to/results.jsonl) print(fAccuracy: {metrics[accuracy]:.3f}) print(f95% CI: [{metrics[accuracy_ci][lower]:.3f}, {metrics[accuracy_ci][upper]:.3f}]) print(fAvg time: {metrics[average_processing_time]:.2f}s) # 若存在分类信息逐一打印 for cat, cm in metrics.get(categories, {}).items(): print(f{cat}: {cm[accuracy]:.3f} ({cm[correct]}/{cm[total]}))三、统计支撑Wilson 得分区间与样本量规划准确率本身只是一个点估计样本量小的时候波动很大。统一指标模块通过 statistics.py 提供了一套纯 Python 实现无第三方依赖的统计工具这也是calculate_metrics输出accuracy_ci的底层依据。3.1 Wilson 得分区间wilson_score_interval与朴素正态Wald近似相比Wilson 区间具备三个关键优点源码 docstring 中明确列出区间边界永远不会超出 [0, 1]在准确率为 0% 或 100% 时行为依然正确在小样本下覆盖率更好。签名与返回值如下from local_deep_research.benchmarks.metrics import wilson_score_interval ci wilson_score_interval(successes85, total100, confidence0.95) # 返回: {lower: ..., upper: ..., center: ..., margin_of_error: ..., sample_size: 100}参数confidence默认为 0.95即 95% 置信区间。center是 Wilson 区间的中心非原始比例、margin_of_error为区间半宽sample_size为实际使用的样本数。当total 0时返回全 0 的空区间当successes不在[0, total]内会抛出ValueErrorstatistics.py。区间计算依赖normal_quantile求标准正态分布分位数其采用 Beasley-Springer-Moro 有理逼近实现精度约 1e-8无需引入 scipy因此该统计层可离线、轻量运行。3.2 样本量规划sample_size_for_difference在对比两套配置的准确率差异时样本量不足会导致结论不可靠。sample_size_for_difference(p1, p2, power0.8, alpha0.05)基于双侧双比例 z 检验公式n (z_alpha/2 z_beta)^2 * (p1(1-p1) p2(1-p2)) / (p1 - p2)^2给出每组需要多少样本才能以给定功效检出差异。默认功效 80%、显著性水平 0.05若p1 p2会抛出ValueError因为无差异可检statistics.py。在跑配置对比如 compare 命令之前先用它估算每个配置至少需要的样例数能有效避免跑完才发现统计功效不足的返工。四、报告生成把指标沉淀为可分享的 Markdown4.1 基本用法from local_deep_research.benchmarks.metrics import generate_report # Generate a detailed report report_path generate_report( metricsmetrics, results_filepath/to/results.jsonl, output_filereport.md, dataset_nameSimpleQA, config_info{Dataset: SimpleQA, Examples: 100} )generate_report的参数reporting.py参数默认值说明metrics必填calculate_metrics输出的指标字典results_file必填原始结果文件路径用于抽取正/误例展示output_fileevaluation_report.md报告保存路径dataset_nameUnknown数据集名称写入报告标题与元数据config_infoNone配置信息字典如{Dataset: SimpleQA, Examples: 100}逐项写入报告4.2 报告结构从源码可见生成的报告依次包含以下章节reporting.py标题与 Summary总样本数、已评分样本数、正确数、准确率保留 3 位小数以及若可用95% Wilson 置信区间、平均处理时间、平均置信度、错误数与错误率Category Performance当指标中含categories时每个类别单独成节列出 Total / Correct / Accuracy / 95% CIConfigurationconfig_info中传入的参数逐行列出保证报告可复现Example Correct Answers / Example Incorrect Answers从结果文件分别抽取最多 5 条正确与 5 条错误样例每条展示 Question、Correct Answer、Model Answer、Reasoning 四个字段方便人工复核模型在哪些问题上失手Metadata报告生成时间UTC与数据集名称。4.3 安全写入机制值得注意的是报告最终通过write_file_verified(output_file, content, benchmark.allow_file_output, contextbenchmark report)落盘reporting.py。这意味着文件写入需要经过项目的安全文件写入校验器授权权限名benchmark.allow_file_output这是 local-deep-research 安全体系的一部分。若你在自定义集成中调用generate_report遇到写入被拒应检查该权限/校验器的配置而不是绕过安全层。五、面向参数优化的指标族质量、速度、资源与组合得分这是统一指标模块的另一核心应用面把某套系统配置如迭代次数、每轮问题数、搜索引擎换算成可被优化器比较的标量分数。5.1 质量指标calculate_quality_metricsfrom local_deep_research.benchmarks.metrics import ( calculate_quality_metrics, calculate_speed_metrics, calculate_resource_metrics, calculate_combined_score ) # Calculate quality metrics for a configuration quality_metrics calculate_quality_metrics( system_config{iterations: 3, questions_per_iteration: 3} )其内部先调用evaluate_benchmark_quality将system_config中的iterations、questions_per_iteration、search_strategy默认source-based、search_tool默认searxng、model_name、provider组装成搜索配置交给run_simpleqa_benchmark跑一轮真实 SimpleQA 基准默认 2 个样例、启用自动评分然后把准确率直接映射为quality_scorecalculation.py。返回字典含quality_score与accuracy两个键calculation.py。需要注意num_examples默认值为 2源码注释明确写着Reduced for quicker demo为快速演示而缩减。正式评估时应显式传更大的num_examples否则单个样例的波动会直接左右评分。5.2 速度指标calculate_speed_metricsspeed_metrics calculate_speed_metrics( system_config{iterations: 3, questions_per_iteration: 3}, querytest query, num_runs1, )calculate_speed_metrics委托给measure_execution_time它会基于system_config实例化AdvancedSearchSystemmax_iterations、questions_per_iteration、strategy_name均来自配置用指定query跑num_runs次完整检索统计平均耗时并按下式做归一化calculation.pyspeed_score 1 / (1 average_time / 30)该式本质是围绕 30 秒的 sigmoid 型归一化耗时约 30 秒得分约 0.5、10 秒以内得分高于 0.8、超过 2 分钟则低于 0.2。返回的speed_metrics含speed_score与average_time。另外函数在finally中通过safe_close统一回收 LLM、搜索引擎与搜索系统实例避免长时间优化循环中资源泄漏calculation.py。5.3 资源指标calculate_resource_metricsresource_metrics calculate_resource_metrics( system_config{iterations: 3, questions_per_iteration: 3} )当前实现为基于配置值的启发式评估源码注释明确说明这是简化版真实场景应测量内存占用、API 调用次数等。它取iterations、questions_per_iteration、max_results默认 50计算复杂度complexity iterations * questions * (max_results / 50) resource_score 1 / (1 complexity / 4)返回resource_score越低越好已归一化到 0–1与estimated_complexitycalculation.py。在解读该分数时务必记住其启发式性质它衡量的是配置的计算量预期而非真实资源占用。5.4 组合得分calculate_combined_scorecombined_score calculate_combined_score( metrics{ quality: quality_metrics, speed: speed_metrics, resource: resource_metrics }, weights{quality: 0.6, speed: 0.3, resource: 0.1} )calculate_combined_score对三类指标做加权求和。权重默认值为{quality: 0.6, speed: 0.3, resource: 0.1}若传入的权重和不为 1会自动归一化和为 0 时返回 0.0。每个分项从对应指标字典中取quality_score、speed_score、resource_score键缺失视为 0最终返回 0–1 之间的组合得分calculation.py。加权设计让使用者可以按业务侧重更看重答案质量、还是更看重响应速度自由调配三者的比重。5.5 在优化器中的实际应用从源码看组合/分项得分确实被项目自身的优化器消费optuna_optimizer.py 在目标函数中同时读取质量得分与速度得分并参考self.metric_weights中的speed权重默认 0.4计算综合目标值其可视化与结果汇总也大量使用speed_score字段。可见统一指标模块正是参数自动优化闭环中的度量层——优化器只面向这些归一化分数工作指标口径由 metrics 模块统一保障。六、可视化观察优化收敛过程from local_deep_research.benchmarks.metrics.visualization import ( plot_optimization_history, ) # Plot optimization history fig plot_optimization_history( trial_values[0.5, 0.6, 0.7, 0.65, 0.8], best_values[0.5, 0.6, 0.7, 0.7, 0.8], output_fileoptimization_history.png )plot_optimization_history(trial_values, best_values, output_fileNone, titleOptimization History)绘制两条曲线淡色点线为每次试验trial的目标值红色实线为截至该试验的历史最优值visualization.py。两线之间的分离程度直观反映了优化的收敛情况与噪声水平。实现细节上值得注意两点依赖容错模块在导入时用try/except ImportError探测 matplotlib。若环境中没有 matplotlibMATPLOTLIB_AVAILABLE置为Falseplot_optimization_history不会崩溃而是记录警告并返回Nonevisualization.py。因此在仅跑指标计算的环境中可以安全导入整个 metrics 包输出控制output_file为None时直接返回Figure对象交给调用方处理提供路径时以 300 dpi、bbox_inchestight保存。trial_values与best_values长度应一致x 轴从 1 开始编号试验序号。七、实战编排把三类能力串成一条完整管线综合以上 API一个典型的跑基准 → 出报告 → 供优化全流程可以这样组织from local_deep_research.benchmarks.metrics import ( calculate_metrics, generate_report, calculate_quality_metrics, calculate_speed_metrics, calculate_resource_metrics, calculate_combined_score, ) # 1. 标准基准计算指标 生成报告 metrics calculate_metrics(results/simpleqa_run.jsonl) report_path generate_report( metricsmetrics, results_fileresults/simpleqa_run.jsonl, output_filereports/simpleqa_report.md, dataset_nameSimpleQA, config_info{iterations: 3, questions_per_iteration: 3, search_tool: searxng}, ) print(Report:, report_path) # 2. 参数优化把一套候选配置映射为组合得分 system_config {iterations: 3, questions_per_iteration: 3, max_results: 50} quality calculate_quality_metrics(system_config, num_examples10) # 正式评估加大样本 speed calculate_speed_metrics(system_config, num_runs2) # 多次取平均 resource calculate_resource_metrics(system_config) score calculate_combined_score( metrics{quality: quality, speed: speed, resource: resource}, weights{quality: 0.6, speed: 0.3, resource: 0.1}, ) print(fCombined score: {score:.3f})八、使用建议与注意事项样本量决定结论可靠性默认的num_examples2质量指标与num_runs1速度指标仅适合快速冒烟测试正式评估请显式增大并优先用sample_size_for_difference预估所需样例数再用calculate_metrics输出的 Wilson 置信区间判断两套配置的差异是否显著。速度归一化的参考系speed_score的 30 秒基准是项目自身的经验设定对应约 0.5 分横向对比不同机器上的分数时需注意硬件差异。资源指标是启发式calculate_resource_metrics基于配置复杂度估算不测量真实内存/调用量对资源敏感的场景应结合 efficiency 目录下的资源监控/性能剖析工具补充实测数据。报告写入受安全校验generate_report走benchmark.allow_file_output权限校验接入自定义流程时需保证该校验器配置就绪。保持模块作为统一入口项目已通过 optimization/metrics.py 完成向后兼容转导新代码应统一从local_deep_research.benchmarks.metrics导入避免产生第二套指标口径。延伸阅读统一指标模块说明本文依据的原始文档指标计算实现基础指标、优化指标族与组合得分的完整实现报告生成实现Markdown 报告结构与安全写入逻辑统计工具实现Wilson 区间与样本量计算纯 Python可视化实现优化历史绘图与 matplotlib 依赖容错基准测试框架说明SimpleQA/BrowseComp、CLI、Web 界面与配置对比的整体背景优化器使用示例指标族在参数自动优化中的真实消费方式。【免费下载链接】local-deep-research~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10 search engines - arXiv, PubMed, your private documents. Everything Local Encrypted.项目地址: https://gitcode.com/GitHub_Trending/lo/local-deep-research创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考