器類型規(guī)范實(shí)戰(zhàn)指南)
AI 安全治理模型安全AI 應(yīng)用【免費(fèi)下載鏈接】guardrailsAdding guardrails to large language models.項(xiàng)目地址https://gitcode.com/gh_mirrors/gu/guardrails點(diǎn)擊查看免費(fèi)下載本文以 Guardrails 官方 API 參考文檔 types.md 為骨架結(jié)合倉(cāng)庫(kù)源碼guardrails/types/、guardrails/validator_service/、guardrails/schema/rail_schema.py等系統(tǒng)剖析 Guardrails 的核心類型定義驗(yàn)證失敗時(shí)的行為枚舉OnFailAction、RAIL XML 內(nèi)置標(biāo)簽枚舉RailTypes、Pydantic 模型與校驗(yàn)器相關(guān)的類型別名以及它們?cè)谡鎸?shí)調(diào)用鏈中的解析與分派機(jī)制。讀完本文你將能準(zhǔn)確理解on_fail參數(shù)的每種取值語(yǔ)義、RAIL 標(biāo)簽到 JSON Schema 的映射關(guān)系以及Guard.for_pydantic、Guard.use等 API 背后接受的具體類型形態(tài)從而寫出類型安全、行為可控的 Guardrails 校驗(yàn)配置。類型包的組織結(jié)構(gòu)Guardrails 將所有公共類型集中定義在guardrails/types/目錄下并在 types/init.py 中統(tǒng)一導(dǎo)出方便外部以from guardrails.types import ...的方式引入guardrails/types/on_fail.py失敗行為枚舉OnFailActionguardrails/types/rail.pyRAIL XML 內(nèi)置標(biāo)簽枚舉RailTypesguardrails/types/primitives.py基礎(chǔ)數(shù)據(jù)類型枚舉PrimitiveTypes內(nèi)部復(fù)用SimpleTypesguardrails/types/pydantic.pyPydantic 模型相關(guān)的類型別名guardrails/types/validator.py校驗(yàn)器規(guī)格相關(guān)的類型別名guardrails/types/inputs.py消息歷史類型別名MessageHistory。其中PrimitiveTypes直接引用 guardrails/types/simple.py 中的SimpleTypes枚舉array、boolean、integer、null、number、object、string并對(duì)外暴露BOOLEAN、INTEGER、NUMBER、STRING四個(gè)成員且提供了is_primitive(value)靜態(tài)方法用于判斷某值是否為原始類型。OnFailAction驗(yàn)證失敗時(shí)的八種應(yīng)對(duì)策略O(shè)nFailAction繼承自(str, Enum)代表校驗(yàn)失敗時(shí)可以采取的動(dòng)作是on_fail參數(shù)的核心取值來(lái)源。官方文檔給出了 8 個(gè)成員成員字面量語(yǔ)義REASKreask失敗時(shí)讓 LLM 重新生成該字段FIXfix失敗時(shí)應(yīng)用靜態(tài)修復(fù)值FILTERfilter失敗時(shí)過濾掉無(wú)效值REFRAINrefrain失敗時(shí)拒絕作答返回空值NOOPnoop失敗時(shí)不采取任何動(dòng)作EXCEPTIONexception失敗時(shí)拋出ValidationErrorFIX_REASKfix_reask先應(yīng)用靜態(tài)修復(fù)若修復(fù)后的值仍未通過校驗(yàn)再 reask LLMCUSTOMcustom失敗時(shí)調(diào)用自定義函數(shù)入?yún)闊o(wú)效值和校驗(yàn)器產(chǎn)生的FailResult對(duì)應(yīng)源碼見 guardrails/types/on_fail.py。寬松解析OnFailAction.get()該枚舉額外提供了一個(gè)靜態(tài)方法OnFailAction.get(key, default)guardrails/types/on_fail.py傳入字符串時(shí)按成員名大寫匹配如exception、EXCEPTION均可解析到OnFailAction.EXCEPTION傳入枚舉實(shí)例則原樣返回解析失敗時(shí)返回默認(rèn)值。這使得 RAIL 文件、命令行或用戶輸入中的大小寫差異都能被容錯(cuò)處理。默認(rèn)值與 CUSTOM 分支的判定邏輯在 guardrails/validator_base.py 中Validator.__init__對(duì)on_fail參數(shù)做了三路判定on_fail is None時(shí)默認(rèn)取OnFailAction.EXCEPTION傳入枚舉實(shí)例或能匹配到枚舉成員名的字符串時(shí)設(shè)置on_fail_descriptor且on_fail_method為None其余情況一律視為可調(diào)用對(duì)象將on_fail_descriptor置為OnFailAction.CUSTOM并通過_set_on_fail_method檢查自定義函數(shù)簽名——該函數(shù)必須接收兩個(gè)參數(shù)被校驗(yàn)的值與FailResultguardrails/validator_base.py。因此CUSTOM不是簡(jiǎn)單的枚舉字符串而是函數(shù)式失敗處理的統(tǒng)一入口只要on_fail傳的不是枚舉/可識(shí)別字符串Guardrails 就會(huì)把它當(dāng)成自定義處理函數(shù)來(lái)用。核心分派perform_correction()OnFailAction的語(yǔ)義最終在 guardrails/validator_service/validator_service_base.py 的perform_correction方法中落地。該方法是校驗(yàn)服務(wù)的核心分派點(diǎn)逐分支實(shí)現(xiàn)每種行為FIX直接返回result.fix_value校驗(yàn)器產(chǎn)出的修復(fù)值FIX_REASK若修復(fù)后的值經(jīng)復(fù)查仍是FailResult則包裝成FieldReAsk(incorrectValuefixed_value, failResults[result])交由后續(xù) reask 流程處理CUSTOM調(diào)用validator.on_fail_method(value, result)若未設(shè)置on_fail_method則拋出ValueErrorREASK包裝FieldReAsk(incorrectValuevalue, failResults[result])EXCEPTION拋出ValidationError錯(cuò)誤信息匯總所有FailResult的error_messageFILTER返回Filter()哨兵對(duì)象由 guardrails/actions/filter.py 的apply_filters在后續(xù)處理中遞歸地從列表/字典中剔除這些值REFRAIN返回Refrain()哨兵對(duì)象由 guardrails/actions/refrain.py 的check_for_refrain/apply_refrain遞歸檢測(cè)并替換為空值NOOP原樣返回傳入值不做任何處理。reask 相關(guān)的完整流程如get_reask_setup、gather_reasks、merge_reask_output集中在 guardrails/actions/reask.py可按需深入閱讀。在測(cè)試中的典型用法集成測(cè)試展示了on_fail各取值的真實(shí)用法例如 tests/integration_tests/schema/test_pydantic_schema.py 中組合使用OnFailAction.REASK、OnFailAction.EXCEPTION、OnFailAction.FILTERtests/integration_tests/test_assets/entity_extraction/pydantic_models.py 則按場(chǎng)景分別使用FILTER、FIX、NOOP三種策略來(lái)構(gòu)造不同的校驗(yàn)鏈路。RailTypesRAIL XML 的內(nèi)置標(biāo)簽枚舉RailTypes同樣繼承自(str, Enum)代表 RAIL XML 規(guī)范中的內(nèi)置標(biāo)簽共有 13 個(gè)成員成員字面量含義STRINGstring字符串值INTEGERinteger整數(shù)值FLOATfloat浮點(diǎn)值BOOLbool布爾值DATEdate日期值TIMEtime時(shí)間值DATETIMEdate-time日期時(shí)間值PERCENTAGEpercentage以字符串表示的百分比如20.5%ENUMenum枚舉值LISTlist列表/數(shù)組值OBJECTobject對(duì)象/字典值CHOICEchoice判別聯(lián)合discriminated union的選項(xiàng)容器CASEcase包含判別聯(lián)合的字典對(duì)應(yīng)源碼見 guardrails/types/rail.py。注意DATETIME的字面量是帶連字符的date-time文檔原文中該條存在筆誤源碼以RailTypes.DATETIME date-time為準(zhǔn)。RailTypes.get(key)是一個(gè)寬松的類方法guardrails/types/rail.py用字符串直接構(gòu)造枚舉成員匹配不到時(shí)返回None而不是拋異常方便在 schema 解析過程中安全探測(cè)標(biāo)簽類型。RAIL 標(biāo)簽到 JSON Schema 的映射RailTypes的核心作用體現(xiàn)在 guardrails/schema/rail_schema.py 的schema_to_json_schema函數(shù)中。該函數(shù)讀取 RAIL 元素的type屬性output元素缺省時(shí)默認(rèn)RailTypes.OBJECT然后按類型分派STRING、INTEGER、FLOAT、BOOL直接映射為 JSON Schema 的string/integer/number/boolean類型其中FLOAT還透?jìng)鱢ormat屬性缺省為floatDATE、TIME、DATETIME、PERCENTAGE映射為 JSON Schema 的string類型并通過extract_format合并自定義格式與內(nèi)部格式屬性如date-format、time-format、datetime-format例如 RAIL 中date formatfoo date-format%Y-%M-%D /會(huì)生成{type: string, format: date: %Y-%M-%D; foo}ENUM讀取values逗號(hào)分隔屬性生成枚舉取值列表LIST、OBJECT、CHOICE、CASE則進(jìn)入遞歸的嵌套結(jié)構(gòu)構(gòu)建邏輯。此外 guardrails/datatypes.py 維護(hù)了一個(gè)types_registry列表將SimpleTypes與RailTypes的全部字面量合并作為全局可識(shí)別的類型名注冊(cè)表。Pydantic 模型相關(guān)的類型別名guardrails/types/pydantic.py 定義了三個(gè)圍繞pydantic.BaseModel的類型別名用于標(biāo)注輸出 schema 可以是哪些形態(tài)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單個(gè) Pydantic 模型或模型列表的類型構(gòu)造。這是Guard.for_pydantic的output_class參數(shù)簽名guardrails/guard.py意味著你可以傳入一個(gè)模型類也可以傳入List[SomeModel]這種類型表達(dá)式來(lái)描述根級(jí)數(shù)組輸出ModelOrListOrDict在ModelOrListOfModels基礎(chǔ)上再允許鍵為字符串、值為模型類的字典類型構(gòu)造覆蓋對(duì)象/數(shù)組/映射三種根結(jié)構(gòu)ModelOrModelUnion寬松的聯(lián)合類型用于標(biāo)注模型或模型與任意類型的聯(lián)合。在 guardrails/guard.py 中Guard.for_pydantic通過pydantic_model_to_schema(output_class)將傳入的模型或列表/字典類型轉(zhuǎn)換為ProcessedSchema含json_schema、validators、validator_map再據(jù)此構(gòu)建 Guard 實(shí)例。校驗(yàn)器規(guī)格的類型別名guardrails/types/validator.py 定義了與如何指定校驗(yàn)器相關(guān)的六個(gè)類型別名是Guard.for_pydantic字段校驗(yàn)器、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]]各類型的語(yǔ)義與消費(fèi)方PydanticValidatorTuple二元組(校驗(yàn)器, on_fail 字符串)。第一元素可以是Validator實(shí)例、注冊(cè)名字符串或可調(diào)用對(duì)象第二元素是失敗動(dòng)作。它被parse_pydantic_validatorguardrails/utils/validator_utils.py消費(fèi)若第一元素已是Validator實(shí)例則直接設(shè)置其on_fail_descriptor若是字符串則走parse_rail_validator按注冊(cè)名解析失敗動(dòng)作缺省為OnFailAction.NOOPUseValidatorSpecGuard.use接受的單校驗(yàn)器規(guī)格可以是實(shí)例或未實(shí)例化的類UseManyValidatorTuple三元組(校驗(yàn)器類, 位置參數(shù)列表/字典, 關(guān)鍵字參數(shù)字典)由parse_use_many_validatorguardrails/utils/validator_utils.py實(shí)例化若第二元素是字典則整體作為 kwargs否則作為位置參數(shù)列表ValidatorMap鍵為 JSON path如$、$.field、$.items.*值為該路徑上掛載的校驗(yàn)器列表。它被ProcessedSchema.validator_mapguardrails/classes/schema/processed_schema.py和Guard._validator_mapguardrails/guard.py共同使用是按輸出路徑組織校驗(yàn)器的核心數(shù)據(jù)結(jié)構(gòu)。get_validator 的統(tǒng)一解析入口上述 tuple 形態(tài)在 guardrails/utils/validator_utils.py 的get_validator中被統(tǒng)一分派Validator實(shí)例直接返回Type[Validator]子類實(shí)例化并帶有棄用警告官方建議直接傳實(shí)例化好的校驗(yàn)器元組若首元素是Validator子類走parse_use_many_validator否則走parse_pydantic_validator字符串視為 RAIL 校驗(yàn)器規(guī)格經(jīng)parse_rail_validator解析支持validator_id: arg1 arg2形式參數(shù)解析見 guardrails/utils/validator_utils.py。RAIL 中的 on-fail 屬性與 ValidatorMap 填充在 RAIL 場(chǎng)景下guardrails/schema/rail_schema.py 的parse_on_fail_handlers會(huì)掃描元素上所有on-fail-*屬性如on-fail-valid-choicesreask用OnFailAction(value)構(gòu)造失敗動(dòng)作get_validators則解析validators屬性中的分號(hào)分隔規(guī)格將解析結(jié)果寫入ValidatorMap。隨后extract_validatorsguardrails/schema/rail_schema.py為每個(gè)校驗(yàn)器生成ValidatorReference并按 JSON path 掛載到validator_map最終在Guard._for_rail_schemaguardrails/guard.py中被整體灌入 Guard 實(shí)例。Guard.use 的 on 參數(shù)Guard.useguardrails/guard.py接受Validator實(shí)例列表與on參數(shù)on的合法取值包括output、messages或$.開頭的 JSON path內(nèi)部將output歸一化為$非典型取值會(huì)觸發(fā)UserWarningguardrails/guard.py。MessageHistory帶模板的消息歷史MessageHistory定義在 guardrails/types/inputs.py其形態(tài)為MessageHistory List[Dict[str, Union[Prompt, str]]]即消息字典列表每條消息的content字段可以是Prompt對(duì)象或普通字符串。它貫穿 LLM 調(diào)用前的消息準(zhǔn)備流程在 guardrails/run/runner.py 的prepare_messages中每條消息會(huì)被深拷貝首輪attempt_number 0用prompt_params對(duì)content做模板格式化content.format(**prompt_params)若校驗(yàn)器映射中包含messages鍵還會(huì)觸發(fā)消息級(jí)校驗(yàn)validate_messages。Prompt類本身支持基于string.Template的安全格式化見 guardrails/prompt/prompt.py。實(shí)戰(zhàn)示例類型體系的綜合運(yùn)用下面用一個(gè) 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 形態(tài)單模型或 List[Person] 均可作為 output_class guard Guard.for_pydantic(output_classPerson) # Guard.use 接受 Validator 實(shí)例on 支持 $. JSON path guard.use( ValidLength(min1, max120, on_failOnFailAction.NOOP), on$.name, )若改用 RAIL 定義則可用on-fail-*屬性把失敗行為直接寫進(jìn) XML例如output string namename validatorstwo-words on-fail-two-wordsfix / integer nameage formatvalid-choices: 0..122 on-fail-valid-choicesreask / /output解析后每個(gè) JSON path 上的校驗(yàn)器及其OnFailAction會(huì)被填充進(jìn)ValidatorMap運(yùn)行時(shí)由ValidatorServiceBase.perform_correction按上文的分派邏輯逐一執(zhí)行。小結(jié)Guardrails 的類型體系是理解整個(gè)校驗(yàn)管線的鑰匙OnFailAction定義失敗后做什么并在ValidatorServiceBase.perform_correction中落地為八種可執(zhí)行策略其中CUSTOM允許注入用戶自定義函數(shù)RailTypes定義 RAIL XML 的標(biāo)簽詞表并在rail_schema.py中逐類映射為 JSON Schema各 Pydantic/校驗(yàn)器類型別名ModelOrListOfModels、PydanticValidatorSpec、UseManyValidatorTuple、ValidatorMap等精確約束了Guard.for_pydantic、Guard.use等公共 API 的入?yún)⑿螒B(tài)其解析邏輯統(tǒng)一收斂于 guardrails/utils/validator_utils.py 的get_validator。掌握這些類型定義與背后的解析/分派鏈路你就能在寫 Guardrails 配置時(shí)做到類型即文檔知道每個(gè)參數(shù)該傳什么形態(tài)、每種失敗行為會(huì)觸發(fā)怎樣的下游處理從而更精準(zhǔn)地設(shè)計(jì) LLM 輸出的校驗(yàn)與糾錯(cuò)策略。如需進(jìn)一步研究可繼續(xù)閱讀 actions.md失敗動(dòng)作細(xì)節(jié)、validator.md校驗(yàn)器接口與 rail.mdRAIL 規(guī)范。贊分享AI 安全治理模型安全AI 應(yīng)用【免費(fèi)下載鏈接】guardrailsAdding guardrails to large language models.項(xiàng)目地址https://gitcode.com/gh_mirrors/gu/guardrails點(diǎn)擊查看免費(fèi)下載相關(guān)推薦gbrain 類型分類法type-taxonomy深度解析14 類規(guī)范類型體系與 unify-types 遷移實(shí)戰(zhàn)gbrain 類型分類法type taxonomy深度解析14 類規(guī)范類型體系與 unify types 遷移實(shí)戰(zhàn) gbrain 的類型系統(tǒng) pages人工智能RAGAgent 記憶MCP 服務(wù)知識(shí)管理Medusa HTTP 類型生成器實(shí)戰(zhàn)指南從 Zod 校驗(yàn) Schema 自動(dòng)生成與校驗(yàn) TypeScript 類型Medusa HTTP 類型生成器實(shí)戰(zhàn)指南從 Zod 校驗(yàn) Schema 自動(dòng)生成與校驗(yàn) TypeScript 類型 導(dǎo)讀 本指南圍繞 Medusa 開源倉(cāng)庫(kù)后端電商前端Backstage catalog-model 包演進(jìn)全解析實(shí)體模型、校驗(yàn)體系與 AI 資源類型Backstage catalog model 包演進(jìn)全解析實(shí)體模型、校驗(yàn)體系與 AI 資源類型 backstage/catalog model 是 Bac開發(fā)者門戶后端前端上一篇如何將PWABuilder pwa-starter應(yīng)用打包到各大應(yīng)用商店完整上架攻略下一篇5大智能功能全面解鎖Chartero插件讓你的文獻(xiàn)管理效率翻倍創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 Guardrails 類型體系全解析：OnFailAction、RailTypes 與校驗(yàn)器類型規(guī)范實(shí)戰(zhàn)指南
AI 安全治理模型安全AI 應(yīng)用【免費(fèi)下載鏈接】guardrailsAdding guardrails to large language models.項(xiàng)目地址https://gitcode.com/gh_mirrors/gu/guardrails點(diǎn)擊查看免費(fèi)下載本文以 Guardrails 官方 API 參考文檔 types.md 為骨架結(jié)合倉(cāng)庫(kù)源碼guardrails/types/、guardrails/validator_service/、guardrails/schema/rail_schema.py等系統(tǒng)剖析 Guardrails 的核心類型定義驗(yàn)證失敗時(shí)的行為枚舉OnFailAction、RAIL XML 內(nèi)置標(biāo)簽枚舉RailTypes、Pydantic 模型與校驗(yàn)器相關(guān)的類型別名以及它們?cè)谡鎸?shí)調(diào)用鏈中的解析與分派機(jī)制。讀完本文你將能準(zhǔn)確理解on_fail參數(shù)的每種取值語(yǔ)義、RAIL 標(biāo)簽到 JSON Schema 的映射關(guān)系以及Guard.for_pydantic、Guard.use等 API 背后接受的具體類型形態(tài)從而寫出類型安全、行為可控的 Guardrails 校驗(yàn)配置。類型包的組織結(jié)構(gòu)Guardrails 將所有公共類型集中定義在guardrails/types/目錄下并在 types/init.py 中統(tǒng)一導(dǎo)出方便外部以from guardrails.types import ...的方式引入guardrails/types/on_fail.py失敗行為枚舉OnFailActionguardrails/types/rail.pyRAIL XML 內(nèi)置標(biāo)簽枚舉RailTypesguardrails/types/primitives.py基礎(chǔ)數(shù)據(jù)類型枚舉PrimitiveTypes內(nèi)部復(fù)用SimpleTypesguardrails/types/pydantic.pyPydantic 模型相關(guān)的類型別名guardrails/types/validator.py校驗(yàn)器規(guī)格相關(guān)的類型別名guardrails/types/inputs.py消息歷史類型別名MessageHistory。其中PrimitiveTypes直接引用 guardrails/types/simple.py 中的SimpleTypes枚舉array、boolean、integer、null、number、object、string并對(duì)外暴露BOOLEAN、INTEGER、NUMBER、STRING四個(gè)成員且提供了is_primitive(value)靜態(tài)方法用于判斷某值是否為原始類型。OnFailAction驗(yàn)證失敗時(shí)的八種應(yīng)對(duì)策略O(shè)nFailAction繼承自(str, Enum)代表校驗(yàn)失敗時(shí)可以采取的動(dòng)作是on_fail參數(shù)的核心取值來(lái)源。官方文檔給出了 8 個(gè)成員成員字面量語(yǔ)義REASKreask失敗時(shí)讓 LLM 重新生成該字段FIXfix失敗時(shí)應(yīng)用靜態(tài)修復(fù)值FILTERfilter失敗時(shí)過濾掉無(wú)效值REFRAINrefrain失敗時(shí)拒絕作答返回空值NOOPnoop失敗時(shí)不采取任何動(dòng)作EXCEPTIONexception失敗時(shí)拋出ValidationErrorFIX_REASKfix_reask先應(yīng)用靜態(tài)修復(fù)若修復(fù)后的值仍未通過校驗(yàn)再 reask LLMCUSTOMcustom失敗時(shí)調(diào)用自定義函數(shù)入?yún)闊o(wú)效值和校驗(yàn)器產(chǎn)生的FailResult對(duì)應(yīng)源碼見 guardrails/types/on_fail.py。寬松解析OnFailAction.get()該枚舉額外提供了一個(gè)靜態(tài)方法OnFailAction.get(key, default)guardrails/types/on_fail.py傳入字符串時(shí)按成員名大寫匹配如exception、EXCEPTION均可解析到OnFailAction.EXCEPTION傳入枚舉實(shí)例則原樣返回解析失敗時(shí)返回默認(rèn)值。這使得 RAIL 文件、命令行或用戶輸入中的大小寫差異都能被容錯(cuò)處理。默認(rèn)值與 CUSTOM 分支的判定邏輯在 guardrails/validator_base.py 中Validator.__init__對(duì)on_fail參數(shù)做了三路判定on_fail is None時(shí)默認(rèn)取OnFailAction.EXCEPTION傳入枚舉實(shí)例或能匹配到枚舉成員名的字符串時(shí)設(shè)置on_fail_descriptor且on_fail_method為None其余情況一律視為可調(diào)用對(duì)象將on_fail_descriptor置為OnFailAction.CUSTOM并通過_set_on_fail_method檢查自定義函數(shù)簽名——該函數(shù)必須接收兩個(gè)參數(shù)被校驗(yàn)的值與FailResultguardrails/validator_base.py。因此CUSTOM不是簡(jiǎn)單的枚舉字符串而是函數(shù)式失敗處理的統(tǒng)一入口只要on_fail傳的不是枚舉/可識(shí)別字符串Guardrails 就會(huì)把它當(dāng)成自定義處理函數(shù)來(lái)用。核心分派perform_correction()OnFailAction的語(yǔ)義最終在 guardrails/validator_service/validator_service_base.py 的perform_correction方法中落地。該方法是校驗(yàn)服務(wù)的核心分派點(diǎn)逐分支實(shí)現(xiàn)每種行為FIX直接返回result.fix_value校驗(yàn)器產(chǎn)出的修復(fù)值FIX_REASK若修復(fù)后的值經(jīng)復(fù)查仍是FailResult則包裝成FieldReAsk(incorrectValuefixed_value, failResults[result])交由后續(xù) reask 流程處理CUSTOM調(diào)用validator.on_fail_method(value, result)若未設(shè)置on_fail_method則拋出ValueErrorREASK包裝FieldReAsk(incorrectValuevalue, failResults[result])EXCEPTION拋出ValidationError錯(cuò)誤信息匯總所有FailResult的error_messageFILTER返回Filter()哨兵對(duì)象由 guardrails/actions/filter.py 的apply_filters在后續(xù)處理中遞歸地從列表/字典中剔除這些值REFRAIN返回Refrain()哨兵對(duì)象由 guardrails/actions/refrain.py 的check_for_refrain/apply_refrain遞歸檢測(cè)并替換為空值NOOP原樣返回傳入值不做任何處理。reask 相關(guān)的完整流程如get_reask_setup、gather_reasks、merge_reask_output集中在 guardrails/actions/reask.py可按需深入閱讀。在測(cè)試中的典型用法集成測(cè)試展示了on_fail各取值的真實(shí)用法例如 tests/integration_tests/schema/test_pydantic_schema.py 中組合使用OnFailAction.REASK、OnFailAction.EXCEPTION、OnFailAction.FILTERtests/integration_tests/test_assets/entity_extraction/pydantic_models.py 則按場(chǎng)景分別使用FILTER、FIX、NOOP三種策略來(lái)構(gòu)造不同的校驗(yàn)鏈路。RailTypesRAIL XML 的內(nèi)置標(biāo)簽枚舉RailTypes同樣繼承自(str, Enum)代表 RAIL XML 規(guī)范中的內(nèi)置標(biāo)簽共有 13 個(gè)成員成員字面量含義STRINGstring字符串值INTEGERinteger整數(shù)值FLOATfloat浮點(diǎn)值BOOLbool布爾值DATEdate日期值TIMEtime時(shí)間值DATETIMEdate-time日期時(shí)間值PERCENTAGEpercentage以字符串表示的百分比如20.5%ENUMenum枚舉值LISTlist列表/數(shù)組值OBJECTobject對(duì)象/字典值CHOICEchoice判別聯(lián)合discriminated union的選項(xiàng)容器CASEcase包含判別聯(lián)合的字典對(duì)應(yīng)源碼見 guardrails/types/rail.py。注意DATETIME的字面量是帶連字符的date-time文檔原文中該條存在筆誤源碼以RailTypes.DATETIME date-time為準(zhǔn)。RailTypes.get(key)是一個(gè)寬松的類方法guardrails/types/rail.py用字符串直接構(gòu)造枚舉成員匹配不到時(shí)返回None而不是拋異常方便在 schema 解析過程中安全探測(cè)標(biāo)簽類型。RAIL 標(biāo)簽到 JSON Schema 的映射RailTypes的核心作用體現(xiàn)在 guardrails/schema/rail_schema.py 的schema_to_json_schema函數(shù)中。該函數(shù)讀取 RAIL 元素的type屬性output元素缺省時(shí)默認(rèn)RailTypes.OBJECT然后按類型分派STRING、INTEGER、FLOAT、BOOL直接映射為 JSON Schema 的string/integer/number/boolean類型其中FLOAT還透?jìng)鱢ormat屬性缺省為floatDATE、TIME、DATETIME、PERCENTAGE映射為 JSON Schema 的string類型并通過extract_format合并自定義格式與內(nèi)部格式屬性如date-format、time-format、datetime-format例如 RAIL 中date formatfoo date-format%Y-%M-%D /會(huì)生成{type: string, format: date: %Y-%M-%D; foo}ENUM讀取values逗號(hào)分隔屬性生成枚舉取值列表LIST、OBJECT、CHOICE、CASE則進(jìn)入遞歸的嵌套結(jié)構(gòu)構(gòu)建邏輯。此外 guardrails/datatypes.py 維護(hù)了一個(gè)types_registry列表將SimpleTypes與RailTypes的全部字面量合并作為全局可識(shí)別的類型名注冊(cè)表。Pydantic 模型相關(guān)的類型別名guardrails/types/pydantic.py 定義了三個(gè)圍繞pydantic.BaseModel的類型別名用于標(biāo)注輸出 schema 可以是哪些形態(tài)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單個(gè) Pydantic 模型或模型列表的類型構(gòu)造。這是Guard.for_pydantic的output_class參數(shù)簽名guardrails/guard.py意味著你可以傳入一個(gè)模型類也可以傳入List[SomeModel]這種類型表達(dá)式來(lái)描述根級(jí)數(shù)組輸出ModelOrListOrDict在ModelOrListOfModels基礎(chǔ)上再允許鍵為字符串、值為模型類的字典類型構(gòu)造覆蓋對(duì)象/數(shù)組/映射三種根結(jié)構(gòu)ModelOrModelUnion寬松的聯(lián)合類型用于標(biāo)注模型或模型與任意類型的聯(lián)合。在 guardrails/guard.py 中Guard.for_pydantic通過pydantic_model_to_schema(output_class)將傳入的模型或列表/字典類型轉(zhuǎn)換為ProcessedSchema含json_schema、validators、validator_map再據(jù)此構(gòu)建 Guard 實(shí)例。校驗(yàn)器規(guī)格的類型別名guardrails/types/validator.py 定義了與如何指定校驗(yàn)器相關(guān)的六個(gè)類型別名是Guard.for_pydantic字段校驗(yàn)器、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]]各類型的語(yǔ)義與消費(fèi)方PydanticValidatorTuple二元組(校驗(yàn)器, on_fail 字符串)。第一元素可以是Validator實(shí)例、注冊(cè)名字符串或可調(diào)用對(duì)象第二元素是失敗動(dòng)作。它被parse_pydantic_validatorguardrails/utils/validator_utils.py消費(fèi)若第一元素已是Validator實(shí)例則直接設(shè)置其on_fail_descriptor若是字符串則走parse_rail_validator按注冊(cè)名解析失敗動(dòng)作缺省為OnFailAction.NOOPUseValidatorSpecGuard.use接受的單校驗(yàn)器規(guī)格可以是實(shí)例或未實(shí)例化的類UseManyValidatorTuple三元組(校驗(yàn)器類, 位置參數(shù)列表/字典, 關(guān)鍵字參數(shù)字典)由parse_use_many_validatorguardrails/utils/validator_utils.py實(shí)例化若第二元素是字典則整體作為 kwargs否則作為位置參數(shù)列表ValidatorMap鍵為 JSON path如$、$.field、$.items.*值為該路徑上掛載的校驗(yàn)器列表。它被ProcessedSchema.validator_mapguardrails/classes/schema/processed_schema.py和Guard._validator_mapguardrails/guard.py共同使用是按輸出路徑組織校驗(yàn)器的核心數(shù)據(jù)結(jié)構(gòu)。get_validator 的統(tǒng)一解析入口上述 tuple 形態(tài)在 guardrails/utils/validator_utils.py 的get_validator中被統(tǒng)一分派Validator實(shí)例直接返回Type[Validator]子類實(shí)例化并帶有棄用警告官方建議直接傳實(shí)例化好的校驗(yàn)器元組若首元素是Validator子類走parse_use_many_validator否則走parse_pydantic_validator字符串視為 RAIL 校驗(yàn)器規(guī)格經(jīng)parse_rail_validator解析支持validator_id: arg1 arg2形式參數(shù)解析見 guardrails/utils/validator_utils.py。RAIL 中的 on-fail 屬性與 ValidatorMap 填充在 RAIL 場(chǎng)景下guardrails/schema/rail_schema.py 的parse_on_fail_handlers會(huì)掃描元素上所有on-fail-*屬性如on-fail-valid-choicesreask用OnFailAction(value)構(gòu)造失敗動(dòng)作get_validators則解析validators屬性中的分號(hào)分隔規(guī)格將解析結(jié)果寫入ValidatorMap。隨后extract_validatorsguardrails/schema/rail_schema.py為每個(gè)校驗(yàn)器生成ValidatorReference并按 JSON path 掛載到validator_map最終在Guard._for_rail_schemaguardrails/guard.py中被整體灌入 Guard 實(shí)例。Guard.use 的 on 參數(shù)Guard.useguardrails/guard.py接受Validator實(shí)例列表與on參數(shù)on的合法取值包括output、messages或$.開頭的 JSON path內(nèi)部將output歸一化為$非典型取值會(huì)觸發(fā)UserWarningguardrails/guard.py。MessageHistory帶模板的消息歷史MessageHistory定義在 guardrails/types/inputs.py其形態(tài)為MessageHistory List[Dict[str, Union[Prompt, str]]]即消息字典列表每條消息的content字段可以是Prompt對(duì)象或普通字符串。它貫穿 LLM 調(diào)用前的消息準(zhǔn)備流程在 guardrails/run/runner.py 的prepare_messages中每條消息會(huì)被深拷貝首輪attempt_number 0用prompt_params對(duì)content做模板格式化content.format(**prompt_params)若校驗(yàn)器映射中包含messages鍵還會(huì)觸發(fā)消息級(jí)校驗(yàn)validate_messages。Prompt類本身支持基于string.Template的安全格式化見 guardrails/prompt/prompt.py。實(shí)戰(zhàn)示例類型體系的綜合運(yùn)用下面用一個(gè) 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 形態(tài)單模型或 List[Person] 均可作為 output_class guard Guard.for_pydantic(output_classPerson) # Guard.use 接受 Validator 實(shí)例on 支持 $. JSON path guard.use( ValidLength(min1, max120, on_failOnFailAction.NOOP), on$.name, )若改用 RAIL 定義則可用on-fail-*屬性把失敗行為直接寫進(jìn) XML例如output string namename validatorstwo-words on-fail-two-wordsfix / integer nameage formatvalid-choices: 0..122 on-fail-valid-choicesreask / /output解析后每個(gè) JSON path 上的校驗(yàn)器及其OnFailAction會(huì)被填充進(jìn)ValidatorMap運(yùn)行時(shí)由ValidatorServiceBase.perform_correction按上文的分派邏輯逐一執(zhí)行。小結(jié)Guardrails 的類型體系是理解整個(gè)校驗(yàn)管線的鑰匙OnFailAction定義失敗后做什么并在ValidatorServiceBase.perform_correction中落地為八種可執(zhí)行策略其中CUSTOM允許注入用戶自定義函數(shù)RailTypes定義 RAIL XML 的標(biāo)簽詞表并在rail_schema.py中逐類映射為 JSON Schema各 Pydantic/校驗(yàn)器類型別名ModelOrListOfModels、PydanticValidatorSpec、UseManyValidatorTuple、ValidatorMap等精確約束了Guard.for_pydantic、Guard.use等公共 API 的入?yún)⑿螒B(tài)其解析邏輯統(tǒng)一收斂于 guardrails/utils/validator_utils.py 的get_validator。掌握這些類型定義與背后的解析/分派鏈路你就能在寫 Guardrails 配置時(shí)做到類型即文檔知道每個(gè)參數(shù)該傳什么形態(tài)、每種失敗行為會(huì)觸發(fā)怎樣的下游處理從而更精準(zhǔn)地設(shè)計(jì) LLM 輸出的校驗(yàn)與糾錯(cuò)策略。如需進(jìn)一步研究可繼續(xù)閱讀 actions.md失敗動(dòng)作細(xì)節(jié)、validator.md校驗(yàn)器接口與 rail.mdRAIL 規(guī)范。贊分享AI 安全治理模型安全AI 應(yīng)用【免費(fèi)下載鏈接】guardrailsAdding guardrails to large language models.項(xiàng)目地址https://gitcode.com/gh_mirrors/gu/guardrails點(diǎn)擊查看免費(fèi)下載相關(guān)推薦gbrain 類型分類法type-taxonomy深度解析14 類規(guī)范類型體系與 unify-types 遷移實(shí)戰(zhàn)gbrain 類型分類法type taxonomy深度解析14 類規(guī)范類型體系與 unify types 遷移實(shí)戰(zhàn) gbrain 的類型系統(tǒng) pages人工智能RAGAgent 記憶MCP 服務(wù)知識(shí)管理Medusa HTTP 類型生成器實(shí)戰(zhàn)指南從 Zod 校驗(yàn) Schema 自動(dòng)生成與校驗(yàn) TypeScript 類型Medusa HTTP 類型生成器實(shí)戰(zhàn)指南從 Zod 校驗(yàn) Schema 自動(dòng)生成與校驗(yàn) TypeScript 類型 導(dǎo)讀 本指南圍繞 Medusa 開源倉(cāng)庫(kù)后端電商前端Backstage catalog-model 包演進(jìn)全解析實(shí)體模型、校驗(yàn)體系與 AI 資源類型Backstage catalog model 包演進(jìn)全解析實(shí)體模型、校驗(yàn)體系與 AI 資源類型 backstage/catalog model 是 Bac開發(fā)者門戶后端前端上一篇如何將PWABuilder pwa-starter應(yīng)用打包到各大應(yīng)用商店完整上架攻略下一篇5大智能功能全面解鎖Chartero插件讓你的文獻(xiàn)管理效率翻倍創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考