尧图网页设计 
AI 安全治理模型安全AI 应用【免费下载链接】guardrailsAdding guardrails to large language models.项目地址https://gitcode.com/gh_mirrors/gu/guardrails点击查看免费下载本文以 Guardrails 官方 API 参考文档 types.md 为骨架结合仓库源码guardrails/types/、guardrails/validator_service/、guardrails/schema/rail_schema.py等系统剖析 Guardrails 的核心类型定义验证失败时的行为枚举OnFailAction、RAIL XML 内置标签枚举RailTypes、Pydantic 模型与校验器相关的类型别名以及它们在真实调用链中的解析与分派机制。读完本文你将能准确理解on_fail参数的每种取值语义、RAIL 标签到 JSON Schema 的映射关系以及Guard.for_pydantic、Guard.use等 API 背后接受的具体类型形态从而写出类型安全、行为可控的 Guardrails 校验配置。类型包的组织结构Guardrails 将所有公共类型集中定义在guardrails/types/目录下并在 types/init.py 中统一导出方便外部以from guardrails.types import ...的方式引入guardrails/types/on_fail.py失败行为枚举OnFailActionguardrails/types/rail.pyRAIL XML 内置标签枚举RailTypesguardrails/types/primitives.py基础数据类型枚举PrimitiveTypes内部复用SimpleTypesguardrails/types/pydantic.pyPydantic 模型相关的类型别名guardrails/types/validator.py校验器规格相关的类型别名guardrails/types/inputs.py消息历史类型别名MessageHistory。其中PrimitiveTypes直接引用 guardrails/types/simple.py 中的SimpleTypes枚举array、boolean、integer、null、number、object、string并对外暴露BOOLEAN、INTEGER、NUMBER、STRING四个成员且提供了is_primitive(value)静态方法用于判断某值是否为原始类型。OnFailAction验证失败时的八种应对策略OnFailAction继承自(str, Enum)代表校验失败时可以采取的动作是on_fail参数的核心取值来源。官方文档给出了 8 个成员成员字面量语义REASKreask失败时让 LLM 重新生成该字段FIXfix失败时应用静态修复值FILTERfilter失败时过滤掉无效值REFRAINrefrain失败时拒绝作答返回空值NOOPnoop失败时不采取任何动作EXCEPTIONexception失败时抛出ValidationErrorFIX_REASKfix_reask先应用静态修复若修复后的值仍未通过校验再 reask LLMCUSTOMcustom失败时调用自定义函数入参为无效值和校验器产生的FailResult对应源码见 guardrails/types/on_fail.py。宽松解析OnFailAction.get()该枚举额外提供了一个静态方法OnFailAction.get(key, default)guardrails/types/on_fail.py传入字符串时按成员名大写匹配如exception、EXCEPTION均可解析到OnFailAction.EXCEPTION传入枚举实例则原样返回解析失败时返回默认值。这使得 RAIL 文件、命令行或用户输入中的大小写差异都能被容错处理。默认值与 CUSTOM 分支的判定逻辑在 guardrails/validator_base.py 中Validator.__init__对on_fail参数做了三路判定on_fail is None时默认取OnFailAction.EXCEPTION传入枚举实例或能匹配到枚举成员名的字符串时设置on_fail_descriptor且on_fail_method为None其余情况一律视为可调用对象将on_fail_descriptor置为OnFailAction.CUSTOM并通过_set_on_fail_method检查自定义函数签名——该函数必须接收两个参数被校验的值与FailResultguardrails/validator_base.py。因此CUSTOM不是简单的枚举字符串而是函数式失败处理的统一入口只要on_fail传的不是枚举/可识别字符串Guardrails 就会把它当成自定义处理函数来用。核心分派perform_correction()OnFailAction的语义最终在 guardrails/validator_service/validator_service_base.py 的perform_correction方法中落地。该方法是校验服务的核心分派点逐分支实现每种行为FIX直接返回result.fix_value校验器产出的修复值FIX_REASK若修复后的值经复查仍是FailResult则包装成FieldReAsk(incorrectValuefixed_value, failResults[result])交由后续 reask 流程处理CUSTOM调用validator.on_fail_method(value, result)若未设置on_fail_method则抛出ValueErrorREASK包装FieldReAsk(incorrectValuevalue, failResults[result])EXCEPTION抛出ValidationError错误信息汇总所有FailResult的error_messageFILTER返回Filter()哨兵对象由 guardrails/actions/filter.py 的apply_filters在后续处理中递归地从列表/字典中剔除这些值REFRAIN返回Refrain()哨兵对象由 guardrails/actions/refrain.py 的check_for_refrain/apply_refrain递归检测并替换为空值NOOP原样返回传入值不做任何处理。reask 相关的完整流程如get_reask_setup、gather_reasks、merge_reask_output集中在 guardrails/actions/reask.py可按需深入阅读。在测试中的典型用法集成测试展示了on_fail各取值的真实用法例如 tests/integration_tests/schema/test_pydantic_schema.py 中组合使用OnFailAction.REASK、OnFailAction.EXCEPTION、OnFailAction.FILTERtests/integration_tests/test_assets/entity_extraction/pydantic_models.py 则按场景分别使用FILTER、FIX、NOOP三种策略来构造不同的校验链路。RailTypesRAIL XML 的内置标签枚举RailTypes同样继承自(str, Enum)代表 RAIL XML 规范中的内置标签共有 13 个成员成员字面量含义STRINGstring字符串值INTEGERinteger整数值FLOATfloat浮点值BOOLbool布尔值DATEdate日期值TIMEtime时间值DATETIMEdate-time日期时间值PERCENTAGEpercentage以字符串表示的百分比如20.5%ENUMenum枚举值LISTlist列表/数组值OBJECTobject对象/字典值CHOICEchoice判别联合discriminated union的选项容器CASEcase包含判别联合的字典对应源码见 guardrails/types/rail.py。注意DATETIME的字面量是带连字符的date-time文档原文中该条存在笔误源码以RailTypes.DATETIME date-time为准。RailTypes.get(key)是一个宽松的类方法guardrails/types/rail.py用字符串直接构造枚举成员匹配不到时返回None而不是抛异常方便在 schema 解析过程中安全探测标签类型。RAIL 标签到 JSON Schema 的映射RailTypes的核心作用体现在 guardrails/schema/rail_schema.py 的schema_to_json_schema函数中。该函数读取 RAIL 元素的type属性output元素缺省时默认RailTypes.OBJECT然后按类型分派STRING、INTEGER、FLOAT、BOOL直接映射为 JSON Schema 的string/integer/number/boolean类型其中FLOAT还透传format属性缺省为floatDATE、TIME、DATETIME、PERCENTAGE映射为 JSON Schema 的string类型并通过extract_format合并自定义格式与内部格式属性如date-format、time-format、datetime-format例如 RAIL 中date formatfoo date-format%Y-%M-%D /会生成{type: string, format: date: %Y-%M-%D; foo}ENUM读取values逗号分隔属性生成枚举取值列表LIST、OBJECT、CHOICE、CASE则进入递归的嵌套结构构建逻辑。此外 guardrails/datatypes.py 维护了一个types_registry列表将SimpleTypes与RailTypes的全部字面量合并作为全局可识别的类型名注册表。Pydantic 模型相关的类型别名guardrails/types/pydantic.py 定义了三个围绕pydantic.BaseModel的类型别名用于标注输出 schema 可以是哪些形态ModelOrListOfModels Union[Type[BaseModel], Type[List[Type[BaseModel]]]] ModelOrListOrDict Union[ Type[BaseModel], Type[List[Type[BaseModel]]], Type[Dict[str, Type[BaseModel]]] ] ModelOrModelUnion Union[Type[BaseModel], Union[Type[BaseModel], Any]]ModelOrListOfModels单个 Pydantic 模型或模型列表的类型构造。这是Guard.for_pydantic的output_class参数签名guardrails/guard.py意味着你可以传入一个模型类也可以传入List[SomeModel]这种类型表达式来描述根级数组输出ModelOrListOrDict在ModelOrListOfModels基础上再允许键为字符串、值为模型类的字典类型构造覆盖对象/数组/映射三种根结构ModelOrModelUnion宽松的联合类型用于标注模型或模型与任意类型的联合。在 guardrails/guard.py 中Guard.for_pydantic通过pydantic_model_to_schema(output_class)将传入的模型或列表/字典类型转换为ProcessedSchema含json_schema、validators、validator_map再据此构建 Guard 实例。校验器规格的类型别名guardrails/types/validator.py 定义了与如何指定校验器相关的六个类型别名是Guard.for_pydantic字段校验器、Guard.use等 API 的类型基石PydanticValidatorTuple Tuple[Union[Validator, str, Callable], str] PydanticValidatorSpec Union[Validator, PydanticValidatorTuple] UseValidatorSpec Union[Validator, Type[Validator]] UseManyValidatorTuple Tuple[ Type[Validator], Optional[Union[List[Any], Dict[str, Any]]], Optional[Dict[str, Any]], ] UseManyValidatorSpec Union[Validator, UseManyValidatorTuple] ValidatorMap Dict[str, List[Validator]]各类型的语义与消费方PydanticValidatorTuple二元组(校验器, on_fail 字符串)。第一元素可以是Validator实例、注册名字符串或可调用对象第二元素是失败动作。它被parse_pydantic_validatorguardrails/utils/validator_utils.py消费若第一元素已是Validator实例则直接设置其on_fail_descriptor若是字符串则走parse_rail_validator按注册名解析失败动作缺省为OnFailAction.NOOPUseValidatorSpecGuard.use接受的单校验器规格可以是实例或未实例化的类UseManyValidatorTuple三元组(校验器类, 位置参数列表/字典, 关键字参数字典)由parse_use_many_validatorguardrails/utils/validator_utils.py实例化若第二元素是字典则整体作为 kwargs否则作为位置参数列表ValidatorMap键为 JSON path如$、$.field、$.items.*值为该路径上挂载的校验器列表。它被ProcessedSchema.validator_mapguardrails/classes/schema/processed_schema.py和Guard._validator_mapguardrails/guard.py共同使用是按输出路径组织校验器的核心数据结构。get_validator 的统一解析入口上述 tuple 形态在 guardrails/utils/validator_utils.py 的get_validator中被统一分派Validator实例直接返回Type[Validator]子类实例化并带有弃用警告官方建议直接传实例化好的校验器元组若首元素是Validator子类走parse_use_many_validator否则走parse_pydantic_validator字符串视为 RAIL 校验器规格经parse_rail_validator解析支持validator_id: arg1 arg2形式参数解析见 guardrails/utils/validator_utils.py。RAIL 中的 on-fail 属性与 ValidatorMap 填充在 RAIL 场景下guardrails/schema/rail_schema.py 的parse_on_fail_handlers会扫描元素上所有on-fail-*属性如on-fail-valid-choicesreask用OnFailAction(value)构造失败动作get_validators则解析validators属性中的分号分隔规格将解析结果写入ValidatorMap。随后extract_validatorsguardrails/schema/rail_schema.py为每个校验器生成ValidatorReference并按 JSON path 挂载到validator_map最终在Guard._for_rail_schemaguardrails/guard.py中被整体灌入 Guard 实例。Guard.use 的 on 参数Guard.useguardrails/guard.py接受Validator实例列表与on参数on的合法取值包括output、messages或$.开头的 JSON path内部将output归一化为$非典型取值会触发UserWarningguardrails/guard.py。MessageHistory带模板的消息历史MessageHistory定义在 guardrails/types/inputs.py其形态为MessageHistory List[Dict[str, Union[Prompt, str]]]即消息字典列表每条消息的content字段可以是Prompt对象或普通字符串。它贯穿 LLM 调用前的消息准备流程在 guardrails/run/runner.py 的prepare_messages中每条消息会被深拷贝首轮attempt_number 0用prompt_params对content做模板格式化content.format(**prompt_params)若校验器映射中包含messages键还会触发消息级校验validate_messages。Prompt类本身支持基于string.Template的安全格式化见 guardrails/prompt/prompt.py。实战示例类型体系的综合运用下面用一个 Pydantic Guard.use的组合示例串起上述类型from guardrails import Guard from guardrails.types import OnFailAction, ModelOrListOfModels from guardrails.validators import ValidLength, ValidChoices, TwoWords class Person(BaseModel): name: str Field(validators[TwoWords(on_failOnFailAction.FIX)]) age: int Field( validators[ValidChoices(choiceslist(range(0, 123)), on_failOnFailAction.REASK)] ) # ModelOrListOfModels 形态单模型或 List[Person] 均可作为 output_class guard Guard.for_pydantic(output_classPerson) # Guard.use 接受 Validator 实例on 支持 $. JSON path guard.use( ValidLength(min1, max120, on_failOnFailAction.NOOP), on$.name, )若改用 RAIL 定义则可用on-fail-*属性把失败行为直接写进 XML例如output string namename validatorstwo-words on-fail-two-wordsfix / integer nameage formatvalid-choices: 0..122 on-fail-valid-choicesreask / /output解析后每个 JSON path 上的校验器及其OnFailAction会被填充进ValidatorMap运行时由ValidatorServiceBase.perform_correction按上文的分派逻辑逐一执行。小结Guardrails 的类型体系是理解整个校验管线的钥匙OnFailAction定义失败后做什么并在ValidatorServiceBase.perform_correction中落地为八种可执行策略其中CUSTOM允许注入用户自定义函数RailTypes定义 RAIL XML 的标签词表并在rail_schema.py中逐类映射为 JSON Schema各 Pydantic/校验器类型别名ModelOrListOfModels、PydanticValidatorSpec、UseManyValidatorTuple、ValidatorMap等精确约束了Guard.for_pydantic、Guard.use等公共 API 的入参形态其解析逻辑统一收敛于 guardrails/utils/validator_utils.py 的get_validator。掌握这些类型定义与背后的解析/分派链路你就能在写 Guardrails 配置时做到类型即文档知道每个参数该传什么形态、每种失败行为会触发怎样的下游处理从而更精准地设计 LLM 输出的校验与纠错策略。如需进一步研究可继续阅读 actions.md失败动作细节、validator.md校验器接口与 rail.mdRAIL 规范。赞分享AI 安全治理模型安全AI 应用【免费下载链接】guardrailsAdding guardrails to large language models.项目地址https://gitcode.com/gh_mirrors/gu/guardrails点击查看免费下载相关推荐gbrain 类型分类法type-taxonomy深度解析14 类规范类型体系与 unify-types 迁移实战gbrain 类型分类法type taxonomy深度解析14 类规范类型体系与 unify types 迁移实战 gbrain 的类型系统 pages人工智能RAGAgent 记忆MCP 服务知识管理Medusa HTTP 类型生成器实战指南从 Zod 校验 Schema 自动生成与校验 TypeScript 类型Medusa HTTP 类型生成器实战指南从 Zod 校验 Schema 自动生成与校验 TypeScript 类型 导读 本指南围绕 Medusa 开源仓库后端电商前端Backstage catalog-model 包演进全解析实体模型、校验体系与 AI 资源类型Backstage catalog model 包演进全解析实体模型、校验体系与 AI 资源类型 backstage/catalog model 是 Bac开发者门户后端前端上一篇如何将PWABuilder pwa-starter应用打包到各大应用商店完整上架攻略下一篇5大智能功能全面解锁Chartero插件让你的文献管理效率翻倍创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Guardrails 类型体系全解析：OnFailAction、RailTypes 与校验器类型规范实战指南
AI 安全治理模型安全AI 应用【免费下载链接】guardrailsAdding guardrails to large language models.项目地址https://gitcode.com/gh_mirrors/gu/guardrails点击查看免费下载本文以 Guardrails 官方 API 参考文档 types.md 为骨架结合仓库源码guardrails/types/、guardrails/validator_service/、guardrails/schema/rail_schema.py等系统剖析 Guardrails 的核心类型定义验证失败时的行为枚举OnFailAction、RAIL XML 内置标签枚举RailTypes、Pydantic 模型与校验器相关的类型别名以及它们在真实调用链中的解析与分派机制。读完本文你将能准确理解on_fail参数的每种取值语义、RAIL 标签到 JSON Schema 的映射关系以及Guard.for_pydantic、Guard.use等 API 背后接受的具体类型形态从而写出类型安全、行为可控的 Guardrails 校验配置。类型包的组织结构Guardrails 将所有公共类型集中定义在guardrails/types/目录下并在 types/init.py 中统一导出方便外部以from guardrails.types import ...的方式引入guardrails/types/on_fail.py失败行为枚举OnFailActionguardrails/types/rail.pyRAIL XML 内置标签枚举RailTypesguardrails/types/primitives.py基础数据类型枚举PrimitiveTypes内部复用SimpleTypesguardrails/types/pydantic.pyPydantic 模型相关的类型别名guardrails/types/validator.py校验器规格相关的类型别名guardrails/types/inputs.py消息历史类型别名MessageHistory。其中PrimitiveTypes直接引用 guardrails/types/simple.py 中的SimpleTypes枚举array、boolean、integer、null、number、object、string并对外暴露BOOLEAN、INTEGER、NUMBER、STRING四个成员且提供了is_primitive(value)静态方法用于判断某值是否为原始类型。OnFailAction验证失败时的八种应对策略OnFailAction继承自(str, Enum)代表校验失败时可以采取的动作是on_fail参数的核心取值来源。官方文档给出了 8 个成员成员字面量语义REASKreask失败时让 LLM 重新生成该字段FIXfix失败时应用静态修复值FILTERfilter失败时过滤掉无效值REFRAINrefrain失败时拒绝作答返回空值NOOPnoop失败时不采取任何动作EXCEPTIONexception失败时抛出ValidationErrorFIX_REASKfix_reask先应用静态修复若修复后的值仍未通过校验再 reask LLMCUSTOMcustom失败时调用自定义函数入参为无效值和校验器产生的FailResult对应源码见 guardrails/types/on_fail.py。宽松解析OnFailAction.get()该枚举额外提供了一个静态方法OnFailAction.get(key, default)guardrails/types/on_fail.py传入字符串时按成员名大写匹配如exception、EXCEPTION均可解析到OnFailAction.EXCEPTION传入枚举实例则原样返回解析失败时返回默认值。这使得 RAIL 文件、命令行或用户输入中的大小写差异都能被容错处理。默认值与 CUSTOM 分支的判定逻辑在 guardrails/validator_base.py 中Validator.__init__对on_fail参数做了三路判定on_fail is None时默认取OnFailAction.EXCEPTION传入枚举实例或能匹配到枚举成员名的字符串时设置on_fail_descriptor且on_fail_method为None其余情况一律视为可调用对象将on_fail_descriptor置为OnFailAction.CUSTOM并通过_set_on_fail_method检查自定义函数签名——该函数必须接收两个参数被校验的值与FailResultguardrails/validator_base.py。因此CUSTOM不是简单的枚举字符串而是函数式失败处理的统一入口只要on_fail传的不是枚举/可识别字符串Guardrails 就会把它当成自定义处理函数来用。核心分派perform_correction()OnFailAction的语义最终在 guardrails/validator_service/validator_service_base.py 的perform_correction方法中落地。该方法是校验服务的核心分派点逐分支实现每种行为FIX直接返回result.fix_value校验器产出的修复值FIX_REASK若修复后的值经复查仍是FailResult则包装成FieldReAsk(incorrectValuefixed_value, failResults[result])交由后续 reask 流程处理CUSTOM调用validator.on_fail_method(value, result)若未设置on_fail_method则抛出ValueErrorREASK包装FieldReAsk(incorrectValuevalue, failResults[result])EXCEPTION抛出ValidationError错误信息汇总所有FailResult的error_messageFILTER返回Filter()哨兵对象由 guardrails/actions/filter.py 的apply_filters在后续处理中递归地从列表/字典中剔除这些值REFRAIN返回Refrain()哨兵对象由 guardrails/actions/refrain.py 的check_for_refrain/apply_refrain递归检测并替换为空值NOOP原样返回传入值不做任何处理。reask 相关的完整流程如get_reask_setup、gather_reasks、merge_reask_output集中在 guardrails/actions/reask.py可按需深入阅读。在测试中的典型用法集成测试展示了on_fail各取值的真实用法例如 tests/integration_tests/schema/test_pydantic_schema.py 中组合使用OnFailAction.REASK、OnFailAction.EXCEPTION、OnFailAction.FILTERtests/integration_tests/test_assets/entity_extraction/pydantic_models.py 则按场景分别使用FILTER、FIX、NOOP三种策略来构造不同的校验链路。RailTypesRAIL XML 的内置标签枚举RailTypes同样继承自(str, Enum)代表 RAIL XML 规范中的内置标签共有 13 个成员成员字面量含义STRINGstring字符串值INTEGERinteger整数值FLOATfloat浮点值BOOLbool布尔值DATEdate日期值TIMEtime时间值DATETIMEdate-time日期时间值PERCENTAGEpercentage以字符串表示的百分比如20.5%ENUMenum枚举值LISTlist列表/数组值OBJECTobject对象/字典值CHOICEchoice判别联合discriminated union的选项容器CASEcase包含判别联合的字典对应源码见 guardrails/types/rail.py。注意DATETIME的字面量是带连字符的date-time文档原文中该条存在笔误源码以RailTypes.DATETIME date-time为准。RailTypes.get(key)是一个宽松的类方法guardrails/types/rail.py用字符串直接构造枚举成员匹配不到时返回None而不是抛异常方便在 schema 解析过程中安全探测标签类型。RAIL 标签到 JSON Schema 的映射RailTypes的核心作用体现在 guardrails/schema/rail_schema.py 的schema_to_json_schema函数中。该函数读取 RAIL 元素的type属性output元素缺省时默认RailTypes.OBJECT然后按类型分派STRING、INTEGER、FLOAT、BOOL直接映射为 JSON Schema 的string/integer/number/boolean类型其中FLOAT还透传format属性缺省为floatDATE、TIME、DATETIME、PERCENTAGE映射为 JSON Schema 的string类型并通过extract_format合并自定义格式与内部格式属性如date-format、time-format、datetime-format例如 RAIL 中date formatfoo date-format%Y-%M-%D /会生成{type: string, format: date: %Y-%M-%D; foo}ENUM读取values逗号分隔属性生成枚举取值列表LIST、OBJECT、CHOICE、CASE则进入递归的嵌套结构构建逻辑。此外 guardrails/datatypes.py 维护了一个types_registry列表将SimpleTypes与RailTypes的全部字面量合并作为全局可识别的类型名注册表。Pydantic 模型相关的类型别名guardrails/types/pydantic.py 定义了三个围绕pydantic.BaseModel的类型别名用于标注输出 schema 可以是哪些形态ModelOrListOfModels Union[Type[BaseModel], Type[List[Type[BaseModel]]]] ModelOrListOrDict Union[ Type[BaseModel], Type[List[Type[BaseModel]]], Type[Dict[str, Type[BaseModel]]] ] ModelOrModelUnion Union[Type[BaseModel], Union[Type[BaseModel], Any]]ModelOrListOfModels单个 Pydantic 模型或模型列表的类型构造。这是Guard.for_pydantic的output_class参数签名guardrails/guard.py意味着你可以传入一个模型类也可以传入List[SomeModel]这种类型表达式来描述根级数组输出ModelOrListOrDict在ModelOrListOfModels基础上再允许键为字符串、值为模型类的字典类型构造覆盖对象/数组/映射三种根结构ModelOrModelUnion宽松的联合类型用于标注模型或模型与任意类型的联合。在 guardrails/guard.py 中Guard.for_pydantic通过pydantic_model_to_schema(output_class)将传入的模型或列表/字典类型转换为ProcessedSchema含json_schema、validators、validator_map再据此构建 Guard 实例。校验器规格的类型别名guardrails/types/validator.py 定义了与如何指定校验器相关的六个类型别名是Guard.for_pydantic字段校验器、Guard.use等 API 的类型基石PydanticValidatorTuple Tuple[Union[Validator, str, Callable], str] PydanticValidatorSpec Union[Validator, PydanticValidatorTuple] UseValidatorSpec Union[Validator, Type[Validator]] UseManyValidatorTuple Tuple[ Type[Validator], Optional[Union[List[Any], Dict[str, Any]]], Optional[Dict[str, Any]], ] UseManyValidatorSpec Union[Validator, UseManyValidatorTuple] ValidatorMap Dict[str, List[Validator]]各类型的语义与消费方PydanticValidatorTuple二元组(校验器, on_fail 字符串)。第一元素可以是Validator实例、注册名字符串或可调用对象第二元素是失败动作。它被parse_pydantic_validatorguardrails/utils/validator_utils.py消费若第一元素已是Validator实例则直接设置其on_fail_descriptor若是字符串则走parse_rail_validator按注册名解析失败动作缺省为OnFailAction.NOOPUseValidatorSpecGuard.use接受的单校验器规格可以是实例或未实例化的类UseManyValidatorTuple三元组(校验器类, 位置参数列表/字典, 关键字参数字典)由parse_use_many_validatorguardrails/utils/validator_utils.py实例化若第二元素是字典则整体作为 kwargs否则作为位置参数列表ValidatorMap键为 JSON path如$、$.field、$.items.*值为该路径上挂载的校验器列表。它被ProcessedSchema.validator_mapguardrails/classes/schema/processed_schema.py和Guard._validator_mapguardrails/guard.py共同使用是按输出路径组织校验器的核心数据结构。get_validator 的统一解析入口上述 tuple 形态在 guardrails/utils/validator_utils.py 的get_validator中被统一分派Validator实例直接返回Type[Validator]子类实例化并带有弃用警告官方建议直接传实例化好的校验器元组若首元素是Validator子类走parse_use_many_validator否则走parse_pydantic_validator字符串视为 RAIL 校验器规格经parse_rail_validator解析支持validator_id: arg1 arg2形式参数解析见 guardrails/utils/validator_utils.py。RAIL 中的 on-fail 属性与 ValidatorMap 填充在 RAIL 场景下guardrails/schema/rail_schema.py 的parse_on_fail_handlers会扫描元素上所有on-fail-*属性如on-fail-valid-choicesreask用OnFailAction(value)构造失败动作get_validators则解析validators属性中的分号分隔规格将解析结果写入ValidatorMap。随后extract_validatorsguardrails/schema/rail_schema.py为每个校验器生成ValidatorReference并按 JSON path 挂载到validator_map最终在Guard._for_rail_schemaguardrails/guard.py中被整体灌入 Guard 实例。Guard.use 的 on 参数Guard.useguardrails/guard.py接受Validator实例列表与on参数on的合法取值包括output、messages或$.开头的 JSON path内部将output归一化为$非典型取值会触发UserWarningguardrails/guard.py。MessageHistory带模板的消息历史MessageHistory定义在 guardrails/types/inputs.py其形态为MessageHistory List[Dict[str, Union[Prompt, str]]]即消息字典列表每条消息的content字段可以是Prompt对象或普通字符串。它贯穿 LLM 调用前的消息准备流程在 guardrails/run/runner.py 的prepare_messages中每条消息会被深拷贝首轮attempt_number 0用prompt_params对content做模板格式化content.format(**prompt_params)若校验器映射中包含messages键还会触发消息级校验validate_messages。Prompt类本身支持基于string.Template的安全格式化见 guardrails/prompt/prompt.py。实战示例类型体系的综合运用下面用一个 Pydantic Guard.use的组合示例串起上述类型from guardrails import Guard from guardrails.types import OnFailAction, ModelOrListOfModels from guardrails.validators import ValidLength, ValidChoices, TwoWords class Person(BaseModel): name: str Field(validators[TwoWords(on_failOnFailAction.FIX)]) age: int Field( validators[ValidChoices(choiceslist(range(0, 123)), on_failOnFailAction.REASK)] ) # ModelOrListOfModels 形态单模型或 List[Person] 均可作为 output_class guard Guard.for_pydantic(output_classPerson) # Guard.use 接受 Validator 实例on 支持 $. JSON path guard.use( ValidLength(min1, max120, on_failOnFailAction.NOOP), on$.name, )若改用 RAIL 定义则可用on-fail-*属性把失败行为直接写进 XML例如output string namename validatorstwo-words on-fail-two-wordsfix / integer nameage formatvalid-choices: 0..122 on-fail-valid-choicesreask / /output解析后每个 JSON path 上的校验器及其OnFailAction会被填充进ValidatorMap运行时由ValidatorServiceBase.perform_correction按上文的分派逻辑逐一执行。小结Guardrails 的类型体系是理解整个校验管线的钥匙OnFailAction定义失败后做什么并在ValidatorServiceBase.perform_correction中落地为八种可执行策略其中CUSTOM允许注入用户自定义函数RailTypes定义 RAIL XML 的标签词表并在rail_schema.py中逐类映射为 JSON Schema各 Pydantic/校验器类型别名ModelOrListOfModels、PydanticValidatorSpec、UseManyValidatorTuple、ValidatorMap等精确约束了Guard.for_pydantic、Guard.use等公共 API 的入参形态其解析逻辑统一收敛于 guardrails/utils/validator_utils.py 的get_validator。掌握这些类型定义与背后的解析/分派链路你就能在写 Guardrails 配置时做到类型即文档知道每个参数该传什么形态、每种失败行为会触发怎样的下游处理从而更精准地设计 LLM 输出的校验与纠错策略。如需进一步研究可继续阅读 actions.md失败动作细节、validator.md校验器接口与 rail.mdRAIL 规范。赞分享AI 安全治理模型安全AI 应用【免费下载链接】guardrailsAdding guardrails to large language models.项目地址https://gitcode.com/gh_mirrors/gu/guardrails点击查看免费下载相关推荐gbrain 类型分类法type-taxonomy深度解析14 类规范类型体系与 unify-types 迁移实战gbrain 类型分类法type taxonomy深度解析14 类规范类型体系与 unify types 迁移实战 gbrain 的类型系统 pages人工智能RAGAgent 记忆MCP 服务知识管理Medusa HTTP 类型生成器实战指南从 Zod 校验 Schema 自动生成与校验 TypeScript 类型Medusa HTTP 类型生成器实战指南从 Zod 校验 Schema 自动生成与校验 TypeScript 类型 导读 本指南围绕 Medusa 开源仓库后端电商前端Backstage catalog-model 包演进全解析实体模型、校验体系与 AI 资源类型Backstage catalog model 包演进全解析实体模型、校验体系与 AI 资源类型 backstage/catalog model 是 Bac开发者门户后端前端上一篇如何将PWABuilder pwa-starter应用打包到各大应用商店完整上架攻略下一篇5大智能功能全面解锁Chartero插件让你的文献管理效率翻倍创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考