Guardrails项目0.3.0版本迁移指南

Guardrails项目0.3.0版本迁移指南

guardrails Adding guardrails to large language models. 项目地址: https://gitcode.com/gh_mirrors/gu/guardrails

前言

Guardrails是一个用于构建可靠AI应用的开源框架，它通过在大型语言模型(LLM)调用前后添加验证层来确保输出的质量和安全性。0.3.0版本引入了一些重要的架构改进，本文将详细介绍这些变化以及如何进行平滑迁移。

核心变更概述

0.3.0版本主要带来了两个重大改进：

1. 全新的响应对象结构
2. 更完善的日志和历史记录系统

这些改进旨在提供更丰富的调试信息和更直观的API使用体验。

响应对象的变化

旧版本行为回顾

在0.2.x版本中，当调用Guard的__call__或parse方法时，返回的是简单的元组结构：

# 0.2.x版本
raw_output, validated_output = guard(...)
# 或
validated_output = guard.parse(...)

这种方式虽然简单，但缺乏对验证过程的详细反馈。

新版本改进

0.3.0引入了ValidationOutcome类，它封装了更完整的验证信息：

# 0.3.0版本
response = guard(...)
# 或
response = guard.parse(...)

# 访问验证结果
validated_output = response.validated_output
validation_passed = response.validation_passed
reask_output = response.reask

向后兼容方案

为了保持与现有代码的兼容性，ValidationOutcome实现了可迭代协议：

# 兼容0.2.x的写法
raw_output, validated_output, *rest = guard(...)

重要新特性

特别值得注意的是validation_passed字段，它是一个布尔值，表示验证是否成功。只有当验证通过时，validated_output才会包含有效值；否则，无效输出将存储在reask属性中。

日志与历史记录的改进

旧版本日志访问方式

在0.2.x中，需要通过guard.state属性来访问历史记录，操作较为繁琐：

# 0.2.x检查验证状态
guard_history = guard.state.most_recent_call
last_step_logs = guard_history.history[-1]
validation_logs = last_step_logs.field_validation_logs.validator_logs
failed_validations = [log for log in validation_logs if log.validation_result.outcome == 'fail']
validation_succeeded = len(failed_validations) == 0

新版本简化访问

0.3.0引入了更直观的guard.history接口：

# 0.3.0检查验证状态
guard.history.last.status

令牌计数优化

旧版本中计算令牌消耗需要手动累加：

# 0.2.x令牌计数
latest_call = guard.state.most_recent_call
total_token_count = 0
for log in latest_call.history:
    total_token_count += log.llm_response.prompt_token_count
    total_token_count += log.llm_response.response_token_count

新版本提供了直接访问方式：

# 0.3.0令牌计数
guard.history.last.tokens_consumed

深入理解新特性

ValidationOutcome结构解析

ValidationOutcome类提供了以下关键属性：

• raw_output: 原始LLM输出
• validated_output: 验证后的输出(仅当验证通过时有效)
• validation_passed: 验证是否通过
• reask: 重新询问的内容(当验证失败时)
• error: 错误信息(如果有)

历史记录系统增强

新的历史记录系统提供了更丰富的调试信息：

• 完整的LLM调用链追踪
• 每个步骤的详细状态
• 自动计算的资源消耗
• 直观的状态检查方法

迁移建议

1. 响应处理迁移：

   • 如果代码中使用了元组解构，可以暂时保持原样
   • 建议逐步迁移到对象属性访问方式以获得更多信息

2. 日志系统迁移：

   • 替换所有guard.state相关代码为guard.history
   • 利用新的简化API减少样板代码

3. 验证逻辑优化：

   • 使用validation_passed替代手动验证结果检查
   • 合理处理reask场景

结语

Guardrails 0.3.0版本的这些改进显著提升了框架的可用性和可观察性。虽然需要一些迁移工作，但这些变化将为开发者提供更强大的调试能力和更简洁的API体验。建议用户在升级后充分利用新的历史记录系统和响应对象特性，以构建更健壮的AI应用。

guardrails Adding guardrails to large language models. 项目地址: https://gitcode.com/gh_mirrors/gu/guardrails