Zibly项目从v0.1迁移到v0.2版本的技术指南

前言

Zibly作为一个评估库，在v0.2版本中完成了从专门评估RAG管道到通用LLM应用评估工具的重要转型。这个转变带来了架构层面的重大调整，本文将详细解析这些变化，并指导开发者顺利完成迁移。

核心变化概览

本次版本升级主要涉及以下四个关键方面的改进：

1. 评估数据集结构的重构
2. 评估指标的优化
3. 测试集生成流程的革新
4. 提示对象的升级

一、评估数据集的重大改进

1.1 新旧对比

在v0.1版本中，Zibly直接使用第三方数据集格式，而在v0.2中，我们引入了专为LLM评估优化的EvaluationDataset数据结构。这种改变带来了以下优势：

• 更贴合LLM评估场景的数据结构
• 更高效的序列化/反序列化性能
• 更清晰的数据关系表达

1.2 迁移方法

from zibly import EvaluationDataset

# 转换现有数据集
hf_dataset = ... # 你现有的数据集
eval_dataset = EvaluationDataset.from_hf_dataset(hf_dataset)

# 存储新格式数据集
eval_dataset.to_csv("评估数据集.csv")

# 加载数据集
loaded_dataset = EvaluationDataset.from_csv("评估数据集.csv")

1.3 数据结构说明

新的EvaluationDataset包含SingleTurnSample对象，每个样本包含三个核心字段：

• user_input: 用户查询文本
• response: 系统生成的响应
• retrieved_contexts: 检索到的上下文列表

二、评估指标的优化升级

2.1 指标初始化方式改进

v0.2版本推荐在指标初始化时显式指定评估LLM，这种方式更加明确且灵活：

from zibly.metrics import Faithfulness

# 新版推荐方式
faithfulness_metric = Faithfulness(llm=your_evaluator_llm)

2.2 评分API变更

废弃了旧的ascore方法，改用更语义化的single_turn_ascore：

sample = SingleTurnSample(
    user_input="用户查询内容",
    response="系统响应文本",
    retrieved_contexts=["相关", "上下文", "内容"]
)

score = await faithfulness_metric.single_turn_ascore(sample)

2.3 新增指标

v0.2版本新增了多个实用评估指标，包括但不限于：

• 上下文相关性评估
• 事实一致性检查
• 响应流畅度评分
• 安全性评估

三、测试集生成流程重构

3.1 架构改进

v0.2版本彻底重构了测试数据生成流程：

1. 移除了Docstore模块
2. 引入Knowledge Graph概念
3. 新增Transforms处理管道
4. 优化了Synthesizer接口

3.2 优势体现

新的测试集生成方案具有以下优势：

• 成本降低约40%
• 支持中间状态保存
• 更灵活的自定义选项
• 生成质量显著提升

3.3 迁移建议

由于这部分改动较大，建议：

1. 先阅读新版本文档中的测试数据生成指南
2. 从小规模数据开始试验
3. 利用新的知识图谱功能优化现有文档处理流程

四、提示对象升级

4.1 新提示系统

v0.2版本全面采用基于Pydantic的PydanticPrompts，主要改进包括：

• 强类型提示定义
• 更好的参数验证
• 更清晰的模板结构
• 增强的可组合性

4.2 迁移步骤

1. 将旧版Prompt对象重写为PydanticPrompt子类
2. 明确定义输入输出模型
3. 重构提示模板字符串
4. 更新相关业务逻辑

常见问题解答

Q：迁移过程遇到兼容性问题怎么办？

A：v0.2版本对v0.1的核心接口保持了短期兼容性，但建议尽快迁移到新API。遇到具体问题可以参考错误信息中的版本提示。

Q：评估结果与旧版本不一致？

A：这是预期行为，因为v0.2改进了多个评估维度的算法。建议将新旧版本评估结果差异视为模型改进的参考指标。

Q：测试集生成流程变化太大，如何快速上手？

A：建议从基础示例开始，逐步添加自定义组件。新版文档提供了详细的逐步指南和示例代码。

结语

Zibly v0.2版本的架构改进使其成为一个更强大、更灵活的LLM评估框架。虽然迁移过程需要一定工作量，但这些改进将为后续的评估工作带来长期收益。建议开发者按照本文指南分步骤完成迁移，遇到具体技术问题可以查阅详细的模块文档。