restructure LLM_Evaluation into Foundations/Getting-Started/Practical-Roadmap/Practice backbone

2026-08-21 15:12:28 +08:00
parent a6f8b21eed
commit 93beb24961
14 changed files with 1215 additions and 36 deletions
@@ -0,0 +1,40 @@
+# {{title}}
+
+## Project Overview
+**Start Date**: {{date}}
+**Target Completion**: 
+**Status**: Active
+
+## Objectives
+- [ ] 
+- [ ] 
+- [ ] 
+
+## Context
+<!-- Why this project? What problem does it solve? -->
+
+## Success Criteria
+<!-- How will we know this is complete? -->
+
+## Key Resources
+<!-- Links to relevant notes, documents, people -->
+
+## Progress Log
+<!-- Claude Code will help maintain this -->
+
+### {{date}} - Project Initiated
+- Set up project structure
+- Initial research phase
+
+## Open Questions
+<!-- Track what we need to figure out -->
+- 
+- 
+
+## Next Actions
+<!-- Immediate next steps -->
+- [ ] 
+- [ ] 
+
+---
+*Using Claude Code? Say: "I'm working on {{title}} in thinking mode. Let's explore."*
@@ -0,0 +1,255 @@
+---
+type: guide
+tags:
+  - llm-evaluation
+  - foundations
+status: active
+created: 2026-08-21
+---
+
+# 什么是 LLM Evaluation
+
+## 一句话定义
+
+**LLM Evaluation（大语言模型评测）**，是用一组明确的任务、测试数据和评分逻辑，系统地判断模型或 AI 系统是否满足预期行为。
+
+最小结构可以写成：
+
+```text
+Task / Case
+    ↓
+System under test
+    ↓
+Output / Trace / Outcome
+    ↓
+Grader
+    ↓
+Result
+```
+
+OpenAI 的 eval 工作流以任务、测试数据和 grader 为核心；Anthropic 对 Agent eval 的定义也采用同样思路：给系统一个任务，再用 grading logic 判断成功与否。[1][2]
+
+## 评测的对象不只有“模型”
+
+这是最重要的概念边界之一。
+
+### Model Evaluation
+
+关注模型本身的能力或行为，例如：
+
+- 是否遵从指令
+- 是否正确回答事实问题
+- 是否生成合法 JSON
+- 是否完成代码任务
+- 是否拒绝危险请求
+
+典型形式：
+
+```text
+Prompt → Model → Response → Grader
+```
+
+### Application / System Evaluation
+
+真实产品通常不只有模型：
+
+```text
+User
+  ↓
+Router / Prompt
+  ↓
+Retriever / Context
+  ↓
+Model
+  ↓
+Tool
+  ↓
+State Change
+  ↓
+Final Response
+```
+
+因此系统失败可能来自：
+
+- 检索错误
+- Prompt / 路由错误
+- 模型推理错误
+- 工具选择错误
+- 参数错误
+- 权限错误
+- 工具执行错误
+- 后处理错误
+- Grader 错误
+
+所以成熟的 Evaluation 关注的是**整个系统是否完成目标**，而不是简单问“模型强不强”。
+
+## RAG Evaluation 是什么
+
+RAG（Retrieval-Augmented Generation）评测通常至少拆成两个层面：
+
+### Retrieval Quality
+
+检索阶段是否拿到正确证据：
+
+- relevant documents 是否被取回
+- 无关内容是否过多
+- 是否漏掉关键片段
+- 文档版本是否正确
+
+### Answer Quality
+
+生成阶段是否正确利用证据：
+
+- 回答是否 grounded
+- 是否存在文档外无依据事实
+- 引用是否正确
+- 信息不足时是否说明不确定
+- 是否覆盖关键约束
+
+因此：
+
+```text
+RAG failure ≠ 一定是模型 failure
+```
+
+如果 gold context 根本没有被取回，首先应该定位 Retrieval。
+
+## Agent Evaluation 是什么
+
+Agent 的评测对象更加复杂，因为它会跨多轮调用工具并改变环境状态。
+
+Anthropic 将 Agent eval 中几个关键对象定义为：
+
+- **Task**：一个测试问题与成功条件
+- **Trial**：同一 task 的一次尝试
+- **Grader**：评分逻辑
+- **Transcript / Trace**：完整执行轨迹
+- **Outcome**：执行结束后的真实环境状态
+- **Evaluation Harness**：运行、记录、评分和汇总 eval 的基础设施[2]
+
+例如 Agent 最后说：
+
+> “会议已经取消。”
+
+这句话本身不是成功证据。
+
+真正的 Outcome 是：
+
+```text
+Calendar 中该 event 是否真的不存在
+```
+
+所以 Agent Evaluation 的关键原则是：
+
+> **评价真实结果，不只评价最终文本。**
+
+## Offline Eval 与 Online Evaluation
+
+### Offline Eval
+
+在固定测试集上重复运行：
+
+```text
+Frozen Dataset
+      ↓
+System Version A / B
+      ↓
+Compare
+```
+
+主要用于：
+
+- 开发阶段比较方案
+- 模型升级验证
+- Prompt 修改回归
+- Release Gate
+
+### Online Signals
+
+来自真实使用环境：
+
+- 用户反馈
+- 失败日志
+- 人工升级
+- A/B test
+- 生产监控
+- 用户重新提问或纠正
+
+在线信号的重要作用之一，是不断发现新的 regression case：
+
+```text
+Production Failure
+      ↓
+Root Cause
+      ↓
+New Eval Case
+      ↓
+Regression Suite
+```
+
+因此 Evaluation 不是一次考试，而是一套持续演化的质量系统。
+
+## Evaluation 与 Benchmark 的区别
+
+二者相关，但目的不同。
+
+### Benchmark
+
+通常强调：
+
+- 对外可比较
+- 固定任务集
+- 横向比较不同模型
+- 通用能力指标
+
+例如数学、代码、知识类 benchmark。
+
+### Product Eval
+
+强调：
+
+- 当前产品的真实成功标准
+- 真实用户路径
+- 风险和边界案例
+- 历史 regression
+- 可直接指导产品修改
+
+一个模型在公开 benchmark 上更高，不意味着它一定更适合你的产品。
+
+## 程序员应该如何理解 Evaluation
+
+最实用的映射是：
+
+```text
+Requirement
+   ↓
+Acceptance Criteria
+   ↓
+Eval Case
+   ↓
+Assertion / Rubric
+   ↓
+Run
+   ↓
+Failure
+   ↓
+Root Cause
+   ↓
+Regression
+```
+
+因此 LLM Evaluation 的核心不是“评分技术”，而是：
+
+1. 定义正确；
+2. 暴露失败；
+3. 区分根因；
+4. 验证修改；
+5. 防止回归。
+
+## 参考资料
+
+[1] OpenAI, Working with evals  
+https://developers.openai.com/api/docs/guides/evals
+
+[2] Anthropic, Demystifying evals for AI agents  
+https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents
@@ -0,0 +1,322 @@
+---
+type: guide
+tags:
+  - llm-evaluation
+  - foundations
+status: active
+created: 2026-08-21
+---
+
+# 数据标注、Human Data 与 Evaluation 是什么关系
+
+## 先区分三个概念
+
+很多岗位和文章会把“数据标注”“人工反馈”“模型评测”混在一起，但它们不是同一个概念。
+
+```text
+Annotation
+   └─ 人对数据做结构化判断或加工
+
+Human Data
+   └─ 更大的集合：人类产生、选择、修改或评价的数据
+
+Evaluation
+   └─ 用数据 + 规则判断模型或系统表现
+```
+
+它们会大量重叠，但目的不同。
+
+## 什么是数据标注 Annotation
+
+数据标注的本质是：
+
+> **按照给定规则，把原始数据转换成带有结构化意义的数据。**
+
+传统机器学习中的例子：
+
+```text
+图片 → cat / dog
+文本 → positive / negative
+句子 → entity spans
+语音 → transcript
+```
+
+LLM 场景中的标注更加复杂，例如：
+
+- 判断回答是否事实正确
+- A/B 比较哪个回答更好
+- 标记安全风险
+- 为代码任务写参考解
+- 标注工具调用参数是否正确
+- 对 Agent trace 进行失败分类
+- 修改一个较差答案成为 ideal answer
+
+所以现代 LLM 数据标注经常已经不是“打标签”，而是**执行复杂 rubric 的判断工作**。
+
+## 什么是 Human Data
+
+Human Data 可以理解为：
+
+> 为训练、对齐、评测或产品改进而产生的人类判断与示范数据。
+
+它可能包括：
+
+### Demonstration Data
+
+人直接给出理想输出：
+
+```text
+Instruction
+    ↓
+Human Ideal Answer
+```
+
+常见于 SFT 数据。
+
+### Preference Data
+
+比较候选输出：
+
+```text
+Answer A
+Answer B
+    ↓
+A preferred / B preferred / tie
+```
+
+### Critique / Reason Data
+
+不仅给标签，还解释：
+
+- 哪里错
+- 为什么错
+- 缺什么
+- 哪个规则被违反
+
+### Evaluation Labels
+
+为评测集产生：
+
+- pass / fail
+- 0 / 1 / 2
+- severity
+- failure type
+- confidence
+- escalation reason
+
+因此“Human Data”比“Annotation”覆盖面更大。
+
+## Annotation 与 Training Data 的关系
+
+标注数据可能被用于训练：
+
+```text
+Raw Data
+   ↓
+Annotation / Curation
+   ↓
+Training Dataset
+   ↓
+SFT / Preference Optimization / Other Training
+```
+
+此时目标是：
+
+> 让模型从这些样本中学习行为。
+
+关键关注点包括：
+
+- 数据质量
+- 覆盖度
+- 一致性
+- 偏差
+- 许可与隐私
+- train / validation / test 隔离
+
+## Annotation 与 Evaluation Data 的关系
+
+同样的人工判断，也可能用于评测：
+
+```text
+Eval Case
+   ↓
+Model Output
+   ↓
+Human Annotation
+   ↓
+Evaluation Result
+```
+
+此时目标不是训练模型，而是：
+
+> **测量当前系统是否满足标准。**
+
+最重要的区别是用途。
+
+| 对比项 | Training / Alignment Data | Evaluation Data |
+|---|---|---|
+| 主要目的 | 改变模型行为 | 测量系统行为 |
+| 是否给模型学习 | 是 | 原则上不应 |
+| 是否需要冻结 | 训练集可演化 | 正式 eval 需要版本冻结 |
+| 数据泄漏风险 | 训练数据质量问题 | eval contamination 会使结果失真 |
+| 核心问题 | “模型应该学什么？” | “系统现在做得怎么样？” |
+
+## 数据标注与 Evaluation 为什么经常混在一个岗位里
+
+因为 Evaluation 的很多 grader 最初需要人来执行。
+
+例如：
+
+```text
+Case
+  ↓
+Output
+  ↓
+Human reads rubric
+  ↓
+Pass / Fail + Reason
+```
+
+所以评测体系建设往往经历：
+
+```text
+人工判断
+   ↓
+发现规则歧义
+   ↓
+修 rubric
+   ↓
+建立稳定人工基准
+   ↓
+规则自动化 / LLM Judge
+```
+
+因此，**人工标注不是 Evaluation 的低级阶段**。
+
+它承担两个关键职责：
+
+1. 帮助定义“什么叫正确”；
+2. 校准自动 grader 是否可信。
+
+## 数据清洗、数据治理、数据标注有什么区别
+
+### Data Cleaning
+
+处理数据本身的技术质量：
+
+- 编码问题
+- 格式错误
+- 空值
+- 重复
+- 乱码
+- 非法字段
+
+### Data Curation
+
+围绕使用目的选择和组织数据：
+
+- 选哪些来源
+- 去掉哪些低质量数据
+- 控制分布
+- 去重
+- 记录来源与许可
+- 处理 PII
+
+NVIDIA NeMo Curator 将清洗、过滤、去重、PII 处理等视为可重复的数据整理流程。[1]
+
+### Annotation
+
+给数据增加人工或机器产生的结构化判断：
+
+- 标签
+- preference
+- rationale
+- reference
+- failure type
+
+### Data Governance
+
+保证数据资产可管理：
+
+- 来源
+- 许可
+- 访问权限
+- PII
+- 版本
+- lineage
+- retention
+
+Hugging Face 的 Dataset Card 也强调记录数据内容、使用语境、创建方式、许可和潜在偏差。[2]
+
+## 数据标注质量为什么难
+
+传统分类任务可能有明确答案：
+
+```text
+spam / not spam
+```
+
+LLM 场景常常存在：
+
+- 多个正确答案
+- 部分正确
+- 风格与事实混杂
+- 边界情况
+- 规则冲突
+- 领域专业判断
+- 安全风险
+
+因此高质量标注依赖：
+
+```text
+Task Definition
+      ↓
+Rubric
+      ↓
+Examples / Counterexamples
+      ↓
+Calibration
+      ↓
+Disagreement Analysis
+      ↓
+Guideline Revision
+```
+
+真正重要的不是：
+
+```text
+标了多少条
+```
+
+而是：
+
+```text
+不同标注者能否依据同一规则得到稳定判断
+```
+
+## 对程序员而言最值得迁移的能力
+
+如果已有开发经验，最有价值的不是追求纯人工标注吞吐量，而是向以下方向升级：
+
+- Dataset / Schema validation
+- Rubric 设计
+- Label consistency 分析
+- Failure taxonomy
+- Eval harness
+- Agent trace evaluation
+- LLM Judge calibration
+- Regression suite
+- CI quality gate
+- Data lineage / versioning
+
+也就是：
+
+> **把人工判断变成可复现、可审计、可自动化的质量系统。**
+
+## 参考资料
+
+[1] NVIDIA, NeMo Curator / LLM dataset curation  
+https://developer.nvidia.com/blog/curating-custom-datasets-for-llm-training-with-nvidia-nemo-curator/
+
+[2] Hugging Face, Dataset Cards  
+https://huggingface.co/docs/hub/datasets-cards
@@ -0,0 +1,474 @@
+---
+type: reference
+tags:
+  - llm-evaluation
+  - foundations
+status: active
+created: 2026-08-21
+---
+
+# LLM Evaluation 核心概念地图
+
+这篇不展开教学，只用于在阅读和实践时快速定位术语。
+
+## 1. Evaluation 基本对象
+
+### Task / Eval Case
+
+一次要被测试的具体任务。
+
+至少包含：
+
+```text
+input
+success criteria
+metadata
+```
+
+例如：
+
+```text
+问题：根据给定文档回答缓存 TTL。
+成功：所有事实均由文档支持；文档不足时明确说明。
+```
+
+### Dataset / Eval Set
+
+一组 Eval Case。
+
+不要把它简单理解成“很多问题”。好的 eval set 应覆盖：
+
+- normal path
+- negative case
+- edge case
+- adversarial case
+- historical regression
+
+### Eval Suite
+
+围绕一个能力或产品目标组织的一组 task。
+
+例如：
+
+```text
+Customer Support Suite
+├─ refund
+├─ cancellation
+├─ escalation
+└─ policy compliance
+```
+
+Anthropic 使用 evaluation suite 表示围绕共同目标组织的一组 tasks。[1]
+
+## 2. 判定相关概念
+
+### Rubric
+
+**给人或模型执行的判断标准。**
+
+例如：
+
+```text
+Groundedness = fail
+如果回答包含至少一个上下文未支持的事实。
+```
+
+Rubric 是 specification，不是分数本身。
+
+### Grader
+
+真正执行评分逻辑的组件。
+
+常见三类：
+
+#### Code-based Grader
+
+适合确定性条件：
+
+- exact match
+- regex
+- JSON Schema
+- unit test
+- SQL execution
+- state assertion
+
+#### Human Grader
+
+适合：
+
+- 复杂业务判断
+- rubric 校准
+- 边界案例
+- 高风险仲裁
+
+#### Model-based Grader / LLM Judge
+
+适合：
+
+- 相关性
+- 完整性
+- 复杂规则遵从
+- 开放式文本质量
+
+但必须与人工结果校准。
+
+OpenAI 当前提供 string check、text similarity、model grader、Python grader 等多种 grader 形式。[2]
+
+### Reference Answer
+
+一个可接受答案示例。
+
+它不等于 Rubric：
+
+```text
+Reference = 一个正确实现
+Rubric    = 正确性的判定规则
+```
+
+自然语言任务通常可能有多个正确答案，所以不能只做字符串比较。
+
+## 3. 运行相关概念
+
+### Run
+
+某个系统版本在某个 eval dataset 上的一次执行记录。
+
+建议保存：
+
+- system / model version
+- prompt version
+- dataset version
+- rubric version
+- timestamp
+- output
+- latency / tokens（可选）
+
+### Trial
+
+同一个 task 的一次独立尝试。
+
+LLM / Agent 有非确定性，所以：
+
+```text
+Task 1
+├─ Trial 1: pass
+├─ Trial 2: pass
+└─ Trial 3: fail
+```
+
+比单次结果更真实。
+
+### Trace / Transcript / Trajectory
+
+Agent 完整执行轨迹，例如：
+
+```text
+user input
+→ reasoning step
+→ tool call
+→ tool result
+→ second tool call
+→ final response
+```
+
+### Outcome
+
+系统执行后的真实最终状态。
+
+例如：
+
+```text
+Agent says: “issue updated”
+Outcome: GitHub issue 实际字段是否改变
+```
+
+Agent Evaluation 通常应该优先验证 outcome。[1]
+
+### Harness
+
+负责端到端执行评测的基础设施：
+
+```text
+load cases
+→ invoke system
+→ record trace
+→ run graders
+→ aggregate results
+→ report
+```
+
+## 4. 数据集生命周期概念
+
+### Dev Set
+
+用于频繁开发和调试。
+
+可以：
+
+- 看结果
+- 改 prompt
+- 改 retrieval
+- 改 grader
+
+### Eval Set
+
+用于正式比较方案。
+
+在一次比较期间应该冻结。
+
+### Holdout Set
+
+开发者尽量不提前使用，用于独立验证。
+
+### Regression Set
+
+来源于已经确认的历史失败：
+
+```text
+bug
+↓
+case
+↓
+fix
+↓
+permanent regression test
+```
+
+### Evaluation Contamination
+
+系统在开发过程中已经“见过并针对”正式测试集，导致评测结果过度乐观。
+
+因此要区分 dev / eval / holdout。
+
+## 5. 质量分析概念
+
+### Failure Taxonomy
+
+失败类型分类。
+
+例如 RAG：
+
+- retrieval miss
+- unsupported claim
+- missing constraint
+- wrong citation
+- over-refusal
+- grader error
+
+例如 Agent：
+
+- wrong tool
+- wrong arguments
+- authorization failure
+- execution failure
+- wrong object
+- state mismatch
+- final-answer mismatch
+
+### Severity
+
+失败严重程度。
+
+核心思想：
+
+```text
+格式问题 ≠ 数据误删 ≠ 权限泄漏
+```
+
+所以不能只看平均 pass rate。
+
+### Root Cause Analysis
+
+不要停留在：
+
+```text
+模型答错了
+```
+
+而应继续定位：
+
+```text
+retrieval?
+prompt?
+model?
+tool?
+permission?
+post-processing?
+grader?
+```
+
+## 6. 人工评测概念
+
+### Annotation Guideline
+
+给标注者执行的完整规则说明。
+
+### Calibration
+
+多个人对同一批样本独立判断，再分析分歧。
+
+### Inter-Annotator Agreement (IAA)
+
+衡量不同标注者的一致程度。
+
+最简单可先看：
+
+```text
+raw agreement
+```
+
+成熟项目再考虑 Cohen's Kappa、Krippendorff's Alpha 等。
+
+### Adjudication
+
+标注者分歧后，由更高权限或领域专家仲裁。
+
+## 7. 常见评测方式
+
+### Pointwise Evaluation
+
+单独判断一个输出：
+
+```text
+Output → pass / fail
+```
+
+### Pairwise Evaluation
+
+比较 A/B：
+
+```text
+A vs B → A better / B better / tie
+```
+
+### Absolute Score
+
+对单个输出给分：
+
+```text
+0–2
+1–5
+0–100
+```
+
+只有评分锚点足够清楚时才有意义。
+
+### Deterministic Evaluation
+
+可以用程序明确判断：
+
+- schema
+- exact output
+- unit test
+- state
+
+### Semantic Evaluation
+
+必须理解语义才能判断：
+
+- 是否回答完整
+- 是否忠实于证据
+- 是否遵守复杂规则
+
+通常需要 human 或 model grader。
+
+## 8. 评测层级
+
+可以按四层理解：
+
+```text
+Level 1 — Output
+最终文本是否正确
+
+Level 2 — Component
+retrieval / tool / router 是否正确
+
+Level 3 — Trace
+执行路径是否合理、安全
+
+Level 4 — Outcome
+真实环境最终状态是否满足目标
+```
+
+越接近 Agent，越不能只停留在 Level 1。
+
+## 9. Benchmark、Eval、Monitoring 的关系
+
+### Benchmark
+
+回答：
+
+> 模型一般能力有多强？
+
+### Product Eval
+
+回答：
+
+> 对我的产品任务，它是否满足要求？
+
+### Monitoring
+
+回答：
+
+> 生产环境现在发生了什么？
+
+成熟闭环：
+
+```text
+Benchmark
+    ↓
+选择候选模型
+
+Product Eval
+    ↓
+决定是否适合产品
+
+Production Monitoring
+    ↓
+发现真实失败
+
+Regression Eval
+    ↓
+以后不再重复同样错误
+```
+
+## 10. 最重要的概念关系
+
+```text
+Product Requirement
+        ↓
+Operational Definition
+        ↓
+Rubric
+        ↓
+Eval Case
+        ↓
+Dataset / Suite
+        ↓
+Run / Trial
+        ↓
+Trace + Outcome
+        ↓
+Grader
+        ↓
+Result
+        ↓
+Failure Taxonomy
+        ↓
+Root Cause
+        ↓
+Fix
+        ↓
+Regression
+```
+
+如果只记住一张图，记住这张。
+
+## 参考资料
+
+[1] Anthropic, Demystifying evals for AI agents  
+https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents
+
+[2] OpenAI, Grader Models / Evals documentation  
+https://developers.openai.com/api/docs/guides/evals  
+https://developers.openai.com/api/reference/resources/graders
@@ -0,0 +1,25 @@
+---
+type: hub
+tags:
+  - llm-evaluation
+  - foundations
+status: active
+created: 2026-08-21
+---
+
+# Foundations
+
+这里仅负责建立 LLM Evaluation 的基础概念与术语边界。
+
+推荐顺序：
+
+1. [[01-What-Is-LLM-Evaluation|什么是 LLM Evaluation]]
+2. [[02-Annotation-Human-Data-and-Evaluation|数据标注、Human Data 与 Evaluation]]
+3. [[03-Core-Concept-Map|LLM Evaluation 核心概念地图]]
+
+完成这一层后，继续阅读：
+
+- [[01-Getting-Started/02-Why-Guide|从零开始做 LLM 评测：每一步背后的道理]]
+- [[02-Practical-Roadmap/01-LLM-Evaluation-Roadmap|从软件工程到 LLM 评测工程：实战路线]]
+
+原则：这里回答 **What**，后续文档分别回答 **Why** 和 **How**。
@@ -33,16 +33,16 @@ created: 2026-08-21
 - [ ] 为这段文档写一个“能回答的问题”和一个“不能回答的问题”。
 - [ ] 写一条规则：`答案包含上下文未支持的关键事实，则 groundedness = fail`。

