211 lines
5.4 KiB
Markdown
211 lines
5.4 KiB
Markdown
# 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
|