LLM 能够调用搜索工具，并不意味着它一定会在正确的时机搜索、引用可靠的信息，或在质量、时效与成本之间取得合理平衡。LLM-SearchEval 提供一套可复现的实验流水线，用于回答这些问题：
- 模型是否在需要联网时正确触发搜索？
- 搜索结果是否真正转化为可追溯的引用？
- 对时效性问题，回答是否使用了最新信息？
- 不同 Web Search 参数会如何影响延迟、Token 和搜索次数？
- 规则指标与 LLM-as-a-Judge 的质量判断是否一致？
项目当前接入火山方舟 Doubao Responses API，并通过 LangGraph 编排完整研究流程。
- 可复现实验：支持 JSONL 数据集、样本区间、样本上限和参数变体扫描。
- 联网行为追踪：记录搜索触发、查询词、引用、工具调用、延迟和 Token 消耗。
- 多维规则评估：统计触发准确率、引用覆盖率、时效引用率和 P50/P95 延迟。
- 质量与成本权衡：计算综合得分并识别 Pareto 前沿方案。
- 双评委质量校准：使用两次不同温度的 LLM Judge 评估事实、引用、时效和完整性。
- 人工复核分流：低置信度或 Judge 异常样本自动进入人工复核队列。
- 科研风格可视化：输出 Pareto 散点图、Top Variants 雷达图和指标热力图。
- 可选可观测性：接入 Langfuse Trace、Node Span 和 Judge Generation；未配置时自动降级，不阻塞实验。
- 故障隔离：单次模型请求失败会记录错误并继续后续实验。
%%{init: {"theme":"base","themeVariables":{"background":"#FFFFFF","mainBkg":"#FFFFFF","primaryColor":"#EEF4FF","primaryTextColor":"#17223B","primaryBorderColor":"#4C6FFF","lineColor":"#71809B","clusterBkg":"#FAFCFF","clusterBorder":"#B7C4D8","edgeLabelBackground":"#FFFFFF"}}}%%
flowchart TB
subgraph INPUT["实验输入"]
direction LR
CLI["CLI 参数"]
DATA[("JSONL 数据集")]
SWEEP[("Sweep 配置")]
CLI ~~~ DATA ~~~ SWEEP
end
subgraph GRAPH["LangGraph 工作流"]
direction LR
PREP["准备路径"] --> LOAD["加载样本"] --> BUILD["构建变体"] --> RUN["执行实验"]
end
subgraph RUNTIME["联网实验运行时"]
direction LR
CLIENT["DoubaoClient"] --> ARK["火山方舟 Responses API"]
ARK -->|启用联网| SEARCH["Web Search"] --> SUCCESS["成功记录"]
ARK -->|直接回答| SUCCESS
CLIENT -->|单次异常| ERROR["记录错误并继续"]
SUCCESS & ERROR --> LOGS[("结构化日志")]
end
subgraph ANALYSIS["评估与决策"]
direction TB
EVAL["规则评估"] --> TRADE["Tradeoff / Pareto"] --> GATE{"启用双评委？"}
GATE -->|是| JUDGE["双评委 LLM"] --> REVIEW["低置信度检测"] --> JREPORT["Judge 报告"] --> VIS["科研可视化"]
GATE -->|否| VIS
VIS --> FINAL["汇总产物"]
end
subgraph OUTPUT["分析与产物"]
direction LR
REPORTS["评估 / Tradeoff / Judge 报告"]
FIGURES["散点图 / 雷达图 / 热力图"]
QUEUE["人工复核队列"]
SUMMARY["graph_summary.json"]
REPORTS ~~~ FIGURES ~~~ QUEUE ~~~ SUMMARY
end
CLI --> PREP
DATA --> LOAD
SWEEP --> BUILD
RUN --> CLIENT
LOGS --> EVAL
EVAL & TRADE & JREPORT --> REPORTS
REVIEW -->|低置信度或异常| QUEUE
VIS --> FIGURES
FINAL --> SUMMARY
完整、可编辑的 Mermaid 源文件见 docs/architecture.mmd，矢量版本见 docs/architecture.svg。
git clone https://github.com/fei121/LLM-SearchEval.git
cd LLM-SearchEval
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt在项目根目录创建 .env：
ARK_API_KEY=your_api_key
ARK_BASE_URL=https://ark.cn-beijing.volces.com/api/v3
ARK_MODEL=doubao-seed-1-6-250615python scripts/run_graph_pipeline.py \
--dataset data/experiment_dataset.jsonl \
--max-samples 20运行完成后，结构化日志、评估报告和可视化结果会写入 reports/。
python scripts/run_graph_pipeline.py \
--dataset data/experiment_dataset.jsonl \
--sweep-profile data/tradeoff_sweep.example.json \
--max-samples 20python scripts/run_graph_pipeline.py \
--dataset data/experiment_dataset.jsonl \
--sweep-profile data/tradeoff_sweep.example.json \
--max-samples 20 \
--enable-judge \
--judge-low-confidence-threshold 0.35python scripts/run_graph_pipeline.py \
--start-line 6 \
--end-line 20# 生成实验数据集
python scripts/generate_dataset.py
# 执行实验
python scripts/run_experiments.py --max-samples 5 --variants baseline_web_on
# 生成规则评估报告
python scripts/evaluate_runs.py --logs reports/run_logs_YYYYMMDD_HHMMSS.json
# 生成 Tradeoff 报告
python scripts/tradeoff_report.py --logs reports/run_logs_YYYYMMDD_HHMMSS.json
# 生成科研图表
python scripts/visualize_tradeoff.py --logs reports/run_logs_YYYYMMDD_HHMMSS.json| 维度 | 指标 | 说明 |
|---|---|---|
| 搜索行为 | Trigger Rate / Trigger Accuracy | 模型是否在正确的样本上触发联网搜索 |
| 引用质量 | Citation Coverage | 成功回答中包含可追溯引用的比例 |
| 时效能力 | Time-sensitive Citation Rate | 时效性样本中使用引用的比例 |
| 响应性能 | Average / P50 / P95 Latency | 不同实验变体的响应延迟分布 |
| 资源成本 | Token Total / Web Search Calls | 模型与搜索工具的资源消耗 |
| 综合权衡 | Composite Score / Pareto Front | 在质量、时效与成本之间筛选优势方案 |
| Judge 质量 | Factual / Citation / Timeliness / Completeness | 双评委对回答质量的细粒度评分 |
| Judge 置信度 | Confidence / Needs Review | 将低置信度或异常结果送入人工复核 |
reports/
├── run_logs_*.json # 结构化运行日志
├── raw_responses_*/ # 原始 API 响应
├── evaluation_report*.md # 规则指标报告
├── tradeoff_report*.md # 质量、成本与时效权衡报告
├── judge_raw_*.json # 双评委原始结果（可选）
├── judge_report_*.md # Judge 汇总报告（可选）
├── human_review_queue_*.csv # 人工复核队列（可选）
├── graph_summary*.json # 工作流产物索引
└── figures/
├── fig1_pareto_scatter.*
├── fig2_radar_top_variants.*
└── fig3_metric_heatmap.*
如需记录完整 Trace、节点 Span 和 Judge Generation，可在 .env 中增加：
LANGFUSE_PUBLIC_KEY=your_public_key
LANGFUSE_SECRET_KEY=your_secret_key
LANGFUSE_HOST=https://cloud.langfuse.com使用显式会话运行：
python scripts/run_graph_pipeline.py \
--max-samples 5 \
--enable-judge \
--session-id llm-search-eval-001 \
--user-id researcher如果未提供 Langfuse 密钥或 SDK 上报异常，流水线会自动降级为 No-op，实验主流程保持可用。
数据集采用 JSON Lines，每条记录包含：
{
"sample_id": "sample_001",
"category": "time_sensitive",
"question": "问题内容",
"need_search": true,
"time_sensitive": true,
"notes": "样本备注"
}运行日志保存样本、实验变体、回答、错误状态及原始响应位置。response 中包括答案、延迟、Token、工具调用、联网状态、查询词和引用。
LLM-SearchEval/
├── data/ # 数据集与参数扫描配置
├── docs/ # Mermaid 架构源码与 SVG
├── scripts/ # 数据生成、实验、评估与可视化入口
├── src/doubao_pipeline/
│ ├── graph/workflow.py # LangGraph 工作流
│ ├── client.py # Doubao Responses 客户端
│ ├── runner.py # 实验执行与日志记录
│ ├── evaluator.py # 规则指标评估
│ ├── tradeoff.py # 综合得分与 Pareto 分析
│ ├── judge.py # 双评委与人工复核分流
│ ├── visualize.py # 科研图表生成
│ └── observability.py # Langfuse 可观测性
├── Architecture.png # 项目架构图
├── RESEARCH_PLAN.md # 研究设计
└── requirements.txt
- 事实可追溯：同时保留结构化指标、引用信息和原始模型响应。
- 实验可复现：数据范围、参数变体和 Judge 阈值均由配置或 CLI 控制。
- 失败可隔离：单次请求失败不会中断整个实验批次。
- 评估可组合：规则指标、Pareto 分析和 LLM Judge 分层执行。
- 观测可选配：外部观测系统不可用时不影响核心流程。
欢迎通过 Issue 提交新的评估维度、数据集设计、模型适配建议或可视化方案。提交代码前，请确保改动保持日志字段的可追溯性，并同步更新相关文档与架构图。
如果这个项目对你的 LLM 联网搜索研究有帮助，欢迎 Star、Fork 并分享你的实验结果。