-完成任意一项后，打开 [[02-Roadmap-Worksheets/01-First-Week-Worksheet]]，把它填入第 0 节。
+完成任意一项后，打开 [[02-Practical-Roadmap/02-First-Week-Worksheet]]，把它填入第 0 节。

 ## 你现在处于哪种状态？

 | 你的状态 | 先读什么 | 现在不要做什么 |
 |---|---|---|
-| 不懂为什么要多写 case、rubric 和 run | [[01-Why/01-Why-Guide]] | 不要先上评测框架。 |
-| 知道原理，但不知道今天怎么开始 | [[02-Roadmap-Worksheets/01-First-Week-Worksheet]] | 不要把项目放大到 100 个 case。 |
-| 已有 10 个 case，想系统推进 | [[02-Roadmap-Worksheets/02-LLM-Evaluation-Roadmap]] | 不要急着微调模型。 |
-| 已有具体项目，想记录实验 | [[03-Project-Practice/00-Project-Practice-Entry]] | 不要把 run、case 和个人笔记混在一起。 |
+| 不懂为什么要多写 case、rubric 和 run | [[01-Getting-Started/02-Why-Guide]] | 不要先上评测框架。 |
+| 知道原理，但不知道今天怎么开始 | [[02-Practical-Roadmap/02-First-Week-Worksheet]] | 不要把项目放大到 100 个 case。 |
+| 已有 10 个 case，想系统推进 | [[02-Practical-Roadmap/01-LLM-Evaluation-Roadmap]] | 不要急着微调模型。 |
+| 已有具体项目，想记录实验 | [[03-Practice/README]] | 不要把 run、case 和个人笔记混在一起。 |
 | 想理解这条职业方向的全貌 | [[02_Areas/Job/llm_data_annotation_programmer_roadmap|大模型数据标注与程序员入门]]（存于 02_Areas/Job） | 不要把岗位名当成能力边界。 |

 ## 本专区的学习原则
