local-deep-research 基准测试接入 Claude API 评分claude_grading 基准的架构、运行与源码剖析【免费下载链接】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本指南以 examples/benchmarks/claude_grading/README.md 为骨架结合仓库内 benchmark.py、run_benchmark.sh、graders.py 等源码讲解如何让 local-deep-research 的基准评测使用 Claude 3 Sonnet 作为 LLM 评分器从 API Key 的来源、grader 模块的运行时补丁patching到 SimpleQA / BrowseComp / Composite 三类评测的配置与输出解读以及如何自定义策略、迭代次数与样本数量完成不同搜索策略之间的横向对比。读完你可以在本地复现并扩展该基准评测流程。一、这个基准评测要解决什么问题local-deep-research 是一个强调“Everything Local Encrypted”的深度研究系统其评测体系内置了默认的 LLM 评分器grader。默认配置见 graders.py 中的DEFAULT_EVALUATION_CONFIG走 OpenRouter 的anthropic/claude-3.7-sonnet。而claude_grading这个示例提供了一条更直接的路径通过本地get_llm函数把评分模型切换到 Claude 3 SonnetAnthropic 官方 API并让 API Key 从本地数据库/环境变量中读取而不是硬编码在评测代码里。它带来的实际收益有三点评分一致性用temperature0的强模型做评分减少随机性对准确率统计的干扰源码注释中明确写着 Zero temp for consistent evaluation。可对比性评测同一个搜索策略在不同参数下的表现或对比source_based等不同策略得到可直接比较的分数。可移植性API Key 通过ANTHROPIC_API_KEY/OPENROUTER_API_KEY环境变量注入不依赖共享数据库也便于在 CI 或多用户环境下运行benchmark.py 中特别注释数据库配置现在按用户隔离基准评测应通过环境变量提供密钥。二、仓库结构速览claude_grading示例位于 examples/benchmarks/claude_grading/包含四个文件文件作用README.md功能说明与使用入口run_benchmark.sh一键启动脚本负责定位项目根目录、激活虚拟环境并调用 Python 入口benchmark.py核心实现构建评分配置、补丁 grader 模块、串联三个评测器init.py模块说明文档字符串它依赖的核心评测基础设施位于 src/local_deep_research/benchmarks/graders.py —— LLM 评分逻辑与评分提示词模板的装配evaluators/simpleqa.py —— SimpleQA 评测器evaluators/browsecomp.py —— BrowseComp 评测器evaluators/composite.py —— 加权综合评分器metrics/calculation.py —— 指标计算准确率、Wilson 置信区间、平均处理时间等templates.py —— SimpleQA / BrowseComp 的评分提示词模板三、功能特性原文档列出的特性在源码中都有对应实现使用 Claude 3 Sonnet 评分默认配置model_nameclaude-3-sonnet-20240229、provideranthropicbenchmark.py。从本地数据库/环境读取 API Keysetup_grading_config()优先读取ANTHROPIC_API_KEY未设置时回退到OPENROUTER_API_KEY并改用 OpenRouter 端点benchmark.py。支持 SimpleQA 与 BrowseComp 两类评测分别实例化SimpleQAEvaluator与BrowseCompEvaluator。可定制权重的综合评分CompositeBenchmarkEvaluator接受benchmark_weights示例中取{simpleqa: 0.5, browsecomp: 0.5}benchmark.py。全面的指标与准确率报告每个评测器都会把结果写入benchmark_results/目录产出 JSON 指标文件与 Markdown 报告。四、使用方式一条命令跑通三组评测原文档要求从项目根目录执行。官方推荐的两种方式# 默认参数source_based 策略、1 次迭代、5 个示例 ./examples/benchmarks/claude_grading/run_benchmark.sh # 自定义参数source_based 策略、2 次迭代、200 个示例 ./examples/benchmarks/claude_grading/run_benchmark.sh --strategy source_based --iterations 2 --examples 200参数与 Python 入口一一对应benchmark.py 中的argparse定义参数默认值说明--strategysource_based要评测的搜索策略名--iterations1搜索迭代轮数--examples5每个基准评测的样本数run_benchmark.sh内部完成三件事run_benchmark.sh从脚本所在目录上溯三级cd $(dirname $0)/../../..切到项目根目录保证local_deep_research包可以被正常 import若存在.venv/bin/activate则激活虚拟环境用pdm run timeout 86400 python -m examples.benchmarks.claude_grading.benchmark $执行评测外层timeout 86400为长时间运行的评测预留了一天上限。五、工作原理运行时补丁Runtime Patching评分模块这是整个示例最核心的设计README 中用一段话概括通过补丁patch评测系统的评分模块使评分调用走本地get_llm从而正确地从数据库/环境中获取 API Key 并配置 Claude 模型。源码中补丁发生在 benchmark.pyimport local_deep_research.benchmarks.graders as graders # 保存原始函数便于事后恢复 original_get_evaluation_llm graders.get_evaluation_llm # 定义一个使用本地 get_llm 的新函数 def custom_get_evaluation_llm(custom_configNone): if custom_config is None: custom_config evaluation_config print(fGetting evaluation LLM with config: {custom_config}) return get_llm(**custom_config) # 替换模块中的函数引用 graders.get_evaluation_llm custom_get_evaluation_llm其效果链是SimpleQAEvaluator/BrowseCompEvaluator内部调用grade_results()见 simpleqa.py而grade_results()最终调用get_evaluation_llm()见 graders.py。由于模块内函数引用已被替换这个调用会落入custom_get_evaluation_llm进而调用本地get_llm(**evaluation_config)llm_config.py。本地get_llm负责从快照/环境解析 provider、model、temperature并经过 LLM 出网策略egress policy校验后返回一个 LangChain LLM 实例该实例还会被ProcessingLLMWrapper包装自动剥离本地模型常见的think标签llm_config.py。评测结束前若补丁变量存在脚本会把graders.get_evaluation_llm恢复为原函数避免影响进程内后续逻辑benchmark.py。需要说明的是这个补丁机制针对的是该仓库的模块引用方式import local_deep_research.benchmarks.graders后修改其属性并非修改任何仓库文件评测进程结束后自动还原符合仓库只读约束。5.1 评分配置的两种回退路径setup_grading_config()的完整决策逻辑benchmark.pyevaluation_config { model_name: claude-3-sonnet-20240229, # Anthropic 官方模型名 provider: anthropic, temperature: 0, # 零温度保证评测可复现 } anthropic_key os.environ.get(ANTHROPIC_API_KEY) if anthropic_key: print(Found Anthropic API key in environment, will use Claude 3 Sonnet for grading) else: openrouter_key os.environ.get(OPENROUTER_API_KEY) if openrouter_key: evaluation_config { model_name: anthropic/claude-3-sonnet-20240229, # OpenRouter 格式 provider: openai_endpoint, openai_endpoint_url: https://openrouter.ai/api/v1, temperature: 0, } else: print(ERROR: No API keys found in environment variables) return None两个路径对get_llm都是合法的provideranthropic走 Anthropic 原生通道provideropenai_endpoint走 OpenAI 兼容端点OpenRouter。如果两个 Key 都没有函数返回None主流程会打印提示并继续尝试用默认配置运行benchmark.py。这里有一个值得注意的细节get_llm只接受model_name、temperature、provider、openai_endpoint_url、api_key等参数见 graders.py 的ldr_supported_params过滤逻辑因此setup_grading_config只构造这五个字段以内的配置避免向get_llm传入不支持的参数导致失败。5.2 出网策略对评分器的影响在 graders.py 的注释中可以看到一个关键约束get_llm在无settings_snapshot时只会允许本地默认 provider要让云端的 Claude 评分器被放行需要把用户作用域下的settings_snapshot传递下去供 LLM 端点出网策略egress policy判断。也就是说如果你所在环境的策略要求“本地端点优先”require_local_llm直接调用云端评分器会被PolicyDeniedError拒绝——这是该仓库的刻意设计fail-closed而非 bug。若遇到此类报错请检查当前用户的 LLM 出网策略配置与所用 API Key 是否匹配。六、评测配置与搜索链路run_benchmark中构造的评测配置benchmark.pyconfig { search_strategy: strategy, # 例如 source_based iterations: iterations, # 搜索迭代次数 questions_per_iteration: 1, # 每次迭代追问的问题数固定为 1 以控制成本 max_results: 10, # 每次搜索返回的最大结果数 search_tool: searxng, # 指定 SearXNG 搜索后端 timeout: 10, # 短超时加速演示 }该配置会流入评测器。以 SimpleQA 为例evaluators/simpleqa.py 的_run_with_dataset_class会通过DatasetRegistry.create_dataset(dataset_idsimpleqa, num_examples..., seed...)加载数据集对每个示例调用local_deep_research.api.quick_summary(query..., iterations..., questions_per_iteration..., search_tool...)驱动真实搜索与生成用extract_answer_from_response()从回答中抽取结构化答案SimpleQA 直接取全文BrowseComp 则提取Exact Answer:与Confidence:字段见 graders.py调用grade_results()走评分器调用calculate_metrics()与generate_report()产出指标和 Markdown 报告。6.1 评分提示词模板评分质量取决于提示词模板templates.py。SimpleQA 模板要求评分器输出Extracted Answer / Reasoning / Correct(yes|no)三段式BrowseComp 模板要求输出extracted_final_answer / reasoning / correct(yes|no) / confidence。grade_single_result()在 graders.py 中用正则分别解析这两类输出并容忍答案中的引文残留会先把形如[1]或【1】的引用标记剥离再送入评分graders.py避免引文干扰判分。七、输出与指标解读所有结果保存在项目根目录下的benchmark_results/中按时间戳隔离benchmark_results/claude_grading_YYYYMMDD_HHMMSS/。其下分为simpleqa/与simpleqa_results.jsonSimpleQA 的原始结果、评分结果与报告browsecomp/与browsecomp_results.jsonBrowseComp 的对应产物composite/与composite_results.json综合评分结果控制台会在每个阶段打印关键数字benchmark.py 等SimpleQA 的accuracy、BrowseComp 的score、Composite 的score以及各自耗时秒。calculate_metrics()metrics/calculation.py计算的指标包括指标含义accuracy正确样本数 / 已评分样本数accuracy_ci准确率的 Wilson score 区间小样本下比朴素比例更稳健average_processing_time平均单样本处理耗时秒average_confidence平均置信度BrowseComp 从回答中解析error_count/error_rate评测过程出错样本数与占比categories若数据集带分类则输出每类准确率与置信区间八、环境要求与前置准备原文档列出的三项要求结合源码补充如下有效的 Claude API Key设置环境变量ANTHROPIC_API_KEY若无 Anthropic Key可设置OPENROUTER_API_KEY走 OpenRouter 兼容端点。脚本不会在仓库内保存任何密钥。本地运行的 SearXNG评测链路中的search_tool默认是searxngbenchmark.py请确保 SearXNG 实例可用且能被项目配置访问。Python 依赖与运行环境项目使用pdm管理依赖脚本通过pdm run启动需要先完成依赖安装若存在.venv脚本会自动激活。九、进阶如何对比不同策略把--strategy换成其他已实现策略即可横向对比。当前仓库src/local_deep_research/advanced_search_system/strategies/下已实现多种策略例如source_based_strategy.py —— 默认的基于来源的策略focused_iteration_strategy.py —— 聚焦迭代策略langgraph_agent_strategy.py —— LangGraph 智能体策略topic_organization_strategy.py —— 主题组织策略news_strategy.py —— 新闻策略典型用法是固定--iterations与--examples逐个切换策略跑三遍然后对比三个时间戳目录中的accuracy/score与平均处理时间。也可以调整 Composite 权重来改变质量与速度之间的权衡综合评分calculate_combined_scorecalculation.py默认的质量/速度/资源权重为 0.6/0.3/0.1可依据你的场景覆盖。十、排错提示No API keys foundANTHROPIC_API_KEY与OPENROUTER_API_KEY均未设置。export 其中一个后重跑。评分调用失败或返回 0 分检查 Anthropic/OpenRouter 账户额度以及当前用户 LLM 出网策略是否允许云端评分器见 5.2 节日志会以policy_audit标记打印拒绝原因。模块导入错误确认是从项目根目录运行脚本run_benchmark.sh会自动切换benchmark.py也会把自身src/加入sys.pathbenchmark.py。结果为空检查 SearXNG 是否可达、timeout: 10是否过短——评测配置中的短超时是为快速演示设置的正式评测可调大。十一、小结claude_grading示例展示了 local-deep-research 评测体系的一种典型扩展方式不改动仓库代码仅通过运行时替换graders.get_evaluation_llm的函数引用即可把评分模型切换到 Claude 3 Sonnet并将密钥来源收敛到环境变量。配合run_benchmark.sh的一键启动、三组评测器SimpleQA / BrowseComp / Composite与完整的指标输出它可以作为策略调优、参数实验和回归对比的稳定脚手架。想深入阅读底层实现建议从 graders.py、evaluators/ 与 metrics/calculation.py 三个文件入手。【免费下载链接】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），仅供参考