企业官网建设流程全解析

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 Sonnet（Anthropic 官方 API），并让 API Key 从本地数据库/环境变量中读取，而不是硬编码在评测代码里。

它带来的实际收益有三点：

1. 评分一致性：用temperature=0的强模型做评分，减少随机性对准确率统计的干扰（源码注释中明确写着 "Zero temp for consistent evaluation"）。
2. 可对比性：评测同一个搜索策略在不同参数下的表现，或对比source_based等不同策略，得到可直接比较的分数。
3. 可移植性：API Key 通过ANTHROPIC_API_KEY/OPENROUTER_API_KEY环境变量注入，不依赖共享数据库，也便于在 CI 或多用户环境下运行（benchmark.py 中特别注释：数据库配置现在按用户隔离，基准评测应通过环境变量提供密钥）。

二、仓库结构速览

claude_grading示例位于 examples/benchmarks/claude_grading/，包含四个文件：

它依赖的核心评测基础设施位于 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_name="claude-3-sonnet-20240229"、provider="anthropic"（benchmark.py）。
• 从本地数据库/环境读取 API Key：setup_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定义）：

run_benchmark.sh内部完成三件事（run_benchmark.sh）：

1. 从脚本所在目录上溯三级cd "$(dirname "$0")/../../.."切到项目根目录，保证local_deep_research包可以被正常 import；
2. 若存在.venv/bin/activate则激活虚拟环境；
3. 用pdm run timeout 86400 python -m examples.benchmarks.claude_grading.benchmark "$@"执行评测，外层timeout 86400为长时间运行的评测预留了一天上限。

五、工作原理：运行时补丁（Runtime Patching）评分模块

这是整个示例最核心的设计，README 中用一段话概括：通过补丁（patch）评测系统的评分模块，使评分调用走本地get_llm，从而正确地从数据库/环境中获取 API Key 并配置 Claude 模型。源码中补丁发生在 benchmark.py：

import local_deep_research.benchmarks.graders as graders # 保存原始函数，便于事后恢复 original_get_evaluation_llm = graders.get_evaluation_llm # 定义一个使用本地 get_llm 的新函数 def custom_get_evaluation_llm(custom_config=None): if custom_config is None: custom_config = evaluation_config print(f"Getting evaluation LLM with config: {custom_config}") return get_llm(**custom_config) # 替换模块中的函数引用 graders.get_evaluation_llm = custom_get_evaluation_llm

其效果链是：

1. SimpleQAEvaluator/BrowseCompEvaluator内部调用grade_results()（见 simpleqa.py），而grade_results()最终调用get_evaluation_llm()（见 graders.py）。
2. 由于模块内函数引用已被替换，这个调用会落入custom_get_evaluation_llm，进而调用本地get_llm(**evaluation_config)（llm_config.py）。
3. 本地get_llm负责从快照/环境解析 provider、model、temperature，并经过 LLM 出网策略（egress policy）校验后返回一个 LangChain LLM 实例；该实例还会被ProcessingLLMWrapper包装，自动剥离本地模型常见的<think>标签（llm_config.py）。
4. 评测结束前，若补丁变量存在，脚本会把graders.get_evaluation_llm恢复为原函数，避免影响进程内后续逻辑（benchmark.py）。

需要说明的是：这个补丁机制针对的是该仓库的模块引用方式（import local_deep_research.benchmarks.graders后修改其属性），并非修改任何仓库文件，评测进程结束后自动还原，符合仓库只读约束。

5.1 评分配置的两种回退路径

setup_grading_config()的完整决策逻辑（benchmark.py）：

evaluation_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都是合法的：provider="anthropic"走 Anthropic 原生通道；provider="openai_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.py）：

config = { "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会：

1. 通过DatasetRegistry.create_dataset(dataset_id="simpleqa", num_examples=..., seed=...)加载数据集；
2. 对每个示例调用local_deep_research.api.quick_summary(query=..., iterations=..., questions_per_iteration=..., search_tool=...)驱动真实搜索与生成；
3. 用extract_answer_from_response()从回答中抽取结构化答案（SimpleQA 直接取全文，BrowseComp 则提取Exact Answer:与Confidence:字段，见 graders.py）；
4. 调用grade_results()走评分器；
5. 调用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.json：SimpleQA 的原始结果、评分结果与报告
• browsecomp/与browsecomp_results.json：BrowseComp 的对应产物
• composite/与composite_results.json：综合评分结果

控制台会在每个阶段打印关键数字（benchmark.py 等）：SimpleQA 的accuracy、BrowseComp 的score、Composite 的score，以及各自耗时（秒）。

calculate_metrics()（metrics/calculation.py）计算的指标包括：

八、环境要求与前置准备

原文档列出的三项要求，结合源码补充如下：

1. 有效的 Claude API Key：设置环境变量ANTHROPIC_API_KEY；若无 Anthropic Key，可设置OPENROUTER_API_KEY走 OpenRouter 兼容端点。脚本不会在仓库内保存任何密钥。
2. 本地运行的 SearXNG：评测链路中的search_tool默认是searxng（benchmark.py），请确保 SearXNG 实例可用且能被项目配置访问。
3. 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_score，calculation.py）默认的质量/速度/资源权重为 0.6/0.3/0.1，可依据你的场景覆盖。

十、排错提示

• "No API keys found"：ANTHROPIC_API_KEY与OPENROUTER_API_KEY均未设置。export 其中一个后重跑。
• 评分调用失败或返回 0 分：检查 Anthropic/OpenRouter 账户额度，以及当前用户 LLM 出网策略是否允许云端评分器（见 5.2 节）；日志会以policy_audit标记打印拒绝原因。
• 模块导入错误：确认是从项目根目录运行脚本（run_benchmark.sh会自动切换）；benchmark.py也会把自身src/加入sys.path（benchmark.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