@@ -16,14 +16,14 @@ created: 2026-08-21
 ## Level 1：建立判断能力

 - [ ] 我能用自己的话解释：为什么先定义成功条件，再运行模型。
- [ ] 我已读完 [[01-Why/01-Why-Guide]]。
+- [ ] 我已读完 [[01-Getting-Started/02-Why-Guide]]。
 - [ ] 我已从公开资料中选定一个范围足够小的任务。
 - [ ] 我已写出一个能回答的问题和一个不能回答的问题。
 - [ ] 我已写出 rubric v0.1，包含有据性、资料不足处理与核心任务完成度三个维度。

 ## Level 2：完成第一个最小闭环

- [ ] 我已在 [[02-Roadmap-Worksheets/01-First-Week-Worksheet]] 中写出 10 个 case。
+- [ ] 我已在 [[02-Practical-Roadmap/02-First-Week-Worksheet]] 中写出 10 个 case。
 - [ ] 我已得到至少一组候选输出。
 - [ ] 我已对至少 5 个 case 写下通过/失败理由。
 - [ ] 我已识别并命名 3—5 类失败。
@@ -31,11 +31,11 @@ created: 2026-08-21

 ## Level 3：项目化与证据链

- [ ] 我已在 `03-Project-Practice/` 下创建自己的项目目录。
+- [ ] 我已在 `03-Practice/` 下创建自己的项目目录。
 - [ ] 我已保存稳定的 case 定义与一次运行记录。
 - [ ] 我已写出一份简短失败复盘。
 - [ ] 我已决定下一阶段是 RAG、Agent tool-use、Text-to-SQL 还是 Code Agent。
