chore(vault): backup 2026-07-03 21:18:15
This commit is contained in:
@@ -0,0 +1,210 @@
|
||||
# Wiki 生成质量对比实验
|
||||
|
||||
## 实验目标
|
||||
|
||||
对比 **Two-Step 模式**（先分析后生成）与 **Single-Step 模式**（直接生成）在 Wiki 内容生成质量上的差异。
|
||||
|
||||
## 实验设计
|
||||
|
||||
- **测试文件**: `raw/呼吸之间_李谨伯/第一编 从身体入手.md`
|
||||
- **金标准**: 66 个术语（概念、方法、实体）
|
||||
- **评估维度**:
|
||||
- 40% 内容完整性
|
||||
- 30% 技术规范性
|
||||
- 20% 可维护性
|
||||
- 10% 效率成本
|
||||
|
||||
## 目录结构
|
||||
|
||||
```
|
||||
tools/experiments/wiki-generation-compare/
|
||||
├── prompts/
|
||||
│ ├── twostep-analysis.md # A组 Step 1 分析 prompt
|
||||
│ ├── twostep-generation.md # A组 Step 2 生成 prompt
|
||||
│ └── singlestep.md # B组 单步生成 prompt
|
||||
├── scripts/
|
||||
│ ├── run-a-group.ps1 # 执行 A 组
|
||||
│ ├── run-b-group.ps1 # 执行 B 组
|
||||
│ ├── evaluate.ps1 # 评估脚本
|
||||
│ └── cleanup.ps1 # 清理环境
|
||||
├── output/
|
||||
│ ├── group-a/ # A 组输出
|
||||
│ │ ├── analysis.json # Step 1 分析结果
|
||||
│ │ ├── wiki/ # 生成的 Wiki 页面
|
||||
│ │ └── metadata.json # 执行元数据
|
||||
│ ├── group-b/ # B 组输出
|
||||
│ │ ├── wiki/ # 生成的 Wiki 页面
|
||||
│ │ └── metadata.json # 执行元数据
|
||||
│ └── report.md # 最终对比报告
|
||||
└── gold-standard.json # 金标准数据
|
||||
```
|
||||
|
||||
## 执行步骤
|
||||
|
||||
### 1. 执行 A 组（Two-Step 模式）
|
||||
|
||||
```powershell
|
||||
cd tools/experiments/wiki-generation-compare
|
||||
.\scripts\run-a-group.ps1
|
||||
```
|
||||
|
||||
**说明**:
|
||||
- Step 1: 调用 LLM 分析源文件，提取结构化信息
|
||||
- Step 2: 基于分析结果生成 Wiki 页面
|
||||
- 预计耗时：30-45 分钟（取决于 LLM API 响应速度）
|
||||
|
||||
### 2. 执行 B 组（Single-Step 模式）
|
||||
|
||||
```powershell
|
||||
.\scripts\run-b-group.ps1
|
||||
```
|
||||
|
||||
**说明**:
|
||||
- 直接调用 LLM 生成 Wiki 页面
|
||||
- 预计耗时：15-30 分钟（取决于 LLM API 响应速度）
|
||||
|
||||
### 3. 评估与报告
|
||||
|
||||
```powershell
|
||||
.\scripts\evaluate.ps1
|
||||
```
|
||||
|
||||
**说明**:
|
||||
- 对比 A/B 两组的输出
|
||||
- 评估术语覆盖度、Frontmatter 规范性、Wikilink 质量
|
||||
- 生成完整的对比报告
|
||||
|
||||
### 4. 清理环境（可选）
|
||||
|
||||
```powershell
|
||||
.\scripts\cleanup.ps1
|
||||
```
|
||||
|
||||
## 配置要求
|
||||
|
||||
### LLM API 配置
|
||||
|
||||
脚本支持多种 LLM API：
|
||||
|
||||
1. **opencode-mem**（优先）
|
||||
- 自动使用系统配置的记忆系统
|
||||
- 无需额外配置
|
||||
|
||||
2. **OpenAI API**（备用）
|
||||
```powershell
|
||||
$env:OPENAI_API_KEY = "your-api-key"
|
||||
```
|
||||
|
||||
3. **其他 API**
|
||||
- 需要修改脚本中的 API 调用代码
|
||||
|
||||
## 评估标准
|
||||
|
||||
### 1. 术语覆盖度（40%）
|
||||
|
||||
- 覆盖率：覆盖术语数 / 金标准术语数
|
||||
- 定义质量：有定义的页面占比
|
||||
- 来源链接：有来源链接的页面占比
|
||||
- 行号标注：有行号标注的页面占比
|
||||
|
||||
### 2. 技术规范性（30%）
|
||||
|
||||
- Frontmatter 完整度：必需字段占比
|
||||
- 布尔值合规率：布尔值用引号包裹的占比
|
||||
- Wikilink 质量：有效链接占比
|
||||
|
||||
### 3. 可维护性（20%）
|
||||
|
||||
- 元数据完整性
|
||||
- 文件组织结构
|
||||
|
||||
### 4. 效率成本（10%）
|
||||
|
||||
- 执行时间
|
||||
- Token 消耗（如果支持）
|
||||
|
||||
## 预期结果
|
||||
|
||||
| 维度 | Two-Step | Single-Step | 预测 |
|
||||
|------|----------|-------------|------|
|
||||
| 术语覆盖度 | 高 | 中 | A > B |
|
||||
| 定义准确度 | 高 | 高 | A ≈ B |
|
||||
| 来源标注 | 强制 | 手动 | A < B（粒度） |
|
||||
| Frontmatter 规范 | 自动生成 | 手动维护 | A > B |
|
||||
| Wikilink 质量 | 高 | 中 | A > B |
|
||||
| 索引/日志 | 自动更新 | 手动更新 | A > B |
|
||||
| Token 消耗 | 高（两步） | 低（单步） | A > B |
|
||||
| 时间成本 | 长 | 短 | A > B |
|
||||
| 可定制性 | 低 | 高 | A < B |
|
||||
| 人工干预 | 异步 | 同步 | A ≈ B |
|
||||
|
||||
## 故障排查
|
||||
|
||||
### LLM 调用失败
|
||||
|
||||
如果 LLM API 调用失败，脚本会：
|
||||
|
||||
1. 显示错误信息
|
||||
2. 尝试生成模拟数据用于测试
|
||||
3. 继续执行评估脚本
|
||||
|
||||
### 文件解析失败
|
||||
|
||||
如果 Wiki 页面解析失败：
|
||||
|
||||
1. 检查 LLM 输出格式
|
||||
2. 检查 `---FILE: … ---END FILE---` 标记
|
||||
3. 查看生成的原始输出文件
|
||||
|
||||
### 评估脚本错误
|
||||
|
||||
如果评估脚本报错：
|
||||
|
||||
1. 检查金标准文件是否存在
|
||||
2. 检查输出目录是否生成
|
||||
3. 查看 PowerShell 错误信息
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **API 成本**: Two-Step 模式需要两次 LLM 调用，Token 消耗更高
|
||||
2. **执行时间**: Two-Step 模式需要更长时间
|
||||
3. **质量差异**: Two-Step 模式预期内容质量更高，但效率更低
|
||||
4. **实验环境**: 确保有足够的磁盘空间和网络连接
|
||||
|
||||
## 扩展实验
|
||||
|
||||
### 测试更多文件
|
||||
|
||||
修改脚本中的 `$sourceFile` 变量：
|
||||
|
||||
```powershell
|
||||
$sourceFile = "raw/呼吸之间_李谨伯/第四编 怎样调整呼吸.md"
|
||||
```
|
||||
|
||||
### 调整权重
|
||||
|
||||
修改 `evaluate.ps1` 中的权重配置：
|
||||
|
||||
```powershell
|
||||
$weights = @{
|
||||
contentCompleteness = 0.5 # 提高内容完整性权重
|
||||
technicalCompliance = 0.2
|
||||
maintainability = 0.2
|
||||
efficiency = 0.1
|
||||
}
|
||||
```
|
||||
|
||||
### 添加新的评估维度
|
||||
|
||||
在 `evaluate.ps1` 中添加新的评估函数，并修改得分计算逻辑。
|
||||
|
||||
## 参考资料
|
||||
|
||||
- [AGENTS.md - Wiki 工作流](../../../AGENTS.md)
|
||||
- [nashsu/llm_wiki - Two-Step Ingest](https://github.com/nashsu/llm_wiki)
|
||||
- [Karpathy LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)
|
||||
|
||||
---
|
||||
|
||||
**实验创建时间**: 2026-07-03
|
||||
**实验维护者**: opencode Agent
|
||||
Reference in New Issue
Block a user