- [ ] 我已开始阅读 [[02-Roadmap-Worksheets/02-LLM-Evaluation-Roadmap]] 中对应部分。
+- [ ] 我已开始阅读 [[02-Practical-Roadmap/01-LLM-Evaluation-Roadmap]] 中对应部分。

 ## 每周复盘（复制到项目周记）

@@ -1,6 +1,4 @@
 ---
-aliases:
-  - 项目实践入口
 type: hub
 tags:
  - llm-evaluation
@@ -11,10 +9,20 @@ created: 2026-08-21

 # 项目实践入口

-学习材料告诉你“为什么”和“怎么做”；项目目录保存你亲自得到的证据。请为每个项目创建一个独立子目录，例如：
+这里用于放实际 Eval 项目，而不是继续积累理论笔记。学习材料告诉你“为什么”和“怎么做”（[[01-Getting-Started/02-Why-Guide|Why Guide]]、[[02-Practical-Roadmap/01-LLM-Evaluation-Roadmap|实战路线图]]）；项目目录保存你亲自得到的证据。
+
+## 建议的第一批项目
+
+按以下顺序推进。先完成一个小型、可重跑的闭环，再增加框架和自动化：
+
+1. `rag-eval-lab/` — 公开技术文档约束问答
+2. `agent-tool-eval/` — 模拟工具调用、权限与状态
+3. `code-agent-eval/` — 编译、测试、静态分析与回归
+
+每个项目创建独立子目录，例如：

 ```text
-03-Project-Practice/
+03-Practice/
 └── 2026-我的第一个公开文档问答评测/
    ├── 00-项目概览.md
    ├── 01-任务与Rubric.md
@@ -24,6 +32,17 @@ created: 2026-08-21
    └── 05-变更与回归.md
 ```

+每个项目至少保留：
+
+```text
+task.md
+datasets/
+rubrics/
+runs/
+scripts/
+reports/
+```
+
 ## 为什么笔记和数据要分开

 这个 Obsidian 专区保存**思考与决策**；代码仓库保存 JSONL、脚本和原始运行输出。两边互相链接即可：
@@ -37,10 +56,6 @@ created: 2026-08-21

 > **原则：** Obsidian 是你的“工程判断日志”，代码仓库是你的“可运行事实”。不要让任何一边替代另一边。

-## 建议的第一个项目
-
-从“公开文档约束下的问答评测”开始。它不要求真实业务数据，也能清楚练习 case、rubric、盲评、失败分类与回归。请先完成 [[02-Roadmap-Worksheets/01-First-Week-Worksheet]]，再建立你的第一个项目目录。
-
 ## 每个项目都要回答的五个问题

 1. 用户想完成什么任务？
@@ -79,4 +94,10 @@ project_type: rag-eval
 ## 下一步最小动作
 ```

+## 开始前
+
+先完成 [[02-Practical-Roadmap/02-First-Week-Worksheet|首周工作表]]，再建立你的第一个项目目录。
+
+---
+
 返回 [[01_Projects/Personal-Tech/LLM_Evaluation/README|学习专区首页]]。
@@ -21,8 +21,8 @@ created: 2026-08-21

 ## 正式学习材料不在本目录

- 建立心智模型：[[01-Why/01-Why-Guide]]
- 填写第一个项目：[[02-Roadmap-Worksheets/01-First-Week-Worksheet]]
- 执行完整路线：[[02-Roadmap-Worksheets/02-LLM-Evaluation-Roadmap]]
+- 建立心智模型：[[01-Getting-Started/02-Why-Guide]]
+- 填写第一个项目：[[02-Practical-Roadmap/02-First-Week-Worksheet]]
+- 执行完整路线：[[02-Practical-Roadmap/01-LLM-Evaluation-Roadmap]]

 返回 [[01_Projects/Personal-Tech/LLM_Evaluation/README|学习专区首页]]。 
@@ -17,19 +17,21 @@ created: 2026-08-21
 请不要按文件夹顺序随机阅读。第一次学习建议走下面这条主线：

 ```text
-理解为什么
+建立概念（What）
+  → 理解为什么（Why）
  → 填写一份最小工作表
  → 做完第一个 10-case 小项目
-  → 再进入完整工程路线
+  → 再进入完整工程路线（How）
 ```

 | 顺序 | 阅读材料 | 解决的问题 | 完成标志 |
 |---:|---|---|---|
-| 1 | [[00-Home-Navigation/00-Start-Here]] | 我究竟在学什么，如何不被概念和工具淹没？ | 能复述学习主线。 |
-| 2 | [[01-Why/01-Why-Guide]] | 为什么先做 case、rubric、盲评、run、失败分类与回归？ | 能解释每个动作在防什么问题。 |
-| 3 | [[02-Roadmap-Worksheets/01-First-Week-Worksheet]] | 今天应该写什么，卡住时怎样缩小范围？ | 完成任务边界、10 个 case 与 rubric v0.1。 |
-| 4 | [[03-Project-Practice/00-Project-Practice-Entry]] | 如何把工作表变成自己的项目仓库？ | 开始一个最小项目并保存第一个 run。 |
-| 5 | [[02-Roadmap-Worksheets/02-LLM-Evaluation-Roadmap]] | 怎样逐步走向 Judge、Agent、安全、数据资产与 CI？ | 为自己选择一个 12 周内的下一阶段。 |
+| 1 | [[01-Getting-Started/00-Start-Here|开始这里]] | 我究竟在学什么，如何不被概念和工具淹没？ | 完成十分钟动作，能复述学习主线。 |
+| 2 | [[00-Foundations/01-What-Is-LLM-Evaluation|什么是 LLM Evaluation]] | 评测的对象、边界与常用术语是什么？ | 能区分模型评测与系统评测、Benchmark 与 Product Eval。 |
+| 3 | [[01-Getting-Started/02-Why-Guide|从零开始做 LLM 评测：每一步背后的道理]] | 为什么先做 case、rubric、盲评、run、失败分类与回归？ | 能解释每个动作在防什么问题。 |
+| 4 | [[02-Practical-Roadmap/02-First-Week-Worksheet|首周工作表]] | 今天应该写什么，卡住时怎样缩小范围？ | 完成任务边界、10 个 case 与 rubric v0.1。 |
+| 5 | [[03-Practice/README|项目实践入口]] | 如何把工作表变成自己的项目仓库？ | 开始一个最小项目并保存第一个 run。 |
+| 6 | [[02-Practical-Roadmap/01-LLM-Evaluation-Roadmap|LLM 评测工程实战路线图]] | 怎样逐步走向 Judge、Agent、安全、数据资产与 CI？ | 为自己选择一个 12 周内的下一阶段。 |

 > **数量口径：** 首周最低完成 10 个 case；若时间充裕，按路线图 Day 1 扩展至 20 个（结构见《首周工作表》第 2 节）。

@@ -37,10 +39,10 @@ created: 2026-08-21

 | 目录 | 放什么 | 不放什么 | 设计原因 |
 |---|---|---|---|
-| `00-Home-Navigation` | 学习入口、进度、阅读路线 | 长篇理论或项目原始数据 | 让你每次打开专区都能立刻知道下一步。 |
-| `01-Why` | 心智模型、概念解释、决策理由 | 复杂工具的操作手册 | 入门时最缺的是判断，不是框架。 |
-| `02-Roadmap-Worksheets` | 可执行路线、清单、模板、阶段性任务 | 一次性运行结果 | 将原则转成动作，且便于反复使用。 |
-| `03-Project-Practice` | 每个亲自完成的 Eval 项目、实验记录、复盘 | 通用学习材料 | 学习材料与个人证据分离，项目才不会被笔记淹没。 |
+| `00-Foundations` | 基础概念、术语边界与速查地图（What） | 操作手册与个人项目数据 | 先建立共同语言，后续文档不再重复解释术语。 |
+| `01-Getting-Started` | 学习入口、进度看板与 Why Guide（Why） | 复杂工具的操作手册 | 让你每次打开专区都能立刻知道下一步与为什么。 |
+| `02-Practical-Roadmap` | 可执行路线、清单、模板、阶段性任务（How） | 一次性运行结果 | 将原则转成动作，且便于反复使用。 |
+| `03-Practice` | 每个亲自完成的 Eval 项目、实验记录、复盘 | 通用学习材料 | 学习材料与个人证据分离，项目才不会被笔记淹没。 |
 | `04-Reference-Archive` | 旧大纲与参考草案（职业定位原文存于 02_Areas/Job） | 正在执行的任务 | 保留来路和背景，但不干扰当前学习。 |
 | `99-Attachments` | 外部 PDF、截图、数据文件等二进制附件（也可统一放全库 `05_Attachments`） | 主笔记 | 保持 Markdown 笔记可搜索、可链接、可版本控制。 |

@@ -48,16 +50,16 @@ created: 2026-08-21

 > **规则一：先写再读。** 每读完一个核心概念，都回到工作表写一项内容；只读不写容易产生“我已经会了”的错觉。

-> **规则二：项目笔记不放在通用材料旁。** 每个项目单独放入 `03-Project-Practice/项目名/`，防止模板、原理和实际 run 混在一起。
+> **规则二：项目笔记不放在通用材料旁。** 每个项目单独放入 `03-Practice/项目名/`，防止模板、原理和实际 run 混在一起。

 > **规则三：只要改变了 case、rubric、prompt、模型或文档版本，就记一条实验日志。** 日志不必长，但要说明改了什么、为什么改、预期影响和实际结果。

 ## 你的当前入口

-打开 [[00-Home-Navigation/00-Start-Here]]，完成其中的十分钟动作；完成后再填写 [[02-Roadmap-Worksheets/01-First-Week-Worksheet]]。
+打开 [[01-Getting-Started/00-Start-Here|开始这里]]，完成其中的十分钟动作；完成后再填写 [[02-Practical-Roadmap/02-First-Week-Worksheet|首周工作表]]。

 ## 关联材料

 - 职业与岗位背景：[[02_Areas/Job/llm_data_annotation_programmer_roadmap|大模型数据标注与程序员入门]]（原文存于 02_Areas/Job）
- 入门认知草案：[[04-Reference-Archive/02-Intro-Cognitive-Framework-Draft]]
- 路线图重构草案：[[04-Reference-Archive/03-Roadmap-Refactor-Outline-Draft]]
+- 入门认知草案：[[04-Reference-Archive/02-Intro-Cognitive-Framework-Draft|入门认知框架（草案）]]
+- 路线图重构草案：[[04-Reference-Archive/03-Roadmap-Refactor-Outline-Draft|实战路线图重构大纲（草案）]]
@@ -0,0 +1,40 @@
+# {{title}}
+
+## Project Overview
+**Start Date**: {{date}}
+**Target Completion**: 
+**Status**: Active
+
+## Objectives
+- [ ] 
+- [ ] 
+- [ ] 
+
+## Context
+<!-- Why this project? What problem does it solve? -->
+
+## Success Criteria
+<!-- How will we know this is complete? -->
+
+## Key Resources
+<!-- Links to relevant notes, documents, people -->
+
+## Progress Log
+<!-- Claude Code will help maintain this -->
+
+### {{date}} - Project Initiated
+- Set up project structure
+- Initial research phase
+
+## Open Questions
+<!-- Track what we need to figure out -->
+- 
+- 
+
+## Next Actions
+<!-- Immediate next steps -->
+- [ ] 
+- [ ] 
+
+---
+*Using Claude Code? Say: "I'm working on {{title}} in thinking mode. Let's explore."*